Vant3 ImagePreview 圖片預(yù)覽

2021-09-14 11:22 更新

介紹

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

實(shí)例演示

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

ImagePreview 是一個(gè)函數(shù),調(diào)用函數(shù)后會(huì)直接在頁面中展示圖片預(yù)覽界面。

import { ImagePreview } from 'vant';

ImagePreview(['https://img.yzcdn.cn/vant/apple-1.jpg']);

組件調(diào)用

通過組件調(diào)用 ImagePreview 時(shí),可以通過下面的方式進(jìn)行注冊(cè)。

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

// 全局注冊(cè)
const app = createApp();
app.use(ImagePreview);

// 局部注冊(cè)
export default {
  components: {
    [ImagePreview.Component.name]: ImagePreview.Component,
  },
};

代碼演示

基礎(chǔ)用法

直接傳入圖片數(shù)組,即可展示圖片預(yù)覽。

ImagePreview([
  'https://img.yzcdn.cn/vant/apple-1.jpg',
  'https://img.yzcdn.cn/vant/apple-2.jpg',
]);

指定初始位置

ImagePreview 支持傳入配置對(duì)象,并通過 startPosition 選項(xiàng)指定圖片的初始位置(索引值)。

ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  startPosition: 1,
});

展示關(guān)閉按鈕

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

ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  closeable: true,
});

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

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

import { Toast } from 'vant';

ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  onClose() {
    Toast('關(guān)閉');
  },
});

異步關(guān)閉

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

const instance = ImagePreview({
  images: [
    'https://img.yzcdn.cn/vant/apple-1.jpg',
    'https://img.yzcdn.cn/vant/apple-2.jpg',
  ],
  beforeClose: () => false,
});

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

組件調(diào)用

如果需要在圖片預(yù)覽內(nèi)嵌入組件或其他自定義內(nèi)容,可以使用組件調(diào)用的方式,調(diào)用前需要通過 app.use 注冊(cè)組件。

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

API

Options

通過函數(shù)調(diào)用 ImagePreview 時(shí),支持傳入以下選項(xiàng):

參數(shù)名 說明 類型 默認(rèn)值
images 需要預(yù)覽的圖片 URL 數(shù)組 string[] []
startPosition 圖片預(yù)覽起始位置索引 number | string 0
swipeDuration 動(dòng)畫時(shí)長(zhǎng),單位為 ms number | string 300
showIndex 是否顯示頁碼 boolean true
showIndicators 是否顯示輪播指示器 boolean false
loop 是否開啟循環(huán)播放 boolean true
onClose 關(guān)閉時(shí)的回調(diào)函數(shù) Function -
onChange 切換圖片時(shí)的回調(diào)函數(shù),回調(diào)參數(shù)為當(dāng)前索引 Function -
onScale 縮放圖片時(shí)的回調(diào)函數(shù),回調(diào)參數(shù)為當(dāng)前索引和當(dāng)前縮放值組成的對(duì)象 Function -
beforeClose 關(guān)閉前的回調(diào)函數(shù),返回 false 可阻止關(guān)閉,支持返回 Promise (active: number) => boolean | Promise<boolean> -
closeOnPopstate 是否在頁面回退時(shí)自動(dòng)關(guān)閉 boolean true
className 自定義類名 string | Array | object -
maxZoom 手勢(shì)縮放時(shí),最大縮放比例 number | string 3
minZoom 手勢(shì)縮放時(shí),最小縮放比例 number | string 1/3
closeable 是否顯示關(guān)閉圖標(biāo) boolean false
closeIcon 關(guān)閉圖標(biāo)名稱或圖片鏈接 string clear
closeIconPosition 關(guān)閉圖標(biāo)位置,可選值為 top-left
bottom-left bottom-right
string top-right
transition v3.0.8 動(dòng)畫類名,等價(jià)于 transition 的 name 屬性 string van-fade
overlay-style v3.0.8 自定義遮罩層樣式 object -
teleport 指定掛載的節(jié)點(diǎn),等同于 Teleport 組件的 to 屬性 string | Element -

Props

通過組件調(diào)用 ImagePreview 時(shí),支持以下 Props:

參數(shù) 說明 類型 默認(rèn)值
v-model:show 是否展示圖片預(yù)覽 boolean false
images 需要預(yù)覽的圖片 URL 數(shù)組 string[] []
start-position 圖片預(yù)覽起始位置索引 number | string 0
swipe-duration 動(dòng)畫時(shí)長(zhǎng),單位為 ms number | string 300
show-index 是否顯示頁碼 boolean true
show-indicators 是否顯示輪播指示器 boolean false
loop 是否開啟循環(huán)播放 boolean true
before-close 關(guān)閉前的回調(diào)函數(shù),返回 false 可阻止關(guān)閉,支持返回 Promise (active: number) => boolean | Promise<boolean> -
close-on-popstate 是否在頁面回退時(shí)自動(dòng)關(guān)閉 boolean true
class-name 自定義類名 string | Array | object -
max-zoom 手勢(shì)縮放時(shí),最大縮放比例 number | string 3
min-zoom 手勢(shì)縮放時(shí),最小縮放比例 number | string 1/3
closeable 是否顯示關(guān)閉圖標(biāo) boolean false
close-icon 關(guān)閉圖標(biāo)名稱或圖片鏈接 string clear
close-icon-position 關(guān)閉圖標(biāo)位置,可選值為 top-left
bottom-left bottom-right
string top-right
transition v3.0.8 動(dòng)畫類名,等價(jià)于 transition 的 name 屬性 string van-fade
overlay-style v3.0.8 自定義遮罩層樣式 object -
teleport 指定掛載的節(jié)點(diǎn),等同于 Teleport 組件的 to 屬性 string | Element -

Events

通過組件調(diào)用 ImagePreview 時(shí),支持以下事件:

事件 說明 回調(diào)參數(shù)
close 關(guān)閉時(shí)觸發(fā) { index: 索引, url: 圖片鏈接 }
closed 關(guān)閉且且動(dòng)畫結(jié)束后觸發(fā) -
change 切換當(dāng)前圖片時(shí)觸發(fā) index: 當(dāng)前圖片的索引
scale 縮放當(dāng)前圖片時(shí)觸發(fā) { index: 當(dāng)前圖片的索引, scale: 當(dāng)前縮放的值 }

方法

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

方法名 說明 參數(shù) 返回值
swipeTo 2.9.0 切換到指定位置 index: number, options: Options -

Slots

通過組件調(diào)用 ImagePreview 時(shí),支持以下插槽:

名稱 說明 參數(shù)
index 自定義頁碼內(nèi)容 { index: 當(dāng)前圖片的索引 }
cover 自定義覆蓋在圖片預(yù)覽上方的內(nèi)容 -

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

參數(shù)名 說明 類型
url 當(dāng)前圖片 URL string
index 當(dāng)前圖片的索引值 number

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

參數(shù)名 說明 類型
index 當(dāng)前圖片的索引值 number
scale 當(dāng)前圖片的縮放值 number

樣式變量

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

名稱 默認(rèn)值 描述
--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 -

常見問題

在桌面端無法操作組件?

參見桌面端適配。

在 JSX 中渲染 ImagePreview 組件無法展示?

請(qǐng)注意 ImagePreview 是一個(gè)函數(shù),ImagePreview.Component 才是 ImagePreview 對(duì)應(yīng)的組件。JSX 調(diào)用圖片預(yù)覽的正確姿勢(shì)如下:

export default {
  setup() {
    const show = ref(false);
    return () => <ImagePreview.Component v-model={[show, 'show']} />;
  },
};


以上內(nèi)容是否對(duì)您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)