viewer.js 怎么实现多图轮播与指定索引预览

一、viewer.js 多图轮播的基本运行机制

viewer.js 是一款基于原生 JavaScript 构建的高性能图片查看器。当我们在一个包含多个 <img> 节点的父容器（如 <ul> 或 <div>）上实例化 Viewer 时，它会自动扫描容器内的全部图片子节点，在内存中按顺序建立起从 0 到 N-1 的数字索引表。

为了提供连贯的多图轮播体验，viewer.js 内部提供了完整的配置项来驱动多图间的切换与交互控制：

• loop（循环轮播）：默认值为 true。当浏览至图集的最后一张时，点击“下一张”会自动循环过渡到第一张；同理在第一张点击“上一张”也会无缝衔接至末张。
• navbar（缩略图导航）：在预览模态框底部以水平滑动轨的形式渲染全部图片的缩略图，用户点击下方任意缩略图，主舞台会直接联动切换。
• toolbar（交互工具栏）：提供翻页控制按键（prev、next）、旋转、翻转、等比缩放以及原始比例重置等完整操作面板。
• keyboard（键盘支持）：默认开启，允许用户直接敲击键盘左箭头（←）与右箭头（→）进行平滑切图，提升桌面端浏览效率。
• 大图分离机制（url 参数）：页面列表通常只需加载轻量的缩略图以保障首屏性能，将高清大图的实际地址配置在 data-original 自定义属性中，并在初始化时指定 url: 'data-original'，Viewer 便只会在唤起预览时按需请求高清大图。

二、实现指定索引预览的两种核心路径与代码实现

在实际业务中，“预览第 N 张图片”通常分为两类场景：一是读者在图片列表中点击某张缩略图，自然希望大图就定格在该张；二是外部 UI 逻辑（例如订单表格中点击“查看第 3 份凭证”、商品详情页点击某个颜色 SKU 联动弹出大图）需要通过脚本强制唤起并跳转到特定图片。针对这两类场景，viewer.js 提供了两种截然不同的实现路径。

路径一：基于原生 DOM 容器的事件自动委托

如果页面中原本就有一个清晰展示的图片列表，最简便的做法是直接让 viewer.js 代理整个容器。viewer.js 会在内部监听父容器的点击事件，当用户点击容器内的任意图片时，自动匹配出该图片在同级 <img> 集合中的索引，并执行全屏渲染。

<!-- 示例一：原生 DOM 容器自动委托模式 -->
<ul id="gallery" class="image-gallery">
  <li><img src="thumbs/pic1.jpg" data-original="images/pic1.jpg" alt="图 1"></li>
  <li><img src="thumbs/pic2.jpg" data-original="images/pic2.jpg" alt="图 2"></li>
  <li><img src="thumbs/pic3.jpg" data-original="images/pic3.jpg" alt="图 3"></li>
</ul>

<script>
  const galleryElem = document.getElementById('gallery');
  
  // 初始化 Viewer 实例
  const galleryViewer = new Viewer(galleryElem, {
    url: 'data-original',  // 读取原图高清地址
    loop: true,            // 启用多图无限循环轮播
    navbar: true,          // 启用底部导航缩略图
    toolbar: true,         // 启用底部工具栏
    tooltip: true,         // 显示放大比例提示
    transition: true       // 启用平滑过渡动效
  });
</script>

在这种方式下，点击第二张图片（下标为 1），viewer.js 内部自动捕获并执行定位，用户不需要编写任何额外的索引计算逻辑。

路径二：基于编程式 API 的精准调度（viewer.view(index)）

当页面排版不允许平铺所有图片，或者触发按钮与大图没有直接从属关系时，应当采用编程式 API。核心关键在于调用实例提供的 viewer.view(targetIndex) 方法：

• 若此时 Viewer 处于关闭状态，调用 viewer.view(targetIndex) 会自动拉起全屏遮罩并直接跳到该索引图片；
• 若此时 Viewer 已经处于打开状态，调用 viewer.view(targetIndex) 则会在保持全屏视窗的同时平滑滑动至目标图片。

<!-- 示例二：编程式 API 精确调度（支持隐藏挂载容器与外部自定义按钮） -->
<div class="custom-card-list">
  <button type="button" class="preview-btn" data-index="0">预览封面大图 (Index 0)</button>
  <button type="button" class="preview-btn" data-index="1">预览细节特写 (Index 1)</button>
  <button type="button" class="preview-btn" data-index="2">预览包装图集 (Index 2)</button>
</div>

<!-- 离屏挂载容器（用于存放全量图片数据源，无需在主界面直接占位） -->
<div id="hiddenGallery" style="position: absolute; left: -9999px; top: -9999px;">
  <img src="thumbs/cover.jpg" data-original="images/cover_hd.jpg" alt="封面">
  <img src="thumbs/detail.jpg" data-original="images/detail_hd.jpg" alt="细节">
  <img src="thumbs/pack.jpg" data-original="images/pack_hd.jpg" alt="包装">
</div>

<script>
  const hiddenContainer = document.getElementById('hiddenGallery');
  
  // 1. 初始化独立的图片查看器实例
  const programmaticViewer = new Viewer(hiddenContainer, {
    url: 'data-original',
    loop: true,
    navbar: true
  });

  // 2. 外部交互按钮统一绑定事件
  const buttons = document.querySelectorAll('.preview-btn');
  buttons.forEach(btn => {
    btn.addEventListener('click', function() {
      const rawIndex = parseInt(this.getAttribute('data-index'), 10);
      
      // 安全边界防御校验
      const totalImages = hiddenContainer.querySelectorAll('img').length;
      if (isNaN(rawIndex) || rawIndex < 0 || rawIndex >= totalImages) {
        console.warn('请求的目标图片索引超出范围：', rawIndex);
        return;
      }
      
      // 核心 API：传入合法下标，精确开启指定图片
      programmaticViewer.view(rawIndex);
    });
  });
</script>

三、两种方案的关键差异与架构选型对比

在技术选型时，究竟选择“原生 DOM 委托”还是“编程式 API 控制”，取决于页面结构复杂度、动态数据特征以及是否需要在唤起前执行业务逻辑。两者的关键差异如下：

四、动态列表与生产环境关键避坑指南

在实际部署和高频使用 viewer.js 时，以下四个问题最为常见，若处理不当常导致“点击没反应”、“首张白屏”或“索引错位”等缺陷。

// 异步加载新图片并安全更新索引示例
async function appendNewImages(newImageUrls) {
  const gallery = document.getElementById('gallery');
  
  // 1. 向 DOM 中追加新节点
  newImageUrls.forEach(item => {
    const li = document.createElement('li');
    li.innerHTML = `<img src="${item.thumb}" data-original="${item.hd}" alt="${item.title}">`;
    gallery.appendChild(li);
  });

  // 2. 核心：必须通知 viewer 实例重新扫描并重建内部索引映射！
  myViewer.update();

  // 3. 此时即可安全定向到新增的图片位置
  const lastIndex = gallery.querySelectorAll('img').length - 1;
  myViewer.view(lastIndex);
}

五、总结与落地建议

实现 viewer.js 的多图轮播与指定索引预览，本质上是“容器数据组织”与“实例 API 精准调用”的有机结合。在常规画廊场景中，利用原生 DOM 委托配合 loop: true 和 navbar: true 即可获得完善的轮播与缩略图联动效果；在复杂的业务组件系统中，通过独立的挂载容器并结合 viewer.view(safeIndex)，可以实现完全与 UI 视觉解耦的高自由度预览。

在实际编码时，牢记“索引从 0 起算”、“异步更新调 update()”、“组件卸载调 destroy()”三大原则，就能确保多图预览功能在各种复杂网络与交互环境下稳定可靠地运行。