介绍

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

实例演示

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。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 };
  },
};

监听 change 事件

在每一页轮播结束后，会触发 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 属性设置单个滑块的宽度。纵向滚动模式下，可以通过 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>

目前不支持在循环滚动模式下自定义滑块大小，因此需要将 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

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

Swipe Events

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

SwipeItem Events

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

Swipe 方法

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

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

类型定义

通过 SwipeInstance 获取 Swipe 实例的类型定义。

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

const swipeRef = ref<SwipeInstance>();

swipeRef.value?.next();

SwipeToOptions 格式

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

Swipe Slots

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

样式变量

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

名称	默认值	描述
--van-swipe-indicator-size	6px	-
--van-swipe-indicator-margin	var(--van-padding-sm)	-
--van-swipe-indicator-active-opacity	1	-
--van-swipe-indicator-inactive-opacity	0.3	-
--van-swipe-indicator-active-background-color	var(--van-primary-color)	-
--van-swipe-indicator-inactive-background-color	var(--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 即可解决此问题：

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

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

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

this.$refs.swipe.resize();