v-viewer

简体中文

English

简体中文

English

外观

指令 ​

适合无需复杂定制需求的简单浏览场景，同时支持动态渲染 Markdown 或 HTML 等未知图片内容。默认监听指令绑定元素内部 <img> 元素的增删和属性变化，自动更新图库。

演练场 ​

演练场

vue
<script>
import Vue from 'vue'
import VueViewer from 'v-viewer'
Vue.use(VueViewer)
const sourceImages = [
  '/images/photo-01.jpg',
  '/images/photo-02.jpg',
  '/images/photo-03.jpg',
  '/images/photo-04.jpg',
  '/images/photo-05.jpg',
  '/images/photo-06.jpg',
  '/images/photo-07.jpg',
  '/images/photo-08.jpg',
  '/images/photo-09.jpg',
  '/images/photo-10.jpg',
].map((original) => ({
  src: original.replace('/images/', '/images/thumbnails/'),
  'data-source': original,
}))
export default {
  data() {
    return {
      sourceImages,
      images: sourceImages.slice(0, 5),
      options: { toolbar: true, url: 'data-source' },
    }
  },

  methods: {
    add() {
      this.images.push(this.sourceImages[this.images.length])
    },
    remove() {
      this.images.pop()
    },
    show() {
      this.$refs.gallery.$viewer.show()
    },
    onViewed(event) {
      console.log(event.detail.index)
    },
  },
}
</script>

<template>
  <main class="viewer-example">
    <div class="controls">
      <button :disabled="images.length === sourceImages.length" @click="add">
        添加图片
      </button>
      <button :disabled="images.length === 0" @click="remove">删除图片</button>
      <button class="open" :disabled="images.length === 0" @click="show()">
        显示viewer
      </button>
      <div class="toolbar" role="group" aria-label="切换工具栏">
        <span>切换工具栏</span>
        <button
          :aria-pressed="options.toolbar ? 'true' : 'false'"
          @click="options.toolbar = true"
        >
          开启
        </button>
        <button
          :aria-pressed="options.toolbar ? 'false' : 'true'"
          @click="options.toolbar = false"
        >
          关闭
        </button>
      </div>
    </div>
    <div ref="gallery" v-viewer="options" @viewed="onViewed" class="gallery">
      <img
        v-for="(image, index) in images"
        :key="image.src"
        :src="image.src"
        :data-source="image['data-source']"
        :alt="`Landscape ${index + 1}`"
      />
    </div>
  </main>
</template>

渲染得到的 HTML 同样适用：

vue
<article v-viewer v-html="html" />

绑定值与修饰符 ​

用法说明
v-viewer="options"接受 Viewer.js 配置，深层修改会重建实例。
v-viewer="{ observe: false }"关闭图片 DOM 自动更新。
v-viewer="{ observe: 100 }"在 100ms 窗口内合并图片 DOM 变化；默认 true 使用 50ms，0 不额外等待。
v-viewer="{ rebuild: true }"图片变化时重建实例；默认 false，支持动态切换。
.rebuildrebuild: true 的简写。

绑定值中的 rebuild 优先于 .rebuild，显式设置 false 可关闭重建；未设置或为 undefined 时沿用修饰符。

默认监听指令绑定元素内部 <img> 元素的增删和属性变化，自动更新图库。可通过 element.$viewer 获取实例；卸载时会断开监听并销毁实例。

取值、更新时机及适用场景详见自动更新 observe。

ts
import type { ViewerElement } from 'v-viewer'
const element = document.querySelector<ViewerElement>('#gallery')
element?.$viewer?.show()

配置项 ​

直接放入 v-viewer="options" 绑定的配置对象。配置及其嵌套值变化后会重建实例。

对应 Viewer.js 配置项，点击属性名可查看原文档。可用配置和默认值以安装的 Viewer.js 版本为准。

属性类型作用
backdropboolean / string弹窗模式的背景遮罩；设为 static 时点击遮罩不关闭弹窗。
buttonboolean显示右上角按钮。
classNamestring添加到查看器根元素的自定义类名。
containerstring / Element弹窗模式的挂载容器，可传元素或 CSS 选择器。
filterfunction筛选可查看的图片，返回 true 保留，false 忽略。
fullscreenboolean / FullscreenOptions播放时请求浏览器全屏，可传入 Fullscreen API 配置。
focusboolean初始化时聚焦缩略图导航的当前项，需要开启 keyboard。
inheritedAttributesarray从源图片额外继承的属性；src、alt 始终继承。
initialCoveragenumber图片初始覆盖比例，取值大于 0 且不超过 1。
initialViewIndexnumber初始图片下标，也作为 view() 的默认下标。
inlineboolean开启内嵌模式，在容器内显示；关闭时使用弹窗模式。
autoplayboolean播放时自动切换图片。
intervalnumber播放时自动切换图片的间隔，单位毫秒。
keyboardboolean启用键盘操作。
loadingboolean加载图片时显示加载指示器。
loopboolean循环浏览，首尾图片之间可继续切换。
magnifierboolean / object全屏查看时悬停显示放大镜，可设置尺寸、倍率和透明度；触屏禁用。
maxZoomRationumber / function最大放大比例，也可由函数根据图片和图片数据计算。
minHeightnumber内嵌模式下查看器的最小高度，单位像素。
minWidthnumber内嵌模式下查看器的最小宽度，单位像素。
minZoomRationumber / function最小缩放比例，也可由函数根据图片和图片数据计算。
movableboolean允许移动图片。
navbarboolean / number / string / object缩略图导航的显示、尺寸和位置；对象配置支持更多布局选项。
navigationboolean / number / object查看器左右两侧的上一张、下一张按钮，可分别设置显示和尺寸。
preloadboolean提前加载上一张或下一张图片。
rotatableboolean允许旋转图片。
rotateOnGestureboolean通过手势事件旋转图片，例如 Mac Safari 的双指手势。
rotateOnTouchboolean通过触屏双指手势旋转图片。
scalableboolean允许按轴缩放图片，可用于水平或垂直翻转。
slideOnTouchboolean通过触屏滑动切换上一张或下一张图片。
slideOnWheelboolean / string通过滚轮切图，可指定修饰键；在缩略图导航区域或滚轮缩放未生效时可用。
titleboolean / number / function / array图片标题的显示和内容；默认使用 alt 或从 URL 提取的文件名。
toggleOnDblclickboolean双击时在图片自然尺寸和初始尺寸之间切换。
toolbarboolean / number / object工具栏及按钮的显示、布局、尺寸和点击行为。
tooltipboolean缩放时显示当前图片比例的百分比提示。
transitionboolean / object启用 CSS 过渡动画，也可通过对象关闭指定操作的动画。
urlstring / function原图地址来源；字符串指定图片属性名，函数返回图片 URL。
zIndexnumber弹窗模式下查看器的 CSS z-index。
zIndexInlinenumber内嵌模式下查看器的 CSS z-index。
zoomOnGestureboolean通过手势事件缩放图片，例如 Mac Safari 的捏合手势。
zoomOnTouchboolean通过触屏拖动手势缩放图片。
zoomOnWheelboolean / string通过滚轮缩放，可指定修饰键或修饰键组合。
zoomRationumber滚轮缩放时每次变化的比例。
zoomableboolean允许缩放图片。

事件 ​

Viewer.js 会在指令绑定的原生 HTML 元素上派发 DOM 事件，可以通过 @viewed 这样的写法监听。参数为原始事件，操作数据位于 event.detail；可通过 @show.prevent 阻止打开。

vue
<div v-viewer="options" @viewed="onViewed">
  <img src="/images/photo-01.jpg" />
</div>
名称触发时机 / 常用参数
ready查看器界面初始化完成；弹窗模式下可能在首次打开时才触发。
show / shown弹窗打开前 / 打开过渡动画完成后。
hide / hidden弹窗关闭前 / 关闭过渡动画完成后。
view / viewed图片显示前 / 显示完成后；detail.index 为从 0 开始的图片下标，image 和 originalImage 分别为预览图片与源图片元素。
move / moved移动前 / 后；detail.x、y、oldX、oldY 表示位置变化。
rotate / rotated旋转前 / 后；detail.degree、oldDegree 表示角度变化。
scale / scaled按轴缩放或翻转前 / 后；detail.scaleX、scaleY、oldScaleX、oldScaleY 表示变化。
zoom / zoomed缩放前 / 后；detail.ratio、oldRatio 表示缩放比例。
play / stop开始 / 停止幻灯片播放前。
playing幻灯片播放中显示每张图片之前。

回调 ​

也可以在 options 中设置 Viewer.js 回调，名称与参数对应上面的事件：

js
const options = {
  viewed(event) {
    console.log(event.detail.index)
  },
}

同时设置 @viewed 和 options.viewed 时，两者都会执行；处理相同逻辑时选用一种即可。

旧版本迁移 ​

旧版 .static 修饰符已移除，请替换为 { observe: false }。

基于 MIT 许可发布

v-viewer · mirari