瀑布流插件Masonry中文文档

• 时间：2018-11-01 23:17 作者：免费开源 来源：免费开源 阅读：1529
• 扫一扫，手机访问

bower install masonry --save

npm install masonry-layout

 
...

 
...

 
...

 ...

.grid-item { width: 200px; }
.grid-item--width2 { width: 400px; }

$('.grid').masonry({
 // options
 itemSelector: '.grid-item',
 columnWidth: 200
});

var elem = document.querySelector('.grid');
var msnry = new Masonry( elem, {
 // options
 itemSelector: '.grid-item',
 columnWidth: 200
});
// element argument can be a selector string
// for an individual element
var msnry = new Masonry( '.grid', {
 // options
});

 data-masonry-options='{ "itemSelector": ".grid-item", "columnWidth": 200 }'>

div class="grid">
 

 

 

 ...

 
 

 

 

 ...

/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
/* 2 columns */
.grid-item--width2 { width: 40%; }
$('.grid').masonry({
 // set itemSelector so .grid-sizer is not used in layout
 itemSelector: '.grid-item',
 // use element for option
 columnWidth: '.grid-sizer',
 percentPosition: true
})

// init Masonry
var $grid = $('.grid').masonry({
 // options...
});
// layout Masonry after each image loads
$grid.imagesLoaded().progress( function() {
 $grid.masonry('layout');
});

var $grid = $('.grid').imagesLoaded( function() {
 // init Masonry after all images have loaded
 $grid.masonry({
 // options...
 });
});

// jQuery
$('.grid').masonry({
 columnWidth: 200,
 itemSelector: '.grid-item'
});
// vanilla JS （原生JS）
var msnry = new Masonry( '.grid', {
 columnWidth: 200,
 itemSelector: '.grid-item'
});

itemSelector: '.grid-item'

 
  
Static banner

 

 

 ...

columnWidth: 80

div class="grid">
 
 

 

 

 ...

布局Layout

组件尺寸Element sizing

尺寸配置项columnWidth和gutter可以可以设置组件的列宽和间距。

 
 

 

 

 ...

/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
/* 2 columns wide */
.grid-item--width2 { width: 40%; }
// use outer width of grid-sizer for columnWidth
columnWidth: '.grid-sizer',
// do not use .grid-sizer in layout
itemSelector: '.grid-item',
percentPosition: true

该配置项可以设置为一个选择器的字符串或者一个元素

// set to a selector string
// first matching element within container element will be used
columnWidth: '.grid-sizer'
// set to an element
columnWidth: $grid.find('.grid-sizer')[0]

组件尺寸允许你使用CSS控制Masonry的布局。这在响应式布局和媒体查询中非常有用。

/* 3 columns by default */
.grid-sizer { width: 33.333%; }
@media screen and (min-width: 768px) {
 /* 5 columns for larger screens */
 .grid-sizer { width: 20%; }
}

Gutter（间距）

gutter: 10

在js配置项gutter可以设置组件的横向间距，使用CSS margin能设置组件的纵向间距。

gutter: 10

css:

.grid-item {
 margin-bottom: 10px;
}

在响应式布局中使用组件尺寸将宽度设置为百分比时，可以将gutter的值设置为选择器字符串或者者一个元素。

 

 

 

 

 ...

.grid-sizer,
.grid-item { width: 22%; }
.gutter-sizer { width: 4%; }
.grid-item--width2 { width: 48%; }
columnWidth: '.grid-sizer',
gutter: '.gutter-sizer',
itemSelector: '.grid-item',
percentPosition: true

horizontalOrder

使组件按照从左到右排列。（比照组件们在第二排的排列）

horizontalOrder: true

percentPosition

设置组件的位置（尺寸）为百分比而非像素数。percentPosition: true可以使宽度为百分比的组件不改变他们本来的位置。

// set positions with percent values
percentPosition: true,
columnWidth: '.grid-sizer',
itemSelector: '.grid-item'
/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }

Stamp

指定组件为stamp。Masonry在布局时会避开这些组件。

配置项stamp只在Masonry实例第一次初始化完成后黏贴指定组件，但你可以通过stamp method更改后续的stamp布局。

 

 

 

 

 ....

// specify itemSelector so stamps do get laid out
itemSelector: '.grid-item',
// stamp elements
stamp: '.stamp'
/* position stamp elements with CSS */
.stamp {
 position: absolute;
 background: orange;
 border: 4px dotted black;
}
.stamp1 {
 left: 30%;
 top: 10px;
 width: 20%;
 height: 100px;
}
.stamp2 {
 right: 10%;
 top: 20px;
 width: 70%;
 height: 30px;
}

fitWidth

根据父级容器的尺寸，设置容器的宽，以适应可用的列数。启用之后将容器grid居中

fitWidth: true
/* center container with CSS */
.grid {
 margin: 0 auto;
}

originLeft

控制水平布局，默认状态下originLeft: true控件从左到右布局，设置originLeft: false后，控件从右向左布局。

originLeftMasonry v3使用isOriginLeft，在Masonry v4之后isOriginLeft也是被兼容的。

originLeft: false

originTop

相似originLeft，开启originTop: false后，自下而上布局

设置（Setup）

containerStyle

设置父级容器grid的css样式。默认状态下为position:’relative’，禁用grid容器的所有样式：containerStyle:null

// default
// containerStyle: { position: 'relative' }
// disable any styles being set on container
// useful if using absolute position on container
containerStyle: null

transitionDuration

控件改变位置或者重排的缓动时间。默认为0.4s

// fast transitions
transitionDuration: '0.2s'
// slow transitions
transitionDuration: '0.8s'
// no transitions
transitionDuration: 0

stagger

控件重排的时间。当一个控件改变了位置，其余控件逐次的改变位置进行重排，stagger属性即为每个控件发生重排的缓动时间。，默认为值30（毫秒）

stagger: 30

resize

当窗口大小改变时控件重排以适应父级容器大小。默认为允许重排resize: true，在v3版本中使用isResizeBound，并在v4版本下兼容。

// disable window resize behavior
resize: false
/* grid has fixed width */
.grid {
 width: 320px;
}

initLayout

允许初始化布局，默认开启。

设置为initLayout: false，可以禁止初始化布局，你可以通过methods或者者添加event事件的方法开启布局。V3版本使用isInitLayout。

var $grid = $('.grid').masonry({
 // disable initial layout
 initLayout: false,
 //...
});
// bind event
$grid.masonry( 'on', 'layoutComplete', function() {
 console.log('layout is complete');
});
// trigger initial layout
$grid.masonry();

方法（Methods）

Methods是Masonry实例的行为

使用jQuery时，methods遵从jQuery格式.masonry( 'methodName' /* arguments */ )

$grid.masonry()
 .append( elem )
 .masonry( 'appended', elem )
 // layout
 .masonry();

原生JS的method使用相似：masonry.methodName( /* arguments */ )，与jQuery不同，原生JS不能使用链（chaining）.

// vanilla JS
var msnry = new Masonry( '.grid', {...});
gridElement.appendChild( elem );
msnry.appended( elem );
msnry.layout();

布局（Layout）

layout / .masonry()

将所有组件布局。layout用于当一个组件改变了尺寸后所有的控件需要重新布局。

// jQuery
$grid.masonry()
// vanilla JS
msnry.layout()
var $grid = $('.grid').masonry({
 columnWidth: 80
});
// change size of item by toggling gigante class
$grid.on( 'click', '.grid-item', function() {
 $(this).toggleClass('gigante');
 // trigger layout after item size changes
 $grid.masonry('layout');
});

layoutItems

布局指定控件

// jQuery
$grid.masonry( 'layoutItems', items, isStill )
// vanilla JS
msnry.layoutItems( items, isStill )

items Masonry控件的数组

isStill布尔型，禁止变换

stamp

在排列中黏贴指定控件，Masonry会围绕被黏贴的元素进行排列

// jQuery
$grid.masonry( 'stamp', elements )
// vanilla JS
msnry.stamp( elements )

elements element,jQuery对象，节点，或者数组

设置不参加瀑布流布局的对象，以选择器形式给出。

var $grid = $('.grid').masonry({
 // specify itemSelector so stamps do get laid out
 itemSelector: '.grid-item',
 columnWidth: 80
});
var $stamp = $grid.find('.stamp');
var isStamped = false;
$('.stamp-button').on( 'click', function() {
 // stamp or unstamp element
 if ( isStamped ) {
 $grid.masonry( 'unstamp', $stamp );
 } else {
 $grid.masonry( 'stamp', $stamp );
 }
 // trigger layout
 $grid.masonry('layout');
 // set flag
 isStamped = !isStamped;
});

unstamp

解除指定元素的stamp 状态。

添加&移除控件

Appended

在瀑布流末尾添加新控件并重排。

// jQuery
$grid.masonry( 'appended', elements )
// vanilla JS
msnry.appended( elements )

elements element,jQuery对象，节点，或者数组

$('.append-button').on( 'click', function() {
 // create new item elements
 var $items = $('
...
');
 // append items to grid
 $grid.append( $items )
 // add and lay out newly appended items
 .masonry( 'appended', $items );
});

*（注意链chaining的使用，此处为先添加节点，再讲节点重排）

jQuery可以使用，添加字符串结构的HTML节点，但是masonry不行，所以当时用jQuery ajax动态加载节点时要将HTML节点转化成jQuery对象。

// does not work
$.get( 'page2', function( content ) {
 // HTML string added, but items not added to Masonry
 $grid.append( content ).masonry( 'appended', content );
});
// does work
$.get( 'page2', function( content ) {
 // wrap content in jQuery object
 var $content = $( content );
 // add jQuery object
 $grid.append( $content ).masonry( 'appended', $content );
});

prepended

相似append，在顶部添加新节点并重排。

addItems

项Masonry实例中添加控件元素，addItems不能像append和prepended重排新添加加的元素

// jQuery
$grid.masonry( 'addItems', elements )
// vanilla JS
msnry.addItems( elements )

remove

从Masonry实例和DOM中移除元素

// jQuery
$grid.masonry( 'remove', elements )
// vanilla JS
msnry.remove( elements )
$grid.on( 'click', '.grid-item', function() {
 // remove clicked element
 $grid.masonry( 'remove', this )
 // layout remaining item elements
 .masonry('layout');
});

事件（Events）

on

添加一个Masonry事件监听。

// jQuery
var msnry = $grid.masonry( 'on', eventName, listener )
// vanilla JS
msnry.on( eventName, listener )

eventName 字符串，Masonry事件名称

listener 方法

off

移除Masonry事件

// jQuery
var msnry = $grid.masonry( 'off', eventName, listener )
// vanilla JS
msnry.off( eventName, listener )

eventName 字符串，Masonry事件名称

listener 方法

once

添加一个Masonry事件，只触发一次。

// jQuery
var msnry = $grid.masonry( 'once', eventName, listener )
// vanilla JS
msnry.once( eventName, listener )

eventName 字符串，Masonry事件名称

listener 方法

$grid.masonry( 'once', 'layoutComplete', function() {
 console.log('layout is complete, just once');
})

Utilities

reloadItems

Recollects all item elements.

For frameworks like Angular and React, reloadItems may be useful to apply changes to the DOM to Masonry.

// jQuery
$grid.masonry('reloadItems')
// vanilla JS
msnry.reloadItems()

destroy

移除所有的Masonry功能，destroy将恢复元素预加载之前的状态。

// jQuery
$grid.masonry('destroy')
// vanilla JS
msnry.destroy()
var masonryOptions = {
 itemSelector: '.grid-item',
 columnWidth: 80
};
// initialize Masonry
var $grid = $('.grid').masonry( masonryOptions );
var isActive = true;
$('.toggle-button').on( 'click', function() {
 if ( isActive ) {
 $grid.masonry('destroy'); // destroy
 } else {
 $grid.masonry( masonryOptions ); // re-initialize
 }
 // set flag
 isActive = !isActive;
});

getItemElements

返回一个组件元素的数组

// jQuery
var elems = $grid.masonry('getItemElements')
// vanilla JS
var elems = msnry.getItemElements()

elems 数组

jQuery.fn.data('masonry')

从jQuery对象中取出Masonry实例，以便读取Masonry的属性。

var msnry = $('.grid').data('masonry')
// access Masonry properties
console.log( msnry.items.length + ' filtered items' )

Masonry.data

通过元素取出Masonry实例，Masonry.data()用于从HTML初始化的Masonry实例中取出Masonry属性。

var msnry = Masonry.data( element )

element 控件或者选择器的字符串

msnry Masonry

...

// jQuery
// pass in the element, $element[0], not the jQuery object
var msnry = Masonry.data( $('.grid')[0] )
// vanilla JS
// using an element
var grid = document.querySelector('.grid')
var msnry = Masonry.data( grid )
// using a selector string
var msnry = Masonry.data('.grid')

事件

事件绑定（event binding）

jQuery事件绑定

使用jQuery标准的事件方法绑定，如.on()，.off()和.one()。

// jQuery
var $grid = $('.grid').masonry({...});
function onLayout() {
 console.log('layout done');
}
// bind event listener
$grid.on( 'layoutComplete', onLayout );
// un-bind event listener
$grid.off( 'layoutComplete', onLayout );
// bind event listener to be triggered just once. note ONE not ON
$grid.one( 'layoutComplete', function() {
 console.log('layout done, just this one time');
});

jQuery事件监听器需要一个eventargument参数，原生的JS不需要。

// jQuery, has event argument
$grid.on( 'layoutComplete', function( event, items ) {
 console.log( items.length );
});
// vanilla JS, no event argument
msnry.on( 'layoutComplete', function( items ) {
 console.log( items.length );
});

原生JS事件绑定

使用原生JS方法绑定。on()，.off()，.once()。

// vanilla JS
var msnry = new Masonry( '.grid', {...});
function onLayout() {
 console.log('layout done');
}
// bind event listener
msnry.on( 'layoutComplete', onLayout );
// un-bind event listener
msnry.off( 'layoutComplete', onLayout );
// bind event listener to be triggered just once
msnry.once( 'layoutComplete', function() {
 console.log('layout done, just this one time');
});

Masonry 事件

layoutComplete

在布局和所有位置变化完成后触发。

// jQuery
$grid.on( 'layoutComplete', function( event, laidOutItems ) {...} )
// vanilla JS
msnry.on( 'layoutComplete', function( laidOutItems ) {...} )

laidOutItems Masonry控件数组，已完成排列的控件

$grid.on( 'layoutComplete',
 function( event, laidOutItems ) {
 console.log( 'Masonry layout completed on ' +
 laidOutItems.length + ' items' );
 }
);

removeComplete

元素移除后触发

// jQuery
$grid.on( 'removeComplete', function( event, removedItems ) {...} )
// vanilla JS
msnry.on( 'removeComplete', function( removedItems ) {...} )

removedItemsMasonry控件数组，被移除的控件

$grid.on( 'removeComplete',
 function( event, removedItems ) {
 notify( 'Removed ' + removedItems.length + ' items' );
 }
);