Swiper 轮播

介绍

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

基础用法

每个 SwiperItem 组件代表一张轮播卡片，通过 height 属性设置轮播高度。

<vd-swiper :height="200" :vertical="state.vertical" @touchmove.stop.prevent>
  <vd-swiper-item>
    <image src="图片1" mode="aspectFill" style="width:100%;height:100%;" />
  </vd-swiper-item>
  <vd-swiper-item>
    <image src="图片2" mode="aspectFill" style="width:100%;height:100%;" />
  </vd-swiper-item>
  <vd-swiper-item>
    <image src="图片3" mode="aspectFill" style="width:100%;height:100%;" />
  </vd-swiper-item>
</vd-swiper>

纵向滚动

通过 vertical 属性设置纵向滚动。

<vd-swiper :height="200" vertical @touchmove.stop.prevent>
  <vd-swiper-item>1</vd-swiper-item>
  <vd-swiper-item>2</vd-swiper-item>
  <vd-swiper-item>3</vd-swiper-item>
</vd-swiper>

指示器样式

通过 indicator-type 属性设置指示器样式，可选值为 dots dots-bar page。

<vd-swiper :height="200" indicator-type="page" @touchmove.stop.prevent>
  <vd-swiper-item>1</vd-swiper-item>
  <vd-swiper-item>2</vd-swiper-item>
  <vd-swiper-item>3</vd-swiper-item>
</vd-swiper>

指示器位置

通过 indicator-position 属性设置指示器位置，可选值为 bottom bottom-left bottom-right top top-left top-right right right-top right-bottom left left-top left-bottom right。

<vd-swiper
  :height="200"
  indicator-type="page"
  indicator-position="bottom-right"
  @touchmove.stop.prevent
>
  <vd-swiper-item>1</vd-swiper-item>
  <vd-swiper-item>2</vd-swiper-item>
  <vd-swiper-item>3</vd-swiper-item>
</vd-swiper>

自动高度

通过 autosize 属性设置自动高度，设置后切换时会根据下一张卡片的高度自动调整。

<vd-swiper autosize @touchmove.stop.prevent>
  <vd-swiper-item>1</vd-swiper-item>
  <vd-swiper-item>2</vd-swiper-item>
  <vd-swiper-item>3</vd-swiper-item>
</vd-swiper>

卡片式轮播

卡片式轮播由样式实现：容器设置 overflow: visible 并留出左右边距，侧边卡片缩小并降低透明度，激活项通过 SwiperItem 的 is-active 类还原。

<vd-swiper
  custom-class="swiper-card"
  :height="200"
  indicator-type="dots-bar"
  @touchmove.stop.prevent
>
  <vd-swiper-item
    v-for="(src, index) in cardList"
    :key="src"
    :index="index"
  >
    <view class="swiper-card-item">
      <image :src="src" mode="aspectFill" />
    </view>
  </vd-swiper-item>
</vd-swiper>

const cardList = [
  '图片1',
  '图片2',
  '图片3',
];

.swiper-card {
  overflow: visible;
  padding: 0 24px;

  &-item {
    height: 100%;
    border-radius: 12px;
    box-shadow: 0 10px 24px rgba(0, 0, 0, 0.2);
    overflow: hidden;
    transition: transform 0.3s ease, opacity 0.3s ease;
    transform: scale(0.9);
    opacity: 0.7;

    image {
      width: 100%;
      height: 100%;
    }
  }

  :deep(.vd-swiper-item.is-active) {
    z-index: 3;

    .swiper-card-item {
      transform: scale(1);
      opacity: 1;
    }
  }
}

绑定激活项

通过 active 绑定轮播当前的激活索引。

<vd-swiper v-model:active="active" @touchmove.stop.prevent>
  <vd-swiper-item>1</vd-swiper-item>
  <vd-swiper-item>2</vd-swiper-item>
  <vd-swiper-item>3</vd-swiper-item>
</vd-swiper>

const active = ref(0);

API

Swiper Props

参数	说明	类型	默认值
active	激活索引	number	0
height	轮播高度	string | number	-
autosize	是否自适应轮播高度，传入数字可设置高度未计算完成的轮播初始高度	boolean | string | number	true
autosize-begin	自适应高度未计算完成时的初始高度，设置为 -1 时禁用	string | number	0
vertical	是否纵向轮播	boolean	false
autoplay	自动轮播间隔，0 或 false 时禁用	string | number | boolean	5000
duration	切换动画时长	number	500
loop	是否循环播放	boolean	true
swipeable	是否可滑动	boolean	true
swipe-limit	滑动限制	string | number	-
indicator	是否展示指示器	boolean	true
indicator-type	指示器类型	SwiperIndicatorType	dots
indicator-position	指示器位置	SwiperIndicatorPosition	横向滚动：'bottom' 垂直滚动：'right'

SwiperItem Props

参数	说明	类型	默认值
index	索引，小程序下循环列表时需要设置该值	string | number	-

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Swiper Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
change	轮播切换时触发	SwiperOnChangeEvent
update:active	激活索引更新时触发	number

SwiperItem Events

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

Swiper Slots

名称	说明
default	轮播卡片内容
indicator	自定义指示器，作用域参数 active、value、total、data
indicator-page	页码指示器内容

SwiperItem Slots

名称	说明
default	自定义内容

Swiper Expose

方法名	说明	参数	返回值
prev	切换上一个	-	-
next	切换下一个	-	-
swipeTo	切换到指定索引	index: number	-

类型定义

组件导出以下类型定义：

import type {
  SwiperOnChangeEvent,
  SwiperIndicatorType,
  SwiperIndicatorPosition,
  SwiperExpose,
  SwiperInstance,
} from 'vital-design';