ts-container-swiper.md 7.4 KB
Newer Older
Z
zengyawen 已提交
1 2
# Swiper

T
fourth  
tianyu 已提交
3 4
 滑块视图容器,提供子组件滑动轮播显示的能力。 

H
geshi  
HelloCrease 已提交
5
> **说明:**
6
>
Z
zengyawen 已提交
7
> 该组件从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
Z
zengyawen 已提交
8

Z
zengyawen 已提交
9

Z
zengyawen 已提交
10
## 子组件
Z
zengyawen 已提交
11 12 13

可以包含子组件。

Z
zengyawen 已提交
14 15 16

## 接口

L
fix doc  
luoying_ace_admin 已提交
17
Swiper(controller?: SwiperController)
Z
zengyawen 已提交
18

19 20
**参数:** 

T
fourth  
tianyu 已提交
21 22 23
| 参数名        | 参数类型                           | 必填  | 参数描述                 |
| ---------- | ------------------------------------- | ---- | -------------------- |
| controller | [SwiperController](#swipercontroller) | 否   | 给组件绑定一个控制器,用来控制组件翻页。 |
Z
zengyawen 已提交
24 25 26 27


## 属性

T
fourth  
tianyu 已提交
28
除支持[通用属性](ts-universal-attributes-size.md)外,还支持以下属性,不支持[Menu控制](ts-universal-attributes-menu.md)
H
HelloCrease 已提交
29

30 31 32 33 34 35 36 37 38
| 名称                          | 参数类型                               | 描述                                       |
| --------------------------- | ---------------------------------------- | ---------------------------------------- |
| index                       | number                                   | 设置当前在容器中显示的子组件的索引值。<br/>默认值:0                     |
| autoPlay                    | boolean                                  | 子组件是否自动播放,自动播放状态下,导航点不可操作。<br/>默认值:false    |
| interval                    | number                                   | 使用自动播放时播放的时间间隔,单位为毫秒。<br/>默认值:3000                    |
| indicator                   | boolean                                  | 是否启用导航点指示器。<br/>默认值:true                              |
| loop                        | boolean                                  | 是否开启循环。<br>设置为true时表示开启循环,在LazyForEach懒循环加载模式下,加载的组件数量建议大于5个。<br/>默认值:true |
| duration                    | number                                   | 子组件切换的动画时长,单位为毫秒。<br/>默认值:400                        |
| vertical                    | boolean                                  | 是否为纵向滑动。<br/>默认值:false                                 |
T
fourth  
tianyu 已提交
39
| itemSpace                   | number&nbsp;\|&nbsp;string          | 设置子组件与子组件之间间隙。<br/>默认值:0                           |
40 41 42
| displayMode                 | SwiperDisplayMode                        | 主轴方向上元素排列的模式,优先以displayCount设置的个数显示,displayCount未设置时本属性生效。<br/>默认值:SwiperDisplayMode.Stretch |
| cachedCount<sup>8+</sup>    | number                                   | 设置预加载子组件个数。<br/>默认值:1                              |
| disableSwipe<sup>8+</sup>   | boolean                                  | 禁用组件滑动切换功能。<br/>默认值:false                              |
43
| curve<sup>8+</sup>          | [Curve](ts-appendix-enums.md#curve)  \| string | 设置Swiper的动画曲线,默认为淡入淡出曲线,常用曲线参考[Curve枚举说明](ts-appendix-enums.md#curve),也可以通过[插值计算](../apis/js-apis-curve.md)模块提供的接口创建自定义的插值曲线对象。<br/>默认值:Curve.Ease |
H
HelloCrease 已提交
44
| indicatorStyle<sup>8+</sup> | {<br/>left?:&nbsp;[Length](ts-types.md#length),<br/>top?:&nbsp;[Length](ts-types.md#length),<br/>right?:&nbsp;[Length](ts-types.md#length),<br/>bottom?:&nbsp;[Length](ts-types.md#length),<br/>size?:&nbsp;[Length](ts-types.md#length),<br/>mask?:&nbsp;boolean,<br/>color?:&nbsp;[ResourceColor](ts-types.md),<br/>selectedColor?:&nbsp;[ResourceColor](ts-types.md)<br/>} | 设置导航点样式:<br/>\- left: 设置导航点距离Swiper组件左边的距离。<br/>\- top: 设置导航点距离Swiper组件顶部的距离。<br/>\- right: 设置导航点距离Swiper组件右边的距离。<br/>\- bottom: 设置导航点距离Swiper组件底部的距离。<br/>\- size: 设置导航点的直径。<br/>\- mask: 设置是否显示导航点蒙层样式。<br/>\- color: 设置导航点的颜色。<br/>\- selectedColor: 设置选中的导航点的颜色。 |
45
| displayCount<sup>8+</sup>   | number\|string                                               | 设置一页内元素显示个数。<br/>默认值:1                                           |
K
kangchongtao 已提交
46
| effectMode<sup>8+</sup>     | [EdgeEffect](ts-appendix-enums.md#edgeeffect)  | 滑动效果,目前支持的滑动效果参见EdgeEffect的枚举说明。<br/>默认值:EdgeEffect.Spring |
47 48

## SwiperDisplayMode枚举说明
T
fourth  
tianyu 已提交
49 50 51 52 53

| 名称 | 描述 |
| ----------- | ------------------------------------------ |
| Stretch     | Swiper滑动一页的宽度为Swiper组件自身的宽度。|
| AutoLinear  | Swiper滑动一页的宽度为子组件宽度中的最大值。|
54

55
## SwiperController
Z
zengyawen 已提交
56 57 58

Swiper容器组件的控制器,可以将此对象绑定至Swiper组件,然后通过它控制翻页。

59 60 61 62 63 64 65 66 67 68 69 70 71
### showNext

showNext(): void

翻至下一页。

### showPrevious

showPrevious(): void

翻至上一页。

### finishAnimation
Z
zengyawen 已提交
72

73 74 75 76 77 78 79 80
finishAnimation(callback?: () => void): void

停止播放动画。

**参数:**

| 参数名    | 参数类型   | 必填项 | 参数描述 |
| --------- | ---------- | ------ | -------- |
81
| callback  | () => void | 否     | 动画结束的回调。 |
Z
zengyawen 已提交
82 83 84

## 事件

85 86
### onChange

K
kangchongtao 已提交
87
onChange(event: (index: number) => void)
88

K
kangchongtao 已提交
89
当前显示的子组件索引变化时触发该事件,返回值为当前显示的子组件的索引值。
90

W
wangshuainan 已提交
91 92
**说明**:Swiper组件结合LazyForEach使用时,不能在onChange事件里触发子页面UI的刷新。

93
**返回值:**
94

95 96 97
| 名称    |   类型    | 参数描述 |
| --------- | ---------- | -------- |
| index     | number    | 当前显示元素的索引。 |
Z
zengyawen 已提交
98 99 100


## 示例
Z
zengyawen 已提交
101

H
geshi  
HelloCrease 已提交
102 103
```ts
// xxx.ets
Z
zengyawen 已提交
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
class MyDataSource implements IDataSource {
  private list: number[] = []
  private listener: DataChangeListener

  constructor(list: number[]) {
    this.list = list
  }

  totalCount(): number {
    return this.list.length
  }

  getData(index: number): any {
    return this.list[index]
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.listener = listener
  }

  unregisterDataChangeListener() {
  }
}

Z
zengyawen 已提交
128 129 130 131
@Entry
@Component
struct SwiperExample {
  private swiperController: SwiperController = new SwiperController()
Z
zengyawen 已提交
132 133
  private data: MyDataSource = new MyDataSource([])

134
  aboutToAppear(): void {
Z
zengyawen 已提交
135 136 137 138 139 140
    let list = []
    for (var i = 1; i <= 10; i++) {
      list.push(i.toString());
    }
    this.data = new MyDataSource(list)
  }
Z
zengyawen 已提交
141 142 143 144

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
Z
zengyawen 已提交
145
        LazyForEach(this.data, (item: string) => {
146
          Text(item).width('90%').height(160).backgroundColor(0xAFEEEE).textAlign(TextAlign.Center).fontSize(30)
Z
zengyawen 已提交
147
        }, item => item)
Z
zengyawen 已提交
148
      }
Z
zengyawen 已提交
149
      .cachedCount(2)
Z
zengyawen 已提交
150 151 152
      .index(1)
      .autoPlay(true)
      .interval(4000)
153 154
      .indicator(true)
      .loop(true)
Z
zengyawen 已提交
155 156
      .duration(1000)
      .itemSpace(0)
157
      .curve(Curve.Linear)
Z
zengyawen 已提交
158 159 160 161
      .onChange((index: number) => {
        console.info(index.toString())
      })

162 163
      Row({ space: 12 }) {
        Button('showNext')
Z
zengyawen 已提交
164 165 166
          .onClick(() => {
            this.swiperController.showNext()
          })
167
        Button('showPrevious')
Z
zengyawen 已提交
168 169 170
          .onClick(() => {
            this.swiperController.showPrevious()
          })
171 172 173
      }.margin(5)
    }.width('100%')
    .margin({ top: 5 })
Z
zengyawen 已提交
174 175 176
  }
}
```
Y
yamila 已提交
177 178

![swiper](figures/swiper.gif)