Swipe 轮播
介绍
用于循环播放一组图片或内容。
代码演示
基础用法
每个 SwipeItem 代表一张轮播卡片,可以通过 indicator-color
属性设置指示器颜色。
<z-swipe indicator-color="#ffffff">
<z-swipe-item
v-for="(item, index) in 4"
:key="index"
:custom-style="customStyle"
>{{ item }}</z-swipe-item
>
</z-swipe>
import { ref } from 'vue'
const customStyle = ref({
color: '#ffffff',
'font-size': '40rpx',
'line-height': '300rpx',
'text-align': 'center',
'background-color': '#39a9ed'
})
自动播放
可以通过 autoplay
属性设置自动轮播的间隔。
<z-swipe autoplay="1000" indicator-color="#ffffff">
<z-swipe-item
v-for="(item, index) in 4"
:key="index"
:custom-style="customStyle"
>{{ item }}</z-swipe-item
>
</z-swipe>
import { ref } from 'vue'
const customStyle = ref({
color: '#ffffff',
'font-size': '40rpx',
'line-height': '300rpx',
'text-align': 'center',
'background-color': '#39a9ed'
})
监听 change 事件
在每一页轮播结束后,会触发 change
事件。
<z-swipe @change="onChange">
<z-swipe-item
v-for="(item, index) in 4"
:key="index"
:custom-style="customStyle"
>{{ item }}</z-swipe-item
>
</z-swipe>
const onChange = (index: number) => console.log('当前 Swipe 索引:' + index)
纵向滚动
设置 vertical
属性后滑块会纵向排列,此时需要指定滑块容器的高度。
<z-swipe
vertical
indicator-color="#ffffff"
:custom-style="{ height: '300rpx' }"
>
<z-swipe-item
v-for="(item, index) in 4"
:key="index"
:custom-style="customStyle"
>{{ item }}</z-swipe-item
>
</z-swipe>
自定义滑块大小
滑块默认宽度为 100%
,可以通过 width
属性设置单个滑块的宽度。纵向滚动模式下,可以通过 height
属性设置单个滑块的高度。
<z-swipe :loop="false" :width="200">
<z-swipe-item
v-for="(item, index) in 4"
:key="index"
:custom-style="customStyle"
>{{ item }}</z-swipe-item
>
</z-swipe>
目前不支持在循环滚动模式下自定义滑块大小,因此需要将 loop 设置为 false。
自定义指示器
通过 indicator
插槽可以自定义指示器的样式。
<z-swipe :show-indicators="false">
<z-swipe-item
v-for="(item, index) in 4"
:key="index"
:custom-style="customStyle"
>{{ item }}</z-swipe-item
>
<template #indicator="{ active, total }">
<view class="custom-indicator">{{ active + 1 }}/{{ total }}</view>
</template>
</z-swipe>
<style>
.custom-indicator {
position: absolute;
right: 10rpx;
bottom: 10rpx;
padding: 4rpx 10rpx;
font-size: 24rpx;
color: #fff;
background: rgb(0 0 0 / 10%);
}
</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 |
indicator-color | 指示器颜色 | string | #1989fa |
Swipe Events
事件名 | 说明 | 回调参数 |
---|---|---|
change | 每一页轮播结束后触发 | index: number |
drag-start | 当用户开始拖动轮播组件时触发 | |
drag-end | 当用户结束拖动轮播组件时触发 |
SwipeItem Events
事件名 | 说明 | 回调参数 |
---|---|---|
click | 点击时触发 | event: MouseEvent |
Swipe 方法
通过 ref 可以获取到 Swipe 实例并调用实例方法。
方法名 | 说明 | 参数 | 返回值 |
---|---|---|---|
prev | 切换到上一轮播 | - | - |
next | 切换到下一轮播 | - | - |
swipeTo | 切换到指定位置 | index: number, options: SwipeToOptions | - |
resize | 外层元素大小或组件显示状态变化时,可以调用此方法来触发重绘 | - | - |
SwipeToOptions 格式
名称 | 说明 | 类型 |
---|---|---|
immediate | 是否跳过动画 | boolean |
Swipe Slots
名称 | 说明 | 参数 |
---|---|---|
default | 轮播内容 | - |
indicator | 自定义指示器 | { active: number, total: number } |
主题定制
样式变量
组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件。
名称 | 默认值 | 描述 |
---|---|---|
--z-swipe-indicator-size | 12rpx | - |
--z-swipe-indicator-margin | var(--z-padding-sm) | - |
--z-swipe-indicator-active-opacity | 1 | - |
--z-swipe-indicator-inactive-opacity | 0.3 | - |
--z-swipe-indicator-active-background | var(--z-primary-color) | - |
--z-swipe-indicator-inactive-background | var(--z-border-color) | - |