React Image Gallery

一款响应式、可定制的 React 图片画廊组件

▶️ 查看在线演示

✨ 特性

特性	描述
📱 移动端滑动	原生触摸手势，实现流畅的移动端导航
🖼️ 缩略图	可定制的缩略图导航，支持多种位置摆放
📺 全屏模式	浏览器全屏或基于 CSS 的全屏模式
🎨 主题定制	CSS 自定义属性，便于样式调整
⌨️ 键盘导航	支持方向键、ESC 键及自定义按键绑定
🔄 RTL 支持	支持从右到左的语言排版
↕️ 垂直模式	可切换为垂直方向滑动而非水平方向
🎬 自定义幻灯片	可渲染视频、iframes 或任何自定义内容

🚀 快速开始

npm install react-image-gallery

import { useRef } from "react";
import ImageGallery from "react-image-gallery";
import "react-image-gallery/styles/image-gallery.css";
import type { GalleryItem, ImageGalleryRef } from "react-image-gallery";

const images: GalleryItem[] = [
  {
    original: "https://picsum.photos/id/1018/1000/600/",
    thumbnail: "https://picsum.photos/id/1018/250/150/",
  },
  {
    original: "https://picsum.photos/id/1015/1000/600/",
    thumbnail: "https://picsum.photos/id/1015/250/150/",
  },
  {
    original: "https://picsum.photos/id/1019/1000/600/",
    thumbnail: "https://picsum.photos/id/1019/250/150/",
  },
];

function MyGallery() {
  const galleryRef = useRef<ImageGalleryRef>(null);

  return (
    <ImageGallery
      ref={galleryRef}
      items={images}
      onSlide={(index) => console.log("Slid to", index)}
    />
  );
}

更多示例，请参见 example/App.jsx

⚙️ 属性

• items：（必填）对象数组。可用属性：
  • original - 图片源 URL
  • thumbnail - 缩略图源 URL
  • fullscreen - 全屏图片 URL（默认为 original）
  • originalHeight - 图片高度（html5 属性）
  • originalWidth - 图片宽度（html5 属性）
  • loading - "lazy" 或 "eager"（HTML5 属性）
  • thumbnailHeight - 缩略图高度（html5 属性）
  • thumbnailWidth - 缩略图宽度（html5 属性）
  • thumbnailLoading - "lazy" 或 "eager"（HTML5 属性）
  • originalClass - 自定义图片类名
  • thumbnailClass - 自定义缩略图类名
  • renderItem - 用于自定义渲染特定幻灯片的函数（见下文 renderItem）
  • renderThumbInner - 用于自定义缩略图渲染的函数（见下文 renderThumbInner）
  • originalAlt - 图片 alt 属性
  • thumbnailAlt - 缩略图 alt 属性
  • originalTitle - 图片 title 属性
  • thumbnailTitle - 缩略图 title 属性
  • thumbnailLabel - 缩略图标签
  • description - 图片描述
  • srcSet - 图片 srcset（html5 属性）
  • sizes - 图片 sizes（html5 属性）
  • bulletClass - 项目指示点的额外类名
• infinite：布尔值，默认 true - 无限循环
• lazyLoad：布尔值，默认 false
• showNav：布尔值，默认 true
• showThumbnails：布尔值，默认 true
• thumbnailPosition：字符串，默认 bottom - 选项：top、right、bottom、left
• showFullscreenButton：布尔值，默认 true
• useBrowserFullscreen：布尔值，默认 true - 如果为 false，则使用基于 CSS 的全屏
• useTranslate3D：布尔值，默认 true - 如果为 false，则使用 translate 而非 translate3d
• showPlayButton：布尔值，默认 true
• isRTL：布尔值，默认 false - 从右到左模式
• showBullets：布尔值，默认 false
• maxBullets：数字，默认 undefined - 显示的最大指示点数量（至少 3 个，活动指示点居中）
• showIndex：布尔值，默认 false
• autoPlay：布尔值，默认 false
• disableThumbnailScroll：布尔值，默认 false - 禁用缩略图自动滚动
• disableKeyDown：布尔值，默认 false - 禁用键盘导航
• disableSwipe：布尔值，默认 false
• disableThumbnailSwipe：布尔值，默认 false
• onErrorImageURL：字符串，默认 undefined - 加载失败时的备用图片 URL
• indexSeparator：字符串，默认 ' / '，如果 showIndex 为 false 则忽略
• slideDuration：数字，默认 550 - 幻灯片过渡持续时间（毫秒）
• swipingTransitionDuration：数字，默认 0 - 滑动时的过渡持续时间（毫秒）
• slideInterval：数字，默认 3000
• slideOnThumbnailOver：布尔值，默认 false
• slideVertically：布尔值，默认 false - 垂直滑动而非水平滑动
• flickThreshold：数字，默认 0.4 - 滑动速度阈值（值越低越敏感）
• swipeThreshold：数字，默认 30 - 触发导航所需的幻灯片宽度百分比
• stopPropagation：布尔值，默认 false - 在滑动事件上调用 stopPropagation
• startIndex：数字，默认 0
• onImageError：函数，callback(event) - 覆盖 onErrorImageURL
• onThumbnailError：函数，callback(event) - 覆盖 onErrorImageURL
• onThumbnailClick：函数，callback(event, index)
• onBulletClick：函数，callback(event, index)
• onImageLoad：函数，callback(event)
• onSlide：函数，callback(currentIndex)
• onBeforeSlide：函数，callback(nextIndex)
• onScreenChange：函数，callback(isFullscreen)
• onPause：函数，callback(currentIndex)
• onPlay：函数，callback(currentIndex)
• onClick：函数，callback(event)
• onTouchMove：函数，callback(event) on gallery slide
• onTouchEnd：函数，callback(event) on gallery slide
• onTouchStart：函数，callback(event) on gallery slide
• onMouseOver：函数，callback(event) on gallery slide
• onMouseLeave：函数，callback(event) on gallery slide
• additionalClass：字符串，根节点的额外类名
• renderCustomControls：函数，在当前幻灯片上渲染自定义控件
• renderItem：函数，自定义幻灯片渲染
• renderThumbInner：函数，自定义缩略图渲染
• renderLeftNav：函数，自定义左侧导航组件
• renderRightNav：函数，自定义右侧导航组件
• renderTopNav：函数，自定义顶部导航组件（垂直模式）
• renderBottomNav：函数，自定义底部导航组件（垂直模式）
• renderPlayPauseButton：函数，自定义播放/暂停按钮
• renderFullscreenButton：函数，自定义全屏按钮
• useWindowKeyDown：布尔值，默认 true - 使用 window 或元素来监听键盘事件

🔧 功能

以下功能可通过 refs 访问

• play(): 启动幻灯片播放
• pause(): 暂停幻灯片播放
• togglePlay(): 切换播放/暂停状态
• fullScreen(): 进入全屏模式
• exitFullScreen(): 退出全屏模式
• toggleFullScreen(): 切换全屏模式
• slideToIndex(index): 切换到指定索引的幻灯片
• getCurrentIndex(): 返回当前索引

🤝 贡献指南

拉取请求应聚焦于单个问题。如果您不确定某项更改是否有用或涉及重大修改，请先创建一个 issue。

• 遵循 eslint 配置
• 为代码添加注释

🛠️ 本地构建示例

需要 Node.js >= 18.18

git clone https://github.com/xiaolin/react-image-gallery.git
cd react-image-gallery
npm install
npm start

然后在浏览器中打开 localhost:8001。

📄 许可证

MIT © Xiao Lin