PhotoSwipe 核心方法详解与应用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00107/article/details/148361373

PhotoSwipe 核心方法详解与应用指南

PhotoSwipe JavaScript image gallery for mobile and desktop, modular, framework independent 项目地址: https://gitcode.com/gh_mirrors/ph/PhotoSwipe

PhotoSwipe 是一个功能强大的图片浏览库，提供了丰富的 API 方法让开发者能够灵活控制图片浏览器的行为。本文将深入解析 PhotoSwipe 的核心方法，帮助开发者更好地掌握这一工具。

PhotoSwipeLightbox 方法

初始化方法 init()

init() 方法是使用 PhotoSwipeLightbox 的第一步，它负责初始化灯箱实例但不直接打开图片浏览器。主要功能包括：

绑定触发打开图片浏览器的事件（默认是点击事件）
允许在对话框打开前预加载图片
为后续操作做好准备

const lightbox = new PhotoSwipeLightbox({
  // 配置选项
});

lightbox.init(); // 必须调用

最佳实践：在实例化后立即调用 init()，但可以在调用前绑定事件监听器。

销毁方法 destroy()

destroy() 方法用于彻底清除一个灯箱实例：

解绑所有事件监听器
如果当前有打开的图片浏览器，会先关闭它
实例销毁后无法再次初始化

if (lightbox) {
  lightbox.destroy();
  lightbox = null; // 手动置空引用是个好习惯
}

应用场景：在单页应用中，当组件卸载时需要清理资源；或者在需要重新初始化灯箱时先销毁旧实例。

加载并打开方法 loadAndOpen()

loadAndOpen() 是主动打开图片浏览器的主要方法，接受三个参数：

index：要打开的幻灯片索引（从0开始）
dataSource（可选）：数据源，可以是数组或包含 gallery 和 items 的对象
point（可选）：点击位置坐标，用于动画效果

// 打开第二个图片
lightbox.loadAndOpen(1, {
  gallery: document.querySelector('#my-gallery')
});

高级用法：当有多个相册时，可以通过指定不同的 gallery 元素来切换数据源。

PhotoSwipe 核心方法

通过 lightbox.pswp 可以访问核心实例，常用方法包括：

导航控制

pswp.goTo(3);    // 跳转到第4张幻灯片
pswp.next();     // 下一张
pswp.prev();     // 上一张

关闭控制

pswp.close();    // 带动画关闭
pswp.destroy();  // 立即销毁

图片操作

// 缩放操作
pswp.currSlide.zoomTo(
  1.5,                   // 缩放级别（1为原始大小）
  { x: 100, y: 100 },    // 缩放中心点
  500,                   // 动画持续时间(ms)
  false                  // 是否忽略边界限制
);

// 平移操作
pswp.currSlide.panTo(200, 150);  // 移动到x:200, y:150位置

注意事项：这些方法通常在 beforeOpen 或 afterInit 等事件回调中使用。

动态幻灯片管理

PhotoSwipe 支持运行时动态修改幻灯片内容，基于 preload 选项智能加载（至少预加载前后2张）。

数据源结构

从DOM初始化的结构：

{
  gallery: <Gallery元素>,
  items: [<子元素1>, <子元素2>, ...]
}

直接传递数组的结构：

[
  { src: 'image1.jpg', width: 100, height: 50 },
  { src: 'image2.jpg', width: 100, height: 50 }
]

动态修改示例

// 替换当前幻灯片
pswp.options.dataSource[pswp.currSlide.index] = {
  src: 'new-image.jpg', 
  width: 800, 
  height: 600
};
pswp.refreshSlideContent(pswp.currSlide.index);

// 添加新幻灯片
pswp.options.dataSource.push({
  src: 'added-image.jpg',
  width: 800,
  height: 600
});
pswp.refreshSlideContent(pswp.getNumItems() - 1);

性能提示：只刷新可见或即将可见的幻灯片，避免不必要的性能开销。

自定义UI元素

通过 pswp.ui.registerElement() 可以添加自定义按钮：

pswp.ui.registerElement({
  name: 'custom-button',
  className: 'pswp__button--custom',
  order: 9,  // 显示顺序
  isButton: true,
  html: '自定义按钮',
  onClick: (event, el) => {
    // 点击处理逻辑
  }
});

样式建议：为自定义按钮添加专属样式类，避免影响默认UI。