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