1# List 2 3The **List** component provides a list container that presents a series of list items arranged in a column with the same width. It supports presentations of the same type of data in a multiple and coherent row style, for example, images or text. 4 5> **NOTE** 6> 7> - This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> - By default, this component can produce a bounce effect only when there is more than one screen of content. To produce a bounce effect when there is less than one screen of content, use the **options** parameter of the **edgeEffect** attribute. 10> 11> - The default value of the universal attribute [clip](ts-universal-attributes-sharp-clipping.md) is **true** for the **List** component. 12> 13> - To enable the editable mode for a list, the following conditions must be met: (This feature is deprecated since API version 9.) 14> 15> - **editMode** is set to **true**. 16> 17> - The list is bound to the **onItemDelete** event and the event returns **true** in the event callback. 18> 19> - The **editable** attribute of **ListItem** is set to **true**. 20> 21> - To enable list item dragging, the following conditions must be met: 22> 23> - **editMode** is set to **true**. (This is not required since API version 9.) 24> 25> - The list item is bound to the **onDragStart** event and the event returns a floating UI during event callback. 26 27 28## Child Components 29 30Only the [ListItem](ts-container-listitem.md) and [ListItemGroup](ts-container-listitemgroup.md) child components are allowed, with support for [if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md), and [Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md) rendering control. 31 32> **NOTE** 33> 34> Below are the rules for calculating the indexes of the child components of **List**: 35> 36> The index increases in ascending order of child components. 37> 38> In the **if/else** statement, only the child components for which the condition evaluates to true participate in the index calculation. 39> 40> In the **ForEach**, **LazyForEach**, or **Repeat** statement, the indexes of all expanded subnodes are calculated. 41> 42> After changes occur in [if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md), or [Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md), the indexes of the child nodes are updated. 43> 44> Each **ListItemGroup** component is taken as a whole and assigned an index, and the indexes of the list items within are not included in the index calculation. 45> 46> Child components of **List** whose **visibility** attribute is set to **Hidden** or **None** are included in the index calculation. 47> 48> Child components of **List** whose **visibility** attribute is set to **None** are not displayed, but the spacing above and below them still takes effect. 49 50 51## APIs 52 53List(value?:{space?: number | string, initialIndex?: number, scroller?: Scroller}) 54 55**Widget capability**: This API can be used in ArkTS widgets since API version 9. 56 57**Atomic service API**: This API can be used in atomic services since API version 11. 58 59**System capability**: SystemCapability.ArkUI.ArkUI.Full 60 61**Parameters** 62 63| Name | Type| Mandatory| Description| 64| ------ | ---- | ---- | ---- | 65| space | number \| string | No | Spacing between list items along the main axis.<br>Default value: **0**<br>If the parameter type is number, the unit is vp.<br>**NOTE**<br>If this parameter is set to a negative number or a value greater than or equal to the length of the list content area, the default value is used.<br>If this parameter is set to a value less than the width of the list divider, the width of the list divider is used as the spacing.| 66| initialIndex | number | No | Index of the item to be displayed at the start when the list is initially loaded.<br>Default value: **0**<br>**NOTE**<br>If the set value is a negative number or is greater than the index of the last item in the list, the value is invalid. In this case, the default value will be used.| 67| scroller | [Scroller](ts-container-scroll.md#scroller) | No | Scroller, which can be bound to scrollable components.<br>**NOTE**<br>The scroller cannot be bound to other scrollable components.| 68 69## Attributes 70 71In 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. 72 73### listDirection 74 75listDirection(value: Axis) 76 77Sets the direction in which the list items are arranged. 78 79**Widget capability**: This API can be used in ArkTS widgets since API version 9. 80 81**Atomic service API**: This API can be used in atomic services since API version 11. 82 83**System capability**: SystemCapability.ArkUI.ArkUI.Full 84 85**Parameters** 86 87| Name| Type | Mandatory| Description | 88| ------ | --------------------------------- | ---- | ------------------------------------------ | 89| value | [Axis](ts-appendix-enums.md#axis) | Yes | Direction in which the list items are arranged.<br>Default value: **Axis.Vertical**| 90 91### divider 92 93divider(value: {strokeWidth: Length; color?: ResourceColor; startMargin?: Length; endMargin?: Length;} | null,) 94 95Sets the style of the divider for the list items. By default, there is no divider. 96 97If **endMargin** and **startMargin** add up to a value that exceeds the column width, they will be set to **0**. 98 99**strokeWidth**, **startMargin**, and **endMargin** cannot be set in percentage. 100 101The divider is drawn between list items along the main axis, and not above the first list item and below the last list item. 102 103In multi-column mode, the value of **startMargin** is calculated from the start edge of the cross axis of each column. In other cases, it is calculated from the start edge of the cross axis of the list. 104 105When a list item has [polymorphic styles](ts-universal-attributes-polymorphic-style.md) applied, the dividers above and below the pressed child component are not rendered. 106 107**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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 | {<br>strokeWidth: [Length](ts-types.md#length),<br>color?:[ResourceColor](ts-types.md#resourcecolor),<br>startMargin?: [Length](ts-types.md#length),<br>endMargin?: [Length](ts-types.md#length)<br>} \| null | Yes | Style of the divider for the list items.<br>- **strokeWidth**: stroke width of the divider.<br>- **color**: color of the divider.<br>Default value: **0x08000000**<br>- **startMargin**: distance between the divider and the start edge of the list.<br>Default value: **0**, in vp<br>- **endMargin**: distance between the divider and the end edge of the list.<br>Default value: **0**, in vp| 118 119### scrollBar 120 121scrollBar(value: BarState) 122 123Sets the scrollbar state. 124 125**Widget capability**: This API can be used in ArkTS widgets since API version 9. 126 127**Atomic service API**: This API can be used in atomic services since API version 11. 128 129**System capability**: SystemCapability.ArkUI.ArkUI.Full 130 131**Parameters** 132 133| Name| Type | Mandatory| Description | 134| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 135| value | [BarState](ts-appendix-enums.md#barstate) | Yes | Scrollbar state.<br>Default value: **BarState.Auto**<br>**NOTE**<br>In API version 9 and earlier versions, the default value is **BarState.Off**. Since API version 10, the default value is **BarState.Auto**.| 136 137### cachedCount 138 139cachedCount(value: number) 140 141Sets the number of list items or list item groups to be preloaded (cached). In a lazy loading scenario, only the content equivalent to **cachedCount** outside the visible area of the list is preloaded. In a non-lazy loading scenario, all items are loaded at once. For both lazy and non-lazy loading, only the content within the list display area plus the content equivalent to **cachedCount** outside the display area is laid out. <!--Del-->For details, see [Minimizing White Blocks During Swiping](../../../performance/arkts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).<!--DelEnd--> 142 143When **cachedCount** is set for a list, the system preloads and lays out the **cachedCount**-specified number of rows of list items both above and below the currently visible area of the list. When calculating the number of rows for list items, the system takes into account the number of rows from the list items within a list item group. If a list item group does not contain any list items, then the entire list item group is counted as one row. 144 145When a list is nested with **LazyForEach**, and within **LazyForEach** there is a list item group, **LazyForEach** will create **cachedCount**-specified number of list item groups both above and below the currently visible area of the list. 146 147**Widget capability**: This API can be used in ArkTS widgets since API version 9. 148 149**Atomic service API**: This API can be used in atomic services since API version 11. 150 151**System capability**: SystemCapability.ArkUI.ArkUI.Full 152 153**Parameters** 154 155| Name| Type | Mandatory| Description | 156| ------ | ------ | ---- | -------------------------------------------------- | 157| value | number | Yes | Number of list items or list item groups to be preloaded (cached).<br>Default value: **1**<br>Value range: [0, +∞)| 158 159### cachedCount<sup>14+</sup> 160 161cachedCount(count: number, show: boolean) 162 163Sets the number of list items or list item groups to be cached (preloaded) and specifies whether to display the preloaded nodes. 164 165When **cachedCount** is set for the list, the system preloads and lays out the **cachedCount**-specified number of rows of list items both above and below the currently visible area of the list. When calculating the number of rows for list items, the system takes into account the number of rows from the list items within a list item group. If a list item group does not contain any list items, then the entire list item group is counted as one row. This attribute can be combined with the [clip](ts-universal-attributes-sharp-clipping.md#clip12) or [content clipping](ts-container-scrollable-common.md#clipcontent14) attributes to display the preloaded nodes. 166 167**Widget capability**: This API can be used in ArkTS widgets since API version 14. 168 169**Atomic service API**: This API can be used in atomic services since API version 14. 170 171**System capability**: SystemCapability.ArkUI.ArkUI.Full 172 173**Parameters** 174 175| Name| Type | Mandatory| Description | 176| ------ | ------ | ---- | -------------------------------------- | 177| count | number | Yes | Number of list items to be preloaded.<br>Default value: **1**<br>Value range: [0, +∞)| 178| show | boolean | Yes | Whether to display the preloaded list items.<br> Default value: **false**| 179 180### editMode<sup>(deprecated)</sup> 181 182editMode(value: boolean) 183 184Sets whether to enable edit mode. For details about how to delete selected list items, see [Example 3](#example-3-setting-the-editable-mode). 185 186This API is deprecated since API version 9. There is no substitute API. 187 188**System capability**: SystemCapability.ArkUI.ArkUI.Full 189 190**Parameters** 191 192| Name| Type | Mandatory| Description | 193| ------ | ------ | ---- | -------------------------------------------------- | 194| value | boolean | Yes | Whether to enable edit mode.<br>Default value: **false**| 195 196### edgeEffect 197 198edgeEffect(value: EdgeEffect, options?: EdgeEffectOptions) 199 200Sets the effect used when the scroll boundary is reached. 201 202**Widget capability**: This API can be used in ArkTS widgets since API version 9. 203 204**Atomic service API**: This API can be used in atomic services since API version 11. 205 206**System capability**: SystemCapability.ArkUI.ArkUI.Full 207 208**Parameters** 209 210| Name | Type | Mandatory| Description | 211| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 212| value | [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.Spring**| 213| 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: false }**| 214 215### chainAnimation 216 217chainAnimation(value: boolean) 218 219Sets whether to enable chained animations, which provide a visually connected, or "chained," effect when the list is scrolled or its top or bottom edge is dragged. 220 221With chained animations enabled, list items are spaced apart by a certain distance, which is 20 vp by default and can be adjusted as needed using the **space** parameter of the **List** component. During scrolling, the list item being actively dragged by the user's finger is considered the active object, while adjacent items are driven objects. The active object triggers a physics-based spring animation that affects the driven objects. 222 223When chained animations are active, the list divider is not displayed. 224 225For chained animations to work properly, the following conditions must be met: 226 227 1. The list is configured to use a spring effect when its scroll boundary is reached. 228 229 2. The list is not in multi-column mode. 230 231**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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**Parameters** 238 239| Name| Type | Mandatory| Description | 240| ------ | ------- | ---- | ------------------------------------------------------------ | 241| value | boolean | Yes | Whether to enable chained animations.<br>**false** (default): Chained animations are disabled.<br>**true**: Chained animations are enabled. | 242 243### multiSelectable<sup>8+</sup> 244 245multiSelectable(value: boolean) 246 247Sets whether to enable multiselect. 248 249**Widget capability**: This API can be used in ArkTS widgets since API version 9. 250 251**Atomic service API**: This API can be used in atomic services since API version 11. 252 253**System capability**: SystemCapability.ArkUI.ArkUI.Full 254 255**Parameters** 256 257| Name| Type | Mandatory| Description | 258| ------ | ------- | ---- | ------------------------------------------------------------ | 259| value | boolean | Yes | Whether to enable multiselect.<br>**false** (default): Multiselect is disabled.<br>**true**: Multiselect is enabled. | 260 261### lanes<sup>9+</sup> 262 263lanes(value: number | LengthConstrain, gutter?: Dimension) 264 265Sets the number of columns or rows in the list. If the value is set to the **gutter** type, it indicates the gap between columns. It takes effect when the number of columns is greater than 1. 266 267The rules are as follows: 268 269- If the value is set to a number, the column width is calculated by dividing the cross-axis width of the **List** component by the specified number. 270- If the value is set to {minLength, maxLength}, the number of columns is adjusted adaptively based on the width of the **List** component, ensuring that the width respects the {minLength, maxLength} constraints during adaptation. The **minLength** constraint is prioritized. 271- If the value is set to {minLength, maxLength}, and the cross-axis width constraint of the parent component is infinite, the parent component is arranged by column, and the column width is calculated based on the largest list item in the display area. 272- Each list item group occupies one row in multi-column mode. Its child list items are arranged based on the **lanes** attribute of the list. 273- If the value is set to {minLength, maxLength}, the number of columns is calculated based on the cross-axis width of the list item group. If the cross-axis width of the list item group is different from that of the list, the number of columns in the list item group may be different from that in the list. 274 275**Widget capability**: This API can be used in ArkTS widgets since API version 9. 276 277**Atomic service API**: This API can be used in atomic services since API version 11. 278 279**System capability**: SystemCapability.ArkUI.ArkUI.Full 280 281**Parameters** 282 283| Name | Type | Mandatory| Description | 284| -------------------- | ------------------------------------------------------------ | ---- | ---------------------------------------- | 285| value | number \| [LengthConstrain](ts-types.md#lengthconstrain) | Yes | Number of columns or rows in the list.<br>Default value: **1**| 286| gutter<sup>10+</sup> | [Dimension](ts-types.md#dimension10) | No | Gap between columns.<br>Default value: **0** | 287 288### alignListItem<sup>9+</sup> 289 290alignListItem(value: ListItemAlign) 291 292Alignment mode of list items along the cross axis when the cross-axis width of the list is greater than the cross-axis width of list items multiplied by the value of **lanes**. 293 294**Widget capability**: This API can be used in ArkTS widgets since API version 9. 295 296**Atomic service API**: This API can be used in atomic services since API version 11. 297 298**System capability**: SystemCapability.ArkUI.ArkUI.Full 299 300**Parameters** 301 302| Name| Type | Mandatory| Description | 303| ------ | ---------------------------------------- | ---- | ------------------------------------------------------ | 304| value | [ListItemAlign](#listitemalign9) | Yes | Alignment mode of list items along the cross axis.<br>Default value: **ListItemAlign.Start**| 305 306### sticky<sup>9+</sup> 307 308sticky(value: StickyStyle) 309 310Sets whether to pin the header to the top or the footer to the bottom in the [list item group](ts-container-listitemgroup.md), if set. To support both the pin-to-top and pin-to-bottom features, set **sticky** to **StickyStyle.Header \| StickyStyle.Footer**. 311 312> **NOTE** 313> 314> Occasionally, after **sticky** is set, floating-point calculation precision may result in small gaps appearing during scrolling. To address this issue, you can apply the [pixelRound](ts-universal-attributes-pixelRound.md#pixelround) attribute to the current component, which rounds down the pixel values and help eliminate the gaps. 315 316**Widget capability**: This API can be used in ArkTS widgets since API version 9. 317 318**Atomic service API**: This API can be used in atomic services since API version 11. 319 320**System capability**: SystemCapability.ArkUI.ArkUI.Full 321 322**Parameters** 323 324| Name| Type | Mandatory| Description | 325| ------ | ------------------------------------ | ---- | ---------------------------------------------------------- | 326| value | [StickyStyle](#stickystyle9) | Yes | Whether to pin the header to the top or the footer to the bottom in the list item group.<br>Default value: **StickyStyle.None**| 327 328### scrollSnapAlign<sup>10+</sup> 329 330scrollSnapAlign(value: ScrollSnapAlign) 331 332Sets the alignment mode for the scroll snap position. 333 334This attribute is effective only when the heights of list items are the same. 335 336It does not take effect after scrolling by a touchpad or mouse device ends. 337 338**Atomic service API**: This API can be used in atomic services since API version 11. 339 340**System capability**: SystemCapability.ArkUI.ArkUI.Full 341 342**Parameters** 343 344| Name| Type | Mandatory| Description | 345| ------ | --------------------------------------------- | ---- | --------------------------------------------------------- | 346| value | [ScrollSnapAlign](#scrollsnapalign10) | Yes | Alignment mode of the scroll snap position.<br>Default value: **ScrollSnapAlign.NONE**| 347 348### enableScrollInteraction<sup>10+</sup> 349 350enableScrollInteraction(value: boolean) 351 352Sets 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. 353 354**Atomic service API**: This API can be used in atomic services since API version 11. 355 356**System capability**: SystemCapability.ArkUI.ArkUI.Full 357 358**Parameters** 359 360| Name| Type | Mandatory| Description | 361| ------ | ------- | ---- | ----------------------------------- | 362| value | boolean | Yes | Whether to support scroll gestures.<br>Default value: **true**| 363 364### nestedScroll<sup>10+</sup> 365 366nestedScroll(value: NestedScrollOptions) 367 368Sets 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. 369 370**Atomic service API**: This API can be used in atomic services since API version 11. 371 372**System capability**: SystemCapability.ArkUI.ArkUI.Full 373 374**Parameters** 375 376| Name| Type | Mandatory| Description | 377| ------ | ------------------------------------------------------------ | ---- | -------------- | 378| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10) | Yes | Nested scrolling options.| 379 380### friction<sup>10+</sup> 381 382friction(value: number | Resource) 383 384Sets 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. 385 386**Atomic service API**: This API can be used in atomic services since API version 11. 387 388**System capability**: SystemCapability.ArkUI.ArkUI.Full 389 390**Parameters** 391 392| Name| Type | Mandatory| Description | 393| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 394| 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**.| 395 396### contentStartOffset<sup>11+</sup> 397 398contentStartOffset(value: number) 399 400Sets the offset from the start of the list content to the boundary of the list display area. 401 402**Atomic service API**: This API can be used in atomic services since API version 12. 403 404**System capability**: SystemCapability.ArkUI.ArkUI.Full 405 406**Parameters** 407 408| Name| Type | Mandatory| Description | 409| ------ | ------ | ---- | ----------------------------------------------- | 410| value | number | Yes | Offset from the start of the list content to the boundary of the list display area.<br>Default value: **0**<br>Unit: vp| 411 412### contentEndOffset<sup>11+</sup> 413 414contentEndOffset(value: number) 415 416Sets the offset from the end of the list content to the boundary of the list display area. 417 418**Atomic service API**: This API can be used in atomic services since API version 12. 419 420**System capability**: SystemCapability.ArkUI.ArkUI.Full 421 422**Parameters** 423 424| Name| Type | Mandatory| Description | 425| ------ | ------ | ---- | --------------------------------------------- | 426| value | number | Yes | Offset from the end of the list content to the boundary of the list display area.<br>Default value: **0**<br>Unit: vp| 427 428### childrenMainSize<sup>12+</sup> 429 430childrenMainSize(value: ChildrenMainSize) 431 432Sets the size information of the child components of a **List** component along the main axis. 433 434**Atomic service API**: This API can be used in atomic services since API version 12. 435 436**System capability**: SystemCapability.ArkUI.ArkUI.Full 437 438**Parameters** 439 440| Name | Type | Mandatory| Description | 441| ---------- | ------ | ---- | ------------------------------- | 442| value | [ChildrenMainSize](ts-container-scrollable-common.md#childrenmainsize12) | Yes | 1. Purpose:<br>By providing a **ChildrenMainSize** object to the **List** component, it accurately conveys the size information of all child components along the main axis. This enables the **List** component to maintain an accurate scroll position even when child components have varying sizes on the main axis, when child components are added or removed, or when [scrollToIndex](ts-container-scroll.md#scrolltoindex) is used. This ensures that [scrollTo](ts-container-scroll.md#scrollto) can jump to an exact specified location, [currentOffset](ts-container-scroll.md#currentoffset) can obtain the current exact scroll position, and the built-in scrollbar can move smoothly without any discontinuities.<br>2. Constraints:<br>(1) The provided size along the main axis must be consistent with the actual size of the child components on the main axis. Any changes in size or additions/removals of child components must be communicated to the **List** component through the **ChildrenMainSize** object method.<br>(2) When the child component is a list item group, the overall size of the list item group along the main axis must be accurately calculated based on the number of columns in the list item group, the spacing between list items along the main axis, and the size of the header, footer, and list items within the list item group. The calculated size must then be provided to the **List** component.<br>(3) If child components include list item groups, the **childrenMainSize** attribute must be set for each individual list item group. Each list item group, as well as the **List** component itself, must be bound one-to-one with a **ChildrenMainSize** object through the **childrenMainSize** attribute.<br>(4) For a multi-column list where child components are generated using **LazyForEach**, ensure that **LazyForEach** generates either all **ListItemGroup** components or all** ListItem** components. | 443 444### maintainVisibleContentPosition<sup>12+</sup> 445 446maintainVisibleContentPosition(enabled: boolean) 447 448Sets whether the visible content position should remain unchanged when data is inserted or deleted above the visible area. 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**Parameters** 455 456| Name| Type | Mandatory| Description | 457| ------ | ------- | ---- | ------------------------------------------------------------ | 458| enabled | boolean | Yes | Whether the visible content position should remain unchanged when data is inserted or deleted above the visible area.<br>Default value: **false**<br>**false**: The visible content position will change when data is inserted or deleted. **true**: The visible content position remains unchanged when data is inserted or deleted.| 459 460> **NOTE** 461> - The visible content position will only remain unchanged when **LazyForEach** is used to insert or delete data outside the visible area. If **ForEach** is used to insert or delete data, or if **LazyForEach** is used for data reloading, the visible content position will change even if **maintainVisibleContentPosition** is set to **true**. 462> - When **maintainVisibleContentPosition** is set to **true**, inserting or deleting data above the visible area will trigger **onDidScroll** and **onScrollIndex** events. 463> - In a multi-column scenario, setting **maintainVisibleContentPosition** to **true** allows you to insert or delete entire rows of data while keeping the visible content position unchanged. If the insertion or deletion does not involve entire rows, however, the visible content position will still change. 464 465## ListItemAlign<sup>9+</sup> 466 467**Widget capability**: This API can be used in ArkTS widgets since API version 9. 468 469**Atomic service API**: This API can be used in atomic services since API version 11. 470 471**System capability**: SystemCapability.ArkUI.ArkUI.Full 472 473| Name | Value | Description | 474| ------ | ------ | ------------------------- | 475| Start | 0 | The list items are packed toward the start edge of the **List** component along the cross axis.| 476| Center | 1 | The list items are centered in the **List** component along the cross axis.| 477| End | 2 | The list items are packed toward the end edge of the **List** component along the cross axis.| 478 479## StickyStyle<sup>9+</sup> 480 481**Widget capability**: This API can be used in ArkTS widgets since API version 9. 482 483**Atomic service API**: This API can be used in atomic services since API version 11. 484 485**System capability**: SystemCapability.ArkUI.ArkUI.Full 486 487| Name | Value | Description | 488| ------ | ------ | ---------------------------------- | 489| None | 0 | In the **ListItemGroup** component, the header is not pinned to the top, and the footer is not pinned to the bottom.| 490| Header | 1 | In the **ListItemGroup** component, the header is pinned to the top, and the footer is not pinned to the bottom. | 491| Footer | 2 | In the **ListItemGroup** component, the footer is pinned to the bottom, and the header is not pinned to the top. | 492 493## ScrollSnapAlign<sup>10+</sup> 494 495Enumerates the alignment modes of list items when scrolling ends. 496 497When list items are left-, right-, top-, or bottom-aligned, the items at the end must be completely displayed, without exposure of any blank area of the boundary; the items at the other end can be out of alignment. 498 499This API is available only when the heights of list items are the same. 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| Name | Value | Description | 506| ------ | ------ | ---------------------------------------- | 507| NONE | 0 | No alignment. This is the default value. | 508| START | 1 | The first item in the view is aligned at the start of the list.<br>**NOTE**<br>When the list hits the end, the items at the end must be completely displayed. In this case, the items at the start may not be aligned.| 509| CENTER | 2 | The middle items in the view are aligned in the center of the list.<br>**NOTE**<br>The top and end items can be aligned in the center of the list. In this case, a blank area may result, and the first or last item is aligned to the center of the list.| 510| END | 3 | The last item in the view is aligned at the end of the list.<br>**NOTE**<br>When the list hits the start, the items at the start must be completely displayed. In this case, the items at the end may not be aligned.| 511## CloseSwipeActionOptions<sup>11+</sup> 512 513Implements the callbacks and events for the [ListItem](ts-container-listitem.md) in the [expanded](ts-container-listitem.md#swipeactionstate11) state. 514 515**Atomic service API**: This API can be used in atomic services since API version 12. 516 517**System capability**: SystemCapability.ArkUI.ArkUI.Full 518 519| Name | Type | Mandatory| Description | 520| ------- | -------- | ---- | ---------------------- | 521| onFinish | ()=>void | No | Triggered after the collapse animation is complete.| 522 523## Events 524 525In 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. 526 527### onItemDelete<sup>(deprecated)</sup> 528 529onItemDelete(event: (index: number) => boolean) 530 531Triggered when a list item is deleted. 532 533This API is deprecated since API version 9. There is no substitute API. 534 535**System capability**: SystemCapability.ArkUI.ArkUI.Full 536 537**Parameters** 538 539| Name| Type | Mandatory| Description | 540| ------ | ------ | ---- | ------------------------ | 541| index | number | Yes | Index of the deleted list item.| 542 543**Return value** 544 545| Type | Description | 546| ------- | -------------- | 547| boolean | Whether the list item is deleted.| 548 549### onScrollIndex 550 551onScrollIndex(event: (start: number, end: number, center: number) => void) 552 553Triggered when a child component enters or leaves the list display area. During index calculation, each **ListItemGroup** component is taken as a whole and assigned an index, and the indexes of the list items within are not included in the calculation. 554 555When the list edge scrolling effect is the spring effect, the **onScrollIndex** event is not triggered when the user scrolls the list to the edge or releases the list to rebound. 556 557This event is triggered once when the list is initialized and when the index of the first list item or the next list item in the list display area changes. 558 559Since API version 10, this event is also triggered when the child component in the center of the list display area changes. 560 561**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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| start | number | Yes | Index of the first child component in the list display area. | 572| end | number | Yes | Index of the last child component in the list display area.| 573| center<sup>10+</sup> | number | Yes | Index of the center child component in the list display area.| 574 575### onReachStart 576 577onReachStart(event: () => void) 578 579Triggered when the list reaches the start position. 580 581This event is triggered once when **initialIndex** is **0** during list initialization and once when the list scrolls to the start position. When the list edge scrolling effect is the spring effect, this event is triggered once when the list passes the start position and is triggered again when the list returns to the start position. 582 583**Widget capability**: This API can be used in ArkTS widgets since API version 9. 584 585**Atomic service API**: This API can be used in atomic services since API version 11. 586 587**System capability**: SystemCapability.ArkUI.ArkUI.Full 588 589### onReachEnd 590 591onReachEnd(event: () => void) 592 593Triggered when the list reaches the end position. 594 595When the list edge scrolling effect is the spring effect, this event is triggered once when the list passes the end position and is triggered again when the list returns to the end position. 596 597**Widget capability**: This API can be used in ArkTS widgets since API version 9. 598 599**Atomic service API**: This API can be used in atomic services since API version 11. 600 601**System capability**: SystemCapability.ArkUI.ArkUI.Full 602 603### onScrollFrameBegin<sup>9+</sup> 604 605onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain: number }) 606 607Triggered when the list starts to scroll. The input parameters indicate the amount by which the list will scroll. The event handler then works out the amount by which the list needs to scroll based on the real-world situation and returns the result. 608 609If **listDirection** is set to **Axis.Vertical**, the return value is the amount by which the list needs to scroll in the vertical direction. If **listDirection** is set to **Axis.Horizontal**, the return value is the amount by which the list needs to scroll in the horizontal direction. 610 611This event is triggered when the user starts dragging the list or the list starts inertial scrolling. It is not triggered when the component rebounds, the scrolling controller is used, or the scrollbar is dragged. 612 613**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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| offset | number | Yes | Amount to scroll by, in vp.| 624| state | [ScrollState](#scrollstate) | Yes | Current scroll state. | 625 626**Return value** 627 628| Type | Description | 629| ------------------------ | -------------------- | 630| { offsetRemain: number } | Actual amount by which the grid scrolls, in vp.| 631 632### onScrollStart<sup>9+</sup> 633 634onScrollStart(event: () => void) 635 636Triggered when the list starts scrolling initiated by the user's finger dragging the list or its scrollbar. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](ts-container-scroll.md#scroller) starts. 637 638**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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### onScrollStop 645 646onScrollStop(event: () => void) 647 648Triggered when the list stops scrolling 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. 649 650**Widget capability**: This API can be used in ArkTS widgets since API version 9. 651 652**Atomic service API**: This API can be used in atomic services since API version 11. 653 654**System capability**: SystemCapability.ArkUI.ArkUI.Full 655 656### onItemMove 657 658onItemMove(event: (from: number, to: number) => boolean) 659 660Triggered when a list item moves. 661 662**Atomic service API**: This API can be used in atomic services since API version 11. 663 664**System capability**: SystemCapability.ArkUI.ArkUI.Full 665 666**Parameters** 667 668| Name| Type | Mandatory| Description | 669| ------ | ------ | ---- | -------------- | 670| from | number | Yes | Index of the item before moving.| 671| to | number | Yes | Index of the item after moving.| 672 673**Return value** 674 675| Type | Description | 676| ------- | -------------- | 677| boolean | Whether the item is moved.| 678 679### onItemDragStart<sup>8+</sup> 680 681onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) \| void)) 682 683Triggered when a list item starts to be dragged. 684 685**Atomic service API**: This API can be used in atomic services since API version 11. 686 687**System capability**: SystemCapability.ArkUI.ArkUI.Full 688 689**Parameters** 690 691| Name | Type | Mandatory| Description | 692| --------- | --------------------------------------------------------- | ---- | ---------------------- | 693| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point. | 694| itemIndex | number | Yes | Index of the dragged item.| 695 696### onItemDragEnter<sup>8+</sup> 697 698onItemDragEnter(event: (event: ItemDragInfo) => void) 699 700Triggered when the dragged item enters the drop target of the list. 701 702**Atomic service API**: This API can be used in atomic services since API version 11. 703 704**System capability**: SystemCapability.ArkUI.ArkUI.Full 705 706**Parameters** 707 708| Name| Type | Mandatory| Description | 709| ------ | --------------------------------------------------------- | ---- | -------------- | 710| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point.| 711 712### onItemDragMove<sup>8+</sup> 713 714onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) 715 716Triggered when the dragged item moves over the drop target of the list. 717 718**Atomic service API**: This API can be used in atomic services since API version 11. 719 720**System capability**: SystemCapability.ArkUI.ArkUI.Full 721 722**Parameters** 723 724| Name | Type | Mandatory| Description | 725| ----------- | --------------------------------------------------------- | ---- | -------------- | 726| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point.| 727| itemIndex | number | Yes | Initial position of the dragged item.| 728| insertIndex | number | Yes | Index of the position to which the dragged item is dropped.| 729 730### onItemDragLeave<sup>8+</sup> 731 732onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) 733 734Triggered when the dragged item leaves the drop target of the list. 735 736**Atomic service API**: This API can be used in atomic services since API version 11. 737 738**System capability**: SystemCapability.ArkUI.ArkUI.Full 739 740**Parameters** 741 742| Name | Type | Mandatory| Description | 743| --------- | --------------------------------------------------------- | ---- | -------------------------- | 744| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point. | 745| itemIndex | number | Yes | Index of the dragged item.| 746 747### onItemDrop<sup>8+</sup> 748 749onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) 750 751Triggered when the dragged item is dropped on the drop target of the list. 752 753During dragging across lists, **true** is returned if the drop target is bound to **onItemDrop**. Otherwise, **false** is returned. During dragging within a list, **isSuccess** is the return value of the **onItemMove** event. 754 755**Atomic service API**: This API can be used in atomic services since API version 11. 756 757**System capability**: SystemCapability.ArkUI.ArkUI.Full 758 759**Parameters** 760 761| Name | Type | Mandatory| Description | 762| ----------- | --------------------------------------------------------- | ---- | -------------- | 763| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point.| 764| itemIndex | number | Yes | Initial position of the dragged item.| 765| insertIndex | number | Yes | Index of the position to which the dragged item is dropped.| 766| isSuccess | boolean | Yes | Whether the dragged item is successfully dropped. | 767 768 769### onScroll<sup>(deprecated)</sup> 770onScroll(event: (scrollOffset: number, scrollState: [ScrollState](#scrollstate)) => void) 771 772Triggered when the list scrolls. 773 774This API is deprecated since API version 12. You are advised to use [onDidScroll](ts-container-scrollable-common.md#ondidscroll12) instead. 775 776**Widget capability**: This API can be used in ArkTS widgets since API version 9. 777 778**Atomic service API**: This API can be used in atomic services since API version 11. 779 780**System capability**: SystemCapability.ArkUI.ArkUI.Full 781 782**Parameters** 783| Name| Type| Mandatory| Description| 784| ------ | ------ | ------ | ------| 785| scrollOffset | number | Yes| Scroll offset of each frame. The offset is positive when the list is scrolled up and negative when the list is scrolled down.<br>Unit: vp| 786| scrollState | [ScrollState](ts-container-list.md#scrollstate) | Yes| Current scroll state.| 787 788### onScrollVisibleContentChange<sup>12+</sup> 789onScrollVisibleContentChange(handler: OnScrollVisibleContentChangeCallback) 790 791Triggered when a child component enters or leaves the list display area. During index calculation, the list item, header of the list item group, and footer of the list item group each are counted as a child component. 792 793When the list edge scrolling effect is the spring effect, the **onScrollVisibleContentChange** event is not triggered when the user scrolls the list to the edge or releases the list to rebound. 794 795This event is triggered once when the list is initialized and when the index of the first child component or the next child component in the list display area changes. 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**Parameters** 802 803| Name| Type| Mandatory| Description| 804| ------ | ------ | ------ | ------| 805| handler | [OnScrollVisibleContentChangeCallback](#onscrollvisiblecontentchangecallback12) | Yes| Callback invoked when the displayed content changes.| 806 807## ScrollState 808 809**Widget capability**: This API can be used in ArkTS widgets since API version 9. 810 811**Atomic service API**: This API can be used in atomic services since API version 11. 812 813**System capability**: SystemCapability.ArkUI.ArkUI.Full 814 815| Name | Value | Description | 816| ------ | ------ | ---------------------------------------- | 817| Idle | 0 | Idle state. Triggered when the scroll state returns to idle, and when the controller's non-animated methods are used to control the scroll.| 818| Scroll | 1 | Scrolling state. Triggered when the list is dragged with the finger, when the scrollbar is dragged, or when the mouse scroll wheel is used.| 819| Fling | 2 | Inertial scrolling state. Triggered by all animated scroll actions. This includes:<br>- Inertial scrolling that occurs after a fling<br>- Bounce-back scrolling when the swipe reaches the edge<br>- Inertial scrolling after quickly dragging the built-in scrollbar and releasing<br>- Scrolling controlled by the animated methods provided by the scroller | 820 821 822## ListScroller<sup>11+</sup> 823 824Implements the scroll controller of the **List** component. A **List** component is bound to a **ListScroller** on a one-to-one basis. 825 826 827> **NOTE** 828> 829> **ListScroller** inherits from [Scroller](ts-container-scroll.md#scroller) and has all methods of [Scroller](ts-container-scroll.md#scroller). 830 831 832### Objects to Import 833 834``` 835listScroller: ListScroller = new ListScroller() 836``` 837 838 839### getItemRectInGroup<sup>11+</sup> 840 841getItemRectInGroup(index: number, indexInGroup: number): RectResult 842 843Obtains the size of a [list item](ts-container-listitem.md) in a [list item group](ts-container-listitemgroup.md) and its position relative to the list. 844 845**Atomic service API**: This API can be used in atomic services since API version 12. 846 847**System capability**: SystemCapability.ArkUI.ArkUI.Full 848 849**Parameters** 850 851| Name | Type | Mandatory | Description | 852| ----- | ------ | ---- | ----------------- | 853| index | number | Yes | Index of the list item group in the list.| 854| indexInGroup | number | Yes | Index of the list item in the list item group.| 855 856> **NOTE** 857> 858> - The value of **index** must be the index of a child component visible in the display area. Otherwise, the value is considered invalid. 859> - The child component for which **index** is set must be a list item group. Otherwise, the **index **value is considered invalid. 860> - The value of **indexInGroup** must be the index of a list item in the list item group visible in the display area. Otherwise, the value is considered invalid. 861> - When **index** or **indexInGroup** is set to an invalid value, the returned size and position are both **0**. 862 863**Return value** 864 865| Type | Description | 866| ------------------- | -------- | 867| [RectResult](ts-types.md#rectresult10) | Size of the list item in the list item group and its position relative to the list.<br>Unit: vp| 868 869 870**Error codes** 871 872For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md). 873 874| ID| Error Message| 875| ------- | -------- | 876| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 877| 100004 | Controller not bound to component. | 878### getVisibleListContentInfo<sup>13+</sup> 879 880getVisibleListContentInfo(x:number, y: number): VisibleListContentInfo 881 882Obtains the index information of the child component at the specified coordinates. 883 884**Atomic service API**: This API can be used in atomic services since API version 13. 885 886**System capability**: SystemCapability.ArkUI.ArkUI.Full 887 888**Parameters** 889 890| Name | Type | Mandatory | Description | 891| ----- | ------ | ---- | ----------------- | 892| x | number | Yes | X-coordinate, in vp.| 893| y | number | Yes | Y-coordinate, in vp.| 894 895> **NOTE** 896> 897> If the provided value of **x** or **y** is invalid, the returned [VisibleListContentInfo](#visiblelistcontentinfo12) object has the **index** property set to **-1**, and both **itemGroupArea** and **itemIndexInGroup** are **undefined**. 898 899**Return value** 900 901| Type | Description | 902| ------------------- | -------- | 903| [VisibleListContentInfo](#visiblelistcontentinfo12) | Index information of the child component at the specified coordinates.| 904 905**Error codes** 906 907For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md). 908 909| ID| Error Message| 910| ------- | -------- | 911| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 912| 100004 | Controller not bound to component. | 913### scrollToItemInGroup<sup>11+</sup> 914 915scrollToItemInGroup(index: number, indexInGroup: number, smooth?: boolean, align?: ScrollAlign): void 916 917Scrolls to the specified list item in the specified list item group. 918 919When **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. 920 921**Atomic service API**: This API can be used in atomic services since API version 12. 922 923**System capability**: SystemCapability.ArkUI.ArkUI.Full 924 925**Parameters** 926 927| Name | Type| Mandatory| Description | 928| --------------------- | -------- | ---- | ------------------------------------------------------------ | 929| index | number | Yes | Index of the target list item group in the current 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. | 930| indexInGroup | number | Yes | Index of the target list item in the list item group specified by **index**.<br>**NOTE**<br>If the value set is a negative value or greater than the maximum index of the items in the list item group, the value is deemed abnormal, and no scrolling will be performed.| 931| 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**| 932| align | [ScrollAlign](ts-container-scroll.md#scrollalign10) | No | How the list item to scroll to is aligned with the container.<br>Default value: **ScrollAlign.START**| 933 934**Error codes** 935 936For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md). 937 938| ID| Error Message| 939| ------- | -------- | 940| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 941| 100004 | Controller not bound to component. | 942 943### closeAllSwipeActions<sup>11+</sup> 944 945closeAllSwipeActions(options?: [CloseSwipeActionOptions](#closeswipeactionoptions11)): void 946 947Collapses the [list items](ts-container-listitem.md) in the [EXPANDED](ts-container-listitem.md#swipeactionstate11) state and sets callback events. 948 949**Atomic service API**: This API can be used in atomic services since API version 12. 950 951**System capability**: SystemCapability.ArkUI.ArkUI.Full 952 953**Parameters** 954 955| Name | Type | Mandatory| Description | 956| ------- | ------------------------------------ | ---- | ----------------------------------------------- | 957| options | [CloseSwipeActionOptions](#closeswipeactionoptions11) | No | Callback events for collapsing [list items](ts-container-listitem.md) in the [EXPANDED](ts-container-listitem.md#swipeactionstate11) state.| 958 959 960**Error codes** 961 962For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md). 963 964| ID| Error Message| 965| ------- | -------- | 966| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 967| 100004 | Controller not bound to component. | 968 969> **NOTE** 970> 971> - A **ListScroller** must be bound to the **List** component. 972 973## OnScrollVisibleContentChangeCallback<sup>12+</sup> 974 975type OnScrollVisibleContentChangeCallback = (start: VisibleListContentInfo, end: VisibleListContentInfo) => void 976 977Called when a child component enters or leaves the list display area. 978 979**Atomic service API**: This API can be used in atomic services since API version 12. 980 981**System capability**: SystemCapability.ArkUI.ArkUI.Full 982 983| Name| Type| Mandatory| Description| 984| ------ | ------ | ------ | ------| 985| start | [VisibleListContentInfo](#visiblelistcontentinfo12) | Yes| Information about the currently displayed first list item or list item group.| 986| end | [VisibleListContentInfo](#visiblelistcontentinfo12) | Yes| Information about the currently displayed last list item or list item group.| 987 988## VisibleListContentInfo<sup>12+</sup> 989 990**Atomic service API**: This API can be used in atomic services since API version 12. 991 992**System capability**: SystemCapability.ArkUI.ArkUI.Full 993 994| Name| Type| Mandatory| Description| 995| ------ | ------ | ------ | ------| 996| index | number | Yes| Index of the list item or list item group in the list display area.| 997| itemGroupArea | [ListItemGroupArea](#listitemgrouparea12) | No| Position of the top or bottom edge of the viewport in the list item group to which the edge is located, if applicable.| 998| itemIndexInGroup | number | No| Index of the starting or ending list item in the list item group to which the top or bottom edge of the viewport is located.| 999 1000## ListItemGroupArea<sup>12+</sup> 1001 1002**Atomic service API**: This API can be used in atomic services since API version 12. 1003 1004**System capability**: SystemCapability.ArkUI.ArkUI.Full 1005 1006| Name | Value | Description | 1007| ------ | ------ | ---------------------------------------- | 1008| NONE | 0 | The edge of the viewport is in the position of **none**. Applicable when the list item group does not contain any header, footer, or list item.| 1009| IN_LIST_ITEM_AREA | 1 | The edge of the viewport is in the position of a list item.| 1010| IN_HEADER_AREA | 2 | The edge of the viewport is in the position of a header.| 1011| IN_FOOTER_AREA | 3 | The edge of the viewport is in the position of a footer.| 1012 1013## Example 1014 1015### Example 1: Adding a Scroll Event 1016In this example, a vertical list is implemented, and a callback is invoked when the first or last item displayed in the list changes. 1017```ts 1018// xxx.ets 1019@Entry 1020@Component 1021struct ListExample { 1022 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1023 1024 build() { 1025 Column() { 1026 List({ space: 20, initialIndex: 0 }) { 1027 ForEach(this.arr, (item: number) => { 1028 ListItem() { 1029 Text('' + item) 1030 .width('100%').height(100).fontSize(16) 1031 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 1032 } 1033 }, (item: string) => item) 1034 } 1035 .listDirection(Axis.Vertical) // Arrangement direction 1036 .scrollBar(BarState.Off) 1037 .friction(0.6) 1038 .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // Divider 1039 .edgeEffect(EdgeEffect.Spring) // Set the edge scrolling effect to Spring. 1040 .onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => { 1041 console.info('first' + firstIndex) 1042 console.info('last' + lastIndex) 1043 console.info('center' + centerIndex) 1044 }) 1045 .onScrollVisibleContentChange((start: VisibleListContentInfo, end: VisibleListContentInfo) => { 1046 console.log(' start index: ' + start.index + 1047 ' start item group area: ' + start.itemGroupArea + 1048 ' start index in group: ' + start.itemIndexInGroup) 1049 console.log(' end index: ' + end.index + 1050 ' end item group area: ' + end.itemGroupArea + 1051 ' end index in group: ' + end.itemIndexInGroup) 1052 }) 1053 .onDidScroll((scrollOffset: number, scrollState: ScrollState) => { 1054 console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset) 1055 }) 1056 .width('90%') 1057 } 1058 .width('100%') 1059 .height('100%') 1060 .backgroundColor(0xDCDCDC) 1061 .padding({ top: 5 }) 1062 } 1063} 1064``` 1065 1066 1067 1068 1069### Example 2: Setting Child Element Alignment 1070This example showcases the alignment effects of child elements in the cross-axis direction of the **List** component using different **ListItemAlign** enumeration values. 1071 1072```ts 1073// xxx.ets 1074@Entry 1075@Component 1076struct ListLanesExample { 1077 @State arr: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"] 1078 @State alignListItem: ListItemAlign = ListItemAlign.Start 1079 1080 build() { 1081 Column() { 1082 List({ space: 20, initialIndex: 0 }) { 1083 ForEach(this.arr, (item: string) => { 1084 ListItem() { 1085 Text('' + item) 1086 .width('100%') 1087 .height(100) 1088 .fontSize(16) 1089 .textAlign(TextAlign.Center) 1090 .borderRadius(10) 1091 .backgroundColor(0xFFFFFF) 1092 } 1093 .border({ width: 2, color: Color.Green }) 1094 }, (item: string) => item) 1095 } 1096 .height(300) 1097 .width("90%") 1098 .friction(0.6) 1099 .border({ width: 3, color: Color.Red }) 1100 .lanes({ minLength: 40, maxLength: 40 }) 1101 .alignListItem(this.alignListItem) 1102 .scrollBar(BarState.Off) 1103 1104 Button("Change alignListItem: "+ this.alignListItem).onClick(() => { 1105 if (this.alignListItem == ListItemAlign.Start) { 1106 this.alignListItem = ListItemAlign.Center 1107 } else if (this.alignListItem == ListItemAlign.Center) { 1108 this.alignListItem = ListItemAlign.End 1109 } else { 1110 this.alignListItem = ListItemAlign.Start 1111 } 1112 }) 1113 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1114 } 1115} 1116``` 1117 1118 1119 1120 1121### Example 3: Setting the Editable Mode 1122This example illustrates how to set whether the current **List** component is in editable mode. 1123 1124```ts 1125// xxx.ets 1126@Entry 1127@Component 1128struct ListExample { 1129 @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1130 @State editFlag: boolean = false 1131 1132 build() { 1133 Stack({ alignContent: Alignment.TopStart }) { 1134 Column() { 1135 List({ space: 20, initialIndex: 0 }) { 1136 ForEach(this.arr, (item: number, index?: number) => { 1137 ListItem() { 1138 Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { 1139 Text('' + item) 1140 .width('100%') 1141 .height(80) 1142 .fontSize(20) 1143 .textAlign(TextAlign.Center) 1144 .borderRadius(10) 1145 .backgroundColor(0xFFFFFF) 1146 .flexShrink(1) 1147 if (this.editFlag) { 1148 Button() { 1149 Text("delete").fontSize(16) 1150 }.width('30%').height(40) 1151 .onClick(() => { 1152 if (index != undefined) { 1153 console.info(this.arr[index] + 'Delete') 1154 this.arr.splice(index, 1) 1155 console.info(JSON.stringify(this.arr)) 1156 this.editFlag = false 1157 } 1158 }).stateEffect(true) 1159 } 1160 } 1161 } 1162 }, (item: string) => item) 1163 }.width('90%') 1164 .scrollBar(BarState.Off) 1165 .friction(0.6) 1166 }.width('100%') 1167 1168 Button('edit list') 1169 .onClick(() => { 1170 this.editFlag = !this.editFlag 1171 }).margin({ top: 5, left: 20 }) 1172 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1173 } 1174} 1175``` 1176 1177 1178 1179### Example 4: Setting the Alignment Mode for the Scroll Snap Position 1180This example shows how to configure the **List** component to align the scroll snap position to the center. 1181 1182```ts 1183// xxx.ets 1184@Entry 1185@Component 1186struct ListExample { 1187 private arr: number[] = [] 1188 private scrollerForList: Scroller = new Scroller() 1189 1190 aboutToAppear() { 1191 for (let i = 0; i < 20; i++) { 1192 this.arr.push(i) 1193 } 1194 } 1195 build() { 1196 Column() { 1197 Row() { 1198 List({ space: 20, initialIndex: 3, scroller: this.scrollerForList }) { 1199 ForEach(this.arr, (item: number) => { 1200 ListItem() { 1201 Text('' + item) 1202 .width('100%').height(100).fontSize(16) 1203 .textAlign(TextAlign.Center) 1204 } 1205 .borderRadius(10).backgroundColor(0xFFFFFF) 1206 .width('60%') 1207 .height('80%') 1208 }, (item: number) => JSON.stringify(item)) 1209 } 1210 .chainAnimation(true) 1211 .edgeEffect(EdgeEffect.Spring) 1212 .listDirection(Axis.Horizontal) 1213 .height('100%') 1214 .width('100%') 1215 .scrollSnapAlign(ScrollSnapAlign.CENTER) 1216 .borderRadius(10) 1217 .backgroundColor(0xDCDCDC) 1218 } 1219 .width('100%') 1220 .height('100%') 1221 .backgroundColor(0xDCDCDC) 1222 .padding({ top: 10 }) 1223 } 1224 } 1225} 1226 1227``` 1228 1229 1230 1231### Example 5: Implementing Accurate Scrolling 1232This example shows that, by setting the **childrenMainSize** attribute, the list can jump to an exact specific location when the **scrollTo** API is called, even when the heights of the child components are inconsistent. 1233 1234For details about how to use these features in conjunction with state management V2, see [List](../../../quick-start/arkts-v1-v2-migration.md#list). 1235```ts 1236// xxx.ets 1237@Entry 1238@Component 1239struct ListExample { 1240 private arr: number[] = [] 1241 private scroller: ListScroller = new ListScroller() 1242 @State listSpace: number = 10 1243 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100) 1244 aboutToAppear(){ 1245 // Initialize the data source. 1246 for (let i = 0; i < 10; i++) { 1247 this.arr.push(i) 1248 } 1249 // The first five items do not have a default main axis size of 100; therefore, it is necessary to inform the list through the ChildrenMainSize. 1250 this.listChildrenSize.splice(0, 5, [300, 300, 300, 300, 300]) 1251 } 1252 build() { 1253 Column() { 1254 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1255 ForEach(this.arr, (item: number) => { 1256 ListItem() { 1257 Text('item-' + item) 1258 .height( item < 5 ? 300 : this.listChildrenSize.childDefaultSize) 1259 .width('90%') 1260 .fontSize(16) 1261 .textAlign(TextAlign.Center) 1262 .borderRadius(10) 1263 .backgroundColor(0xFFFFFF) 1264 } 1265 }, (item: string) => item) 1266 } 1267 .backgroundColor(Color.Gray) 1268 .layoutWeight(1) 1269 .scrollBar(BarState.On) 1270 .childrenMainSize(this.listChildrenSize) 1271 .alignListItem(ListItemAlign.Center) 1272 Row(){ 1273 Button() { Text('item size + 50') }.onClick(()=>{ 1274 this.listChildrenSize.childDefaultSize += 50 1275 }).height('50%').width('30%') 1276 Button() { Text('item size - 50') }.onClick(()=>{ 1277 if (this.listChildrenSize.childDefaultSize === 0) { 1278 return 1279 } 1280 this.listChildrenSize.childDefaultSize -= 50 1281 }).height('50%').width('30%') 1282 Button() { Text('scrollTo (0, 310)') }.onClick(()=>{ 1283 // 310: Jump to the position where the top of item 1 is aligned with the top of the list. 1284 // If childrenMainSize is not set, the scrollTo API may not work correctly when the heights of the list items are inconsistent. 1285 this.scroller.scrollTo({xOffset: 0, yOffset: 310}) 1286 }).height('50%').width('30%') 1287 }.height('20%') 1288 } 1289 } 1290} 1291 1292``` 1293 1294 1295 1296### Example 6: Obtaining Child Component Index Information 1297This example demonstrates how to obtain index information of list items in a **List** component when groups are involved. 1298```ts 1299// xxx.ets 1300@Entry 1301@Component 1302struct ListItemGroupExample { 1303 private timeTable: TimeTable[] = [ 1304 { 1305 title: 'Monday', 1306 projects: ['Language', 'Math', 'English'] 1307 }, 1308 { 1309 title: 'Tuesday', 1310 projects: ['Physics', 'Chemistry', 'Biology'] 1311 }, 1312 { 1313 title: 'Wednesday', 1314 projects: ['History', 'Geography', 'Politics'] 1315 }, 1316 { 1317 title: 'Thursday', 1318 projects: ['Art', 'Music', 'Sports'] 1319 } 1320 ] 1321 private scroller: ListScroller = new ListScroller() 1322 @State listIndexInfo: VisibleListContentInfo = {index: -1} 1323 @State mess:string = "null" 1324 @State itemBackgroundColorArr: boolean[] = [false] 1325 @Builder 1326 itemHead(text: string) { 1327 Text(text) 1328 .fontSize(20) 1329 .backgroundColor(0xAABBCC) 1330 .width("100%") 1331 .padding(10) 1332 } 1333 1334 @Builder 1335 itemFoot(num: number) { 1336 Text('Total lessons: ' + num) 1337 .fontSize(16) 1338 .backgroundColor(0xAABBCC) 1339 .width("100%") 1340 .padding(5) 1341 } 1342 1343 build() { 1344 Column() { 1345 List({ space: 20, scroller: this.scroller}) { 1346 ForEach(this.timeTable, (item: TimeTable, index: number) => { 1347 ListItemGroup({ header: this.itemHead(item.title), footer: this.itemFoot(item.projects.length) }) { 1348 ForEach(item.projects, (project: string, subIndex: number) => { 1349 ListItem() { 1350 Text(project) 1351 .width("100%") 1352 .height(100) 1353 .fontSize(20) 1354 .textAlign(TextAlign.Center) 1355 .backgroundColor(this.itemBackgroundColorArr[index *3 +subIndex] ? 0x68B4FF: 0xFFFFFF) 1356 } 1357 }, (item: string) => item) 1358 } 1359 .divider({ strokeWidth: 1, color: Color.Blue }) // Divider between lines 1360 },(item: string) => item) 1361 } 1362 .width('90%') 1363 .sticky(StickyStyle.Header | StickyStyle.Footer) 1364 .scrollBar(BarState.Off) 1365 .gesture( 1366 PanGesture() 1367 .onActionUpdate((event: GestureEvent) => { 1368 if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) { 1369 this.listIndexInfo = this.scroller.getVisibleListContentInfo(event.fingerList[0].localX, event.fingerList[0].localY) 1370 let itemIndex:string = 'undefined'; 1371 if (this.listIndexInfo.itemIndexInGroup != undefined ) { 1372 itemIndex = this.listIndexInfo.itemIndexInGroup.toString() 1373 if (this.listIndexInfo.index != undefined && this.listIndexInfo.index >= 0 && 1374 this.listIndexInfo.itemIndexInGroup >= 0 ) { 1375 this.itemBackgroundColorArr[this.listIndexInfo.index * 3 + this.listIndexInfo.itemIndexInGroup] = true; 1376 } 1377 } 1378 this.mess = 'index:' + this.listIndexInfo.index.toString() + ' itemIndex:' + itemIndex 1379 } 1380 })) 1381 .gesture( 1382 TapGesture({ count: 1 }) 1383 .onAction((event: GestureEvent) => { 1384 if (event) { 1385 this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length); 1386 } 1387 }) 1388 ) 1389 Text('You are currently at index '+ this.mess) 1390 .fontColor(Color.Red) 1391 .height(50) 1392 }.width('100%').height('90%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1393 } 1394} 1395 1396interface TimeTable { 1397 title: string; 1398 projects: string[]; 1399} 1400 1401``` 1402 1403 1404 1405### Example 7: Setting Edge Fading 1406This example demonstrates how to implement a **List** component with an edge fading effect and set the length of the fading edge. 1407 1408```ts 1409import { LengthMetrics } from '@kit.ArkUI' 1410@Entry 1411@Component 1412struct ListExample { 1413 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] 1414 scrollerForList: Scroller = new Scroller() 1415 build() { 1416 Column() { 1417 1418 List({ space: 20, initialIndex: 0, scroller: this.scrollerForList }) { 1419 ForEach(this.arr, (item: number) => { 1420 ListItem() { 1421 Text('' + item) 1422 .width('100%').height(100).fontSize(16) 1423 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 1424 } 1425 }, (item: string) => item) 1426 } 1427 .fadingEdge(true,{fadingEdgeLength:LengthMetrics.vp(80)}) 1428 } 1429 .width('100%') 1430 .height('100%') 1431 .backgroundColor(0xDCDCDC) 1432 .padding({ top: 5 }) 1433 } 1434} 1435``` 1436 1437 1438
