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> When the **\<Swiper>** component's **displayMode** attribute is set to **SwiperDisplayMode.AutoLinear** or its **displayCount** attribute is set to **'auto'**, the child component whose **visibility** attribute is set to **None** does not take up space in the viewport, but this does not affect the number of navigation dots. 19> 20> If the child component has the **visibility** attribute set to **None** or **Hidden**, it takes up space in the viewport, but is not displayed. 21> 22> When the number of child components is less than or equal to the total number of allowed nodes (totalDisplayCount = DisplayCount + prevMargin? (1: 0 ) + nextMargin? (1: 0 )) in the content area, the **\<Swiper>** component uses the non-looping mode for layout. In this case, the child components specified by **nextMargin** and **prevMargin** take up space in the viewport, but are not displayed. The specifications of the **\<Swiper>** component are calculated based on the value of **totalDisplayCount**. 23> 24> Child components of the **\<Swiper>** component are drawn based on their level if they have the **offset** attribute set. A child component with a higher level overwrites one with a lower level. For example, if the **\<Swiper>** contains three child components and **offset({ x: 100 })** is set for the third child component, the third child component overwrites the first child component during horizontal loop playback. To prevent the first child component from being overwritten, set its **zIndex** attribute to a value greater than that of the third child component. 25 26 27## APIs 28 29Swiper(controller?: SwiperController) 30 31**Parameters** 32 33| Name | Type | Mandatory | Description | 34| ---------- | ------------------------------------- | ---- | -------------------- | 35| controller | [SwiperController](#swipercontroller) | No | Controller bound to the component to control the page switching.| 36 37 38## Attributes 39 40In 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. 41 42| Name | Type | Description | 43| ------------------------------------- | ---------------------------------------- | ---------------------------------------- | 44| 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.<br>Since API version 10, this attribute supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.| 45| 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.| 46| interval | number | Interval for automatic playback, in ms.<br>Default value: **3000** | 47| indicator | [DotIndicator](#dotindicator10)<sup>10+</sup> \| [DigitIndicator](#digitindicator10)<sup>10+</sup> \| boolean | Style of the navigation point indicator.<br> \- **DotIndicator**: dot style.<br> \- **DigitIndicator**: digit style.<br> \- **boolean**: whether to enable the navigation point indicator.<br> Default value: **true**<br> Default type: **DotIndicator**| 48| 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**| 49| duration | number | Duration of the animation for switching child components, in ms.<br>Default value: **400** | 50| vertical | boolean | Whether vertical swiping is used.<br>Default value: **false** | 51| itemSpace | number \| string | Space between child components.<br>Default value: **0**<br>**NOTE**<br>This parameter cannot be set in percentage.<br>If the type is number, the default unit is vp. If the type is string, the pixel unit must be explicitly specified, for example, '10px'.| 52| displayMode | [SwiperDisplayMode](#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**| 53| cachedCount<sup>8+</sup> | number | Number of child components to be cached.<br>Default value: **1**| 54| disableSwipe<sup>8+</sup> | boolean | Whether to disable the swipe feature.<br>Default value: **false** | 55| curve<sup>8+</sup> | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../apis/js-apis-curve.md#icurve)<sup>10+</sup>| Animation curve. The linear 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**| 56| indicatorStyle<sup>(deprecated)</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#resourcecolor),<br>selectedColor?: [ResourceColor](ts-types.md#resourcecolor)<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.<br>This API is supported since API version 8 and is deprecated since API version 10. You are advised to use [indicator](#indicator10) instead.| 57| displayCount<sup>8+</sup> | number \| string \| <br>[SwiperAutoFill](#swiperautofill10)<sup>10+</sup> | 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 set to a number less than or equal to 0, the default value **1** is used.<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.<br> If the value is of the SwiperAutoFill type, the system automatically calculates and changes the number of elements to display per page based on the **\<Swiper>** component width and the **minSize** settings for the child component. If **minSize** is left empty or set to a value less than or equal to 0, the **\<Swiper>** component displays one column.| 58| effectMode<sup>8+</sup> | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Effect when the component is at one of the edges. This parameter is effective only when **loop** is set to **false**. For details about the supported effects, see the **EdgeEffect** enums.<br>Default value: **EdgeEffect.Spring**<br>**NOTE**<br>The spring effect does not take effect when the controller API is called.| 59| displayArrow<sup>10+</sup> | value:[ArrowStyle](#arrowstyle10) \| boolean,<br>isHoverShow?: boolean | Arrow style of the navigation point indicator.<br>- **value**: arrow and background to set. In abnormal scenarios, the default values in the **ArrowStyle** object are used.<br>\- **isHoverShow**: whether to show the arrow only when the mouse pointer hovers over the navigation point indicator.<br>Default value: **false**<br>**NOTE**<br>When **isHoverShow** is set to **false**, the arrow is always displayed and can be clicked to turn pages.<br>When **isHoverShow** is set to **true**, the arrow is displayed only when the mouse pointer hovers over the navigation point indicator, and it can be clicked to turn pages.| 60| nextMargin<sup>10+</sup> | <br>[Length](ts-types.md#length)<br>| Next margin, used to reveal a small part of the next item.<br>Default value: **0**<br>**NOTE**<br>This attribute is available only when **SwiperDisplayMode** is set to **STRETCH**.<br>When the main axis runs horizontally and either the next margin or previous margin is greater than the calculated width of the child component, neither the next margin nor previous margin is displayed.<br>When the main axis runs vertically and either the next margin or previous margin is greater than the calculated height of the child component, neither the next margin nor previous margin is displayed.| 61| prevMargin<sup>10+</sup> | <br>[Length](ts-types.md#length)<br>| Previous margin, used to reveal a small part of the previous item.<br>Default value: **0**<br>**NOTE**<br>This attribute is available only when **SwiperDisplayMode** is set to **STRETCH**.<br>When the main axis runs horizontally and either the next margin or previous margin is greater than the calculated width of the child component, neither the next margin nor previous margin is displayed.<br>When the main axis runs vertically and either the next margin or previous margin is greater than the calculated height of the child component, neither the next margin nor previous margin is displayed.| 62 63## SwiperDisplayMode 64 65| Name | Description | 66| --------------------------------- | ---------------------------------------- | 67| Stretch<sup>(deprecated)</sup> | The slide width of the **\<Swiper>** component is equal to the width of the component.<br>This API is deprecated since API version 10. You are advised to use **STRETCH** instead.| 68| AutoLinear<sup>(deprecated)</sup> | The slide width of the **\<Swiper>** component is equal to that of the child component with the maximum width.<br>This API is deprecated since API version 10. You are advised to use **AUTO_LINEAR** instead.| 69| STRETCH<sup>10+</sup> | The slide width of the **\<Swiper>** component is equal to the width of the component. | 70| AUTO_LINEAR<sup>10+</sup> | The slide width of the **\<Swiper>** component is equal to the width of the leftmost child component in the viewport. | 71 72## SwiperController 73 74Controller of the **\<Swiper>** component. You can bind this object to the **\<Swiper>** component and use it to control page switching. 75 76### Objects to Import 77 78```ts 79let controller: SwiperController = new SwiperController() 80``` 81 82### showNext 83 84showNext(): void 85 86Turns to the next page. Page turning occurs with the animation, whose duration is specified by **duration**. 87 88### showPrevious 89 90showPrevious(): void 91 92Turns to the previous page. Page turning occurs with the animation, whose duration is specified by **duration**. 93 94### finishAnimation 95 96finishAnimation(callback?: () => void): void 97 98Stops an animation. 99 100**Parameters** 101 102| Name | Type | Mandatory. | Description | 103| -------- | ---------- | ---- | -------- | 104| callback | () => void | No | Callback invoked when the animation stops.| 105 106## Indicator<sup>10+</sup> 107 108Sets the distance between the navigation point indicator and the **\<Swiper>** component. 109 110| Name | Type | Mandatory. | Description | 111| ------ | ---------------------------- | ---- | ---------------------------------------- | 112| left | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the left edge of the **\<Swiper>** component.<br>Default value: **0**<br>Unit: vp| 113| top | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the top edge of the **\<Swiper>** component.<br>Default value: **0**<br>Unit: vp| 114| right | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the right edge of the **\<Swiper>** component.<br>Default value: **0**<br>Unit: vp| 115| bottom | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the bottom edge of the **\<Swiper>** component.<br>Default value: **0**<br>Unit: vp| 116| static dot | - | No | **DotIndicator** object returned.| 117| static digit | - | No | **DigitIndicator** object returned.| 118 119## DotIndicator<sup>10+</sup> 120 121Defines the navigation point indicator of the dot style, which inherits attributes and features from **Indicator**. 122 123| Name | Type | Mandatory. | Description | 124| ------------------ | ---------------------------------------- | ---- | ---------------------------------------- | 125| itemWidth | [Length](ts-types.md#length) | No | Width of the navigation point indicator of the dot style. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp| 126| itemHeight | [Length](ts-types.md#length) | No | Height of the navigation point indicator of the dot style. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp| 127| selectedItemWidth | [Length](ts-types.md#length) | No | Width of the selected navigation point indicator of the dot style. This parameter cannot be set in percentage.<br>Default value: **12**<br>Unit: vp| 128| selectedItemHeight | [Length](ts-types.md#length) | No | Height of the selected navigation point indicator of the dot style. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp| 129| mask | boolean | No | Whether to enable the mask for the navigation point indicator of the dot style.<br>Default value: **false**| 130| color | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the navigation point indicator of the dot style.<br>Default value: **'\#182431'** (10% opacity)| 131| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the selected indicator dot.<br>Default value: **'\#007DFF'**| 132 133>**NOTE** 134> 135>When pressed, the navigation point indicator is zoomed in by 1.33 times. To account for this, there is a certain distance between the navigation point indicator's visible boundary and its actual boundary in the non-pressed state. The distance increases with the value of **itemWidth**, **itemHeight**, **selectedItemWidth**, and **selectedItemHeight**. 136 137## DigitIndicator<sup>10+</sup> 138 139Defines the navigation point indicator of the digit style, which inherits attributes and features from **Indicator**. 140 141| Name | Type | Mandatory. | Description | 142| ----------------- | ---------------------------------------- | ---- | ---------------------------------------- | 143| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the navigation point indicator of the digit style.<br>Default value: **'\#ff182431'**| 144| selectedFontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the selected navigation point indicator of the digit style.<br>Default value: **'\#ff182431'**| 145| digitFont | {<br>size?:[Length](ts-types.md#length)<br>weight?:number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string<br>} | No | Font style of the navigation point indicator of the digit style.<br>\- **size**:font size. It cannot be set in percentage.<br>Default value: **14vp**<br>\- **weight**: font weight.| 146| selectedDigitFont | {<br>size?:[Length](ts-types.md#length)<br>weight?:number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string<br>} | No | Font style of the selected navigation point indicator of the digit style.<br>\- **size**:font size. It cannot be set in percentage.<br>Default value: **14vp**<br>\- **weight**: font weight.| 147 148## ArrowStyle<sup>10+</sup> 149Describes the left and right arrow attributes. 150 151| Name | Type | Mandatory. | Description | 152| ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | 153| showBackground | boolean | No | Whether to show the background for the arrow.<br>Default value: **false** | 154| isSidebarMiddle | boolean | No | Whether the arrow is shown on either side of the navigation point indicator.<br>Default value: **false** (the arrow is shown on either side of the navigation point indicator)| 155| backgroundSize | [Length](ts-types.md#length) | No | Size of the background.<br>On both sides of the navigation point indicator:<br>Default value: **24vp**<br>On both sides of the component:<br>Default value: **32vp**<br>This parameter cannot be set in percentage.| 156| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the background.<br>On both sides of the navigation point indicator:<br>Default value: **'\#00000000'**<br>On both sides of the component:<br>Default value: **'\#19182431'**| 157| arrowSize | [Length](ts-types.md#length) | No | Size of the arrow.<br>On both sides of the navigation point indicator:<br>Default value: **18vp**<br>On both sides of the component:<br>Default value: **24vp**<br>**NOTE**<br>If **showBackground** is set to **true**, the value of **arrowSize** is 3/4 of the value of **backgroundSize**.<br>This parameter cannot be set in percentage.| 158| arrowColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the arrow.<br>Default value: **'\#182431'** | 159 160## SwiperAutoFill<sup>10+</sup> 161 162Describes the auto-fill attribute. 163 164| Name | Type | Mandatory.| Description | 165| ------- | -------------------- | ------ | ------------------------------------ | 166| minSize | [VP](ts-types.md#vp10) | Yes | Minimum width of the element.<br>Default value: **0**| 167 168## Events 169 170In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 171 172| Name | Description | 173| ---------------------------------------- | ---------------------------------------- | 174| 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.| 175| onAnimationStart<sup>9+</sup>(event: (index: number, targetIndex<sup>10+</sup>: number, extraInfo<sup>10+</sup>: [SwiperAnimationEvent](ts-types.md#swiperanimationevent10)) => void) | Triggered when the switching animation starts.<br>- **index**: index of the currently displayed element.<br>- **targetIndex**: index of the target element to switch to.<br>- **extraInfo**: extra information of the animation, including the offset of the currently displayed element and target element relative to the start position of the **\<Swiper>** along the main axis, and the hands-off velocity.<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.| 176| onAnimationEnd<sup>9+</sup>(event: (index: number, extraInfo: [SwiperAnimationEvent](ts-types.md#swiperanimationevent10)) => void) | Triggered when the switching animation ends.<br>- **index**: index of the currently displayed element.<br>- **extraInfo**: extra information of the animation, which is the offset of the currently displayed element relative to the start position of the **\<Swiper>** along the main axis.<br>**NOTE**<br>This event is triggered when the switching animation of the **\<Swiper>** component ends, whether it is caused by gesture interruption or by calling **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.| 177| onGestureSwipe<sup>10+</sup>(event: (index: number, extraInfo: [SwiperAnimationEvent](ts-types.md#swiperanimationevent10)) => void) | Triggered on a frame-by-frame basis when the page is turned by a swipe.<br>- **index**: index of the currently displayed element.<br>- **extraInfo**: extra information of the animation, which is the offset of the currently displayed element relative to the start position of the **\<Swiper>** along the main axis.<br>**NOTE**<br>If there are multiple columns, **index** indicates the index of the leftmost component.| 178 179## Example 180 181### Example 1 182```ts 183// xxx.ets 184class MyDataSource implements IDataSource { 185 private list: number[] = [] 186 187 constructor(list: number[]) { 188 this.list = list 189 } 190 191 totalCount(): number { 192 return this.list.length 193 } 194 195 getData(index: number): number { 196 return this.list[index] 197 } 198 199 registerDataChangeListener(listener: DataChangeListener): void { 200 } 201 202 unregisterDataChangeListener() { 203 } 204} 205 206@Entry 207@Component 208struct SwiperExample { 209 private swiperController: SwiperController = new SwiperController() 210 private data: MyDataSource = new MyDataSource([]) 211 212 aboutToAppear(): void { 213 let list: number[] = [] 214 for (let i = 1; i <= 10; i++) { 215 list.push(i); 216 } 217 this.data = new MyDataSource(list) 218 } 219 220 build() { 221 Column({ space: 5 }) { 222 Swiper(this.swiperController) { 223 LazyForEach(this.data, (item: string) => { 224 Text(item.toString()) 225 .width('90%') 226 .height(160) 227 .backgroundColor(0xAFEEEE) 228 .textAlign(TextAlign.Center) 229 .fontSize(30) 230 }, (item: string) => item) 231 } 232 .cachedCount(2) 233 .index(1) 234 .autoPlay(true) 235 .interval(4000) 236 .loop(true) 237 .duration(1000) 238 .itemSpace(0) 239 .indicator( // Set the style of the navigation point indicator. 240 new DotIndicator() 241 .itemWidth(15) 242 .itemHeight(15) 243 .selectedItemWidth(15) 244 .selectedItemHeight(15) 245 .color(Color.Gray) 246 .selectedColor(Color.Blue)) 247 .displayArrow({ // Set the arrow style of the navigation point indicator. 248 showBackground: true, 249 isSidebarMiddle: true, 250 backgroundSize: 24, 251 backgroundColor: Color.White, 252 arrowSize: 18, 253 arrowColor: Color.Blue 254 }, false) 255 .curve(Curve.Linear) 256 .onChange((index: number) => { 257 console.info(index.toString()) 258 }) 259 .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => { 260 console.info("index: " + index) 261 console.info("current offset: " + extraInfo.currentOffset) 262 }) 263 .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => { 264 console.info("index: " + index) 265 console.info("targetIndex: " + targetIndex) 266 console.info("current offset: " + extraInfo.currentOffset) 267 console.info("target offset: " + extraInfo.targetOffset) 268 console.info("velocity: " + extraInfo.velocity) 269 }) 270 .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => { 271 console.info("index: " + index) 272 console.info("current offset: " + extraInfo.currentOffset) 273 }) 274 275 Row({ space: 12 }) { 276 Button('showNext') 277 .onClick(() => { 278 this.swiperController.showNext() 279 }) 280 Button('showPrevious') 281 .onClick(() => { 282 this.swiperController.showPrevious() 283 }) 284 }.margin(5) 285 }.width('100%') 286 .margin({ top: 5 }) 287 } 288} 289``` 290 291 292 293### Example 2 294```ts 295// xxx.ets 296class MyDataSource implements IDataSource { 297 private list: number[] = [] 298 299 constructor(list: number[]) { 300 this.list = list 301 } 302 303 totalCount(): number { 304 return this.list.length 305 } 306 307 getData(index: number): number { 308 return this.list[index] 309 } 310 311 registerDataChangeListener(listener: DataChangeListener): void { 312 } 313 314 unregisterDataChangeListener() { 315 } 316} 317 318@Entry 319@Component 320struct SwiperExample { 321 private swiperController: SwiperController = new SwiperController() 322 private data: MyDataSource = new MyDataSource([]) 323 324 aboutToAppear(): void { 325 let list: number[] = [] 326 for (let i = 1; i <= 10; i++) { 327 list.push(i); 328 } 329 this.data = new MyDataSource(list) 330 } 331 332 build() { 333 Column({ space: 5 }) { 334 Swiper(this.swiperController) { 335 LazyForEach(this.data, (item: string) => { 336 Text(item.toString()) 337 .width('90%') 338 .height(160) 339 .backgroundColor(0xAFEEEE) 340 .textAlign(TextAlign.Center) 341 .fontSize(30) 342 }, (item: string) => item) 343 } 344 .cachedCount(2) 345 .index(1) 346 .autoPlay(true) 347 .interval(4000) 348 .indicator(Indicator.digit() // Set the navigation point indicator of the digit style. 349 .right("43%") 350 .top(200) 351 .fontColor(Color.Gray) 352 .selectedFontColor(Color.Gray) 353 .digitFont({ size: 20, weight: FontWeight.Bold }) 354 .selectedDigitFont({ size: 20, weight: FontWeight.Normal })) 355 .loop(true) 356 .duration(1000) 357 .itemSpace(0) 358 .displayArrow(true, false) 359 360 Row({ space: 12 }) { 361 Button('showNext') 362 .onClick(() => { 363 this.swiperController.showNext() 364 }) 365 Button('showPrevious') 366 .onClick(() => { 367 this.swiperController.showPrevious() 368 }) 369 }.margin(5) 370 }.width('100%') 371 .margin({ top: 5 }) 372 } 373} 374``` 375 376
