Swipe 轮播

介绍

用于循环播放一组图片或内容。

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册

  1. import { createApp } from 'vue';
  2. import { Swipe, SwipeItem } from 'vant';
  3. const app = createApp();
  4. app.use(Swipe);
  5. app.use(SwipeItem);

代码演示

基础用法

每个 SwipeItem 代表一张轮播卡片,可以通过 autoplay 属性设置自动轮播的间隔。

  1. <van-swipe class="my-swipe" :autoplay="3000" indicator-color="white">
  2. <van-swipe-item>1</van-swipe-item>
  3. <van-swipe-item>2</van-swipe-item>
  4. <van-swipe-item>3</van-swipe-item>
  5. <van-swipe-item>4</van-swipe-item>
  6. </van-swipe>
  7. <style>
  8. .my-swipe .van-swipe-item {
  9. color: #fff;
  10. font-size: 20px;
  11. line-height: 150px;
  12. text-align: center;
  13. background-color: #39a9ed;
  14. }
  15. </style>

懒加载

当 Swipe 中含有图片时,可以通过 lazy-render 属性来开启懒加载模式。在懒加载模式下,只会渲染当前页和下一页。

  1. <van-swipe :autoplay="3000" lazy-render>
  2. <van-swipe-item v-for="image in images" :key="image">
  3. <img :src="image" />
  4. </van-swipe-item>
  5. </van-swipe>
  1. export default {
  2. setup() {
  3. const images = [
  4. 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
  5. 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  6. ];
  7. return { images };
  8. },
  9. };

监听 change 事件

在每一页轮播结束后,会触发 change 事件。

  1. <van-swipe @change="onChange">
  2. <van-swipe-item>1</van-swipe-item>
  3. <van-swipe-item>2</van-swipe-item>
  4. <van-swipe-item>3</van-swipe-item>
  5. <van-swipe-item>4</van-swipe-item>
  6. </van-swipe>
  1. import { showToast } from 'vant';
  2. export default {
  3. setup() {
  4. const onChange = (index) => showToast('当前 Swipe 索引:' + index);
  5. return { onChange };
  6. },
  7. };

纵向滚动

设置 vertical 属性后滑块会纵向排列,此时需要指定滑块容器的高度。

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

自定义滑块大小

滑块默认宽度为 100%,可以通过 width 属性设置单个滑块的宽度。纵向滚动模式下,可以通过 height 属性设置单个滑块的高度。

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

目前不支持在循环滚动模式下自定义滑块大小,因此需要将 loop 设置为 false。

自定义指示器

通过 indicator 插槽可以自定义指示器的样式。

  1. <van-swipe>
  2. <van-swipe-item>1</van-swipe-item>
  3. <van-swipe-item>2</van-swipe-item>
  4. <van-swipe-item>3</van-swipe-item>
  5. <van-swipe-item>4</van-swipe-item>
  6. <template #indicator="{ active, total }">
  7. <div class="custom-indicator">{{ active + 1 }}/{{ total }}</div>
  8. </template>
  9. </van-swipe>
  10. <style>
  11. .custom-indicator {
  12. position: absolute;
  13. right: 5px;
  14. bottom: 5px;
  15. padding: 2px 5px;
  16. font-size: 12px;
  17. background: rgba(0, 0, 0, 0.1);
  18. }
  19. </style>

API

Swipe Props

参数说明类型默认值
autoplay自动轮播间隔,单位为 msnumber | string-
duration动画时长,单位为 msnumber | string500
initial-swipe初始位置索引值number | string0
width滑块宽度,单位为 pxnumber | stringauto
height滑块高度,单位为 pxnumber | stringauto
loop是否开启循环播放booleantrue
show-indicators是否显示指示器booleantrue
vertical是否为纵向滚动booleanfalse
touchable是否可以通过手势滑动booleantrue
stop-propagation是否阻止滑动事件冒泡booleantrue
lazy-render是否延迟渲染未展示的轮播booleanfalse
indicator-color指示器颜色string#1989fa

Swipe Events

事件名说明回调参数
change每一页轮播结束后触发index, 当前页的索引

SwipeItem Events

事件名说明回调参数
click点击时触发event: MouseEvent

Swipe 方法

通过 ref 可以获取到 Swipe 实例并调用实例方法,详见组件实例方法

方法名说明参数返回值
prev切换到上一轮播--
next切换到下一轮播--
swipeTo切换到指定位置index: number, options: SwipeToOptions-
resize外层元素大小或组件显示状态变化时,可以调用此方法来触发重绘--

类型定义

组件导出以下类型定义:

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

SwipeInstance 是组件实例的类型,用法如下:

  1. import { ref } from 'vue';
  2. import type { SwipeInstance } from 'vant';
  3. const swipeRef = ref<SwipeInstance>();
  4. swipeRef.value?.next();

SwipeToOptions 格式

名称说明类型
immediate是否跳过动画boolean

Swipe Slots

名称说明参数
default轮播内容-
indicator v3.4.0自定义指示器{ active: number, total: number }

主题定制

样式变量

组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件

名称默认值描述
—van-swipe-indicator-size6px-
—van-swipe-indicator-marginvar(—van-padding-sm)-
—van-swipe-indicator-active-opacity1-
—van-swipe-indicator-inactive-opacity0.3-
—van-swipe-indicator-active-backgroundvar(—van-primary-color)-
—van-swipe-indicator-inactive-backgroundvar(—van-border-color)-

常见问题

滑动轮播时为什么触发了 click 事件?

这种情况通常是由于项目中引入了 fastclick 库导致的。fastclick 的原理是通过 Touch 事件模拟出 click 事件,而 Swipe 内部默认会阻止 touchmove 事件冒泡,干扰了 fastclick 的判断,导致出现这个问题。

将 Swipe 组件的 stop-propagation 属性设置为 false 即可避免该问题。

在桌面端无法操作组件?

参见桌面端适配

Swipe 组件功能太少,无法实现复杂效果?

Vant 中的 Swipe 组件是比较轻量的,因此功能也比较基础。如果需要更复杂的轮播效果,推荐使用社区里一些优质的轮播库,比如 vue-awesome-swiper

组件从隐藏状态切换到显示状态时,无法正确渲染?

Swipe 组件在挂载时,会获取自身的宽度,并计算出轮播图的位置。如果组件一开始处于隐藏状态,则获取到的宽度永远为 0,因此无法正确计算位置。

解决方法

方法一,如果是使用 v-show 来控制组件展示的,则替换为 v-if 即可解决此问题:

  1. <!-- Before -->
  2. <van-swipe v-show="show" />
  3. <!-- After -->
  4. <van-swipe v-if="show" />

方法二,调用组件的 resize 方法来主动触发重绘:

  1. <van-swipe v-show="show" ref="swipe" />
  1. this.$refs.swipe.resize();

Swipe 轮播 - 图1