介绍
用于循环播放一组图片或内容。
引入
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
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 事件
在每一页轮播结束后,会触发 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="" 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>
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 | 外层元素大小或组件显示状态变化时,可以调用此方法来触发重绘 | – | – |
类型定义
组件导出以下类型定义:
import type { SwipeProps, SwipeInstance, SwipeToOptions } from vant;
SwipeInstance
是组件实例的类型,用法如下:
import { ref } from vue;
import type { SwipeInstance } from vant;
const swipeRef = ref<SwipeInstance>();
swipeRef.value?.next();
SwipeToOptions 格式
名称 | 说明 | 类型 |
---|---|---|
immediate | 是否跳过动画 | boolean |
Swipe Slots
名称 | 说明 | 参数 |
---|---|---|
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) | – |
常见问题
滑动轮播时为什么触发了 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();
作者:冒牌SEO,如若转载,请注明出处:https://www.web176.com/vant4/18889.html