1# Scrollable Component Common APIs
2
3The common attributes and events for scrollable components currently only support the [List](ts-container-list.md), [Grid](ts-container-grid.md), [Scroll](ts-container-scroll.md), and [WaterFlow](ts-container-waterflow.md) components.
4
5>  **NOTE**
6>
7>  The initial APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9## Attributes
10
11### scrollBar<sup>11+</sup>
12
13scrollBar(barState: BarState): T
14
15Sets the scrollbar state.
16
17**Atomic service API**: This API can be used in atomic services since API version 11.
18
19**System capability**: SystemCapability.ArkUI.ArkUI.Full
20
21**Parameters**
22
23| Name  | Type                                     | Mandatory| Description                                  |
24| -------- | ----------------------------------------- | ---- | -------------------------------------- |
25| barState | [BarState](ts-appendix-enums.md#barstate) | Yes  | Scrollbar state.<br>Default value: **BarState.Auto** for the **List**, **Grid**, and **Scroll** components and **BarState.Off** for the **WaterFlow** component|
26
27### scrollBarColor<sup>11+</sup>
28
29scrollBarColor(color: Color | number | string): T
30
31Sets the scrollbar color.
32
33**Atomic service API**: This API can be used in atomic services since API version 11.
34
35**System capability**: SystemCapability.ArkUI.ArkUI.Full
36
37**Parameters**
38
39| Name| Type                                                        | Mandatory| Description          |
40| ------ | ------------------------------------------------------------ | ---- | -------------- |
41| color  | string \| number \| [Color](ts-appendix-enums.md#color) | Yes  | Scrollbar color.<br>Default value: **'\#182431'** (40% opacity)|
42
43### scrollBarWidth<sup>11+</sup>
44
45scrollBarWidth(value: number | string): T
46
47Sets 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 scrollable component on the main axis, the scrollbar reverts to the default width.
48
49**Atomic service API**: This API can be used in atomic services since API version 11.
50
51**System capability**: SystemCapability.ArkUI.ArkUI.Full
52
53**Parameters**
54
55| Name| Type                      | Mandatory| Description                                     |
56| ------ | -------------------------- | ---- | ----------------------------------------- |
57| value  | string \| number | Yes  | Scrollbar width.<br>Default value: **4**<br>Unit: vp|
58
59### edgeEffect<sup>11+</sup>
60
61edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions): T
62
63Sets the effect used when the scroll boundary is reached.
64
65**Atomic service API**: This API can be used in atomic services since API version 11.
66
67**System capability**: SystemCapability.ArkUI.ArkUI.Full
68
69**Parameters**
70
71| Name               | Type                                             | Mandatory| Description                                                        |
72| --------------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
73| 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** for the **Grid**, **Scroll**, and **WaterFlow** components and **EdgeEffect.Spring** for the **List** component|
74| options | [EdgeEffectOptions](#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:<br>**{ alwaysEnabled: false }** for the **List**, **Grid**, and **WaterFlow** components, and **{ alwaysEnabled: true }** for the **Scroll** component|
75
76### nestedScroll<sup>11+</sup>
77
78nestedScroll(value: NestedScrollOptions): T
79
80Sets 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.
81
82**Atomic service API**: This API can be used in atomic services since API version 11.
83
84**System capability**: SystemCapability.ArkUI.ArkUI.Full
85
86**Parameters**
87
88| Name| Type                                                 | Mandatory| Description          |
89| ------ | ----------------------------------------------------- | ---- | -------------- |
90| value  | [NestedScrollOptions](#nestedscrolloptions10) | Yes  | Nested scrolling options.|
91
92### enableScrollInteraction<sup>11+</sup>
93
94enableScrollInteraction(value: boolean): T
95
96Sets 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.
97
98**Atomic service API**: This API can be used in atomic services since API version 11.
99
100**System capability**: SystemCapability.ArkUI.ArkUI.Full
101
102**Parameters**
103
104| Name| Type   | Mandatory| Description                               |
105| ------ | ------- | ---- | ----------------------------------- |
106| value  | boolean | Yes  | Whether to support scroll gestures.<br>Default value: **true**|
107
108### friction<sup>11+</sup>
109
110friction(value: number | Resource): T
111
112Sets 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.
113
114**Atomic service API**: This API can be used in atomic services since API version 11.
115
116**System capability**: SystemCapability.ArkUI.ArkUI.Full
117
118**Parameters**
119
120| Name| Type                                                | Mandatory| Description                                                     |
121| ------ | ---------------------------------------------------- | ---- | --------------------------------------------------------- |
122| 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**.|
123
124### flingSpeedLimit<sup>11+</sup>
125
126flingSpeedLimit(speedLimit: number): T
127
128Sets the maximum starting fling speed when the fling animation starts. If this attribute is set to a value less than or equal to 0, the default value is used.
129
130**Atomic service API**: This API can be used in atomic services since API version 11.
131
132**System capability**: SystemCapability.ArkUI.ArkUI.Full
133
134**Parameters**
135
136| Name    | Type  | Mandatory| Description                           |
137| ---------- | ------ | ---- | ------------------------------- |
138| speedLimit | number | Yes  | Maximum starting fling speed when the fling animation starts.<br>Default value: **12000**<br>Unit: vp/s|
139
140
141## Events
142
143### onReachStart<sup>11+</sup>
144
145onReachStart(event: () => void): T
146
147Triggered when the scrollable component reaches the start position.
148
149This event is triggered once when the component is initialized and once when the component scrolls to the start position. If the edge effect is set to a spring effect, this event is triggered once when the swipe passes the start position, and triggered again when the swipe rebounds back to the start position.
150
151**Atomic service API**: This API can be used in atomic services since API version 11.
152
153**System capability**: SystemCapability.ArkUI.ArkUI.Full
154
155### onReachEnd<sup>11+</sup>
156
157onReachEnd(event: () => void): T
158
159Triggered when the scrollable component reaches the end position.
160
161If the edge effect is set to a spring effect, this event is triggered once when the swipe passes the end position, and triggered again when the swipe rebounds back to the end position.
162
163**Atomic service API**: This API can be used in atomic services since API version 11.
164
165**System capability**: SystemCapability.ArkUI.ArkUI.Full
166
167### onScrollStart<sup>11+</sup>
168
169onScrollStart(event: () => void): T
170
171Triggered when the scrollable component starts scrolling initiated by the user's finger dragging the component or its scrollbar. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](ts-container-scroll.md#scroller) starts.
172
173**NOTE**
174
1751. This event is triggered when the scrollable component starts to scroll, and it supports various input methods that can initiate the scroll, including keyboard and mouse operations.
176
1772. This event is triggered when the controller API is called, accompanied by a transition animation.
178
179**Atomic service API**: This API can be used in atomic services since API version 11.
180
181**System capability**: SystemCapability.ArkUI.ArkUI.Full
182
183### onScrollStop<sup>11+</sup>
184
185onScrollStop(event: () => void): T
186
187Triggered 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](ts-container-scroll.md#scroller) stops.
188
189**NOTE**
190
1911. The event is triggered when the scrollable component stops scrolling, and it supports various input methods that can initiate the scroll, including keyboard and mouse operations.
192
1932. This event is triggered when the controller API is called, accompanied by a transition animation.
194
195**Atomic service API**: This API can be used in atomic services since API version 11.
196
197**System capability**: SystemCapability.ArkUI.ArkUI.Full
198
199### onWillScroll<sup>12+</sup> 
200
201onWillScroll(handler: Optional&lt;OnWillScrollCallback&gt;): T
202
203Triggered when the scrollable component is about to scroll.
204
205The 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 scrollable component through the return value of this callback.
206
207**Atomic service API**: This API can be used in atomic services since API version 12.
208
209**System capability**: SystemCapability.ArkUI.ArkUI.Full
210
211**Parameters**
212
213| Name| Type| Mandatory| Description|
214| ------ | ------ | ------ | ------|
215| handler | Optional&lt;[OnWillScrollCallback](#onwillscrollcallback12)&gt; | Yes| Callback triggered when the scrollable component is about to scroll.|
216
217> **NOTE**
218> 
219> When **ScrollEdge** and **ScrollToIndex** that does not involve animation is called, **onWillScroll** is not invoked.
220
221
222### onDidScroll<sup>12+</sup> 
223
224onDidScroll(handler: OnScrollCallback): T
225
226Triggered when the scrollable component scrolls. The return value is the offset amount by which the list has scrolled and the current scroll state.
227
228**Widget capability**: This API can be used in ArkTS widgets since API version 12.
229
230**Atomic service API**: This API can be used in atomic services since API version 12.
231
232**System capability**: SystemCapability.ArkUI.ArkUI.Full
233
234**Parameters**
235
236| Name| Type| Mandatory| Description|
237| ------ | ------ | ------ | ------|
238| handler | [OnScrollCallback](#onscrollcallback12) | Yes| Callback triggered when the scrollable component scrolls.|
239
240### onScroll<sup>(deprecated)</sup>
241
242onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void): T
243
244Triggered when the scrollable component scrolls.
245
246This API is supported since API version 11.
247
248This API is deprecated since API version 12. You are advised to use [onDidScroll](#ondidscroll12) instead.
249
250**Atomic service API**: This API can be used in atomic services since API version 11.
251
252**System capability**: SystemCapability.ArkUI.ArkUI.Full
253
254**Parameters**
255
256| Name| Type| Mandatory| Description|
257| ------ | ------ | ------ | ------|
258| scrollOffset | number | Yes| Scroll offset of each frame. The offset is positive when the scrollable component is scrolled up and negative when it is scrolled down.<br>Unit: vp|
259| scrollState | [ScrollState](ts-container-list.md#scrollstate)| Yes| Current scroll state.|
260
261## ItemDragInfo
262
263**Atomic service API**: This API can be used in atomic services since API version 11.
264
265**System capability**: SystemCapability.ArkUI.ArkUI.Full
266
267| Name        | Type        |   Description        |
268| ---------- | ---------- | ---------- |
269| x | number |  X coordinate of the dragged item, in vp.   |
270| y | number |  Y coordinate of the dragged item, in vp.   |
271
272## NestedScrollOptions<sup>10+</sup>
273
274**Atomic service API**: This API can be used in atomic services since API version 11.
275
276**System capability**: SystemCapability.ArkUI.ArkUI.Full
277
278| Name  | Type | Mandatory| Description             |
279| ----- | ------ | ------ | ----------------- |
280| scrollForward | [NestedScrollMode](ts-appendix-enums.md#nestedscrollmode10) | Yes| Nested scrolling options when the scrollable component scrolls forward.|
281| scrollBackward | [NestedScrollMode](ts-appendix-enums.md#nestedscrollmode10) | Yes| Nested scrolling options when the scrollable component scrolls backward.|
282
283## EdgeEffectOptions<sup>11+</sup>
284
285**Atomic service API**: This API can be used in atomic services since API version 12.
286
287**System capability**: SystemCapability.ArkUI.ArkUI.Full
288
289| Name  | Type | Mandatory| Description             |
290| ----- | ------| ------- | ----------------- |
291| alwaysEnabled | boolean | Yes| Whether to enable the scroll effect when the component content is smaller than the component itself.|
292
293## OnWillScrollCallback<sup>12+</sup>
294
295type OnWillScrollCallback = (scrollOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | ScrollResult
296
297Callback triggered when the scrollable component is about to scroll.
298
299**Atomic service API**: This API can be used in atomic services since API version 12.
300
301**System capability**: SystemCapability.ArkUI.ArkUI.Full
302
303**Parameters**
304
305| Name| Type| Mandatory| Description|
306| ------ | ------ | ------ | ------|
307| scrollOffset | number | Yes| Scroll offset of each frame. The offset is positive when the scrollable component is scrolled up and negative when it is scrolled down.<br>Unit: vp|
308| scrollState | [ScrollState](ts-container-list.md#scrollstate)| Yes| Current scroll state.|
309| scrollSource | [ScrollSource](ts-appendix-enums.md#scrollsource12) | Yes| Source of the current scrolling operation.|
310
311**Return value**
312
313| Type                         | Description                                 |
314| ----------------------------- | ------------------------------------ |
315| void \| [ScrollResult](#scrollresult12) |  Returns a **ScrollResult** object if the scrollable component scrolls by the offset specified by you; returns no **ScrollResult** object if the component scrolls by the offset specified by **scrollOffset** in the callback.|
316
317## OnScrollCallback<sup>12+</sup>
318
319type OnScrollCallback = (scrollOffset: number, scrollState: ScrollState) => void
320
321Callback triggered when the scrollable component scrolls.
322
323**Widget capability**: This API can be used in ArkTS widgets since API version 12.
324
325**Atomic service API**: This API can be used in atomic services since API version 12.
326
327**System capability**: SystemCapability.ArkUI.ArkUI.Full
328
329| Name| Type| Mandatory| Description|
330| ------ | ------ | ------ | ------|
331| scrollOffset | number | Yes| Scroll offset of each frame. The offset is positive when the scrollable component is scrolled up and negative when it is scrolled down.<br>Unit: vp|
332| scrollState | [ScrollState](ts-container-list.md#scrollstate)| Yes| Current scroll state.|
333
334## ScrollResult<sup>12+</sup>
335
336**Atomic service API**: This API can be used in atomic services since API version 12.
337
338**System capability**: SystemCapability.ArkUI.ArkUI.Full
339
340| Name| Type| Mandatory| Description|
341| ------ | ------ | ------ | ------|
342| offsetRemain | number | Yes| Amount by which the component is about to be scrolled, in vp.|
343
344## ChildrenMainSize<sup>12+</sup>
345
346Provides the size information of the child components of the **List** or **ListItemGroup** component along the main axis. This object only supports one-to-one binding to the **List** or **ListItemGroup** component.
347
348**Atomic service API**: This API can be used in atomic services since API version 12.
349
350### constructor<sup>12+</sup>
351
352constructor(childDefaultSize: number): void
353
354A constructor used to create a **ChildrenMainSize** object.
355
356**Atomic service API**: This API can be used in atomic services since API version 12.
357
358**System capability**: SystemCapability.ArkUI.ArkUI.Full
359
360**Parameters**
361
362| Name  | Type                           | Mandatory  | Description                  |
363| ---- | ----------------------------- | ---- | -------------------- |
364| childDefaultSize | number | Yes   | Default size of the child component along the main axis.<br>Unit: vp<br>**NOTE**<br>The value must be a finite non-negative number; otherwise, an exception will be thrown.|
365
366
367### childDefaultSize<sup>12+</sup>
368
369set childDefaultSize(value: number): void
370
371Sets the default size of the child component along the main axis.
372
373**Atomic service API**: This API can be used in atomic services since API version 12.
374
375**System capability**: SystemCapability.ArkUI.ArkUI.Full
376
377**Parameters**
378
379| Name  | Type                           | Mandatory  | Description                  |
380| ---- | ----------------------------- | ---- | -------------------- |
381| value | number | Yes   | Default size of the child component along the main axis.<br>Unit: vp<br>**NOTE**<br>The value must be a finite non-negative number; otherwise, an exception will be thrown.|
382
383**Error codes**
384
385For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md).
386
387| ID| Error Message|
388| ------- | -------- |
389| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
390
391get childDefaultSize(): number
392
393Obtains the default size of the child component along the main axis.
394
395**Atomic service API**: This API can be used in atomic services since API version 12.
396
397**System capability**: SystemCapability.ArkUI.ArkUI.Full
398
399**Return value**
400
401| Type                                                        | Description                                                        |
402| ------------------------------------------------------------ | ------------------------------------------------------------ |
403| number | Default size of the child component along the main axis.<br>Unit: vp|
404
405### splice<sup>12+</sup>
406
407splice(start: number, deleteCount?: number, childrenSize?: Array\<number>): void
408
409Performs batch operations to add, delete, or modify the size information of child components along the main axis.
410
411**Atomic service API**: This API can be used in atomic services since API version 12.
412
413**System capability**: SystemCapability.ArkUI.ArkUI.Full
414
415**Parameters**
416
417| Name  | Type                           | Mandatory  | Description                  |
418| ---- | ----------------------------- | ---- | -------------------- |
419| start | number | Yes   | Index starting from 0, which indicates the position at which to begin modifying the size information of child components along the main axis.<br>**NOTE**<br>1. The value must be a finite non-negative number; otherwise, an exception will be thrown.<br>2. Non-integer values are truncated to the nearest integer.<br>3. Values exceeding the maximum index do not take effect.|
420| deleteCount | number | No   | Number of size information entries to be deleted starting from the **start** position.<br>**NOTE**<br>1.  The value must be a finite non-negative number; otherwise, it will be treated as **0**.<br>2. Non-integer values are truncated to the nearest integer.<br>3. The result of (start + deleteCount - 1) can exceed the maximum index, which will delete all size information of child components starting from the **start** position.|
421| childrenSize | Array\<number > | No   | Size information of all child components to be inserted, starting from the **start** position.<br>Unit for each value in the array: vp<br>**NOTE**<br>1. If the values in the array are finite non-negative number, they are considered specified sizes and will not change with the default size.<br>2. 2. If the values in the array are not finite non-negative number, they will be treated as the default size and will change with the default size. |
422
423
424**Error codes**
425
426For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md).
427
428| ID| Error Message|
429| ------- | -------- |
430| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
431
432
433> **NOTE**
434>
435> - If only the **start** parameter is used, it means to delete the size information of the child components starting from the **start** position and beyond.
436> - If only the **start** and **deleteCount** parameters are used, it means to delete the **deleteCount**-specified number of size information entries starting from the **start** position. This is generally used when you remove child components.
437> - If all three parameters are used, it means to delete the **deleteCount**-specified number of size information entries starting from the **start** position, and then insert all the size information from **childrenSize** at the **start** position. This is generally used when you add child components or batch update the main axis size of child components. If it's only about adding child components, **deleteCount** should be **0**, and the number of elements in **childrenSize** should be equal to the number of child components being added. If it's only about batch updating the main axis size of child components, the number of elements in **childrenSize** should be equal to **deleteCount**, which is the number of updates being made.
438> - If you want to notify that the size of a child component should be the default size, the corresponding value in **childrenSize** should not be given as a finite non-negative value, but rather as **NaN**, any negative value, or any other value that can be processed as the default size.
439
440### update<sup>12+</sup>
441
442update(index: number, childSize: number): void
443
444Updates the main axis size information of the child component corresponding to the specified index.
445
446**Atomic service API**: This API can be used in atomic services since API version 12.
447
448**System capability**: SystemCapability.ArkUI.ArkUI.Full
449
450**Parameters**
451
452| Name  | Type                           | Mandatory  | Description                  |
453| ---- | ----------------------------- | ---- | -------------------- |
454| index | number | Yes   | Index starting from 0, which indicates the position at which to begin modifying the size information of child components along the main axis.<br>**NOTE**<br>1. The value must be a finite non-negative number; otherwise, an exception will be thrown.<br>2. Non-integer values are truncated to the nearest integer.<br>3. Values exceeding the maximum index do not take effect.|
455| childSize | number | Yes   | Size to be updated to.<br>Unit: vp<br>**NOTE**<br>1. If the value is a finite non-negative number, it is considered a specified size and will not change with the default size.<br>2. 2. If the value is not a finite non-negative number, it will be processed as the default size and will change with the default size. |
456
457**Error codes**
458
459For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md).
460
461| ID| Error Message|
462| ------- | -------- |
463| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.   |
464