# GLightbox

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

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 3.x |
| License | MIT |
| 维护方 | biati digital |
| 仓库 / 文档 | https://github.com/biati-digital/glightbox · https://biati-digital.github.io/glightbox |
| 最近 release | 见官方 releases |

## 2. 一句话定位

"一个 selector 就能用"的通用灯箱：图片、视频、iframe、内联内容都支持，自带触摸滑动、键盘与无障碍。
它不追求专业图片查看器的深度缩放，胜在接入成本极低。

## 3. 体积

| 引入方式 | min | gzip |
|---|---|---|
| JS + CSS（整包） | 约 40 KB | 约 15 KB（第三方对比口径，待实测） |

## 4. 核心 API

```js
import GLightbox from 'glightbox';
import 'glightbox/dist/css/glightbox.min.css';

const lightbox = GLightbox({
  selector: '.glightbox',
  touchNavigation: true,
  loop: true,
});

lightbox.reload();
lightbox.destroy();
```

```html
<a href="full.jpg" class="glightbox" data-gallery="product">
  <img src="thumb.jpg" alt="">
</a>
```

## 5. 适用 / 不适用

- **适用**：图文混排的灯箱、产品图 + 视频、需要快速接入的营销页。
- **不适用**：上百张图的高性能图库、需要双指深度缩放的场景（选 PhotoSwipe）。

## 6. 硬缺口与已知坑

- 没有虚拟化，图片数量很大时一次性创建全部 slide，内存与初始化时间上升。
- 缩放能力弱于专业图库，移动端双指缩放的细腻度一般。
- 样式文件必须引入，否则遮罩与按钮不可见。
- 动态插入的内容需调用 `reload()` 重新绑定。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（CDN） | 可用 | 有 UMD 与 ESM 两种产物 |
| ESM / 打包器 | 可用 | 推荐方式 |
| SSR | 需守卫 | 仅在浏览器端初始化 |
| 客户端重渲染 | 需处理生命周期 | `reload()` / `destroy()` |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 4 | 持续维护，issue 有响应 |
| 版本与破坏性变更 | 4 | 3.x 稳定 |
| 采用度 | 4 | 常见于营销页与 CMS 主题 |
| 体积与按需 | 5 | 约 15 KB，功能覆盖广 |
| 生态兼容 | 5 | 无依赖 |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| PhotoSwipe | 手势缩放与图库体验最好 | 需自建缩略图、配置多 | 专业图库 |
| lightGallery | 插件最全 | 体积更大 | 需要完整画廊 |
| Fancybox 5 | 电商图库成熟 | 体积大 | 商业项目 |
| BaguetteBox | 约 4 KB，极简 | 功能少 | 只要最简灯箱 |
