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自动轮播间隔,单位为 msnumber | string-
duration动画时长,单位为 msnumber | string500
initial-swipe初始位置索引值number | string0
width滑块宽度,单位为 pxnumber | stringauto
height滑块高度,单位为 pxnumber | stringauto
loop是否开启循环播放booleantrue
show-indicators是否显示指示器booleantrue
vertical是否为纵向滚动booleanfalse
touchable是否可以通过手势滑动booleantrue
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-size12rpx-
--z-swipe-indicator-marginvar(--z-padding-sm)-
--z-swipe-indicator-active-opacity1-
--z-swipe-indicator-inactive-opacity0.3-
--z-swipe-indicator-active-backgroundvar(--z-primary-color)-
--z-swipe-indicator-inactive-backgroundvar(--z-border-color)-