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 109**Atomic service API**: This API can be used in atomic services since API version 11. 110 111**System capability**: SystemCapability.ArkUI.ArkUI.Full 112 113**Parameters** 114 115| Name| Type | Mandatory| Description | 116| ------ | ----------------------------------------- | ---- | -------------------------- | 117| value | [ScrollSnapOptions](#scrollsnapoptions10) | Yes | Scroll snapping mode.| 118 119### edgeEffect 120 121edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions) 122 123Sets the effect used when the scroll boundary is reached. 124 125**Atomic service API**: This API can be used in atomic services since API version 11. 126 127**System capability**: SystemCapability.ArkUI.ArkUI.Full 128 129**Parameters** 130 131| Name | Type | Mandatory| Description | 132| --------------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 133| 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**| 134| 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 }**| 135 136### enableScrollInteraction<sup>10+</sup> 137 138enableScrollInteraction(value: boolean) 139 140Sets 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. 141 142**Atomic service API**: This API can be used in atomic services since API version 11. 143 144**System capability**: SystemCapability.ArkUI.ArkUI.Full 145 146**Parameters** 147 148| Name| Type | Mandatory| Description | 149| ------ | ------- | ---- | ----------------------------------- | 150| value | boolean | Yes | Whether to support scroll gestures.<br>Default value: **true**| 151 152### nestedScroll<sup>10+</sup> 153 154nestedScroll(value: NestedScrollOptions) 155 156Sets 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. 157 158**Atomic service API**: This API can be used in atomic services since API version 11. 159 160**System capability**: SystemCapability.ArkUI.ArkUI.Full 161 162**Parameters** 163 164| Name| Type | Mandatory| Description | 165| ------ | ----------------------------------------------------- | ---- | -------------- | 166| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10) | Yes | Nested scrolling options.<br>Default value: **{ scrollForward: NestedScrollMode.SELF_ONLY, scrollBackward: NestedScrollMode.SELF_ONLY }**| 167 168### friction<sup>10+</sup> 169 170friction(value: number | Resource) 171 172Sets 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. 173 174**Atomic service API**: This API can be used in atomic services since API version 11. 175 176**System capability**: SystemCapability.ArkUI.ArkUI.Full 177 178**Parameters** 179 180| Name| Type | Mandatory| Description | 181| ------ | ---------------------------------------------------- | ---- | --------------------------------------------------------- | 182| 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**.| 183 184### enablePaging<sup>11+</sup> 185 186enablePaging(value: boolean) 187 188Sets whether to enable the swipe-to-turn-pages feature. If both **enablePaging** and **scrollSnap** are set, **scrollSnap** takes effect, but **enablePaging** does not. 189 190**Atomic service API**: This API can be used in atomic services since API version 12. 191 192**System capability**: SystemCapability.ArkUI.ArkUI.Full 193 194**Parameters** 195 196| Name| Type | Mandatory| Description | 197| ------ | ------- | ---- | ------------------------------------- | 198| 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**| 199 200### initialOffset<sup>12+</sup> 201 202initialOffset(value: OffsetOptions) 203 204Sets 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. 205 206**Atomic service API**: This API can be used in atomic services since API version 12. 207 208**System capability**: SystemCapability.ArkUI.ArkUI.Full 209 210**Parameters** 211 212| Name| Type | Mandatory| Description | 213| ------ | ------- | ---- | ------------------------------------- | 214| 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.| 215 216## ScrollDirection 217 218Enumerates the scrolling directions. 219 220**System capability**: SystemCapability.ArkUI.ArkUI.Full 221 222| Name | Description | 223| ---------- | ------------------------ | 224| Horizontal | Only horizontal scrolling is supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 225| Vertical | Only vertical scrolling is supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 226| None | Scrolling is disabled.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 227| Free<sup>(deprecated) </sup> | Vertical or horizontal scrolling is supported.<br> This API is deprecated since API version 9.| 228 229## ScrollSnapOptions<sup>10+</sup> 230 231Defines a scroll snapping mode object. 232 233**Atomic service API**: This API can be used in atomic services since API version 11. 234 235**System capability**: SystemCapability.ArkUI.ArkUI.Full 236 237| Name | Type | Mandatory | Description | 238| ---------- | --------------------|-------------------- | -------- | 239| snapAlign | [ScrollSnapAlign](ts-container-list.md#scrollsnapalign10) | Yes| Alignment mode for the scroll snap position.<br>**NOTE**<br>1. Default value: **ScrollSnapAlign.NONE**| 240| 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.| 241| 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.| 242| 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.| 243 244## Events 245 246In 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. 247> **NOTE** 248> 249> The [onWillScroll](ts-container-scrollable-common.md#onwillscroll12) and [onDidScroll](ts-container-scrollable-common.md#ondidscroll12) events are not supported. 250 251 252### onScrollFrameBegin<sup>9+</sup> 253 254onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain: number; }) 255 256Triggered 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. 257 258The value of **offsetRemain** can be a negative value. 259 260If 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**. 261 262Notes: 263 2641. 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. 265 266**Atomic service API**: This API can be used in atomic services since API version 11. 267 268**System capability**: SystemCapability.ArkUI.ArkUI.Full 269 270**Parameters** 271 272| Name| Type | Mandatory| Description | 273| ------ | ------------------------------------------------------- | ---- | -------------------------- | 274| offset | number | Yes | Amount to scroll by, in vp.| 275| state | [ScrollState](ts-container-list.md#scrollstate)| Yes | Current scroll state. | 276 277**Return value** 278 279| Type | Description | 280| ------------------------ | -------------------- | 281| { offsetRemain: number } | Actual amount by which the grid scrolls, in vp.| 282 283### onScroll<sup>(deprecated)</sup> 284 285onScroll(event: (xOffset: number, yOffset: number) => void) 286 287Triggered to return the horizontal and vertical offsets, in vp, during scrolling when the specified scroll event occurs. 288 289**NOTE** 290 2911. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations. 292 2932. This event is triggered when the controller API is called. 294 2953. This event supports the out-of-bounds bounce effect. 296 297This API is deprecated since API version 12. You are advised to use [onWillScroll](#onwillscroll12) instead. 298 299**Atomic service API**: This API can be used in atomic services since API version 11. 300 301**System capability**: SystemCapability.ArkUI.ArkUI.Full 302 303**Parameters** 304 305| Name | Type | Mandatory| Description | 306| ------- | --------------------------------------------------------- | ---- | ---------------------- | 307| 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| 308| 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| 309 310### onWillScroll<sup>12+</sup> 311 312onWillScroll(handler: ScrollOnWillScrollCallback) 313 314Triggered before scrolling. 315 316The 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. 317 318**NOTE** 319 3201. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations. 321 3222. This event is triggered when the controller API is called. 323 3243. This event supports the out-of-bounds bounce effect. 325 326**Atomic service API**: This API can be used in atomic services since API version 12. 327 328**System capability**: SystemCapability.ArkUI.ArkUI.Full 329 330**Parameters** 331 332| Name | Type | Mandatory| Description | 333| ------- | --------------------------------------------------------- | ---- | ---------------------- | 334| handler | [ScrollOnWillScrollCallback](#scrollonwillscrollcallback12) | Yes | Callback triggered before scrolling.| 335 336### onDidScroll<sup>12+</sup> 337 338onDidScroll(handler: ScrollOnScrollCallback) 339 340Triggered when the **Scroll** component scrolls. 341 342The return value is the scrolling offset amount in the current frame, along with the current scroll state. 343 344**NOTE** 345 3461. This event is triggered when scrolling is started by the **Scroll** component or other input settings, such as keyboard and mouse operations. 347 3482. This event is triggered when the controller API is called. 349 3503. This event supports the out-of-bounds bounce effect. 351 352**Atomic service API**: This API can be used in atomic services since API version 12. 353 354**System capability**: SystemCapability.ArkUI.ArkUI.Full 355 356**Parameters** 357 358| Name | Type | Mandatory| Description | 359| ------- | --------------------------------------------------------- | ---- | ---------------------- | 360| handler | [ScrollOnScrollCallback](#scrollonscrollcallback12) | Yes | Callback triggered when the **Scroll** component scrolls.| 361 362### onScrollEdge 363 364onScrollEdge(event: (side: Edge) => void) 365 366Triggered when scrolling reaches the edge. 367 368**NOTE** 369 3701. 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. 371 372**Atomic service API**: This API can be used in atomic services since API version 11. 373 374**System capability**: SystemCapability.ArkUI.ArkUI.Full 375 376**Parameters** 377 378| Name| Type | Mandatory| Description | 379| ------ | --------------------------------- | ---- | ------------------ | 380| side | [Edge](ts-appendix-enums.md#edge) | Yes | Edge position to scroll to.| 381 382### onScrollEnd<sup>(deprecated) </sup> 383 384onScrollEnd(event: () => void) 385 386Triggered when scrolling stops. 387 388**NOTE** 389 3901. 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. 391 392This event is deprecated since API version 9. Use the **onScrollStop** event instead. 393 394**System capability**: SystemCapability.ArkUI.ArkUI.Full 395 396### onScrollStart<sup>9+</sup> 397 398onScrollStart(event: () => void) 399 400Triggered 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. 401 402**NOTE** 403 4041. 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. 405 406**Atomic service API**: This API can be used in atomic services since API version 11. 407 408**System capability**: SystemCapability.ArkUI.ArkUI.Full 409 410### onScrollStop<sup>9+</sup> 411 412onScrollStop(event: () => void) 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## ScrollOnScrollCallback<sup>12+</sup> 425 426type ScrollOnScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState) => void 427 428Represents the callback triggered when the **Scroll** component scrolls. 429 430**Atomic service API**: This API can be used in atomic services since API version 12. 431 432**System capability**: SystemCapability.ArkUI.ArkUI.Full 433 434| Name | Type | Mandatory| Description | 435| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 436| 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| 437| 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| 438| scrollState | [ScrollState](ts-container-list.md#scrollstate)| Yes | Current scrolling state. | 439 440> **NOTE** 441> 442> 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**. 443 444## ScrollOnWillScrollCallback<sup>12+</sup> 445 446type ScrollOnWillScrollCallback = (xOffset: number, yOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | OffsetResult 447 448Callback triggered before scrolling. 449 450**Atomic service API**: This API can be used in atomic services since API version 12. 451 452**System capability**: SystemCapability.ArkUI.ArkUI.Full 453 454| Name | Type | Mandatory| Description | 455| ----------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 456| 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| 457| 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| 458| scrollState | [ScrollState](ts-container-list.md#scrollstate)| Yes | Current scrolling state. | 459| scrollSource | [ScrollSource](ts-appendix-enums.md#scrollsource12) | Yes| Source of the current scrolling operation.| 460 461**Return value** 462 463| Type | Description | 464| ------------------------------------------------------------ | ------------------------------------------------------------ | 465| 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)**.| 466 467## Scroller 468 469Implements a controller for a scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. One controller can control only one container component. The supported container components are **List**, **Scroll**, **ScrollBar**, **Grid**, and **WaterFlow**. 470 471>**NOTE** 472> 473>1. The binding of a **Scroller** instance to a scrollable container component occurs during the component creation phase.<br> 474>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> 475>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> 476>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. 477 478### Objects to Import 479 480``` 481scroller: Scroller = new Scroller() 482``` 483 484### constructor 485 486constructor() 487 488A constructor used to create a **Scroller** object. 489 490**Atomic service API**: This API can be used in atomic services since API version 11. 491 492**System capability**: SystemCapability.ArkUI.ArkUI.Full 493 494### scrollTo 495 496scrollTo(value: { xOffset: number | string, yOffset: number | string, animation?: { duration?: number, curve?: Curve | ICurve, canOverScroll?: boolean } | boolean }) 497 498 499Scrolls to the specified position. 500 501**Atomic service API**: This API can be used in atomic services since API version 11. 502 503**System capability**: SystemCapability.ArkUI.ArkUI.Full 504 505**Parameters** 506 507| Name | Type | Mandatory| Description | 508| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 509| 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.| 510| 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.| 511| animation | [ScrollAnimationOptions](#scrollanimationoptions12)<sup>12+</sup> \| boolean<sup>10+ </sup> | 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**.<br>Since API version 12, {duration?: number, curve?: [Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve9)<sup>10+ </sup>} is abstracted as the **ScrollAnimationOptions** API, and the **canOverScroll** parameter is added to the API.| 512 513 514### scrollEdge 515 516scrollEdge(value: Edge, options?: ScrollEdgeOptions) 517 518 519Scrolls 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. 520By default, the **Scroll** component comes with an animation, while the **Grid**, **List**, and **WaterFlow** components do not. 521 522**System capability**: SystemCapability.ArkUI.ArkUI.Full 523 524**Parameters** 525 526| Name | Type| Mandatory | Description | 527| ----- | ---- | ---- | --------- | 528| 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.| 529| 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.| 530 531### fling<sup>12+</sup> 532 533fling(velocity: number): void 534 535 536Performs inertial scrolling based on the initial velocity passed in. 537 538**Atomic service API**: This API can be used in atomic services since API version 12. 539 540**System capability**: SystemCapability.ArkUI.ArkUI.Full 541 542**Parameters** 543 544| Name | Type| Mandatory| Description | 545| -------- | -------- | ---- | ------------------------------------------------------------ | 546| 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.| 547 548**Error codes** 549 550For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Scrollable Component Error Codes](../errorcode-scroll.md). 551 552| ID| Error Message| 553| ------- | -------- | 554| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 555| 100004 | Controller not bound to component. | 556 557### scrollPage<sup>9+</sup> 558 559scrollPage(value: ScrollPageOptions) 560 561Scrolls to the next or previous page. 562 563**Atomic service API**: This API can be used in atomic services since API version 11. 564 565**System capability**: SystemCapability.ArkUI.ArkUI.Full 566 567**Parameters** 568 569| Name| Type | Mandatory| Description | 570| ------ | -------------------------------------------------- | ---- | -------------- | 571| value | [ScrollPageOptions](#scrollpageoptions14)| Yes | Page turning mode.| 572 573### scrollPage<sup>(deprecated)</sup> 574 575scrollPage(value: { next: boolean, direction?: Axis }) 576 577Scrolls 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. 578 579**System capability**: SystemCapability.ArkUI.ArkUI.Full 580 581**Parameters** 582 583| Name | Type | Mandatory | Description | 584| --------- | ------- | ---- | ------------------------------ | 585| 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.| 586| direction | [Axis](ts-appendix-enums.md#axis) | No | Scrolling direction: horizontal or vertical. | 587 588### currentOffset 589 590currentOffset(): OffsetResult 591 592Obtains the current scrolling offset. 593 594**Atomic service API**: This API can be used in atomic services since API version 11. 595 596**System capability**: SystemCapability.ArkUI.ArkUI.Full 597 598| Type | Description| 599| -------- | -------- | 600| [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.| 601 602### scrollToIndex 603 604scrollToIndex(value: number, smooth?: boolean, align?: ScrollAlign, options?: ScrollToIndexOptions) 605 606Scrolls to a specified index, with support for setting an extra offset for the scroll. 607 608When **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. 609 610 611> **NOTE** 612> 613> This API only works for the **Grid**, **List**, and **WaterFlow** components. 614 615**Atomic service API**: This API can be used in atomic services since API version 11. 616 617**System capability**: SystemCapability.ArkUI.ArkUI.Full 618 619**Parameters** 620 621| Name | Type| Mandatory| Description | 622| --------------------- | -------- | ---- | ------------------------------------------------------------ | 623| 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. | 624| 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**| 625| 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.| 626| 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| 627 628### scrollBy<sup>9+</sup> 629 630scrollBy(dx: Length, dy: Length) 631 632 633Scrolls by the specified amount. 634 635 636> **NOTE** 637> 638> This API is available for the **Scroll**, **List**, **Grid**, and **WaterFlow** components. 639 640**Atomic service API**: This API can be used in atomic services since API version 11. 641 642**System capability**: SystemCapability.ArkUI.ArkUI.Full 643 644**Parameters** 645 646| Name | Type | Mandatory | Description | 647| ----- | ------ | ---- | ----------------- | 648| dx | [Length](ts-types.md#length) | Yes | Amount to scroll by in the horizontal direction. The percentage format is not supported.| 649| dy | [Length](ts-types.md#length) | Yes | Amount to scroll by in the vertical direction. The percentage format is not supported.| 650 651### isAtEnd<sup>10+</sup> 652 653isAtEnd(): boolean 654 655Checks whether the component has scrolled to the bottom. 656 657> **NOTE** 658> 659> This API is available for the **Scroll**, **List**, **Grid**, and **WaterFlow** components. 660 661**Atomic service API**: This API can be used in atomic services since API version 11. 662 663**System capability**: SystemCapability.ArkUI.ArkUI.Full 664 665**Return value** 666 667| Type | Description | 668| ------- | -------- | 669| boolean | The value **true** means that the component has scrolled to the bottom, and **false** means the opposite.| 670 671### getItemRect<sup>11+</sup> 672 673getItemRect(index: number): RectResult 674 675Obtains the size and position of a child component relative to its container. 676 677> **NOTE** 678> 679> This API is available for the **Scroll**, **List**, **Grid**, and **WaterFlow** components. 680 681**Atomic service API**: This API can be used in atomic services since API version 12. 682 683**System capability**: SystemCapability.ArkUI.ArkUI.Full 684 685**Parameters** 686 687| Name | Type | Mandatory | Description | 688| ----- | ------ | ---- | ----------------- | 689| index | number | Yes | Index of the target child component.| 690 691> **NOTE** 692> 693> - The value of **index** must be the index of a child component visible in the display area. Otherwise, the value is considered invalid. 694> - The size and position returned for an invalid value are both **0**. 695 696**Return value** 697 698| Type | Description | 699| ------------------- | -------- | 700| [RectResult](ts-types.md#rectresult10) | Size and position of the child component relative to the component.<br>Unit: vp| 701 702**Error codes** 703 704For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Scrollable Component Error Codes](../errorcode-scroll.md). 705 706| ID| Error Message| 707| ------- | -------- | 708| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 709| 100004 | Controller not bound to component. | 710### getItemIndex<sup>14+</sup> 711 712getItemIndex(x: number, y: number): number 713 714Obtains the index of a child component based on coordinates. 715 716> **NOTE** 717> 718> This API is available for the **List**, **Grid**, and **WaterFlow** components. 719 720**Atomic service API**: This API can be used in atomic services since API version 14. 721 722**System capability**: SystemCapability.ArkUI.ArkUI.Full 723 724**Parameters** 725 726| Name | Type | Mandatory | Description | 727| ----- | ------ | ---- | ----------------- | 728| x | number | Yes | X-coordinate, in vp.| 729| y | number | Yes| Y-coordinate, in vp.| 730 731> **NOTE** 732> 733> The returned index is **-1** for invalid coordinates. 734 735**Return value** 736 737| Type | Description | 738| ------------------- | -------- | 739| number | Index of the child component, in vp.| 740 741**Error codes** 742 743For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md) and [Scrollable Component Error Codes](../errorcode-scroll.md). 744 745| ID| Error Message| 746| ------- | -------- | 747| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 748| 100004 |The controller not bound to component. | 749 750## OffsetResult<sup>11+</sup> 751 752Represents the offset values resulting from a scroll operation. 753 754**Atomic service API**: This API can be used in atomic services since API version 11. 755 756**System capability**: SystemCapability.ArkUI.ArkUI.Full 757 758| Name | Type | Read Only| Optional| Description | 759| ------- |------- | ---- | ---- | -------------------------------- | 760| xOffset | number | No | No | Horizontal scrolling offset.<br>The unit of the return value is vp.| 761| yOffset | number | No | No | Vertical scrolling offset.<br>The unit of the return value is vp.| 762 763## ScrollAnimationOptions<sup>12+</sup> 764 765Provides parameters for customizing scroll animations. 766 767**Atomic service API**: This API can be used in atomic services since API version 12. 768 769**System capability**: SystemCapability.ArkUI.ArkUI.Full 770 771| Name | Type | Mandatory | Description | 772| ----- | ------ | ------ | ----------------- | 773| duration | number | No| Scrolling duration.<br>Default value: **1000**<br>**NOTE**<br>A value less than 0 evaluates to the default value.| 774| curve | [Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve9) | No| Scrolling curve.<br>Default value: **Curve.Ease**| 775| 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).| 776 777## ScrollAlign<sup>10+</sup> 778 779Enumerates alignment modes. 780 781**Atomic service API**: This API can be used in atomic services since API version 11. 782 783**System capability**: SystemCapability.ArkUI.ArkUI.Full 784 785| Name | Description | 786| ------ | ------------------------------ | 787| START | The start edge of the list item is flush with the start edge of the list. | 788| CENTER | The list item is centered along the main axis of the list. | 789| END | The end edge of the list item is flush with the end edge of the list.| 790| 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.| 791 792## ScrollToIndexOptions<sup>12+</sup> 793 794Provides parameters for scrolling to a specific index. 795 796**Atomic service API**: This API can be used in atomic services since API version 12. 797 798**System capability**: SystemCapability.ArkUI.ArkUI.Full 799 800| Name | Type | Mandatory| Description | 801| ----- | ------ | ------ | ----------------- | 802| extraOffset | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | No| Extra offset for scrolling to a specified index.| 803 804## ScrollPageOptions<sup>14+</sup> 805 806Provides parameters for page scrolling behavior. 807 808**Atomic service API**: This API can be used in atomic services since API version 14. 809 810**System capability**: SystemCapability.ArkUI.ArkUI.Full 811 812| Name | Type| Mandatory| Description | 813| --------- | -------- | ---- | ------------------------------------------------------------ | 814| 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. | 815| 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**| 816 817## OffsetOptions<sup>12+</sup> 818 819Provides parameters for setting the initial scrolling offset. 820 821**Atomic service API**: This API can be used in atomic services since API version 12. 822 823**System capability**: SystemCapability.ArkUI.ArkUI.Full 824 825| Name | Type | Mandatory| Description | 826| ----- | ------| ------- | ----------------- | 827| xOffset | [Dimension](ts-types.md#dimension10) | No|Horizontal scrolling offset.<br>Default value: **0**| 828| yOffset | [Dimension](ts-types.md#dimension10) | No|Vertical scrolling offset.<br>Default value: **0**| 829 830## ScrollEdgeOptions<sup>12+</sup> 831 832Provides parameters for scrolling to the edge of a scrollable container. 833 834**Atomic service API**: This API can be used in atomic services since API version 12. 835 836**System capability**: SystemCapability.ArkUI.ArkUI.Full 837 838| Name | Type| Mandatory| Description | 839| --------- | -------- | ---- | ------------------------------------------------------------ | 840| 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 | 841 842## Example 843### Example 1: Setting the Scroller 844This example demonstrates the use of some attributes of the **Scroll** component and the **Scroller**. 845 846```ts 847// xxx.ets 848import { curves } from '@kit.ArkUI' 849 850@Entry 851@Component 852struct ScrollExample { 853 scroller: Scroller = new Scroller() 854 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 855 856 build() { 857 Stack({ alignContent: Alignment.TopStart }) { 858 Scroll(this.scroller) { 859 Column() { 860 ForEach(this.arr, (item: number) => { 861 Text(item.toString()) 862 .width('90%') 863 .height(150) 864 .backgroundColor(0xFFFFFF) 865 .borderRadius(15) 866 .fontSize(16) 867 .textAlign(TextAlign.Center) 868 .margin({ top: 10 }) 869 }, (item: string) => item) 870 }.width('100%') 871 } 872 .scrollable(ScrollDirection.Vertical) // The scrollbar scrolls in the vertical direction. 873 .scrollBar(BarState.On) // The scrollbar is always displayed. 874 .scrollBarColor(Color.Gray) // The scrollbar color is gray. 875 .scrollBarWidth(10) // The scrollbar width is 10. 876 .friction(0.6) 877 .edgeEffect(EdgeEffect.None) 878 .onWillScroll((xOffset: number, yOffset: number, scrollState: ScrollState) => { 879 console.info(xOffset + ' ' + yOffset) 880 }) 881 .onScrollEdge((side: Edge) => { 882 console.info('To the edge') 883 }) 884 .onScrollStop(() => { 885 console.info('Scroll Stop') 886 }) 887 888 Button('scroll 150') 889 .height('5%') 890 .onClick(() => { // Click to scroll down by 150.0 vp. 891 this.scroller.scrollBy(0, 150) 892 }) 893 .margin({ top: 10, left: 20 }) 894 Button('scroll 100') 895 .height('5%') 896 .onClick(() => { // Click to scroll down by 100.0 vp. 897 const yOffset: number = this.scroller.currentOffset().yOffset; 898 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100 }) 899 }) 900 .margin({ top: 60, left: 20 }) 901 Button('scroll 100') 902 .height('5%') 903 .onClick(() => {// Click to scroll down by 100.0 vp. An animation is applied to the scrolling. 904 let curve = curves.interpolatingSpring(10, 1, 228, 30) // Create a step curve. 905 const yOffset: number = this.scroller.currentOffset().yOffset; 906 this.scroller.scrollTo({ xOffset: 0, yOffset: yOffset + 100, animation: { duration: 1000, curve: curve } }) 907 }) 908 .margin({ top: 110, left: 20 }) 909 Button('back top') 910 .height('5%') 911 .onClick(() => { // Click to go back to the top. 912 this.scroller.scrollEdge(Edge.Top) 913 }) 914 .margin({ top: 160, left: 20 }) 915 Button('next page') 916 .height('5%') 917 .onClick(() => { // Click to go to the next page. 918 this.scroller.scrollPage({ next: true ,animation: true }) 919 }) 920 .margin({ top: 210, left: 20 }) 921 Button('fling -3000') 922 .height('5%') 923 .onClick(() => { // Trigger a fling with an initial velocity of -3000 vp/s. 924 this.scroller.fling(-3000) 925 }) 926 .margin({ top: 260, left: 20 }) 927 Button('scroll to bottom 700') 928 .height('5%') 929 .onClick(() => {// After the button is clicked, the component scrolls to the bottom edge at a velocity of 700 vp/s. 930 this.scroller.scrollEdge(Edge.Bottom, { velocity: 700 }) 931 }) 932 .margin({ top: 310, left: 20 }) 933 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 934 } 935} 936``` 937 938 939 940### Example 2: Implementing Nested Scrolling (Method 1) 941This example uses the **onScrollFrameBegin** event to achieve nested scrolling between an inner **List** component and an outer **Scroll** component. 942```ts 943import { LengthMetrics } from '@kit.ArkUI' 944 945@Entry 946@Component 947struct NestedScroll { 948 @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. 949 private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] 950 private scrollerForScroll: Scroller = new Scroller() 951 private scrollerForList: Scroller = new Scroller() 952 953 build() { 954 Flex() { 955 Scroll(this.scrollerForScroll) { 956 Column() { 957 Text("Scroll Area") 958 .width("100%") 959 .height("40%") 960 .backgroundColor(0X330000FF) 961 .fontSize(16) 962 .textAlign(TextAlign.Center) 963 .onClick(() => { 964 this.scrollerForList.scrollToIndex(5, false, ScrollAlign.START, { extraOffset: LengthMetrics.vp(5) }) 965 }) 966 967 List({ space: 20, scroller: this.scrollerForList }) { 968 ForEach(this.arr, (item: number) => { 969 ListItem() { 970 Text("ListItem" + item) 971 .width("100%") 972 .height("100%") 973 .borderRadius(15) 974 .fontSize(16) 975 .textAlign(TextAlign.Center) 976 .backgroundColor(Color.White) 977 }.width("100%").height(100) 978 }, (item: string) => item) 979 } 980 .width("100%") 981 .height("50%") 982 .edgeEffect(EdgeEffect.None) 983 .friction(0.6) 984 .onReachStart(() => { 985 this.listPosition = 0 986 }) 987 .onReachEnd(() => { 988 this.listPosition = 2 989 }) 990 .onScrollFrameBegin((offset: number) => { 991 if ((this.listPosition == 0 && offset <= 0) || (this.listPosition == 2 && offset >= 0)) { 992 this.scrollerForScroll.scrollBy(0, offset) 993 return { offsetRemain: 0 } 994 } 995 this.listPosition = 1 996 return { offsetRemain: offset }; 997 }) 998 999 Text("Scroll Area") 1000 .width("100%") 1001 .height("40%") 1002 .backgroundColor(0X330000FF) 1003 .fontSize(16) 1004 .textAlign(TextAlign.Center) 1005 } 1006 } 1007 .width("100%").height("100%") 1008 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20) 1009 } 1010} 1011``` 1012 1013 1014 1015### Example 3: Implementing Nested Scrolling (Method 2) 1016This example uses the **nestedScroll** attribute to achieve nested scrolling between an inner **List** component and an outer **Scroll** component. 1017```ts 1018@Entry 1019@Component 1020struct StickyNestedScroll { 1021 @State arr: number[] = [] 1022 1023 @Styles 1024 listCard() { 1025 .backgroundColor(Color.White) 1026 .height(72) 1027 .width("100%") 1028 .borderRadius(12) 1029 } 1030 1031 build() { 1032 Scroll() { 1033 Column() { 1034 Text("Scroll Area") 1035 .width("100%") 1036 .height("40%") 1037 .backgroundColor('#0080DC') 1038 .textAlign(TextAlign.Center) 1039 Tabs({ barPosition: BarPosition.Start }) { 1040 TabContent() { 1041 List({ space: 10 }) { 1042 ForEach(this.arr, (item: number) => { 1043 ListItem() { 1044 Text("item" + item) 1045 .fontSize(16) 1046 }.listCard() 1047 }, (item: string) => item) 1048 }.width("100%") 1049 .edgeEffect(EdgeEffect.Spring) 1050 .nestedScroll({ 1051 scrollForward: NestedScrollMode.PARENT_FIRST, 1052 scrollBackward: NestedScrollMode.SELF_FIRST 1053 }) 1054 }.tabBar("Tab1") 1055 1056 TabContent() { 1057 }.tabBar("Tab2") 1058 } 1059 .vertical(false) 1060 .height("100%") 1061 }.width("100%") 1062 } 1063 .edgeEffect(EdgeEffect.Spring) 1064 .friction(0.6) 1065 .backgroundColor('#DCDCDC') 1066 .scrollBar(BarState.Off) 1067 .width('100%') 1068 .height('100%') 1069 } 1070 1071 aboutToAppear() { 1072 for (let i = 0; i < 30; i++) { 1073 this.arr.push(i) 1074 } 1075 } 1076} 1077``` 1078 1079### Example 4: Implementing Nested Scrolling with Parent-to-Child Scrolling Propagation 1080This example demonstrates how to propagate scrolling from a parent component to a child component using the **enableScrollInteraction** attribute and the **onScrollFrameBegin** event. 1081```ts 1082@Entry 1083@Component 1084struct NestedScroll { 1085 private headerHeight: number = 0; 1086 private arr: number[] = [] 1087 private scrollerForParent: Scroller = new Scroller() 1088 private scrollerForChild: Scroller = new Scroller() 1089 1090 aboutToAppear(): void { 1091 for (let i = 0; i < 10; i++) { 1092 this.arr.push(i) 1093 } 1094 } 1095 1096 build() { 1097 Scroll(this.scrollerForParent) { 1098 Column() { 1099 Text("Scroll Area") 1100 .width("100%") 1101 .height("40%") 1102 .backgroundColor(0X330000FF) 1103 .fontSize(16) 1104 .textAlign(TextAlign.Center) 1105 .onClick(() => { 1106 this.scrollerForChild.scrollToIndex(5) 1107 }) 1108 .onSizeChange((oldValue: SizeOptions, newValue: SizeOptions) => { 1109 this.headerHeight = newValue.height! as number 1110 }) 1111 List({ space: 20, scroller: this.scrollerForChild }) { 1112 ForEach(this.arr, (item: number) => { 1113 ListItem() { 1114 Text("ListItem" + item) 1115 .width("100%") 1116 .height("100%") 1117 .borderRadius(15) 1118 .fontSize(16) 1119 .textAlign(TextAlign.Center) 1120 .backgroundColor(Color.White) 1121 }.width("100%").height(100) 1122 }, (item: string) => item) 1123 } 1124 .width("100%") 1125 .height("100%") 1126 .edgeEffect(EdgeEffect.None) 1127 .scrollBar(BarState.Off) 1128 .enableScrollInteraction(false) 1129 1130 Text("Scroll Area") 1131 .width("100%") 1132 .height("40%") 1133 .backgroundColor(0X330000FF) 1134 .fontSize(16) 1135 .textAlign(TextAlign.Center) 1136 } 1137 } 1138 .scrollBar(BarState.Off) 1139 .edgeEffect(EdgeEffect.Spring) 1140 .onScrollFrameBegin((offset: number, state: ScrollState) => { 1141 let retOffset = offset; 1142 let currOffset = this.scrollerForParent.currentOffset().yOffset; 1143 let newOffset = currOffset + offset; 1144 if (offset > 0) { 1145 if (this.scrollerForChild.isAtEnd()) { 1146 return { offsetRemain: offset } 1147 } 1148 if (newOffset > this.headerHeight) { 1149 retOffset = this.headerHeight - currOffset 1150 } 1151 this.scrollerForChild.scrollBy(0, offset - retOffset) 1152 } else { 1153 if (this.scrollerForChild.currentOffset().yOffset <= 0) { 1154 return { offsetRemain: offset } 1155 } 1156 if (newOffset < this.headerHeight) { 1157 retOffset = this.headerHeight - currOffset 1158 } 1159 this.scrollerForChild.scrollBy(0, offset - retOffset) 1160 } 1161 return { offsetRemain: retOffset } 1162 }) 1163 .width("100%") 1164 .height("100%") 1165 .backgroundColor(0xDCDCDC) 1166 } 1167} 1168``` 1169 1170### Example 5: Setting Scroll Snapping 1171This example shows how to set scroll snapping for a **Scroll** component. 1172```ts 1173@Entry 1174@Component 1175struct Index { 1176 scroller: Scroller = new Scroller; 1177 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] 1178 build() { 1179 Scroll(this.scroller) { 1180 Column() { 1181 ForEach(this.arr, (item: number) => { 1182 Text(item.toString()) 1183 .width('90%') 1184 .height(200) 1185 .backgroundColor(0xFFFFFF) 1186 .borderWidth(1) 1187 .borderColor(Color.Black) 1188 .borderRadius(15) 1189 .fontSize(16) 1190 .textAlign(TextAlign.Center) 1191 }, (item: string) => item) 1192 }.width('100%').backgroundColor(0xDCDCDC) 1193 } 1194 .backgroundColor(Color.Yellow) 1195 .height('100%') 1196 .edgeEffect(EdgeEffect.Spring) 1197 .scrollSnap({snapAlign:ScrollSnapAlign.START, snapPagination:400, enableSnapToStart:true, enableSnapToEnd:true}) 1198 } 1199} 1200``` 1201 1202 1203### Example 6: Obtaining the Index of a Child Component 1204This example demonstrates how to obtain the index of a child component in a **List** component. 1205 1206```ts 1207// xxx.ets 1208@Entry 1209@Component 1210struct ListExample { 1211 private arr: number[] = [] 1212 private scroller: ListScroller = new ListScroller() 1213 @State listSpace: number = 10 1214 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100) 1215 @State listIndex: number = -1 1216 @State mess:string = "null" 1217 @State itemBackgroundColorArr: boolean[] = [false] 1218 aboutToAppear(){ 1219 // Initialize the data source. 1220 for (let i = 0; i < 10; i++) { 1221 this.arr.push(i) 1222 } 1223 this.listChildrenSize.splice(0, 5, [100, 100, 100, 100, 100]) 1224 } 1225 build() { 1226 Column() { 1227 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1228 ForEach(this.arr, (item: number) => { 1229 ListItem() { 1230 Text('item-' + item) 1231 .height( item < 5 ? 100 : this.listChildrenSize.childDefaultSize) 1232 .width('90%') 1233 .fontSize(16) 1234 .textAlign(TextAlign.Center) 1235 .borderRadius(10) 1236 .backgroundColor( this.itemBackgroundColorArr[item] ? 0x68B4FF: 0xFFFFFF) 1237 } 1238 }, (item: string) => item) 1239 } 1240 .backgroundColor(Color.Gray) 1241 .layoutWeight(1) 1242 .scrollBar(BarState.On) 1243 .childrenMainSize(this.listChildrenSize) 1244 .alignListItem(ListItemAlign.Center) 1245 .gesture( 1246 PanGesture() 1247 .onActionUpdate((event: GestureEvent) => { 1248 if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) { 1249 this.listIndex = this.scroller.getItemIndex(event.fingerList[0].localX, event.fingerList[0].localY) 1250 this.itemBackgroundColorArr[this.listIndex] = true; 1251 } 1252 }) 1253 ) 1254 .gesture( 1255 TapGesture({ count: 1 }) 1256 .onAction((event: GestureEvent) => { 1257 if (event) { 1258 this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length); 1259 } 1260 }) 1261 ) 1262 1263 Text('You are currently at index '+ this.listIndex) 1264 .fontColor(Color.Red) 1265 .height(50) 1266 } 1267 } 1268} 1269``` 1270 1271 1272 1273### Example 7: Setting Edge Fading 1274This example demonstrates how to implement a **Scroll** component with an edge fading effect and set the length of the fading edge. 1275 1276```ts 1277// xxx.ets 1278import { LengthMetrics } from '@kit.ArkUI' 1279@Entry 1280@Component 1281struct ScrollExample { 1282 scroller: Scroller = new Scroller() 1283 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] 1284 1285 build() { 1286 Stack({ alignContent: Alignment.TopStart }) { 1287 Scroll(this.scroller) { 1288 Column() { 1289 ForEach(this.arr, (item: number) => { 1290 Text(item.toString()) 1291 .width('90%') 1292 .height(150) 1293 .backgroundColor(0xFFFFFF) 1294 .borderRadius(15) 1295 .fontSize(16) 1296 .textAlign(TextAlign.Center) 1297 .margin({ top: 10 }) 1298 }, (item: string) => item) 1299 }.width('100%') 1300 } 1301 .fadingEdge(true,{fadingEdgeLength:LengthMetrics.vp(80)}) 1302 1303 1304 1305 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 1306 } 1307} 1308``` 1309 1310 1311
