PhotoSwipe 入门：图片灯箱预览

文章里点一下图片，弹出一个全屏可缩放、可左右滑动的查看器——这个交互有个专有名词叫「灯箱」（Lightbox），PhotoSwipe 是这个品类里最成熟的库。

PhotoSwipe 是什么

PhotoSwipe 是纯 JavaScript 的图片灯箱库，无任何框架依赖（Vue/React/Svelte 都能包），四个核心体验做到了同类最佳：

手势：双指缩放、拖拽平移、左右滑动切换，移动端手感与原生相册一致
缩放：点击放大到原图、滚轮缩放，高分辨率图不糊
动画：从缩略图位置「生长」到全屏的展开动画，关闭时原路收回
无障碍：键盘方向键切换、ESC 关闭、焦点管理、ARIA 标注齐全

pnpm add photoswipe

最小接入

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

const lightbox = new PhotoSwipeLightbox({
  gallery: '.article-content',      // 在哪个容器里找图
  children: 'a',                    // 点击哪些元素触发（这里是包着图片的链接）
  pswpModule: () => import('photoswipe'),   // 核心模块惰性加载
  bgOpacity: 0.9,
});

lightbox.init();

HTML 结构要求：图片包在一个链接里，链接指向原图，并声明原图尺寸（用于动画计算）：

<div class="article-content">
  <a href="/uploads/big-picture.jpg"
     data-pswp-width="1920"
     data-pswp-height="1080"
     target="_blank">
    <img src="/uploads/big-picture-thumb.jpg" alt="示例图" loading="lazy" />
  </a>
</div>

图片大小必须声明——灯箱的展开动画要从缩略图位置精确「飞」到全屏，不知道原始宽高比就算不出动画轨迹。动态内容（如文章正文是异步渲染的）在渲染完成后 lightbox.init() 或调用 refresh() 重新扫描即可。

本站的文章图链路

本站文章图片的完整链路：作者在写作时上传图片到 MinIO → 正文里是 MinIO 的图片 URL → 前台渲染文章时给正文图片自动包上灯箱链接 → 读者点图进 PhotoSwipe 查看。

对动态插入的正文，做法是文章 HTML 渲染后统一处理：

// 文章正文渲染完成后，为所有图片构建灯箱
document.querySelectorAll('.article-body img').forEach((img) => {
  const link = document.createElement('a');
  link.href = img.src;                    // 原图
  link.dataset.pswpWidth = img.naturalWidth;
  link.dataset.pswpHeight = img.naturalHeight;
  img.parentNode.insertBefore(link, img);
  link.appendChild(img);
});

const lightbox = new PhotoSwipeLightbox({
  gallery: '.article-body',
  children: 'a',
  pswpModule: () => import('photoswipe'),
});
lightbox.init();

两个进阶玩法

放大到原图的意义：文章插图为了加载速度通常上传压缩版，PhotoSwipe 可以让缩略图和原图不同——img.src 用缩略图，a.href 指向原图，读者想看细节时点开是全清晰度的。浏览轻量、查看高清两全。

画廊模式：多张图时，gallery 容器内的所有图自动成为一组，灯箱里可左右滑、底部有缩略图导航条——相册页、教程里的分步截图，天然就是画廊体验。

常见问题

移动端占屏体验：PhotoSwipe 默认全屏黑底 + 底部操作栏，关闭按钮位置符合移动端拇指区。若要与站点主题融合，bgOpacity 调低或自定义背景色即可。

与页面滚动的冲突：灯箱打开时它会锁定 body 滚动（防止背景跟着滚），关闭时恢复——如果站点用了自绘滚动条（如 OverlayScrollbars），注意锁定的是哪个滚动容器，必要时在灯箱的 close 回调里手动恢复容器滚动状态。

版权与体验提醒：灯箱放大意味着读者能看原图——涉及隐私的截图、含敏感信息的图片，发布前自己先打码，前端库不会替你拦。

小结

PhotoSwipe 的定位是「图片查看这件事的最终形态」：手势、缩放、动画、无障碍全做到位，接入只要一个容器选择器加声明图片尺寸。内容站的文章配图、相册、教程分步截图，都值得挂上它——读者点开大图的那一刻，对站点的「精致感」评价就上去了。