1# Swiper 2 3 滑块视图容器，提供子组件滑动轮播显示的能力。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12可以包含子组件。 13 14> **说明：** 15> 16> 子组件类型：系统组件和自定义组件，支持渲染控制类型（[if/else](../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../quick-start/arkts-rendering-control-foreach.md)和[LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md)）。 17 18 19## 接口 20 21Swiper(controller?: SwiperController) 22 23**参数：** 24 25| 参数名 | 参数类型 | 必填 | 参数描述 | 26| ---------- | ------------------------------------- | ---- | -------------------- | 27| controller | [SwiperController](#swipercontroller) | 否 | 给组件绑定一个控制器，用来控制组件翻页。 | 28 29 30## 属性 31 32除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性，不支持[Menu控制](ts-universal-attributes-menu.md)。 33 34| 名称 | 参数类型 | 描述 | 35| --------------------------- | ---------------------------------------- | ---------------------------------------- | 36| index | number | 设置当前在容器中显示的子组件的索引值。<br/>默认值：0<br/>**说明：** <br/>设置小于0或大于等于子组件数量时，按照默认值0处理。 | 37| autoPlay | boolean | 子组件是否自动播放。<br/>默认值：false<br/>**说明：** <br/>loop为false时，自动轮播到最后一页时停止轮播。手势切换后不是最后一页时继续播放。 | 38| interval | number | 使用自动播放时播放的时间间隔，单位为毫秒。<br/>默认值：3000 | 39| indicator | boolean | 是否启用导航点指示器。<br/>默认值：true | 40| loop | boolean | 是否开启循环。<br>设置为true时表示开启循环，在LazyForEach懒循环加载模式下，加载的组件数量建议大于5个。<br/>默认值：true | 41| duration | number | 子组件切换的动画时长，单位为毫秒。<br/>默认值：400 | 42| vertical | boolean | 是否为纵向滑动。<br/>默认值：false | 43| itemSpace | number \| string | 设置子组件与子组件之间间隙。<br/>默认值：0<br/>**说明：** <br/>不支持设置百分比。 | 44| displayMode | SwiperDisplayMode | 主轴方向上元素排列的模式，优先以displayCount设置的个数显示，displayCount未设置时本属性生效。<br/>默认值：SwiperDisplayMode.Stretch | 45| cachedCount<sup>8+</sup> | number | 设置预加载子组件个数。<br/>默认值：1<br/>**说明：** <br/>cachedCount已经做了预加载的优化，不建议与[LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md)一起使用。 | 46| disableSwipe<sup>8+</sup> | boolean | 禁用组件滑动切换功能。<br/>默认值：false | 47| 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 | 48| indicatorStyle<sup>8+</sup> | {<br/>left?: [Length](ts-types.md#length),<br/>top?: [Length](ts-types.md#length),<br/>right?: [Length](ts-types.md#length),<br/>bottom?: [Length](ts-types.md#length),<br/>size?: [Length](ts-types.md#length),<br/>mask?: boolean,<br/>color?: [ResourceColor](ts-types.md),<br/>selectedColor?: [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: 设置选中的导航点的颜色。 | 49| displayCount<sup>8+</sup> | number\|string | 设置一页内元素显示个数。<br/>默认值：1<br/>**说明：** <br/>字符串类型仅支持设置为'auto'，显示效果同SwiperDisplayMode.AutoLinear。<br/>使用number类型时，子组件按照主轴均分Swiper宽度（减去displayCount-1的itemSpace）的方式进行主轴拉伸（收缩）布局。 | 50| effectMode<sup>8+</sup> | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 滑动效果，目前支持的滑动效果参见EdgeEffect的枚举说明。<br/>默认值：EdgeEffect.Spring<br/>**说明：** <br/>控制器接口调用时不生效回弹。 | 51 52## SwiperDisplayMode枚举说明 53 54| 名称 | 描述 | 55| ----------- | ------------------------------------------ | 56| Stretch | Swiper滑动一页的宽度为Swiper组件自身的宽度。| 57| AutoLinear | Swiper滑动一页的宽度为子组件宽度中的最大值。| 58 59## SwiperController 60 61Swiper容器组件的控制器，可以将此对象绑定至Swiper组件，然后通过它控制翻页。 62 63### showNext 64 65showNext(): void 66 67翻至下一页。翻页带动效切换过程，时长通过duration指定。 68 69### showPrevious 70 71showPrevious(): void 72 73翻至上一页。翻页带动效切换过程，时长通过duration指定。 74 75### finishAnimation 76 77finishAnimation(callback?: () => void): void 78 79停止播放动画。 80 81**参数：** 82 83| 参数名 | 参数类型 | 必填项 | 参数描述 | 84| --------- | ---------- | ------ | -------- | 85| callback | () => void | 否 | 动画结束的回调。 | 86 87## 事件 88 89除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 90 91| 名称 | 功能描述 | 92| ------------------------------------------------------------ | ------------------------------------------------------------ | 93| onChange(event: (index: number) => void) | 当前显示的子组件索引变化时触发该事件,返回值为当前显示的子组件的索引值。<br/>- index:当前显示元素的索引。<br/>**说明：** <br>Swiper组件结合LazyForEach使用时，不能在onChange事件里触发子页面UI的刷新。 | 94| onAnimationStart<sup>9+</sup>(event: (index: number) => void) | 切换动画开始时触发该回调。<br/>- index:当前显示元素的索引。<br/>**说明：** <br/>参数为动画开始前的index值（不是最终结束动画的index值），多列Swiper时，index为最左侧组件的索引。 | 95| onAnimationEnd<sup>9+</sup>(event: (index: number) => void) | 切换动画结束时触发该回调。<br/>- index:当前显示元素的索引。<br/>**说明：** <br/>当Swiper切换动效结束时触发，包括动画过程中手势中断，通过SwiperController调用finishAnimatio。参数为动画结束后的index值，多列Swiper时，index为最左侧组件的索引。 | 96 97## 示例 98 99```ts 100// xxx.ets 101class MyDataSource implements IDataSource { 102 private list: number[] = [] 103 private listener: DataChangeListener 104 105 constructor(list: number[]) { 106 this.list = list 107 } 108 109 totalCount(): number { 110 return this.list.length 111 } 112 113 getData(index: number): any { 114 return this.list[index] 115 } 116 117 registerDataChangeListener(listener: DataChangeListener): void { 118 this.listener = listener 119 } 120 121 unregisterDataChangeListener() { 122 } 123} 124 125@Entry 126@Component 127struct SwiperExample { 128 private swiperController: SwiperController = new SwiperController() 129 private data: MyDataSource = new MyDataSource([]) 130 131 aboutToAppear(): void { 132 let list = [] 133 for (var i = 1; i <= 10; i++) { 134 list.push(i.toString()); 135 } 136 this.data = new MyDataSource(list) 137 } 138 139 build() { 140 Column({ space: 5 }) { 141 Swiper(this.swiperController) { 142 LazyForEach(this.data, (item: string) => { 143 Text(item).width('90%').height(160).backgroundColor(0xAFEEEE).textAlign(TextAlign.Center).fontSize(30) 144 }, item => item) 145 } 146 .cachedCount(2) 147 .index(1) 148 .autoPlay(true) 149 .interval(4000) 150 .indicator(true) 151 .loop(true) 152 .duration(1000) 153 .itemSpace(0) 154 .curve(Curve.Linear) 155 .onChange((index: number) => { 156 console.info(index.toString()) 157 }) 158 159 Row({ space: 12 }) { 160 Button('showNext') 161 .onClick(() => { 162 this.swiperController.showNext() 163 }) 164 Button('showPrevious') 165 .onClick(() => { 166 this.swiperController.showPrevious() 167 }) 168 }.margin(5) 169 }.width('100%') 170 .margin({ top: 5 }) 171 } 172} 173``` 174 175
