Skip to content

Commit 41dd417

Browse files
MoonofweishengMoonofweisheng
authored
feat: ✨ 优化 Swiper 使用默认插槽时插槽内容的显示效果 (#1301)
1 parent 046b135 commit 41dd417

5 files changed

Lines changed: 252 additions & 31 deletions

File tree

‎docs/component/swiper.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -300,18 +300,21 @@ const isLoop = ref(false)
300300
```
301301

302302

303-
## slot插槽自定义内容
303+
## 插槽用法
304+
305+
通过默认插槽可以自定义轮播项的内容。
306+
304307
```html
305308
<wd-swiper
306309
:list="swiperList"
307310
autoplay
308311
v-model:current="current"
309-
:indicator="{ type: 'dots' }"
312+
:indicator="{ type: 'dots-bar' }"
310313
@click="handleClick"
311314
@change="onChange"
312315
>
313-
<template v-slot="{ item, index }">
314-
<view class="custom-indicator" style="position: absolute; bottom: 24rpx; right: 24rpx">{{ index + 1 }}/{{ item }}</view>
316+
<template #default="{ item }">
317+
<image :src="item as string" mode="aspectFill" style="width: 100%; height: 100%" />
315318
</template>
316319
</wd-swiper>
317320
```
@@ -401,8 +404,8 @@ const isLoop = ref(false)
401404

402405
| name | 说明 | 参数 | 最低版本 |
403406
| --------- | ------------ | ------------------------------------ | -------- |
404-
| indicator | 自定义指示器 | `{ current: number, total: number }` | 0.1.22 |
405-
| default | item展示内容 | `{ item: any, index: number }` | 0.1.22 |
407+
| indicator | 自定义指示器 | `{ current: number, total: number }` | $LOWEST_VERSION$ |
408+
| default | item展示内容 | `{ item: string | SwiperList, index: number }` | $LOWEST_VERSION$ |
406409

407410

408411
## 外部样式类

‎docs/en-US/component/swiper.md‎

Lines changed: 208 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -201,31 +201,216 @@ Set the `display-multiple-items` property to control the number of slides displa
201201
}
202202
```
203203

204+
## Vertical Direction
205+
206+
Set `direction` to `vertical` to arrange slides vertically.
207+
208+
```html
209+
<wd-swiper
210+
:list="swiperList"
211+
direction="vertical"
212+
indicatorPosition="right"
213+
autoplay
214+
v-model:current="current"
215+
:indicator="{ type: 'dots-bar' }"
216+
@click="handleClick"
217+
@change="onChange"
218+
></wd-swiper>
219+
```
220+
221+
## Custom Indicator
222+
223+
Use the `indicator` slot to customize the indicator style.
224+
225+
```html
226+
<wd-swiper
227+
:list="swiperList"
228+
direction="vertical"
229+
indicatorPosition="right"
230+
autoplay
231+
v-model:current="current"
232+
@click="handleClick"
233+
@change="onChange"
234+
>
235+
<template #indicator="{ current, total }">
236+
<view class="custom-indicator" style="position: absolute; bottom: 24rpx; right: 24rpx">{{ current + 1 }}/{{ total }}</view>
237+
</template>
238+
</wd-swiper>
239+
```
240+
241+
```scss
242+
.custom-indicator {
243+
padding: 0 12rpx;
244+
height: 48rpx;
245+
line-height: 48rpx;
246+
border-radius: 45%;
247+
background: rgba(0, 0, 0, 0.6);
248+
color: #ffffff;
249+
font-size: 24rpx;
250+
}
251+
```
252+
253+
## Specify valueKey and textKey
254+
255+
Use `value-key` to specify the image address field in each object of the `list`, default is `value`.
256+
257+
Use `text-key` to specify the title field in each object of the `list`, default is `text`.
258+
259+
```html
260+
<wd-swiper
261+
value-key="url"
262+
text-key="title"
263+
:list="customSwiperList"
264+
autoplay
265+
v-model:current="current"
266+
@click="handleClick"
267+
@change="onChange"
268+
></wd-swiper>
269+
```
270+
271+
```ts
272+
const current = ref<number>(0)
273+
274+
const customSwiperList = ref([
275+
{ url: 'https://wot-ui.cn/assets/redpanda.jpg', title: 'Red Panda!' },
276+
{ url: 'https://wot-ui.cn/assets/capybara.jpg', title: 'Capybara!' },
277+
{ url: 'https://wot-ui.cn/assets/panda.jpg', title: 'Giant Panda!' },
278+
{ url: 'https://wot-ui.cn/assets/moon.jpg', title: 'Poetic China!' }
279+
])
280+
```
281+
282+
## Property Control Switching
283+
284+
```html
285+
<wd-swiper :loop="isLoop" :autoplay="false" :list="swiperList" v-model:current="current" />
286+
<wd-gap />
287+
<wd-cell-group>
288+
<wd-cell title="loop">
289+
<wd-switch v-model="isLoop" size="24px" />
290+
</wd-cell>
291+
<wd-cell title="current" :value="current.toString()" />
292+
</wd-cell-group>
293+
<view style="display: flex; justify-content: space-between">
294+
<wd-button @click="current--">prev</wd-button>
295+
<wd-button type="success" @click="current++">next</wd-button>
296+
</view>
297+
```
298+
299+
```javascript
300+
const current = ref<number>(0)
301+
const isLoop = ref(false)
302+
```
303+
304+
## Slot Usage
305+
306+
Use the default slot to customize the content of carousel items.
307+
308+
```html
309+
<wd-swiper
310+
:list="swiperList"
311+
autoplay
312+
v-model:current="current"
313+
:indicator="{ type: 'dots-bar' }"
314+
@click="handleClick"
315+
@change="onChange"
316+
>
317+
<template #default="{ item }">
318+
<image :src="item as string" mode="aspectFill" style="width: 100%; height: 100%" />
319+
</template>
320+
</wd-swiper>
321+
```
322+
204323
## Attributes
205324

206-
| Attribute | Description | Type | Default | Version |
207-
|-----------|-------------|------|---------|----------|
208-
| list | List of images or videos to display | array | [] | - |
209-
| v-model:current | Current slide index | number | 0 | - |
210-
| autoplay | Whether to enable auto-play | boolean | false | - |
211-
| interval | Auto-play interval (ms) | number | 3000 | - |
212-
| duration | Slide animation duration (ms) | number | 500 | - |
213-
| indicator | Indicator configuration object | object | { type: 'dots' } | - |
214-
| indicator-position | Indicator position | string | 'bottom' | - |
215-
| previous-margin | Previous slide margin | string | '0px' | - |
216-
| next-margin | Next slide margin | string | '0px' | - |
217-
| display-multiple-items | Number of slides to display simultaneously | number | 1 | - |
218-
| autoplay-video | Whether to auto-play videos | boolean | true | - |
219-
| stop-autoplay-when-video-play | Whether to stop carousel when playing video | boolean | false | - |
220-
| loop | Whether to enable loop mode | boolean | true | - |
221-
| custom-indicator-class | Custom indicator class | string | - | - |
222-
| custom-image-class | Custom image class | string | - | - |
223-
| custom-next-image-class | Custom next image class | string | - | - |
224-
| custom-prev-image-class | Custom previous image class | string | - | - |
325+
| Parameter | Description | Type | Optional Values | Default Value | Minimum Version |
326+
| ------------------------- | ------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------- | ---------------- |
327+
| autoplay | Whether to enable auto-play | `boolean` | - | true | 0.1.22 |
328+
| v-model:current | Control which carousel item is currently displayed (index) | `number` | - | 0 | 0.1.22 |
329+
| direction | Carousel sliding direction | `DirectionType` | `horizontal, vertical` | horizontal | 0.1.22 |
330+
| displayMultipleItems | Number of slides displayed simultaneously | `number` | - | 1 | 0.1.22 |
331+
| duration | Slide animation duration | `number` | - | 300 | 0.1.22 |
332+
| easingFunction | Switching easing animation type (WeChat Mini Program, Kuaishou Mini Program, JD Mini Program) | `EasingType` | - | default | 0.1.22 |
333+
| height | Height of the carousel | `string / number` | - | 192 | 0.1.22 |
334+
| interval | Carousel interval time | `number` | - | 5000 | 0.1.22 |
335+
| list | Image list | `string[] / SwiperList[]` | - | - | 0.1.22 |
336+
| loop | Whether to enable loop playback | `boolean` | - | true | 0.1.22 |
337+
| nextMargin | Next margin | `string / number` | - | 0 | 0.1.22 |
338+
| indicatorPosition | Indicator display position | `IndicatorPositionType` | `left, top-left, top, top-right, bottom-left, bottom, bottom-right, right` | bottom | 0.1.22 |
339+
| previousMargin | Previous margin | `string / number` | - | 0 | 0.1.22 |
340+
| snapToEdge | Whether margins should apply to first and last elements | `boolean` | - | false | 0.1.22 |
341+
| indicator | Complete indicator configuration | `SwiperIndicatorProps / boolean` | - | true | 0.1.22 |
342+
| imageMode | Image cropping and scaling mode | `string` | Refer to official documentation [mode](https://uniapp.dcloud.net.cn/component/image.html#mode-%E6%9C%89%E6%95%88%E5%80%BC) | `aspectFill` | 0.1.55 |
343+
| autoplayVideo | Whether videos auto-play, default is auto-play | `boolean` | - | true | 1.3.13 |
344+
| stopPreviousVideo | Whether to stop previous video playback when switching carousel items, default stops previous video when switching | `boolean` | - | true | 1.3.13 |
345+
| stopAutoplayWhenVideoPlay | Whether to stop auto-carousel when video is playing | `boolean` | - | false | 1.3.13 |
346+
| customStyle | External custom style | `string` | - | '' | 0.1.22 |
347+
| value-key | Key corresponding to value in option object | `string` | - | `value` | 1.3.7 |
348+
| text-key | Key corresponding to title text in option object | `string` | - | `text` | 1.3.13 |
349+
| adjust-height | Automatically use specified slide height as entire container height. When vertical is true, default is not adjusted, only supported by Alipay Mini Program. | `string` | `'first' / 'current' / 'highest' / 'none'` | `highest` | 1.3.13 |
350+
| adjust-vertical-height | Force adjust-height to take effect when vertical is true. Only supported by Alipay Mini Program. | `boolean` | - | `false` | 1.3.13 |
351+
| muted | Whether video plays muted | `boolean` | - | `true` | 1.6.0 |
352+
| videoLoop | Whether video loops | `boolean` | - | `true` | 1.6.0 |
353+
354+
### DirectionType
355+
356+
Carousel sliding direction, optional values are `'horizontal'` and `'vertical'`.
357+
358+
### EasingType
359+
360+
Switching easing animation type, optional values are `'default'`, `'linear'`, `'easeInCubic'`, `'easeOutCubic'` and `'easeInOutCubic'`.
361+
362+
### IndicatorPositionType
363+
364+
Page information display position, optional values are `'left'`, `'top-left'`, `'top'`, `'top-right'`, `'bottom-left'`, `'bottom'`, `'bottom-right'` and `'right'`.
365+
366+
### SwiperList
367+
368+
Carousel item list configuration, including image or video address `value`, video cover `poster`, file resource type `type` and other attributes, supports extended attributes. After specifying `type`, the component will not internally determine the file type and will use `type` as the standard.
369+
370+
| name | Description | Minimum Version |
371+
| ------ | ------------------------------ | --------------- |
372+
| value | Image or video address | - |
373+
| poster | Video cover | - |
374+
| type | Used to specify file resource type, optional values `image`, `video` | 1.4.0 |
375+
376+
### SwiperIndicatorProps
377+
378+
| Parameter | Description | Type | Optional Values | Default Value | Minimum Version |
379+
| ------------------- | ------------------------------ | --------------------- | ---------------------------------------------------------------------------------- | ------------- | --------------- |
380+
| current | Current carousel item (index) | Number | - | 0 | 0.1.22 |
381+
| direction | Carousel sliding direction | DirectionType | `horizontal, vertical` | horizontal | 0.1.22 |
382+
| min-show-num | Won't show navigator below this number | Number | - | 2 | 0.1.22 |
383+
| pagination-position | Page information display position | IndicatorPositionType | `left, top-left, top, top-right, bottom-left, bottom, bottom-right, right` | bottom | 0.1.22 |
384+
| show-controls | Whether to show control buttons | Boolean | - | false | 0.1.22 |
385+
| total | Total number of items | Number | - | 0 | 0.1.22 |
386+
| type | Navigator type | SwiperIndicatorType | `dots, dots-bar, fraction` | dots | 0.1.22 |
387+
| autoplay | Whether to enable auto-play | boolean | - | true | 0.1.22 |
225388

226389
## Events
227390

228-
| Event | Description | Parameters |
229-
|-------|-------------|------------|
230-
| click | Triggered when clicking a slide | event: Event |
231-
| change | Triggered when current slide changes | index: number |
391+
| Event Name | Description | Parameters | Minimum Version |
392+
| ---------- | ------------------------ | ----------------------------------------------------------- | --------------- |
393+
| click | Triggered when clicking carousel item | `(index: number, item: SwiperList \| string)` | 0.1.22 |
394+
| change | Triggered when carousel switches | `(current: number, source: 'autoplay' \| 'touch' \| 'nav')` | 0.1.22 |
395+
396+
## Slot
397+
398+
| name | Description | Parameters | Minimum Version |
399+
| --------- | ------------------- | ------------------------------------ | --------------- |
400+
| indicator | Custom indicator | `{ current: number, total: number }` | $LOWEST_VERSION$ |
401+
| default | Item display content | `{ item: string | SwiperList, index: number }` | $LOWEST_VERSION$ |
402+
403+
## External Style Classes
404+
405+
| Class Name | Description | Minimum Version |
406+
| -------------------- | --------------------------- | --------------- |
407+
| customClass | External custom class name | 0.1.22 |
408+
| customIndicatorClass | Custom indicator class name | 0.1.22 |
409+
| customImageClass | Custom image class name, will be deprecated in version 1.3, please use `customItemClass` instead | 0.1.22 |
410+
| customPrevImageClass | Custom previous image class name, will be deprecated in version 1.3, please use `customPrevClass` instead | 0.1.22 |
411+
| customNextImageClass | Custom next image class name, will be deprecated in version 1.3, please use `customNextClass` instead | 0.1.22 |
412+
| customItemClass | Custom item class name | 1.3.13 |
413+
| customPrevClass | Custom previous item class name | 1.3.13 |
414+
| customNextClass | Custom next item class name | 1.3.13 |
415+
| customTextClass | Custom text title class name | 1.3.13 |
416+
| customTextStyle | Custom text title style | 1.3.13 |

‎src/subPages/swiper/Index.vue‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,14 @@
175175
<wd-button type="success" @click="current8++">next</wd-button>
176176
</view>
177177
</demo-block>
178+
179+
<demo-block :title="$t('cha-cao-yong-fa')">
180+
<wd-swiper :list="swiperList" autoplay v-model:current="current1" :indicator="{ type: 'dots-bar' }" @click="handleClick" @change="onChange">
181+
<template #default="{ item }">
182+
<image :src="item as string" mode="aspectFill" style="width: 100%; height: 100%" />
183+
</template>
184+
</wd-swiper>
185+
</demo-block>
178186
</page-wraper>
179187
</template>
180188
<script lang="ts" setup>

‎src/uni_modules/wot-design-uni/components/wd-swiper/index.scss‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,26 @@
1515
align-items: center;
1616
box-sizing: border-box;
1717
padding: $-swiper-item-padding;
18+
19+
@include m(slot) {
20+
// 问题来自 https://github.com/dcloudio/uni-app/issues/4629，支付宝小程序不支持属性选择器
21+
/* #ifdef MP */
22+
:deep() {
23+
/* #ifdef MP-WEIXIN */
24+
view:not([class]) {
25+
width: 100%;
26+
height: 100%;
27+
}
28+
/* #endif */
29+
/* #ifndef MP-WEIXIN */
30+
view {
31+
width: 100%;
32+
height: 100%;
33+
}
34+
/* #endif */
35+
}
36+
/* #endif */
37+
}
1838
}
1939

2040
@include e(image, video) {

0 commit comments

Comments
 (0)