API

适合按钮触发后打开指定图片数组等场景。

演练场

vue

<script setup>
import { ref } from 'vue'
import { useViewer } from 'v-viewer'
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,
}))
const images = ref(sourceImages.slice(0, 5))
const options = ref({ toolbar: true, url: 'data-source', initialViewIndex: 0 })
const { show, isShown } = useViewer({ images, options })
function add() {
  images.value.push(sourceImages[images.value.length])
}
function remove() {
  images.value.pop()
}
</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>
    <p>图片数量：{{ images.length }}</p>
    <p>{{ isShown ? '正在预览' : '等待预览' }}</p>
  </main>
</template>

url: 'data-source' 使用图片的 data-source 属性作为预览地址；initialViewIndex 指定首次显示的图片下标（从 0 开始）。

参数和返回值

useViewer({ images?, options? })

参数	说明
images	临时图库的图片数组、ref 或 getter。
options	Viewer.js 配置、ref 或 getter。

返回值	说明
viewer	ShallowRef<ViewerJs \| undefined>
isShown	弹层是否显示的响应式状态。
show(index?)	打开图库，可指定图片下标。
hide()	正常关闭预览，按配置播放退出动画并调用 `hide` / `hidden` 回调；关闭完成后自动销毁实例并清理临时 DOM。
destroy()	立即销毁实例并清理临时 DOM，不播放退出动画，也不调用 `hide` / `hidden` 回调；再次 `show()` 可重新创建。

在 setup 中调用 useViewer，作用域结束时自动清理。

关闭或销毁预览后会删除临时 DOM。打开期间修改图片数组或配置，下次打开时生效；重复调用 show(index) 会在当前图库内切换图片。

通过 viewer.value 调用 Viewer.js 的全部方法。 Viewer.js methods

配置项

通过 useViewer({ images, options }) 的 options 传入。API 固定使用弹窗模式，inline 始终为 false，不可改写。

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

属性	类型	作用
`backdrop`	boolean / string	弹窗模式的背景遮罩；设为 `static` 时点击遮罩不关闭弹窗。
`button`	boolean	显示右上角按钮。
`className`	string	添加到查看器根元素的自定义类名。
`container`	string / Element	弹窗模式的挂载容器，可传元素或 CSS 选择器。
`filter`	function	筛选可查看的图片，返回 `true` 保留，`false` 忽略。
`fullscreen`	boolean / FullscreenOptions	播放时请求浏览器全屏，可传入 Fullscreen API 配置。
`focus`	boolean	初始化时聚焦缩略图导航的当前项，需要开启 `keyboard`。
`inheritedAttributes`	array	从源图片额外继承的属性；`src`、`alt` 始终继承。
`initialCoverage`	number	图片初始覆盖比例，取值大于 0 且不超过 1。
`initialViewIndex`	number	初始图片下标，也作为 `view()` 的默认下标。
`autoplay`	boolean	播放时自动切换图片。
`interval`	number	播放时自动切换图片的间隔，单位毫秒。
`keyboard`	boolean	启用键盘操作。
`loading`	boolean	加载图片时显示加载指示器。
`loop`	boolean	循环浏览，首尾图片之间可继续切换。
`magnifier`	boolean / object	全屏查看时悬停显示放大镜，可设置尺寸、倍率和透明度；触屏禁用。
`maxZoomRatio`	number / function	最大放大比例，也可由函数根据图片和图片数据计算。
`minZoomRatio`	number / function	最小缩放比例，也可由函数根据图片和图片数据计算。
`movable`	boolean	允许移动图片。
`navbar`	boolean / number / string / object	缩略图导航的显示、尺寸和位置；对象配置支持更多布局选项。
`navigation`	boolean / number / object	查看器左右两侧的上一张、下一张按钮，可分别设置显示和尺寸。
`preload`	boolean	提前加载上一张或下一张图片。
`rotatable`	boolean	允许旋转图片。
`rotateOnGesture`	boolean	通过手势事件旋转图片，例如 Mac Safari 的双指手势。
`rotateOnTouch`	boolean	通过触屏双指手势旋转图片。
`scalable`	boolean	允许按轴缩放图片，可用于水平或垂直翻转。
`slideOnTouch`	boolean	通过触屏滑动切换上一张或下一张图片。
`slideOnWheel`	boolean / string	通过滚轮切图，可指定修饰键；在缩略图导航区域或滚轮缩放未生效时可用。
`title`	boolean / number / function / array	图片标题的显示和内容；默认使用 `alt` 或从 URL 提取的文件名。
`toggleOnDblclick`	boolean	双击时在图片自然尺寸和初始尺寸之间切换。
`toolbar`	boolean / number / object	工具栏及按钮的显示、布局、尺寸和点击行为。
`tooltip`	boolean	缩放时显示当前图片比例的百分比提示。
`transition`	boolean / object	启用 CSS 过渡动画，也可通过对象关闭指定操作的动画。
`url`	string / function	原图地址来源；字符串指定图片属性名，函数返回图片 URL。
`zIndex`	number	弹窗模式下查看器的 CSS `z-index`。
`zoomOnGesture`	boolean	通过手势事件缩放图片，例如 Mac Safari 的捏合手势。
`zoomOnTouch`	boolean	通过触屏拖动手势缩放图片。
`zoomOnWheel`	boolean / string	通过滚轮缩放，可指定修饰键或修饰键组合。
`zoomRatio`	number	滚轮缩放时每次变化的比例。
`zoomable`	boolean	允许缩放图片。

回调

在 options 中设置 viewed(event) 等回调函数，对应 Viewer.js 原生事件。回调参数为原始 DOM 事件，操作数据位于 event.detail；点击名称可查看原文档。

名称	触发时机 / 常用参数
`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`	幻灯片播放中显示每张图片之前。

API ​

演练场 ​

参数和返回值 ​

配置项 ​

回调 ​

API

演练场

参数和返回值

配置项

回调