React Grid Gallery

受 Google Photos 启发的 React 自适应图片画廊组件。

---

react-grid-gallery 库已停止维护

历经十余年，我决定于今日（2025年8月28日）正式终止对该库的支持。自2015年起，我便未在任何项目中使用过它，其开发与维护工作完全是出于对自由及开源软件（FOSS）的支持，以及对那些在自身项目中使用此库的用户的善意。

更多详情请参见 https://github.com/benhowell/react-grid-gallery/issues/375#issuecomment-3231131756。

欢迎继续使用、复刻、复刻并维护该库，或提交 PR 等。感谢大家，再会！

---

🎉 v1.0.0 版本已发布！

v1.0.0 与 v0.5.x 版本存在不兼容变更，请查阅 迁移指南 了解更多信息。v0.5.x 版本的文档请见 此处。

在线演示与示例

https://benhowell.github.io/react-grid-gallery/

• 图片选择
• 自定义覆盖层
• 缩略图标题
• 自定义图片组件
• 灯箱集成 react-image-lightbox
• 灯箱集成 yet-another-react-lightbox

安装

使用 npm：

npm install --save react-grid-gallery

快速开始

import { Gallery } from "react-grid-gallery";

const images = [
   {
      src: "https://c2.staticflickr.com/9/8817/28973449265_07e3aa5d2e_b.jpg",
      width: 320,
      height: 174,
      isSelected: true,
      caption: "After Rain (Jeshu John - designerspics.com)",
   },
   {
      src: "https://c2.staticflickr.com/9/8356/28897120681_3b2c0f43e0_b.jpg",
      width: 320,
      height: 212,
      tags: [
         { value: "Ocean", title: "Ocean" },
         { value: "People", title: "People" },
      ],
      alt: "Boats (Jeshu John - designerspics.com)",
   },
   {
      src: "https://c4.staticflickr.com/9/8887/28897124891_98c4fdd82b_b.jpg",
      width: 320,
      height: 212,
   },
];

<Gallery images={images} />

图片选项

属性	类型	描述
src	string	必需。指向任何有效图像资源（文件、URL 等）的字符串。
width	number	必需。图像的宽度。
height	number	必需。图像的高度。
nano	string:base64	可选。缩略图 Base64 图像将被注入到主图像下方的背景中。这在图像加载过程中提供一个 4x4 的 base64 生成图像。
alt	string	可选。图像的 alt 属性。
tags	array	可选。包含标签属性（value、title，如果 value 是元素则还需 key）的对象数组。例如：{value: "foo", title: "bar"} 或 {value: <a href={tag.url}>{tag.name}</a>, title: tag.title, key: tag.key}
isSelected	bool	可选。图像的选中状态。
caption	string | ReactNode	可选。图像标题。
customOverlay	element	可选。悬停时作为缩略图覆盖层渲染的自定义元素。
thumbnailCaption	string | ReactNode	可选。显示在缩略图下方的缩略图标题。
orientation	number	可选。图像的方向。许多较新型的数码相机（包括数码单反相机和傻瓜数码相机）都内置了方向传感器。该传感器的输出用于在图像文件的元数据中设置 EXIF 方向标志，以反映相机相对于地面的位置（有关更多信息，请参见 EXIF 方向页面）。

画廊选项

属性	类型	描述
images	array	必需。包含图片属性的对象数组（参见上文的图片选项）。
id	string	可选，默认值 ReactGridGallery。<Gallery> 标签的 id 属性。对于希望区分多个画廊的用户，此属性可能有用。
enableImageSelection	bool	可选，默认值 true。允许图片被选择。如果将此选项设为 false，同时提供 isSelected: true 的图片，则这些图片将被永久选中。
onSelect	func	可选。图片被选中时执行的函数。可选参数：index（被选中图片在 images 数组中的索引）、image（被选中的图片）、event。仅当 enableImageSelection: true 时，此函数才可执行。
rowHeight	number	可选，默认值 180。画廊中每行的高度。
maxRows	number	可选。画廊中要显示的最大行数。
margin	number	可选，默认值 2。画廊中每张图片的外边距。
onClick	func	可选。点击画廊图片时执行的函数。可选参数：index（被点击图片在 images 数组中的索引）、image（被点击的图片）、event（点击事件）。
tagStyle	func | CSSProperties	可选。用于传递给标签元素的样式，或返回样式的函数。可选参数：item（images 中的图片项）。覆盖内部标签样式。
tileViewportStyle	func | CSSProperties	可选。用于设置图片瓦片视口样式的样式或函数。可选参数：item（images 中的图片项）。覆盖内部 tileViewportStyle 函数。
thumbnailStyle	func | CSSProperties	可选。用于设置图片缩略图样式的样式或函数。可选参数：item（images 中的图片项）。覆盖内部 thumbnailStyle 函数。
thumbnailImageComponent	React component	可选。替换为一个 React 组件，该组件将接收 imageProps（原本要传递给 <img> 标签的 props）和 item（images 中的原始项），用于渲染缩略图；这对于延迟加载很有用。
defaultContainerWidth	number	可选。设置容器的默认宽度。此选项在服务器端渲染期间很有用，此时我们希望在检测到实际容器宽度之前生成初始标记。

一般说明

• react-grid-gallery 专为现代浏览器构建，因此对 IE 的支持仅限于 IE 11 及更高版本。

• 由于此组件的灵感来源于 Google Photos，非常小的缩略图在选中时由于应用的边框大小，可能不是最美观的。已选择 180px 作为合理的默认行高，但低至 100px 的行高仍然是可行的。

• 画廊宽度由容器元素决定。因此，您的容器元素必须在画廊加载之前就具有宽度（可以是百分比、em、px 等任何单位）！

• 如果您不知道图片的 width 和 height 值，可以使用多种 javascript 技巧 来获取，不过要注意这些方法会带来加载性能损耗。

贡献

非常欢迎所有对 react-grid-gallery 的贡献。功能请求、问题报告和拉取请求都将受到极大的赞赏。请遵循 贡献指南。

许可证

React Grid Gallery 基于 MIT 许可证，可免费用于个人和商业项目。不要求注明出处，但我们对此表示感谢。

致谢

• itoldya 对代码库进行了大规模改造，使该库得以发布 v1 版本。

• 视觉设计灵感来源于 Google Photos。

• 缩略图视口实现灵感来源于 Florian Maul 的 GPlusGallery。

• 后端灯箱功能通过 jossmac 的 React Images 实现。

• 以下画廊函数源自 React Images 示例 演示：closeLightbox、gotoNext、gotoPrevious、handleClickImage、openLightbox。

• cust0dian 在 PR 6 和 PR 7 中修复了关键错误。

• ValYouW 实现了 lightboxWillOpen 和 lightBoxWillClose 功能 (PR 20) 以及 customOverlay 选项 (PR 22)。

• danalloway 提供了主题传递属性 (PR 27)。

• SimeonC 实现了“当 maxRows 变化时更新缩略图”(PR 35) 和“滚动条出现/消失时调整大小”(PR 40)。

• jakub-tucek 实现了 thumbnailCaption 功能 (PR 42)。

• mis94 实现了 EXIF 图像旋转功能 (PR 67)。

• forforf 添加了 contentWindow 检查 (PR 77)。

• ScottMRafferty 修复了 preloadNextImage 未传递到 Lightbox 的问题 (PR 78)。

• Approximator 添加了 currentImageWillChange（灯箱图片更改前执行的函数）(PR 97)。

• Vadimuz 添加了 nano 图像属性和功能 (PR 101)。

• pxpeterxu 添加了注入自定义缩略图组件的功能（用于懒加载）(PR 104)。

• lryta 修复了当 this.props.images.length - 1 < this.state.currentImage 时的崩溃问题 (PR #111)。

• jimishf 添加了 lightBoxProps 选项，用于将任何属性直接分配给灯箱 (PR #121)。

• kym6464 替换了已弃用的 defaultProps，并在构建时清除 rollup 缓存 (PR #298)。

• 演示用库存照片来源：

  • Jeshu John - designerspics.com
  • Gratisography
  • Tom Eversley - isorepublic.com
  • Jan Vasek - jeshoots.com
  • moveast.me
  • 贝莉儿 NG. - unsplash.com
  • Matthew Wiebe. - unsplash.com