viewer.js v1 升级到 v2 需要注意哪些 API 变更

一、版本定位与核心架构演进背景

在开始排查具体代码前，首先需要理清前端工程中常说的“viewer.js v1 与 v2”到底对应哪个层级。在原生 JavaScript 生态中，由 Chen Fengyuan 开发的底层核心库 viewerjs 长期保持在 1.x（如 1.15.x）的稳定语义化版本上；而在 Vue 等现代组件化工程中，广为使用的适配库 v-viewer 迎来了从 1.x 到 2.x（以及适配 Vue 3 的重写版）的彻底重构。

许多开发者在项目升级框架或重构脚手架时，直接升级依赖包后往往会遇到“组件无法挂载”、“viewer.show is not a function 报错”或“动态图片列表无法刷新”等问题。这些问题的根源正是因为 v2 版本彻底摈弃了 v1 时代带有历史包袱的黑盒包装模式，全面拥抱了基于原生插槽、属性透传和组合式 Hook 的现代化设计理念。

从图 1 可以看出，v1 架构在很大程度上扮演了“配置转发中介”，将配置打包通过 :options 传入，内部通过自定义循环渲染 DOM，再通过事件把实例向外抛出；而 v2 架构将选择权交还给组件系统：图片列表由外层模板自然展开，组件专注提供轻量的 DOM 观察与看图能力，两者的通信模式因此发生了结构性转变。

二、模块导入与初始化方式重构（Import & Exports）

升级到 v2 后的第一处破坏性变更是包的导出方式。在 v1 中，大部分项目习惯于直接通过 Vue.use(Viewer) 或 import Viewer from 'v-viewer' 获取混合了插件、组件与指令的对象；而在 v2 中，为了更好地支持 Tree-shaking 和 TypeScript 类型推导，所有功能均改为具名命名导出。

// main.js 或组件内部 (v1)
import Vue from 'vue';
import Viewer from 'v-viewer'; // 默认导出整个插件
import 'viewerjs/dist/viewer.css';

Vue.use(Viewer); // 全局安装指令与组件
// 如果想使用原生 Viewer 构造函数，往往也是从同一个对象解构，容易与组件混淆

// main.ts 或组件内部 (v2)
import { createApp } from 'vue';
import { 
  Viewer,    // Vue 组件
  vViewer,   // 指令（如需要 v-viewer 指令模式）
  useViewer, // 组合式 API（纯 JS 弹窗看图）
  ViewerJs   // 底层原生 Viewer.js 构造类（重命名避免同名冲突）
} from 'v-viewer';
import 'viewerjs/dist/viewer.css'; // 样式必须显式引入

const app = createApp(App);
app.component('Viewer', Viewer);
app.directive('viewer', vViewer);

三、组件参数（Props）与插槽结构的重大破坏性变更

这是整个升级过程中对业务代码改动最大、最容易遗漏的环节。v1 的配置方式高度依赖嵌套字典，而 v2 实现了真正的组件参数扁平化与插槽声明式直出。

1. 废除集中式 :options 对象

在 v1 中，所有 Viewer.js 的配置项都必须写进一个单独的 JavaScript 对象中传给 :options。在 v2 中，官方将 Viewer.js 的所有标准配置项直接映射为 <Viewer> 组件的独立 Props。虽然为了平滑过渡，v2 对 options 属性保持了降级兼容，但该属性已被标记为 Deprecated（已废弃），且显式传递的 Props 具有更高的优先级。

2. 彻底移除 :images 与 :trigger 属性

在 v1 中，组件提供了一个 :images="imgList" 属性，并在模板中使用类似 slot-scope="scope" 的作用域插槽遍历渲染。在 v2 中，images 属性、trigger 属性以及作用域插槽参数被完全移除。

v2 规定：图片元素必须直接渲染在 <Viewer> 的默认插槽（Default Slot）中。组件内部通过浏览器的 MutationObserver 监听插槽 DOM 的新增与移除。这样既保持了 Vue 模板的直观性，又彻底解决了 v1 中动态异步推入图片却无法同步更新索引的陈旧缺陷。

<!-- ========================= v1 旧版写法 ========================= -->
<viewer :options="viewerOptions" :images="imageList" @inited="handleInited">
  <!-- 需要借助作用域插槽接收内部 images -->
  <template slot-scope="scope">
    <img v-for="src in scope.images" :src="src" :key="src" class="thumb-img" />
  </template>
</viewer>

<!-- ========================= v2 新版写法 ========================= -->
<!-- 1. 配置项直接作为 Prop 传递 -->
<!-- 2. 原生渲染 img 放置在默认插槽中 -->
<Viewer
  ref="galleryRef"
  :toolbar="true"
  :navbar="false"
  :title="true"
  :rotatable="true"
  :scalable="true"
>
  <img v-for="item in imageList" :key="item.id" :src="item.url" class="thumb-img" />
</Viewer>

四、实例获取与方法调用机制改造

在业务开发中，我们常常需要手动打开预览（例如点击某个自定义按钮查看大图），或者动态切换当前查看的图片索引。v1 与 v2 在实例获取上的模式有着根本区别。

1. 移除 @inited 事件

在 v1 中，官方推荐通过监听 @inited 事件来捕获底层的 Viewer 实例句柄：

// Options API 风格 (v1)
export default {
  data() {
    return {
      $viewer: null
    };
  },
  methods: {
    handleInited(viewerInstance) {
      this.$viewer = viewerInstance; // 保存句柄
    },
    openPreview() {
      if (this.$viewer) {
        this.$viewer.show(); // 调用原生方法
      }
    }
  }
};

在 v2 中，inited 事件被彻底移除。如果继续在模板中书写 @inited="handleInited"，该回调函数永远不会被执行，导致 this.$viewer 始终为 null 或 undefined，进而触发 TypeError: Cannot read properties of undefined (reading 'show') 运行时异常。

2. 替换方案：模板引用（Template Ref）

v2 将底层 Viewer.js 的核心方法（如 show(), hide(), view(), zoom(), rotate(), update() 等）直接代理并挂载到了 Vue 组件实例本身。只需为 <Viewer> 绑定常规的 ref，即可直接调用方法：

<script setup lang="ts">
import { ref } from 'vue';
import { Viewer } from 'v-viewer';

// 声明组件 Ref
const galleryRef = ref<InstanceType<typeof Viewer> | null>(null);

const imageList = ref([
  'https://example.com/photo-1.jpg',
  'https://example.com/photo-2.jpg'
]);

// 直接通过 Ref 调用
const openGallery = (index: number = 0) => {
  galleryRef.value?.view(index);
  galleryRef.value?.show();
};
</script>

<template>
  <button @click="openGallery(0)">打开画廊</button>
  <Viewer ref="galleryRef" :toolbar="true">
    <img v-for="src in imageList" :key="src" :src="src" />
  </Viewer>
</template>

3. 纯 JS 编程式调用：useViewer

如果业务场景中页面上根本没有 <img> 缩略图标签，仅有一组图片 URL 数组需要弹窗全屏预览，在 v1 中通常需要 hack 一个隐藏的 DOM 节点或调用挂载在原型上的 $viewerApi。v2 提供了专门的 useViewer 组合式函数：

import { useViewer } from 'v-viewer';

const showSingleList = () => {
  const show = useViewer({
    images: [
      'https://example.com/large-1.jpg',
      'https://example.com/large-2.jpg'
    ],
    // 各种配置项作为普通属性传入
    options: {
      initialViewIndex: 1,
      navbar: true
    }
  });

  // 触发打开预览
  show();
};

useViewer 内部封装了单例管理与自动生命周期垃圾回收机制，弹窗关闭后会自动清理内存与 DOM，有效防止长时间运行单页应用（SPA）时的内存泄漏。

五、事件系统、样式加载与常见避坑指南

1. 原生事件映射机制

v2 对底层 Viewer.js 的事件做了更精准的透传。你可以直接使用小写驼峰或中划线在组件上监听事件：

• @viewed：大图加载完成并居中显示时触发；
• @show：弹窗开始展示前触发（可通过事件对象阻止默认行为）；
• @hide：弹窗关闭时触发；
• @zoom / @zoomed：缩放前后触发；
• @rotate / @rotated：旋转前后触发。

2. 核心 CSS 样式的显式加载

在部分构建环境（如现代 Vite、Rspack 或 Turbopack）中，由于打包器不再隐式引入依赖包内部的 CSS，必须确保在应用入口（如 main.ts）或公共组件中导入基础样式：

import 'viewerjs/dist/viewer.css';

如果遗漏了这一行引入，会导致极其隐蔽的显示 Bug：点击预览后界面变灰，但是看不到任何操作图标、放大缩小按钮，图片可能以超大尺寸直接撑破视口或堆叠在左上角。

3. 常见报错排查速查表

六、升级验证清单与最佳实践总结

为了确保业务系统中的图片预览功能在升级后稳定上线，建议对照以下检查清单完成代码评审与功能回归：

• 依赖检查：确认 package.json 中 v-viewer 与 viewerjs 版本匹配，无冗余多版本共存；
• 导入检查：检索全局代码中的 from 'v-viewer'，确认已全部改为 import { Viewer, ... } 具名导出，原生类已更名为 ViewerJs；
• 模板检查：确认所有 <Viewer> 标签已剥离 :options 大对象与 :images，并改为直接在默认 slot 渲染 <img>；
• 实例调用：确认所有 @inited 事件监听已替换为模板 ref 直接调用或 useViewer；
• 样式与回归：确认 viewerjs/dist/viewer.css 全局生效，验证单图、多图列表、键盘快捷键（Esc退出、箭头切换）以及移动端手势缩放。

通过以上系统的重构，你的代码不仅能够平滑适配现代化的 Viewer.js v2 体系，还能享受声明式插槽带来的代码精简与更稳定的响应式更新体验。