1# Swiper 2 3 The **\<Swiper>** component is able to display child components in looping mode. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12This component can contain child components. 13 14> **NOTE** 15> 16> Built-in components and custom components are allowed, with support for ([if/else](../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md)) rendering control. 17 18 19## APIs 20 21Swiper(controller?: SwiperController) 22 23**Parameters** 24 25| Name | Type | Mandatory | Description | 26| ---------- | ------------------------------------- | ---- | -------------------- | 27| controller | [SwiperController](#swipercontroller) | No | Controller bound to the component to control the page switching.| 28 29 30## Attributes 31 32In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. [Menu control](ts-universal-attributes-menu.md) is not supported. 33 34| Name | Type | Description | 35| --------------------------- | ---------------------------------------- | ---------------------------------------- | 36| index | number | Index of the child component currently displayed in the container.<br>Default value: **0**<br>**NOTE**<br>If the value is less than 0 or greater than or equal to the number of child components, the default value **0** is used.| 37| autoPlay | boolean | Whether to enable automatic playback for child component switching.<br>Default value: **false**<br>**NOTE**<br>If **loop** is set to **false**, the playback stops when the last page is displayed. The playback continues when the page is not the last page after a swipe gesture.| 38| interval | number | Interval for automatic playback, in ms.<br>Default value: **3000** | 39| indicator | boolean | Whether to enable the navigation dots indicator.<br>Default value: **true** | 40| loop | boolean | Whether to enable loop playback.<br>The value **true** means to enable loop playback. When LazyForEach is used, it is recommended that the number of the components to load exceed 5.<br>Default value: **true**| 41| duration | number | Duration of the animation for switching child components, in ms.<br>Default value: **400** | 42| vertical | boolean | Whether vertical swiping is used.<br>Default value: **false** | 43| itemSpace | number \| string | Space between child components.<br>Default value: **0**<br>**NOTE**<br>This parameter cannot be set in percentage.| 44| displayMode | SwiperDisplayMode | Mode in which elements are displayed along the main axis. This attribute takes effect only when **displayCount** is not set.<br>Default value: **SwiperDisplayMode.Stretch**| 45| cachedCount<sup>8+</sup> | number | Number of child components to be cached.<br>Default value: **1**<br>**NOTE**<br>**cachedCount** has caching optimized. You are advised not to use it together with [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md).| 46| disableSwipe<sup>8+</sup> | boolean | Whether to disable the swipe feature.<br>Default value: **false** | 47| curve<sup>8+</sup> | [Curve](ts-appendix-enums.md#curve) \| string | Animation curve. The ease-in/ease-out curve is used by default. For details about common curves, see [Curve](ts-appendix-enums.md#curve). You can also create custom curves (interpolation curve objects) by using the API provided by the [interpolation calculation](../apis/js-apis-curve.md) module.<br>Default value: **Curve.Linear**| 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>} | Style of the navigation point indicator.<br>\- **left**: distance between the navigation point indicator and the left edge of the **\<Swiper>** component.<br>\- **top**: distance between the navigation point indicator and the top edge of the **\<Swiper>** component.<br>\- **right**: distance between the navigation point indicator and the right edge of the **\<Swiper>** component.<br>\- **bottom**: distance between the navigation point indicator and the bottom edge of the **\<Swiper>** component.<br>\- **size**: diameter of the navigation point indicator. The value cannot be in percentage. Default value: **6vp**<br>\- **mask**: whether to enable the mask for the navigation point indicator.<br>\- **color**: color of the navigation point indicator.<br>\- **selectedColor**: color of the selected navigation dot.| 49| displayCount<sup>8+</sup> | number \| string | Number of elements to display per page.<br>Default value: **1**<br>**NOTE**<br>If the value is of the string type, it can only be **'auto'**, whose display effect is the same as that of **SwiperDisplayMode.AutoLinear**.<br>If the value is of the number type, child components stretch (shrink) on the main axis after the swiper width [deducting the result of itemSpace x (displayCount - 1)] is evenly distributed among them on the main axis.| 50| effectMode<sup>8+</sup> | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Swipe effect. For details, see **EdgeEffect**.<br>Default value: **EdgeEffect.Spring**<br>**NOTE**<br>The spring effect does not take effect when the controller API is called.| 51 52## SwiperDisplayMode 53 54| Name| Description| 55| ----------- | ------------------------------------------ | 56| Stretch | The slide width of the **\<Swiper>** component is equal to the width of the component.| 57| AutoLinear | The slide width of the **\<Swiper>** component is equal to that of the child component with the maximum width.| 58 59## SwiperController 60 61Controller of the **\<Swiper>** component. You can bind this object to the **\<Swiper>** component and use it to control page switching. 62 63### showNext 64 65showNext(): void 66 67Turns to the next page. Page turning occurs with the animation, whose duration is specified by **duration**. 68 69### showPrevious 70 71showPrevious(): void 72 73Turns to the previous page. Page turning occurs with the animation, whose duration is specified by **duration**. 74 75### finishAnimation 76 77finishAnimation(callback?: () => void): void 78 79Stops an animation. 80 81**Parameters** 82 83| Name | Type | Mandatory.| Description| 84| --------- | ---------- | ------ | -------- | 85| callback | () => void | No | Callback invoked when the animation stops.| 86 87 88## Events 89 90In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 91 92| Name | Description | 93| ------------------------------------------------------------ | ------------------------------------------------------------ | 94| onChange(event: (index: number) => void) | Triggered when the index of the currently displayed child component changes.<br>- **index**: index of the currently displayed element.<br>**NOTE**<br>When the **\<Swiper>** component is used together with **LazyForEach**, the subpage UI update cannot be triggered in the **onChange** event.| 95| onAnimationStart<sup>9+</sup>(event: (index: number) => void) | Triggered when the switching animation starts.<br>- **index**: index of the currently displayed element.<br>**NOTE**<br>The **index** parameter indicates the index before the animation starts (not the one after). When the **\<Swiper>** component contains multiple columns, the index is of the leftmost element.| 96| onAnimationEnd<sup>9+</sup>(event: (index: number) => void) | Triggered when the switching animation ends.<br>- **index**: index of the currently displayed element.<br>**NOTE**<br>This event is triggered when the animation ends regardless of whether it is due to a user gesture or invocation of **finishAnimation** through **SwiperController**. The **index** parameter indicates the index after the animation ends. When the **\<Swiper>** component contains multiple columns, the index is of the leftmost element.| 97 98## Example 99 100```ts 101// xxx.ets 102class MyDataSource implements IDataSource { 103 private list: number[] = [] 104 private listener: DataChangeListener 105 106 constructor(list: number[]) { 107 this.list = list 108 } 109 110 totalCount(): number { 111 return this.list.length 112 } 113 114 getData(index: number): any { 115 return this.list[index] 116 } 117 118 registerDataChangeListener(listener: DataChangeListener): void { 119 this.listener = listener 120 } 121 122 unregisterDataChangeListener() { 123 } 124} 125 126@Entry 127@Component 128struct SwiperExample { 129 private swiperController: SwiperController = new SwiperController() 130 private data: MyDataSource = new MyDataSource([]) 131 132 aboutToAppear(): void { 133 let list = [] 134 for (var i = 1; i <= 10; i++) { 135 list.push(i.toString()); 136 } 137 this.data = new MyDataSource(list) 138 } 139 140 build() { 141 Column({ space: 5 }) { 142 Swiper(this.swiperController) { 143 LazyForEach(this.data, (item: string) => { 144 Text(item).width('90%').height(160).backgroundColor(0xAFEEEE).textAlign(TextAlign.Center).fontSize(30) 145 }, item => item) 146 } 147 .cachedCount(2) 148 .index(1) 149 .autoPlay(true) 150 .interval(4000) 151 .indicator(true) 152 .loop(true) 153 .duration(1000) 154 .itemSpace(0) 155 .curve(Curve.Linear) 156 .onChange((index: number) => { 157 console.info(index.toString()) 158 }) 159 160 Row({ space: 12 }) { 161 Button('showNext') 162 .onClick(() => { 163 this.swiperController.showNext() 164 }) 165 Button('showPrevious') 166 .onClick(() => { 167 this.swiperController.showPrevious() 168 }) 169 }.margin(5) 170 }.width('100%') 171 .margin({ top: 5 }) 172 } 173} 174``` 175 176 177
