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 dragging for a list item, 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 | Item displayed at the beginning of the viewport when the current list is loaded for the first time, that is, the first item to be displayed.<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**| 158 159### editMode<sup>(deprecated)</sup> 160 161editMode(value: boolean) 162 163Sets whether to enable edit mode. For details about how to implement deletion of a selected list item, see [Example 3](#example-3). 164 165This API is deprecated since API version 9. There is no substitute API. 166 167**System capability**: SystemCapability.ArkUI.ArkUI.Full 168 169**Parameters** 170 171| Name| Type | Mandatory| Description | 172| ------ | ------ | ---- | -------------------------------------------------- | 173| value | boolean | Yes | Whether to enable edit mode.<br>Default value: **false**| 174 175### edgeEffect 176 177edgeEffect(value: EdgeEffect, options?: EdgeEffectOptions) 178 179Sets the effect used when the scroll boundary is reached. 180 181**Widget capability**: This API can be used in ArkTS widgets since API version 9. 182 183**Atomic service API**: This API can be used in atomic services since API version 11. 184 185**System capability**: SystemCapability.ArkUI.ArkUI.Full 186 187**Parameters** 188 189| Name | Type | Mandatory| Description | 190| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 191| 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**| 192| 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 }**| 193 194### chainAnimation 195 196chainAnimation(value: boolean) 197 198Sets whether to enable chained animations, which are displayed when the list slides or its top or bottom is dragged. 199 200The list items are separated with even space, and one item animation starts after the previous animation during basic sliding interactions. The chained animation effect is similar with spring physics. 201 202When chained animations are in motion, the list divider is not displayed. 203 204The following prerequisites must be met for the chained animations to take effect: 205 206 1. The spring effect is used when the scroll boundary of the list is reached. 207 208 2. The multi-column mode is not enabled for the list. 209 210**Widget capability**: This API can be used in ArkTS widgets since API version 9. 211 212**Atomic service API**: This API can be used in atomic services since API version 11. 213 214**System capability**: SystemCapability.ArkUI.ArkUI.Full 215 216**Parameters** 217 218| Name| Type | Mandatory| Description | 219| ------ | ------- | ---- | ------------------------------------------------------------ | 220| value | boolean | Yes | Whether to enable chained animations.<br>**false** (default): Chained animations are disabled.<br>**true**: Chained animations are enabled. | 221 222### multiSelectable<sup>8+</sup> 223 224multiSelectable(value: boolean) 225 226Sets whether to enable multiselect. 227 228**Widget capability**: This API can be used in ArkTS widgets since API version 9. 229 230**Atomic service API**: This API can be used in atomic services since API version 11. 231 232**System capability**: SystemCapability.ArkUI.ArkUI.Full 233 234**Parameters** 235 236| Name| Type | Mandatory| Description | 237| ------ | ------- | ---- | ------------------------------------------------------------ | 238| value | boolean | Yes | Whether to enable multiselect.<br>**false** (default): Multiselect is disabled.<br>**true**: Multiselect is enabled. | 239 240### lanes<sup>9+</sup> 241 242lanes(value: number | LengthConstrain, gutter?: Dimension) 243 244Sets 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. 245 246The rules are as follows: 247 248- 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. 249- 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. 250- 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. 251- 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. 252- 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. 253 254**Widget capability**: This API can be used in ArkTS widgets since API version 9. 255 256**Atomic service API**: This API can be used in atomic services since API version 11. 257 258**System capability**: SystemCapability.ArkUI.ArkUI.Full 259 260**Parameters** 261 262| Name | Type | Mandatory| Description | 263| -------------------- | ------------------------------------------------------------ | ---- | ---------------------------------------- | 264| value | number \| [LengthConstrain](ts-types.md#lengthconstrain) | Yes | Number of columns or rows in the list.<br>Default value: **1**| 265| gutter<sup>10+</sup> | [Dimension](ts-types.md#dimension10) | No | Gap between columns.<br>Default value: **0** | 266 267### alignListItem<sup>9+</sup> 268 269alignListItem(value: ListItemAlign) 270 271Alignment 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**. 272 273**Widget capability**: This API can be used in ArkTS widgets since API version 9. 274 275**Atomic service API**: This API can be used in atomic services since API version 11. 276 277**System capability**: SystemCapability.ArkUI.ArkUI.Full 278 279**Parameters** 280 281| Name| Type | Mandatory| Description | 282| ------ | ---------------------------------------- | ---- | ------------------------------------------------------ | 283| value | [ListItemAlign](#listitemalign9) | Yes | Alignment mode of list items along the cross axis.<br>Default value: **ListItemAlign.Start**| 284 285### sticky<sup>9+</sup> 286 287sticky(value: StickyStyle) 288 289Sets 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**. 290 291**Widget capability**: This API can be used in ArkTS widgets since API version 9. 292 293**Atomic service API**: This API can be used in atomic services since API version 11. 294 295**System capability**: SystemCapability.ArkUI.ArkUI.Full 296 297**Parameters** 298 299| Name| Type | Mandatory| Description | 300| ------ | ------------------------------------ | ---- | ---------------------------------------------------------- | 301| 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**| 302 303### scrollSnapAlign<sup>10+</sup> 304 305scrollSnapAlign(value: ScrollSnapAlign) 306 307Sets the alignment mode of list items when scrolling ends. 308 309This attribute is effective only when the heights of list items are the same. 310 311It does not take effect after scrolling by a touchpad or mouse device ends. 312 313**Atomic service API**: This API can be used in atomic services since API version 11. 314 315**System capability**: SystemCapability.ArkUI.ArkUI.Full 316 317**Parameters** 318 319| Name| Type | Mandatory| Description | 320| ------ | --------------------------------------------- | ---- | --------------------------------------------------------- | 321| value | [ScrollSnapAlign](#scrollsnapalign10) | Yes | Alignment mode of list items when scrolling ends.<br>Default value: **ScrollSnapAlign.NONE**| 322 323### enableScrollInteraction<sup>10+</sup> 324 325enableScrollInteraction(value: boolean) 326 327Sets 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. 328 329**Atomic service API**: This API can be used in atomic services since API version 11. 330 331**System capability**: SystemCapability.ArkUI.ArkUI.Full 332 333**Parameters** 334 335| Name| Type | Mandatory| Description | 336| ------ | ------- | ---- | ----------------------------------- | 337| value | boolean | Yes | Whether to support scroll gestures.<br>Default value: **true**| 338 339### nestedScroll<sup>10+</sup> 340 341nestedScroll(value: NestedScrollOptions) 342 343Sets 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. 344 345**Atomic service API**: This API can be used in atomic services since API version 11. 346 347**System capability**: SystemCapability.ArkUI.ArkUI.Full 348 349**Parameters** 350 351| Name| Type | Mandatory| Description | 352| ------ | ------------------------------------------------------------ | ---- | -------------- | 353| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10) | Yes | Nested scrolling options.| 354 355### friction<sup>10+</sup> 356 357friction(value: number | Resource) 358 359Sets 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. 360 361**Atomic service API**: This API can be used in atomic services since API version 11. 362 363**System capability**: SystemCapability.ArkUI.ArkUI.Full 364 365**Parameters** 366 367| Name| Type | Mandatory| Description | 368| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 369| 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**.| 370 371### contentStartOffset<sup>11+</sup> 372 373contentStartOffset(value: number) 374 375Sets the offset from the start of the list content to the boundary of the list display area. 376 377**Atomic service API**: This API can be used in atomic services since API version 12. 378 379**System capability**: SystemCapability.ArkUI.ArkUI.Full 380 381**Parameters** 382 383| Name| Type | Mandatory| Description | 384| ------ | ------ | ---- | ----------------------------------------------- | 385| 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| 386 387### contentEndOffset<sup>11+</sup> 388 389contentEndOffset(value: number) 390 391Sets the offset from the end of the list content to the boundary of the list display area. 392 393**Atomic service API**: This API can be used in atomic services since API version 12. 394 395**System capability**: SystemCapability.ArkUI.ArkUI.Full 396 397**Parameters** 398 399| Name| Type | Mandatory| Description | 400| ------ | ------ | ---- | --------------------------------------------- | 401| 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| 402 403### childrenMainSize<sup>12+</sup> 404 405childrenMainSize(value: ChildrenMainSize) 406 407Sets the size information of the child components of a **List** component along the main axis. 408 409**Atomic service API**: This API can be used in atomic services since API version 12. 410 411**System capability**: SystemCapability.ArkUI.ArkUI.Full 412 413**Parameters** 414 415| Name | Type | Mandatory| Description | 416| ---------- | ------ | ---- | ------------------------------- | 417| 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. | 418 419## ListItemAlign<sup>9+</sup> 420 421**Widget capability**: This API can be used in ArkTS widgets since API version 9. 422 423**Atomic service API**: This API can be used in atomic services since API version 11. 424 425**System capability**: SystemCapability.ArkUI.ArkUI.Full 426 427| Name | Value | Description | 428| ------ | ------ | ------------------------- | 429| Start | 0 | The list items are packed toward the start edge of the **List** component along the cross axis.| 430| Center | 1 | The list items are centered in the **List** component along the cross axis.| 431| End | 2 | The list items are packed toward the end edge of the **List** component along the cross axis.| 432 433## StickyStyle<sup>9+</sup> 434 435**Widget capability**: This API can be used in ArkTS widgets since API version 9. 436 437**Atomic service API**: This API can be used in atomic services since API version 11. 438 439**System capability**: SystemCapability.ArkUI.ArkUI.Full 440 441| Name | Value | Description | 442| ------ | ------ | ---------------------------------- | 443| None | 0 | In the **ListItemGroup** component, the header is not pinned to the top, and the footer is not pinned to the bottom.| 444| Header | 1 | In the **ListItemGroup** component, the header is pinned to the top, and the footer is not pinned to the bottom. | 445| Footer | 2 | In the **ListItemGroup** component, the footer is pinned to the bottom, and the header is not pinned to the top. | 446 447## ScrollSnapAlign<sup>10+</sup> 448 449Enumerates the alignment modes of list items when scrolling ends. 450 451When 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. 452 453This API is available only when the heights of list items are the same. 454 455**Atomic service API**: This API can be used in atomic services since API version 11. 456 457**System capability**: SystemCapability.ArkUI.ArkUI.Full 458 459| Name | Value | Description | 460| ------ | ------ | ---------------------------------------- | 461| NONE | 0 | No alignment. This is the default value. | 462| 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.| 463| 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,<br>and the first or last item is aligned to the center of the list.| 464| 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.| 465## CloseSwipeActionOptions<sup>11+</sup> 466 467Implements the callbacks and events for the [ListItem](ts-container-listitem.md) in the [expanded](ts-container-listitem.md#swipeactionstate11) state. 468 469**Atomic service API**: This API can be used in atomic services since API version 12. 470 471**System capability**: SystemCapability.ArkUI.ArkUI.Full 472 473| Name | Type | Mandatory| Description | 474| :------- | -------- | ---- | ---------------------- | 475| onFinish | ()=>void | No | Triggered after the collapse animation is complete.| 476 477## Events 478 479In 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. 480 481### onItemDelete<sup>(deprecated)</sup> 482 483onItemDelete(event: (index: number) => boolean) 484 485Triggered when a list item is deleted. 486 487This API is deprecated since API version 9. There is no substitute API. 488 489**System capability**: SystemCapability.ArkUI.ArkUI.Full 490 491**Parameters** 492 493| Name| Type | Mandatory| Description | 494| ------ | ------ | ---- | ------------------------ | 495| index | number | Yes | Index of the deleted list item.| 496 497**Return value** 498 499| Type | Description | 500| ------- | -------------- | 501| boolean | Whether the list item is deleted.| 502 503### onScrollIndex 504 505onScrollIndex(event: (start: number, end: number, center: number) => void) 506 507Triggered 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. 508 509When 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. 510 511This 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. 512 513Since API version 10, this event is also triggered when the child component in the center of the list display area changes. 514 515**Widget capability**: This API can be used in ArkTS widgets since API version 9. 516 517**Atomic service API**: This API can be used in atomic services since API version 11. 518 519**System capability**: SystemCapability.ArkUI.ArkUI.Full 520 521**Parameters** 522 523| Name | Type | Mandatory| Description | 524| -------------------- | ------ | ---- | -------------------------------------- | 525| start | number | Yes | Index of the first child component in the list display area. | 526| end | number | Yes | Index of the last child component in the list display area.| 527| center<sup>10+</sup> | number | Yes | Index of the center child component in the list display area.| 528 529### onReachStart 530 531onReachStart(event: () => void) 532 533Triggered when the list reaches the start position. 534 535This 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. 536 537**Widget capability**: This API can be used in ArkTS widgets since API version 9. 538 539**Atomic service API**: This API can be used in atomic services since API version 11. 540 541**System capability**: SystemCapability.ArkUI.ArkUI.Full 542 543### onReachEnd 544 545onReachEnd(event: () => void) 546 547Triggered when the list reaches the end position. 548 549When 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. 550 551**Widget capability**: This API can be used in ArkTS widgets since API version 9. 552 553**Atomic service API**: This API can be used in atomic services since API version 11. 554 555**System capability**: SystemCapability.ArkUI.ArkUI.Full 556 557### onScrollFrameBegin<sup>9+</sup> 558 559onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain: number }) 560 561Triggered 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. 562 563If **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. 564 565This 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. 566 567**Widget capability**: This API can be used in ArkTS widgets since API version 9. 568 569**Atomic service API**: This API can be used in atomic services since API version 11. 570 571**System capability**: SystemCapability.ArkUI.ArkUI.Full 572 573**Parameters** 574 575| Name| Type | Mandatory| Description | 576| ------ | ----------------------------------- | ---- | -------------------------- | 577| offset | number | Yes | Amount to scroll by, in vp.| 578| state | [ScrollState](#scrollstate) | Yes | Current scroll state. | 579 580**Return value** 581 582| Type | Description | 583| ------------------------ | -------------------- | 584| { offsetRemain: number } | Actual amount by which the grid scrolls, in vp.| 585 586### onScrollStart<sup>9+</sup> 587 588onScrollStart(event: () => void) 589 590Triggered 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. 591 592**Widget capability**: This API can be used in ArkTS widgets since API version 9. 593 594**Atomic service API**: This API can be used in atomic services since API version 11. 595 596**System capability**: SystemCapability.ArkUI.ArkUI.Full 597 598### onScrollStop 599 600onScrollStop(event: () => void) 601 602Triggered 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. 603 604**Widget capability**: This API can be used in ArkTS widgets since API version 9. 605 606**Atomic service API**: This API can be used in atomic services since API version 11. 607 608**System capability**: SystemCapability.ArkUI.ArkUI.Full 609 610### onItemMove 611 612onItemMove(event: (from: number, to: number) => boolean) 613 614Triggered when a list item moves. 615 616**Atomic service API**: This API can be used in atomic services since API version 11. 617 618**System capability**: SystemCapability.ArkUI.ArkUI.Full 619 620**Parameters** 621 622| Name| Type | Mandatory| Description | 623| ------ | ------ | ---- | -------------- | 624| from | number | Yes | Index of the item before moving.| 625| to | number | Yes | Index of the item after moving.| 626 627**Return value** 628 629| Type | Description | 630| ------- | -------------- | 631| boolean | Whether the item is moved.| 632 633### onItemDragStart<sup>8+</sup> 634 635onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) \| void)) 636 637Triggered when a list item starts to be dragged. 638 639**Atomic service API**: This API can be used in atomic services since API version 11. 640 641**System capability**: SystemCapability.ArkUI.ArkUI.Full 642 643**Parameters** 644 645| Name | Type | Mandatory| Description | 646| --------- | --------------------------------------------------------- | ---- | ---------------------- | 647| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point. | 648| itemIndex | number | Yes | Index of the dragged item.| 649 650### onItemDragEnter<sup>8+</sup> 651 652onItemDragEnter(event: (event: ItemDragInfo) => void) 653 654Triggered when the dragged item enters the drop target of the list. 655 656**Atomic service API**: This API can be used in atomic services since API version 11. 657 658**System capability**: SystemCapability.ArkUI.ArkUI.Full 659 660**Parameters** 661 662| Name| Type | Mandatory| Description | 663| ------ | --------------------------------------------------------- | ---- | -------------- | 664| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point.| 665 666### onItemDragMove<sup>8+</sup> 667 668onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) 669 670Triggered when the dragged item moves over the drop target of the list. 671 672**Atomic service API**: This API can be used in atomic services since API version 11. 673 674**System capability**: SystemCapability.ArkUI.ArkUI.Full 675 676**Parameters** 677 678| Name | Type | Mandatory| Description | 679| ----------- | --------------------------------------------------------- | ---- | -------------- | 680| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point.| 681| itemIndex | number | Yes | Initial position of the dragged item.| 682| insertIndex | number | Yes | Index of the position to which the dragged item is dropped.| 683 684### onItemDragLeave<sup>8+</sup> 685 686onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) 687 688Triggered when the dragged item leaves the drop target of the list. 689 690**Atomic service API**: This API can be used in atomic services since API version 11. 691 692**System capability**: SystemCapability.ArkUI.ArkUI.Full 693 694**Parameters** 695 696| Name | Type | Mandatory| Description | 697| --------- | --------------------------------------------------------- | ---- | -------------------------- | 698| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point. | 699| itemIndex | number | Yes | Index of the dragged item.| 700 701### onItemDrop<sup>8+</sup> 702 703onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) 704 705Triggered when the dragged item is dropped on the drop target of the list. 706 707During 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. 708 709**Atomic service API**: This API can be used in atomic services since API version 11. 710 711**System capability**: SystemCapability.ArkUI.ArkUI.Full 712 713**Parameters** 714 715| Name | Type | Mandatory| Description | 716| ----------- | --------------------------------------------------------- | ---- | -------------- | 717| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo) | Yes | Information about the drag point.| 718| itemIndex | number | Yes | Initial position of the dragged item.| 719| insertIndex | number | Yes | Index of the position to which the dragged item is dropped.| 720| isSuccess | boolean | Yes | Whether the dragged item is successfully dropped. | 721 722 723### onScroll<sup>(deprecated)</sup> 724onScroll(event: (scrollOffset: number, scrollState: [ScrollState](#scrollstate)) => void) 725 726Triggered when the list scrolls. 727 728This API is deprecated since API version 12. You are advised to use [onDidScroll](#ondidscroll12) instead. 729 730**Widget capability**: This API can be used in ArkTS widgets since API version 9. 731 732**Atomic service API**: This API can be used in atomic services since API version 11. 733 734**System capability**: SystemCapability.ArkUI.ArkUI.Full 735 736**Parameters** 737| Name| Type| Mandatory| Description| 738| ------ | ------ | ------ | ------| 739| 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| 740| scrollState | [ScrollState](ts-container-list.md#scrollstate) | Yes| Current scroll state.| 741 742### onWillScroll<sup>12+</sup> 743onWillScroll(handler: Optional<OnWillScrollCallback>) 744 745Triggered when the list is about to scroll. The callback provides the amount of offset that is about to be scrolled in the current frame, along with the current scroll state and the source of the scroll operation. The offset provided in the callback is the calculated intended scrolling offset, not the final actual scrolling offset. You can specify the intended scrolling offset through the return value of this callback. 746 747**Widget capability**: This API can be used in ArkTS widgets since API version 12. 748 749**Atomic service API**: This API can be used in atomic services since API version 12. 750 751**System capability**: SystemCapability.ArkUI.ArkUI.Full 752 753**Parameters** 754 755| Name| Type| Mandatory| Description| 756| ------ | ------ | ------ | ------| 757| handler | Optional<[OnWillScrollCallback](ts-container-scrollable-common.md#onwillscrollcallback12)> | Yes| Callback invoked when the list is about to scroll.| 758 759> **NOTE** 760> 761> When **ScrollEdge** and **ScrollToIndex** that does not involve animation is called, **onWillScroll** is not invoked. 762 763### onDidScroll<sup>12+</sup> 764onDidScroll(handler: OnScrollCallback) 765 766Triggered when the list scrolls. The return value is the offset amount by which the list has scrolled and the current scroll state. 767 768**Widget capability**: This API can be used in ArkTS widgets since API version 12. 769 770**Atomic service API**: This API can be used in atomic services since API version 12. 771 772**System capability**: SystemCapability.ArkUI.ArkUI.Full 773 774**Parameters** 775 776| Name| Type| Mandatory| Description| 777| ------ | ------ | ------ | ------| 778| handler | [OnScrollCallback](ts-container-scrollable-common.md#onscrollcallback12) | Yes| Callback invoked when the list scrolls.| 779 780### onScrollVisibleContentChange<sup>12+</sup> 781onScrollVisibleContentChange(handler: OnScrollVisibleContentChangeCallback) 782 783Triggered when a child component enters or leaves the list display area. During index calculation, list item, header of the list item group, and footer of the list item group each are counted as a child component. 784 785When 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. 786 787This 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. 788 789**Atomic service API**: This API can be used in atomic services since API version 12. 790 791**System capability**: SystemCapability.ArkUI.ArkUI.Full 792 793**Parameters** 794 795| Name| Type| Mandatory| Description| 796| ------ | ------ | ------ | ------| 797| handler | [OnScrollVisibleContentChangeCallback](#onscrollvisiblecontentchangecallback12) | Yes| Callback invoked when the displayed content changes.| 798 799## ScrollState 800 801**Widget capability**: This API can be used in ArkTS widgets since API version 9. 802 803**Atomic service API**: This API can be used in atomic services since API version 11. 804 805**System capability**: SystemCapability.ArkUI.ArkUI.Full 806 807| Name | Value | Description | 808| ------ | ------ | ---------------------------------------- | 809| 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.| 810| 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.| 811| 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 | 812 813 814## ListScroller<sup>11+</sup> 815 816Implements the scroll controller of the **List** component. A **List** component is bound to a **ListScroller** on a one-to-one basis. 817 818 819> **NOTE** 820> 821> **ListScroller** inherits from [Scroller](ts-container-scroll.md#scroller) and has all methods of [Scroller](ts-container-scroll.md#scroller). 822 823 824### Objects to Import 825 826``` 827listScroller: ListScroller = new ListScroller() 828``` 829 830 831### getItemRectInGroup<sup>11+</sup> 832 833getItemRectInGroup(index: number, indexInGroup: number): RectResult 834 835Obtains 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. 836 837**Atomic service API**: This API can be used in atomic services since API version 12. 838 839**System capability**: SystemCapability.ArkUI.ArkUI.Full 840 841**Parameters** 842 843| Name | Type | Mandatory | Description | 844| ----- | ------ | ---- | ----------------- | 845| index | number | Yes | Index of the list item group in the list.| 846| indexInGroup | number | Yes | Index of the list item in the list item group.| 847 848> **NOTE** 849> 850> - The value of **index** must be the index of a child component visible in the display area. Otherwise, the value is considered invalid. 851> - The child component for which **index** is set must be a list item group. Otherwise, the **index **value is considered invalid. 852> - 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. 853> - When **index** or **indexInGroup** is set to an invalid value, the returned size and position are both **0**. 854 855**Return value** 856 857| Type | Description | 858| ------------------- | -------- | 859| [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| 860 861 862**Error codes** 863 864For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md). 865 866| ID| Error Message| 867| ------- | -------- | 868| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 869| 100004 | Controller not bound to component. | 870 871### scrollToItemInGroup<sup>11+</sup> 872 873scrollToItemInGroup(index: number, indexInGroup: number, smooth?: boolean, align?: ScrollAlign): void 874 875Scrolls to the specified list item in the specified list item group. 876 877When **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. 878 879**Atomic service API**: This API can be used in atomic services since API version 12. 880 881**System capability**: SystemCapability.ArkUI.ArkUI.Full 882 883**Parameters** 884 885| Name | Type| Mandatory| Description | 886| --------------------- | -------- | ---- | ------------------------------------------------------------ | 887| 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. | 888| 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.| 889| 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**| 890| 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**| 891 892**Error codes** 893 894For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md). 895 896| ID| Error Message| 897| ------- | -------- | 898| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 899| 100004 | Controller not bound to component. | 900 901### closeAllSwipeActions<sup>11+</sup> 902 903closeAllSwipeActions(options?: [CloseSwipeActionOptions](#closeswipeactionoptions11)): void 904 905Collapses the [list items](ts-container-listitem.md) in the [EXPANDED](ts-container-listitem.md#swipeactionstate11) state and sets callback events. 906 907**Atomic service API**: This API can be used in atomic services since API version 12. 908 909**System capability**: SystemCapability.ArkUI.ArkUI.Full 910 911**Parameters** 912 913| Name | Type | Mandatory| Description | 914| ------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 915| options | [CloseSwipeActionOptions](#closeswipeactionoptions11) | No | Callback events for collapsing [list items](ts-container-listitem.md) in the [EXPANDED](ts-container-listitem.md#swipeactionstate11) state.| 916 917 918**Error codes** 919 920For details about the error codes, see [Universal Error Codes](../../errorcode-universal.md). 921 922| ID| Error Message| 923| ------- | -------- | 924| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed. | 925| 100004 | Controller not bound to component. | 926 927> **NOTE** 928> 929> - A **ListScroller** must be bound to the **List** component. 930 931## OnScrollVisibleContentChangeCallback<sup>12+</sup> 932 933type OnScrollVisibleContentChangeCallback = (start: VisibleListContentInfo, end: VisibleListContentInfo) => void 934 935Called when a child component enters or leaves the list display area. 936 937**Atomic service API**: This API can be used in atomic services since API version 12. 938 939**System capability**: SystemCapability.ArkUI.ArkUI.Full 940 941| Name| Type| Mandatory| Description| 942| ------ | ------ | ------ | ------| 943| start | [VisibleListContentInfo](#visiblelistcontentinfo12) | Yes| Information about the currently displayed first list item or list item group.| 944| end | [VisibleListContentInfo](#visiblelistcontentinfo12) | Yes| Information about the currently displayed last list item or list item group.| 945 946## VisibleListContentInfo<sup>12+</sup> 947 948**Atomic service API**: This API can be used in atomic services since API version 12. 949 950**System capability**: SystemCapability.ArkUI.ArkUI.Full 951 952| Name| Type| Mandatory| Description| 953| ------ | ------ | ------ | ------| 954| index | number | Yes| Index of the list item or list item group in the list display area.| 955| 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.| 956| 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.| 957 958## ListItemGroupArea<sup>12+</sup> 959 960**Atomic service API**: This API can be used in atomic services since API version 12. 961 962**System capability**: SystemCapability.ArkUI.ArkUI.Full 963 964| Name | Value | Description | 965| ------ | ------ | ---------------------------------------- | 966| 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.| 967| IN_LIST_ITEM_AREA | 1 | The edge of the viewport is in the position of a list item.| 968| IN_HEADER_AREA | 2 | The edge of the viewport is in the position of a header.| 969| IN_FOOTER_AREA | 3 | The edge of the viewport is in the position of a footer.| 970 971## Example 972 973### Example 1 974In this example, a vertical list is implemented, and a callback is invoked when the first or last item displayed in the list changes. 975```ts 976// xxx.ets 977@Entry 978@Component 979struct ListExample { 980 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 981 982 build() { 983 Column() { 984 List({ space: 20, initialIndex: 0 }) { 985 ForEach(this.arr, (item: number) => { 986 ListItem() { 987 Text('' + item) 988 .width('100%').height(100).fontSize(16) 989 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 990 } 991 }, (item: string) => item) 992 } 993 .listDirection(Axis.Vertical) // Arrangement direction 994 .scrollBar(BarState.Off) 995 .friction(0.6) 996 .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // Divider 997 .edgeEffect(EdgeEffect.Spring) // Set the edge scrolling effect to Spring. 998 .onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => { 999 console.info('first' + firstIndex) 1000 console.info('last' + lastIndex) 1001 console.info('center' + centerIndex) 1002 }) 1003 .onScrollVisibleContentChange((start: VisibleListContentInfo, end: VisibleListContentInfo) => { 1004 console.log(' start index: ' + start.index + 1005 ' start item group area: ' + start.itemGroupArea + 1006 ' start index in group: ' + start.itemIndexInGroup) 1007 console.log(' end index: ' + end.index + 1008 ' end item group area: ' + end.itemGroupArea + 1009 ' end index in group: ' + end.itemIndexInGroup) 1010 }) 1011 .onDidScroll((scrollOffset: number, scrollState: ScrollState) => { 1012 console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset) 1013 }) 1014 .width('90%') 1015 } 1016 .width('100%') 1017 .height('100%') 1018 .backgroundColor(0xDCDCDC) 1019 .padding({ top: 5 }) 1020 } 1021} 1022``` 1023 1024 1025 1026 1027### Example 2 1028 1029```ts 1030// xxx.ets 1031@Entry 1032@Component 1033struct ListLanesExample { 1034 @State arr: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"] 1035 @State alignListItem: ListItemAlign = ListItemAlign.Start 1036 1037 build() { 1038 Column() { 1039 List({ space: 20, initialIndex: 0 }) { 1040 ForEach(this.arr, (item: string) => { 1041 ListItem() { 1042 Text('' + item) 1043 .width('100%') 1044 .height(100) 1045 .fontSize(16) 1046 .textAlign(TextAlign.Center) 1047 .borderRadius(10) 1048 .backgroundColor(0xFFFFFF) 1049 } 1050 .border({ width: 2, color: Color.Green }) 1051 }, (item: string) => item) 1052 } 1053 .height(300) 1054 .width("90%") 1055 .friction(0.6) 1056 .border({ width: 3, color: Color.Red }) 1057 .lanes({ minLength: 40, maxLength: 40 }) 1058 .alignListItem(this.alignListItem) 1059 .scrollBar(BarState.Off) 1060 1061 Button("Change alignListItem: "+ this.alignListItem).onClick(() => { 1062 if (this.alignListItem == ListItemAlign.Start) { 1063 this.alignListItem = ListItemAlign.Center 1064 } else if (this.alignListItem == ListItemAlign.Center) { 1065 this.alignListItem = ListItemAlign.End 1066 } else { 1067 this.alignListItem = ListItemAlign.Start 1068 } 1069 }) 1070 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1071 } 1072} 1073``` 1074 1075 1076 1077 1078### Example 3 1079 1080```ts 1081// xxx.ets 1082@Entry 1083@Component 1084struct ListExample { 1085 @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1086 @State editFlag: boolean = false 1087 1088 build() { 1089 Stack({ alignContent: Alignment.TopStart }) { 1090 Column() { 1091 List({ space: 20, initialIndex: 0 }) { 1092 ForEach(this.arr, (item: number, index?: number) => { 1093 ListItem() { 1094 Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { 1095 Text('' + item) 1096 .width('100%') 1097 .height(80) 1098 .fontSize(20) 1099 .textAlign(TextAlign.Center) 1100 .borderRadius(10) 1101 .backgroundColor(0xFFFFFF) 1102 .flexShrink(1) 1103 if (this.editFlag) { 1104 Button() { 1105 Text("delete").fontSize(16) 1106 }.width('30%').height(40) 1107 .onClick(() => { 1108 if (index != undefined) { 1109 console.info(this.arr[index] + 'Delete') 1110 this.arr.splice(index, 1) 1111 console.info(JSON.stringify(this.arr)) 1112 this.editFlag = false 1113 } 1114 }).stateEffect(true) 1115 } 1116 } 1117 } 1118 }, (item: string) => item) 1119 }.width('90%') 1120 .scrollBar(BarState.Off) 1121 .friction(0.6) 1122 }.width('100%') 1123 1124 Button('edit list') 1125 .onClick(() => { 1126 this.editFlag = !this.editFlag 1127 }).margin({ top: 5, left: 20 }) 1128 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1129 } 1130} 1131``` 1132 1133 1134 1135### Example 4 1136 1137```ts 1138// xxx.ets 1139@Entry 1140@Component 1141struct ListExample { 1142 private arr: number[] = [] 1143 private scrollerForList: Scroller = new Scroller() 1144 1145 aboutToAppear() { 1146 for (let i = 0; i < 20; i++) { 1147 this.arr.push(i) 1148 } 1149 } 1150 build() { 1151 Column() { 1152 Row() { 1153 List({ space: 20, initialIndex: 3, scroller: this.scrollerForList }) { 1154 ForEach(this.arr, (item: number) => { 1155 ListItem() { 1156 Text('' + item) 1157 .width('100%').height(100).fontSize(16) 1158 .textAlign(TextAlign.Center) 1159 } 1160 .borderRadius(10).backgroundColor(0xFFFFFF) 1161 .width('60%') 1162 .height('80%') 1163 }, (item: number) => JSON.stringify(item)) 1164 } 1165 .chainAnimation(true) 1166 .edgeEffect(EdgeEffect.Spring) 1167 .listDirection(Axis.Horizontal) 1168 .height('100%') 1169 .width('100%') 1170 .scrollSnapAlign(ScrollSnapAlign.CENTER) 1171 .borderRadius(10) 1172 .backgroundColor(0xDCDCDC) 1173 } 1174 .width('100%') 1175 .height('100%') 1176 .backgroundColor(0xDCDCDC) 1177 .padding({ top: 10 }) 1178 } 1179 } 1180} 1181 1182``` 1183 1184 1185 1186### Example 5 1187This 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. 1188```ts 1189// xxx.ets 1190@Entry 1191@Component 1192struct ListExample { 1193 private arr: number[] = [] 1194 private scroller: ListScroller = new ListScroller() 1195 @State listSpace: number = 10 1196 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100) 1197 aboutToAppear(){ 1198 // Initialize the data source. 1199 for (let i = 0; i < 10; i++) { 1200 this.arr.push(i) 1201 } 1202 // 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. 1203 this.listChildrenSize.splice(0, 5, [300, 300, 300, 300, 300]) 1204 } 1205 build() { 1206 Column() { 1207 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1208 ForEach(this.arr, (item: number) => { 1209 ListItem() { 1210 Text('item-' + item) 1211 .height( item < 5 ? 300 : this.listChildrenSize.childDefaultSize) 1212 .width('90%') 1213 .fontSize(16) 1214 .textAlign(TextAlign.Center) 1215 .borderRadius(10) 1216 .backgroundColor(0xFFFFFF) 1217 } 1218 }, (item: string) => item) 1219 } 1220 .backgroundColor(Color.Gray) 1221 .layoutWeight(1) 1222 .scrollBar(BarState.On) 1223 .childrenMainSize(this.listChildrenSize) 1224 .alignListItem(ListItemAlign.Center) 1225 Row(){ 1226 Button() { Text('item size + 50') }.onClick(()=>{ 1227 this.listChildrenSize.childDefaultSize += 50 1228 }).height('50%').width('30%') 1229 Button() { Text('item size - 50') }.onClick(()=>{ 1230 if (this.listChildrenSize.childDefaultSize === 0) { 1231 return 1232 } 1233 this.listChildrenSize.childDefaultSize -= 50 1234 }).height('50%').width('30%') 1235 Button() { Text('scrollTo (0, 310)') }.onClick(()=>{ 1236 // 310: Jump to the position where the top of item 1 is aligned with the top of the list. 1237 // If childrenMainSize is not set, the scrollTo API may not work correctly when the heights of the list items are inconsistent. 1238 this.scroller.scrollTo({xOffset: 0, yOffset: 310}) 1239 }).height('50%').width('30%') 1240 }.height('20%') 1241 } 1242 } 1243} 1244 1245``` 1246 1247 1248
