shop-wx/doc/wot-design-uni/docs/component/swiper.md

Swiper 轮播

用于创建轮播，它支持水平和垂直方向的滑动，可以自定义样式和指示器位置，支持视频和图片资源的轮播，支持设置轮播标题和自定义标题样式。

:::danger 请注意 嵌入视频仅在h5、微信小程序和钉钉小程序支持，其余端不支持，请了解后使用。 :::

基础用法

通过设置 autoplay 属性控制轮播图是否自动播放，设置 v-model:current 属性初始化轮播图展示的滑块，监听滑块 click 来处理点击事件，而每一页轮播结束后，会触发 change 事件。

<wd-swiper :list="swiperList" autoplay v-model:current="current" @click="handleClick" @change="onChange"></wd-swiper>

const current = ref<number>(0)

const swiperList = ref([
  'https://wot-ui.cn/assets/redpanda.jpg',
  'https://wot-ui.cn/assets/capybara.jpg',
  'https://wot-ui.cn/assets/panda.jpg',
  'https://wot-ui.cn/assets/moon.jpg',
  'https://wot-ui.cn/assets/meng.jpg'
])
function handleClick(e) {
  console.log(e)
}
function onChange(e) {
  console.log(e)
}

点条状指示器

<wd-swiper :list="swiperList" autoplay v-model:current="current" :indicator="{ type: 'dots-bar' }" @click="handleClick" @change="onChange"></wd-swiper>

数字指示器

<wd-swiper
  :list="swiperList"
  autoplay
  v-model:current="current"
  :indicator="{ type: 'fraction' }"
  indicatorPosition="bottom-right"
  @click="handleClick"
  @change="onChange"
></wd-swiper>

视频轮播1.3.13

:::danger 请注意 嵌入视频仅在h5、微信小程序和钉钉小程序支持，其余端不支持，请了解后使用。 :::

<wd-swiper :list="videoList" autoplay :indicator="false" indicator-position="bottom-right"></wd-swiper>

const videoList = ref([
  'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_115503.mp4',
  'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_150752.mp4',
  'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_155516.mp4',
  'https://wot-ui.cn/assets/moon.jpg'
])

手动播放视频

<wd-swiper :list="videoList" autoplay :autoplayVideo="false" :indicator="{ type: 'fraction' }" indicator-position="top-right"></wd-swiper>

const videoList = ref([
  'https://unpkg.com/wot-design-uni-assets/VID_115503.mp4',
  'https://unpkg.com/wot-design-uni-assets/VID_150752.mp4',
  'https://unpkg.com/wot-design-uni-assets/VID_155516.mp4'
])

播放视频时停止轮播

<wd-swiper
  :list="videoList"
  autoplay
  stopAutoplayWhenVideoPlay
  :autoplayVideo="false"
  :indicator="{ type: 'fraction' }"
  indicator-position="top-right"
></wd-swiper>

const videoList = ref([
  'https://unpkg.com/wot-design-uni-assets/VID_115503.mp4',
  'https://unpkg.com/wot-design-uni-assets/VID_150752.mp4',
  'https://unpkg.com/wot-design-uni-assets/VID_155516.mp4'
])

手动切换

<wd-swiper
  :list="swiperList"
  :autoplay="false"
  v-model:current="current"
  :indicator="{ showControls: true }"
  :loop="false"
  @click="handleClick"
  @change="onChange"
></wd-swiper>

卡片样式

设置 previousMargin 和 nextMargin 实现卡片轮播的样式。

<view class="card-swiper">
  <wd-swiper
    autoplay
    v-model:current="current"
    custom-indicator-class="custom-indicator-class"
    custom-image-class="custom-image"
    custom-next-image-class="custom-image-prev"
    custom-prev-image-class="custom-image-prev"
    :indicator="{ type: 'dots' }"
    :list="swiperList"
    previousMargin="24px"
    nextMargin="24px"
  ></wd-swiper>
</view>

.card-swiper {
  --wot-swiper-radius: 0;
  --wot-swiper-item-padding: 0 24rpx;
  --wot-swiper-nav-dot-color: #e7e7e7;
  --wot-swiper-nav-dot-active-color: #4d80f0;
  padding-bottom: 24rpx;
  :deep(.custom-indicator-class) {
    bottom: -16px;
  }
  :deep(.custom-image) {
    border-radius: 12rpx;
  }
  :deep(.custom-image-prev) {
    height: 168px !important;
  }
}

同时展示 2 个滑块

设置 display-multiple-items 属性，控制同时展示的滑块数量。

<view class="card-swiper">
  <wd-swiper
    autoplay
    v-model:current="current"
    :display-multiple-items="2"
    custom-indicator-class="custom-indicator-class"
    custom-image-class="custom-image"
    custom-next-image-class="custom-image-prev"
    custom-prev-image-class="custom-image-prev"
    :indicator="{ type: 'dots' }"
    :list="swiperList"
    previousMargin="24px"
    nextMargin="24px"
  ></wd-swiper>
</view>

.card-swiper {
  --wot-swiper-radius: 0;
  --wot-swiper-item-padding: 0 24rpx;
  --wot-swiper-nav-dot-color: #e7e7e7;
  --wot-swiper-nav-dot-active-color: #4d80f0;
  padding-bottom: 24rpx;
  :deep(.custom-indicator-class) {
    bottom: -16px;
  }
  :deep(.custom-image) {
    border-radius: 12rpx;
  }
  :deep(.custom-image-prev) {
    height: 168px !important;
  }
}

垂直方向

direction 设置为 vertical 后滑块会纵向排列。

<wd-swiper
  :list="swiperList"
  direction="vertical"
  indicatorPosition="right"
  autoplay
  v-model:current="current"
  :indicator="{ type: 'dots-bar' }"
  @click="handleClick"
  @change="onChange"
></wd-swiper>

自定义指示器

通过 indicator 插槽可以自定义指示器的样式。

<wd-swiper :list="swiperList" direction="vertical" indicatorPosition="right" autoplay v-model:current="current" @click="handleClick" @change="onChange">
  <template #indicator="{ current, total }">
    <view class="custom-indicator" style="position: absolute; bottom: 24rpx; right: 24rpx">{{ current + 1 }}/{{ total }}</view>
  </template>
</wd-swiper>

.custom-indicator {
  padding: 0 12rpx;
  height: 48rpx;
  line-height: 48rpx;
  border-radius: 45%;
  background: rgba(0, 0, 0, 0.6);
  color: #ffffff;
  font-size: 24rpx;
}

指定valueKey和textKey

通过value-key 属性指定 list 中每个对象图片地址字段，默认为 value。

通过text-key 属性指定 list 中每个对象标题字段，默认为 text。 :::tip 提示 当前swiper提供的标题样式为顶部靠右，如需自定义样式，请使用外部样式类customTextClass或者自定义样式customTextStyle，使用text-key时请确认你的组件库版本是否包含此功能。 :::

<wd-swiper value-key="url" text-key="title" :custom-text-style="color:#fff" :list="customSwiperList" autoplay v-model:current="current" @click="handleClick" @change="onChange"></wd-swiper>

const current = ref<number>(0)

const customSwiperList = ref([
  { url: 'https://wot-ui.cn/assets/redpanda.jpg', title: '小熊猫！' },
  { url: 'https://wot-ui.cn/assets/capybara.jpg', title: '卡！皮！巴！拉！' },
  { url: 'https://wot-ui.cn/assets/panda.jpg', title: '大熊猫！' },
  { url: 'https://wot-ui.cn/assets/moon.jpg', title: '诗画中国！' }
])

:deep(.customTextClass) {
  position: absolute;
  top: 24rpx;
  right: 24rpx;
  color: #ffffff;
  font-size: 24rpx;
  text-shadow: 0 0 8rpx #000000;
}

属性控制切换

<wd-swiper :loop="isLoop" :autoplay="false" :list="swiperList" v-model:current="current" />
<wd-gap />
<wd-cell-group>
  <wd-cell title="loop">
    <wd-switch v-model="isLoop" size="24px" />
  </wd-cell>
  <wd-cell title="current" :value="current.toString()" />
</wd-cell-group>
<view style="display: flex; justify-content: space-between">
  <wd-button @click="current--">prev</wd-button>
  <wd-button type="success" @click="current++">next</wd-button>
</view>

const current = ref <number>(0)
const isLoop = ref(false)

插槽用法

通过默认插槽可以自定义轮播项的内容。

<wd-swiper
  :list="swiperList"
  autoplay
  v-model:current="current"
  :indicator="{ type: 'dots-bar' }"
  @click="handleClick"
  @change="onChange"
>
  <template #default="{ item }">
    <image :src="item as string" mode="aspectFill" style="width: 100%; height: 100%" />
  </template>
</wd-swiper>

Attributes

参数	说明	类型	可选值	默认值	最低版本
autoplay	是否自动播放	boolean	-	true	0.1.22
v-model:current	控制当前轮播在哪一项（下标）	number	-	0	0.1.22
direction	轮播滑动方向	DirectionType	horizontal, vertical	horizontal	0.1.22
displayMultipleItems	同时显示的滑块数量	number	-	1	0.1.22
duration	滑动动画时长	number	-	300	0.1.22
easingFunction	切换缓动动画类型（微信小程序、快手小程序、京东小程序）	EasingType	-	default	0.1.22
height	轮播的高度	string / number	-	192	0.1.22
interval	轮播间隔时间	number	-	5000	0.1.22
list	图片列表	string[] / SwiperList[]	-	-	0.1.22
loop	是否循环播放	boolean	-	true	0.1.22
nextMargin	后边距	string / number	-	0	0.1.22
indicatorPosition	指示器展示位置	IndicatorPositionType	left, top-left, top, top-right, bottom-left, bottom, bottom-right, right	bottom	0.1.22
previousMargin	前边距	string / number	-	0	0.1.22
snapToEdge	边距是否应用到第一个、最后一个元素	boolean	-	false	0.1.22
indicator	指示器全部配置	SwiperIndicatorProps / boolean	-	true	0.1.22
imageMode	图片裁剪、缩放的模式	string	参考官方文档mode	aspectFill	0.1.55
autoplayVideo	视频是否自动播放，默认自动播放	boolean	-	true	1.3.13
stopPreviousVideo	切换轮播项时是否停止上一个视频的播放，默认切换时停止播放上一个视频	boolean	-	true	1.3.13
stopAutoplayWhenVideoPlay	视频播放时是否停止自动轮播	boolean	-	false	1.3.13
customStyle	外部自定义样式	string	-	''	0.1.22
value-key	选项对象中，value 对应的 key	string	-	value	1.3.7
text-key	选项对象中，标题 text 对应的 key	string	-	text	1.3.13
adjust-height	自动以指定滑块的高度为整个容器的高度。当 vertical 为 true 时，默认不调整，仅支付宝小程序支持。	string	'first' / 'current' / 'highest' / 'none'	highest	1.3.13
adjust-vertical-height	vertical 为 true 时强制使 adjust-height 生效。仅支付宝小程序支持。	boolean	-	false	1.3.13
｜ muted	视频是否静音播放	boolean	-	true	1.6.0
videoLoop	视频是否循环播放	boolean	-	true	1.6.0

DirectionType

轮播滑动方向，可选值为 'horizontal' 和 'vertical'。

EasingType

切换缓动动画类型，可选值为 'default'、'linear'、'easeInCubic'、'easeOutCubic' 和 'easeInOutCubic'。

IndicatorPositionType

页码信息展示位置，可选值为 'left'、'top-left'、'top'、'top-right'、'bottom-left'、'bottom'、'bottom-right' 和 'right'。

SwiperList

轮播图项的列表配置，包括 图片或视频地址value、视频封面poster 、文件资源的类型type等属性，支持扩展属性。指定type后组件将不在内部判断文件类型，以type为准。

name	说明	最低版本
value	图片或视频地址	-
poster	视频封面	-
type	用于指定文件资源的类型，可选值image、video	1.4.0

SwiperIndicatorProps

参数	说明	类型	可选值	默认值	最低版本
current	当前轮播在哪一项（下标）	Number	-	0	0.1.22
direction	轮播滑动方向	DirectionType	horizontal, vertical	horizontal	0.1.22
min-show-num	小于这个数字不会显示导航器	Number	-	2	0.1.22
参数	说明	类型	可选值	默认值	最低版本
-------------------	--------------------------	---------------------	--------------------------------------------------------------------------	----------	--------
current	当前轮播在哪一项（下标）	Number	-	0	0.1.22
direction	轮播滑动方向	DirectionType	horizontal, vertical	horizontal	0.1.22
min-show-num	小于这个数字不会显示导航器	Number	-	2	0.1.22
pagination-position	页码信息展示位置	IndicatorPositionType	left, top-left, top, top-right, bottom-left, bottom, bottom-right, right	bottom	0.1.22
show-controls	是否显示控制按钮	Boolean	-	false	0.1.22
total	总共的项数	Number	-	0	0.1.22
type	导航器类型	SwiperIndicatorType	dots, dots-bar, fraction	dots	0.1.22
autoplay	是否自动播放	boolean	-	true	0.1.22

Events

事件名称	说明	参数	最低版本
click	点击轮播项时触发	(index: number, item: SwiperList | string)	0.1.22
change	轮播切换时触发	(current: number, source: 'autoplay' | 'touch' | 'nav')	0.1.22

Slot

name	说明	参数	最低版本
indicator	自定义指示器	{ current: number, total: number }	1.13.0
default	item展示内容	`{ item: string	SwiperList, index: number }`

外部样式类

类名	说明	最低版本
customClass	外部自定义类名	0.1.22
customIndicatorClass	自定义指示器类名	0.1.22
customImageClass	自定义图片类名，1.3版本将废弃，请使用customItemClass代替	0.1.22
customPrevImageClass	自定义上一个图片类名，1.3版本将废弃，请使用customPrevClass代替	0.1.22
customNextImageClass	自定义下一个图片类名，1.3版本将废弃，请使用customNextClass代替	0.1.22
customItemClass	自定义子项类名	1.3.13
customPrevClass	自定义上一个子项类名	1.3.13
customNextClass	自定义下一个子项类名	1.3.13
customTextClass	自定义文字标题类名	1.3.13
customTextStyle	自定义文字标题样式	1.3.13