1# Swiper 2 3 The **Swiper** component is able to display child components in a carousel-like manner. 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 **Swiper** component incorporates a [PanGesture](ts-basic-gestures-pangesture.md) event that facilitates the swiping action to cycle through its child components. Setting [disableSwipe](#disableswipe8) to **true** will cancel the internal listening for the **PanGesture** event, disabling the swiping interaction. 10 11## Child Components 12 13This component can contain child components. 14 15> **NOTE** 16> 17> - Child components can consist of both built-in components and custom components, and their rendering can be controlled 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), and [Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md). To maximize the benefits of lazy loading, avoid mixing lazy loading components (including **LazyForEach** and **Repeat**) and non-lazy loading components, and exercise caution when using multiple lazy loading components. Avoid modifying the data source while an animation is in progress, as doing so can lead to layout issues. 18> 19> - If a child component has its [visibility](ts-universal-attributes-visibility.md#visibility) attribute set to **Visibility.None** and the **Swiper** component has its **displayCount** attribute set to **'auto'**, the child component does not take up space in the viewport, but does not affect the number of navigation points. If a child component has its **visibility** attribute set to **Visibility.None** or **Visibility.Hidden**, it takes up space in the viewport, but is not displayed. 20> 21> - Child components of the **Swiper** component are drawn based on their level if they have the [offset](ts-universal-attributes-location.md#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](ts-universal-attributes-z-order.md) attribute to a value greater than that of the third child component. 22> 23> - When focus is moved to a custom child node, navigation points and arrows may be obscured by changes to the z-index due to [focus styles](../../../ui/arkts-common-events-focus-event.md#focus-style). 24 25## APIs 26 27Swiper(controller?: SwiperController) 28 29Creates a **Swiper** component. 30 31**Widget capability**: This API can be used in ArkTS widgets since API version 10. 32 33**Atomic service API**: This API can be used in atomic services since API version 11. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37**Parameters** 38 39| Name | Type | Mandatory | Description | 40| ---------- | ------------------------------------- | ---- | -------------------- | 41| controller | [SwiperController](#swipercontroller) | No | Controller bound to the component to control the swiping.| 42 43 44## Attributes 45 46In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 47 48> **NOTE** 49> 50> The default value of the universal attribute [clip](ts-universal-attributes-sharp-clipping.md) is **true** for the **Swiper** component. 51 52### index 53 54index(value: number) 55 56Sets 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. 57 58Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). 59 60**Widget capability**: This API can be used in ArkTS widgets since API version 10. 61 62**Atomic service API**: This API can be used in atomic services since API version 11. 63 64**System capability**: SystemCapability.ArkUI.ArkUI.Full 65 66**Parameters** 67 68| Name| Type | Mandatory| Description | 69| ------ | ------ | ---- | ------------------------------------------------ | 70| value | number | Yes | Index of the child component currently displayed in the container.<br>Default value: **0**<br>**NOTE**<br>If the value specified is less than 0 or greater than the maximum page index, the value **0** is used.| 71 72### autoPlay 73 74autoPlay(value: boolean) 75 76Sets whether to enable automatic playback for child component switching. 77 78If **loop** is set to **false**, the playback stops when the last page is reached. The playback continues when the page is not the last page after a swipe gesture. If the **Swiper** component becomes invisible, the playback stops. 79 80**Widget capability**: This API can be used in ArkTS widgets since API version 10. 81 82**Atomic service API**: This API can be used in atomic services since API version 11. 83 84**System capability**: SystemCapability.ArkUI.ArkUI.Full 85 86**Parameters** 87 88| Name| Type | Mandatory| Description | 89| ------ | ------- | ---- | -------------------------------------- | 90| value | boolean | Yes | Whether to enable automatic playback for child component switching.<br>Default value: **false** (automatic playback is disabled for child component switching.)| 91 92### autoPlay<sup>18+</sup> 93 94autoPlay(autoPlay: boolean, options: AutoPlayOptions) 95 96Sets whether child components automatically play when the screen is pressed by fingers, a mouse device, or other input devices. 97 98If [loop](#loop) is set to **false**, autoplay stops when the last page is reached. If a gesture is used to switch pages and the last page is not reached, playback will continue. Autoplay also stops when the **Swiper** component is not visible. 99 100**Widget capability**: This API can be used in ArkTS widgets since API version 18. 101 102**Atomic service API**: This API can be used in atomic services since API version 18. 103 104**System capability**: SystemCapability.ArkUI.ArkUI.Full 105 106**Parameters** 107 108| Name| Type | Mandatory| Description | 109| ------ | ------- | ---- | -------------------------------------- | 110| autoPlay | boolean | Yes | Whether to enable automatic playback for child component switching.<br>Default value: **false** (automatic playback is disabled for child component switching)| 111| options | [AutoPlayOptions](#autoplayoptions18) | Yes | Whether child components stop autoplay when the screen is pressed by fingers, a mouse device, or other input devices. If **stopWhenTouched** is set to **true**, autoplay stops when the screen is pressed.<br>Default value: **{ stopWhenTouched: true }** (stop autoplay)| 112 113### interval 114 115interval(value: number) 116 117Sets the interval for automatic playback. 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 | number | Yes | Interval for automatic playback.<br>Default value: **3000**<br>Unit: ms<br>Value range: [0, +∞). If a value less than 0 is set, the default value is used.| 130 131### indicator 132 133indicator(value: DotIndicator | DigitIndicator | boolean) 134 135Sets the style of the navigation indicator. 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 | [DotIndicator](#dotindicator10)<sup>10+</sup> \| [DigitIndicator](#digitindicator10)<sup>10+</sup> \| boolean | Yes | Style of the navigation indicator.<br> \- **DotIndicator**: dot style.<br> \- **DigitIndicator**: digit style.<br> \- **boolean**: whether to enable the navigation indicator. The value **true** means to enable the feature, and **false** means the opposite.<br> Default value: **true**<br> Default style: **DotIndicator**| 148 149### indicator<sup>15+</sup> 150 151indicator(indicator: IndicatorComponentController | DotIndicator | DigitIndicator | boolean) 152 153Sets the navigation indicator for the component. 154 155**Widget capability**: This API can be used in ArkTS widgets since API version 15. 156 157**Atomic service API**: This API can be used in atomic services since API version 15. 158 159**System capability**: SystemCapability.ArkUI.ArkUI.Full 160 161**Parameters** 162 163| Name| Type | Mandatory| Description | 164| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 165| indicator | [IndicatorComponentController](ts-swiper-components-indicator.md#indicatorcomponentcontroller)<sup>15+</sup> \| [DotIndicator](#dotindicator10) \| [DigitIndicator](#digitindicator10) \| boolean| Yes | Style of the navigation indicator.<br>\- **IndicatorComponentController**: separate navigation indicator controller. This controller can be bound to an external navigation indicator, but the external and internal indicators cannot coexist.<br> \- **DotIndicator**: dot-style indicator.<br> \- **DigitIndicator**: digit-style indicator.<br> \- **boolean**: whether to enable the navigation indicator. The value **true** means to enable the feature, and **false** means the opposite.<br> Default value: **true**<br> Default style: **DotIndicator**| 166 167 168### loop 169 170loop(value: boolean) 171 172Sets 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. 173 174**Widget capability**: This API can be used in ArkTS widgets since API version 10. 175 176**Atomic service API**: This API can be used in atomic services since API version 11. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Parameters** 181 182| Name| Type | Mandatory| Description | 183| ------ | ------- | ---- | ------------------------------- | 184| value | boolean | Yes | Whether to enable loop playback.<br>Default value: **true**| 185 186### duration 187 188duration(value: number) 189 190Sets the duration of the animation for child component switching. 191 192**duration** must be used in conjunction with [curve](#curve8). 193 194The 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). Among others, [springMotion](../js-apis-curve.md#curvesspringmotion9) and [responsiveSpringMotion](../js-apis-curve.md#curvesresponsivespringmotion9) do not respect the **duration** setting. To have the animation duration managed by **duration**, you should select a different curve for the **curve** attribute. 195 196**Atomic service API**: This API can be used in atomic services since API version 11. 197 198**System capability**: SystemCapability.ArkUI.ArkUI.Full 199 200**Parameters** 201 202| Name| Type | Mandatory| Description | 203| ------ | ------ | ---- | ----------------------------------------------------- | 204| value | number | Yes | Duration of the autoplay for child component switching.<br>Default value: **400**<br>Unit: ms<br>Value range: [0, +∞). If a value less than 0 is set, the default value is used.| 205 206### vertical 207 208vertical(value: boolean) 209 210Sets whether vertical swiping is used. 211 212**Widget capability**: This API can be used in ArkTS widgets since API version 10. 213 214**Atomic service API**: This API can be used in atomic services since API version 11. 215 216**System capability**: SystemCapability.ArkUI.ArkUI.Full 217 218**Parameters** 219 220| Name| Type | Mandatory| Description | 221| ------ | ------- | ---- | ---------------------------------- | 222| value | boolean | Yes | Whether vertical swiping is used. The value **true** means vertical swiping, and **false** means horizontal swiping.<br>Default value: **false**| 223 224### itemSpace 225 226itemSpace(value: number | string) 227 228Sets the space between child components. This attribute cannot be set in percentage. 229 230If 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. 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 \| string | Yes | Space between child components.<br>Default value: **0**<br>Value range: [0, +∞). If a value less than 0 is set, the default value is used.| 243 244### displayMode 245 246displayMode(value: SwiperDisplayMode) 247 248Sets the mode in which elements are displayed along the main axis. This API takes effect only when **displayCount** is not set. 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 | [SwiperDisplayMode](#swiperdisplaymode) | Yes | Mode in which elements are displayed along the main axis.<br>Default value: **SwiperDisplayMode.STRETCH**| 261 262### cachedCount<sup>8+</sup> 263 264cachedCount(value: number) 265 266Sets 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. 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 | number | Yes | Number of child components to be preloaded (cached).<br>Default value: **1**<br>Value range: [0, +∞). If a value less than 0 is set, the default value is used.| 279 280### cachedCount<sup>15+</sup> 281 282cachedCount(count: number, isShown: boolean) 283 284Sets the number of child components to be cached. 285 286**Widget capability**: This API can be used in ArkTS widgets since API version 15. 287 288**Atomic service API**: This API can be used in atomic services since API version 15. 289 290**System capability**: SystemCapability.ArkUI.ArkUI.Full 291 292**Parameters** 293 294| Name| Type | Mandatory| Description | 295| ------ | ------ | ---- | -------------------------------- | 296| count | number | Yes | Number of child components to be preloaded (cached).<br>Default value: **1**<br>Value range: [0, +∞). If a value less than 0 is set, the default value is used.| 297| isShown | boolean | Yes | Whether the cached nodes within the range rendered without being added to the render tree.<br>Default value: **false**, indicating that cached nodes within the range are rendered| 298 299### disableSwipe<sup>8+</sup> 300 301disableSwipe(value: boolean) 302 303Sets whether to disable the swipe feature. 304 305**Widget capability**: This API can be used in ArkTS widgets since API version 10. 306 307**Atomic service API**: This API can be used in atomic services since API version 11. 308 309**System capability**: SystemCapability.ArkUI.ArkUI.Full 310 311**Parameters** 312 313| Name| Type | Mandatory| Description | 314| ------ | ------- | ---- | ---------------------------------------- | 315| 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**| 316 317### curve<sup>8+</sup> 318 319curve(value: Curve | string | ICurve) 320 321Sets 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. 322 323**Widget capability**: This API can be used in ArkTS widgets since API version 10. 324 325**Atomic service API**: This API can be used in atomic services since API version 11. 326 327**System capability**: SystemCapability.ArkUI.ArkUI.Full 328 329**Parameters** 330 331| Name| Type | Mandatory| Description | 332| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------- | 333| 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)**| 334 335### indicatorStyle<sup>(deprecated)</sup> 336 337indicatorStyle(value?: IndicatorStyle) 338 339Sets the style of the navigation indicator. 340 341This API is supported since API version 8 and is deprecated since API version 10. You are advised to use [indicator](#indicator10) instead. 342 343**System capability**: SystemCapability.ArkUI.ArkUI.Full 344 345**Parameters** 346 347| Name| Type | Mandatory| Description | 348| ------ | --------------------------------------------------- | ---- | ------------ | 349| value | [IndicatorStyle](#indicatorstyledeprecated) | No | Style of the navigation indicator.| 350 351### displayCount<sup>8+</sup> 352 353displayCount(value: number | string | SwiperAutoFill, swipeByGroup?: boolean) 354 355Sets the number of elements to display per page. 356 357If the value is of the string type, it can only be **'auto'**. In this case, setting [customContentTransition](#customcontenttransition12) or [onContentDidScroll](#oncontentdidscroll12) has no effect. 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; a value less than or equal to 0 is handled as the default value **1**. If 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. 358 359When turning pages by group is used, the drag distance threshold for turning pages is half of the width of the **Swiper** component (50% of the child elements width if turning pages by child element is used). If the number of child elements in the last group is less than the value of **displayCount**, placeholders are used, but they show the **Swiper** background style directly and do not display any content. 360 361**Widget capability**: This API can be used in ArkTS widgets since API version 10. 362 363**Atomic service API**: This API can be used in atomic services since API version 11. 364 365**System capability**: SystemCapability.ArkUI.ArkUI.Full 366 367**Parameters** 368 369| Name | Type | Mandatory| Description | 370| -------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 371| value | number \| string \| [SwiperAutoFill](#swiperautofill10)<sup>10+</sup> | Yes | Number of elements to display per page.<br> Default value: **1**<br>Value range: (0, +∞). If this parameter is set to a value less than or equal to 0, the default value is used.| 372| 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. When turning pages by group is used, the number of child elements per group is the value of **displayCount**.<br> Default value: **false**| 373 374> **NOTE** 375> 376> 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: 377> 378> - 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. 379> 380> - 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.) 381> 382 383### effectMode<sup>8+</sup> 384 385effectMode(value: EdgeEffect) 386 387Sets 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. 388 389**Widget capability**: This API can be used in ArkTS widgets since API version 10. 390 391**Atomic service API**: This API can be used in atomic services since API version 11. 392 393**System capability**: SystemCapability.ArkUI.ArkUI.Full 394 395**Parameters** 396 397| Name| Type | Mandatory| Description | 398| ------ | --------------------------------------------- | ---- | -------------------------------------------- | 399| value | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Yes | Effect used when the component is at one of the edges.<br>Default value: **EdgeEffect.Spring**| 400 401### displayArrow<sup>10+</sup> 402 403displayArrow(value: ArrowStyle | boolean, isHoverShow?: boolean) 404 405Sets the arrow style of the navigation indicator. 406 407**Atomic service API**: This API can be used in atomic services since API version 11. 408 409**System capability**: SystemCapability.ArkUI.ArkUI.Full 410 411**Parameters** 412 413| Name | Type | Mandatory| Description | 414| -------------------------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 415| 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**| 416| isHoverShow | boolean | No | Whether to show the arrow only when the mouse pointer hovers over the navigation 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 indicator, and it can be clicked to turn pages.| 417 418> **NOTE** 419> 420> When all child nodes fit within the viewport, resulting in only one screen's worth of content being visible, the **Swiper** component displays only that screen without any left or right page-turning arrows. 421 422### nextMargin<sup>10+</sup> 423 424nextMargin(value: Length, ignoreBlank?:boolean) 425 426Sets 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. 427 428When 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. 429 430When 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. 431 432**Atomic service API**: This API can be used in atomic services since API version 11. 433 434**System capability**: SystemCapability.ArkUI.ArkUI.Full 435 436**Parameters** 437 438| Name| Type | Mandatory| Description | 439| ------ | ---------------------------- | ---- | ---------------------- | 440| value | [Length](ts-types.md#length) | Yes | Next margin. This attribute cannot be set in percentage.<br>Default value: **0**| 441| 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.| 442 443### prevMargin<sup>10+</sup> 444 445prevMargin(value: Length, ignoreBlank?:boolean) 446 447Sets 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. 448 449When 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. 450 451When 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. 452 453**Atomic service API**: This API can be used in atomic services since API version 11. 454 455**System capability**: SystemCapability.ArkUI.ArkUI.Full 456 457**Parameters** 458 459| Name| Type | Mandatory| Description | 460| ------ | ---------------------------- | ---- | ---------------------- | 461| value | [Length](ts-types.md#length) | Yes | Previous margin. This attribute cannot be set in percentage.<br>Default value: **0**| 462| 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.| 463 464### nestedScroll<sup>11+</sup> 465 466nestedScroll(value: SwiperNestedScrollMode) 467 468Sets 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. 469 470**Atomic service API**: This API can be used in atomic services since API version 11. 471 472**System capability**: SystemCapability.ArkUI.ArkUI.Full 473 474**Parameters** 475 476| Name| Type | Mandatory| Description | 477| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 478| value | [SwiperNestedScrollMode](#swipernestedscrollmode11) | Yes | Nested scrolling mode of the **Swiper** component and its parent container.<br>Default value: **SwiperNestedScrollMode.SELF_ONLY**| 479 480> **NOTE** 481> 482> 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. 483 484### indicatorInteractive<sup>12+</sup> 485 486indicatorInteractive(value: boolean) 487 488Sets whether the navigation indicator is interactive. The value **true** means that the navigation indicator is interactive. 489 490**Atomic service API**: This API can be used in atomic services since API version 12. 491 492**System capability**: SystemCapability.ArkUI.ArkUI.Full 493 494**Parameters** 495 496| Name| Type | Mandatory| Description | 497| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 498| value | boolean | Yes | Whether the navigation indicator is interactive.<br>Default value: **true**| 499 500### pageFlipMode<sup>15+</sup> 501 502pageFlipMode(mode: Optional\<PageFlipMode>) 503 504Sets the mode for flipping pages using the mouse wheel. 505 506**Widget capability**: This API can be used in ArkTS widgets since API version 15. 507 508**Atomic service API**: This API can be used in atomic services since API version 15. 509 510**System capability**: SystemCapability.ArkUI.ArkUI.Full 511 512**Parameters** 513 514| Name| Type | Mandatory| Description | 515| ------ | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 516| mode | Optional\<[PageFlipMode](ts-appendix-enums.md#pageflipmode15)> | Yes | Mode for flipping pages using the mouse wheel.<br>Default value: **PageFlipMode.CONTINUOUS**| 517 518## IndicatorStyle<sup>(deprecated)</sup> 519 520This API is supported since API version 8 and is deprecated since API version 10. You are advised to use [indicator](#indicator10) instead. 521 522**System capability**: SystemCapability.ArkUI.ArkUI.Full 523 524| Name | Type | Mandatory| Description | 525| ------------- | ------------------------------------------ | ---- | ---------------------------------------------------- | 526| left | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the left edge of the **Swiper** component.<br>If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: higher than the **right** property<br>Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary. | 527| top | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the top edge of the **Swiper** component.<br>If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: higher than the **bottom** property<br>Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary. | 528| right | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the right edge of the **Swiper** component.<br>If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: lower than the **left** property<br>Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary. | 529| bottom | [Length](ts-types.md#length) | No | Position of the navigation indicator relative to the bottom edge of the **Swiper** component.<br>If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: lower than the **top** property<br>Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary. | 530| size | [Length](ts-types.md#length) | No | Diameter of the navigation indicator. It cannot be set in percentage.<br>Default value: **6vp**| 531| mask | boolean | No | Whether to enable the mask for the navigation indicator. | 532| color | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the navigation indicator. | 533| selectedColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the selected navigation indicator. | 534 535## SwiperDisplayMode 536 537Enumerates the modes in which elements are displayed along the main axis. 538 539**System capability**: SystemCapability.ArkUI.ArkUI.Full 540 541| Name | Description | 542| ---------------------------------- | ------------------------------------------------------------ | 543| 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.| 544| 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.| 545| 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.| 546| 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.| 547 548## SwiperNestedScrollMode<sup>11+</sup> 549 550Enumerates the nested scrolling modes of the **Swiper** component and its parent container. 551 552**Atomic service API**: This API can be used in atomic services since API version 11. 553 554**System capability**: SystemCapability.ArkUI.ArkUI.Full 555 556| Name | Value| Description | 557| ------------ | -- | ---------------------------------------- | 558| 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.| 559| 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.| 560 561## SwiperController 562 563Controller of the **Swiper** component. You can bind this object to the **Swiper** component and use it to control page switching. 564 565**Widget capability**: This API can be used in ArkTS widgets since API version 10. 566 567**Atomic service API**: This API can be used in atomic services since API version 11. 568 569**System capability**: SystemCapability.ArkUI.ArkUI.Full 570 571### Objects to Import 572 573```ts 574let controller: SwiperController = new SwiperController() 575``` 576 577### constructor 578 579constructor() 580 581A constructor used to create a **SwiperController** object. 582 583**Widget capability**: This API can be used in ArkTS widgets since API version 10. 584 585**Atomic service API**: This API can be used in atomic services since API version 11. 586 587**System capability**: SystemCapability.ArkUI.ArkUI.Full 588 589### showNext 590 591showNext() 592 593Turns to the next page. Page turning occurs with the animation, whose duration is specified by **duration**. 594 595**Widget capability**: This API can be used in ArkTS widgets since API version 10. 596 597**Atomic service API**: This API can be used in atomic services since API version 11. 598 599**System capability**: SystemCapability.ArkUI.ArkUI.Full 600 601### showPrevious 602 603showPrevious() 604 605Turns to the previous page. Page turning occurs with the animation, whose duration is specified by **duration**. 606 607**Widget capability**: This API can be used in ArkTS widgets since API version 10. 608 609**Atomic service API**: This API can be used in atomic services since API version 11. 610 611**System capability**: SystemCapability.ArkUI.ArkUI.Full 612 613### changeIndex<sup>12+</sup> 614 615changeIndex(index: number, useAnimation?: boolean) 616 617Goes to a specified page. 618 619**Widget capability**: This API can be used in ArkTS widgets since API version 12. 620 621**Atomic service API**: This API can be used in atomic services since API version 12. 622 623**System capability**: SystemCapability.ArkUI.ArkUI.Full 624 625**Parameters** 626 627| Name | Type | Mandatory | Description | 628| -------- | ---------- | ---- | -------- | 629| index| number | Yes | Index of the target page in the **Swiper** component.<br>**NOTE**<br>If the value specified is less than 0 or greater than the maximum page index, the value **0** is used.| 630| 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**| 631 632### changeIndex<sup>15+</sup> 633 634changeIndex(index: number, animationMode?: SwiperAnimationMode | boolean) 635 636Moves to a specific page. 637 638**Widget capability**: This API can be used in ArkTS widgets since API version 15. 639 640**Atomic service API**: This API can be used in atomic services since API version 15. 641 642**System capability**: SystemCapability.ArkUI.ArkUI.Full 643 644**Parameters** 645 646| Name | Type | Mandatory | Description | 647| -------- | ---------- | ---- | -------- | 648| index| number | Yes | Index of the target page in the **Swiper** component.<br>**NOTE**<br>If the value specified is less than 0 or greater than the maximum page index, the value **0** is used.| 649| animationMode| [SwiperAnimationMode](#swiperanimationmode15) \| boolean | No | Animation mode for moving to the specified page.<br>Default value: **SwiperAnimationMode.NO_ANIMATION**<br> **NOTE**<br>The value **true** is equivalent to **SwiperAnimationMode.DEFAULT_ANIMATION**, which means to use the default animation. The value **false** is equivalent to **SwiperAnimationMode.NO_ANIMATION**, which means to use no animation.| 650 651### finishAnimation 652 653finishAnimation(callback?: VoidCallback) 654 655Stops an animation. 656 657**Widget capability**: This API can be used in ArkTS widgets since API version 10. 658 659**Atomic service API**: This API can be used in atomic services since API version 11. 660 661**System capability**: SystemCapability.ArkUI.ArkUI.Full 662 663**Parameters** 664 665| Name | Type | Mandatory | Description | 666| -------- | ---------- | ---- | -------- | 667| callback | [VoidCallback](./ts-types.md#voidcallback12) | No | Callback invoked when the animation stops.| 668 669### preloadItems<sup>18+</sup> 670 671preloadItems(indices: Optional\<Array\<number>>): Promise\<void> 672 673Preloads child nodes. After this API is called, all specified child nodes will be loaded at once. Therefore, for performance considerations, it is recommended that you load child nodes in batches. 674 675If the **SwiperController** object is not bound to any **Swiper** component, any attempt to call APIs on it will result in a JavaScript exception, together with the error code 100004. Therefore, you are advised to use **try-catch** to handle potential exceptions when calling APIs on **SwiperController**. 676 677When combining **SwiperController** with [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md) and custom components, be aware that **LazyForEach** only retains custom components within the cache range. Components outside this range are removed. Therefore, make sure the nodes to preload are within the cache range of **LazyForEach** to avoid issues. 678 679**Widget capability**: This API can be used in ArkTS widgets since API version 18. 680 681**Atomic service API**: This API can be used in atomic services since API version 18. 682 683**System capability**: SystemCapability.ArkUI.ArkUI.Full 684 685**Parameters** 686 687| Name | Type | Mandatory | Description | 688| ----- | ------ | ---- | ---------------------------------------- | 689| indices | Optional\<Array\<number>> | Yes| Array of indexes of the child nodes to preload.<br>The default value is an empty array.| 690 691**Return value** 692 693| Type | Description | 694| ------------------------------------------------------------ | ------------------------ | 695| Promise\<void> | Promise used to return the value.| 696 697**Error codes** 698 699For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Scrollable Component Error Codes](../../apis-arkui/errorcode-scroll.md). 700 701| ID | Error Message | 702| -------- | -------------------------------------------- | 703| 401 | Parameter invalid. Possible causes: 1. The parameter type is not Array\<number>; 2. The parameter is an empty array; 3. The parameter contains an invalid index. | 704| 100004 | Controller not bound to component. | 705 706## SwiperAnimationMode<sup>15+</sup> 707 708Enumerates the animation mode for moving to a specific page in the **Swiper** component. 709 710**Widget capability**: This API can be used in ArkTS widgets since API version 15. 711 712**Atomic service API**: This API can be used in atomic services since API version 15. 713 714**System capability**: SystemCapability.ArkUI.ArkUI.Full 715 716| Name | Value | Description | 717| ------------- | ---- | ------------------------------------------------------------ | 718| NO_ANIMATION | 0 | Move to the specified page without any animation. | 719| DEFAULT_ANIMATION | 1 | Move to the specified page with the default animation. | 720| FAST_ANIMATION | 2 | Move to a page near the specified page without animation, and then navigate to the specified page with the default animation.| 721 722## Indicator<sup>10+</sup> 723 724Sets the distance between the navigation indicator and the **Swiper** component. Note that due to its default interaction area height of 32 vp, the navigation indicator cannot be placed flush against the bottom edge. 725 726**Widget capability**: This API can be used in ArkTS widgets since API version 10. 727 728**Atomic service API**: This API can be used in atomic services since API version 11. 729 730**System capability**: SystemCapability.ArkUI.ArkUI.Full 731 732### left 733 734left(value: Length): T 735 736Sets the position of the navigation indicator relative to the left edge of the **Swiper** component. 737 738**Widget capability**: This API can be used in ArkTS widgets since API version 10. 739 740**Atomic service API**: This API can be used in atomic services since API version 11. 741 742**System capability**: SystemCapability.ArkUI.ArkUI.Full 743 744**Parameters** 745 746| Name| Type | Mandatory| Description | 747| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 748| value | [Length](ts-types.md#length) | Yes | Position of the navigation indicator relative to the left edge of the **Swiper** component.<br>If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: higher than the **right** property<br>Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary.| 749 750### top 751 752top(value: Length): T 753 754Sets the position of the navigation indicator relative to the top edge of the **Swiper** component. 755 756**Widget capability**: This API can be used in ArkTS widgets since API version 10. 757 758**Atomic service API**: This API can be used in atomic services since API version 11. 759 760**System capability**: SystemCapability.ArkUI.ArkUI.Full 761 762**Parameters** 763 764| Name| Type | Mandatory| Description | 765| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 766| value | [Length](ts-types.md#length) | Yes | Position of the navigation indicator relative to the top edge of the **Swiper** component.<br>If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: higher than the **bottom** property<br>Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary.| 767 768### right 769 770right(value: Length): T 771 772Sets the position of the navigation indicator relative to the right edge of the **Swiper** component. 773 774**Widget capability**: This API can be used in ArkTS widgets since API version 10. 775 776**Atomic service API**: This API can be used in atomic services since API version 11. 777 778**System capability**: SystemCapability.ArkUI.ArkUI.Full 779 780**Parameters** 781 782| Name| Type | Mandatory| Description | 783| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 784| value | [Length](ts-types.md#length) | Yes | Sets the position of the navigation indicator relative to the right edge of the **Swiper** component.<br>If neither **left** nor **right** is set, the navigation indicator is centered along the main axis based on its own size and the size of the **Swiper** component.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: lower than the **left** property<br>Value range: [0, Swiper width - Navigation indicator area width]. Values outside this range are adjusted to the nearest boundary.| 785 786### bottom 787 788bottom(value: Length): T 789 790Sets the position of the navigation indicator relative to the bottom edge of the **Swiper** component. 791 792**Widget capability**: This API can be used in ArkTS widgets since API version 10. 793 794**Atomic service API**: This API can be used in atomic services since API version 11. 795 796**System capability**: SystemCapability.ArkUI.ArkUI.Full 797 798**Parameters** 799 800| Name| Type | Mandatory| Description | 801| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 802| value | [Length](ts-types.md#length) | Yes | Position of the navigation indicator relative to the bottom edge of the **Swiper** component.<br>If neither **top** nor **bottom** is set, the navigation indicator is aligned at the bottom along the cross axis based on its own size and the size of the **Swiper** component, which is the same effect as setting **bottom=0**.<br>If the value specified is **0**, the navigation indicator is placed at the position 0.<br>Priority: lower than the **top** property<br>Value range: [0, Swiper height - Navigation indicator area height]. Values outside this range are adjusted to the nearest boundary.| 803 804### start<sup>12+</sup> 805 806start(value: LengthMetrics): T 807 808Sets the distance between the navigation indicator and the right edge (in right-to-left scripts) or the left edge (in left-to-right scripts) of the **Swiper** component. 809 810**Widget capability**: This API can be used in ArkTS widgets since API version 12. 811 812**Atomic service API**: This API can be used in atomic services since API version 12. 813 814**System capability**: SystemCapability.ArkUI.ArkUI.Full 815 816**Parameters** 817 818| Name| Type | Mandatory| Description | 819| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 820| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Distance between the navigation indicator and the right edge (in right-to-left scripts) or the left edge (in left-to-right scripts) of the **Swiper** component.<br>Default value: **0**<br>Unit: vp| 821 822### end<sup>12+</sup> 823 824end(value: LengthMetrics): T 825 826Sets the distance between the navigation indicator and the left edge (in right-to-left scripts) or the right edge (in left-to-right scripts) of the **Swiper** component. 827 828**Widget capability**: This API can be used in ArkTS widgets since API version 12. 829 830**Atomic service API**: This API can be used in atomic services since API version 12. 831 832**System capability**: SystemCapability.ArkUI.ArkUI.Full 833 834**Parameters** 835 836| Name| Type | Mandatory | Description | 837| ------ | ---------------------------- | ---- | ---------------------------------------- | 838| value | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | Yes | Distance between the navigation indicator and the left edge (in right-to-left scripts) or the right edge (in left-to-right scripts) of the **Swiper** component.<br>Default value: **0**<br>Unit: vp | 839 840### dot 841 842static dot(): DotIndicator 843 844Returns a **DotIndicator** object. 845 846**Widget capability**: This API can be used in ArkTS widgets since API version 10. 847 848**Atomic service API**: This API can be used in atomic services since API version 11. 849 850**System capability**: SystemCapability.ArkUI.ArkUI.Full 851 852### digit 853 854static digit(): DigitIndicator 855 856Returns **DigitIndicator** object. 857 858**Widget capability**: This API can be used in ArkTS widgets since API version 10. 859 860**Atomic service API**: This API can be used in atomic services since API version 11. 861 862**System capability**: SystemCapability.ArkUI.ArkUI.Full 863 864## DotIndicator<sup>10+</sup> 865 866Constructs a dot indicator style. It extends from [Indicator] (#indicator10). 867 868**Atomic service API**: This API can be used in atomic services since API version 11. 869 870**System capability**: SystemCapability.ArkUI.ArkUI.Full 871 872### itemWidth 873 874itemWidth(value: Length): DotIndicator 875 876Sets the width of the dot-style navigation indicator. This parameter cannot be set in percentage. 877 878**Widget capability**: This API can be used in ArkTS widgets since API version 10. 879 880**Atomic service API**: This API can be used in atomic services since API version 11. 881 882**System capability**: SystemCapability.ArkUI.ArkUI.Full 883 884**Parameters** 885 886| Name| Type | Mandatory| Description | 887| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 888| value | [Length](ts-types.md#length) | Yes | Width of the dot-style navigation indicator. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp| 889 890**Return value** 891 892| Type | Description | 893| ------------------------------- | ------------ | 894| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 895 896### itemHeight 897 898itemHeight(value: Length): DotIndicator 899 900Sets the height of the dot-style navigation indicator. This parameter cannot be set in percentage. 901 902**Widget capability**: This API can be used in ArkTS widgets since API version 10. 903 904**Atomic service API**: This API can be used in atomic services since API version 11. 905 906**System capability**: SystemCapability.ArkUI.ArkUI.Full 907 908**Parameters** 909 910| Name| Type | Mandatory| Description | 911| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 912| value | [Length](ts-types.md#length) | Yes | Height of the dot-style navigation indicator. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp| 913 914**Return value** 915 916| Type | Description | 917| ------------------------------- | ------------ | 918| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 919 920### selectedItemWidth 921 922selectedItemWidth(value: Length): DotIndicator 923 924Sets the width of the selected dot in the dot-style navigation indicator. This parameter cannot be set in percentage. 925 926**Widget capability**: This API can be used in ArkTS widgets since API version 10. 927 928**Atomic service API**: This API can be used in atomic services since API version 11. 929 930**System capability**: SystemCapability.ArkUI.ArkUI.Full 931 932**Parameters** 933 934| Name| Type | Mandatory| Description | 935| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 936| value | [Length](ts-types.md#length) | Yes | Width of the selected dot in the dot-style navigation indicator. This parameter cannot be set in percentage.<br>Default value: **12**<br>Unit: vp| 937 938**Return value** 939 940| Type | Description | 941| ------------------------------- | ------------ | 942| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 943 944### selectedItemHeight 945 946selectedItemHeight(value: Length): DotIndicator 947 948Sets the height of the selected dot in the dot-style navigation indicator. This parameter cannot be set in percentage. 949 950**Widget capability**: This API can be used in ArkTS widgets since API version 10. 951 952**Atomic service API**: This API can be used in atomic services since API version 11. 953 954**System capability**: SystemCapability.ArkUI.ArkUI.Full 955 956**Parameters** 957 958| Name| Type | Mandatory| Description | 959| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 960| value | [Length](ts-types.md#length) | Yes | Height of the selected dot in the dot-style navigation indicator. This parameter cannot be set in percentage.<br>Default value: **6**<br>Unit: vp| 961 962**Return value** 963 964| Type | Description | 965| ------------------------------- | ------------ | 966| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 967 968### mask 969 970mask(value: boolean): DotIndicator 971 972Sets whether to enable the mask for the dot-style navigation indicator. 973 974**Widget capability**: This API can be used in ArkTS widgets since API version 10. 975 976**Atomic service API**: This API can be used in atomic services since API version 11. 977 978**System capability**: SystemCapability.ArkUI.ArkUI.Full 979 980**Parameters** 981 982| Name| Type | Mandatory| Description | 983| ------ | ------- | ---- | ------------------------------------------------------------ | 984| value | boolean | Yes | Whether to enable the mask for the dot-style navigation indicator.<br>Default value: **false**| 985 986**Return value** 987 988| Type | Description | 989| ------------------------------- | ------------ | 990| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 991 992### color 993 994color(value: ResourceColor): DotIndicator 995 996Sets the color of the dot-style navigation indicator. 997 998**Widget capability**: This API can be used in ArkTS widgets since API version 10. 999 1000**Atomic service API**: This API can be used in atomic services since API version 11. 1001 1002**System capability**: SystemCapability.ArkUI.ArkUI.Full 1003 1004**Parameters** 1005 1006| Name| Type | Mandatory| Description | 1007| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1008| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the dot-style navigation indicator.<br>Default value: **'\#182431'** (10% opacity)| 1009 1010**Return value** 1011 1012| Type | Description | 1013| ------------------------------- | ------------ | 1014| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 1015 1016### selectedColor 1017 1018selectedColor(value: ResourceColor): DotIndicator 1019 1020Sets the color of the selected dot in the dot-style navigation indicator. 1021 1022**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1023 1024**Atomic service API**: This API can be used in atomic services since API version 11. 1025 1026**System capability**: SystemCapability.ArkUI.ArkUI.Full 1027 1028**Parameters** 1029 1030| Name| Type | Mandatory| Description | 1031| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1032| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the selected dot in the dot-style navigation indicator.<br>Default value: **'\#007DFF'**| 1033 1034**Return value** 1035 1036| Type | Description | 1037| ------------------------------- | ------------ | 1038| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 1039 1040### maxDisplayCount<sup>12+</sup> 1041 1042maxDisplayCount(maxDisplayCount: number): DotIndicator 1043 1044Sets the maximum number of navigation dots in the dot-style navigation indicator. 1045 1046In a separate navigation indicator controller, this attribute has effect only when the controller is bound to a **Swiper** component. 1047 1048**Atomic service API**: This API can be used in atomic services since API version 12. 1049 1050**System capability**: SystemCapability.ArkUI.ArkUI.Full 1051 1052**Parameters** 1053 1054| Name | Type | Mandatory| Description | 1055| --------------- | ------ | ---- | ------------------------------------------------------------ | 1056| maxDisplayCount | number | Yes | Maximum number of navigation dots in the dot-style navigation indicator. If the actual number of navigation dots exceeds this limit, the overflow effect is activated, as shown in Example 5.<br>This parameter has no default value. If an invalid value is set, no overflow effect is applied.<br>Value range: 6–9<br>**NOTE**<br>In scenarios involving overflow display:<br>1. Interactive features, such as gestures and mouse operations, are not supported.<br>2. The position of the selected navigation dot corresponding to the middle page is not strictly fixed; it depends on the sequence of previous page-turning operations.<br>3. Currently, only scenarios with **displayCount** set to **1** are supported.| 1057 1058**Return value** 1059 1060| Type | Description | 1061| ------------------------------- | ------------ | 1062| [DotIndicator](#dotindicator10) | Dot-style navigation indicator.| 1063 1064### constructor 1065 1066constructor() 1067 1068A constructor used to create a **DotIndicator** object. 1069 1070**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1071 1072**Atomic service API**: This API can be used in atomic services since API version 11. 1073 1074**System capability**: SystemCapability.ArkUI.ArkUI.Full 1075 1076>**NOTE** 1077> 1078>When pressed, the navigation indicator is zoomed in to 1.33 times. To account for this, there is a certain distance between the navigation 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**. 1079 1080## DigitIndicator<sup>10+</sup> 1081 1082A constructor used to create a **DigitIndicator** object. It inherits from [Indicator](#indicator10). 1083 1084**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1085 1086**Atomic service API**: This API can be used in atomic services since API version 11. 1087 1088**System capability**: SystemCapability.ArkUI.ArkUI.Full 1089 1090>**NOTE** 1091> 1092>When pages are turned by group, the child nodes displayed in the digit-style navigation indicator do not count placeholder nodes.<br> 1093>The maximum value of [maxFontScale](ts-basic-components-text.md#maxfontscale12) for the digit-style navigation indicator is 2. 1094 1095### fontColor 1096 1097fontColor(value: ResourceColor): DigitIndicator 1098 1099Sets the font color of the digit-style navigation indicator. 1100 1101**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1102 1103**Atomic service API**: This API can be used in atomic services since API version 11. 1104 1105**System capability**: SystemCapability.ArkUI.ArkUI.Full 1106 1107**Parameters** 1108 1109| Name| Type | Mandatory| Description | 1110| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1111| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color of the digit-style navigation indicator.<br>Default value: **'\#ff182431'**| 1112 1113**Return value** 1114 1115| Type | Description | 1116| ----------------------------------- | ------------ | 1117| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| 1118 1119### selectedFontColor 1120 1121selectedFontColor(value: ResourceColor): DigitIndicator 1122 1123Sets the font color of the selected digit in the digit-style navigation indicator. 1124 1125**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1126 1127**Atomic service API**: This API can be used in atomic services since API version 11. 1128 1129**System capability**: SystemCapability.ArkUI.ArkUI.Full 1130 1131**Parameters** 1132 1133| Name| Type | Mandatory| Description | 1134| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 1135| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color of the selected digit in the digit-style navigation indicator.<br>Default value: **'\#ff182431'**| 1136 1137**Return value** 1138 1139| Type | Description | 1140| ----------------------------------- | ------------ | 1141| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| 1142 1143### digitFont 1144 1145digitFont(value: Font): DigitIndicator 1146 1147Sets the font style of the digit-style navigation indicator. 1148 1149**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1150 1151**Atomic service API**: This API can be used in atomic services since API version 11. 1152 1153**System capability**: SystemCapability.ArkUI.ArkUI.Full 1154 1155**Parameters** 1156 1157| Name| Type | Mandatory| Description | 1158| ------ | ------------------------ | ---- | ------------------------------------------------------------ | 1159| value | [Font](ts-types.md#font) | Yes | Font style of the digit-style navigation indicator.<br>Only the **size** and **weight** parameters in **Font** are adjustable. Setting **family** and **style** has no effect.<br>Default value:<br>{ size: 14, weight: FontWeight.Normal } | 1160 1161**Return value** 1162 1163| Type | Description | 1164| ----------------------------------- | ------------ | 1165| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| 1166 1167### selectedDigitFont 1168 1169selectedDigitFont(value: Font): DigitIndicator 1170 1171Sets the font style of the selected digit in the digit-style navigation indicator. 1172 1173**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1174 1175**Atomic service API**: This API can be used in atomic services since API version 11. 1176 1177**System capability**: SystemCapability.ArkUI.ArkUI.Full 1178 1179**Parameters** 1180 1181| Name| Type | Mandatory| Description | 1182| ------ | ------------------------ | ---- | ------------------------------------------------------------ | 1183| value | [Font](ts-types.md#font) | Yes | Font style of the selected digit in the digit-style navigation indicator.<br>Default value:<br>{ size: 14, weight: FontWeight.Normal } | 1184 1185>**NOTE** 1186> 1187> When pages are turned by group, the child nodes displayed in the digit-style navigation indicator do not count placeholder nodes. 1188 1189**Return value** 1190 1191| Type | Description | 1192| ----------------------------------- | ------------ | 1193| [DigitIndicator](#digitindicator10) | Digit-style navigation indicator.| 1194 1195### constructor 1196 1197constructor() 1198 1199A constructor used to create a **DigitIndicator** object. 1200 1201**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1202 1203**Atomic service API**: This API can be used in atomic services since API version 11. 1204 1205**System capability**: SystemCapability.ArkUI.ArkUI.Full 1206 1207## ArrowStyle<sup>10+</sup> 1208Describes the left and right arrow attributes. 1209 1210**Atomic service API**: This API can be used in atomic services since API version 11. 1211 1212**System capability**: SystemCapability.ArkUI.ArkUI.Full 1213 1214| Name | Type | Mandatory | Description | 1215| ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | 1216| showBackground | boolean | No | Whether to show the background for the arrow.<br>Default value: **false** | 1217| isSidebarMiddle | boolean | No | Whether the arrow is shown on either side of the navigation indicator.<br>Default value: **false**<br>(the arrow is shown on either side of the navigation indicator)| 1218| backgroundSize | [Length](ts-types.md#length) | No | Size of the background.<br>On both sides of the navigation indicator:<br>Default value: **24vp**<br>On both sides of the component:<br>Default value: **32vp**<br>This parameter cannot be set in percentage.| 1219| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the background.<br>On both sides of the navigation indicator:<br>Default value: **'\#00000000'**<br>On both sides of the component:<br>Default value: **'\#19182431'**| 1220| arrowSize | [Length](ts-types.md#length) | No | Size of the arrow.<br>On both sides of the navigation 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.| 1221| arrowColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the arrow.<br>Default value: **'\#182431'** | 1222 1223## SwiperAutoFill<sup>10+</sup> 1224 1225Describes the auto-fill attribute. 1226 1227**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1228 1229**Atomic service API**: This API can be used in atomic services since API version 11. 1230 1231**System capability**: SystemCapability.ArkUI.ArkUI.Full 1232 1233| Name | Type | Mandatory| Description | 1234| ------- | -------------------- | ------ | ------------------------------------ | 1235| minSize | [VP](ts-types.md#vp10) | Yes | Minimum width of the element.<br>Default value: **0**| 1236 1237## AutoPlayOptions<sup>18+</sup> 1238 1239Defines the properties for controlling the autoplay behavior. 1240 1241**Widget capability**: This API can be used in ArkTS widgets since API version 18. 1242 1243**Atomic service API**: This API can be used in atomic services since API version 18. 1244 1245**System capability**: SystemCapability.ArkUI.ArkUI.Full 1246 1247| Name | Type | Mandatory | Description | 1248| ---------------- | ---------------------------------------- | ---- | ---------------------------------------- | 1249| stopWhenTouched | boolean | Yes | Whether the autoplay stops immediately when the component is touched.<br>Default value: **true**| 1250 1251## Events 1252 1253In addition to the [universal events](ts-component-general-events.md), the following events are supported. 1254 1255### onChange 1256 1257onChange(event: Callback\<number>) 1258 1259Triggered when the index of the currently displayed child component changes. The return value is the index of the currently displayed child component. 1260 1261When the **Swiper** component is used together with **LazyForEach**, the subpage UI update cannot be triggered in the **onChange** event. 1262 1263**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1264 1265**Atomic service API**: This API can be used in atomic services since API version 11. 1266 1267**System capability**: SystemCapability.ArkUI.ArkUI.Full 1268 1269**Parameters** 1270 1271| Name| Type | Mandatory| Description | 1272| ------ | ------ | ---- | -------------------- | 1273| event | [Callback](./ts-types.md#callback12)\<number> | Yes | Index of the currently displayed element.| 1274 1275### onAnimationStart<sup>9+</sup> 1276 1277onAnimationStart(event: OnSwiperAnimationStartCallback) 1278 1279Triggered when the switching animation starts. 1280 1281**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1282 1283**Atomic service API**: This API can be used in atomic services since API version 11. 1284 1285**System capability**: SystemCapability.ArkUI.ArkUI.Full 1286 1287**Parameters** 1288 1289| Name| Type | Mandatory| Description | 1290| ------ | ------ | ---- | -------------------- | 1291| event | [OnSwiperAnimationStartCallback](#onswiperanimationstartcallback18) | Yes | Callback triggered when the switching animation starts.| 1292 1293>**NOTE** 1294> 1295>- When the duration of the switching animation is set to 0, this callback is triggered only in the following scenarios: swiping to turn pages, automatic playback, calling **SwiperController.showNext()** or **SwiperController.showPrevious()**, and touching navigation points to navigate. 1296 1297### onAnimationEnd<sup>9+</sup> 1298 1299onAnimationEnd(event: OnSwiperAnimationEndCallback) 1300 1301Triggered when the switching animation ends. 1302 1303This 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. 1304 1305**Widget capability**: This API can be used in ArkTS widgets since API version 10. 1306 1307**Atomic service API**: This API can be used in atomic services since API version 11. 1308 1309**System capability**: SystemCapability.ArkUI.ArkUI.Full 1310 1311**Parameters** 1312 1313| Name| Type | Mandatory| Description | 1314| ------ | ------ | ---- | -------------------- | 1315| event | [OnSwiperAnimationEndCallback](#onswiperanimationendcallback18) | Yes | Callback triggered when the switching animation ends.| 1316 1317>**NOTE** 1318> 1319>- When the duration of the switching animation is set to 0, this callback is triggered only in the following scenarios: swiping to turn pages, automatic playback, calling **SwiperController.showNext()** or **SwiperController.showPrevious()**, and touching navigation points to navigate. 1320 1321### onGestureSwipe<sup>10+</sup> 1322 1323onGestureSwipe(event: OnSwiperGestureSwipeCallback) 1324 1325Triggered on a frame-by-frame basis when the page is turned by a swipe. 1326 1327**Atomic service API**: This API can be used in atomic services since API version 11. 1328 1329**System capability**: SystemCapability.ArkUI.ArkUI.Full 1330 1331**Parameters** 1332 1333| Name| Type | Mandatory| Description | 1334| ------ | ------ | ---- | -------------------- | 1335| event | [OnSwiperGestureSwipeCallback](#onswipergestureswipecallback18) | Yes | Callback triggered on a frame-by-frame basis when the page is turned by a swipe.| 1336 1337### customContentTransition<sup>12+</sup> 1338 1339customContentTransition(transition: SwiperContentAnimatedTransition) 1340 1341Defines 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. 1342 1343Instructions: 1344 13451. 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][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** 1346 1347**Atomic service API**: This API can be used in atomic services since API version 12. 1348 1349**System capability**: SystemCapability.ArkUI.ArkUI.Full 1350 1351**Parameters** 1352 1353| Name| Type| Mandatory| Description| 1354| ------ | ---- | ---- | ---- | 1355| transition | [SwiperContentAnimatedTransition](#swipercontentanimatedtransition12) | Yes| Information about the custom switching animation.| 1356 1357### onContentDidScroll<sup>12+</sup> 1358 1359onContentDidScroll(handler: ContentDidScrollCallback) 1360 1361Triggered when content in the **Swiper** component scrolls. 1362 1363Instructions: 1364 13651. 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. 1366 1367**Atomic service API**: This API can be used in atomic services since API version 12. 1368 1369**System capability**: SystemCapability.ArkUI.ArkUI.Full 1370 1371**Parameters** 1372 1373| Name| Type| Mandatory| Description| 1374| ------ | ---- | ---- | ---- | 1375| handler | [ContentDidScrollCallback](#contentdidscrollcallback12) | Yes| Callback triggered when content in the **Swiper** component scrolls.| 1376 1377### onSelected<sup>18+</sup> 1378 1379onSelected(event: Callback\<number>) 1380 1381Triggered when the selected element changes. The index of the currently selected element is returned. 1382 1383**Widget capability**: This API can be used in ArkTS widgets since API version 18. 1384 1385**Atomic service API**: This API can be used in atomic services since API version 18. 1386 1387**System capability**: SystemCapability.ArkUI.ArkUI.Full 1388 1389**Parameters** 1390 1391| Name| Type | Mandatory| Description | 1392| ------ | ------ | ---- | -------------------- | 1393| event | [Callback](./ts-types.md#callback12)\<number> | Yes | Index of the currently selected element.| 1394 1395> **NOTE** 1396> 1397> In the **onSelected** callback, do not modify the **index** attribute of the **Swiper** component, or call the **SwiperController.changeIndex()**, **SwiperController.showNext()**, or **SwiperController.showPrevious()** APIs. 1398 1399### onUnselected<sup>18+</sup> 1400 1401onUnselected(event: Callback\<number>) 1402 1403Triggered when the selected element changes. The index of the element that is about to be hidden is returned. 1404 1405**Widget capability**: This API can be used in ArkTS widgets since API version 18. 1406 1407**Atomic service API**: This API can be used in atomic services since API version 18. 1408 1409**System capability**: SystemCapability.ArkUI.ArkUI.Full 1410 1411**Parameters** 1412 1413| Name| Type | Mandatory| Description | 1414| ------ | ------ | ---- | -------------------- | 1415| event | [Callback](./ts-types.md#callback12)\<number> | Yes | Index of the element that is about to be hidden.| 1416 1417> **NOTE** 1418> 1419> In the **onUnselected** callback, do not modify the **index** attribute of the **Swiper** component, nor call the **SwiperController.changeIndex()**, **SwiperController.showNext()**, or **SwiperController.showPrevious()** APIs. 1420 1421### onContentWillScroll<sup>15+</sup> 1422 1423onContentWillScroll(handler: ContentWillScrollCallback) 1424 1425Triggered when the **Swiper** component is about to scroll. This event allows you to intercept and control the scrolling behavior of the component. The component determines whether to allow the scroll action based on the return value. If **true** is returned, the scroll action is allowed, and the pages in the **Swiper** component will follow the scrolling. If **false** is returned, the scroll action is disallowed, and the pages will remain stationary. 1426 14271. This event is only triggered by gesture operations, including finger swipes, scrolling the mouse wheel, and moving focus using keyboard arrow keys. 1428 14292. During finger swipes, the event is triggered for each frame. The system uses the return value of the event to determine whether to respond to the swipe for each frame. 1430 14313. For scrolling the mouse wheel and moving focus using keyboard arrow keys, the event is triggered once per page turning. The system uses the return value to decide whether to allow the page turning. 1432 1433**Widget capability**: This API can be used in ArkTS widgets since API version 15. 1434 1435**Atomic service API**: This API can be used in atomic services since API version 15. 1436 1437**System capability**: SystemCapability.ArkUI.ArkUI.Full 1438 1439**Parameters** 1440 1441| Name| Type| Mandatory| Description| 1442| ------ | ---- | ---- | ---- | 1443| handler | [ContentWillScrollCallback](#contentwillscrollcallback15) | Yes| Callback triggered when content in the **Swiper** component scrolls.| 1444 1445## OnSwiperAnimationStartCallback<sup>18+</sup> 1446 1447type OnSwiperAnimationStartCallback = (index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => void 1448 1449Defines the callback triggered when the switching animation starts. 1450 1451**Widget capability**: This API can be used in ArkTS widgets since API version 18. 1452 1453**Atomic service API**: This API can be used in atomic services since API version 18. 1454 1455**System capability**: SystemCapability.ArkUI.ArkUI.Full 1456 1457**Parameters** 1458 1459| Name | Type | Mandatory| Description | 1460| ------------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1461| index | number | Yes | Index of the currently displayed element. If there are multiple columns, **index** indicates the index of the leftmost component. | 1462| targetIndex<sup>10+</sup> | number | Yes | Index of the target element to switch to. | 1463| 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.| 1464 1465## OnSwiperAnimationEndCallback<sup>18+</sup> 1466 1467type OnSwiperAnimationEndCallback = (index: number, extraInfo: SwiperAnimationEvent) => void 1468 1469Defines the callback triggered when the switching animation ends. 1470 1471**Widget capability**: This API can be used in ArkTS widgets since API version 18. 1472 1473**Atomic service API**: This API can be used in atomic services since API version 18. 1474 1475**System capability**: SystemCapability.ArkUI.ArkUI.Full 1476 1477**Parameters** 1478 1479| Name | Type | Mandatory| Description | 1480| ----------------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1481| index | number | Yes | Index of the currently displayed element. If there are multiple columns, **index** indicates the index of the leftmost component. | 1482| 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.| 1483 1484## OnSwiperGestureSwipeCallback<sup>18+</sup> 1485 1486type OnSwiperGestureSwipeCallback = (index: number, extraInfo: SwiperAnimationEvent) => void 1487 1488Defines the callback triggered on a frame-by-frame basis when the page is turned by a swipe. 1489 1490**Atomic service API**: This API can be used in atomic services since API version 18. 1491 1492**System capability**: SystemCapability.ArkUI.ArkUI.Full 1493 1494**Parameters** 1495 1496| Name | Type | Mandatory| Description | 1497| --------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1498| index | number | Yes | Index of the currently displayed element. If there are multiple columns, **index** indicates the index of the leftmost component. | 1499| 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.| 1500 1501## ContentDidScrollCallback<sup>12+</sup> 1502 1503type ContentDidScrollCallback = (selectedIndex: number, index: number, position: number, mainAxisLength: number) => void 1504 1505Triggered during the swipe action of the **Swiper** component. For details about the parameters, see [SwiperContentTransitionProxy](#swipercontenttransitionproxy12). 1506 1507**Atomic service API**: This API can be used in atomic services since API version 12. 1508 1509**System capability**: SystemCapability.ArkUI.ArkUI.Full 1510 1511| Name| Type| Mandatory| Description| 1512| ------ | ---- | ---- | ---- | 1513| selectedIndex | number | Yes| Index of the currently selected page.| 1514| index | number | Yes| Index of a page in the viewport.| 1515| 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**).| 1516| mainAxisLength | number | Yes| Length of the page specified by **index** along the main axis.| 1517 1518## ContentWillScrollCallback<sup>15+</sup> 1519 1520type ContentWillScrollCallback = (result: SwiperContentWillScrollResult) => boolean 1521 1522Defines the callback triggered when the **Swiper** component is about to scroll. The return value indicates whether the scroll action is allowed. 1523 1524**Widget capability**: This API can be used in ArkTS widgets since API version 15. 1525 1526**Atomic service API**: This API can be used in atomic services since API version 15. 1527 1528**System capability**: SystemCapability.ArkUI.ArkUI.Full 1529 1530**Parameters** 1531 1532| Name| Type| Mandatory| Description| 1533| ------ | ---- | ---- | ---- | 1534| result | [SwiperContentWillScrollResult](#swipercontentwillscrollresult15) | Yes| Information related to the upcoming scroll action, including the index of the current page, the index of the page that will be displayed in the scroll direction, and the displacement of the scroll action.| 1535 1536**Return value** 1537 1538| Type| Description| 1539| ------ | ---- | 1540| boolean | Whether the scroll action is allowed. The value **true** means the scroll action is allowed, and **false** means the opposite.| 1541 1542## SwiperContentWillScrollResult<sup>15+</sup> 1543 1544Provides information related to the upcoming scroll action, including the index of the current page, the index of the page that will be displayed in the scroll direction, and the displacement of the scroll action. 1545 1546**Widget capability**: This API can be used in ArkTS widgets since API version 15. 1547 1548**Atomic service API**: This API can be used in atomic services since API version 15. 1549 1550**System capability**: SystemCapability.ArkUI.ArkUI.Full 1551 1552| Name| Type| Mandatory| Description| 1553| ------ | ---- | ---- | ---- | 1554| currentIndex | number | Yes| Index of the current page. During a finger swipe, this value remains constant as long as the finger is on the screen, even if the page has completely moved out of view.| 1555| comingIndex | number | Yes| Index of the page that will be displayed in the scroll direction.| 1556| offset | number | Yes| Displacement of the scroll action, which is signed to indicate different swipe directions. A positive value indicates a swipe from index=1 to index=0, while a negative value indicates a swipe from index=0 to index=1.<br>This value represents the offset for each frame during a finger swipe and the distance for page turning when the mouse wheel or keyboard navigation is used.| 1557 1558## SwiperAnimationEvent<sup>10+</sup> 1559 1560Describes the animation information of the **Swiper** component. 1561 1562**Atomic service API**: This API can be used in atomic services since API version 11. 1563 1564**System capability**: SystemCapability.ArkUI.ArkUI.Full 1565 1566| Name | Type | Read Only| Optional| Description | 1567| ------------- | ----------- | ---- | ---- |------------------------------- | 1568| 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**| 1569| 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**| 1570| velocity | number | No| No| Hands-off velocity at the beginning of the animation. Unit: VP/S<br>Default value: **0**| 1571 1572## SwiperContentAnimatedTransition<sup>12+</sup> 1573 1574Information about the custom page switching animation. 1575 1576**Atomic service API**: This API can be used in atomic services since API version 12. 1577 1578**System capability**: SystemCapability.ArkUI.ArkUI.Full 1579 1580| Name| Type| Mandatory| Description| 1581| ------ | ---- | ---- | ---- | 1582| 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**.| 1583| transition | Callback<[SwiperContentTransitionProxy](#swipercontenttransitionproxy12)> | Yes| Content of the custom switching animation.| 1584 1585## SwiperContentTransitionProxy<sup>12+</sup> 1586 1587Implements 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. 1588 1589**Atomic service API**: This API can be used in atomic services since API version 12. 1590 1591**System capability**: SystemCapability.ArkUI.ArkUI.Full 1592 1593### Attributes 1594 1595| Name| Type| Read Only| Optional| Description| 1596| ---- | ---- | --- | ---- | --- | 1597| selectedIndex | number | No| No| Index of the currently selected page.| 1598| index | number | No| No| Index of a page in the viewport.| 1599| 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**).| 1600| mainAxisLength | number | No| No| Length of the page specified by **index** along the main axis.| 1601 1602>**NOTE** 1603> 1604>- 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. 1605> 1606>- 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. 1607 1608 1609### finishTransition<sup>12+</sup> 1610 1611finishTransition(): void 1612 1613Notifies the **Swiper** component that the custom animation has finished playing. 1614 1615**Atomic service API**: This API can be used in atomic services since API version 12. 1616 1617**System capability**: SystemCapability.ArkUI.ArkUI.Full 1618 1619## Example 1620 1621### Example 1: Setting the Navigation Indicator Interaction and Page Turning Effect 1622 1623This example demonstrates how to use the **changeIndex** API with **SwiperAnimationMode** to move to a specific page in the **Swiper** component. 1624 1625```ts 1626// xxx.ets 1627class MyDataSource implements IDataSource { 1628 private list: number[] = [] 1629 1630 constructor(list: number[]) { 1631 this.list = list 1632 } 1633 1634 totalCount(): number { 1635 return this.list.length 1636 } 1637 1638 getData(index: number): number { 1639 return this.list[index] 1640 } 1641 1642 registerDataChangeListener(listener: DataChangeListener): void { 1643 } 1644 1645 unregisterDataChangeListener() { 1646 } 1647} 1648 1649@Entry 1650@Component 1651struct SwiperExample { 1652 private swiperController: SwiperController = new SwiperController() 1653 private data: MyDataSource = new MyDataSource([]) 1654 1655 aboutToAppear(): void { 1656 let list: number[] = [] 1657 for (let i = 1; i <= 10; i++) { 1658 list.push(i); 1659 } 1660 this.data = new MyDataSource(list) 1661 } 1662 1663 build() { 1664 Column({ space: 5 }) { 1665 Swiper(this.swiperController) { 1666 LazyForEach(this.data, (item: string) => { 1667 Text(item.toString()) 1668 .width('90%') 1669 .height(160) 1670 .backgroundColor(0xAFEEEE) 1671 .textAlign(TextAlign.Center) 1672 .fontSize(30) 1673 }, (item: string) => item) 1674 } 1675 .cachedCount(2) 1676 .index(1) 1677 .autoPlay(true) 1678 .interval(4000) 1679 .loop(true) 1680 .indicatorInteractive(true) 1681 .duration(1000) 1682 .itemSpace(0) 1683 .indicator( // Set the style of the navigation indicator. 1684 new DotIndicator() 1685 .itemWidth(15) 1686 .itemHeight(15) 1687 .selectedItemWidth(15) 1688 .selectedItemHeight(15) 1689 .color(Color.Gray) 1690 .selectedColor(Color.Blue)) 1691 .displayArrow({ // Set the arrow style of the navigation indicator. 1692 showBackground: true, 1693 isSidebarMiddle: true, 1694 backgroundSize: 24, 1695 backgroundColor: Color.White, 1696 arrowSize: 18, 1697 arrowColor: Color.Blue 1698 }, false) 1699 .curve(Curve.Linear) 1700 .onChange((index: number) => { 1701 console.info(index.toString()) 1702 }) 1703 .onGestureSwipe((index: number, extraInfo: SwiperAnimationEvent) => { 1704 console.info("index: " + index) 1705 console.info("current offset: " + extraInfo.currentOffset) 1706 }) 1707 .onAnimationStart((index: number, targetIndex: number, extraInfo: SwiperAnimationEvent) => { 1708 console.info("index: " + index) 1709 console.info("targetIndex: " + targetIndex) 1710 console.info("current offset: " + extraInfo.currentOffset) 1711 console.info("target offset: " + extraInfo.targetOffset) 1712 console.info("velocity: " + extraInfo.velocity) 1713 }) 1714 .onAnimationEnd((index: number, extraInfo: SwiperAnimationEvent) => { 1715 console.info("index: " + index) 1716 console.info("current offset: " + extraInfo.currentOffset) 1717 }) 1718 1719 Row({ space: 12 }) { 1720 Button('showNext') 1721 .onClick(() => { 1722 this.swiperController.showNext() 1723 }) 1724 Button('showPrevious') 1725 .onClick(() => { 1726 this.swiperController.showPrevious() 1727 }) 1728 }.margin(5) 1729 Row({ space: 5 }) { 1730 Button('FAST 0') 1731 .onClick(() => { 1732 this.swiperController.changeIndex(0, SwiperAnimationMode.FAST_ANIMATION) 1733 }) 1734 Button('FAST 3') 1735 .onClick(() => { 1736 this.swiperController.changeIndex(3, SwiperAnimationMode.FAST_ANIMATION) 1737 }) 1738 Button('FAST ' + 9) 1739 .onClick(() => { 1740 this.swiperController.changeIndex(9, SwiperAnimationMode.FAST_ANIMATION) 1741 }) 1742 }.margin(5) 1743 }.width('100%') 1744 .margin({ top: 5 }) 1745 } 1746} 1747``` 1748 1749 1750 1751### Example 2: Implementing a Digit Indicator 1752 1753This example showcases how to implement a digit indicator using the **DigitIndicator** API. 1754 1755```ts 1756// xxx.ets 1757class MyDataSource implements IDataSource { 1758 private list: number[] = [] 1759 1760 constructor(list: number[]) { 1761 this.list = list 1762 } 1763 1764 totalCount(): number { 1765 return this.list.length 1766 } 1767 1768 getData(index: number): number { 1769 return this.list[index] 1770 } 1771 1772 registerDataChangeListener(listener: DataChangeListener): void { 1773 } 1774 1775 unregisterDataChangeListener() { 1776 } 1777} 1778 1779@Entry 1780@Component 1781struct SwiperExample { 1782 private swiperController: SwiperController = new SwiperController() 1783 private data: MyDataSource = new MyDataSource([]) 1784 1785 aboutToAppear(): void { 1786 let list: number[] = [] 1787 for (let i = 1; i <= 10; i++) { 1788 list.push(i); 1789 } 1790 this.data = new MyDataSource(list) 1791 } 1792 1793 build() { 1794 Column({ space: 5 }) { 1795 Swiper(this.swiperController) { 1796 LazyForEach(this.data, (item: string) => { 1797 Text(item.toString()) 1798 .width('90%') 1799 .height(160) 1800 .backgroundColor(0xAFEEEE) 1801 .textAlign(TextAlign.Center) 1802 .fontSize(30) 1803 }, (item: string) => item) 1804 } 1805 .cachedCount(2) 1806 .index(1) 1807 .autoPlay(true) 1808 .interval(4000) 1809 .indicator(Indicator.digit() // Set the digit-style navigation indicator. 1810 .top(200) 1811 .fontColor(Color.Gray) 1812 .selectedFontColor(Color.Gray) 1813 .digitFont({ size: 20, weight: FontWeight.Bold }) 1814 .selectedDigitFont({ size: 20, weight: FontWeight.Normal })) 1815 .loop(true) 1816 .duration(1000) 1817 .itemSpace(0) 1818 .displayArrow(true, false) 1819 1820 Row({ space: 12 }) { 1821 Button('showNext') 1822 .onClick(() => { 1823 this.swiperController.showNext() 1824 }) 1825 Button('showPrevious') 1826 .onClick(() => { 1827 this.swiperController.showPrevious() 1828 }) 1829 }.margin(5) 1830 }.width('100%') 1831 .margin({ top: 5 }) 1832 } 1833} 1834``` 1835 1836 1837### Example 3: Configuring Group Page-Turning 1838 1839This example illustrates the group page-turning effect using the **displayCount** property. 1840 1841```ts 1842// xxx.ets 1843class MyDataSource implements IDataSource { 1844 private list: number[] = [] 1845 1846 constructor(list: number[]) { 1847 this.list = list 1848 } 1849 1850 totalCount(): number { 1851 return this.list.length 1852 } 1853 1854 getData(index: number): number { 1855 return this.list[index] 1856 } 1857 1858 registerDataChangeListener(listener: DataChangeListener): void { 1859 } 1860 1861 unregisterDataChangeListener() { 1862 } 1863} 1864 1865@Entry 1866@Component 1867struct SwiperExample { 1868 private swiperController: SwiperController = new SwiperController() 1869 private data: MyDataSource = new MyDataSource([]) 1870 1871 aboutToAppear(): void { 1872 let list: number[] = [] 1873 for (let i = 1; i <= 10; i++) { 1874 list.push(i); 1875 } 1876 this.data = new MyDataSource(list) 1877 } 1878 1879 build() { 1880 Column({ space: 5 }) { 1881 Swiper(this.swiperController) { 1882 LazyForEach(this.data, (item: string) => { 1883 Text(item.toString()) 1884 .width('90%') 1885 .height(160) 1886 .backgroundColor(0xAFEEEE) 1887 .textAlign(TextAlign.Center) 1888 .fontSize(30) 1889 }, (item: string) => item) 1890 } 1891 .displayCount(3, true) 1892 .autoPlay(true) 1893 .interval(4000) 1894 .loop(true) 1895 .duration(1000) 1896 .itemSpace(10) 1897 .indicator( // Set the style of the navigation indicator. 1898 new DotIndicator() 1899 .itemWidth(15) 1900 .itemHeight(15) 1901 .selectedItemWidth(15) 1902 .selectedItemHeight(15) 1903 .color(Color.Gray) 1904 .selectedColor(Color.Blue)) 1905 1906 Row({ space: 12 }) { 1907 Button('showNext') 1908 .onClick(() => { 1909 this.swiperController.showNext() 1910 }) 1911 Button('showPrevious') 1912 .onClick(() => { 1913 this.swiperController.showPrevious() 1914 }) 1915 }.margin(5) 1916 }.width('100%') 1917 .margin({ top: 5 }) 1918 } 1919} 1920``` 1921 1922 1923### Example 4: Customizing the Page Switching Animation 1924 1925This example presents how to implement a custom page turning animation for the **Swiper** component through the **customContentTransition** API. 1926 1927```ts 1928// xxx.ets 1929@Entry 1930@Component 1931struct SwiperCustomAnimationExample { 1932 private DISPLAY_COUNT: number = 2 1933 private MIN_SCALE: number = 0.75 1934 1935 @State backgroundColors: Color[] = [Color.Green, Color.Blue, Color.Yellow, Color.Pink, Color.Gray, Color.Orange] 1936 @State opacityList: number[] = [] 1937 @State scaleList: number[] = [] 1938 @State translateList: number[] = [] 1939 @State zIndexList: number[] = [] 1940 1941 aboutToAppear(): void { 1942 for (let i = 0; i < this.backgroundColors.length; i++) { 1943 this.opacityList.push(1.0) 1944 this.scaleList.push(1.0) 1945 this.translateList.push(0.0) 1946 this.zIndexList.push(0) 1947 } 1948 } 1949 1950 build() { 1951 Column() { 1952 Swiper() { 1953 ForEach(this.backgroundColors, (backgroundColor: Color, index: number) => { 1954 Text(index.toString()).width('100%').height('100%').fontSize(50).textAlign(TextAlign.Center) 1955 .backgroundColor(backgroundColor) 1956 // Customize how the opacity, scale, translate, and other attributes change during the custom switching animation. 1957 .opacity(this.opacityList[index]) 1958 .scale({ x: this.scaleList[index], y: this.scaleList[index] }) 1959 .translate({ x: this.translateList[index] }) 1960 .zIndex(this.zIndexList[index]) 1961 }) 1962 } 1963 .height(300) 1964 .indicator(false) 1965 .displayCount(this.DISPLAY_COUNT, true) 1966 .customContentTransition({ 1967 // The page is removed from the render tree when 1000 ms (timeout time) has elapsed. 1968 timeout: 1000, 1969 // 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. 1970 transition: (proxy: SwiperContentTransitionProxy) => { 1971 if (proxy.position <= proxy.index % this.DISPLAY_COUNT || proxy.position >= this.DISPLAY_COUNT + proxy.index % this.DISPLAY_COUNT) { 1972 // 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. 1973 this.opacityList[proxy.index] = 1.0 1974 this.scaleList[proxy.index] = 1.0 1975 this.translateList[proxy.index] = 0.0 1976 this.zIndexList[proxy.index] = 0 1977 } else { 1978 // 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. 1979 if (proxy.index % this.DISPLAY_COUNT === 0) { 1980 this.opacityList[proxy.index] = 1 - proxy.position / this.DISPLAY_COUNT 1981 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - proxy.position / this.DISPLAY_COUNT) 1982 this.translateList[proxy.index] = - proxy.position * proxy.mainAxisLength + (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 1983 } else { 1984 this.opacityList[proxy.index] = 1 - (proxy.position - 1) / this.DISPLAY_COUNT 1985 this.scaleList[proxy.index] = this.MIN_SCALE + (1 - this.MIN_SCALE) * (1 - (proxy.position - 1) / this.DISPLAY_COUNT) 1986 this.translateList[proxy.index] = - (proxy.position - 1) * proxy.mainAxisLength - (1 - this.scaleList[proxy.index]) * proxy.mainAxisLength / 2.0 1987 } 1988 this.zIndexList[proxy.index] = -1 1989 } 1990 } 1991 }) 1992 .onContentDidScroll((selectedIndex: number, index: number, position: number, mainAxisLength: number) => { 1993 // Called when content in the <Swiper> component scrolls. In this callback, you can customize the navigation indicator switching animation. 1994 console.info("onContentDidScroll selectedIndex: " + selectedIndex + ", index: " + index + ", position: " + position + ", mainAxisLength: " + mainAxisLength) 1995 }) 1996 }.width('100%') 1997 } 1998} 1999``` 2000 2001 2002### Example 5: Configuring Overflow for the Dot Indicator 2003 2004This example illustrates the activation of the overflow effect when the number of navigation dots exceeds the limit set through the **maxDisplayCount** property of the **DotIndicator** API. 2005 2006```ts 2007class MyDataSource implements IDataSource { 2008 private list: number[] = [] 2009 2010 constructor(list: number[]) { 2011 this.list = list 2012 } 2013 2014 totalCount(): number { 2015 return this.list.length 2016 } 2017 2018 getData(index: number): number { 2019 return this.list[index] 2020 } 2021 2022 registerDataChangeListener(listener: DataChangeListener): void { 2023 } 2024 2025 unregisterDataChangeListener() { 2026 } 2027} 2028 2029@Entry 2030@Component 2031struct Index { 2032 private swiperController: SwiperController = new SwiperController() 2033 private data: MyDataSource = new MyDataSource([]) 2034 2035 aboutToAppear(): void { 2036 let list: number[] = [] 2037 for (let i = 1; i <= 15; i++) { 2038 list.push(i); 2039 } 2040 this.data = new MyDataSource(list) 2041 } 2042 2043 build() { 2044 Column({ space: 5 }) { 2045 Swiper(this.swiperController) { 2046 LazyForEach(this.data, (item: string) => { 2047 Text(item.toString()) 2048 .width('90%') 2049 .height(160) 2050 .backgroundColor(0xAFEEEE) 2051 .textAlign(TextAlign.Center) 2052 .fontSize(30) 2053 }, (item: string) => item) 2054 } 2055 .cachedCount(2) 2056 .index(5) 2057 .autoPlay(true) 2058 .interval(4000) 2059 .loop(true) 2060 .duration(1000) 2061 .itemSpace(0) 2062 .indicator( // Set the style of the navigation indicator. 2063 new DotIndicator() 2064 .itemWidth(8) 2065 .itemHeight(8) 2066 .selectedItemWidth(16) 2067 .selectedItemHeight(8) 2068 .color(Color.Gray) 2069 .selectedColor(Color.Blue) 2070 .maxDisplayCount(9)) 2071 .displayArrow({ // Set the arrow style of the navigation indicator. 2072 showBackground: true, 2073 isSidebarMiddle: true, 2074 backgroundSize: 24, 2075 backgroundColor: Color.White, 2076 arrowSize: 18, 2077 arrowColor: Color.Blue 2078 }, false) 2079 .curve(Curve.Linear) 2080 Row({ space: 12 }) { 2081 Button('showNext') 2082 .onClick(() => { 2083 this.swiperController.showNext() 2084 }) 2085 Button('showPrevious') 2086 .onClick(() => { 2087 this.swiperController.showPrevious() 2088 }) 2089 }.margin(5) 2090 }.width('100%') 2091 .margin({ top: 5 }) 2092 } 2093} 2094``` 2095 2096 2097 2098### Example 6: Preloading Child Nodes 2099 2100This example shows how to use the **preloadItems** API to preload specified child nodes. 2101 2102```ts 2103// xxx.ets 2104import { BusinessError } from '@kit.BasicServicesKit' 2105 2106@Entry 2107@Component 2108struct SwiperPreloadItems { 2109 @State currentIndex: number = 1 2110 private swiperController: SwiperController = new SwiperController() 2111 @State arr: string[] = ["0", "1", "2", "3", "4", "5"] 2112 2113 build() { 2114 Column() { 2115 Swiper(this.swiperController) { 2116 ForEach(this.arr, (item: string) => { 2117 MyComponent({ txt: item }) 2118 }) 2119 } 2120 .cachedCount(1, true) 2121 .width("70%") 2122 .height("50%") 2123 2124 2125 Button('preload items: [2, 3]') 2126 .margin(5) 2127 .onClick(() => { 2128 // Preload child nodes with index=2 and index=3. 2129 try { 2130 this.swiperController.preloadItems([2, 3]) 2131 .then(() => { 2132 console.info('preloadItems [2, 3] success.') 2133 }) 2134 .catch((error: BusinessError) => { 2135 console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message) 2136 }) 2137 } catch (error) { 2138 console.error('preloadItems [2, 3] failed, error code: ' + error.code + ', error message: ' + error.message) 2139 } 2140 2141 }) 2142 } 2143 .width("100%") 2144 .margin(5) 2145 } 2146} 2147 2148@Component 2149struct MyComponent { 2150 private txt: string = "" 2151 2152 aboutToAppear(): void { 2153 console.info('aboutToAppear txt:' + this.txt) 2154 } 2155 2156 aboutToDisappear(): void { 2157 console.info('aboutToDisappear txt:' + this.txt) 2158 } 2159 2160 build() { 2161 Text(this.txt) 2162 .textAlign(TextAlign.Center) 2163 .width('100%') 2164 .height('100%') 2165 .backgroundColor(0xAFEEEE) 2166 } 2167} 2168``` 2169 2170### Example 7: Implementing Synchronized Switching Between the Tabs and Swiper Components 2171 2172This example shows how to implement synchronized switching between the **Tabs** and **Swiper** components using the **onSelected** callback. 2173 2174```ts 2175// xxx.ets 2176class MyDataSource implements IDataSource { 2177 private list: number[] = [] 2178 2179 constructor(list: number[]) { 2180 this.list = list 2181 } 2182 2183 totalCount(): number { 2184 return this.list.length 2185 } 2186 2187 getData(index: number): number { 2188 return this.list[index] 2189 } 2190 2191 registerDataChangeListener(listener: DataChangeListener): void { 2192 } 2193 2194 unregisterDataChangeListener() { 2195 } 2196} 2197 2198@Entry 2199@Component 2200struct TabsSwiperExample { 2201 @State fontColor: string = '#182431' 2202 @State selectedFontColor: string = '#007DFF' 2203 @State currentIndex: number = 0 2204 private list: number[] = [] 2205 private tabsController: TabsController = new TabsController() 2206 private swiperController: SwiperController = new SwiperController() 2207 private swiperData: MyDataSource = new MyDataSource([]) 2208 2209 aboutToAppear(): void { 2210 for (let i = 0; i <= 9; i++) { 2211 this.list.push(i); 2212 } 2213 this.swiperData = new MyDataSource(this.list) 2214 } 2215 2216 @Builder tabBuilder(index: number, name: string) { 2217 Column() { 2218 Text(name) 2219 .fontColor(this.currentIndex === index ? this.selectedFontColor : this.fontColor) 2220 .fontSize(16) 2221 .fontWeight(this.currentIndex === index ? 500 : 400) 2222 .lineHeight(22) 2223 .margin({ top: 17, bottom: 7 }) 2224 Divider() 2225 .strokeWidth(2) 2226 .color('#007DFF') 2227 .opacity(this.currentIndex === index ? 1 : 0) 2228 }.width('20%') 2229 } 2230 2231 build() { 2232 Column() { 2233 Tabs({ barPosition: BarPosition.Start, controller: this.tabsController }) { 2234 ForEach(this.list, (index: number) =>{ 2235 TabContent().tabBar(this.tabBuilder(index, 'Tab ' + this.list[index])) 2236 }) 2237 } 2238 .onTabBarClick((index: number) => { 2239 this.currentIndex = index 2240 this.swiperController.changeIndex(index, true) 2241 }) 2242 .barMode(BarMode.Scrollable) 2243 .backgroundColor('#F1F3F5') 2244 .height(56) 2245 .width('100%') 2246 2247 Swiper(this.swiperController) { 2248 LazyForEach(this.swiperData, (item: string) => { 2249 Text(item.toString()) 2250 .onAppear(()=>{ 2251 console.info('onAppear ' + item.toString()) 2252 }) 2253 .onDisAppear(()=>{ 2254 console.info('onDisAppear ' + item.toString()) 2255 }) 2256 .width('100%') 2257 .height('40%') 2258 .backgroundColor(0xAFEEEE) 2259 .textAlign(TextAlign.Center) 2260 .fontSize(30) 2261 }, (item: string) => item) 2262 } 2263 .loop(false) 2264 .onSelected((index: number) => { 2265 console.info("onSelected:" + index) 2266 this.currentIndex = index; 2267 this.tabsController.changeIndex(index) 2268 }) 2269 } 2270 } 2271} 2272``` 2273 2274 2275### Example 8: Intercepting the Scrolling Behavior 2276 2277This example demonstrates how to use the **onContentWillScroll** event to allow only forward scrolling and intercept backward scrolling. 2278 2279```ts 2280// xxx.ets 2281class MyDataSource implements IDataSource { 2282 private list: number[] = [] 2283 2284 constructor(list: number[]) { 2285 this.list = list 2286 } 2287 2288 totalCount(): number { 2289 return this.list.length 2290 } 2291 2292 getData(index: number): number { 2293 return this.list[index] 2294 } 2295 2296 registerDataChangeListener(listener: DataChangeListener): void { 2297 } 2298 2299 unregisterDataChangeListener() { 2300 } 2301} 2302 2303@Entry 2304@Component 2305struct SwiperExample { 2306 private swiperController: SwiperController = new SwiperController() 2307 private data: MyDataSource = new MyDataSource([]) 2308 private currentIndex: number = 4 2309 2310 aboutToAppear(): void { 2311 let list: number[] = [] 2312 for (let i = 1; i <= 10; i++) { 2313 list.push(i); 2314 } 2315 this.data = new MyDataSource(list) 2316 } 2317 2318 build() { 2319 Column({ space: 5 }) { 2320 Swiper(this.swiperController) { 2321 LazyForEach(this.data, (item: string) => { 2322 Text(item.toString()) 2323 .width('90%') 2324 .height(160) 2325 .backgroundColor(0xAFEEEE) 2326 .textAlign(TextAlign.Center) 2327 .fontSize(30) 2328 }, (item: string) => item) 2329 } 2330 .index(this.currentIndex) 2331 .loop(false) 2332 .onChange((index: number) => { 2333 this.currentIndex = index 2334 }) 2335 .onContentWillScroll((result: SwiperContentWillScrollResult) => { 2336 if (result.comingIndex > this.currentIndex) { 2337 return false; 2338 } 2339 return true; 2340 }) 2341 2342 Row({ space: 12 }) { 2343 Button('showNext') 2344 .onClick(() => { 2345 this.swiperController.showNext() 2346 }) 2347 Button('showPrevious') 2348 .onClick(() => { 2349 this.swiperController.showPrevious() 2350 }) 2351 }.margin(5) 2352 }.width('100%') 2353 .margin({ top: 5 }) 2354 } 2355} 2356``` 2357
