# PhotoSwipe

> 分类：`libs/media/` · 档位：**评估** · 更新时间：2026-11-17

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 5.x |
| License | MIT |
| 维护方 | Dmitry Semenov（dimsemenov） |
| 仓库 / 文档 | https://github.com/dimsemenov/PhotoSwipe · https://photoswipe.com |
| 最近 release | 见官方 releases |

## 2. 一句话定位

面向图片画廊的灯箱：手势缩放、平移、滑动切换、深链与历史记录，移动端体验接近原生相册。
它只负责"看图"，不生成缩略图网格，也不处理视频。

## 3. 体积

| 引入方式 | min | gzip |
|---|---|---|
| 核心 lightbox + pswp（ESM） | 约 45 KB | 约 17 KB（第三方对比口径，待实测） |
| 样式 | — | 另计，需显式引入 |

## 4. 核心 API

```js
import PhotoSwipeLightbox from 'photoswipe/lightbox';
import 'photoswipe/style.css';

const lightbox = new PhotoSwipeLightbox({
  gallery: '#gallery',
  children: 'a',
  pswpModule: () => import('photoswipe'),
});
lightbox.init();
lightbox.destroy();
```

```html
<a href="full.jpg" data-pswp-width="1600" data-pswp-height="1200">
  <img src="thumb.jpg" alt="">
</a>
```

## 5. 适用 / 不适用

- **适用**：产品多图、摄影作品集、需要双指缩放与滑动切换的图库。
- **不适用**：只需要点击放大单图（选 medium-zoom / Zooming）；大量视频或 iframe（选 GLightbox / Fancybox）。

## 6. 硬缺口与已知坑

- 不提供缩略图布局，网格要自己写。
- 必须给每张原图标注 `data-pswp-width` / `data-pswp-height`，否则缩放比例错乱。
- 样式需单独引入，漏引会完全没有遮罩与动画。
- 视频需自定义 content，不属于开箱能力。
- 动态插入或重渲染后要 `destroy()` 再 `init()`。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（CDN ESM） | 可用 | 需用 `<script type="module">` |
| ESM / 打包器 | 可用 | 推荐方式 |
| SSR | 需守卫 | 仅在浏览器端初始化 |
| 客户端重渲染 | 需处理生命周期 | 重渲染后重新 init |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 4 | 成熟项目，更新节奏平稳 |
| 版本与破坏性变更 | 4 | v5 重构后有明确迁移文档 |
| 采用度 | 5 | 大量图库与电商在用 |
| 体积与按需 | 4 | 核心约 17 KB，功能对得起体积 |
| 生态兼容 | 5 | 无依赖，原生 JS |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| GLightbox | 图片/视频/iframe 通吃，接入最简单 | 超多图与深度缩放弱 | 通用内容灯箱 |
| lightGallery | 插件生态最全（缩略图、缩放、分页） | 核心 + 插件后体积偏大 | 需要完整画廊 UI |
| Fancybox 5 | 功能最全，电商图库成熟 | 体积大 | 商业图库 |
| medium-zoom | 极小，单击放大 | 无画廊与切换 | 文章内图片 |
