怎么自定义 viewer.js 的 UI 样式和图标

自定义 Viewer.js 的核心路径并不复杂：Viewer.js 在启动时会向页面动态注入一套标准的 DOM 结构，所有的视图容器、工具栏底座以及操作按钮都带有清晰规范的 class 类名，而按键图标则由默认 CSS 通过 ::before 伪元素渲染。因此，定制主要分为两个层面的工作：一是编写高优先级的 CSS 选择器覆盖弹层背景、工具栏圆角与阴影等 UI 外观；二是将伪元素的背景图替换为自定义 SVG 矢量图标，或通过 JavaScript 的 toolbar 配置项直接注入全新功能按键与事件回调。

一、理解 Viewer.js 的 DOM 结构与样式层级

要精准覆盖样式，必须先明确 Viewer.js 打开大图时在 DOM 树中生成的节点层次。默认情况下，Viewer.js 会将一个根容器 .viewer-container 直接追加到 document.body 尾部。它的内部主要包含三个核心区域：

• .viewer-backdrop：全屏半透明遮罩背景，默认背景色为纯黑（rgba(0, 0, 0, 0.5)），负责捕获背景点击关闭事件。
• .viewer-canvas：图片主画布与变换层，内部包裹真正承载缩放和平移的 <img class="viewer-move"> 元素。
• .viewer-footer：底部浮动控制栏总容器，内含标题栏 .viewer-title、操作按键列表 .viewer-toolbar 以及缩略图条 .viewer-navbar。
• .viewer-button.viewer-close：右上角独立的圆形关闭按键。

在默认的 viewer.css 中，每个工具栏按钮（如放大、缩小、还原、旋转等）都是 .viewer-toolbar > li 元素。其尺寸通常为 24px × 24px，背景为半透明黑色圆形，图标本身并不依赖任何外链字体图标，而是通过 li::before 伪元素指定背景图（Sprites 精灵图或内嵌 Base64/SVG），并利用负边距或定位进行裁切呈现。掌握了这套结构，我们就能有针对性地进行视觉重塑。

二、通过 CSS 深度定制基础 UI 样式

定制 UI 的常规操作顺序应当是：先规划独立的主题样式文件，再依次重置遮罩氛围、工具栏形态以及各个交互按钮的悬浮与激活反馈。

1. 重置全屏遮罩与高斯模糊

默认的黑色半透明遮罩较为单调。如果项目倾向于现代通透风格，可以将遮罩改为浅色毛玻璃背景，或深色高斯模糊渐变：

/* 自定义遮罩层：高斯模糊毛玻璃氛围 */
.viewer-backdrop {
  background-color: rgba(15, 23, 42, 0.75) !important;
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
}

2. 重塑工具栏（Toolbar）为现代悬浮胶囊

原生工具栏的各个按钮紧密排列，视觉层次偏弱。我们可以将 .viewer-toolbar 重构成圆润的毛玻璃胶囊形态，增加阴影与间距：

/* 底部浮动工具栏胶囊容器 */
.viewer-footer .viewer-toolbar {
  background: rgba(255, 255, 255, 0.9) !important;
  backdrop-filter: blur(8px);
  -webkit-backdrop-filter: blur(8px);
  padding: 6px 14px !important;
  border-radius: 30px !important;
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.18) !important;
  display: flex !important;
  align-items: center;
  gap: 8px; /* 增加按钮间隙 */
  width: auto !important;
  height: auto !important;
}

/* 工具栏内部单个按键美化 */
.viewer-footer .viewer-toolbar > li {
  width: 32px !important;
  height: 32px !important;
  background-color: transparent !important;
  border-radius: 50% !important;
  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
}

/* 悬浮微交互反馈 */
.viewer-footer .viewer-toolbar > li:hover {
  background-color: #E2E8F0 !important;
  transform: translateY(-2px);
}

/* 点击激活状态 */
.viewer-footer .viewer-toolbar > li:active {
  transform: translateY(0);
  background-color: #CBD5E1 !important;
}

3. 右上角关闭按钮定制

右上角的关闭按钮类名为 .viewer-button.viewer-close。为了保持整套 UI 风格协调，可以将其改造成具有微光感与圆角阴影的悬浮按钮：

/* 右上角关闭按钮重置 */
.viewer-button.viewer-close {
  top: 24px !important;
  right: 24px !important;
  width: 36px !important;
  height: 36px !important;
  background-color: rgba(255, 255, 255, 0.85) !important;
  backdrop-filter: blur(6px);
  border-radius: 50% !important;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12) !important;
  transition: transform 0.2s ease, background-color 0.2s ease;
}

.viewer-button.viewer-close:hover {
  background-color: #FFFFFF !important;
  transform: scale(1.08);
}

三、更换与自定义工具栏图标的两种实用方案

改变界面骨架后，最显著的视觉差异往往体现在操作图标上。针对图标替换，实际项目中有两种可靠途径：纯 CSS 伪元素背景注入法 与 JavaScript 配置动态扩展法。

方案 A：通过纯 CSS 替换默认图标（推荐用于主题换肤）

Viewer.js 内置了 10 个预设按钮，每个按钮都拥有对应的专属类名：

替换图标时，先将原有的背景精灵图裁切属性清空，并将 ::before 的 background-image 设置为自定义 SVG 的 Data URI，或者使用现代 CSS mask-image（蒙版遮罩技术）。采用 mask-image 的最大好处是能够通过 background-color 任意更改图标颜色：

/* 方案 A-1：直接注入内联 SVG 背景图 */
.viewer-toolbar > li.viewer-zoom-in::before {
  content: "" !important;
  display: block !important;
  width: 20px !important;
  height: 20px !important;
  margin: 0 !important;
  /* 自定义内嵌 SVG（注意 URL 编码中的 %23 代表 #） */
  background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="%23456581" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/><line x1="11" y1="8" x2="11" y2="14"/><line x1="8" y1="11" x2="14" y2="11"/></svg>') !important;
  background-size: contain !important;
  background-repeat: no-repeat !important;
  background-position: center !important;
}

/* 方案 A-2：使用 CSS Mask 蒙版，实现随时用 CSS 变量变色 */
.viewer-toolbar > li.viewer-zoom-out::before {
  content: "" !important;
  display: block !important;
  width: 20px !important;
  height: 20px !important;
  margin: 0 !important;
  background-color: #456581 !important; /* 图标填充色 */
  -webkit-mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/><line x1="8" y1="11" x2="14" y2="11"/></svg>');
  mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/><line x1="8" y1="11" x2="14" y2="11"/></svg>');
  -webkit-mask-size: contain;
  mask-size: contain;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-position: center;
  mask-position: center;
}

.viewer-toolbar > li.viewer-zoom-out:hover::before {
  background-color: #438A80 !important; /* 悬浮时轻松变色 */
}

方案 B：通过 JS options.toolbar 扩展自定义业务按钮与图标

当需要为 Viewer.js 添加原生不存在的功能（例如“下载当前原图”、“图片复制链接”等业务动作）时，应当使用 JavaScript 的 toolbar 选项自定义按键定义与点击事件：

// 初始化 Viewer 并注册自定义工具栏
const gallery = document.getElementById('my-gallery');

const viewer = new Viewer(gallery, {
  inline: false,
  toolbar: {
    // 1. 保留部分内置按钮，按键顺序由对象声明顺序决定
    zoomIn: 1,
    zoomOut: 1,
    oneToOne: 1,
    reset: 1,
    rotateLeft: 1,
    rotateRight: 1,

    // 2. 声明自定义业务按钮：下载功能
    download: {
      show: 1,
      size: 'large',
      click: function() {
        const activeImg = viewer.image; // 获取当前查看的图片元素
        if (!activeImg) return;
        const link = document.createElement('a');
        link.href = activeImg.src;
        link.download = activeImg.alt || 'viewer-download.jpg';
        document.body.appendChild(link);
        link.click();
        document.body.removeChild(link);
      },
    }
  }
});

在 JS 中注册 download 属性后，Viewer.js 会在工具栏中自动生成一个带有 .viewer-download 类名的 <li> 标签。此时只需在 CSS 中为它赋予对应的图标与样式：

/* 为自定义的 download 按钮绑定下载图标 */
.viewer-toolbar > li.viewer-download::before {
  content: "" !important;
  display: block !important;
  width: 20px !important;
  height: 20px !important;
  margin: 0 !important;
  background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="%23438A80" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>') !important;
  background-size: contain !important;
  background-repeat: no-repeat !important;
  background-position: center !important;
}

四、完整实战代码与效果验证

为了让定制效果直接可运行验证，下面提供一份整合好的 HTML + CSS + JS 骨架结构：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Viewer.js 自定义样式演示</title>
  <!-- 1. 引入 Viewer.js 官方样式 -->
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/viewerjs/1.11.6/viewer.min.css">
  <style>
    /* 2. 覆盖自定义主题 */
    .viewer-backdrop {
      background-color: rgba(15, 23, 42, 0.8) !important;
      backdrop-filter: blur(10px);
    }
    .viewer-footer .viewer-toolbar {
      background: rgba(255, 255, 255, 0.95) !important;
      border-radius: 28px !important;
      padding: 6px 16px !important;
      box-shadow: 0 10px 30px rgba(0, 0, 0, 0.25) !important;
      gap: 6px;
    }
    .viewer-toolbar > li {
      width: 32px !important;
      height: 32px !important;
      border-radius: 50% !important;
      background-color: transparent !important;
    }
    .viewer-toolbar > li:hover {
      background-color: #E2E8F0 !important;
    }
    /* 重置放大图标 */
    .viewer-toolbar > li.viewer-zoom-in::before {
      content: "" !important;
      display: block !important;
      width: 18px !important;
      height: 18px !important;
      background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="%23456581" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/><line x1="11" y1="8" x2="11" y2="14"/><line x1="8" y1="11" x2="14" y2="11"/></svg>') !important;
      background-size: contain !important;
      background-repeat: no-repeat !important;
      background-position: center !important;
    }
  </style>
</head>
<body>
  <ul id="gallery" style="list-style: none; display: flex; gap: 12px;">
    <li><img src="https://picsum.photos/400/300" alt="样例图 1" style="max-width: 200px; cursor: pointer;"></li>
  </ul>

  <script src="https://cdnjs.cloudflare.com/ajax/libs/viewerjs/1.11.6/viewer.min.js"></script>
  <script>
    const galleryEl = document.getElementById('gallery');
    new Viewer(galleryEl);
  </script>
</body>
</html>

五、常见问题排查与注意事项

1. 为什么写的 CSS 规则完全不生效？

这是定制 Viewer.js 最常见的问题。主要原因通常有两点：

• CSS 引用时序颠倒：如果自定义样式表排在官方 viewer.min.css 之前，同等权重的选择器会被官方样式无情覆盖。请确保自定义 CSS 在 viewer.min.css 之后引入。
• 选择器权重不足：官方样式中部分属性（如 .viewer-toolbar > li）具有精确的层级。重写时可以增加祖先选择器提升权重，例如写成 body .viewer-container .viewer-toolbar > li，避免暴力滥用 !important。

2. SVG 图标在 Retina / 2K 屏上模糊或尺寸错位？

如果使用内联 SVG Data URI 后图标偏离中心或失真，通常是因为遗漏了 background-size 或 display 属性。务必在 ::before 中声明：

display: block !important;
width: 20px !important;
height: 20px !important;
margin: 0 !important;
background-size: contain !important;
background-repeat: no-repeat !important;
background-position: center !important;

3. 移动端触控热区过小怎么处理？

原生 Viewer.js 的按键尺寸仅为 24px，在移动端容易误触。定制时应在移动端媒体查询中将 .viewer-toolbar > li 的宽高扩展至至少 36px ~ 40px，并适当增大图标内边距，提升触控手感。

六、定制核心维度速查总结

综上所述，自定义 Viewer.js 的 UI 样式与图标是一项典型的“DOM 骨架锁定 + CSS 选择器精准覆盖 + 伪元素矢量注入”的前端实战流程。只要严格遵循 DOM 层级结构、理清图标定位机制并做好特殊字符编码，就能打造出与业务产品视觉完全契合的专业图片查看器。