1# Scroll 2 3The **Scroll** component scrolls the content when the layout size of a component exceeds the size of its parent component. 4 5> **NOTE** 6> - This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 7> - When nesting a **List** within this component, specify the width and height for the **List** under scenarios where consistently high performance is required. If the width and height are not specified, this component will load all content of the **List**. 8> - This component can scroll only when the size on the main axis is less than the content size. 9> - The default value of the universal attribute [clip](ts-universal-attributes-sharp-clipping.md) is **true** for the **Scroll** component. 10 11 12## Child Components 13 14This component supports only one child component. 15 16 17## APIs 18 19Scroll(scroller?: Scroller) 20 21Creates a **Scroll** component. 22 23**Atomic service API**: This API can be used in atomic services since API version 11. 24 25**System capability**: SystemCapability.ArkUI.ArkUI.Full 26 27**Parameters** 28 29| Name| Type| Mandatory| Description| 30| -------- | -------- | -------- | -------- | 31| scroller | [Scroller](#scroller) | No| Scroller, which can be bound to scrollable components.| 32 33## Attributes 34 35In addition to [universal attributes](ts-component-general-attributes.md) and [scrollable component common attributes](ts-container-scrollable-common.md#attributes), the following attributes are also supported. 36 37### scrollable 38 39scrollable(value: ScrollDirection) 40 41Sets the scrolling direction. 42 43**Atomic service API**: This API can be used in atomic services since API version 11. 44 45**System capability**: SystemCapability.ArkUI.ArkUI.Full 46 47**Parameters** 48 49| Name| Type | Mandatory| Description | 50| ------ | ------------------------------------------- | ---- | ----------------------------------------------- | 51| value | [ScrollDirection](#scrolldirection) | Yes | Scrolling direction.<br>Default value: **ScrollDirection.Vertical**| 52 53### scrollBar 54 55scrollBar(barState: BarState) 56 57Sets the scrollbar state. If the container component cannot be scrolled, the scrollbar is not displayed. If the size of a child component of a container component is infinite, the scrollbar cannot be dragged or scrolled with the child component. 58 59Since API version 10, when the scrollable component has rounded corners, to prevent the scrollbar from being cut off by the corners, the scrollbar will automatically calculate the clearance distance from the top and bottom. 60 61**Atomic service API**: This API can be used in atomic services since API version 11. 62 63**System capability**: SystemCapability.ArkUI.ArkUI.Full 64 65**Parameters** 66 67| Name | Type | Mandatory| Description | 68| -------- | ----------------------------------------- | ---- | -------------------------------------- | 69| barState | [BarState](ts-appendix-enums.md#barstate) | Yes | Scrollbar state.<br>Default value: **BarState.Auto**| 70 71### scrollBarColor 72 73scrollBarColor(color: Color | number | string) 74 75Sets the scrollbar color. 76 77**Atomic service API**: This API can be used in atomic services since API version 11. 78 79**System capability**: SystemCapability.ArkUI.ArkUI.Full 80 81**Parameters** 82 83| Name| Type | Mandatory| Description | 84| ------ | ------------------------------------------------------------ | ---- | -------------- | 85| color | [Color](ts-appendix-enums.md#color) \| number \| string | Yes | Scrollbar color.<br>Default value: **'\#182431'** (40% opacity) | 86 87### scrollBarWidth 88 89scrollBarWidth(value: number | string) 90 91Sets the scrollbar width. This attribute cannot be set in percentage. After the width is set, the scrollbar is displayed with the set width in normal state and pressed state. If the set width exceeds the height of the **Scroll** component on the main axis, the scrollbar reverts to the default width. 92 93**Atomic service API**: This API can be used in atomic services since API version 11. 94 95**System capability**: SystemCapability.ArkUI.ArkUI.Full 96 97**Parameters** 98 99| Name| Type | Mandatory| Description | 100| ------ | -------------------------- | ---- | ----------------------------------------- | 101| value | number \| string | Yes | Scrollbar width.<br>Default value: **4**<br>Unit: vp| 102 103### scrollSnap<sup>10+</sup> 104 105scrollSnap(value: ScrollSnapOptions) 106 107Sets the scroll snapping mode. 108 109During the snap animation, the scroll operation source type reported by the **onWillScroll** event is **ScrollSource.FLING**. 110 111**Atomic service API**: This API can be used in atomic services since API version 11. 112 113**System capability**: SystemCapability.ArkUI.ArkUI.Full 114 115**Parameters** 116 117| Name| Type | Mandatory| Description | 118| ------ | ----------------------------------------- | ---- | -------------------------- | 119| value | [ScrollSnapOptions](#scrollsnapoptions10) | Yes | Scroll snapping mode.| 120 121### edgeEffect 122 123edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions) 124 125Sets the effect used when the scroll boundary is reached. 126 127**Atomic service API**: This API can be used in atomic services since API version 11. 128 129**System capability**: SystemCapability.ArkUI.ArkUI.Full 130 131**Parameters** 132 133| Name | Type | Mandatory| Description | 134| --------------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 135| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Yes | Effect used when the scroll boundary is reached. The spring and shadow effects are supported.<br>Default value: **EdgeEffect.None**| 136| options<sup>11+</sup> | [EdgeEffectOptions](ts-container-scrollable-common.md#edgeeffectoptions11) | No | Whether to enable the scroll effect when the component content is smaller than the component itself. The value **{ alwaysEnabled: true }** means to enable the scroll effect, and **{ alwaysEnabled: false }** means the opposite.<br>Default value: **{ alwaysEnabled: true }**| 137 138### enableScrollInteraction<sup>10+</sup> 139 140enableScrollInteraction(value: boolean) 141 142Sets whether to support scroll gestures. When this attribute is set to **false**, scrolling by finger or mouse is not supported, but the scroll controller API is not affected. 143 144**Atomic service API**: This API can be used in atomic services since API version 11. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148**Parameters** 149 150| Name| Type | Mandatory| Description | 151| ------ | ------- | ---- | ----------------------------------- | 152| value | boolean | Yes | Whether to support scroll gestures.<br>Default value: **true**| 153 154### nestedScroll<sup>10+</sup> 155 156nestedScroll(value: NestedScrollOptions) 157 158Sets the nested scrolling options. You can set the nested scrolling mode in the forward and backward directions to implement scrolling linkage with the parent component. 159 160**Atomic service API**: This API can be used in atomic services since API version 11. 161 162**System capability**: SystemCapability.ArkUI.ArkUI.Full 163 164**Parameters** 165 166| Name| Type | Mandatory| Description | 167| ------ | ----------------------------------------------------- | ---- | -------------- | 168| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10) | Yes | Nested scrolling options.<br>Default value: **{ scrollForward: NestedScrollMode.SELF_ONLY, scrollBackward: NestedScrollMode.SELF_ONLY }**| 169 170### friction<sup>10+</sup> 171 172friction(value: number | Resource) 173 174Sets the friction coefficient. It applies only to gestures in the scrolling area, and it affects only indirectly the scroll chaining during the inertial scrolling process. If this attribute is set to a value less than or equal to 0, the default value is used. 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 | number \| [Resource](ts-types.md#resource) | Yes | Friction coefficient.<br>Default value: **0.9** for wearable devices and **0.6** for non-wearable devices<br>Since API version 11, the default value for non-wearable devices is **0.7**.<br>Since API version 12, the default value for non-wearable devices is **0.75**.| 185 186### enablePaging<sup>11+</sup> 187 188enablePaging(value: boolean) 189 190Sets whether to enable the swipe-to-turn-pages feature. If both **enablePaging** and **scrollSnap** are set, **scrollSnap** takes effect, but **enablePaging** does not. 191 192**Atomic service API**: This API can be used in atomic services since API version 12. 193 194**System capability**: SystemCapability.ArkUI.ArkUI.Full 195 196**Parameters** 197 198| Name| Type | Mandatory| Description | 199| ------ | ------- | ---- | ------------------------------------- | 200| value | boolean | Yes | Whether to enable the swipe-to-turn-pages feature. The value **true** means to enable the swipe-to-turn-pages feature, and **false** means the opposite.<br>Default value: **false**| 201 202### initialOffset<sup>12+</sup> 203 204initialOffset(value: OffsetOptions) 205 206Sets the initial scrolling offset. This attribute takes effect only during the initial layout of the component. After the initial layout, dynamically changing the value of this attribute does not have any effect. 207 208**Atomic service API**: This API can be used in atomic services since API version 12. 209 210**System capability**: SystemCapability.ArkUI.ArkUI.Full 211 212**Parameters** 213 214| Name| Type | Mandatory| Description | 215| ------ | ------- | ---- | ------------------------------------- | 216| value | [OffsetOptions](#offsetoptions12) | Yes |Initial scrolling offset. When the value specified is a percentage, the initial scrolling offset is calculated as the product of the **Scroll** component's size in the main axis direction and the percentage value.| 217 218## ScrollDirection 219 220Enumerates the scrolling directions. 221 222**System capability**: SystemCapability.ArkUI.ArkUI.Full 223 224| Name | Description | 225| ---------- | ------------------------ | 226| Horizontal | Only horizontal scrolling is supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 227| Vertical | Only vertical scrolling is supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 228| None | Scrolling is disabled.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 229| Free<sup>(deprecated) </sup> | Vertical or horizontal scrolling is supported.<br> This API is deprecated since API version 9.| 230 231## ScrollSnapOptions<sup>10+</sup> 232 233Defines a scroll snapping mode object. 234 235**Atomic service API**: This API can be used in atomic services since API version 11. 236 237**System capability**: SystemCapability.ArkUI.ArkUI.Full 238 239| Name | Type | Mandatory | Description | 240| ---------- | --------------------|-------------------- | -------- | 241| snapAlign | [ScrollSnapAlign](ts-container-list.md#scrollsnapalign10) | Yes| Alignment mode for the scroll snap position.<br>**NOTE**<br>1. Default value: **ScrollSnapAlign.NONE**| 242| snapPagination | [Dimension](ts-types.md#dimension10) \| Array\<Dimension\> | No| Pagination points for scroll snapping.<br>**NOTE**<br>1. If the value is of the Dimension type, it indicates the size of each page, and the system will paginate based on this size.<br>2. If the value is of the Array\<Dimension\> type, each **Dimension** represents a pagination point, and the system will paginate accordingly. Each **Dimension** value must be within the [0, scrollable distance] range.<br>3. If this parameter is not set or **Dimension** is set to a value less than or equal to 0, the value is regarded as an invalid value. In this case, there is no scroll snapping. When the value is of the Array\<Dimension\> type, the items in the array must be monotonically increasing.<br>4. When the value is a percentage, the actual size is the product of the viewport of the **Scroll** component and the percentage value.| 243| enableSnapToStart | boolean | No| Whether to enable the snap to start feature. When scroll snapping is defined for the **Scroll** component, setting this parameter to **false** enables the component to scroll between the start and the first page.<br>**NOTE**<br>1. Default value: **true**<br>2. This attribute takes effect only when **snapPagination** is set to a value of the **Array\<Dimension\>** type; it does not work with values of the **Dimension** type.| 244| enableSnapToEnd | boolean | No| Whether to enable the snap to end feature. When scroll snapping is defined for the **Scroll** component, setting this parameter to **false** enables the component to scroll between the end and the last page.<br>**NOTE**<br>1. Default value: **true**<br>2. This attribute takes effect only when **snapPagination** is set to a value of the **Array\<Dimension\>** type; it does not work with values of the **Dimension** type.| 245 246## Events 247 248In addition to [universal events](ts-component-general-events.md) and [scrollable component common events](ts-container-scrollable-common.md#events), the following events are also supported. 249> **NOTE** 250> 251> The [onWillScroll](ts-container-scrollable-common.md#onwillscroll12) and [onDidScroll](ts-container-scrollable-common.md#ondidscroll12) events are not supported. 252 253### onScrollFrameBegin<sup>9+</sup> 254 255onScrollFrameBegin(event: OnScrollFrameBeginCallback) 256 257Triggered when each frame scrolling starts. The input parameters indicate the amount by which the **Scroll** component will scroll. The event handler then works out the amount by which the component needs to scroll based on the real-world situation and returns the result. 258 259The value of **offsetRemain** can be a negative value. 260 261If the **onScrollFrameBegin** event and **scrollBy** method are used to implement nested scrolling, set the **edgeEffect** attribute of the scrollable child component to **None**. For example, if a **List** is nested in the **Scroll** component, **edgeEffect** of the **List** must be set to **EdgeEffect.None**. 262 263Notes: 264 2651. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations.<br>2. This event is not triggered when the controller API is called.<br>3. This event does not support the out-of-bounds bounce effect.<br>4. This event is not triggered when the scroll bar is dragged. 266 267**Atomic service API**: This API can be used in atomic services since API version 11. 268 269**System capability**: SystemCapability.ArkUI.ArkUI.Full 270 271**Parameters** 272 273| Name| Type | Mandatory| Description | 274| ------ | --------------------------------- | ---- | ------------------ | 275| event | [OnScrollFrameBeginCallback](#onscrollframebegincallback16) | Yes | Callback triggered when each frame scrolling starts.| 276 277### onScroll<sup>(deprecated)</sup> 278 279onScroll(event: (xOffset: number, yOffset: number) => void) 280 281Triggered to return the horizontal and vertical offsets, in vp, during scrolling when the specified scroll event occurs. 282 283**NOTE** 284 2851. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations. 286 2872. This event is triggered when the controller API is called. 288 2893. This event supports the out-of-bounds bounce effect. 290 291This API is deprecated since API version 12. You are advised to use [onWillScroll](#onwillscroll12) instead. 292 293**Atomic service API**: This API can be used in atomic services since API version 11. 294 295**System capability**: SystemCapability.ArkUI.ArkUI.Full 296 297**Parameters** 298 299| Name | Type | Mandatory| Description | 300| ------- | --------------------------------------------------------- | ---- | ---------------------- | 301| xOffset | number | Yes | Horizontal offset per frame during scrolling. A positive offset indicates scrolling to the left, and a negative offset indicates scrolling to the right.<br>Unit: vp| 302| yOffset | number | Yes | Vertical offset per frame during scrolling. A positive offset indicates scrolling upward, and a negative offset indicates scrolling downward.<br>Unit: vp| 303 304### onWillScroll<sup>12+</sup> 305 306onWillScroll(handler: ScrollOnWillScrollCallback) 307 308Triggered before scrolling. 309 310The callback provides the amount of offset that is about to be scrolled in the current frame, along with the current scroll status and the source of the scrolling operation. The offset provided in the callback is the calculated intended scrolling offset, not the final actual scrolling offset. You can specify the intended scrolling offset for the **Scroll** through the return value of this callback. 311 312**NOTE** 313 3141. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations. 315 3162. This event is triggered when the controller API is called. 317 3183. This event supports the out-of-bounds bounce effect. 319 320**Atomic service API**: This API can be used in atomic services since API version 12. 321 322**System capability**: SystemCapability.ArkUI.ArkUI.Full 323 324**Parameters** 325 326| Name | Type | Mandatory| Description | 327| ------- | --------------------------------------------------------- | ---- | ---------------------- | 328| handler | [ScrollOnWillScrollCallback](#scrollonwillscrollcallback12) | Yes | Callback triggered before scrolling.| 329 330### onDidScroll<sup>12+</sup> 331 332onDidScroll(handler: ScrollOnScrollCallback) 333 334Triggered when the **Scroll** component scrolls. 335 336The return value is the scrolling offset amount in the current frame, along with the current scroll state. 337 338**NOTE** 339 3401. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations. 341 3422. This event is triggered when the controller API is called. 343 3443. This event supports the out-of-bounds bounce effect. 345 346**Atomic service API**: This API can be used in atomic services since API version 12. 347 348**System capability**: SystemCapability.ArkUI.ArkUI.Full 349 350**Parameters** 351 352| Name | Type | Mandatory| Description | 353| ------- | --------------------------------------------------------- | ---- | ---------------------- | 354| handler | [ScrollOnScrollCallback](#scrollonscrollcallback12) | Yes | Callback triggered when the **Scroll** component scrolls.| 355 356### onScrollEdge 357 358onScrollEdge(event: OnScrollEdgeCallback) 359 360Triggered when scrolling reaches the edge. 361 362**NOTE** 363 3641. This event is triggered when scrolling reaches the edge after being started by the **Scroll** component or other input settings, such as keyboard and mouse operations.<br>2. This event is triggered when the controller API is called.<br>3. This event supports the out-of-bounds bounce effect. 365 366**Atomic service API**: This API can be used in atomic services since API version 11. 367 368**System capability**: SystemCapability.ArkUI.ArkUI.Full 369 370**Parameters** 371 372| Name| Type | Mandatory| Description | 373| ------ | --------------------------------- | ---- | ------------------ | 374| event | [OnScrollEdgeCallback](#onscrolledgecallback16) | Yes | Edge position to scroll to.| 375 376### onScrollEnd<sup>(deprecated) </sup> 377 378onScrollEnd(event: () => void) 379 380Triggered when scrolling stops. 381 382**NOTE** 383 3841. This event is triggered when scrolling is stopped by the **Scroll** component or other input settings, such as keyboard and mouse operations.<br>2. This event is triggered when the controller API is called, accompanied by a transition animation. 385 386This event is deprecated since API version 9. Use the **onScrollStop** event instead. 387 388**System capability**: SystemCapability.ArkUI.ArkUI.Full 389 390### onScrollStart<sup>9+</sup> 391 392onScrollStart(event: VoidCallback) 393 394Triggered when scrolling starts and is initiated by the user's finger dragging the **Scroll** component or its scrollbar. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](#scroller) starts. 395 396**NOTE** 397 3981. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations.<br>2. This event is triggered when the controller API is called, accompanied by a transition animation. 399 400**Atomic service API**: This API can be used in atomic services since API version 11. 401 402**System capability**: SystemCapability.ArkUI.ArkUI.Full 403 404**Parameters** 405 406| Name| Type | Mandatory| Description | 407| ------ | --------------------------------- | ---- | ------------------ | 408| event | [VoidCallback](ts-types.md#voidcallback12) | Yes | Callback triggered when scrolling starts.| 409 410### onScrollStop<sup>9+</sup> 411 412onScrollStop(event: VoidCallback) 413 414Triggered when scrolling stops after the user's finger leaves the screen. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](#scroller) stops. 415 416**NOTE** 417 4181. This event is triggered when scrolling is stopped by the **Scroll** component or other input settings, such as keyboard and mouse operations.<br>2. This event is triggered when the controller API is called, accompanied by a transition animation. 419 420**Atomic service API**: This API can be used in atomic services since API version 11. 421 422**System capability**: SystemCapability.ArkUI.ArkUI.Full 423 424**Parameters** 425 426| Name| Type | Mandatory| Description | 427| ------ | --------------------------------- | ---- | ------------------ | 428| event | [VoidCallback](ts-types.md#voidcallback12) | Yes | Callback triggered when scrolling stops.| 429 430## ScrollOnScrollCallback<sup>12+</sup> 431 432type ScrollOnScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState) => void 433 434Represents the callback triggered when the **Scroll** component scrolls. 435 436**Atomic service API**: This API can be used in atomic services since API version 12. 437 438**System capability**: SystemCapability.ArkUI.ArkUI.Full 439 440| Name | Type | Mandatory| Description | 441| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 442| xOffset | number | Yes | Horizontal offset per frame during scrolling. A positive offset indicates scrolling to the left, and a negative offset indicates scrolling to the right.<br>Unit: vp| 443| yOffset | number | Yes | Vertical offset per frame during scrolling. A positive offset indicates scrolling upward, and a negative offset indicates scrolling downward.<br>Unit: vp| 444| scrollState | [ScrollState](ts-container-list.md#scrollstate)| Yes | Current scrolling state. | 445 446> **NOTE** 447> 448> If the **onScrollFrameBegin** event and **scrollBy** method are used to implement nested scrolling, set the **edgeEffect** attribute of the scrollable child component to **None**. For example, if a **List** is nested in the **Scroll** component, **edgeEffect** of the **List** must be set to **EdgeEffect.None**. 449 450## ScrollOnWillScrollCallback<sup>12+</sup> 451 452type ScrollOnWillScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | OffsetResult 453 454Callback triggered before scrolling. 455 456**Atomic service API**: This API can be used in atomic services since API version 12. 457 458**System capability**: SystemCapability.ArkUI.ArkUI.Full 459 460| Name | Type | Mandatory| Description | 461| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 462| xOffset | number | Yes | Horizontal offset per frame during scrolling. A positive offset indicates scrolling to the left, and a negative offset indicates scrolling to the right.<br>Unit: vp| 463| yOffset | number | Yes | Vertical offset per frame during scrolling. A positive offset indicates scrolling upward, and a negative offset indicates scrolling downward.<br>Unit: vp| 464| scrollState | [ScrollState](ts-container-list.md#scrollstate)| Yes | Current scrolling state. | 465| scrollSource | [ScrollSource](ts-appendix-enums.md#scrollsource12) | Yes| Source of the current scrolling operation.| 466 467**Return value** 468 469| Type | Description | 470| ------------------------------------------------------------ | ------------------------------------------------------------ | 471| void \| [OffsetResult](#offsetresult11) | If **OffsetResult** is returned, the scrolling will be performed with the offsets specified. Otherwise, the scrolling will be performed with the offsets determined by **(xOffset, yOffset)**.| 472 473## OnScrollEdgeCallback<sup>16+</sup> 474 475type OnScrollEdgeCallback = (side: Edge) => void 476 477Represents the callback triggered when scrolling reaches an edge. 478 479**Atomic service API**: This API can be used in atomic services since API version 16. 480 481**System capability**: SystemCapability.ArkUI.ArkUI.Full 482 483| Name | Type | Mandatory| Description | 484| ------- | ----- | ---- | ------ | 485| side | [Edge](ts-appendix-enums.md#edge) | Yes | Edge position to scroll to.| 486 487## OnScrollFrameBeginCallback<sup>16+</sup> 488 489type OnScrollFrameBeginCallback = (offset: number, scrollState: ScrollState) => OnScrollFrameBeginHandlerResult; 490 491Represents the callback triggered before each frame scrolling starts. 492 493**Atomic service API**: This API can be used in atomic services since API version 16. 494 495**System capability**: SystemCapability.ArkUI.ArkUI.Full 496 497**Parameters** 498 499| Name| Type | Mandatory| Description | 500| ------ | ------------------------------------------------------- | ---- | -------------------------- | 501| offset | number | Yes | Amount to scroll by, in vp.| 502| state | [ScrollState](ts-container-list.md#scrollstate)| Yes | Current scroll state. | 503 504**Return value** 505 506| Type | Description | 507| ------------------------ | -------------------- | 508| [OnScrollFrameBeginHandlerResult](#onscrollframebeginhandlerresult16) | Actual scroll offset.| 509 510## OnScrollFrameBeginHandlerResult<sup>16+</sup> 511 512**Atomic service API**: This API can be used in atomic services since API version 16. 513 514**System capability**: SystemCapability.ArkUI.ArkUI.Full 515 516| Name | Type | Mandatory| Description | 517| ----- | ------ | ---- | ----- | 518| offsetRemain | number | Yes | Actual scroll offset.<br>Unit: vp| 519 520## Scroller 521 522Defines a controller for scrollable container components. It can be bound to a container component to control its scrolling behavior. A single **Scroller** instance cannot control multiple container components simultaneously. Currently, it can be bound to the following components: **ArcList**, **ArcScrollBar**, **List**, **Scroll**, **ScrollBar**, **Grid**, and **WaterFlow**. 523 524>**NOTE** 525> 526>1. The binding of a **Scroller** instance to a scrollable container component occurs during the component creation phase.<br> 527>2. **Scroller** APIs can only be effectively called after the **Scroller** instance is bound to a scrollable container component. Otherwise, depending on the API called, it may have no effect or throw an exception.<br> 528>3. For example, with [aboutToAppear](ts-custom-component-lifecycle.md#abouttoappear), this callback is executed after a new instance of a custom component is created and before its **build()** method is called. Therefore, if a scrollable component is defined within the **build** method of a custom component, the internal scrollable component has not yet been created during the **aboutToAppear** callback of that custom component, and therefore the **Scroller** APIs cannot be called effectively.<br> 529>4. For example, with [onAppear](ts-universal-events-show-hide.md#onappear), this callback is triggered after the component is mounted and displayed. Therefore, when the **onAppear** callback of a scrollable component is executed, the scrollable component has already been created and successfully bound to the **Scroller** instance, allowing the **Scroller** APIs to be called effectively. 530 531### Objects to Import 532 533``` 534scroller: Scroller = new Scroller() 535``` 536 537### constructor 538 539constructor() 540 541A constructor used to create a **Scroller** object. 542 543**Atomic service API**: This API can be used in atomic services since API version 11. 544 545**System capability**: SystemCapability.ArkUI.ArkUI.Full 546 547### scrollTo 548 549scrollTo(options: [ScrollOptions](#scrolloptions16)) 550 551 552Scrolls to the specified position. 553 554**Atomic service API**: This API can be used in atomic services since API version 11. 555 556**System capability**: SystemCapability.ArkUI.ArkUI.Full 557 558**Parameters** 559 560| Name | Type| Mandatory | Description | 561| ----- | ---- | ---- | --------- | 562| options | [ScrollOptions](#scrolloptions16) | Yes | Parameters for scrolling to the specified position. 563 564### scrollEdge 565 566scrollEdge(value: Edge, options?: ScrollEdgeOptions) 567 568Scrolls to the edge of the container, regardless of the scroll axis direction. **Edge.Top** and **Edge.Start** produce the same effect, and **Edge.Bottom** and **Edge.End** produce the same effect. 569By default, the **Scroll** component comes with an animation, while the **Grid**, **List**, and **WaterFlow** components do not. 570 571**System capability**: SystemCapability.ArkUI.ArkUI.Full 572 573**Parameters** 574 575| Name | Type| Mandatory | Description | 576| ----- | ---- | ---- | --------- | 577| value | [Edge](ts-appendix-enums.md#edge) | Yes | Edge position to scroll to.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 578| options<sup>12+</sup> | [ScrollEdgeOptions](#scrolledgeoptions12)| No | Mode of scrolling to the edge position.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 579 580### fling<sup>12+</sup> 581 582fling(velocity: number): void 583 584 585Performs inertial scrolling based on the initial velocity passed in. 586 587**Atomic service API**: This API can be used in atomic services since API version 12. 588 589**System capability**: SystemCapability.ArkUI.ArkUI.Full 590 591**Parameters** 592 593| Name | Type| Mandatory| Description | 594| -------- | -------- | ---- | ------------------------------------------------------------ | 595| velocity | number | Yes | Initial velocity of inertial scrolling. Unit: vp/s<br>**NOTE**<br>If the value specified is 0, it is considered as invalid, and the scrolling for this instance will not take effect. A positive value indicates scrolling towards the top, while a negative value indicates scrolling towards the bottom.| 596 597**Error codes** 598 599For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Scrollable Component Error Codes](../errorcode-scroll.md). 600 601| ID| Error Message| 602| ------- | -------- | 603| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 604| 100004 | Controller not bound to component. | 605 606### scrollPage<sup>9+</sup> 607 608scrollPage(value: ScrollPageOptions) 609 610Scrolls to the next or previous page. 611 612**Atomic service API**: This API can be used in atomic services since API version 11. 613 614**System capability**: SystemCapability.ArkUI.ArkUI.Full 615 616**Parameters** 617 618| Name| Type | Mandatory| Description | 619| ------ | -------------------------------------------------- | ---- | -------------- | 620| value | [ScrollPageOptions](#scrollpageoptions14) | Yes | Page turning mode.| 621 622### scrollPage<sup>(deprecated)</sup> 623 624scrollPage(value: { next: boolean, direction?: Axis }) 625 626Scrolls to the next or previous page. This API is deprecated since API version 9. You are advised to use [scrollPage<sup>9+</sup>](#scrollpage9) instead. 627 628**System capability**: SystemCapability.ArkUI.ArkUI.Full 629 630**Parameters** 631 632| Name | Type | Mandatory | Description | 633| --------- | ------- | ---- | ------------------------------ | 634| next | boolean | Yes | Whether to turn to the next page. The value **true** means to scroll to the next page, and **false** means to scroll to the previous page.| 635| direction | [Axis](ts-appendix-enums.md#axis) | No | Scrolling direction: horizontal or vertical. | 636 637### currentOffset 638 639currentOffset(): OffsetResult 640 641Obtains the current scrolling offset. 642 643**Atomic service API**: This API can be used in atomic services since API version 11. 644 645**System capability**: SystemCapability.ArkUI.ArkUI.Full 646 647| Type | Description| 648| -------- | -------- | 649| [OffsetResult<sup>11+</sup>](#offsetresult11) | Obtains the scrolling offset.<br>**NOTE**<br>If **Scroller** is not bound to a container component or the container component is released abnormally, the return value for **currentOffset** is null.| 650 651### scrollToIndex 652 653scrollToIndex(value: number, smooth?: boolean, align?: ScrollAlign, options?: ScrollToIndexOptions) 654 655Scrolls to a specified index, with support for setting an extra offset for the scroll. 656 657When **smooth** is set to **true**, all passed items are loaded and counted in layout calculation. This may result in performance issues if a large number of items are involved. 658 659 660> **NOTE** 661> 662> This API only works for the **ArcList**, **Grid**, **List**, and **WaterFlow** components. 663 664**Atomic service API**: This API can be used in atomic services since API version 11. 665 666**System capability**: SystemCapability.ArkUI.ArkUI.Full 667 668**Parameters** 669 670| Name | Type| Mandatory| Description | 671| --------------------- | -------- | ---- | ------------------------------------------------------------ | 672| value | number | Yes | Index of the item to be scrolled to in the container.<br>**NOTE**<br>If the value set is a negative value or greater than the maximum index of the items in the container, the value is deemed abnormal, and no scrolling will be performed. | 673| smooth | boolean | No | Whether to enable the smooth animation for scrolling to the item with the specified index. The value **true** means to enable that the smooth animation, and **false** means the opposite.<br>Default value: **false**| 674| align | [ScrollAlign](#scrollalign10) | No | How the list item to scroll to is aligned with the container.<br>Default value when the container is **List**: **ScrollAlign.START**<br> Default value when the container is **Grid**: **ScrollAlign.AUTO**<br> Default value when the container is **WaterFlow**: **ScrollAlign.START**<br>**NOTE**<br>This parameter is only available for the **List**, **Grid**, and **WaterFlow** components.| 675| options<sup>12+</sup> | [ScrollToIndexOptions](#scrolltoindexoptions12) | No | Options for scrolling to a specified index, for example, an extra offset for the scroll.<br>Default value: **0**, in vp| 676 677### scrollBy<sup>9+</sup> 678 679scrollBy(dx: Length, dy: Length) 680 681 682Scrolls by the specified amount. 683 684 685> **NOTE** 686> 687> This API is available for the **ArcList**, **Scroll**, **List**, **Grid**, and **WaterFlow** components. 688 689**Atomic service API**: This API can be used in atomic services since API version 11. 690 691**System capability**: SystemCapability.ArkUI.ArkUI.Full 692 693**Parameters** 694 695| Name | Type | Mandatory | Description | 696| ----- | ------ | ---- | ----------------- | 697| dx | [Length](ts-types.md#length) | Yes | Amount to scroll by in the horizontal direction. The percentage format is not supported.| 698| dy | [Length](ts-types.md#length) | Yes | Amount to scroll by in the vertical direction. The percentage format is not supported.| 699 700### isAtEnd<sup>10+</sup> 701 702isAtEnd(): boolean 703 704Checks whether the component has scrolled to the bottom. 705 706> **NOTE** 707> 708> This API is available for the **ArcList**, **Scroll**, **List**, **Grid**, and **WaterFlow** components. 709 710**Atomic service API**: This API can be used in atomic services since API version 11. 711 712**System capability**: SystemCapability.ArkUI.ArkUI.Full 713 714**Return value** 715 716| Type | Description | 717| ------- | -------- | 718| boolean | The value **true** means that the component has scrolled to the bottom, and **false** means the opposite.| 719 720### getItemRect<sup>11+</sup> 721 722getItemRect(index: number): RectResult 723 724Obtains the size and position of a child component relative to its container. 725 726> **NOTE** 727> 728> This API is available for the **ArcList**, **Scroll**, **List**, **Grid**, and **WaterFlow** components. 729 730**Atomic service API**: This API can be used in atomic services since API version 12. 731 732**System capability**: SystemCapability.ArkUI.ArkUI.Full 733 734**Parameters** 735 736| Name | Type | Mandatory | Description | 737| ----- | ------ | ---- | ----------------- | 738| index | number | Yes | Index of the target child component.| 739 740> **NOTE** 741> 742> - The value of **index** must be the index of a child component visible in the display area. Otherwise, the value is considered invalid. 743> - The size and position returned for an invalid value are both **0**. 744 745**Return value** 746 747| Type | Description | 748| ------------------- | -------- | 749| [RectResult](ts-types.md#rectresult10) | Size and position of the child component relative to the component.<br>Unit: vp| 750 751**Error codes** 752 753For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Scrollable Component Error Codes](../errorcode-scroll.md). 754 755| ID| Error Message| 756| ------- | -------- | 757| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 758| 100004 | Controller not bound to component. | 759### getItemIndex<sup>14+</sup> 760 761getItemIndex(x: number, y: number): number 762 763Obtains the index of a child component based on coordinates. 764 765> **NOTE** 766> 767> This API is available for the **List**, **Grid**, and **WaterFlow** components. 768 769**Atomic service API**: This API can be used in atomic services since API version 14. 770 771**System capability**: SystemCapability.ArkUI.ArkUI.Full 772 773**Parameters** 774 775| Name | Type | Mandatory | Description | 776| ----- | ------ | ---- | ----------------- | 777| x | number | Yes | X-coordinate, in vp.| 778| y | number | Yes| Y-coordinate, in vp.| 779 780> **NOTE** 781> 782> The returned index is **-1** for invalid coordinates. 783 784**Return value** 785 786| Type | Description | 787| ------------------- | -------- | 788| number | Index of the child component, in vp.| 789 790**Error codes** 791 792For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Scrollable Component Error Codes](../errorcode-scroll.md). 793 794| ID| Error Message| 795| ------- | -------- | 796| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 797| 100004 |The controller not bound to component. | 798 799## OffsetResult<sup>11+</sup> 800 801Represents the offset values resulting from a scroll operation. 802 803**Atomic service API**: This API can be used in atomic services since API version 11. 804 805**System capability**: SystemCapability.ArkUI.ArkUI.Full 806 807| Name | Type | Read Only| Optional| Description | 808| ------- |------- | ---- | ---- | -------------------------------- | 809| xOffset | number | No | No | Horizontal scrolling offset.<br>The unit of the return value is vp.| 810| yOffset | number | No | No | Vertical scrolling offset.<br>The unit of the return value is vp.| 811 812## ScrollAnimationOptions<sup>12+</sup> 813 814Provides parameters for customizing scroll animations. 815 816**Atomic service API**: This API can be used in atomic services since API version 12. 817 818**System capability**: SystemCapability.ArkUI.ArkUI.Full 819 820| Name | Type | Mandatory | Description | 821| ----- | ------ | ------ | ----------------- | 822| duration | number | No| Scrolling duration.<br>Default value: **1000**<br>**NOTE**<br>A value less than 0 evaluates to the default value.| 823| curve | [Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve9) | No| Scrolling curve.<br>Default value: **Curve.Ease**| 824| canOverScroll | boolean | No| Whether to enable overscroll.<br>Default value: **false**<br>**NOTE**<br> Scrolling can exceed the boundary and initiate a bounce animation when this parameter is set to **true**, and the component's **edgeEffect** attribute is set to [EdgeEffect.Spring](ts-appendix-enums.md#edgeeffect).| 825 826## ScrollAlign<sup>10+</sup> 827 828Enumerates alignment modes. 829 830**Atomic service API**: This API can be used in atomic services since API version 11. 831 832**System capability**: SystemCapability.ArkUI.ArkUI.Full 833 834| Name | Description | 835| ------ | ------------------------------ | 836| START | The start edge of the list item is flush with the start edge of the list. | 837| CENTER | The list item is centered along the main axis of the list. | 838| END | The end edge of the list item is flush with the end edge of the list.| 839| AUTO | The list item is automatically aligned.<br>If the list item is fully contained within the display area, no adjustment is performed. Otherwise, the list item is aligned so that its start or end edge is flush with the start or end edge of the list, whichever requires a shorter scrolling distance.| 840 841## ScrollToIndexOptions<sup>12+</sup> 842 843Provides parameters for scrolling to a specific index. 844 845**Atomic service API**: This API can be used in atomic services since API version 12. 846 847**System capability**: SystemCapability.ArkUI.ArkUI.Full 848 849| Name | Type | Mandatory| Description | 850| ----- | ------ | ------ | ----------------- | 851| extraOffset | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Extra offset for scrolling to a specified index.| 852 853## ScrollPageOptions<sup>14+</sup> 854 855Provides parameters for page scrolling behavior. 856 857**Atomic service API**: This API can be used in atomic services since API version 14. 858 859**System capability**: SystemCapability.ArkUI.ArkUI.Full 860 861| Name | Type| Mandatory| Description | 862| --------- | -------- | ---- | ------------------------------------------------------------ | 863| next | boolean | Yes | Whether to turn to the next page. The value **true** means to scroll to the next page, and **false** means to scroll to the previous page. | 864| animation | boolean | No | Whether to enable the page-turning animation. The value **true** means to enable the page-turning animation, and **false** means the opposite.<br>Default value: **false**| 865 866## OffsetOptions<sup>12+</sup> 867 868Provides parameters for setting the initial scrolling offset. 869 870**Atomic service API**: This API can be used in atomic services since API version 12. 871 872**System capability**: SystemCapability.ArkUI.ArkUI.Full 873 874| Name | Type | Mandatory| Description | 875| ----- | ------| ------- | ----------------- | 876| xOffset | [Dimension](ts-types.md#dimension10) | No|Horizontal scrolling offset.<br>Default value: **0**| 877| yOffset | [Dimension](ts-types.md#dimension10) | No|Vertical scrolling offset.<br>Default value: **0**| 878 879## ScrollEdgeOptions<sup>12+</sup> 880 881Provides parameters for scrolling to the edge of a scrollable container. 882 883**Atomic service API**: This API can be used in atomic services since API version 12. 884 885**System capability**: SystemCapability.ArkUI.ArkUI.Full 886 887| Name | Type| Mandatory| Description | 888| --------- | -------- | ---- | ------------------------------------------------------------ | 889| velocity | number | No | Fixed velocity for scrolling to the edge of the container. If the value specified is less than or equal to 0, the parameter will not take effect.<br>Default value: **0**<br> Unit: vp/s | 890 891## ScrollOptions<sup>16+</sup> 892 893Provides parameters for scrolling to a specific position in a scrollable container. 894 895**Atomic service API**: This API can be used in atomic services since API version 16. 896 897**System capability**: SystemCapability.ArkUI.ArkUI.Full 898 899| Name | Type | Mandatory| Description | 900| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 901| xOffset | number \| string | Yes | Horizontal scrolling offset.<br>**NOTE**<br>This parameter cannot be set in percentage.<br>If the value is less than 0, the offset will be 0 for non-animated scrolling. Animated scrolling stops at the starting position by default. By setting the **animation** parameter, you can enable a bounce effect when the scrolling goes beyond the boundary.<br>This parameter takes effect only when the scroll axis is the x-axis.| 902| yOffset | number \| string | Yes | Vertical scrolling offset.<br>**NOTE**<br>This parameter cannot be set in percentage.<br>If the value is less than 0, the offset will be 0 for non-animated scrolling. Animated scrolling stops at the starting position by default. By setting the **animation** parameter, you can enable a bounce effect when the scrolling goes beyond the boundary.<br>This parameter takes effect only when the scroll axis is the y-axis.| 903| animation | [ScrollAnimationOptions](#scrollanimationoptions12) \| boolean | No | Animation configuration, which includes the following:<br>- **ScrollAnimationOptions**: custom animation settings.<br>- **boolean**: whether to enable the default spring animation.<br>Default value:<br>ScrollAnimationOptions: { duration: 1000, curve: Curve.Ease, canOverScroll: false } <br>boolean: false<br>**NOTE**<br>Currently, the **List**, **Scroll**, **Grid**, and **WaterFlow** support the **Boolean** type and **ICurve**.| 904 905## Example 906### Example 1: Setting the Scroller 907This example demonstrates the use of some attributes of the **Scroll** component and the **Scroller**. 908 909```ts 910// xxx.ets 911import { curves } from '@kit.ArkUI' 912 913@Entry 914@Component 915struct ScrollExample { 916 scroller: Scroller = new Scroller() 917 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 918 919 build() { 920 Stack({ alignContent: Alignment.TopStart }) { 921 Scroll(this.scroller) { 922 Column() { 923 ForEach(this.arr, (item: number) => { 924 Text(item.toString()) 925 .width('90%') 926 .height(150) 927 .backgroundColor(0xFFFFFF) 928 .borderRadius(15) 929 .fontSize(16) 930 .textAlign(TextAlign.Center) 931 .margin({ top: 10 }) 932 }, (item: string) => item) 933 }.width('100%') 934 } 935 .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction. 936 .scrollBar(BarState.On) // The scrollbar is always displayed. 937 .scrollBarColor(Color.Gray) // The scrollbar color is gray. 938 .scrollBarWidth(10) // The scrollbar width is 10. 939 .friction(0.6) 940 .edgeEffect(EdgeEffect.None) 941 .onWillScroll((xOffset: number, yOffset: number, scrollState: ScrollState) => { 942 console.info(xOffset + ' ' + yOffset) 943 }) 944 .onScrollEdge((side: Edge) => { 945 console.info('To the edge') 946 }) 947 .onScrollStop(() => { 948 console.info('Scroll Stop') 949 }) 950 951 Button('scroll 150') 952 .height('5%') 953 .onClick(() => { // Click to scroll down by 150.0 vp. 954 this.scroller.scrollBy(0, 150) 955 }) 956 .margin({ top: 10, left: 20 }) 957 Button('scroll 100') 958 .height('5%') 959 .onClick(() => { // Click to scroll down by 100.0 vp. 960 const yOffset: number = this.scroller.currentOffset().yOffset; 961 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100 }) 962 }) 963 .margin({ top: 60, left: 20 }) 964 Button('scroll 100') 965 .height('5%') 966 .onClick(() => {// Click to scroll down by 100.0 vp. An animation is applied to the scrolling. 967 let curve = curves.interpolatingSpring(10, 1, 228, 30) // Create a step curve. 968 const yOffset: number = this.scroller.currentOffset().yOffset; 969 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100, animation: { duration: 1000, curve: curve } }) 970 }) 971 .margin({ top: 110, left: 20 }) 972 Button('back top') 973 .height('5%') 974 .onClick(() => { // Click to go back to the top. 975 this.scroller.scrollEdge(Edge.Top) 976 }) 977 .margin({ top: 160, left: 20 }) 978 Button('next page') 979 .height('5%') 980 .onClick(() => { // Click to go to the next page. 981 this.scroller.scrollPage({ next: true ,animation: true }) 982 }) 983 .margin({ top: 210, left: 20 }) 984 Button('fling -3000') 985 .height('5%') 986 .onClick(() => { // Trigger a fling with an initial velocity of -3000 vp/s. 987 this.scroller.fling(-3000) 988 }) 989 .margin({ top: 260, left: 20 }) 990 Button('scroll to bottom 700') 991 .height('5%') 992 .onClick(() => {// After the button is clicked, the component scrolls to the bottom edge at a velocity of 700 vp/s. 993 this.scroller.scrollEdge(Edge.Bottom, { velocity: 700 }) 994 }) 995 .margin({ top: 310, left: 20 }) 996 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 997 } 998} 999``` 1000 1001 1002 1003### Example 2: Implementing Nested Scrolling (Method 1) 1004This example uses the **onScrollFrameBegin** event to achieve nested scrolling between an inner **List** component and an outer **Scroll** component. 1005```ts 1006import { LengthMetrics } from '@kit.ArkUI' 1007 1008@Entry 1009@Component 1010struct NestedScroll { 1011 @State listPosition: number = 0; // 0 indicates scrolling to the top of the list, 1 indicates scrolling to the middle of the list, and 2 indicates scrolling to the bottom of the list. 1012 private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] 1013 private scrollerForScroll: Scroller = new Scroller() 1014 private scrollerForList: Scroller = new Scroller() 1015 1016 build() { 1017 Flex() { 1018 Scroll(this.scrollerForScroll) { 1019 Column() { 1020 Text("Scroll Area") 1021 .width("100%") 1022 .height("40%") 1023 .backgroundColor(0X330000FF) 1024 .fontSize(16) 1025 .textAlign(TextAlign.Center) 1026 .onClick(() => { 1027 this.scrollerForList.scrollToIndex(5, false, ScrollAlign.START, { extraOffset: LengthMetrics.vp(5) }) 1028 }) 1029 1030 List({ space: 20, scroller: this.scrollerForList }) { 1031 ForEach(this.arr, (item: number) => { 1032 ListItem() { 1033 Text("ListItem" + item) 1034 .width("100%") 1035 .height("100%") 1036 .borderRadius(15) 1037 .fontSize(16) 1038 .textAlign(TextAlign.Center) 1039 .backgroundColor(Color.White) 1040 }.width("100%").height(100) 1041 }, (item: string) => item) 1042 } 1043 .width("100%") 1044 .height("50%") 1045 .edgeEffect(EdgeEffect.None) 1046 .friction(0.6) 1047 .onReachStart(() => { 1048 this.listPosition = 0 1049 }) 1050 .onReachEnd(() => { 1051 this.listPosition = 2 1052 }) 1053 .onScrollFrameBegin((offset: number) => { 1054 if ((this.listPosition == 0 && offset <= 0) || (this.listPosition == 2 && offset >= 0)) { 1055 this.scrollerForScroll.scrollBy(0, offset) 1056 return { offsetRemain: 0 } 1057 } 1058 this.listPosition = 1 1059 return { offsetRemain: offset }; 1060 }) 1061 1062 Text("Scroll Area") 1063 .width("100%") 1064 .height("40%") 1065 .backgroundColor(0X330000FF) 1066 .fontSize(16) 1067 .textAlign(TextAlign.Center) 1068 } 1069 } 1070 .width("100%").height("100%") 1071 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20) 1072 } 1073} 1074``` 1075 1076 1077 1078### Example 3: Implementing Nested Scrolling (Method 2) 1079This example uses the **nestedScroll** attribute to achieve nested scrolling between an inner **List** component and an outer **Scroll** component. 1080```ts 1081@Entry 1082@Component 1083struct StickyNestedScroll { 1084 @State arr: number[] = [] 1085 1086 @Styles 1087 listCard() { 1088 .backgroundColor(Color.White) 1089 .height(72) 1090 .width("100%") 1091 .borderRadius(12) 1092 } 1093 1094 build() { 1095 Scroll() { 1096 Column() { 1097 Text("Scroll Area") 1098 .width("100%") 1099 .height("40%") 1100 .backgroundColor('#0080DC') 1101 .textAlign(TextAlign.Center) 1102 Tabs({ barPosition: BarPosition.Start }) { 1103 TabContent() { 1104 List({ space: 10 }) { 1105 ForEach(this.arr, (item: number) => { 1106 ListItem() { 1107 Text("item" + item) 1108 .fontSize(16) 1109 }.listCard() 1110 }, (item: string) => item) 1111 }.width("100%") 1112 .edgeEffect(EdgeEffect.Spring) 1113 .nestedScroll({ 1114 scrollForward: NestedScrollMode.PARENT_FIRST, 1115 scrollBackward: NestedScrollMode.SELF_FIRST 1116 }) 1117 }.tabBar("Tab1") 1118 1119 TabContent() { 1120 }.tabBar("Tab2") 1121 } 1122 .vertical(false) 1123 .height("100%") 1124 }.width("100%") 1125 } 1126 .edgeEffect(EdgeEffect.Spring) 1127 .friction(0.6) 1128 .backgroundColor('#DCDCDC') 1129 .scrollBar(BarState.Off) 1130 .width('100%') 1131 .height('100%') 1132 } 1133 1134 aboutToAppear() { 1135 for (let i = 0; i < 30; i++) { 1136 this.arr.push(i) 1137 } 1138 } 1139} 1140``` 1141 1142### Example 4: Implementing Nested Scrolling with Parent-to-Child Scrolling Propagation 1143This example demonstrates how to propagate scrolling from a parent component to a child component using the **enableScrollInteraction** attribute and the **onScrollFrameBegin** event. 1144```ts 1145@Entry 1146@Component 1147struct NestedScroll { 1148 private headerHeight: number = 0; 1149 private arr: number[] = [] 1150 private scrollerForParent: Scroller = new Scroller() 1151 private scrollerForChild: Scroller = new Scroller() 1152 1153 aboutToAppear(): void { 1154 for (let i = 0; i < 10; i++) { 1155 this.arr.push(i) 1156 } 1157 } 1158 1159 build() { 1160 Scroll(this.scrollerForParent) { 1161 Column() { 1162 Text("Scroll Area") 1163 .width("100%") 1164 .height("40%") 1165 .backgroundColor(0X330000FF) 1166 .fontSize(16) 1167 .textAlign(TextAlign.Center) 1168 .onClick(() => { 1169 this.scrollerForChild.scrollToIndex(5) 1170 }) 1171 .onSizeChange((oldValue: SizeOptions, newValue: SizeOptions) => { 1172 this.headerHeight = newValue.height! as number 1173 }) 1174 List({ space: 20, scroller: this.scrollerForChild }) { 1175 ForEach(this.arr, (item: number) => { 1176 ListItem() { 1177 Text("ListItem" + item) 1178 .width("100%") 1179 .height("100%") 1180 .borderRadius(15) 1181 .fontSize(16) 1182 .textAlign(TextAlign.Center) 1183 .backgroundColor(Color.White) 1184 }.width("100%").height(100) 1185 }, (item: string) => item) 1186 } 1187 .width("100%") 1188 .height("100%") 1189 .edgeEffect(EdgeEffect.None) 1190 .scrollBar(BarState.Off) 1191 .enableScrollInteraction(false) 1192 1193 Text("Scroll Area") 1194 .width("100%") 1195 .height("40%") 1196 .backgroundColor(0X330000FF) 1197 .fontSize(16) 1198 .textAlign(TextAlign.Center) 1199 } 1200 } 1201 .scrollBar(BarState.Off) 1202 .edgeEffect(EdgeEffect.Spring) 1203 .onScrollFrameBegin((offset: number, state: ScrollState) => { 1204 let retOffset = offset; 1205 let currOffset = this.scrollerForParent.currentOffset().yOffset; 1206 let newOffset = currOffset + offset; 1207 if (offset > 0) { 1208 if (this.scrollerForChild.isAtEnd()) { 1209 return { offsetRemain: offset } 1210 } 1211 if (newOffset > this.headerHeight) { 1212 retOffset = this.headerHeight - currOffset 1213 } 1214 this.scrollerForChild.scrollBy(0, offset - retOffset) 1215 } else { 1216 if (this.scrollerForChild.currentOffset().yOffset <= 0) { 1217 return { offsetRemain: offset } 1218 } 1219 if (newOffset < this.headerHeight) { 1220 retOffset = this.headerHeight - currOffset 1221 } 1222 this.scrollerForChild.scrollBy(0, offset - retOffset) 1223 } 1224 return { offsetRemain: retOffset } 1225 }) 1226 .width("100%") 1227 .height("100%") 1228 .backgroundColor(0xDCDCDC) 1229 } 1230} 1231``` 1232 1233### Example 5: Setting Scroll Snapping 1234This example shows how to set scroll snapping for a **Scroll** component. 1235```ts 1236@Entry 1237@Component 1238struct Index { 1239 scroller: Scroller = new Scroller; 1240 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] 1241 build() { 1242 Scroll(this.scroller) { 1243 Column() { 1244 ForEach(this.arr, (item: number) => { 1245 Text(item.toString()) 1246 .width('90%') 1247 .height(200) 1248 .backgroundColor(0xFFFFFF) 1249 .borderWidth(1) 1250 .borderColor(Color.Black) 1251 .borderRadius(15) 1252 .fontSize(16) 1253 .textAlign(TextAlign.Center) 1254 }, (item: string) => item) 1255 }.width('100%').backgroundColor(0xDCDCDC) 1256 } 1257 .backgroundColor(Color.Yellow) 1258 .height('100%') 1259 .edgeEffect(EdgeEffect.Spring) 1260 .scrollSnap({snapAlign:ScrollSnapAlign.START, snapPagination:400, enableSnapToStart:true, enableSnapToEnd:true}) 1261 } 1262} 1263``` 1264 1265 1266### Example 6: Obtaining the Index of a Child Component 1267This example demonstrates how to obtain the index of a child component in a **List** component. 1268 1269```ts 1270// xxx.ets 1271@Entry 1272@Component 1273struct ListExample { 1274 private arr: number[] = [] 1275 private scroller: ListScroller = new ListScroller() 1276 @State listSpace: number = 10 1277 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100) 1278 @State listIndex: number = -1 1279 @State mess:string = "null" 1280 @State itemBackgroundColorArr: boolean[] = [false] 1281 aboutToAppear(){ 1282 // Initialize the data source. 1283 for (let i = 0; i < 10; i++) { 1284 this.arr.push(i) 1285 } 1286 this.listChildrenSize.splice(0, 5, [100, 100, 100, 100, 100]) 1287 } 1288 build() { 1289 Column() { 1290 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1291 ForEach(this.arr, (item: number) => { 1292 ListItem() { 1293 Text('item-' + item) 1294 .height( item < 5 ? 100 : this.listChildrenSize.childDefaultSize) 1295 .width('90%') 1296 .fontSize(16) 1297 .textAlign(TextAlign.Center) 1298 .borderRadius(10) 1299 .backgroundColor( this.itemBackgroundColorArr[item] ? 0x68B4FF: 0xFFFFFF) 1300 } 1301 }, (item: string) => item) 1302 } 1303 .backgroundColor(Color.Gray) 1304 .layoutWeight(1) 1305 .scrollBar(BarState.On) 1306 .childrenMainSize(this.listChildrenSize) 1307 .alignListItem(ListItemAlign.Center) 1308 .gesture( 1309 PanGesture() 1310 .onActionUpdate((event: GestureEvent) => { 1311 if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) { 1312 this.listIndex = this.scroller.getItemIndex(event.fingerList[0].localX, event.fingerList[0].localY) 1313 this.itemBackgroundColorArr[this.listIndex] = true; 1314 } 1315 }) 1316 ) 1317 .gesture( 1318 TapGesture({ count: 1 }) 1319 .onAction((event: GestureEvent) => { 1320 if (event) { 1321 this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length); 1322 } 1323 }) 1324 ) 1325 1326 Text('You are currently at index '+ this.listIndex) 1327 .fontColor(Color.Red) 1328 .height(50) 1329 } 1330 } 1331} 1332``` 1333 1334 1335 1336### Example 7: Setting Edge Fading 1337This example demonstrates how to implement a **Scroll** component with an edge fading effect and set the length of the fading edge. 1338 1339```ts 1340// xxx.ets 1341import { LengthMetrics } from '@kit.ArkUI' 1342@Entry 1343@Component 1344struct ScrollExample { 1345 scroller: Scroller = new Scroller() 1346 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] 1347 1348 build() { 1349 Stack({ alignContent: Alignment.TopStart }) { 1350 Scroll(this.scroller) { 1351 Column() { 1352 ForEach(this.arr, (item: number) => { 1353 Text(item.toString()) 1354 .width('90%') 1355 .height(150) 1356 .backgroundColor(0xFFFFFF) 1357 .borderRadius(15) 1358 .fontSize(16) 1359 .textAlign(TextAlign.Center) 1360 .margin({ top: 10 }) 1361 }, (item: string) => item) 1362 }.width('100%') 1363 } 1364 .fadingEdge(true,{fadingEdgeLength:LengthMetrics.vp(80)}) 1365 1366 1367 1368 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1369 } 1370} 1371``` 1372 1373 1374 1375### Example 8: Setting the Single-Side Edge Effect 1376 1377This example demonstrates how to set a single-side edge effect for the **Scroll** component using the **edgeEffect** API. 1378 1379```ts 1380// xxx.ets 1381@Entry 1382@Component 1383struct ScrollExample { 1384 scroller: Scroller = new Scroller() 1385 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] 1386 1387 build() { 1388 Stack({ alignContent: Alignment.TopStart }) { 1389 Scroll(this.scroller) { 1390 Column() { 1391 ForEach(this.arr, (item: number) => { 1392 Text(item.toString()) 1393 .width('90%') 1394 .height(150) 1395 .backgroundColor(0xFFFFFF) 1396 .borderRadius(15) 1397 .fontSize(16) 1398 .textAlign(TextAlign.Center) 1399 .margin({ top: 10 }) 1400 }, (item: string) => item) 1401 }.width('100%') 1402 } 1403 .edgeEffect(EdgeEffect.Spring,{alwaysEnabled:true,effectEdge:EffectEdge.START}) 1404 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1405 } 1406} 1407``` 1408 1409 1410
