Swipe 轮播 - Vant 4

Swipe 轮播

介绍

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

引入

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

import { createApp } from'vue'; import { Swipe, SwipeItem } from'vant'; const app = createApp(); app.use(Swipe); app.use(SwipeItem);

代码演示

基础用法

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

懒加载

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

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

监听 change 事件

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

import { showToast } from'vant'; exportdefault { setup() { constonChange = (index) => showToast('当前 Swipe 索引：' + index); return { onChange }; }, };

纵向滚动

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

自定义滑块大小

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

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

自定义指示器

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

API

Swipe Props

参数	说明	类型	默认值
autoplay	自动轮播间隔，单位为 ms	*number	string*
duration	动画时长，单位为 ms	*number	string*
initial-swipe	初始位置索引值	*number	string*
width	滑块宽度，单位为 px	*number	string*
height	滑块高度，单位为 px	*number	string*
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: number
drag-start v4.0.9	当用户开始拖动轮播组件时触发	{ index: number }
drag-end v4.0.9	当用户结束拖动轮播组件时触发	{ index: number }

SwipeItem Events

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

Swipe 方法

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

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

类型定义

组件导出以下类型定义：

importtype { SwipeProps, SwipeInstance, SwipeToOptions } from'vant';

SwipeInstance 是组件实例的类型，用法如下：

import { ref } from'vue'; importtype { SwipeInstance } from'vant'; const swipeRef = ref<SwipeInstance>(); swipeRef.value?.next();

SwipeToOptions 格式

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

Swipe Slots

名称	说明	参数
default	轮播内容	-
indicator	自定义指示器	{ active: number, total: 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	var(--van-primary-color)	-
--van-swipe-indicator-inactive-background	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 即可解决此问题：

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

this.$refs.swipe.resize();