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