# @reuse-sh/lightbox 中文文档

规范地址：https://npmcn.com/package/%40reuse-sh/lightbox/

版本：0\.0\.5
npm 元数据更新时间：2026-11-02T07:14:03.499Z
中文译文更新时间：2026-11-02T08:10:12.289Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40reuse-sh/lightbox
原文对照：https://npmcn.com/package/%40reuse-sh/lightbox/?lang=original
项目主页：https://reuse.sh/lightbox
源码仓库：https://github.com/reuse-sh/reuse

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：57.4 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19
- 首次发布：2026-11-01T16:46:47.668Z
- 最新版本发布：2026-11-02T07:14:03.106Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

本机滚动的图像灯箱，具有缩略图过渡，缩放，平移和缩放。

## 安装

```sh
npm install @reuse-sh/lightbox
```

也可以使用：`pnpm add @reuse-sh/lightbox`、`yarn add @reuse-sh/lightbox`、`bun add @reuse-sh/lightbox`

## README

# @reuse-sh / lightbox

一种图像查看器，可以从缩略图（包括裁剪过的缩略图）打开，并在关闭时返回到缩略图。页面可以通过浏览器滚动和滑动，图像可以通过缩放、平移、双击和指针缩放。

## 原则

这些是代码遵守的规则。对任何框架的适应也会保留它们。

-   **带有原生滚动条的页面。** 页面是旋转盘上的滚动夹条，因此触摸和触控板可以保持系统的动力。
-   **从缩略图打开并返回到它。** 图像从其裁剪的预览中生长出来，并在接近时回到相同的位置。
-   **只装近处的东西。** 只加载当前和邻近的图像，并跳过中间的页面。
-   **缩放你触摸的点。** 缩放，滚轮和双击围绕指针或手指缩放，平移停止在图像的边缘。
-   **把注意力集中在内心，然后再放回来。** 查看器是一个原生模态对话框，关闭它会将焦点返回到打开它的元素。
-   **让这一页保持原样。** Destroy恢复页面滚动，隐藏的缩略图，以及查看者触摸的每个样式和监听器。

## 安装

```sh
npm install @reuse-sh/lightbox
```

## 浏览器

```js
import { createLightbox } from "@reuse-sh/lightbox";
import "@reuse-sh/lightbox/styles.css";

const viewer = createLightbox({ thumbnails: true });
viewer.open([{
  src: "/photo.jpg",
  alt: "A mountain lake",
  width: 1600,
  height: 1200,
  origin: document.querySelector("img"),
}]);
```

## 反应

```tsx
import { useLightbox } from "@reuse-sh/lightbox/react";
import "@reuse-sh/lightbox/styles.css";

function Gallery({ images }) {
  const viewer = useLightbox();
  return <button onClick={() => viewer.open(images)}>
    Open gallery
  </button>;
}
```

## 文档

-   示例和API： [https://reuse.sh/lightbox](https://reuse.sh/lightbox)
-   编码代理指南： [https://reuse.sh/lightbox/guide.md](https://reuse.sh/lightbox/guide.md)

## 许可证

麻省理工学院

## 常见问题

### @reuse-sh/lightbox 是什么？

本机滚动的图像灯箱，具有缩略图过渡，缩放，平移和缩放。

### 如何安装 @reuse-sh/lightbox？

在项目目录运行 npm install @reuse-sh/lightbox，或使用 pnpm add / yarn add / bun add。

### @reuse-sh/lightbox 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @reuse-sh/lightbox 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @reuse-sh/lightbox 可以商用吗？

@reuse-sh/lightbox 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @reuse-sh/lightbox 还在维护吗？

最新版本 0\.0\.5 发布于 2026/11/02（1 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。