Vant3 Swipe 輪播

介紹

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

實例演示

引入

通過以下方式來全局注冊組件，更多注冊方式請參考組件注冊。import { createApp } from 'vue';

import { Swipe, SwipeItem } from 'vant';

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

代碼演示

基礎用法

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

<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>

懶加載

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

<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://img.yzcdn.cn/vant/apple-1.jpg',
      'https://img.yzcdn.cn/vant/apple-2.jpg',
    ];
    return { images };
  },
};

監(jiān)聽 change 事件

在每一頁輪播結束后，會觸發(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 { Toast } from 'vant';

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

縱向滾動

設置 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%，可以通過 width 屬性設置單個滑塊的寬度?？v向滾動模式下，可以通過 height 屬性設置單個滑塊的高度。

<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 設置為 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 }">
    <div class="custom-indicator">{{ active + 1 }}/4</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 實例并調用實例方法，詳見組件實例方法。

類型定義

通過 SwipeInstance 獲取 Swipe 實例的類型定義。

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

const swipeRef = ref<SwipeInstance>();

swipeRef.value?.next();

SwipeToOptions 格式

Swipe Slots

樣式變量

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

常見問題

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

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

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

在桌面端無法操作組件？

參見桌面端適配。

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

Vant 中的 Swipe 組件是比較輕量的，因此功能也比較基礎。如果需要更復雜的輪播效果，推薦使用社區(qū)里一些優(yōu)質的輪播庫，比如 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" />

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

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

this.$refs.swipe.resize();