怎么在 Vue 或 React 项目中正确集成 viewer.js

在现代前端开发中，viewer.js 是极其成熟且功能完备的原生图片查看器库，支持手势缩放、拖拽平移、旋转翻转以及多图画廊预览。然而，在 Vue 3 或 React 18+ 等现代声明式框架中集成 viewer.js 时，很多开发者会遇到弹窗残留、动态增删图片后无法预览新图、路由切换后内存泄漏，或者在服务端渲染（SSR）阶段抛出 window is not defined 等问题。

出现这些现象的核心根源，在于Vue/React 的虚拟 DOM 声明式渲染逻辑与 viewer.js 的原生命令式 DOM 操作模式之间存在脱节。viewer.js 在初始化时会抓取传入 DOM 内部的 <img> 标签并在 document.body 下创建独立的模态框与工具栏节点。如果不遵循组件生命周期的受控约束，框架与第三方库就会各行其是。要实现规范集成，核心要做好的只有四件事：使用 Ref 获取容器节点、在挂载钩子中实例化、在响应式数据变动后执行 update 同步，以及在组件卸载前彻底调用 destroy 销毁。

一、生命周期契合点与核心约束

原生 JavaScript 使用 viewer.js 时，通常只需执行 const viewer = new Viewer(element, options)。但在组件化框架中，任何对 DOM 的直接读取与改动都必须被纳入框架生命周期管理。以下是现代框架集成必须遵守的三项铁律：

• 严禁使用 document.getElementById 查找目标：在单页应用（SPA）中，组件可能被多次复用或在不同路由间切换，直接全局查询极易获取到缓存的旧节点或产生 ID 冲突。必须统一使用 Vue 的 ref 或 React 的 useRef 绑定 DOM 引用。
• 必须实现对称销毁（Cleanup）：viewer.js 在调用时会在全局 window 和 document 上注册键盘（Esc、方向键）与手势事件，并在 DOM 树外部注入弹出层容器。如果组件卸载时没有调用 viewer.destroy()，事件监听器与浮动 DOM 将永久滞留在内存中，形成典型内存泄漏。
• 列表更新使用 update() 而非重新 new：当图片列表从后端异步拉取或用户上传新图后，DOM 节点被框架重新 Patch，但 viewer.js 内部的图片索引仍停留在旧状态。此时不应销毁并反复重新创建实例，而应调用其内置的 viewer.update() 方法增量同步。

二、在 Vue 3 项目中正确集成

在 Vue 3 项目中，推荐使用 <script setup> 搭配 Composition API 进行实现。由于 viewer.js 依赖独立的 CSS 样式表来定位工具栏和弹出层，必须在组件或全局入口显式引入 viewerjs/dist/viewer.css。

1. 依赖安装与样式引入

npm install viewerjs
# 或使用 pnpm
pnpm add viewerjs

样式可以在应用入口文件（如 main.ts / main.js）中全局引入，也可以只在需要使用查看器的组件中按需局部导入：

import 'viewerjs/dist/viewer.css';

2. Vue 3 基础完整实现

下面是一个标准的 Vue 3 规范示例，实现了 DOM 容器绑定、挂载初始化、异步数据更新监听以及卸载注销：

<template>
  <div class="gallery-wrapper">
    <!-- 1. 将容器通过 ref 绑定到 Vue 实例 -->
    <div ref="galleryRef" class="image-list">
      <img
        v-for="(item, index) in imageList"
        :key="item.id || index"
        :src="item.thumbUrl"
        :data-original="item.largeUrl"
        :alt="item.title"
      />
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount, watch, nextTick } from 'vue';
import Viewer from 'viewerjs';
import 'viewerjs/dist/viewer.css';

// 接收外部传入或内部响应式的图片列表
const props = defineProps({
  imageList: {
    type: Array,
    default: () => []
  }
});

const galleryRef = ref(null);
let viewerInstance = null;

// 初始化 viewer
const initViewer = () => {
  if (!galleryRef.value) return;

  viewerInstance = new Viewer(galleryRef.value, {
    url: 'data-original', // 高清原图属性名
    toolbar: true,
    navbar: true,
    title: true,
    tooltip: true,
    movable: true,
    zoomable: true,
    rotatable: true,
    scalable: true,
    transition: true
  });
};

onMounted(() => {
  initViewer();
});

// 核心细节：监听图片列表更新，在 DOM 更新完成后同步 viewer 内部状态
watch(
  () => props.imageList,
  async () => {
    await nextTick();
    if (viewerInstance) {
      viewerInstance.update();
    }
  },
  { deep: true }
);

// 组件卸载前务必执行销毁
onBeforeUnmount(() => {
  if (viewerInstance) {
    viewerInstance.destroy();
    viewerInstance = null;
  }
});
</script>

三、在 React 项目中正确集成

在 React 18+ 项目中，集成的核心在于利用 useRef 存储两个对象：一个是挂载图片列表的 DOM 容器节点引用，另一个是 Viewer 实例的引用。同时，利用 useEffect 的返回函数完成严格模式（Strict Mode）下的清理工作。

1. React 基础组件实现

import React, { useEffect, useRef } from 'react';
import Viewer from 'viewerjs';
import 'viewerjs/dist/viewer.css';

interface ImageItem {
  id: string | number;
  thumbUrl: string;
  largeUrl: string;
  title?: string;
}

interface ImageViewerProps {
  images: ImageItem[];
  options?: Viewer.Options;
}

export const ImageViewer: React.FC<ImageViewerProps> = ({ images, options }) => {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const viewerRef = useRef<Viewer | null>(null);

  // 1. 初始化与销毁生命周期
  useEffect(() => {
    if (!containerRef.current) return;

    // 创建 viewer.js 实例
    viewerRef.current = new Viewer(containerRef.current, {
      url: 'data-original',
      toolbar: true,
      navbar: true,
      ...options
    });

    // 清理函数：组件卸载或热更新时执行
    return () => {
      if (viewerRef.current) {
        viewerRef.current.destroy();
        viewerRef.current = null;
      }
    };
  }, []); // 仅在容器组件初次挂载时建立实例

  // 2. 当 images 列表变更时同步更新索引
  useEffect(() => {
    if (viewerRef.current) {
      // React 在完成当前 render cycle 后会保证 DOM 已更新
      viewerRef.current.update();
    }
  }, [images]);

  return (
    <div className="react-image-viewer">
      <div ref={containerRef} className="image-grid">
        {images.map((img) => (
          <img
            key={img.id}
            src={img.thumbUrl}
            data-original={img.largeUrl}
            alt={img.title || ''}
            style={{ cursor: 'pointer', maxWidth: '120px', borderRadius: '4px' }}
          />
        ))}
      </div>
    </div>
  );
};

2. React 18 开发环境严格模式应对

在 React 18 开发模式下，<React.StrictMode> 会在挂载时故意执行一次“挂载 -> 卸载 -> 重新挂载”的模拟过程，用以验证组件是否具备纯函数特性及正确的副作用清理。如果清理函数漏写了 destroy()，开发模式下在第一次挂载后便会留下幽灵实例，导致双击放大等行为出现多次触发的异常。

四、生产级集成避坑与排查清单

在实际项目上线或生产构建时，还有几个高频出现的边缘场景需要重点防护：

1. SSR / Nuxt / Next.js 环境报错：window is not defined

viewer.js 内部在模块顶层直接引用了 window 和 document 对象。在服务端预渲染（SSR）阶段，Node.js 运行时没有全局 window，直接顶层 import Viewer from 'viewerjs' 就会导致构建或运行崩溃。

• Nuxt 3 方案：在组件内使用 <ClientOnly> 包裹，或在 onMounted 钩子内部进行动态导入：

  onMounted(async () => {
    const ViewerModule = await import('viewerjs');
    const Viewer = ViewerModule.default;
    viewerInstance = new Viewer(galleryRef.value);
  });

• Next.js 方案：使用 next/dynamic 关闭服务端渲染，或者仅在 useEffect 内部执行动态 import('viewerjs')。

2. 异步大图加载导致的定位偏移与白屏

当配置 url: 'data-original' 加载高清大图时，若网络较慢且未提前为图片指定占位宽高，图片加载完成后尺寸突变可能导致 viewer.js 计算的可视区域中心点偏移。建议在样式中为预览缩略图设定明确的 aspect-ratio 或固定宽高。

3. 路由跳转时处于大图预览状态，遮罩残留

用户在全屏查看图片时点击了浏览器后退按钮或触发了路由切换。此时若仅依赖组件卸载，部分情况下 viewer.js 的过渡动画尚未结束。最稳妥的方式是在卸载前执行关闭并直接销毁：

if (viewerInstance) {
  viewerInstance.hide();    // 立即收起模态框
  viewerInstance.destroy(); // 卸载 DOM
}

五、总结

集成 viewer.js 的关键不是繁琐的配置，而是处理好“生命周期的边界掌控”。只要在组件初次挂载时建立唯一受控实例，在响应式数据变更时结合框架的渲染机制调用 viewer.update()，并在组件注销前毫不犹豫地调用 viewer.destroy()，即可在保证性能与安全的前提下，充分发挥 viewer.js 强大的图片缩放与手势交互能力。