瀑布流插件Masonry中文文档【翻译】

soasme 发布于2019-08-22 15:18 / 2224人阅读

摘要：本位为官方文档翻译，原始链接安装下载下载压缩或未压缩的压缩未压缩在直接饮用文件。排列未加载完成的图片时会导致元素的重叠，可以解决这个问题。布局组件尺寸尺寸配置项和可以可以设置组件的列宽和间距。增加移除控件在瀑布流末尾增加新控件并重排。

本位为Masonry官方文档翻译，原始链接

安装Install 下载

下载压缩或未压缩的masonry

masonry.pkgd.min.js （压缩）

masonry.pkgd.js （未压缩）

CDN

在unpkg直接饮用Masonry文件。

包管理

使用Bower安装

bower install masonry --save

使用npm安装

npm install masonry-layout

入门Getting started HTML

在你的项目中引入Masonry.js

Masonry的运行需要一个包含一些列子组件的grid容器标签


  ...
  ...
  ...
  ...

CSS

你可以通过CSS控制所有组件的尺寸

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

通过jQuery初始化

你可以将Masonry作为一个jQuery插件来使用$("selector").masonry()

$(".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组件的配置

注意：在HTML中必须以JSON格式配置，key必须带引号，例如："itemSelector":。 data-masonry的值使用单引号，JSON使用双引号。
在Masonry v3版本，HTML初始化需要使用特定的class： js-masonry ，设置配置需要属性data-masonry-options，在Masonry v4之后版本中，这种写法也是兼容的。

布局Layout 组件尺寸

你可以通过CSS控制组件的尺寸

div class="grid">
  
  
  
  ...

.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改变大小事，组件将以百分比的形式响应式布局。

...

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

必选配置项Recommended

itemSelector
用于指定参与布局的子组件。
我们建议始终设置项，用于区分参组件元素是否参与布局。

itemSelector: ".grid-item"


  
  Static banner
  
  
  ...

columnWidth
用于在水平网格上对齐组件

我们建议设置columnWidth，如果没有设置columnWidth，Masonry将使用第一个组件的外宽作为默认值。

columnWidth: 80

使用组件尺寸，在响应式布局中奖组件的宽度设置成百分比，设置columnWidth时，将值设置为指定组件选择器的字符串，即使用该组件的外宽。

div class="grid">
  
  
  
  
  ...

/* 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可以可以设置组件的列宽和间距。

...

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

混合云私有云瀑布流瀑布流方式 gridview瀑布流 jquery瀑布流

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/93359.html

瀑布流插件Masonry的配置和使用

摘要：是最流行的瀑布流插件之一，配置简单，功能强大，在上收获了。如果你想使用瀑布流提升网站体验，将是不错的选择。瀑布流，又称瀑布流式布局。需要注意的是，如果你需要加载图片，不会在图片加载完后重新布局，这可能会影响你的布局效果，建议配合使用插件。 Masonry是最流行的瀑布流插件之一，配置简单，功能强大，在Github上收获了1w+ stars。如果你想使用瀑布流提升网站体验，Masonry...

waterc 2019-08-22 10:42 评论0 收藏0
推荐JS插件：imagesLoaded，监测图片加载情况并提供相应的事件（加载成功/失败）

摘要：为了保证在拿到图片高度，也即图片加载完成后再进行排列，我根据的推荐，选用了这一款插件。另外，在做一些图片加载效果的时候也可以用到，比如说图片未加载完成之前放个图，加载失败时放个错误提示什么的都很方便呢。惯例，首先贴上imagesLoaded的官方网址：http://imagesloaded.desandro.com/ 第一次知道imagesLoaded这个插件是在做瀑布流布局时，当时...

atinosun 2019-08-22 10:59 评论0 收藏0
avalon与masonry的结合

摘要：相关组件版本最近，在公司的项目中，要开发一个使用瀑布流的前台，衡量了各种解决方案后，还是觉得最成熟，所以就选用了它。测试的结果很令人沮丧，依然没有控制节点的位置，所以应该不是这个问题。相关组件版本：avalon 1.3.6、masonry 3.1.5 最近，在公司的项目中，要开发一个使用瀑布流的前台，衡量了各种解决方案后，还是觉得masonry最成熟，所以就选用了它。而在之前开发后台...

Kosmos 2019-08-22 10:59 评论0 收藏0
jQuery动画效果、jQuery插件使用

摘要：一事件的绑定与解绑的简单绑定事件新版本使用为指定的元素添加一个或多个事件处理程序，并规定当这个事件发生时运行的函数。将整个文件放至项目的任意目录不要移动其文件结构，它们具有完整的依赖体系。一、事件的绑定与解绑 1.1 jQuery的简单绑定 1.1.1 on(events,fn)事件(新版本使用) 为指定的元素添加一个或多个事件处理程序，并规定当这个事件发生时运行的函数。on()方法...

MkkHou 2019-08-29 16:16 评论0 收藏0
jQuery动画效果、jQuery插件使用

摘要：一事件的绑定与解绑的简单绑定事件新版本使用为指定的元素添加一个或多个事件处理程序，并规定当这个事件发生时运行的函数。将整个文件放至项目的任意目录不要移动其文件结构，它们具有完整的依赖体系。一、事件的绑定与解绑 1.1 jQuery的简单绑定 1.1.1 on(events,fn)事件(新版本使用) 为指定的元素添加一个或多个事件处理程序，并规定当这个事件发生时运行的函数。on()方法...

ssshooter 2019-08-23 10:40 评论0 收藏0