Vant4 ImagePreview 圖片預覽

介紹

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

引入

通過以下方式來全局注冊組件，更多注冊方式請參考組件注冊。

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

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

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

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

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

import { showImagePreview } from 'vant';

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

代碼演示

基礎用法

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

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

展示關(guān)閉按鈕

設置 ?closeable? 屬性后，會在彈出層的右上角顯示關(guān)閉圖標，并且可以通過 ?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,
});

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

通過 ?onClose? 選項監(jiān)聽圖片預覽的關(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)閉

通過 ?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)用實例上的 close 方法手動關(guān)閉圖片預覽
  instance.close();
}, 2000);

使用 ImagePreview 組件

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

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

當以組件調(diào)用的方式使用 ImagePreview 時，可以通過 ?image? 插槽來插入自定義的內(nèi)容，比如展示一個視頻內(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 中導出了以下 ImagePreview 相關(guān)的輔助函數(shù)：

ImagePreviewOptions

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

Props

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

Events

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

方法

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

類型定義

組件導出以下類型定義：

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

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

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

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

主題定制

樣式變量

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

常見問題

在桌面端無法操作組件？

參見桌面端適配。

引用 showImagePreview 時出現(xiàn)編譯報錯？

如果引用 ?showImagePreview? 方法時出現(xiàn)以下報錯，說明項目中使用了 ?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? 插件，請參考 遷移指南 移除該插件。