Vant4 Swipe 輪播

介紹

用于循環(huán)播放一組圖片或內(nèi)容。

引入

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

import { createApp } from 'vue';
import { Swipe, SwipeItem } from 'vant';

const app = createApp();
app.use(Swipe);
app.use(SwipeItem);

代碼演示

基礎(chǔ)用法

每個 SwipeItem 代表一張輪播卡片，可以通過 ?autoplay? 屬性設(shè)置自動輪播的間隔。

<van-swipe class="my-swipe" :autoplay="3000" indicator-color="white">
  <van-swipe-item>1</van-swipe-item>
  <van-swipe-item>2</van-swipe-item>
  <van-swipe-item>3</van-swipe-item>
  <van-swipe-item>4</van-swipe-item>
</van-swipe>

<style>
  .my-swipe .van-swipe-item {
    color: #fff;
    font-size: 20px;
    line-height: 150px;
    text-align: center;
    background-color: #39a9ed;
  }
</style>

懶加載

當(dāng) Swipe 中含有圖片時，可以通過 ?lazy-render? 屬性來開啟懶加載模式。在懶加載模式下，只會渲染當(dāng)前頁和下一頁。

<van-swipe :autoplay="3000" lazy-render>
  <van-swipe-item v-for="image in images" :key="image">
    <img :src="image" />
  </van-swipe-item>
</van-swipe>

export default {
  setup() {
    const images = [
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
    ];
    return { images };
  },
};

監(jiān)聽 change 事件

在每一頁輪播結(jié)束后，會觸發(fā) ?change? 事件。

<van-swipe @change="onChange">
  <van-swipe-item>1</van-swipe-item>
  <van-swipe-item>2</van-swipe-item>
  <van-swipe-item>3</van-swipe-item>
  <van-swipe-item>4</van-swipe-item>
</van-swipe>

import { showToast } from 'vant';

export default {
  setup() {
    const onChange = (index) => showToast('當(dāng)前 Swipe 索引：' + index);
    return { onChange };
  },
};

縱向滾動

設(shè)置 ?vertical? 屬性后滑塊會縱向排列，此時需要指定滑塊容器的高度。

<van-swipe style="height: 200px;" vertical>
  <van-swipe-item>1</van-swipe-item>
  <van-swipe-item>2</van-swipe-item>
  <van-swipe-item>3</van-swipe-item>
  <van-swipe-item>4</van-swipe-item>
</van-swipe>

自定義滑塊大小

滑塊默認寬度為 ?100%?，可以通過 ?widt?h 屬性設(shè)置單個滑塊的寬度?？v向滾動模式下，可以通過 ?height? 屬性設(shè)置單個滑塊的高度。

<van-swipe :loop="false" :width="300">
  <van-swipe-item>1</van-swipe-item>
  <van-swipe-item>2</van-swipe-item>
  <van-swipe-item>3</van-swipe-item>
  <van-swipe-item>4</van-swipe-item>
</van-swipe>

目前不支持在循環(huán)滾動模式下自定義滑塊大小，因此需要將 loop 設(shè)置為 false。

自定義指示器

通過 ?indicator? 插槽可以自定義指示器的樣式。

<van-swipe>
  <van-swipe-item>1</van-swipe-item>
  <van-swipe-item>2</van-swipe-item>
  <van-swipe-item>3</van-swipe-item>
  <van-swipe-item>4</van-swipe-item>
  <template #indicator="{ active, total }">
    <div class="custom-indicator">{{ active + 1 }}/{{ total }}</div>
  </template>
</van-swipe>

<style>
  .custom-indicator {
    position: absolute;
    right: 5px;
    bottom: 5px;
    padding: 2px 5px;
    font-size: 12px;
    background: rgba(0, 0, 0, 0.1);
  }
</style>

API

Swipe Props

Swipe Events

SwipeItem Events

Swipe 方法

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

類型定義

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

import type { SwipeProps, SwipeInstance, SwipeToOptions } from 'vant';

?SwipeInstance? 是組件實例的類型，用法如下：

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

const swipeRef = ref<SwipeInstance>();

swipeRef.value?.next();

SwipeToOptions 格式

Swipe Slots

主題定制

樣式變量

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

常見問題

滑動輪播時為什么觸發(fā)了 click 事件？

這種情況通常是由于項目中引入了 ?fastclick? 庫導(dǎo)致的。?fastclick? 的原理是通過 Touch 事件模擬出 click 事件，而 Swipe 內(nèi)部默認會阻止 touchmove 事件冒泡，干擾了 fastclick 的判斷，導(dǎo)致出現(xiàn)這個問題。

將 Swipe 組件的 stop-propagation 屬性設(shè)置為 false 即可避免該問題。

在桌面端無法操作組件？

參見桌面端適配。

Swipe 組件功能太少，無法實現(xiàn)復(fù)雜效果？

Vant 中的 Swipe 組件是比較輕量的，因此功能也比較基礎(chǔ)。如果需要更復(fù)雜的輪播效果，推薦使用社區(qū)里一些優(yōu)質(zhì)的輪播庫，比如 vue-awesome-swiper。

組件從隱藏狀態(tài)切換到顯示狀態(tài)時，無法正確渲染？

Swipe 組件在掛載時，會獲取自身的寬度，并計算出輪播圖的位置。如果組件一開始處于隱藏狀態(tài)，則獲取到的寬度永遠為 0，因此無法正確計算位置。

解決方法

方法一，如果是使用 ?v-show? 來控制組件展示的，則替換為 ?v-if? 即可解決此問題：

<!-- Before -->
<van-swipe v-show="show" />
<!-- After -->
<van-swipe v-if="show" />

方法二，調(diào)用組件的 resize 方法來主動觸發(fā)重繪：

<van-swipe v-show="show" ref="swipe" />

this.$refs.swipe.resize();