瀑布流插件Masonry中文文檔【翻譯】

時間 2019-11-08

標籤瀑布插件 masonry 中文文檔翻譯欄目悠閒生活简体版

原文原文鏈接

本位爲Masonry官方文檔翻譯，原始連接javascript

安裝Install

下載

下載壓縮或未壓縮的masonrycss

masonry.pkgd.min.js （壓縮）
masonry.pkgd.js （未壓縮）

CDN

在unpkg直接飲用Masonry文件。html

<script src="https://unpkg.com/masonry-layout@4/dist/masonry.pkgd.min.js"></script>
<!-- or -->
<script src="https://unpkg.com/masonry-layout@4/dist/masonry.pkgd.js"></script>

包管理

使用Bower安裝java

bower install masonry --save

使用npm安裝ajax

npm install masonry-layout

入門Getting started

HTML

在你的項目中引入Masonry.jsnpm

<script src="/path/to/masonry.pkgd.min.js"></script>

Masonry的運行須要一個包含一些列子組件的grid容器標籤數組

<div class="grid">
  <div class="grid-item">...</div>
  <div class="grid-item grid-item--width2">...</div>
  <div class="grid-item">...</div>
  ...
</div>

CSS

你能夠經過CSS控制全部組件的尺寸app

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

經過jQuery初始化

你能夠將Masonry做爲一個jQuery插件來使用$('selector').masonry()ide

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

經過原生JavaScript初始化

你能夠經過原生JS使用Masonry：new Masonry( elem, options )。構造函數Masonry()接收兩個參數：容器標籤和配置對象。函數

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
});

在HTML中初始化

你也能夠在HTML中初始化Masonry，這樣不須要書寫任何JavaScript。在容器標籤中增長data-masonry屬性，其值則是Masonry組件的配置

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

注意：在HTML中必須以JSON格式配置，key必須帶引號，例如："itemSelector":。 data-masonry的值使用單引號，JSON使用雙引號。
在Masonry v3版本，HTML初始化須要使用特定的class： js-masonry ，設置配置須要屬性data-masonry-options，在Masonry v4以後版本中，這種寫法也是兼容的。

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

佈局Layout

組件尺寸

你能夠經過CSS控制組件的尺寸

div class="grid">
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  <div class="grid-item grid-item--height2"></div>
  ...
</div>

.grid-item {
  float: left;
  width: 80px;
  height: 60px;
  border: 2px solid hsla(0, 0%, 0%, 0.5);
}

.grid-item--width2 { width: 160px; }
.grid-item--height2 { height: 140px; }

響應式佈局

組件的尺寸可設置成百分比從而適應響應式的佈局，在設置masonry佈局模式時，將columnWidth設置爲指定組件的尺寸，設置percentPosition: true 。組件的位置將再也不改變，window改變大小事，組件將以百分比的形式響應式佈局。

<div class="grid">
  <!-- width of .grid-sizer used for columnWidth -->
  <div class="grid-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

/* 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
})

imagesLoaded

Masonry排列未加載完成的圖片時會致使元素的重疊，imagesLoaded能夠解決這個問題。imagesLoaded是一個獨立的腳本插件，你能夠在imagesloaded.desandro.com下載。
初始化Masonry，在每一張圖片加載完成後觸發佈局。

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

或者在全部圖片都加載完成後初始化Masonry

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

配置項Options

除了columnWidth和itemSelector之外，全部的配置項都是能夠選擇的。

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

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

<!-- in HTML -->
<div class="grid" data-masonry='{ "columnWidth": 200, "itemSelector": ".grid-item" }'>

必選配置項Recommended

itemSelector
用於指定參與佈局的子組件。
咱們建議始終設置項，用於區分參組件元素是否參與佈局。

itemSelector: '.grid-item'

<div class="grid">
  <!-- do not use banner in Masonry layout -->
  <!—在Masonry佈局時忽略 banner
  <div class="static-banner">Static banner</div>
  <div class="grid-item"></div>
  <div class="grid-item"></div>
  ...
</div>

columnWidth
用於在水平網格上對齊組件

咱們建議設置columnWidth，若是沒有設置columnWidth，Masonry將使用第一個組件的外寬做爲默認值。

columnWidth: 80

使用組件尺寸，在響應式佈局中獎組件的寬度設置成百分比，設置columnWidth時，將值設置爲指定組件選擇器的字符串，即便用該組件的外寬。

div class="grid">
  <!-- .grid-sizer empty element, only used for element sizing -->
  <div class="grid-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

/* 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',
itemSelector: '.grid-item',
percentPosition: true

佈局Layout

組件尺寸Element sizing
尺寸配置項columnWidth和gutter能夠能夠設置組件的列寬和間距。

<div class="grid">
  <!-- .grid-sizer empty element, only used for element sizing -->
  <div class="grid-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

/* 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的值設置爲選擇器字符串或者一個元素。

<div class="grid">
  <div class="grid-sizer"></div>
  <div class="gutter-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

.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佈局。

<div class="grid">
  <div class="stamp stamp1"></div>
  <div class="stamp stamp2"></div>
  <div class="grid-item"></div>
  <div class="grid-item"></div>
  ....
</div>

// 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 = $('<div class="grid-item">...</div>');
  // 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

<!-- init Masonry in HTML -->
<div class="grid" data-masonry='{...}'>...</div>

// 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' );
  }
);

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。