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> - The default value of the universal attribute [clip](ts-universal-attributes-sharp-clipping.md) is **true** for the **Swiper** component. 10 11 12## Child Components 13 14This component can contain child components. 15 16> **NOTE** 17> 18> - Supported types of child components: built-in components and custom components, with support for rendering control with [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), or [Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md). 19> 20> - If a child component has its **visibility** attribute set to **None** and the **Swiper** component has its **displayCount** attribute set to **'auto'**, the child component takes up space in the viewport, but is not displayed. 21> 22> - If a child component has its **visibility** attribute set to **None** or **Hidden**, it takes up space in the viewport, but is not displayed. 23> 24> - When the number of child components is less than or equal to the total number of allowed nodes in the content area (totalDisplayCount = displayCount + prevMargin? (1 : 0 ) + nextMargin? (1 : 0 )), the **Swiper** component generally 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**. The exceptions are as follows: 25> 26> - When the number of child components is equal to the total number of allowed nodes in the content area and both **prevMargin** and **nextMargin** take effect, set **loop** to **true** to enable loop playback. 27> 28> - When the number of child components is equal to the value of **displayCount** plus 1 and at least one of **prevMargin** and **nextMargin** takes effect, set **loop** to **true** to enable loop playback. When loop playback is enabled, a snapshot is generated as the placeholder image. (The snapshot may not be correctly generated for those components that take a long time to display, such as those that use asynchronous image loading. Avoid enabling loop playback under this scenario.) 29> 30> - 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. 31> 32> - Do not add or delete child components during a page turning animation. Doing so may result in child components not yet animated entering the viewport in advance and causing display exceptions. 33 34## APIs 35 36Swiper(controller?: SwiperController) 37 38**Widget capability**: This API can be used in ArkTS widgets since API version 10. 39 40**Atomic service API**: This API can be used in atomic services since API version 11. 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44**Parameters** 45 46| Name | Type | Mandatory | Description | 47| ---------- | ------------------------------------- | ---- | -------------------- | 48| controller | [SwiperController](#swipercontroller) | No | Controller bound to the component to control the page turning.| 49 50 51## Attributes 52 53In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 54 55### index 56 57index(value: number) 58 59Sets the index of the child component currently displayed in the container. If the value is less than 0 or greater than or equal to the number of child components, the default value **0** is used. 60 61Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). 62 63**Widget capability**: This API can be used in ArkTS widgets since API version 10. 64 65**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69**Parameters** 70 71| Name| Type | Mandatory| Description | 72| ------ | ------ | ---- | ------------------------------------------------ | 73| value | number | Yes | Index of the child component currently displayed in the container.<br>Default value: **0**| 74 75### autoPlay 76 77autoPlay(value: boolean) 78 79Sets whether to enable automatic playback for child component switching. 80 81If **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. 82 83**Widget capability**: This API can be used in ArkTS widgets since API version 10. 84 85**Atomic service API**: This API can be used in atomic services since API version 11. 86 87**System capability**: SystemCapability.ArkUI.ArkUI.Full 88 89**Parameters** 90 91| Name| Type | Mandatory| Description | 92| ------ | ------- | ---- | -------------------------------------- | 93| value | boolean | Yes | Whether to enable automatic playback for child component switching.<br>Default value: **false**| 94 95### interval 96 97interval(value: number) 98 99Sets the interval for automatic playback. 100 101**Widget capability**: This API can be used in ArkTS widgets since API version 10. 102 103**Atomic service API**: This API can be used in atomic services since API version 11. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107**Parameters** 108 109| Name| Type | Mandatory| Description | 110| ------ | ------ | ---- | ---------------------------------------------------------- | 111| value | number | Yes | Interval for automatic playback.<br>Default value: **3000**<br>Unit: ms| 112 113### indicator 114 115indicator(value: DotIndicator | DigitIndicator | boolean) 116 117Sets the style of the navigation point indicator. 118 119**Widget capability**: This API can be used in ArkTS widgets since API version 10. 120 121**Atomic service API**: This API can be used in atomic services since API version 11. 122 123**System capability**: SystemCapability.ArkUI.ArkUI.Full 124 125**Parameters** 126 127| Name| Type | Mandatory| Description | 128| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 129| value | [DotIndicator](#dotindicator10)<sup>10+</sup> \| [DigitIndicator](#digitindicator10)<sup>10+</sup> \| boolean | Yes | Style of the navigation point indicator.<br> \- **DotIndicator**: dot style.<br> \- **DigitIndicator**: digit style.<br> \- **boolean**: whether to enable the navigation point indicator. The value **true** means to enable the feature, and **false** means the opposite.<br> Default value: **true**<br> Default style: **DotIndicator**| 130 131### loop 132 133loop(value: boolean) 134 135Sets whether to enable loop playback. 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. 136 137**Widget capability**: This API can be used in ArkTS widgets since API version 10. 138 139**Atomic service API**: This API can be used in atomic services since API version 11. 140 141**System capability**: SystemCapability.ArkUI.ArkUI.Full 142 143**Parameters** 144 145| Name| Type | Mandatory| Description | 146| ------ | ------- | ---- | ------------------------------- | 147| value | boolean | Yes | Whether to enable loop playback.<br>Default value: **true**| 148 149### duration 150 151duration(value: number) 152 153Sets the duration of the animation for child component switching. 154 155**duration** must be used in conjunction with [curve](#curve8). 156 157The default curve for the animation is [interpolatingSpring](../js-apis-curve.md#curvesinterpolatingspring10).When this curve is applied, the duration of the animation is determined solely by the parameters of the curve itself and is no longer governed by the **duration** setting. For curves that are not governed by the **duration** setting, see [Interpolation Calculation](../js-apis-curve.md). 158Such curves include [springMotion](../js-apis-curve.md#curvesspringmotion9), [responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9), and **interpolatingSpring**. To have the animation duration managed by **duration**, you should select a different curve for the **curve** attribute. 159 160**Atomic service API**: This API can be used in atomic services since API version 11. 161 162**System capability**: SystemCapability.ArkUI.ArkUI.Full 163 164**Parameters** 165 166| Name| Type | Mandatory| Description | 167| ------ | ------ | ---- | ----------------------------------------------------- | 168| value | number | Yes | Duration of the autoplay for child component switching.<br>Default value: **400**<br>Unit: ms| 169 170### vertical 171 172vertical(value: boolean) 173 174Sets whether vertical swiping is used. 175 176**Widget capability**: This API can be used in ArkTS widgets since API version 10. 177 178**Atomic service API**: This API can be used in atomic services since API version 11. 179 180**System capability**: SystemCapability.ArkUI.ArkUI.Full 181 182**Parameters** 183 184| Name| Type | Mandatory| Description | 185| ------ | ------- | ---- | ---------------------------------- | 186| value | boolean | Yes | Whether vertical swiping is used. The value **true** means vertical swiping, and **false** means horizontal swiping.<br>Default value: **false**| 187 188### itemSpace 189 190itemSpace(value: number | string) 191 192Sets the space between child components. This attribute cannot be set in percentage. 193 194If the type is number, the default unit is vp. If the type is string, the pixel unit must be explicitly specified, for example, **'10px'**; if the unit is not specified, for example, **'10'**, the default unit vp is used. 195 196**Widget capability**: This API can be used in ArkTS widgets since API version 10. 197 198**Atomic service API**: This API can be used in atomic services since API version 11. 199 200**System capability**: SystemCapability.ArkUI.ArkUI.Full 201 202**Parameters** 203 204| Name| Type | Mandatory| Description | 205| ------ | -------------------------- | ---- | -------------------------------------- | 206| value | number \| string | Yes | Space between child components.<br>Default value: **0**| 207 208### displayMode 209 210displayMode(value: SwiperDisplayMode) 211 212Sets the mode in which elements are displayed along the main axis. This API takes effect only when **displayCount** is not set. 213 214**Widget capability**: This API can be used in ArkTS widgets since API version 10. 215 216**Atomic service API**: This API can be used in atomic services since API version 11. 217 218**System capability**: SystemCapability.ArkUI.ArkUI.Full 219 220**Parameters** 221 222| Name| Type | Mandatory| Description | 223| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 224| value | [SwiperDisplayMode](#swiperdisplaymode) | Yes | Mode in which elements are displayed along the main axis.<br>Default value: **SwiperDisplayMode.STRETCH**| 225 226### cachedCount<sup>8+</sup> 227 228cachedCount(value: number) 229 230Sets the number of child components to be preloaded (cached), which are needed for the specific number of pages immediately before and after the current page. For example, if **cachedCount** is set to **1**, the child components on the previous page and the next page are cached. If **swipeByGroup** in **displayCount** is set to **true**, child components are cached by group. For example, if **cachedCount** is set to **1** and **swipeByGroup** is set to **true**, the child components in the previous and next groups are cached. 231 232**Widget capability**: This API can be used in ArkTS widgets since API version 10. 233 234**Atomic service API**: This API can be used in atomic services since API version 11. 235 236**System capability**: SystemCapability.ArkUI.ArkUI.Full 237 238**Parameters** 239 240| Name| Type | Mandatory| Description | 241| ------ | ------ | ---- | -------------------------------- | 242| value | number | Yes | Number of child components to be preloaded (cached).<br>Default value: **1**| 243 244### disableSwipe<sup>8+</sup> 245 246disableSwipe(value: boolean) 247 248Sets whether to disable the swipe feature. 249 250**Widget capability**: This API can be used in ArkTS widgets since API version 10. 251 252**Atomic service API**: This API can be used in atomic services since API version 11. 253 254**System capability**: SystemCapability.ArkUI.ArkUI.Full 255 256**Parameters** 257 258| Name| Type | Mandatory| Description | 259| ------ | ------- | ---- | ---------------------------------------- | 260| value | boolean | Yes | Whether to disable the swipe feature. The value **true** means to disable the feature, and **false** means the opposite.<br>Default value: **false**| 261 262### curve<sup>8+</sup> 263 264curve(value: Curve | string | ICurve) 265 266Sets the animation curve. The interpolating spring 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](../js-apis-curve.md) module. 267 268**Widget capability**: This API can be used in ArkTS widgets since API version 10. 269 270**Atomic service API**: This API can be used in atomic services since API version 11. 271 272**System capability**: SystemCapability.ArkUI.ArkUI.Full 273 274**Parameters** 275 276| Name| Type | Mandatory| Description | 277| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------- | 278| value | [Curve](ts-appendix-enums.md#curve) \| string \| [ICurve](../js-apis-curve.md#icurve9)<sup>10+</sup> | Yes | Animation curve.<br>Default value: **interpolatingSpring(-1, 1, 328, 34)**| 279 280### indicatorStyle<sup>(deprecated)</sup> 281 282indicatorStyle(value?: IndicatorStyle) 283 284Sets the style of the navigation point indicator. 285 286This API is supported since API version 8 and is deprecated since API version 10. You are advised to use [indicator](#indicator10) instead. 287 288**System capability**: SystemCapability.ArkUI.ArkUI.Full 289 290**Parameters** 291 292| Name| Type | Mandatory| Description | 293| ------ | --------------------------------------------------- | ---- | ------------ | 294| value | [IndicatorStyle](#indicatorstyledeprecated) | No | Style of the navigation point indicator.| 295 296### displayCount<sup>8+</sup> 297 298displayCount(value: number | string | SwiperAutoFill, swipeByGroup?: boolean) 299 300Sets the number of elements to display per page. 301 302For the string type, this attribute can only be set to **'auto'**. 303 304If the value is set to a number less than or equal to 0, the default value **1** is used. 305 306If 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. 307 308If the value is of the SwiperAutoFill type, the system automatically works out the value based on the width and **minSize** settings of the **Swiper** component. If **minSize** is left empty or set to a value less than or equal to 0, the **Swiper** component displays one column. 309 310With page turning by group, placeholders are used if the number of child elements in the last group is less than the value of **displayCount**. Such placeholders are used to reserve space in the layout and does not display any content. The background style of the **Swiper** is applied to where the placeholders are displayed. 311 312With page turning by group, the drag distance threshold for page turning is half of the width of the **Swiper** component. (With page turning by child element, the threshold is half of the width of the child element.) 313 314**Widget capability**: This API can be used in ArkTS widgets since API version 10. 315 316**Atomic service API**: This API can be used in atomic services since API version 11. 317 318**System capability**: SystemCapability.ArkUI.ArkUI.Full 319 320**Parameters** 321 322| Name | Type | Mandatory| Description | 323| -------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 324| value | number \| string \| [SwiperAutoFill](#swiperautofill10)<sup>10+</sup> | Yes | Number of elements to display per page.<br> Default value: **1** | 325| swipeByGroup<sup>11+</sup> | boolean | No | Whether to turn pages by group. The value **true** means to turn pages by group, and **false** means to turn pages by child element. With page turning by group, the number of child elements per group is the value of **displayCount**.<br> Default value: **false**| 326 327### effectMode<sup>8+</sup> 328 329effectMode(value: EdgeEffect) 330 331Sets the effect used when the component is at one of the edges. This attribute takes effect when **loop** is set to **false**. For details about the supported effects, see the **EdgeEffect** enums. The spring effect does not take effect when the controller API is called. 332 333**Widget capability**: This API can be used in ArkTS widgets since API version 10. 334 335**Atomic service API**: This API can be used in atomic services since API version 11. 336 337**System capability**: SystemCapability.ArkUI.ArkUI.Full 338 339**Parameters** 340 341| Name| Type | Mandatory| Description | 342| ------ | --------------------------------------------- | ---- | -------------------------------------------- | 343| value | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Yes | Effect used when the component is at one of the edges.<br>Default value: **EdgeEffect.Spring**| 344 345### displayArrow<sup>10+</sup> 346 347displayArrow(value: ArrowStyle | boolean, isHoverShow?: boolean) 348 349Sets the arrow style of the navigation point indicator. 350 351**Atomic service API**: This API can be used in atomic services since API version 11. 352 353**System capability**: SystemCapability.ArkUI.ArkUI.Full 354 355**Parameters** 356 357| Name | Type | Mandatory| Description | 358| -------------------------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 359| value | [ArrowStyle](#arrowstyle10) \| boolean | Yes | Arrow and background to set. In cases of exceptions, the default values in the **ArrowStyle** object are used. The value **true** means to show the arrow and background in the default styles, and **false** means to hide the arrow and background.<br>Default value: **false**| 360| isHoverShow | boolean | No | 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.| 361 362### nextMargin<sup>10+</sup> 363 364nextMargin(value: Length, ignoreBlank?:boolean) 365 366Sets the next margin, used to reveal a small part of the next item. This attribute is effective only when the layout mode of the child components in **Swiper** is set to stretch, which mainly includes two scenarios: 1. **displayMode** is set to **SwiperDisplayMode.STRETCH**; 2. **displayCount** is assigned a numeric value. 367 368When the main axis runs horizontally and either the next margin or previous margin is greater than the measured width of the child component, neither the next margin nor previous margin is displayed. 369 370When the main axis runs vertically and either the next margin or previous margin is greater than the measured height of the child component, neither the next margin nor previous margin is displayed. 371 372**Atomic service API**: This API can be used in atomic services since API version 11. 373 374**System capability**: SystemCapability.ArkUI.ArkUI.Full 375 376**Parameters** 377 378| Name| Type | Mandatory| Description | 379| ------ | ---------------------------- | ---- | ---------------------- | 380| value | [Length](ts-types.md#length) | Yes | Next margin.<br>Default value: **0**| 381| ignoreBlank<sup>12+</sup> | boolean | No | Whether to hide (ignore) the next margin on the last page in non-loop scenarios.<br> **true**: The last page does not show the next margin, and the right edge of the last page is aligned with that of the **Swiper**'s viewable area.<br>**false**: The last page displays the next margin, and the distance between the right edge of the last page and that of the **Swiper**'s viewable area is equal to the next margin.<br>Default value: **false**<br>**NOTE**<br>On the last page, the values of **prevMargin** and **nextMargin** are added to create a left margin that allows the previous page to be displayed partially.| 382 383### prevMargin<sup>10+</sup> 384 385prevMargin(value: Length, ignoreBlank?:boolean) 386 387Sets the previous margin, used to reveal a small part of the previous item. This attribute is effective only when the layout mode of the child components in **Swiper** is set to stretch, which mainly includes two scenarios: 1. **displayMode** is set to **SwiperDisplayMode.STRETCH**; 2. **displayCount** is assigned a numeric value. 388 389When the main axis runs horizontally and either the next margin or previous margin is greater than the measured width of the child component, neither the next margin nor previous margin is displayed. 390 391When the main axis runs vertically and either the next margin or previous margin is greater than the measured height of the child component, neither the next margin nor previous margin is displayed. 392 393**Atomic service API**: This API can be used in atomic services since API version 11. 394 395**System capability**: SystemCapability.ArkUI.ArkUI.Full 396 397**Parameters** 398 399| Name| Type | Mandatory| Description | 400| ------ | ---------------------------- | ---- | ---------------------- | 401| value | [Length](ts-types.md#length) | Yes | Previous margin.<br>Default value: **0**| 402| ignoreBlank<sup>12+</sup> | boolean | No | Whether to hide (ignore) the previous margin on the first page in non-loop scenarios.<br> **true**: The first page does not show the previous margin, and the left edge of the first page is align with that of the **Swiper**'s viewable area.<br>**false**: The first page displays the previous margin, and the distance between the left edge of the first page and that of the **Swiper**'s viewable area is equal to the previous margin.<br>Default value: **false**<br>**NOTE**<br>On the first page, the values of **prevMargin** and **nextMargin** are added to create a right margin that allows the next page to be displayed partially.| 403 404### nestedScroll<sup>11+</sup> 405 406nestedScroll(value: SwiperNestedScrollMode) 407 408Sets the nested scrolling mode of the **Swiper** component and its parent container. When **loop** is set to **true**, the **Swiper** component has no edge effect and does not trigger nested scrolling of its parent container. 409 410**Atomic service API**: This API can be used in atomic services since API version 11. 411 412**System capability**: SystemCapability.ArkUI.ArkUI.Full 413 414**Parameters** 415 416| Name| Type | Mandatory| Description | 417| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 418| value | [SwiperNestedScrollMode](#swipernestedscrollmode11) | Yes | Nested scrolling mode of the **Swiper** component and its parent container.<br>Default value: **SwiperNestedScrollMode.SELF_ONLY**| 419 420> **NOTE** 421> 422> The **Swiper** component's flick animation logic differs from other scrollable components, as **Swiper** can only slide one page at a time and performs a page-flip animation during a flick. When a **Swiper** component is nested with other scrollable components, it will not accept the scroll offset values transmitted by its child nodes after its page-turning animation has already started. At this point, the page-turning animation of the **Swiper** and the edge effect animation of the child node will be executed simultaneously. 423 424### indicatorInteractive<sup>12+</sup> 425 426indicatorInteractive(value: boolean) 427 428Sets whether the navigation point indicator is interactive. The value **true** means that the navigation point indicator is interactive. 429 430**Atomic service API**: This API can be used in atomic services since API version 12. 431 432**System capability**: SystemCapability.ArkUI.ArkUI.Full 433 434**Parameters** 435 436| Name| Type | Mandatory| Description | 437| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 438| value | boolean | Yes | Whether the navigation point indicator is interactive.<br>Default value: **true**| 439 440## IndicatorStyle<sup>(deprecated)</sup> 441 442This API is supported since API version 8 and is deprecated since API version 10. You are advised to use [indicator](#indicator10) instead. 443 444**System capability**: SystemCapability.ArkUI.ArkUI.Full 445 446| Name | Type | Mandatory| Description | 447| ------------- | ------------------------------------------ | ---- | ---------------------------------------------------- | 448| left | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the left edge of the **Swiper** component. | 449| top | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the top edge of the **Swiper** component. | 450| right | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the right edge of the **Swiper** component. | 451| bottom | [Length](ts-types.md#length) | No | Distance between the navigation point indicator and the bottom edge of the **Swiper** component. | 452| size | [Length](ts-types.md#length) | No | Diameter of the navigation point indicator. It cannot be set in percentage.<br>Default value: **6vp**| 453| mask | boolean | No | Whether to enable the mask for the navigation point indicator. | 454| color | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the navigation point indicator. | 455| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the selected navigation point indicator. | 456 457## SwiperDisplayMode 458 459Enumerates the modes in which elements are displayed along the main axis. 460 461**System capability**: SystemCapability.ArkUI.ArkUI.Full 462 463| Name | Description | 464| --------------------------------- | ------------------------------------------------------------ | 465| 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.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 7.| 466| 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 [Scroller.scrollTo](ts-container-scroll.md#scrollto) instead.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 7.| 467| STRETCH<sup>10+</sup> | The slide width of the **Swiper** component is equal to the width of the component.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 468| AUTO_LINEAR<sup>(deprecated)</sup> | The slide width of the **Swiper** component is equal to the width of the leftmost child component in the viewport.<br>This API is supported since API version 10 and is deprecated since API version 12. You are advised to use [Scroller.scrollTo](ts-container-scroll.md#scrollto) instead.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 469 470## SwiperNestedScrollMode<sup>11+</sup> 471 472Enumerates the nested scrolling modes of the **Swiper** component and its parent container. 473 474**Atomic service API**: This API can be used in atomic services since API version 11. 475 476**System capability**: SystemCapability.ArkUI.ArkUI.Full 477 478| Name | Value| Description | 479| ------------ | -- | ---------------------------------------- | 480| SELF_ONLY | 0 | The scrolling is contained within the **Swiper** component, and no scroll chaining occurs, that is, the parent container does not scroll when the component scrolling reaches the boundary.| 481| SELF_FIRST | 1 | The **Swiper** component scrolls first, and when it hits the boundary, the parent container scrolls. When the parent container hits the boundary, its edge effect is displayed. If no edge effect is specified for the parent container, the edge effect of the **Swiper** component is displayed instead.| 482 483## SwiperController 484 485Controller of the **Swiper** component. You can bind this object to the **Swiper** component and use it to control page switching. 486 487**Widget capability**: This API can be used in ArkTS widgets since API version 10. 488 489**Atomic service API**: This API can be used in atomic services since API version 11. 490 491**System capability**: SystemCapability.ArkUI.ArkUI.Full 492 493### Objects to Import 494 495```ts 496let controller: SwiperController = new SwiperController() 497``` 498 499### constructor 500 501constructor() 502 503A constructor used to create a **SwiperController** object. 504 505**Widget capability**: This API can be used in ArkTS widgets since API version 10. 506 507**Atomic service API**: This API can be used in atomic services since API version 11. 508 509**System capability**: SystemCapability.ArkUI.ArkUI.Full 510 511### showNext 512 513showNext() 514 515Turns to the next page. Page turning occurs with the animation, whose duration is specified by **duration**. 516 517**Widget capability**: This API can be used in ArkTS widgets since API version 10. 518 519**Atomic service API**: This API can be used in atomic services since API version 11. 520 521**System capability**: SystemCapability.ArkUI.ArkUI.Full 522 523### showPrevious 524 525showPrevious() 526 527Turns to the previous page. Page turning occurs with the animation, whose duration is specified by **duration**. 528 529**Widget capability**: This API can be used in ArkTS widgets since API version 10. 530 531**Atomic service API**: This API can be used in atomic services since API version 11. 532 533**System capability**: SystemCapability.ArkUI.ArkUI.Full 534 535### changeIndex<sup>12+</sup> 536 537changeIndex(index: number, useAnimation?: boolean) 538 539Goes to a specified page. 540 541**Widget capability**: This API can be used in ArkTS widgets since API version 12. 542 543**Atomic service API**: This API can be used in atomic services since API version 12. 544 545**System capability**: SystemCapability.ArkUI.ArkUI.Full 546 547**Parameters** 548 549| Name | Type | Mandatory | Description | 550| -------- | ---------- | ---- | -------- | 551| index| number | Yes | Index of the target page in the **Swiper** component.| 552| useAnimation| boolean | No | Whether to use an animation for when the target page is reached. The value **true** means to use an animation, and **false** means the opposite.<br>Default value: **false**| 553 554### finishAnimation 555 556finishAnimation(callback?: () => void) 557 558Stops an animation. 559 560**Widget capability**: This API can be used in ArkTS widgets since API version 10. 561 562**Atomic service API**: This API can be used in atomic services since API version 11. 563 564**System capability**: SystemCapability.ArkUI.ArkUI.Full 565 566**Parameters** 567 568| Name | Type | Mandatory | Description | 569| -------- | ---------- | ---- | -------- | 570| callback | () => void | No | Callback invoked when the animation stops.| 571 572## Indicator<sup>10+</sup> 573 574Sets the distance between the navigation point indicator and the **Swiper** component. 575 576**Widget capability**: This API can be used in ArkTS widgets since API version 10. 577 578**Atomic service API**: This API can be used in atomic services since API version 11. 579 580**System capability**: SystemCapability.ArkUI.ArkUI.Full 581 582### Attributes 583 584| Name | Type | Mandatory | Description | 585| ------ | ---------------------------- | ---- | ---------------------------------------- | 586| left | [Length](ts-types.md#length) | Yes | Distance between the navigation point indicator and the left edge of the **Swiper** component.<br>Default value: **0**<br>Unit: vp| 587| top | [Length](ts-types.md#length) | Yes | Distance between the navigation point indicator and the top edge of the **Swiper** component.<br>Default value: **0**<br>Unit: vp| 588| right | [Length](ts-types.md#length) | Yes | Distance between the navigation point indicator and the right edge of the **Swiper** component.<br>Default value: **0**<br>Unit: vp| 589| bottom | [Length](ts-types.md#length) | Yes | Distance between the navigation point indicator and the bottom edge of the **Swiper** component.<br>Default value: **0**<br>Unit: vp| 590| start<sup>12+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Right-to-left scripts: Distance between the navigation point indicator and the right edge of the **Swiper** component.<br>Left-to-right scripts: Distance between the navigation point indicator and the left edge of the **Swiper** component.<br>Default value: **0**<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 591| end<sup>12+</sup> | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Right-to-left scripts: Distance between the navigation point indicator and the left edge of the **Swiper** component.<br>Left-to-right scripts: Distance between the navigation point indicator and the right edge of the **Swiper** component.<br>Default value: **0**<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 592 593### dot 594 595static dot(): DotIndicator 596 597**DotIndicator** object returned. 598 599**Widget capability**: This API can be used in ArkTS widgets since API version 10. 600 601**Atomic service API**: This API can be used in atomic services since API version 11. 602 603**System capability**: SystemCapability.ArkUI.ArkUI.Full 604 605### digit 606 607static digit(): DigitIndicator 608 609**DigitIndicator** object returned. 610 611**Widget capability**: This API can be used in ArkTS widgets since API version 10. 612 613**Atomic service API**: This API can be used in atomic services since API version 11. 614 615**System capability**: SystemCapability.ArkUI.ArkUI.Full 616 617## DotIndicator<sup>10+</sup> 618 619Defines the navigation point indicator of the dot style. It inherits from [Indicator](#indicator10). 620 621**Atomic service API**: This API can be used in atomic services since API version 11. 622 623**System capability**: SystemCapability.ArkUI.ArkUI.Full 624 625| Name | Type | Mandatory| Description | 626| ----------------------------- | ------------------------------------------ | ------ | ------------------------------------------------------------ | 627| itemWidth | [Length](ts-types.md#length) | Yes | Width of the navigation point indicator of the dot style. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 628| itemHeight | [Length](ts-types.md#length) | Yes | Height of the navigation point indicator of the dot style. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 629| selectedItemWidth | [Length](ts-types.md#length) | Yes | 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<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 630| selectedItemHeight | [Length](ts-types.md#length) | Yes | 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<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 631| mask | boolean | Yes | Whether to enable the mask for the navigation point indicator of the dot style.<br>Default value: **false**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 632| color | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the navigation point indicator of the dot style.<br>Default value: **'\#182431'** (10% opacity)<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 633| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the selected navigation point indicator of the dot style.<br>Default value: **'\#007DFF'**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 10.| 634| maxDisplayCount<sup>12+</sup> | number | Yes | Maximum number of navigation dots in the navigation point indicator of the dot style. When the actual number of navigation dots exceeds the maximum, the overflow effect will be activated, as shown in Example 5.<br>Default value: This attribute has no default value; if an invalid value is set, it is equivalent to having no overflow effect.<br>Value range: 6–9<br>**NOTE**<br>1. In the overflow display scenario, interactive features are currently not supported, including gestures and mouse operations.<br>2. In the overflow display scenario, the position of the selected navigation dot corresponding to the middle page is not completely fixed; it depends on the sequence of previous page-turning operations.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 635 636### constructor 637 638constructor() 639 640A constructor used to create a **DotIndicator** object. 641 642**Widget capability**: This API can be used in ArkTS widgets since API version 10. 643 644**Atomic service API**: This API can be used in atomic services since API version 11. 645 646**System capability**: SystemCapability.ArkUI.ArkUI.Full 647 648>**NOTE** 649> 650>When pressed, the navigation point indicator is zoomed in to 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**. 651 652## DigitIndicator<sup>10+</sup> 653 654Defines the navigation point indicator of the digit style. It inherits from [Indicator](#indicator10). 655 656**Widget capability**: This API can be used in ArkTS widgets since API version 10. 657 658**Atomic service API**: This API can be used in atomic services since API version 11. 659 660**System capability**: SystemCapability.ArkUI.ArkUI.Full 661 662| Name | Type | Mandatory | Description | 663| ----------------- | ---------------------------------------- | ---- | ---------------------------------------- | 664| fontColor | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color of the navigation point indicator of the digit style.<br>Default value: **'\#ff182431'**| 665| selectedFontColor | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color of the selected navigation point indicator of the digit style.<br>Default value: **'\#ff182431'**| 666| digitFont | {<br>size?:[Length](ts-types.md#length)<br>weight?:number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string<br>} | Yes | 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.<br>Default value: **FontWeight.Normal**| 667| selectedDigitFont | {<br>size?:[Length](ts-types.md#length)<br>weight?:number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string<br>} | Yes | 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.<br>Default value: **FontWeight.Normal**| 668 669### constructor 670 671constructor() 672 673A constructor used to create a **DigitIndicator** object. 674 675**Widget capability**: This API can be used in ArkTS widgets since API version 10. 676 677**Atomic service API**: This API can be used in atomic services since API version 11. 678 679**System capability**: SystemCapability.ArkUI.ArkUI.Full 680 681## ArrowStyle<sup>10+</sup> 682Describes the left and right arrow attributes. 683 684**Atomic service API**: This API can be used in atomic services since API version 11. 685 686**System capability**: SystemCapability.ArkUI.ArkUI.Full 687 688| Name | Type | Mandatory. | Description | 689| ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | 690| showBackground | boolean | No | Whether to show the background for the arrow.<br>Default value: **false** | 691| isSidebarMiddle | boolean | No | Whether the arrow is shown on either side of the navigation point indicator.<br>Default value: **false**<br>(the arrow is shown on either side of the navigation point indicator)| 692| 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.| 693| 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'**| 694| 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.| 695| arrowColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the arrow.<br>Default value: **'\#182431'** | 696 697## SwiperAutoFill<sup>10+</sup> 698 699Describes the auto-fill attribute. 700 701**Widget capability**: This API can be used in ArkTS widgets since API version 10. 702 703**Atomic service API**: This API can be used in atomic services since API version 11. 704 705**System capability**: SystemCapability.ArkUI.ArkUI.Full 706 707| Name | Type | Mandatory| Description | 708| ------- | -------------------- | ------ | ------------------------------------ | 709| minSize | [VP](ts-types.md#vp10) | Yes | Minimum width of the element.<br>Default value: **0**| 710 711## Events 712 713In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 714 715### onChange 716 717onChange(event: (index: number) => void) 718 719Triggered when the index of the currently displayed child component changes. The return value is the index of the currently displayed child component. 720 721When the **Swiper** component is used together with **LazyForEach**, the subpage UI update cannot be triggered in the **onChange** event. 722 723**Widget capability**: This API can be used in ArkTS widgets since API version 10. 724 725**Atomic service API**: This API can be used in atomic services since API version 11. 726 727**System capability**: SystemCapability.ArkUI.ArkUI.Full 728 729**Parameters** 730 731| Name| Type | Mandatory| Description | 732| ------ | ------ | ---- | -------------------- | 733| index | number | Yes | Index of the currently displayed element.| 734 735### onAnimationStart<sup>9+</sup> 736 737onAnimationStart(event: (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => void) 738 739Triggered when the switching animation starts. 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. 740 741**Widget capability**: This API can be used in ArkTS widgets since API version 10. 742 743**Atomic service API**: This API can be used in atomic services since API version 11. 744 745**System capability**: SystemCapability.ArkUI.ArkUI.Full 746 747**Parameters** 748 749| Name | Type | Mandatory| Description | 750| ------------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 751| index | number | Yes | Index of the currently displayed element. | 752| targetIndex<sup>10+</sup> | number | Yes | Index of the target element to switch to. | 753| extraInfo<sup>10+</sup> | [SwiperAnimationEvent](#swiperanimationevent10) | Yes | 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.| 754 755### onAnimationEnd<sup>9+</sup> 756 757onAnimationEnd(event: (index: number, extraInfo: SwiperAnimationEvent) => void) 758 759Triggered when the switching animation ends. 760 761This 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. 762 763**Widget capability**: This API can be used in ArkTS widgets since API version 10. 764 765**Atomic service API**: This API can be used in atomic services since API version 11. 766 767**System capability**: SystemCapability.ArkUI.ArkUI.Full 768 769**Parameters** 770 771| Name | Type | Mandatory| Description | 772| ----------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 773| index | number | Yes | Index of the currently displayed element. | 774| extraInfo<sup>10+</sup> | [SwiperAnimationEvent](#swiperanimationevent10) | Yes | 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.| 775 776### onGestureSwipe<sup>10+</sup> 777 778onGestureSwipe(event: (index: number, extraInfo: SwiperAnimationEvent) => void) 779 780Triggered on a frame-by-frame basis when the page is turned by a swipe. If there are multiple columns, **index** indicates the index of the leftmost component. 781 782**Atomic service API**: This API can be used in atomic services since API version 11. 783 784**System capability**: SystemCapability.ArkUI.ArkUI.Full 785 786**Parameters** 787 788| Name | Type | Mandatory| Description | 789| --------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 790| index | number | Yes | Index of the currently displayed element. | 791| extraInfo | [SwiperAnimationEvent](#swiperanimationevent10) | Yes | 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.| 792 793### customContentTransition<sup>12+</sup> 794 795customContentTransition(transition: SwiperContentAnimatedTransition) 796 797Defines a custom switching animation. You can define custom animation attributes, such as **opacity**, **scale**, and **translate**, in the callback invoked on a frame-by-frame basis during the swiping-initiated page switching animation. 798 799Instructions: 800 8011. This API does not work when **prevMargin** and **nextMargin** are set in such a way that the **Swiper** frontend and backend display the same page during loop playback.<br>2. During the swiping-initiated page switching animation, the [SwiperContentTransitionProxy](#swipercontenttransitionproxy12) callback is invoked for all pages in the viewport on a frame-by-frame basis. For example, when there are two pages whose subscripts are 0 and 1 in the viewport, two callbacks whose indexes are 0 and 1 are invoked in each frame.<br>3. When the **swipeByGroup** parameter of the **displayCount** attribute is set to **true**, the callback is invoked for all pages in a group if any page in the group is within the viewport; and all pages in a group are removed from the render tree if none of them are within the viewport.<br>4. During the swiping-initiated page switching animation, the default animation (page scrolling) is still effective. If you do not want the page to scroll, you can set the **translate** attribute on the main axis to offset the page scrolling. For example, if the value of **displayCount** is **2** and there are two pages whose subscripts are 0 and 1 within the viewport, you can set the **translate** attribute on the main axis to the following on a frame-by-frame basis: **translate** for page 0 = **-position** x **mainAxisLength**; **translate** for page 1 = **-(position - 1)** x **mainAxisLength** 802 803**Atomic service API**: This API can be used in atomic services since API version 12. 804 805**System capability**: SystemCapability.ArkUI.ArkUI.Full 806 807**Parameters** 808 809| Name| Type| Mandatory| Description| 810| ------ | ---- | ---- | ---- | 811| transition | [SwiperContentAnimatedTransition](#swipercontentanimatedtransition12) | Yes| Information about the custom switching animation.| 812 813### onContentDidScroll<sup>12+</sup> 814 815onContentDidScroll(handler: ContentDidScrollCallback) 816 817Triggered when content in the **Swiper** component scrolls. 818 819Instructions: 820 8211. This API does not work when **prevMargin** and **nextMargin** are set in such a way that the **Swiper** frontend and backend display the same page during loop playback.<br>2. During page scrolling, the [ContentDidScrollCallback](#contentdidscrollcallback12) callback is invoked for all pages in the viewport on a frame-by-frame basis. For example, when there are two pages whose subscripts are 0 and 1 in the viewport, two callbacks whose indexes are 0 and 1 are invoked in each frame.<br>3. When the **swipeByGroup** parameter of the **displayCount** attribute is set to **true**, the callback is invoked for all pages in a group if any page in the group is within the viewport. 822 823**Atomic service API**: This API can be used in atomic services since API version 12. 824 825**System capability**: SystemCapability.ArkUI.ArkUI.Full 826 827**Parameters** 828 829| Name| Type| Mandatory| Description| 830| ------ | ---- | ---- | ---- | 831| handler | [ContentDidScrollCallback](#contentdidscrollcallback12) | Yes| Callback triggered when content in the **Swiper** component scrolls.| 832 833## SwiperAnimationEvent<sup>10+</sup> 834 835Describes the animation information of the **Swiper** component. 836 837**Atomic service API**: This API can be used in atomic services since API version 11. 838 839**System capability**: SystemCapability.ArkUI.ArkUI.Full 840 841| Name | Type | Read Only| Optional| Description | 842| ------------- | ----------- | ---- | ---- |------------------------------- | 843| currentOffset | number | No| No| Offset of the currently displayed element relative to the start position of the **Swiper** along the main axis. Unit: vp<br>Default value: **0**| 844| targetOffset | number | No| No| Offset of the target element relative to the start position of the **Swiper** along the main axis. Unit: vp<br>Default value: **0**| 845| velocity | number | No| No| Hands-off velocity at the beginning of the animation. Unit: VP/S<br>Default value: **0**| 846 847## SwiperContentAnimatedTransition<sup>12+</sup> 848 849Information about the custom page switching animation. 850 851**Atomic service API**: This API can be used in atomic services since API version 12. 852 853**System capability**: SystemCapability.ArkUI.ArkUI.Full 854 855| Name| Type| Mandatory| Description| 856| ------ | ---- | ---- | ---- | 857| timeout | number | No| Timeout for the switching animation. The timeout timer starts when the default animation (page scrolling) reaches the point where the first frame is moved out of the viewport. If you do not call the **finishTransition** API of [SwiperContentTransitionProxy](#swipercontenttransitionproxy12) before the timer expires, the component considers that the custom animation of the page ends and immediately removes the page node from the render tree. The unit is ms. The default value is **0**.| 858| transition | Callback<[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)> | Yes| Content of the custom switching animation.| 859 860## SwiperContentTransitionProxy<sup>12+</sup> 861 862Implements the proxy object returned during the execution of the custom switching animation of the **Swiper** component. You can use this object to obtain the page information in the custom animation viewport. You can also call the **finishTransition** API of this object to notify the **Swiper** component that the custom animation has finished playing. 863 864**Atomic service API**: This API can be used in atomic services since API version 12. 865 866**System capability**: SystemCapability.ArkUI.ArkUI.Full 867 868### Attributes 869 870| Name| Type| Read Only| Optional| Description| 871| ---- | ---- | --- | ---- | --- | 872| selectedIndex | number | No| No| Index of the currently selected page.| 873| index | number | No| No| Index of a page in the viewport.| 874| position | number | No| No| Position of the page specified by **index** relative to the start position of the **Swiper** main axis (start position of the page corresponding to **selectedIndex**).| 875| mainAxisLength | number | No| No| Length of the page specified by **index** along the main axis.| 876 877>**NOTE** 878> 879>- For example, when the index of the currently selected child component is 0, during a transition animation from page 0 to page 1, the callback is triggered for all pages within the viewport on every frame. When pages 0 and 1 are both in the viewport, the callback is triggered twice per frame. The first callback has **selectedIndex** as **0**, **index** as **0**, **position** as the ratio of how much page 0 has moved relative to its position before the animation started on the current frame, and **mainAxisLength** as the length of page 0 on the main axis. The second callback has **selectedIndex** as **0**, **index** as **1**, **position** as the ratio of how much page 1 has moved relative to page 0 before the animation started on the current frame, and **mainAxisLength** as the length of page 1 on the main axis. 880> 881>- If the animation curve is a spring interpolation curve, during the transition animation from page 0 to page 1, due to the position and velocity when the user lifts their finger off the screen, animation may overshoot and slide past to page 2, then bounce back to page 1. Throughout this process, a callback is triggered for pages 1 and 2 within the viewport on every frame. 882 883 884### finishTransition<sup>12+</sup> 885 886finishTransition(): void 887 888Notifies the **Swiper** component that the custom animation has finished playing. 889 890**Atomic service API**: This API can be used in atomic services since API version 12. 891 892**System capability**: SystemCapability.ArkUI.ArkUI.Full 893 894## ContentDidScrollCallback<sup>12+</sup> 895 896type ContentDidScrollCallback = (selectedIndex: number, index: number, position: number, mainAxisLength: number) => void 897 898Triggered during the swipe action of the **Swiper** component. For details about the parameters, see [SwiperContentTransitionProxy](#swipercontenttransitionproxy12). 899 900**Atomic service API**: This API can be used in atomic services since API version 12. 901 902**System capability**: SystemCapability.ArkUI.ArkUI.Full 903 904| Name| Type| Mandatory| Description| 905| ------ | ---- | ---- | ---- | 906| selectedIndex | number | Yes| Index of the currently selected page.| 907| index | number | Yes| Index of a page in the viewport.| 908| position | number | Yes| Position of the page specified by **index** relative to the start position of the **Swiper** main axis (start position of the page corresponding to **selectedIndex**).| 909| mainAxisLength | number | Yes| Length of the page specified by **index** along the main axis.| 910 911## Example 912 913### Example 1 914This example shows the usage of **indicatorInteractive**. 915```ts 916// xxx.ets 917class MyDataSource implements IDataSource { 918 private list: number[] = [] 919 920 constructor(list: number[]) { 921 this.list = list 922 } 923 924 totalCount(): number { 925 return this.list.length 926 } 927 928 getData(index: number): number { 929 return this.list[index] 930 } 931 932 registerDataChangeListener(listener: DataChangeListener): void { 933 } 934 935 unregisterDataChangeListener() { 936 } 937} 938 939@Entry 940@Component 941struct SwiperExample { 942 private swiperController: SwiperController = new SwiperController() 943 private data: MyDataSource = new MyDataSource([]) 944 945 aboutToAppear(): void { 946 let list: number[] = [] 947 for (let i = 1; i <= 10; i++) { 948 list.push(i); 949 } 950 this.data = new MyDataSource(list) 951 } 952 953 build() { 954 Column({ space: 5 }) { 955 Swiper(this.swiperController) { 956 LazyForEach(this.data, (item: string) => { 957 Text(item.toString()) 958 .width('90%') 959 .height(160) 960 .backgroundColor(0xAFEEEE) 961 .textAlign(TextAlign.Center) 962 .fontSize(30) 963 }, (item: string) => item) 964 } 965 .cachedCount(2) 966 .index(1) 967 .autoPlay(true) 968 .interval(4000) 969 .loop(true) 970 .indicatorInteractive(true) 971 .duration(1000) 972 .itemSpace(0) 973 .indicator( // Set the style of the navigation point indicator. 974 new DotIndicator() 975 .itemWidth(15) 976 .itemHeight(15) 977 .selectedItemWidth(15) 978 .selectedItemHeight(15) 979 .color(Color.Gray) 980 .selectedColor(Color.Blue)) 981 .displayArrow({ // Set the arrow style of the navigation point indicator. 982 showBackground: true, 983 isSidebarMiddle: true, 984 backgroundSize: 24, 985 backgroundColor: Color.White, 986 arrowSize: 18, 987 arrowColor: Color.Blue 988 }, false) 989 .curve(Curve.Linear) 990 .onChange((index: number) => { 991 console.info(index.toString()) 992 }) 993 .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => { 994 console.info("index: " + index) 995 console.info("current offset: " + extraInfo.currentOffset) 996 }) 997 .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => { 998 console.info("index: " + index) 999 console.info("targetIndex: " + targetIndex) 1000 console.info("current offset: " + extraInfo.currentOffset) 1001 console.info("target offset: " + extraInfo.targetOffset) 1002 console.info("velocity: " + extraInfo.velocity) 1003 }) 1004 .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => { 1005 console.info("index: " + index) 1006 console.info("current offset: " + extraInfo.currentOffset) 1007 }) 1008 1009 Row({ space: 12 }) { 1010 Button('showNext') 1011 .onClick(() => { 1012 this.swiperController.showNext() 1013 }) 1014 Button('showPrevious') 1015 .onClick(() => { 1016 this.swiperController.showPrevious() 1017 }) 1018 }.margin(5) 1019 }.width('100%') 1020 .margin({ top: 5 }) 1021 } 1022} 1023``` 1024 1025 1026 1027### Example 2 1028```ts 1029// xxx.ets 1030class MyDataSource implements IDataSource { 1031 private list: number[] = [] 1032 1033 constructor(list: number[]) { 1034 this.list = list 1035 } 1036 1037 totalCount(): number { 1038 return this.list.length 1039 } 1040 1041 getData(index: number): number { 1042 return this.list[index] 1043 } 1044 1045 registerDataChangeListener(listener: DataChangeListener): void { 1046 } 1047 1048 unregisterDataChangeListener() { 1049 } 1050} 1051 1052@Entry 1053@Component 1054struct SwiperExample { 1055 private swiperController: SwiperController = new SwiperController() 1056 private data: MyDataSource = new MyDataSource([]) 1057 1058 aboutToAppear(): void { 1059 let list: number[] = [] 1060 for (let i = 1; i <= 10; i++) { 1061 list.push(i); 1062 } 1063 this.data = new MyDataSource(list) 1064 } 1065 1066 build() { 1067 Column({ space: 5 }) { 1068 Swiper(this.swiperController) { 1069 LazyForEach(this.data, (item: string) => { 1070 Text(item.toString()) 1071 .width('90%') 1072 .height(160) 1073 .backgroundColor(0xAFEEEE) 1074 .textAlign(TextAlign.Center) 1075 .fontSize(30) 1076 }, (item: string) => item) 1077 } 1078 .cachedCount(2) 1079 .index(1) 1080 .autoPlay(true) 1081 .interval(4000) 1082 .indicator(Indicator.digit() // Set the navigation point indicator of the digit style. 1083 .right("43%") 1084 .top(200) 1085 .fontColor(Color.Gray) 1086 .selectedFontColor(Color.Gray) 1087 .digitFont({ size: 20, weight: FontWeight.Bold }) 1088 .selectedDigitFont({ size: 20, weight: FontWeight.Normal })) 1089 .loop(true) 1090 .duration(1000) 1091 .itemSpace(0) 1092 .displayArrow(true, false) 1093 1094 Row({ space: 12 }) { 1095 Button('showNext') 1096 .onClick(() => { 1097 this.swiperController.showNext() 1098 }) 1099 Button('showPrevious') 1100 .onClick(() => { 1101 this.swiperController.showPrevious() 1102 }) 1103 }.margin(5) 1104 }.width('100%') 1105 .margin({ top: 5 }) 1106 } 1107} 1108``` 1109 1110 1111### Example 3 1112```ts 1113// xxx.ets 1114class MyDataSource implements IDataSource { 1115 private list: number[] = [] 1116 1117 constructor(list: number[]) { 1118 this.list = list 1119 } 1120 1121 totalCount(): number { 1122 return this.list.length 1123 } 1124 1125 getData(index: number): number { 1126 return this.list[index] 1127 } 1128 1129 registerDataChangeListener(listener: DataChangeListener): void { 1130 } 1131 1132 unregisterDataChangeListener() { 1133 } 1134} 1135 1136@Entry 1137@Component 1138struct SwiperExample { 1139 private swiperController: SwiperController = new SwiperController() 1140 private data: MyDataSource = new MyDataSource([]) 1141 1142 aboutToAppear(): void { 1143 let list: number[] = [] 1144 for (let i = 1; i <= 10; i++) { 1145 list.push(i); 1146 } 1147 this.data = new MyDataSource(list) 1148 } 1149 1150 build() { 1151 Column({ space: 5 }) { 1152 Swiper(this.swiperController) { 1153 LazyForEach(this.data, (item: string) => { 1154 Text(item.toString()) 1155 .width('90%') 1156 .height(160) 1157 .backgroundColor(0xAFEEEE) 1158 .textAlign(TextAlign.Center) 1159 .fontSize(30) 1160 }, (item: string) => item) 1161 } 1162 .displayCount(3, true) 1163 .autoPlay(true) 1164 .interval(4000) 1165 .loop(true) 1166 .duration(1000) 1167 .itemSpace(10) 1168 .indicator( // Set the style of the navigation point indicator. 1169 new DotIndicator() 1170 .itemWidth(15) 1171 .itemHeight(15) 1172 .selectedItemWidth(15) 1173 .selectedItemHeight(15) 1174 .color(Color.Gray) 1175 .selectedColor(Color.Blue)) 1176 1177 Row({ space: 12 }) { 1178 Button('showNext') 1179 .onClick(() => { 1180 this.swiperController.showNext() 1181 }) 1182 Button('showPrevious') 1183 .onClick(() => { 1184 this.swiperController.showPrevious() 1185 }) 1186 }.margin(5) 1187 }.width('100%') 1188 .margin({ top: 5 }) 1189 } 1190} 1191``` 1192 1193 1194### Example 4 1195 1196In this example, the **customContentTransition** API is used to define a custom switching animation for the **Swiper** component. 1197 1198```ts 1199// xxx.ets 1200@Entry 1201@Component 1202struct SwiperCustomAnimationExample { 1203 private DISPLAY_COUNT: number = 2 1204 private MIN_SCALE: number = 0.75 1205 1206 @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange] 1207 @State opacityList: number[] = [] 1208 @State scaleList: number[] = [] 1209 @State translateList: number[] = [] 1210 @State zIndexList: number[] = [] 1211 1212 aboutToAppear(): void { 1213 for (let i = 0; i < this.backgroundColors.length; i++) { 1214 this.opacityList.push(1.0) 1215 this.scaleList.push(1.0) 1216 this.translateList.push(0.0) 1217 this.zIndexList.push(0) 1218 } 1219 } 1220 1221 build() { 1222 Column() { 1223 Swiper() { 1224 ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => { 1225 Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center) 1226 .backgroundColor(backgroundColor) 1227 // Customize how the opacity, scale, translate, and other attributes change during the custom switching animation. 1228 .opacity(this.opacityList[index]) 1229 .scale({ x: this.scaleList[index], y: this.scaleList[index] }) 1230 .translate({ x: this.translateList[index] }) 1231 .zIndex(this.zIndexList[index]) 1232 }) 1233 } 1234 .height(300) 1235 .indicator(false) 1236 .displayCount(this.DISPLAY_COUNT, true) 1237 .customContentTransition({ 1238 // The page is removed from the render tree when 1000 ms (timeout time) has elapsed. 1239 timeout: 1000, 1240 // Called on a frame-by-frame basis for all pages in the viewport. You can change the values of attributes such as opacity, scale, translate, and zIndex in the callback to implement a custom animation. 1241 transition: (proxy: SwiperContentTransitionProxy) => { 1242 if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) { 1243 // Reset the attribute values when a page in the same group is swiped left or is swiped right to be completely out of the viewport. 1244 this.opacityList[proxy.index] = 1.0 1245 this.scaleList[proxy.index] = 1.0 1246 this.translateList[proxy.index] = 0.0 1247 this.zIndexList[proxy.index] = 0 1248 } else { 1249 // When a page in the same group is swiped right but is still within the viewport, the attribute values of the left and right pages in the same group are changed frame by frame based on the position. The changes implement the custom switching animation in which the two pages move close to the middle of the <Swiper> and are transparently scaled in or out. 1250 if (proxy.index % this.DISPLAY_COUNT === 0) { 1251 this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT 1252 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT) 1253 this.translateList[proxy.index] = - proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 1254 } else { 1255 this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT 1256 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT) 1257 this.translateList[proxy.index] = - (proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 1258 } 1259 this.zIndexList[proxy.index] = -1 1260 } 1261 } 1262 }) 1263 .onContentDidScroll((selectedIndex: number, index: number, position: number, mainAxisLength: number) => { 1264 // Called when content in the <Swiper> component scrolls. In this callback, you can customize the navigation point indicator switching animation. 1265 console.info("onContentDidScroll selectedIndex: " + selectedIndex + ", index: " + index + ", position: " + position + ", mainAxisLength: " + mainAxisLength) 1266 }) 1267 }.width('100%') 1268 } 1269} 1270``` 1271 1272 1273### Example 5 1274 1275This example implements an animation for the display of navigation dots that exceed the maximum display count through the **maxDisplayCount** attribute of the **DotIndicator** API. 1276 1277```ts 1278class MyDataSource implements IDataSource { 1279 private list: number[] = [] 1280 1281 constructor(list: number[]) { 1282 this.list = list 1283 } 1284 1285 totalCount(): number { 1286 return this.list.length 1287 } 1288 1289 getData(index: number): number { 1290 return this.list[index] 1291 } 1292 1293 registerDataChangeListener(listener: DataChangeListener): void { 1294 } 1295 1296 unregisterDataChangeListener() { 1297 } 1298} 1299 1300@Entry 1301@Component 1302struct Index { 1303 private swiperController: SwiperController = new SwiperController() 1304 private data: MyDataSource = new MyDataSource([]) 1305 1306 aboutToAppear(): void { 1307 let list: number[] = [] 1308 for (let i = 1; i <= 15; i++) { 1309 list.push(i); 1310 } 1311 this.data = new MyDataSource(list) 1312 } 1313 1314 build() { 1315 Column({ space: 5 }) { 1316 Swiper(this.swiperController) { 1317 LazyForEach(this.data, (item: string) => { 1318 Text(item.toString()) 1319 .width('90%') 1320 .height(160) 1321 .backgroundColor(0xAFEEEE) 1322 .textAlign(TextAlign.Center) 1323 .fontSize(30) 1324 }, (item: string) => item) 1325 } 1326 .cachedCount(2) 1327 .index(5) 1328 .autoPlay(true) 1329 .interval(4000) 1330 .loop(true) 1331 .duration(1000) 1332 .itemSpace(0) 1333 .indicator( // Set the style of the navigation point indicator. 1334 new DotIndicator() 1335 .itemWidth(8) 1336 .itemHeight(8) 1337 .selectedItemWidth(16) 1338 .selectedItemHeight(8) 1339 .color(Color.Gray) 1340 .selectedColor(Color.Blue) 1341 .maxDisplayCount(9)) 1342 .displayArrow({ // Set the arrow style of the navigation point indicator. 1343 showBackground: true, 1344 isSidebarMiddle: true, 1345 backgroundSize: 24, 1346 backgroundColor: Color.White, 1347 arrowSize: 18, 1348 arrowColor: Color.Blue 1349 }, false) 1350 .curve(Curve.Linear) 1351 Row({ space: 12 }) { 1352 Button('showNext') 1353 .onClick(() => { 1354 this.swiperController.showNext() 1355 }) 1356 Button('showPrevious') 1357 .onClick(() => { 1358 this.swiperController.showPrevious() 1359 }) 1360 }.margin(5) 1361 }.width('100%') 1362 .margin({ top: 5 }) 1363 } 1364} 1365``` 1366 1367 1368
