viewer.js 安装与基础初始化教程

一、环境准备与依赖引入

在开始编写业务代码之前，首先需要将 viewer.js 的资源包引入到项目中。根据项目的构建架构不同，通常分为 CDN 标签直引 与 NPM 包管理模块化引入 两种方式。

1. CDN 引入方式（适用于传统 HTML、静态页或快速原型测试）

对于未使用打包工具的原生项目，直接在 HTML 页面中通过 <link> 与 <script> 标签引入官方编译好的静态资源是最直接的做法。推荐使用国内或国际主流稳定 CDN 服务：

<!-- 1. 引入 viewer.js 核心样式文件（必须置于 head 标签中） -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/viewerjs/1.11.7/viewer.min.css">

<!-- 2. 引入 viewer.js 核心逻辑脚本（置于 body 底部或 DOM 节点之后） -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/viewerjs/1.11.7/viewer.min.js"></script>

2. NPM / Yarn 模块化引入（适用于 Vue、React、Vite、Webpack 等现代工程）

在基于模块化打包工具构建的前端项目中，使用包管理器进行安装并局部引入能更好地配合代码分割与版本锁定：

# 使用 npm 安装
npm install viewerjs

# 或使用 yarn 安装
yarn add viewerjs

在对应的页面组件或脚本文件中导入构造器与样式模块：

// 导入 Viewer 核心构造类
import Viewer from 'viewerjs';

// 导入 Viewer 必须的样式表
import 'viewerjs/dist/viewer.css';

二、构建规范的 HTML DOM 结构

viewer.js 在初始化时需要绑定一个容器元素。它会自动扫描该容器内部包含的所有 <img> 标签，并将其纳入当前画廊的轮播索引列表中。常见的组织形式为无序列表 <ul> 或 <div> 容器。

1. 多图画廊相册结构

当需要为多张连续的图片提供翻页浏览体验时，结构如下：

<!-- 统一的画廊外层包裹容器 -->
<ul id="gallery-container" style="display: flex; gap: 12px; list-style: none;">
  <li>
    <img 
      src="images/thumb-01.jpg" 
      data-original="images/highres-01.jpg" 
      alt="项目现场俯瞰实景图">
  </li>
  <li>
    <img 
      src="images/thumb-02.jpg" 
      data-original="images/highres-02.jpg" 
      alt="控制台系统架构拓扑图">
  </li>
  <li>
    <img 
      src="images/thumb-03.jpg" 
      data-original="images/highres-03.jpg" 
      alt="设备运行参数分析曲线">
  </li>
</ul>

2. 核心属性详解与性能建议

• src 属性：定义网页中初次展示的缩略图路径。建议使用体积较小、尺寸合适的压缩图，保证网页首屏的快速渲染。
• data-original 属性（推荐）：指定点击放大后展示的高清大图源地址。viewer.js 默认优先读取该自定义属性。在未点击前不会加载大图，点击后才按需拉取，有效节约网络带宽。
• alt 属性：图片的替代文本。viewer.js 会自动抓取 alt 内容作为弹出画廊顶部的标题文本展示，提供无障碍支持与语义化标注。

三、JavaScript 基础实例化与核心配置

完成依赖引入与 DOM 构建后，即可在脚本中调用全局 Viewer 构造函数。实例化时接受两个参数：目标容器 DOM 节点 以及 自定义配置选项对象。

1. 最简初始化代码

// 确保 DOM 树加载就绪后执行
document.addEventListener('DOMContentLoaded', () => {
  const galleryElement = document.getElementById('gallery-container');
  
  // 基础实例化
  const viewer = new Viewer(galleryElement);
});

在没有传入任何配置项的情况下，viewer.js 会采用默认预设：点击任意一张图片将自动调出全屏遮罩模态框，包含顶部的标题条、底部的缩略图导航栏、完整的控制工具栏（放大、缩小、复位、左右旋转、水平垂直镜像翻转），并支持鼠标滚轮缩放与鼠标拖拽平移。

2. 常用初始化参数详解

通过传入第二个对象参数，可以根据具体业务场景定制预览界面的交互行为与功能组件：

const customViewer = new Viewer(document.getElementById('gallery-container'), {
  // 1. 视图模式设置
  inline: false,           // 是否采用内嵌模式。false 为模态弹窗（默认），true 为直接在容器内展示
  backdrop: true,          // 是否显示半透明遮罩背景（点击遮罩可关闭）
  button: true,            // 是否在右上角显示关闭按钮

  // 2. 界面部件控制
  navbar: true,            // 是否显示底部缩略图导航横条（多图浏览推荐开启，单图可设为 false）
  title: true,             // 是否在顶部显示图片标题（默认读取 img 标签的 alt 属性）
  toolbar: true,           // 是否显示底部操作工具条（可传入数字或对象精简按钮）
  tooltip: true,           // 缩放或旋转时是否在中心弹出百分比提示气泡

  // 3. 交互行为控制
  movable: true,           // 是否允许鼠标按住拖拽图片
  zoomable: true,          // 是否允许缩放（鼠标滚轮、双击或手势捏合）
  rotatable: true,         // 是否允许旋转图片
  scalable: true,          // 是否允许水平/垂直翻转镜像
  transition: true,        // 是否启用打开与关闭的 CSS 平滑过渡动画
  keyboard: true,          // 是否允许键盘方向键切换图片、ESC 键关闭

  // 4. 事件监听回调
  ready() {
    console.log('Viewer 实例初始化完成');
  },
  view(event) {
    console.log('正在展示第 ' + event.detail.index + ' 张图片');
  }
});

四、实例常用 API 与动态交互控制

实例化返回的 viewer 对象暴露了一系列实用方法，供开发者在外部通过按钮点击、快捷键或业务逻辑进行编程式控制。

动态增删图片时的必用方案：viewer.update()

在前后端分离开发中，图片通常由接口异步返回。如果在 new Viewer() 之后向容器中插入了新的 <li><img></li> 节点，直接点击新图片将没有任何反应，因为 viewer.js 尚未捕获新节点。此时必须执行更新：

// 模拟异步接口获取新图片数据
fetch('/api/get-new-photos')
  .then(res => res.json())
  .then(data => {
    const gallery = document.getElementById('gallery-container');
    
    // 动态追加新 DOM 节点
    data.photos.forEach(photo => {
      const li = document.createElement('li');
      li.innerHTML = `<img src="${photo.thumb}" data-original="${photo.large}" alt="${photo.desc}">`;
      gallery.appendChild(li);
    });

    // 核心：通知 viewer 实例更新缓存与事件委托
    viewer.update();
  });

五、常见问题排查与避坑指南

在实际开发与生产集成过程中，针对以下高频问题可按对应步骤进行排查：

1. 弹出遮罩层错位，控制按钮全平铺在页面底部

根本原因：未正确加载 viewer.min.css 或样式被构建工具丢弃。
排查方法：打开浏览器开发者工具（F12），在“网络 (Network)”面板中检查 viewer.css 是否返回 200 状态码；在“元素 (Elements)”面板中查看 .viewer-container 是否应用了 position: fixed 样式规则。

2. 控制台报错 TypeError: Cannot read properties of null (reading 'querySelectorAll')

根本原因：JavaScript 脚本在 DOM 节点渲染出来之前便执行了 new Viewer(element)，导致传入的 element 参数为 null。
解决方案：确保初始化逻辑包裹在 document.addEventListener('DOMContentLoaded', ...) 回调内；在 Vue 中应写在 mounted() / onMounted() 生命周期中，在 React 中应写在 useEffect() 钩子函数内。

3. 单页应用（SPA）切换页面时内存占用飙升或报错

根本原因：前端路由切换时仅销毁了局部页面组件，但 viewer.js 绑定的全局 window 监听器（如 resize、keydown）以及动态注入到 document.body 上的模态 DOM 未被释放。
解决方案：在组件销毁钩子（如 Vue 的 beforeUnmount、React 的 useEffect 清理函数）中主动调用 viewer.destroy()。

4. 弹出的全屏模态框被页面现有的导航栏（Header）遮挡

根本原因：部分系统的头部导航栏设置了极高的 z-index（例如 99999），超过了 viewer.js 默认的 z-index: 2015。
解决方案：在项目的全局样式表中重写 viewer.js 容器的层级，或通过初始化选项中的 zIndex 属性提升优先级：

const viewer = new Viewer(galleryElement, {
  zIndex: 999999 // 提高模态层级，确保覆盖页面固定导航
});

六、初始化实践总结清单

1. 样式优先：始终优先引入 viewer.min.css，这是所有视觉与定位功能的前提。
2. 大图解耦：合理运用 data-original 区分缩略图与高清图，平衡列表加载性能与全屏查看画质。
3. 生命周期闭环：牢记“初始化 → 动态变动调 update() → 组件销毁调 destroy()”的完整闭环，保证程序稳健无内存泄漏。