ImagePreview 图片预览
uni-appH5微信小程序App
uni-app 跨端图片预览。全屏遮罩查看图片,基于内置 <swiper> 实现多图滑动切换(支持循环),双触图片在 1x/2x 间缩放,点击遮罩或关闭按钮退出。与 Web 版 API 保持一致;Web 版的滚轮缩放与 Esc/方向键键盘操作依赖 DOM,跨端降级为双触缩放与箭头/手势切换。
何时使用
点击图片后需要全屏查看并在多图间滑动切换。
何时不使用
仅需原生预览能力时可直接调用 uni.previewImage。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | boolean | false | 显隐(v-model) |
images | string[] | "-" | 图片地址列表(必填) |
startIndex | number | 0 | 初始显示第几张(从 0 开始) |
maskClosable | boolean | true | 点击遮罩是否关闭 |
zIndex | number | 1002 | 浮层层级 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | boolean | 显隐变化时触发 |
close | - | 关闭时触发(遮罩点击 / 关闭按钮) |
change | index: 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" />