图片放大预览，支持函数调用和组件调用两种方式。
ImagePreview 是一个函数，调用函数后会直接在页面中展示图片预览界面。
import { ImagePreview } from 'vant';
ImagePreview(['https://img.yzcdn.cn/vant/apple-1.jpg']); 通过组件调用 ImagePreview 时，可以通过下面的方式进行注册。
import { createApp } from 'vue';
import { ImagePreview } from 'vant';
// 全局注册
const app = createApp();
app.use(ImagePreview);
// 局部注册
export default {
components: {
[ImagePreview.Component.name]: ImagePreview.Component,
},
}; 直接传入图片数组，即可展示图片预览。
ImagePreview([
'https://img.yzcdn.cn/vant/apple-1.jpg',
'https://img.yzcdn.cn/vant/apple-2.jpg',
]);
ImagePreview 支持传入配置对象，并通过 startPosition 选项指定图片的初始位置（索引值）。
ImagePreview({
images: [
'https://img.yzcdn.cn/vant/apple-1.jpg',
'https://img.yzcdn.cn/vant/apple-2.jpg',
],
startPosition: 1,
}); 设置 closeable 属性后，会在弹出层的右上角显示关闭图标，并且可以通过 close-icon 属性自定义图标，使用close-icon-position 属性可以自定义图标位置。
ImagePreview({
images: [
'https://img.yzcdn.cn/vant/apple-1.jpg',
'https://img.yzcdn.cn/vant/apple-2.jpg',
],
closeable: true,
}); 通过 onClose 选项监听图片预览的关闭事件。
import { Toast } from 'vant';
ImagePreview({
images: [
'https://img.yzcdn.cn/vant/apple-1.jpg',
'https://img.yzcdn.cn/vant/apple-2.jpg',
],
onClose() {
Toast('关闭');
},
}); 通过 beforeClose 属性可以拦截关闭行为。
const instance = ImagePreview({
images: [
'https://img.yzcdn.cn/vant/apple-1.jpg',
'https://img.yzcdn.cn/vant/apple-2.jpg',
],
beforeClose: () => false,
});
setTimeout(() => {
// 调用实例上的 close 方法手动关闭图片预览
instance.close();
}, 2000); 如果需要在图片预览内嵌入组件或其他自定义内容，可以使用组件调用的方式，调用前需要通过 app.use 注册组件。
<van-image-preview
v-model:show="state.show"
:images="state.images"
@change="onChange"
>
<template v-slot:index>第{{ index }}页</template>
</van-image-preview>
import { reactive } from 'vue';
export default {
setup() {
const state = reactive({
show: false,
index: 0,
});
const onChange = (index) => {
state.index = index;
};
return {
state,
images: [
'https://img.yzcdn.cn/vant/apple-1.jpg',
'https://img.yzcdn.cn/vant/apple-2.jpg',
],
onChange,
};
},
}; 通过函数调用 ImagePreview 时，支持传入以下选项：
| 参数名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| images | 需要预览的图片 URL 数组 | string[] |
|
| startPosition | 图片预览起始位置索引 | number | string |
|
| swipeDuration | 动画时长，单位为 | number | string |
|
| showIndex | 是否显示页码 | boolean |
|
| showIndicators | 是否显示轮播指示器 | boolean |
|
| loop | 是否开启循环播放 | boolean |
|
| onClose | 关闭时的回调函数 | Function | - |
| onChange | 切换图片时的回调函数，回调参数为当前索引 | Function | - |
| onScale | 缩放图片时的回调函数，回调参数为当前索引和当前缩放值组成的对象 | Function | - |
| beforeClose | 关闭前的回调函数，返回 false可阻止关闭，支持返回 Promise | (active: number) => boolean | Promise<boolean> | - |
| closeOnPopstate | 是否在页面回退时自动关闭 | boolean |
|
| className | 自定义类名 | string | Array | object | - |
| maxZoom | 手势缩放时，最大缩放比例 | number | string |
|
| minZoom | 手势缩放时，最小缩放比例 | number | string |
|
| closeable | 是否显示关闭图标 | boolean |
|
| closeIcon | 关闭图标名称或图片链接 | string |
|
| closeIconPosition | 关闭图标位置，可选值为
| string |
|
transition | 动画类名，等价于 transition的 name属性 | string |
|
overlay-style | 自定义遮罩层样式 | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 ImagePreview 时，支持以下 Props：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model:show | 是否展示图片预览 | boolean |
|
| images | 需要预览的图片 URL 数组 | string[] |
|
| start-position | 图片预览起始位置索引 | number | string |
|
| swipe-duration | 动画时长，单位为 ms | number | string |
|
| show-index | 是否显示页码 | boolean |
|
| show-indicators | 是否显示轮播指示器 | boolean |
|
| loop | 是否开启循环播放 | boolean |
|
| before-close | 关闭前的回调函数，返回 false可阻止关闭，支持返回 Promise | (active: number) => boolean | Promise<boolean> | - |
| close-on-popstate | 是否在页面回退时自动关闭 | boolean |
|
| class-name | 自定义类名 | string | Array | object | - |
| max-zoom | 手势缩放时，最大缩放比例 | number | string |
|
| min-zoom | 手势缩放时，最小缩放比例 | number | string |
|
| closeable | 是否显示关闭图标 | boolean |
|
| close-icon | 关闭图标名称或图片链接 | string |
|
| close-icon-position | 关闭图标位置，可选值为
| string |
|
transition | 动画类名，等价于 transition的 name属性 | string |
|
overlay-style | 自定义遮罩层样式 | object | - |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
通过组件调用 ImagePreview 时，支持以下事件：
| 事件 | 说明 | 回调参数 |
|---|---|---|
| close | 关闭时触发 | { index: 索引, url: 图片链接 } |
| closed | 关闭且且动画结束后触发 | - |
| change | 切换当前图片时触发 | index: 当前图片的索引 |
| scale | 缩放当前图片时触发 | { index: 当前图片的索引, scale: 当前缩放的值 } |
通过组件调用 ImagePreview 时，通过 ref 可以获取到 ImagePreview 实例并调用实例方法，详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
swipeTo | 切换到指定位置 | index: number, options: Options | - |
通过组件调用 ImagePreview 时，支持以下插槽：
| 名称 | 说明 | 参数 |
|---|---|---|
| index | 自定义页码内容 | { index: 当前图片的索引 } |
| cover | 自定义覆盖在图片预览上方的内容 | - |
| 参数名 | 说明 | 类型 |
|---|---|---|
| url | 当前图片 URL | string |
| index | 当前图片的索引值 | number |
| 参数名 | 说明 | 类型 |
|---|---|---|
| index | 当前图片的索引值 | number |
| scale | 当前图片的缩放值 | number |
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-image-preview-index-text-color | var(--van-white) | - |
| --van-image-preview-index-font-size | var(--van-font-size-md) | - |
| --van-image-preview-index-line-height | var(--van-line-height-md) | - |
| --van-image-preview-index-text-shadow | 0 1px 1px var(--van-gray-8) | - |
| --van-image-preview-overlay-background-color | rgba(0, 0, 0, 0.9) | - |
| --van-image-preview-close-icon-size | 22px | - |
| --van-image-preview-close-icon-color | var(--van-gray-5) | - |
| --van-image-preview-close-icon-active-color | var(--van-gray-6) | - |
| --van-image-preview-close-icon-margin | var(--van-padding-md) | - |
| --van-image-preview-close-icon-z-index | 1 | - |
参见桌面端适配。
请注意 ImagePreview 是一个函数，ImagePreview.Component 才是 ImagePreview 对应的组件。JSX 调用图片预览的正确姿势如下：
export default {
setup() {
const show = ref(false);
return () => <ImagePreview.Component v-model={[show, 'show']} />;
},
};