Vue3中v-viewer详解与使用

v-viewer是基于viewer.js封装的 Vue 3 图片预览组件支持缩放、旋转、翻转、全屏、幻灯片等功能。它提供指令式、组件式、API调用三种使用方式配置高度灵活。一、安装依赖# Vue3 需安装 v-viewernextnpminstallv-viewernext viewerjs--save# 或 yarnyarnaddv-viewernext viewerjs二、全局注册与配置main.js在入口文件全局注册并设置默认配置所有组件生效import{createApp}fromvueimportAppfrom./App.vue// 引入v-viewer及样式importVueViewerfromv-viewerimportviewerjs/dist/viewer.cssconstappcreateApp(App)// 全局注册 默认配置app.use(VueViewer,{defaultOptions:{zIndex:9999,// 层级inline:false,// false弹窗模式true内联模式button:true,// 右上角关闭按钮navbar:true,// 底部缩略图导航title:true,// 显示图片标题文件名/alttoolbar:true,// 底部工具栏tooltip:true,// 缩放时显示百分比movable:true,// 允许拖动zoomable:true,// 允许缩放rotatable:true,// 允许旋转scalable:true,// 允许翻转上下/左右transition:true,// 过渡动画fullscreen:true,// 全屏按钮keyboard:true,// 键盘支持ESC/左右箭头url:src// 读取大图的属性默认img的src}})app.mount(#app)三、三种使用方式Vue3 Script Setup方式1指令式最简单给容器加v-viewer内部所有img自动支持预览template !-- 基础用法 -- div v-viewer classimage-list img v-foritem in imgList :keyitem.id :srcitem.thumb :altitem.name :data-sourceitem.src !-- 自定义大图地址 -- width100 / /div !-- 带局部配置 -- div v-viewer{ navbar: false, zoomRatio: 0.5 } classimage-list img v-forsrc in simpleImgs :keysrc :srcsrc width100 / /div /template script setup import { ref } from vue // 图片列表缩略图 原图 const imgList ref([ { id: 1, thumb: https://picsum.photos/100/100?1, src: https://picsum.photos/800/600?1, name: 风景1 }, { id: 2, thumb: https://picsum.photos/100/100?2, src: https://picsum.photos/800/600?2, name: 风景2 } ]) const simpleImgs ref([ https://picsum.photos/800/600?3, https://picsum.photos/800/600?4 ]) /script方式2组件式viewer标签适合需要自定义布局、作用域插槽、主动控制的场景template viewer :imagesimgList !-- 图片数组 -- :optionsviewerOpts !-- 配置 -- readyonReady !-- 事件 -- showonShow refviewerRef !-- 获取实例 -- !-- 作用域插槽自定义缩略图展示 -- template #default{ index, img } div classimg-item img :srcimg.thumb :altimg.name width120 / p{{ img.name }}/p /div /template /viewer !-- 手动控制 -- button clickshowViewer(1)打开第2张/button /template script setup import { ref } from vue import { Viewer } from v-viewer // 引入组件 const imgList ref([/* 同前 */]) const viewerRef ref(null) // 局部配置覆盖全局 const viewerOpts ref({ toolbar: { zoomIn: 1, zoomOut: 1, reset: 1, rotateLeft: 1, rotateRight: 1, flipHorizontal: 1 }, initialViewIndex: 0 // 初始显示第1张 }) // 方法 const showViewer (index) { viewerRef.value?.$viewer?.view(index) // 调用实例方法 } const onReady (e) console.log(ready, e) const onShow (e) console.log(show, e) /script方式3API 调用程序化打开无缩略图、点击按钮直接打开预览template button clickopenPreview打开图片预览/button /template script setup import { api as viewerApi } from v-viewer // 引入API const openPreview () { const $viewer viewerApi({ // 图片数组字符串或对象 images: [ https://picsum.photos/800/600?5, { src: https://picsum.photos/800/600?6, alt: 图6 } ], // 配置 options: { fullscreen: false, title: false, initialViewIndex: 0 } }) // 调用实例方法 $viewer.show() } /script四、核心配置项详解配置项类型默认说明inlineBooleanfalsetrue内联显示嵌入页面false弹窗buttonBooleantrue右上角关闭按钮navbarBoolean/Numbertrue缩略图导航0/false隐藏toolbarBoolean/Objecttrue工具栏可自定义显示哪些按钮titleBoolean/Functiontrue标题可返回自定义文本zoomableBooleantrue允许缩放rotatableBooleantrue允许旋转90°scalableBooleantrue允许翻转水平/垂直movableBooleantrue允许拖动keyboardBooleantrue键盘支持ESC/←→urlString‘src’从img哪个属性取原图地址initialViewIndexNumber0初始显示第几张zoomRatioNumber0.1鼠标滚轮缩放比例工具栏自定义示例toolbar:{zoomIn:true,zoomOut:true,reset:true,rotateLeft:true,rotateRight:true,flipHorizontal:true,flipVertical:true,prev:true,next:true,play:true,fullscreen:true}五、常用事件与实例方法事件指令/组件均可监听ready初始化完成show显示前shown显示后hide隐藏前hidden隐藏后view切换图片前viewed切换图片后实例方法通过 ref/$viewer 调用view(index)切换到第n张show()/hide()显示/隐藏prev()/next()上一张/下一张zoom(ratio)缩放rotate(degree)旋转flip(horizontal)翻转六、常见问题图片不显示/预览失败检查是否引入viewer.css确认url配置与图片属性匹配src/data-sourceVue3 报错必须安装v-viewernext注册方式改为app.use(VueViewer)动态图片不更新指令加.static修饰符v-viewer.static会禁用更新改用组件式并绑定images响应式数据七、完整最小示例单文件template div v-viewer{ toolbar: true, navbar: true } img v-fori in 4 :keyi :srchttps://picsum.photos/300/200?${i} width100 / /div /template script setup import viewerjs/dist/viewer.css import { directive as viewer } from v-viewer // 局部注册指令 const vViewer viewer({/* 默认配置 */}) /script