更新记录

1.0.0（2026-10-12） 下载此版本

平台兼容性

uni-app(3.8.5)

uni-app x(3.8.5)

其他

vant-image-preview

图片预览组件（Vant 风格，零业务耦合），支持函数式与组件式两种调用

介绍

图片预览用于在 fullscreen 遮罩中查看大图，支持左右切换、计数、关闭按钮。本组件为 Vue3 <script setup lang="ts"> 实现，样式令牌统一来自宿主 uni.scss 的 $uni-* 体系。

基础用法

<!-- 函数式调用 -->
<vant-button @click="openByFunction">预览图片</vant-button>

<script setup lang="ts">
import { showImagePreview } from '@/uni_modules/vant-image-preview/components/vant-image-preview/image-preview'

const images = [
  'https://example.com/a.png',
  'https://example.com/b.png',
  'https://example.com/c.png',
]

const openByFunction = () => showImagePreview({ images, startPosition: 0 })
</script>

<!-- 组件式调用（v-model:show） -->
<vant-switch v-model="show" />
<vant-image-preview v-model:show="show" :images="images" :start-position="0" />

Props

Events

Slots

本组件暂无插槽。图片与按钮均为内部渲染；如需自定义，请基于组件源码扩展。

函数式 API

• showImagePreview(images: string[] | { images: string[]; startPosition?: number; closeable?: boolean })：打开预览。
• closeImagePreview()：关闭预览。
• ImagePreview.show(...) / ImagePreview.close()：便捷对象封装。

平台兼容性

• H5 ✓
• 小程序 ✓
• App ✓

设计约束

• 仅 Vue3，不提供 Vue2 / .uvue 实现。
• 组件零业务耦合：无 navigateTo / redirectTo / reLaunch / switchTab / request / cloud 等调用。
• 样式令牌统一来自宿主 uni.scss 的 $uni-*，遮罩背景使用 $uni-bg-color-mask，无硬编码色值。