> 本文由 [简悦 SimpRead](http://ksria.com/simpread/) 转码， 原文地址 [develop365.gitlab.io](https://develop365.gitlab.io/vant/zh-CN/image-preview/#/zh-CN/image-preview)

> ImagePreview 图片预览 vant-image-preview Doc | 组件 中文文档 documentation | v4.9.6 v4.0 v4.x | Vant UI (for v......

### 介绍

图片放大预览，支持组件调用和函数调用两种方式。

### 引入

通过以下方式来全局注册组件，更多注册方式请参考[组件注册](https://develop365.gitlab.io/vant/zh-CN/advanced-usage#zu-jian-zhu-ce//vant/zh-CN/advanced-usage)。

```
import { createApp } from 'vue';
import { ImagePreview } from 'vant';

const app = createApp();
app.use(ImagePreview);
```

### 函数调用

为了便于使用 `ImagePreview`，Vant 提供了一系列辅助函数，通过辅助函数可以快速唤起全局的图片预览组件。

比如使用 `showImagePreview` 函数，调用后会直接在页面中渲染对应的图片预览组件。

```
import { showImagePreview } from 'vant';

showImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);
```

代码演示
----

### 基础用法

在调用 `showImagePreview` 时，直接传入图片数组，即可展示图片预览。

```
import { showImagePreview } from 'vant';

showImagePreview([
  'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
  'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
]);
```

### 指定初始位置

`showImagePreview` 支持传入配置对象，并通过 `startPosition` 选项指定图片的初始位置（索引值）。

```
import { showImagePreview } from 'vant';

showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  startPosition: 1,
});
```

### 展示关闭按钮

开启 `closeable` 选项后，会在弹出层的右上角显示关闭图标，并且可以通过 `close-icon` 属性自定义图标，使用`close-icon-position` 属性可以自定义图标位置。

```
import { showImagePreview } from 'vant';

showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  closeable: true,
});
```

### 监听关闭事件

通过 `onClose` 选项监听图片预览的关闭事件。

```
import { showToast, showImagePreview } from 'vant';

showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  onClose() {
    showToast('关闭');
  },
});
```

### 异步关闭

通过 `beforeClose` 属性可以传入一个回调函数，在图片预览关闭前进行特定操作。

```
import { showImagePreview } from 'vant';

const instance = showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  beforeClose: () => false,
});

setTimeout(() => {
  // 调用实例上的 close 方法手动关闭图片预览
  instance.close();
}, 2000);
```

### 使用 ImagePreview 组件

如果需要在 ImagePreview 内嵌入组件或其他自定义内容，可以直接使用 ImagePreview 组件，并使用 `index` 插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。

```
<van-image-preview v-model:show="show" :images="images" @change="onChange">
  <template v-slot:index>第{{ index + 1 }}页</template>
</van-image-preview>
```

```
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    const index = ref(0);
    const images = [
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
    ];
    const onChange = (newIndex) => {
      index.value = newIndex;
    };

    return {
      show,
      index,
      images,
      onChange,
    };
  },
};
```

### 使用 image 插槽

当以组件调用的方式使用 ImagePreview 时，可以通过 `image` 插槽来插入自定义的内容，比如展示一个视频内容。在这个例子中，你可以将 `close-on-click-image` 属性设置为 `false`，这样当你点击视频时就不会意外关闭预览了。

```
<van-image-preview
  v-model:show="show"
  :images="images"
  :close-on-click-image="false"
>
  <template #image="{ src }">
    <video style="width: 100%;" controls>
      <source :src="src" />
    </video>
  </template>
</van-image-preview>
```

```
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    const images = [
      'https://www.w3school.com.cn/i/movie.ogg',
      'https://www.w3school.com.cn/i/movie.ogg',
      'https://www.w3school.com.cn/i/movie.ogg',
    ];
    return {
      show,
      images,
    };
  },
};
```

当你通过 `image` 插槽自定义图片时，可以通过插槽的参数绑定 `style` 样式和 `onLoad` 回调函数，这可以让 `<img>` 标签支持图片缩放。

```
<van-image-preview
  v-model:show="show"
  :images="images"
  :close-on-click-image="false"
>
  <template #image="{ src, style, onLoad }">
    <img :src="src" :style="[{ width: '100%' }, style]" @load="onLoad" />
  </template>
</van-image-preview>
```

API
---

### 方法

Vant 中导出了以下 ImagePreview 相关的辅助函数：

<table><thead><tr><th>方法名</th><th>说明</th><th>参数</th><th>返回值</th></tr></thead><tbody><tr><td>showImagePreview</td><td>展示一个全屏的图片预览组件</td><td><em>string[] | ImagePreviewOptions</em></td><td>ImagePreview 实例</td></tr></tbody></table>

### ImagePreviewOptions

调用 `showImagePreview` 方法时，支持传入以下选项：

<table><thead><tr><th>参数名</th><th>说明</th><th>类型</th><th>默认值</th></tr></thead><tbody><tr><td>images</td><td>需要预览的图片 URL 数组</td><td><em>string[]</em></td><td><code>[]</code></td></tr><tr><td>startPosition</td><td>图片预览起始位置索引</td><td><em>number | string</em></td><td><code>0</code></td></tr><tr><td>swipeDuration</td><td>动画时长，单位为 <code>ms</code></td><td><em>number | string</em></td><td><code>300</code></td></tr><tr><td>showIndex</td><td>是否显示页码</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>showIndicators</td><td>是否显示轮播指示器</td><td><em>boolean</em></td><td><code>false</code></td></tr><tr><td>loop</td><td>是否开启循环播放</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>doubleScale <code>v4.7.2</code></td><td>是否启用双击缩放手势，禁用后，点击时会立即关闭图片预览</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>onClose</td><td>关闭时的回调函数</td><td><em>Function</em></td><td>-</td></tr><tr><td>onChange</td><td>切换图片时的回调函数，回调参数为当前索引</td><td><em>Function</em></td><td>-</td></tr><tr><td>onScale</td><td>缩放图片时的回调函数，回调参数为当前索引和当前缩放值组成的对象</td><td><em>Function</em></td><td>-</td></tr><tr><td>beforeClose</td><td>关闭前的回调函数，返回 <code>false</code> 可阻止关闭，支持返回 Promise</td><td><em>(active: number) =&gt; boolean | Promise&lt;boolean&gt;</em></td><td>-</td></tr><tr><td>closeOnPopstate</td><td>是否在页面回退时自动关闭</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>closeOnClickImage <code>v4.8.3</code></td><td>是否在点击图片后关闭图片预览</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>closeOnClickOverlay <code>v4.6.4</code></td><td>是否在点击遮罩层后关闭图片预览</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>vertical <code>v4.8.6</code></td><td>是否开启纵向手势滑动</td><td><em>boolean</em></td><td><code>false</code></td></tr><tr><td>className</td><td>自定义类名 (应用在图片预览的弹出层)</td><td><em>string | Array | object</em></td><td>-</td></tr><tr><td>maxZoom</td><td>手势缩放时，最大缩放比例</td><td><em>number | string</em></td><td><code>3</code></td></tr><tr><td>minZoom</td><td>手势缩放时，最小缩放比例</td><td><em>number | string</em></td><td><code>1/3</code></td></tr><tr><td>closeable</td><td>是否显示关闭图标</td><td><em>boolean</em></td><td><code>false</code></td></tr><tr><td>closeIcon</td><td>关闭图标名称或图片链接</td><td><em>string</em></td><td><code>clear</code></td></tr><tr><td>closeIconPosition</td><td>关闭图标位置，可选值为 <code>top-left</code><br><code>bottom-left</code> <code>bottom-right</code></td><td><em>string</em></td><td><code>top-right</code></td></tr><tr><td>transition</td><td>动画类名，等价于 <a href="https://cn.vuejs.org/api/built-in-components.html#transition" target="_blank">transition</a> 的 <code>name</code> 属性</td><td><em>string</em></td><td><code>van-fade</code></td></tr><tr><td>overlayClass</td><td>自定义遮罩层类名</td><td><em>string | Array | object</em></td><td>-</td></tr><tr><td>overlayStyle</td><td>自定义遮罩层样式</td><td><em>object</em></td><td>-</td></tr><tr><td>teleport</td><td>指定挂载的节点，等同于 Teleport 组件的 <a href="https://cn.vuejs.org/api/built-in-components.html#teleport" target="_blank">to 属性</a></td><td><em>string | Element</em></td><td>-</td></tr></tbody></table>

### Props

通过组件调用 `ImagePreview` 时，支持以下 Props：

<table><thead><tr><th>参数</th><th>说明</th><th>类型</th><th>默认值</th></tr></thead><tbody><tr><td>v-model:show</td><td>是否展示图片预览</td><td><em>boolean</em></td><td><code>false</code></td></tr><tr><td>images</td><td>需要预览的图片 URL 数组</td><td><em>string[]</em></td><td><code>[]</code></td></tr><tr><td>start-position</td><td>图片预览起始位置索引</td><td><em>number | string</em></td><td><code>0</code></td></tr><tr><td>swipe-duration</td><td>动画时长，单位为 ms</td><td><em>number | string</em></td><td><code>300</code></td></tr><tr><td>show-index</td><td>是否显示页码</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>show-indicators</td><td>是否显示轮播指示器</td><td><em>boolean</em></td><td><code>false</code></td></tr><tr><td>loop</td><td>是否开启循环播放</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>double-scale <code>v4.7.2</code></td><td>是否启用双击缩放手势，禁用后，点击时会立即关闭图片预览</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>before-close</td><td>关闭前的回调函数，返回 <code>false</code> 可阻止关闭，支持返回 Promise</td><td><em>(active: number) =&gt; boolean | Promise&lt;boolean&gt;</em></td><td>-</td></tr><tr><td>close-on-popstate</td><td>是否在页面回退时自动关闭</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>close-on-click-image <code>v4.8.3</code></td><td>是否在点击图片后关闭图片预览</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>close-on-click-overlay <code>v4.6.4</code></td><td>是否在点击遮罩层后关闭图片预览</td><td><em>boolean</em></td><td><code>true</code></td></tr><tr><td>vertical <code>v4.8.6</code></td><td>是否开启纵向手势滑动</td><td><em>boolean</em></td><td><code>false</code></td></tr><tr><td>class-name</td><td>自定义类名</td><td><em>string | Array | object</em></td><td>-</td></tr><tr><td>max-zoom</td><td>手势缩放时，最大缩放比例</td><td><em>number | string</em></td><td><code>3</code></td></tr><tr><td>min-zoom</td><td>手势缩放时，最小缩放比例</td><td><em>number | string</em></td><td><code>1/3</code></td></tr><tr><td>closeable</td><td>是否显示关闭图标</td><td><em>boolean</em></td><td><code>false</code></td></tr><tr><td>close-icon</td><td>关闭图标名称或图片链接</td><td><em>string</em></td><td><code>clear</code></td></tr><tr><td>close-icon-position</td><td>关闭图标位置，可选值为 <code>top-left</code><br><code>bottom-left</code> <code>bottom-right</code></td><td><em>string</em></td><td><code>top-right</code></td></tr><tr><td>transition</td><td>动画类名，等价于 <a href="https://cn.vuejs.org/api/built-in-components.html#transition" target="_blank">transition</a> 的 <code>name</code> 属性</td><td><em>string</em></td><td><code>van-fade</code></td></tr><tr><td>overlay-class</td><td>自定义遮罩层类名</td><td><em>string | Array | object</em></td><td>-</td></tr><tr><td>overlay-style</td><td>自定义遮罩层样式</td><td><em>object</em></td><td>-</td></tr><tr><td>teleport</td><td>指定挂载的节点，等同于 Teleport 组件的 <a href="https://cn.vuejs.org/api/built-in-components.html#teleport" target="_blank">to 属性</a></td><td><em>string | Element</em></td><td>-</td></tr></tbody></table>

### Events

通过组件调用 `ImagePreview` 时，支持以下事件：

<table><thead><tr><th>事件名</th><th>说明</th><th>回调参数</th></tr></thead><tbody><tr><td>close</td><td>关闭时触发</td><td><em>{index: number, url: string}</em></td></tr><tr><td>closed</td><td>关闭且且动画结束后触发</td><td>-</td></tr><tr><td>change</td><td>切换当前图片时触发</td><td><em>index: number</em></td></tr><tr><td>scale</td><td>缩放当前图片时触发</td><td><em>{index: number, scale: number}</em></td></tr><tr><td>long-press</td><td>长按当前图片时触发</td><td><em>{index: number}</em></td></tr></tbody></table>

### 方法

通过组件调用 `ImagePreview` 时，通过 ref 可以获取到 ImagePreview 实例并调用实例方法，详见[组件实例方法](https://develop365.gitlab.io/vant/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa//vant/zh-CN/advanced-usage)。

<table><thead><tr><th>方法名</th><th>说明</th><th>参数</th><th>返回值</th></tr></thead><tbody><tr><td>resetScale <code>4.7.4</code></td><td>重置当前图片的缩放比</td><td>-</td><td>-</td></tr><tr><td>swipeTo</td><td>切换到指定位置</td><td><em>index: number, options?: SwipeToOptions</em></td><td>-</td></tr></tbody></table>

### 类型定义

组件导出以下类型定义：

```
import type {
  ImagePreviewProps,
  ImagePreviewOptions,
  ImagePreviewInstance,
  ImagePreviewScaleEventParams,
} from 'vant';
```

`ImagePreviewInstance` 是组件实例的类型，用法如下：

```
import { ref } from 'vue';
import type { ImagePreviewInstance } from 'vant';

const imagePreviewRef = ref<ImagePreviewInstance>();

imagePreviewRef.value?.swipeTo(1);
```

### Slots

通过组件调用 `ImagePreview` 时，支持以下插槽：

<table><thead><tr><th>名称</th><th>说明</th><th>参数</th></tr></thead><tbody><tr><td>index</td><td>自定义页码内容</td><td><em>{index: 当前图片的索引}</em></td></tr><tr><td>cover</td><td>自定义覆盖在图片预览上方的内容</td><td>-</td></tr><tr><td>image</td><td>自定义图片内容</td><td><em>{src: 当前资源地址, onLoad: 加载图片函数, style: 当前图片样式}</em></td></tr></tbody></table>

### onClose 回调参数

<table><thead><tr><th>参数名</th><th>说明</th><th>类型</th></tr></thead><tbody><tr><td>url</td><td>当前图片 URL</td><td><em>string</em></td></tr><tr><td>index</td><td>当前图片的索引值</td><td><em>number</em></td></tr></tbody></table>

### onScale 回调参数

<table><thead><tr><th>参数名</th><th>说明</th><th>类型</th></tr></thead><tbody><tr><td>index</td><td>当前图片的索引值</td><td><em>number</em></td></tr><tr><td>scale</td><td>当前图片的缩放值</td><td><em>number</em></td></tr></tbody></table>

主题定制
----

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](https://develop365.gitlab.io/vant/zh-CN/config-provider/#/zh-CN/config-provider)。

<table><thead><tr><th>名称</th><th>默认值</th><th>描述</th></tr></thead><tbody><tr><td>--van-image-preview-index-text-color</td><td><em>var(--van-white)</em></td><td>-</td></tr><tr><td>--van-image-preview-index-font-size</td><td><em>var(--van-font-size-md)</em></td><td>-</td></tr><tr><td>--van-image-preview-index-line-height</td><td><em>var(--van-line-height-md)</em></td><td>-</td></tr><tr><td>--van-image-preview-index-text-shadow</td><td><em>0 1px 1px var(--van-gray-8)</em></td><td>-</td></tr><tr><td>--van-image-preview-overlay-background</td><td><em>rgba(0, 0, 0, 0.9)</em></td><td>-</td></tr><tr><td>--van-image-preview-close-icon-size</td><td><em>22px</em></td><td>-</td></tr><tr><td>--van-image-preview-close-icon-color</td><td><em>var(--van-gray-5)</em></td><td>-</td></tr><tr><td>--van-image-preview-close-icon-margin</td><td><em>var(--van-padding-md)</em></td><td>-</td></tr><tr><td>--van-image-preview-close-icon-z-index</td><td><em>1</em></td><td>-</td></tr></tbody></table>

常见问题
----

### 引用 showImagePreview 时出现编译报错？

如果引用 `showImagePreview` 方法时出现以下报错，说明项目中使用了 `babel-plugin-import` 插件，导致代码被错误编译。

```
These dependencies were not found:

* vant/es/show-image-preview in ./src/xxx.js
* vant/es/show-image-preview/style in ./src/xxx.js
```

Vant 从 4.0 版本开始不再支持 `babel-plugin-import` 插件，请参考 [迁移指南](https://develop365.gitlab.io/vant/zh-CN/migrate-from-v3#yi-chu-babel-plugin-import//vant/zh-CN/migrate-from-v3) 移除该插件。