ImageViewer 图片预览
全屏图片预览浮层,支持多图相册、加载中状态、缩放/平移/旋转、工具栏操作与下载,适用于聊天图片、附件、头像等大图查看场景。
使用方式
组件以 EmImageViewer 为名导出,全局注册后可直接使用:
vue
<script setup lang="ts">
import { ref } from 'vue'
const show = ref(false)
const index = ref(0)
const srcs = [
'https://example.com/image-1.jpg',
'https://example.com/image-2.jpg',
]
</script>
<template>
<em-image-viewer v-model:show="show" v-model:index="index" :srcs="srcs" />
</template>基础用法
API
ImageViewer API
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| srcs | string[] | — | 图片 URL 列表(多图相册) |
| index | number | 0 | 当前展示索引(v-model:index) |
| show | boolean | false | 是否显示(v-model:show 受控) |
| showToolbar | boolean | true | 是否显示工具栏(缩放/旋转/适应屏/下载) |
| showNavigator | boolean | true | 是否显示多图切换箭头与索引指示 |
| closeOnClickOverlay | boolean | true | 点击遮罩是否关闭 |
Events
| 事件名 | 参数 | 说明 |
|---|---|---|
update:show | value: boolean | 关闭预览时触发(点击遮罩/右上角关闭按钮/ESC),负载 false,供 v-model:show 双向同步 |
update:index | value: number | 当前图片索引变化时触发(打开/切换上下一张),负载为新索引,供 v-model:index 双向同步 |
close | — | 预览关闭完成时触发,与 update:show(false) 同时发出,供业务侧感知关闭 |
load | index: number | 当前图片加载完成 |
load-error | index: number | 当前图片加载失败(业务侧可据此做降级切换) |
download | url: string, index: number | 下载动作触发(组件内部执行下载,事件供业务感知) |
Slots
| 插槽名 | 说明 |
|---|---|
footer | — |
说明
show与index均为受控状态,支持v-model;打开、关闭与切图时自动重置缩放、旋转与平移- 交互能力:双击在 1x / 2x 间切换;滚轮与双指捏合缩放(1~5 倍);放大后可拖拽平移;工具栏支持 90° 旋转、适应屏幕复位与下载
- 「适应屏幕」按钮在视图已处于初始态(未缩放 / 未偏移 / 未旋转)时禁用,hover 提示「已在适应屏幕状态」;缩放或旋转后自动变为可用,点击一键复位
- 退出预览:点击右上角关闭按钮或按
ESC;←/→仅当show-navigator为true时切换图片 - 点击遮罩默认关闭,可通过
close-on-click-overlay关闭该行为;右上角关闭按钮不受此配置影响 #footer插槽作用域提供index/loading/error,业务侧可放置自定义操作(如图片消息的大图 / 原图切换按钮),默认渲染多图索引指示器download事件在组件内部执行下载后触发,供业务感知;文件名从图片 URL 自动提取- 图片加载失败时展示失败占位并触发
load-error事件,业务侧可据此做降级切换(如切回低清图)
