跳到主要内容

ImagePreview 图片预览 ​

uni-appH5微信小程序App

uni-app 跨端图片预览。全屏遮罩查看图片,基于内置 <swiper> 实现多图滑动切换(支持循环),双触图片在 1x/2x 间缩放,点击遮罩或关闭按钮退出。与 Web 版 API 保持一致;Web 版的滚轮缩放与 Esc/方向键键盘操作依赖 DOM,跨端降级为双触缩放与箭头/手势切换。

何时使用 ​

点击图片后需要全屏查看并在多图间滑动切换。

何时不使用 ​

仅需原生预览能力时可直接调用 uni.previewImage。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
ImagePreview 图片预览 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuebooleanfalse显隐(v-model)
imagesstring[]"-"图片地址列表(必填)
startIndexnumber0初始显示第几张(从 0 开始)
maskClosablebooleantrue点击遮罩是否关闭
zIndexnumber1002浮层层级

Events ​

名称载荷说明
update:modelValueboolean显隐变化时触发
close-关闭时触发(遮罩点击 / 关闭按钮)
changeindex: number切换图片时触发(滑动 swiper 或点击箭头),参数为新索引

示例 ​

基础用法 ​

vue
<Button variant="primary" @click="visible = true">预览图片</Button>
<ImagePreview v-model="visible" :images="[imgA, imgB]" />

指定起点 ​

vue
<Button variant="secondary" @click="visible2 = true">从第二张开始</Button>
<ImagePreview v-model="visible2" :images="[imgA, imgB]" :start-index="1" />

遮罩不可关闭 ​

vue
<Button variant="ghost" @click="visible3 = true">强预览</Button>
<ImagePreview v-model="visible3" :images="[imgA, imgB]" :mask-closable="false" />