SmartGallery 2.0 API

创建实例

import SmartGallery from 'smart-gallery';

const gallery = new SmartGallery('#gallery', {
  layout: 'justified',
  gap: 10,
  targetRowHeight: 300
});

容器可以是 CSS 选择器或 HTMLElement。选择器找不到元素时会抛出错误。

图片数据

gallery.setItems([
  {
    id: 'photo-1',
    src: '/images/photo-1.jpg',
    width: 1600,
    height: 1200,
    alt: '图片说明',
    title: '可选标题',
    srcset: '/images/photo-1-800.jpg 800w, /images/photo-1.jpg 1600w',
    sizes: '(max-width: 600px) 100vw, 50vw'
  },
  {
    src: '/images/photo-2.jpg',
    aspectRatio: 1.5
  }
]);

id 可以是字符串或数字；省略时由图库生成。
同一个图库内的 id 必须唯一。
尺寸可以传 aspectRatio，也可以传 width 和 height。
无法得到有效宽高比时按 1:1 布局。
业务需要的其他字段会原样保留，可供自定义渲染和灯箱使用。

配置

配置	默认值	说明
`layout`	`'justified'`	`'justified'`、`'masonry'` 或 `'grid'`
`gap`	`10`	图片间距，必须不小于 0
`targetRowHeight`	`300`	Justified 目标行高
`lastRowBehavior`	`'left'`	`'left'`、`'center'`、`'right'`、`'fill'` 或 `'hide'`
`columnWidth`	`300`	Masonry/Grid 自动分列时的目标列宽
`columns`	`'auto'`	`'auto'` 或固定正整数列数
`className`	`''`	添加到容器的单个 CSS 类名
`itemClassName`	`'sg-item'`	图片外层元素的单个 CSS 类名
`virtualize`	`true`	是否只挂载可见区域附近的图片
`buffer`	`500`	可视区域上下额外挂载的像素范围
`scrollContainer`	`'auto'`	`'auto'`、`window` 或明确的滚动元素
`placeholderColor`	`'#eee'`	默认占位背景色
`errorClassName`	`'sg-item-error'`	图片加载失败时添加到外层元素的类名
`renderItem`	`null`	自定义内容函数 `(item, index) => Node`
`onItemClick`	`null`	图片点击回调
`onImageLoad`	`null`	默认图片加载成功回调
`onImageError`	`null`	默认图片加载失败回调

运行时通过 setOptions() 修改配置，不要直接修改实例内部字段：

gallery.setOptions({ layout: 'masonry', columnWidth: 260 });

数据方法

gallery.setItems(items);       // 替换并重新布局
gallery.addItems(moreItems);   // 追加并重新布局
gallery.removeItem('photo-1'); // 按 id 删除，返回是否找到
gallery.clear();               // 清空图库

gallery.getItems();            // 返回完整数据副本
gallery.getItem('photo-2');    // 按 id 获取图片
gallery.getIndex('photo-2');   // 获取当前顺序，找不到返回 -1
gallery.getGeometry('photo-2');// 获取当前布局位置，未布局时返回 null

以上数据修改方法会自动重新布局。render() 仅用于外部样式变化后主动刷新。

组件卸载时必须清理实例：

gallery.destroy();

灯箱集成

推荐使用编程式数据源，不要让灯箱扫描图库 DOM：

const gallery = new SmartGallery('#gallery', {
  onItemClick: ({ id, index, item, element, geometry, originalEvent }) => {
    const lightboxItems = gallery.getItems().map((photo) => ({
      src: photo.originalSrc || photo.src,
      width: photo.originalWidth || photo.width,
      height: photo.originalHeight || photo.height
    }));

    openLightbox({ items: lightboxItems, index });
  }
});

开启虚拟滚动后，DOM 中只存在当前可视区域附近的元素，因此依赖“扫描所有 DOM 图片”的灯箱只能得到部分数据。getItems() 始终返回完整图片列表。

回调中的 id 是稳定标识，index 是图片当前所在位置。删除或替换数据后，应重新通过 getIndex(id) 获取位置。

FilesExpand file tree

API.md

Latest commit

History