JavaScript Library – PhotoSwipe

效果

前言

以前用过 lightbox2 和 fancyapps.

lightbox2 已经没有维护了.

fancyapps 改版好多次了. v2, v3 现在 v4 已经开始收费了.

PhotoSwipe 目前最火, 下载量最大. 今年三月才推出新版. 虽然还没有用 TypeScript 重写, 但至少是 ES Module 也有 .d.ts 了. 算有跟着时代走.

还有一个叫 lightGallery.js 也是要付费的.

参考

官网 Docs – photoswipe.com

Get Started

我这里用 esbuild + Yarn classic 做 demo.

安装

yarn add photoswipe

它自带 .d.ts 所以不需要另外安装 @types 了.

HTML 引入 CSS

因为没有用 bundle tools 所以直接从 node_module 拉出来就好.

<link
  rel="stylesheet"
  href="./node_modules/photoswipe/dist/photoswipe.css"
/>

用 bundle tools 是这样

import 'photoswipe/style.css';

HTML Data Elements

    <div
      class="pswp-gallery pswp-gallery--single-column"
      id="gallery--getting-started"
    >
      <a
        href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-2500.jpg"
        data-pswp-width="1669"
        data-pswp-height="2500"
        target="_blank"
      >
        <img
          src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/2/img-200.jpg"
          alt=""
        />
      </a>
      <!-- cropped thumbnail: -->
      <a
        href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-2500.jpg"
        data-pswp-width="1875"
        data-pswp-height="2500"
        data-cropped="true"
        target="_blank"
      >
        <img
          src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/7/img-200.jpg"
          alt=""
        />
        Cropped
      </a>
      <!-- data-pswp-src with custom URL in href -->
      <a
        href="https://unsplash.com"
        data-pswp-src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-2500.jpg"
        data-pswp-width="2500"
        data-pswp-height="1666"
        target="_blank"
      >
        <img
          src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/3/img-200.jpg"
          alt=""
        />
      </a>
      <!-- Without thumbnail: -->
      <a
        href="http://example.com"
        data-pswp-src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/5/img-2500.jpg"
        data-pswp-width="2500"
        data-pswp-height="1668"
        target="_blank"
      >
        No thumbnail
      </a>
      <!-- wrapped with any element: -->
      <div>
        <a
          href="https://cdn.photoswipe.com/photoswipe-demo-images/photos/6/img-2500.jpg"
          data-pswp-width="2500"
          data-pswp-height="1667"
          target="_blank"
        >
          <img
            src="https://cdn.photoswipe.com/photoswipe-demo-images/photos/6/img-200.jpg"
            alt=""
          />
        </a>
      </div>
    </div>

结构

首先是一个 container 里面包含了所有要展现在 modal 里的图片. 接着就是每一个图片 data 了.

最基本的 data 需要有 width, height, src 三个属性值.

这个是一种用 HTML provide data 的手法, 它还有一种是直接用 JS without HTML 的手法. 下面会讲到.

JavaScript

import PhotoSwipeLightbox from 'photoswipe/lightbox';

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

photoswipe/lightbox 和 photoswipe 是分开的 src, 目的是减少第一次加载的重量, photoswipe/lightbox 是立刻加载, photoswipe 则是在点击后才去加载.

PhotoSwipeLightbox 初始化后会去 select HTML 然后获取到 data sources, 这个 data sources 也可以直接通过 JS provide 哦. 下面会讲到.

TypeScript Issue

目前有一个 TypeScript Issue, 虽然例子是 Angular 但其实只要你用 TypeScript 都会遇到的. 没办法对这类 library 来说最少还需要 2 年才会完全拥抱 TypeScript 的.

解决方法是定义一个 photoswipe.d.ts 就可以了.

declare module 'photoswipe';
declare module 'photoswipe/lightbox';

同步 Swiper

在 JavaScript Library – Swiper 中, 我举例了一个 fully custom pagination 的例子.

如果想搭上 PhotoSwipe 那么需要加入一个同步的效果.

不然它是这样的

1. swiper index = 0

2. click to popup modal

3. slide to index 2

4. close popup modal

5. swiper index = 0 (没有做同步的话, 这里依然会是 0, 这不一定是期望的体验)

const lightbox = new PhotoSwipeLightbox({
  gallery: '.swiper',
  children: 'a',
  pswpModule: () => import('photoswipe'),
});
lightbox.init();
lightbox.on('change', (e) => {
  swiper.slideTo(lightbox.pswp!.currIndex);
});

参考:

Docs – Events

Docs – Methods

实现起来挺容易的

1. 监听 change

2. 调用 Swiper.slideTo

3. lightbox.pswp.currIndex 获取当前 index (这个 lightbox.pswp 就是 PhotoSwipe 实例)

How PhotoSwipe Work?

作为一个 Library, 我觉得 PhotoSwipe 设计的很好. 它没有封装许多上层的功能, 反而是给出了许多例子去实现这些功能.

比如 download,  fullscreen, caption, WebP

这样可以确保 Library 足够轻. 维护升级就相对轻松. 相对的, 对普罗大众来说可能就需要二次开发了. 但这个 trade-off 还是很值得学习的.

下面我们来看看它的几个重要接口.

1. Data Sources

参考: Docs – Data Sources

上面有提到, data sources 就是 without HTML. 直接通过 JS provide data.

因为 PhotoSwipe 的主要功能就是做 Modal 开启后的 gallery 游览. 其实只要有 data 就可以了. 开启 Modal 之前的图片并不在它的范围内.

首先是设定 options, 里面包含 dataSources

然后 import module, 最后通过 loadAndOpen 打开 Modal Gallery

2. addFilter

参考: Custom Content in Slides

PhotoSwipe 拿到 data sources 以后就要去 build modal gallery 了. 这时它提供了一些拦截接口.

你可以理解为 pipe 或者 middleware.

这 2 招就非常 customize.

1. numItems 直接修改了 data sources 的 length. 那么 loop 就多了

2. itemData, 可以改写输出的内容. 它直接给了一个 raw HTML.

整个就是无中生有, 动态的创建了 data sources. 非常灵活.

在一个例子 WebP

把 HTML dataset 的属性传入 itemData 中

在 contentLoadImage 的时候偷龙转风换成 <picture>

最后输出做好的 picture image

它的概念就是拦截然后替换输出.

其它 Customize

1. 增加操作按钮 e.g. download, autoplay :

参考: Adding UI elements, Methods

2. 换 Theme

Styling PhotoSwipe

3. video

direct support issue

实现 example

虽然没有直接支持, 但是可以通过类似 WebP 的方法做到

4. thumbnails and video

The Best Pop-up Galleries for Photography

这篇文章有提到, PhotoSwipe 和 lightGallery.js (要钱的) 的主要区别. 虽然是 2017 年的文章.

PhotoSwipe 缺失的主要功能是支持 video 和 thumbnials (开启 modal gallery 之后有一个 thumbnials list 让用户切换)

但就如上面提到的可以通过 Customize 的方式去实现. thumbnials list 的实现类似 Adding Navigation Indicator (bullets)

总结

整体使用体验还是很不错的, 如果没有特别要求基本上算是开箱即用了. 个人觉得如果有支持 video 那就更好了.