介紹

圖片放大預(yù)覽，支持組件調(diào)用和函數(shù)調(diào)用兩種方式。

引入

通過(guò)以下方式來(lái)全局注冊(cè)組件，更多注冊(cè)方式請(qǐng)參考組件注冊(cè)。

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

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

函數(shù)調(diào)用

為了便于使用 ?ImagePreview?，Vant 提供了一系列輔助函數(shù)，通過(guò)輔助函數(shù)可以快速喚起全局的圖片預(yù)覽組件。

比如使用 ?showImagePreview? 函數(shù)，調(diào)用后會(huì)直接在頁(yè)面中渲染對(duì)應(yīng)的圖片預(yù)覽組件。

import { showImagePreview } from 'vant';

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

代碼演示

基礎(chǔ)用法

在調(diào)用 ?showImagePreview? 時(shí)，直接傳入圖片數(shù)組，即可展示圖片預(yù)覽。

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? 支持傳入配置對(duì)象，并通過(guò) ?startPosition? 選項(xiàng)指定圖片的初始位置（索引值）。

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,
});

展示關(guān)閉按鈕

設(shè)置 ?closeable? 屬性后，會(huì)在彈出層的右上角顯示關(guān)閉圖標(biāo)，并且可以通過(guò) ?close-icon? 屬性自定義圖標(biāo)，使用?close-icon-position? 屬性可以自定義圖標(biāo)位置。

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,
});

監(jiān)聽關(guān)閉事件

通過(guò) ?onClose? 選項(xiàng)監(jiān)聽圖片預(yù)覽的關(guān)閉事件。

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('關(guān)閉');
  },
});

異步關(guān)閉

通過(guò) ?beforeClose? 屬性可以攔截關(guān)閉行為。

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(() => {
  // 調(diào)用實(shí)例上的 close 方法手動(dòng)關(guān)閉圖片預(yù)覽
  instance.close();
}, 2000);

使用 ImagePreview 組件

如果需要在 ImagePreview 內(nèi)嵌入組件或其他自定義內(nèi)容，可以直接使用 ImagePreview 組件，并使用 ?index? 插槽進(jìn)行定制。使用前需要通過(guò) ?app.use? 等方式注冊(cè)組件。

<van-image-preview v-model:show="show" :images="images" @change="onChange">
  <template v-slot:index>第{{ index }}頁(yè)</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 插槽

當(dāng)以組件調(diào)用的方式使用 ImagePreview 時(shí)，可以通過(guò) ?image? 插槽來(lái)插入自定義的內(nèi)容，比如展示一個(gè)視頻內(nèi)容。

<van-image-preview v-model:show="show" :images="images">
  <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,
    };
  },
};

API

方法

Vant 中導(dǎo)出了以下 ImagePreview 相關(guān)的輔助函數(shù)：

ImagePreviewOptions

調(diào)用 ?showImagePreview? 方法時(shí)，支持傳入以下選項(xiàng)：

Props

通過(guò)組件調(diào)用 ?ImagePreview? 時(shí)，支持以下 Props：

Events

通過(guò)組件調(diào)用 ?ImagePreview? 時(shí)，支持以下事件：

方法

通過(guò)組件調(diào)用 ?ImagePreview? 時(shí)，通過(guò) ref 可以獲取到 ImagePreview 實(shí)例并調(diào)用實(shí)例方法，詳見組件實(shí)例方法。

類型定義

組件導(dǎo)出以下類型定義：

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

?ImagePreviewInstance? 是組件實(shí)例的類型，用法如下：

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

const imagePreviewRef = ref<ImagePreviewInstance>();

imagePreviewRef.value?.swipeTo(1);

Slots

通過(guò)組件調(diào)用 ?ImagePreview? 時(shí)，支持以下插槽：

onClose 回調(diào)參數(shù)

onScale 回調(diào)參數(shù)

主題定制

樣式變量

組件提供了下列 CSS 變量，可用于自定義樣式，使用方法請(qǐng)參考 ConfigProvider 組件。

常見問(wèn)題

在桌面端無(wú)法操作組件？

參見桌面端適配。

引用 showImagePreview 時(shí)出現(xiàn)編譯報(bào)錯(cuò)？

如果引用 ?showImagePreview? 方法時(shí)出現(xiàn)以下報(bào)錯(cuò)，說(shuō)明項(xiàng)目中使用了 ?babel-plugin-import? 插件，導(dǎo)致代碼被錯(cuò)誤編譯。

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? 插件，請(qǐng)參考 遷移指南 移除該插件。