用于循环播放一组图片或内容。
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
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://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg",
"https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg",
];
return { images };
},
};
在每一页轮播结束后,会触发 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("当前 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%
,可以通过 widt
h 属性设置单个滑块的宽度。纵向滚动模式下,可以通过 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, 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>
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
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
|
事件名 | 说明 | 回调参数 |
---|---|---|
change | 每一页轮播结束后触发 | index, 当前页的索引 |
事件名 | 说明 | 回调参数 |
---|---|---|
click | 点击时触发 | event: MouseEvent |
通过 ref 可以获取到 Swipe 实例并调用实例方法,详见组件实例方法。
方法名 | 说明 | 参数 | 返回值 |
---|---|---|---|
prev | 切换到上一轮播 | - | - |
next | 切换到下一轮播 | - | - |
swipeTo | 切换到指定位置 | index: number, options: SwipeToOptions | - |
resize | 外层元素大小或组件显示状态变化时,可以调用此方法来触发重绘 | - | - |
组件导出以下类型定义:
import type { SwipeProps, SwipeInstance, SwipeToOptions } from "vant";
SwipeInstance
是组件实例的类型,用法如下:
import { ref } from "vue";
import type { SwipeInstance } from "vant";
const swipeRef = ref<SwipeInstance>();
swipeRef.value?.next();
名称 | 说明 | 类型 |
---|---|---|
immediate | 是否跳过动画 | boolean |
名称 | 说明 | 参数 |
---|---|---|
default | 轮播内容 | - |
indicator v3.4.0
|
自定义指示器 | { 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) | - |
这种情况通常是由于项目中引入了 fastclick
库导致的。fastclick
的原理是通过 Touch 事件模拟出 click 事件,而 Swipe 内部默认会阻止 touchmove 事件冒泡,干扰了 fastclick 的判断,导致出现这个问题。
将 Swipe 组件的 stop-propagation 属性设置为 false 即可避免该问题。
参见桌面端适配。
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();
介绍提供多个选项集合供用户选择,支持单列选择和多列级联,通常与弹出层组件配合使用。实例演示引入通过以下方式来全局注册组件...
介绍感谢你使用 Vant。以下是关于向 Vant 提交反馈或代码的指南。在向 Vant 提交 issue 或者 PR 之前,请先花几分钟时间阅读以下...