Skip to content

Commit a50c0be

Browse files
MoonofweishengMoonofweisheng
authored
feat: ✨ Swiper 轮播组件支持展示视频和设置轮播项标题 (#663)
1 parent 60b07e5 commit a50c0be

File tree

6 files changed

+381
-58
lines changed

6 files changed

+381
-58
lines changed

‎docs/component/swiper.md‎

Lines changed: 123 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
<frame/>
22

3-
# Swiper 轮播图 <el-tag text style="vertical-align: middle;margin-left:8px;" effect="plain">0.1.22</el-tag>
3+
# Swiper 轮播
44

5-
用于创建轮播图，它支持水平和垂直方向的滑动，可以自定义样式和指示器位置。
5+
用于创建轮播，它支持水平和垂直方向的滑动，可以自定义样式和指示器位置，支持视频和图片资源的轮播，支持设置轮播标题和自定义标题样式。
6+
7+
:::danger 请注意
8+
嵌入视频仅在`h5`、`微信小程序`和`钉钉小程序`支持，其余端不支持，请了解后使用。
9+
:::
610

711
## 基础用法
812

@@ -50,6 +54,60 @@ function onChange(e) {
5054
></wd-swiper>
5155
```
5256

57+
## 视频轮播<el-tag text style="vertical-align: middle;margin-left:8px;" effect="plain">1.3.13</el-tag>
58+
59+
:::danger 请注意
60+
嵌入视频仅在`h5`、`微信小程序`和`钉钉小程序`支持，其余端不支持，请了解后使用。
61+
:::
62+
63+
```html
64+
<wd-swiper :list="videoList" autoplay :indicator="false" indicator-position="bottom-right"></wd-swiper>
65+
```
66+
67+
```ts
68+
const videoList = ref([
69+
'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_115503.mp4',
70+
'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_150752.mp4',
71+
'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_155516.mp4',
72+
'https://registry.npmmirror.com/wot-design-uni-assets/*/files/moon.jpg'
73+
])
74+
```
75+
76+
## 手动播放视频
77+
78+
```html
79+
<wd-swiper :list="videoList" autoplay :autoplayVideo="false" :indicator="{ type: 'fraction' }" indicator-position="top-right"></wd-swiper>
80+
```
81+
82+
```ts
83+
const videoList = ref([
84+
'https://unpkg.com/wot-design-uni-assets/VID_115503.mp4',
85+
'https://unpkg.com/wot-design-uni-assets/VID_150752.mp4',
86+
'https://unpkg.com/wot-design-uni-assets/VID_155516.mp4'
87+
])
88+
```
89+
90+
## 播放视频时停止轮播
91+
92+
```html
93+
<wd-swiper
94+
:list="videoList"
95+
autoplay
96+
stopAutoplayWhenVideoPlay
97+
:autoplayVideo="false"
98+
:indicator="{ type: 'fraction' }"
99+
indicator-position="top-right"
100+
></wd-swiper>
101+
```
102+
103+
```ts
104+
const videoList = ref([
105+
'https://unpkg.com/wot-design-uni-assets/VID_115503.mp4',
106+
'https://unpkg.com/wot-design-uni-assets/VID_150752.mp4',
107+
'https://unpkg.com/wot-design-uni-assets/VID_155516.mp4'
108+
])
109+
```
110+
53111
## 手动切换
54112

55113
```html
@@ -186,25 +244,39 @@ function onChange(e) {
186244
}
187245
```
188246

189-
## 指定valueKey <el-tag text style="vertical-align: middle;margin-left:8px;" effect="plain">1.3.7</el-tag>
247+
## 指定valueKey和textKey
190248

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

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

194257
```html
195-
<wd-swiper value-key="url" :list="customSwiperList" autoplay v-model:current="current" @click="handleClick" @change="onChange"></wd-swiper>
258+
<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>
196259
```
197260
```ts
198261
const current = ref<number>(0)
199262

200263
const customSwiperList = ref([
201-
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/redpanda.jpg' },
202-
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/capybara.jpg' },
203-
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/panda.jpg' },
204-
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/moon.jpg' }
264+
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/redpanda.jpg', title: '小熊猫！' },
265+
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/capybara.jpg', title: '卡！皮！巴！拉！' },
266+
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/panda.jpg', title: '大熊猫！' },
267+
{ url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/moon.jpg', title: '诗画中国！' }
205268
])
206269
```
207-
270+
```scss
271+
:deep(.customTextClass) {
272+
position: absolute;
273+
top: 24rpx;
274+
right: 24rpx;
275+
color: #ffffff;
276+
font-size: 24rpx;
277+
text-shadow: 0 0 8rpx #000000;
278+
}
279+
```
208280

209281

210282
## 属性控制切换
@@ -231,26 +303,33 @@ const isLoop = ref(false)
231303

232304
## Attributes
233305

234-
| 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 |
235-
| -------------------- | ------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------ | -------- |
236-
| autoplay | 是否自动播放 | `boolean` | - | true | 0.1.22 |
237-
| v-model:current | 控制当前轮播在哪一项（下标） | `number` | - | 0 | 0.1.22 |
238-
| direction | 轮播滑动方向 | `DirectionType` | `horizontal, vertical` | horizontal | 0.1.22 |
239-
| displayMultipleItems | 同时显示的滑块数量 | `number` | - | 1 | 0.1.22 |
240-
| duration | 滑动动画时长 | `number` | - | 300 | 0.1.22 |
241-
| easingFunction | 切换缓动动画类型（微信小程序、快手小程序、京东小程序） | `EasingType` | - | default | 0.1.22 |
242-
| height | 轮播的高度 | `string \| number` | - | 192 | 0.1.22 |
243-
| interval | 轮播间隔时间 | `number` | - | 5000 | 0.1.22 |
244-
| list | 图片列表 | `string[] \| SwiperList[]` | - | - | 0.1.22 |
245-
| loop | 是否循环播放 | `boolean` | - | true | 0.1.22 |
246-
| nextMargin | 后边距 | `string \| number` | - | 0 | 0.1.22 |
247-
| indicatorPosition | 指示器展示位置 | `IndicatorPositionType` | `left, top-left, top, top-right, bottom-left, bottom, bottom-right, right` | bottom | 0.1.22 |
248-
| previousMargin | 前边距 | `string \| number` | - | 0 | 0.1.22 |
249-
| snapToEdge | 边距是否应用到第一个、最后一个元素 | `boolean` | - | false | 0.1.22 |
250-
| indicator | 指示器全部配置 | `SwiperIndicatorProps \| boolean` | - | true | 0.1.22 |
251-
| imageMode | 图片裁剪、缩放的模式 | `string` | 参考官方文档[mode](https://uniapp.dcloud.net.cn/component/image.html#mode-%E6%9C%89%E6%95%88%E5%80%BC) | `aspectFill` | 0.1.55 |
252-
| customStyle | 外部自定义样式 | `string` | - | '' | 0.1.22 |
306+
| 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 |
307+
| ------------------------- | ------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------ | ---------------- |
308+
| autoplay | 是否自动播放 | `boolean` | - | true | 0.1.22 |
309+
| v-model:current | 控制当前轮播在哪一项（下标） | `number` | - | 0 | 0.1.22 |
310+
| direction | 轮播滑动方向 | `DirectionType` | `horizontal, vertical` | horizontal | 0.1.22 |
311+
| displayMultipleItems | 同时显示的滑块数量 | `number` | - | 1 | 0.1.22 |
312+
| duration | 滑动动画时长 | `number` | - | 300 | 0.1.22 |
313+
| easingFunction | 切换缓动动画类型（微信小程序、快手小程序、京东小程序） | `EasingType` | - | default | 0.1.22 |
314+
| height | 轮播的高度 | `string \| number` | - | 192 | 0.1.22 |
315+
| interval | 轮播间隔时间 | `number` | - | 5000 | 0.1.22 |
316+
| list | 图片列表 | `string[] \| SwiperList[]` | - | - | 0.1.22 |
317+
| loop | 是否循环播放 | `boolean` | - | true | 0.1.22 |
318+
| nextMargin | 后边距 | `string \| number` | - | 0 | 0.1.22 |
319+
| indicatorPosition | 指示器展示位置 | `IndicatorPositionType` | `left, top-left, top, top-right, bottom-left, bottom, bottom-right, right` | bottom | 0.1.22 |
320+
| previousMargin | 前边距 | `string \| number` | - | 0 | 0.1.22 |
321+
| snapToEdge | 边距是否应用到第一个、最后一个元素 | `boolean` | - | false | 0.1.22 |
322+
| indicator | 指示器全部配置 | `SwiperIndicatorProps \| boolean` | - | true | 0.1.22 |
323+
| imageMode | 图片裁剪、缩放的模式 | `string` | 参考官方文档[mode](https://uniapp.dcloud.net.cn/component/image.html#mode-%E6%9C%89%E6%95%88%E5%80%BC) | `aspectFill` | 0.1.55 |
324+
| autoplayVideo | 视频是否自动播放，默认自动播放 | `boolean` | - | true | $LOWEST_VERSION$ |
325+
| stopPreviousVideo  | 切换轮播项时是否停止上一个视频的播放，默认切换时停止播放上一个视频 | `boolean` | - | true | $LOWEST_VERSION$ |
326+
| stopAutoplayWhenVideoPlay | 视频播放时是否停止自动轮播 | `boolean` | - | false | $LOWEST_VERSION$ |
327+
| customStyle | 外部自定义样式 | `string` | - | '' | 0.1.22 |
253328
| value-key | 选项对象中，value 对应的 key | `string` | - | `value` | 1.3.7 |
329+
| text-key | 选项对象中，标题 text 对应的 key | `string` | - | `text` | $LOWEST_VERSION$ |
330+
| adjust-height | 自动以指定滑块的高度为整个容器的高度。当 vertical 为 true 时，默认不调整，仅支付宝小程序支持。| `string` | `'first' \| 'current' \| 'highest' \| 'none'` | `highest` | $LOWEST_VERSION$ |
331+
| adjust-vertical-height | vertical 为 true 时强制使 adjust-height 生效。仅支付宝小程序支持。 | `boolean` | - | `false` | $LOWEST_VERSION$ |
332+
254333

255334

256335
### DirectionType
@@ -267,10 +346,15 @@ const isLoop = ref(false)
267346

268347
### SwiperList
269348

270-
轮播图项的列表配置，包括 `value` 属性，支持扩展属性。
349+
轮播图项的列表配置，包括 图片或视频地址`value`、视频封面`poster` 等属性，支持扩展属性。
271350

272351
### SwiperIndicatorProps
273352

353+
| 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 |
354+
| ------------------- | -------------------------- | --------------------- | -------------------------------------------------------------------------- | ---------- | -------- |
355+
| current | 当前轮播在哪一项（下标） | Number | - | 0 | 0.1.22 |
356+
| direction | 轮播滑动方向 | DirectionType | `horizontal, vertical` | horizontal | 0.1.22 |
357+
| min-show-num | 小于这个数字不会显示导航器 | Number | - | 2 | 0.1.22 |
274358
| 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 |
275359
| ------------------- | -------------------------- | --------------------- | -------------------------------------------------------------------------- | ---------- | -------- |
276360
| current | 当前轮播在哪一项（下标） | Number | - | 0 | 0.1.22 |
@@ -295,12 +379,18 @@ const isLoop = ref(false)
295379
| --------- | ------------ | ------------------------------------ | -------- |
296380
| indicator | 自定义指示器 | `{ current: number, total: number }` | 0.1.22 |
297381

382+
298383
## 外部样式类
299384

300385
| 类名 | 说明 | 最低版本 |
301386
| -------------------- | -------------------- | -------- |
302387
| customClass | 外部自定义类名 | 0.1.22 |
303-
| customIndicatorClass | 自定义指示器类名 | 0.1.22 |
304-
| customImageClass | 自定义图片类名 | 0.1.22 |
305-
| customPrevImageClass | 自定义上一个图片类名 | 0.1.22 |
306-
| customNextImageClass | 自定义下一个图片类名 | 0.1.22 |
388+
| customIndicatorClass | 自定义指示器类名 | 0.1.22 |
389+
| customImageClass | 自定义图片类名，1.3版本将废弃，请使用`customItemClass`代替 | 0.1.22 |
390+
| customPrevImageClass | 自定义上一个图片类名，1.3版本将废弃，请使用`customPrevClass`代替 | 0.1.22 |
391+
| customNextImageClass | 自定义下一个图片类名，1.3版本将废弃，请使用`customNextClass`代替 | 0.1.22 |
392+
| customItemClass | 自定义子项类名 | $LOWEST_VERSION$ |
393+
| customPrevClass | 自定义上一个子项类名 | $LOWEST_VERSION$ |
394+
| customNextClass | 自定义下一个子项类名 | $LOWEST_VERSION$ |
395+
| customTextClass | 自定义文字标题类名 | $LOWEST_VERSION$ |
396+
| customTextStyle | 自定义文字标题样式 | $LOWEST_VERSION$ |

0 commit comments

Comments
 (0)