viewer.js 常用配置参数详解：自定义工具栏与缩放行为

在 Web 项目中集成图片预览功能时，Viewer.js 是极为流行的高性能开源方案。然而其默认全开的 11 个工具栏按钮常令界面臃肿，不受限制的鼠标滚轮缩放也极易与页面垂直滚动发生误触冲突，或因过度放大导致图像失真。要打造克制、高效且符合具体业务交互的图片查看器，核心在于精准重构 toolbar 对象以及调校 zoomable、zoomRatio、minZoomRatio 等缩放参数。本文将全面拆解这两个维度的底层逻辑，并提供包含自定义按钮注入与安全边界约束的完整落地代码。

一、标准引入与基础初始化

Viewer.js 提供了无框架依赖的原生 JavaScript 版本，同时兼容各类现代前端框架。在页面中接入图片查看器，标准流程包含静态资源加载、DOM 节点组织、配置项注入与实例挂载四个步骤。

最简单的容器形式是在页面中定义包裹图片的父级容器（如 <ul> 或 <div>），或者直接针对单张 <img> 进行实例化。如果希望查看高清大图，可在元素上预先设置 data-original 属性，Viewer.js 会在展开预览时自动以高清图源替换低分辨率的缩略图。

<!-- 1. 引入样式与脚本 -->
<link rel="stylesheet" href="viewer.min.css">
<script src="viewer.min.js"></script>

<!-- 2. 准备图片 DOM 容器 -->
<div id="image-gallery">
  <img src="thumb_01.jpg" data-original="full_01.jpg" alt="设计蓝图 01">
  <img src="thumb_02.jpg" data-original="full_02.jpg" alt="设计蓝图 02">
</div>

<script>
  // 3. 基础初始化
  const gallery = document.getElementById('image-gallery');
  const viewer = new Viewer(gallery, {
    url: 'data-original', // 指定高清大图来源属性
    inline: false,         // 模态弹窗模式（默认）
  });
</script>

在调用 new Viewer(element, options) 之后，Viewer.js 会接管目标容器中所有子图片的点击事件。如果不传入任何自定义选项，Viewer.js 默认会显示底部的全部工具按钮并启用无限制自由缩放。接下来我们将对这一生命周期各个环节进行标准控制。

二、深入配置自定义工具栏（toolbar）

默认状态下，Viewer.js 的底部工具栏包含 11 个内置功能：放大、缩小、1:1还原、重置、上一张、播放、下一张、向左旋转、向右旋转、水平翻转和垂直翻转。在大多数业务场景（例如后台商品审查、工单凭证查看、文档插图放大）中，翻转和幻灯片播放极少使用，反而会增加用户的认知负荷。

2.1 toolbar 参数的三种配置形态

配置项 toolbar 支持布尔值（Boolean）、数字（Number）以及对象（Object）三种传参形式：

• 布尔值模式：传入 false 可完全移除底部工具栏及其 DOM 容器，实现极简视窗；传入 true 则开启默认工具栏。
• 数值模式：传入 0 至 4 的整数档位，代表库预设的不同按钮子集与图标尺寸级别（例如 0 隐藏，4 显示全量）。
• 对象模式（强烈推荐）：通过对象键值对显式声明需要展示的按钮。在对象模式下，只有显式声明的按钮才会渲染，未声明的内置按钮会自动隐藏，无需逐个将它们置为 0。

2.2 内置按钮名称速查

2.3 精简裁剪与按钮尺寸控制

在对象模式中，每个按钮的值可以是一个数字（1 表示显示，0 表示隐藏），也可以是一个更详细的配置对象：包含 show（显隐布尔值或数字）与 size（按钮尺寸：'small'、'medium' 或 'large'）。

// 仅保留常用操作：放大、缩小、1:1还原、复位与旋转
const viewer = new Viewer(gallery, {
  toolbar: {
    zoomIn: 1,
    zoomOut: 1,
    oneToOne: 1,
    reset: 1,
    rotateLeft: 1,
    rotateRight: {
      show: 1,
      size: 'large' // 将最常用的顺时针旋转按钮设置为大尺寸
    },
    // 未显式写入的 prev, next, play, flipHorizontal 等将自动隐藏
  }
});

2.4 扩展挂载自定义功能按钮（如：下载原图）

Viewer.js 允许在 toolbar 对象中定义任意非内置标识的键名，并为其注入 click 回调函数。Viewer.js 会在工具栏中为其生成一个对应的按钮元素，类名为 .viewer-{key}。

// 注入自定义“下载图片”按钮
const viewer = new Viewer(gallery, {
  toolbar: {
    zoomIn: 1,
    zoomOut: 1,
    oneToOne: 1,
    reset: 1,
    download: {
      show: 1,
      size: 'large',
      click: function() {
        // this 指向当前 Viewer 实例上下文
        const currentImg = viewer.image; // 获取当前正在查看的高清 Image 节点
        const downloadUrl = currentImg.src;
        const fileName = currentImg.alt || 'download-image.jpg';
        
        // 创建临时链接触发静默下载
        const link = document.createElement('a');
        link.href = downloadUrl;
        link.download = fileName;
        document.body.appendChild(link);
        link.click();
        document.body.removeChild(link);
      }
    }
  }
});

.viewer-download {
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='white'%3E%3Cpath d='M19 9h-4V3H9v6H5l7 7 7-7zM5 18v2h14v-2H5z'/%3E%3C/svg%3E");
  background-repeat: no-repeat;
  background-position: center;
  background-size: 16px 16px;
}

三、精确控制缩放行为（Zooming）

缩放是图片查看器中使用频率最高的交互，但也是极易引发体验灾难的区域。若不加约束，过快或过慢的缩放步长会让操作失去掌控感，而无限放大缩小会导致图片撕裂或在视口中变成无法看清的细微光斑。

3.1 核心缩放配置参数

3.2 缩放计算逻辑与安全边界配置

当用户通过滚轮或工具栏按钮进行相对缩放时，Viewer.js 的换算机制为：

// 放大
目标比例 = 当前比例 * (1 + zoomRatio);

// 缩小
目标比例 = 当前比例 * (1 - zoomRatio);

计算得出目标比例后，Viewer.js 会将该值置入 [minZoomRatio, maxZoomRatio] 区间进行校验截断。如果设置了合理的极值，超出范围的缩放请求将被自动拦截并截断在边界值，从而保护画面的清晰度与可辨识度。

// 生产级防失真与防穿透缩放配置示例
const viewer = new Viewer(gallery, {
  zoomable: true,        // 开启缩放
  zoomOnWheel: true,     // 允许滚轮缩放
  zoomOnTouch: true,     // 允许触控捏合
  zoomRatio: 0.15,       // 单次步长 15%，滑动体验更轻快
  minZoomRatio: 0.2,     // 最小缩小到原始尺寸的 20%，避免小到丢失
  maxZoomRatio: 4.0,     // 最大放大到原始尺寸的 400%，防止严重马赛克
  tooltip: true          // 呈现缩放百分比浮层
});

3.3 编程式缩放 API：zoom() 与 zoomTo()

除了响应用户交互，我们还可以通过代码主动操控画布。Viewer.js 提供了两个核心缩放方法：

• viewer.zoom(ratio, hasTooltip)：相对增量缩放。
  参数 ratio 为在当前比例基础上的增量。例如 viewer.zoom(0.2) 表示在当前比例上增加 20%；viewer.zoom(-0.1) 表示减少 10%。
• viewer.zoomTo(ratio, hasTooltip)：绝对目标比例缩放。
  参数 ratio 对应目标绝对比例。例如 viewer.zoomTo(1.0) 强制回到 100% 原始尺寸；viewer.zoomTo(2.5) 直接跳转到 250%。

四、进阶实战：监听缩放事件与界面状态联动

Viewer.js 提供了完善的自定义事件机制。在缩放生命周期中，存在两个关键事件：

• zoom：在比例即将发生改变前触发。事件对象的 event.detail 中包含 ratio（目标比例）、oldRatio（旧比例）以及 originalEvent。在此阶段可以通过调用 event.preventDefault() 取消本次缩放。
• zoomed：缩放变换完成并完成画布重绘后触发，用于执行状态同步。

// 实例与外部自定义 UI（如实时百分比指示器）联动
const galleryElement = document.getElementById('image-gallery');
const scaleBadge = document.getElementById('scale-indicator');

galleryElement.addEventListener('zoom', (event) => {
  const nextRatio = event.detail.ratio;
  
  // 示例：动态条件拦截
  // 如果当前是某些特定涉密或水印图片，禁止放大超过 1.5 倍
  if (isRestrictedImage() && nextRatio > 1.5) {
    console.warn('受限图像禁止过度放大');
    event.preventDefault(); // 阻止缩放生效
    return;
  }
});

galleryElement.addEventListener('zoomed', (event) => {
  // 缩放完成后更新外部指示器
  const currentPercent = (event.detail.ratio * 100).toFixed(0);
  if (scaleBadge) {
    scaleBadge.textContent = `${currentPercent}%`;
  }
});

五、生产环境避坑指南

.viewer-container {
  z-index: 99999 !important;
}

六、全景配置矩阵与速查

为了方便快速查阅，以下将本文涉及的关键参数、方法与事件归纳为一个整合的生产级模板配置：

/**
 * Viewer.js 常用综合标准配置模版
 */
const standardViewer = new Viewer(document.getElementById('gallery'), {
  // 基础视窗
  inline: false,         // 模态弹窗模式
  button: true,          // 右上角关闭按钮
  navbar: true,          // 底部小缩略图导航栏
  title: true,           // 显示图片名称与当前张数计数
  tooltip: true,         // 缩放百分比浮层

  // 精细化工具栏（显式声明保留项，其余自动隐藏）
  toolbar: {
    zoomIn: 1,
    zoomOut: 1,
    oneToOne: 1,
    reset: 1,
    rotateRight: 1,
    download: {
      show: 1,
      size: 'large',
      click: function() {
        window.open(this.image.src, '_blank');
      }
    }
  },

  // 缩放行为安全控制
  zoomable: true,        // 开启缩放
  zoomOnWheel: true,     // 允许鼠标滚轮缩放
  zoomOnTouch: true,     // 允许移动端双指手势
  zoomRatio: 0.15,       // 每次缩放步长 15%
  minZoomRatio: 0.2,     // 最小缩小至 20%，防止脱离视区
  maxZoomRatio: 4.0,     // 最大放大至 400%，防止失真严重

  // 边界事件拦截
  zoom(e) {
    // 阻止非正常过载缩放
    if (e.detail.ratio > 5.0 || e.detail.ratio < 0.1) {
      e.preventDefault();
    }
  }
});