1# ListItem 2 3The **ListItem** component displays specific items in the list. It must be used together with **List**. 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> - The parent of this component can only be [List](ts-container-list.md) or [ListItemGroup](ts-container-listitemgroup.md). 9> - When this component is used with **LazyForEach**, its child components are created when it is created. When this component is used with **if/else** or **ForEach**, or when the parent component is **List**or **ListItemGroup**, its child components are created when it is laid out. 10 11## Child Components 12 13This component can contain a single child component. 14 15## APIs 16 17### ListItem<sup>10+</sup> 18 19ListItem(value?: ListItemOptions) 20 21**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 22 23**Atomic service API**: This API can be used in atomic services since API version 11. 24 25**System capability**: SystemCapability.ArkUI.ArkUI.Full 26 27**Parameters** 28 29| Name| Type | Mandatory| Description | 30| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 31| value | [ListItemOptions](#listitemoptions10) | No | Value of the list item, containing the **style** parameter of the **ListItemStyle** enum type.| 32 33### ListItem<sup>(deprecated)</sup> 34 35ListItem(value?: string) 36 37This API is deprecated since API version 10. You are advised to use [ListItem<sup>10+</sup>](#listitem10) instead. 38 39**Widget capability**: Since API version 9, this API is supported in ArkTS widgets. 40 41**System capability**: SystemCapability.ArkUI.ArkUI.Full 42 43**Parameters** 44 45| Name| Type | Mandatory| Description| 46| ------ | ----------------------------- | ---- | -------- | 47| value | string | No | N/A | 48 49## Attributes 50 51In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 52 53### sticky<sup>(deprecated)</sup> 54 55sticky(value: Sticky) 56 57Sets the sticky effect of the list item. 58 59This attribute is deprecated since API version 9. You are advised to use [the sticky attribute of the List component](ts-container-list.md#attributes) instead. 60 61**System capability**: SystemCapability.ArkUI.ArkUI.Full 62 63**Parameters** 64 65| Name| Type | Mandatory| Description | 66| ------ | ----------------------------------- | ---- | ------------------------------------------ | 67| value | [Sticky](#stickydeprecated) | Yes | Sticky effect of the list item.<br>Default value: **Sticky.None**| 68 69### editable<sup>(deprecated)</sup> 70 71editable(value: boolean | EditMode) 72 73Sets whether to enable edit mode, where the list item can be deleted or moved. 74 75This API is deprecated since API version 9. There is no substitute API. 76 77**System capability**: SystemCapability.ArkUI.ArkUI.Full 78 79**Parameters** 80 81| Name| Type | Mandatory| Description | 82| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------ | 83| value | boolean \| [EditMode](#editmodedeprecated) | Yes | Whether to enable edit mode.<br>Default value: **false**| 84 85### selectable<sup>8+</sup> 86 87selectable(value: boolean) 88 89Sets whether the list item is selectable for multiselect. This attribute takes effect only when mouse frame selection is enabled for the parent **List** container. 90 91**Widget capability**: Since API version 9, this API is supported in ArkTS widgets. 92 93**Atomic service API**: This API can be used in atomic services since API version 11. 94 95**System capability**: SystemCapability.ArkUI.ArkUI.Full 96 97**Parameters** 98 99| Name| Type | Mandatory| Description | 100| ------ | ------- | ---- | ------------------------------------------------- | 101| value | boolean | Yes | whether the list item is selectable for multiselect.<br>Default value: **true**| 102 103### selected<sup>10+</sup> 104 105selected(value: boolean) 106 107Sets whether the list item is selected. This attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). This attribute must be used before the [style for the selected state](./ts-universal-attributes-polymorphic-style.md) is set. Otherwise, the style settings will not take effect. 108 109**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 110 111**Atomic service API**: This API can be used in atomic services since API version 11. 112 113**System capability**: SystemCapability.ArkUI.ArkUI.Full 114 115**Parameters** 116 117| Name| Type | Mandatory| Description | 118| ------ | ------- | ---- | ---------------------------------------- | 119| value | boolean | Yes | Whether the list item is selected.<br>Default value: **false**| 120 121### swipeAction<sup>9+</sup> 122 123swipeAction(value: SwipeActionOptions) 124 125Sets the swipe action item displayed when the list item is swiped out from the screen edge. 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 | [SwipeActionOptions](#swipeactionoptions9) | Yes | Swipe action item displayed when the list item is swiped out from the screen edge.| 136 137## Sticky<sup>(deprecated)</sup> 138This API is deprecated since API version 9. You are advised to use [the stickyStyle enum of the List component](ts-container-list.md#stickystyle9) instead. 139 140**System capability**: SystemCapability.ArkUI.ArkUI.Full 141 142| Name| Value| Description| 143| -------- | -------- | -------- | 144| None | 0 | The list item is not sticky.| 145| Normal | 1 | The list item is sticky with no special effects.| 146| Opacity | 2 | The list item is sticky with opacity changes.| 147 148## EditMode<sup>(deprecated)</sup> 149This API is deprecated since API version 9. There is no substitute API. 150 151**System capability**: SystemCapability.ArkUI.ArkUI.Full 152 153| Name | Value| Description | 154| ------ | ------ | --------- | 155| None | 0 | The editing operation is not restricted. | 156| Deletable | 1 | The list item can be deleted.| 157| Movable | 2 | The list item can be moved.| 158 159## SwipeEdgeEffect<sup>9+</sup> 160 161**Atomic service API**: This API can be used in atomic services since API version 11. 162 163**System capability**: SystemCapability.ArkUI.ArkUI.Full 164 165| Name | Value| Description | 166| ------ | ------ | --------- | 167| Spring | 0 | When the list item scrolls to the edge of the list, it can continue to scroll for a distance.<br>If the delete area is set, the list item can continue to scroll after the scroll distance exceeds the delete threshold and,<br>after being released, rebound following the spring curve.| 168| None | 1 | The list item cannot scroll beyond the edge of the list.<br>If the delete area is set, the list item cannot continue to scroll after the scroll distance exceeds the delete threshold.<br>If the delete callback is set, it is triggered when the delete threshold is reached and the list item is released.| 169 170## SwipeActionOptions<sup>9+</sup> 171 172The top level of the @builder function corresponding to **start** and **end** must be a single component and cannot be an **if/else**, **ForEach**, or **LazyForEach** statement. 173 174The swipe gesture works only in the list item area. If a swipe causes a child component to extend beyond the list item area, the portion outside the area does not respond to the swipe. In light of this, avoid setting **swipeAction** to a component too wide in a multi-column list. 175 176**System capability**: SystemCapability.ArkUI.ArkUI.Full 177 178| Name | Type | Mandatory| Description | 179| ---------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 180| start | [CustomBuilder](ts-types.md#custombuilder8) \| [SwipeActionItem](#swipeactionitem10) | No | Swipe action item displayed on the left of the list item when the item is swiped right (in vertical list layout) or above the list item when the item is swiped down (in horizontal list layout).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 181| end | [CustomBuilder](ts-types.md#custombuilder8) \| [SwipeActionItem](#swipeactionitem10) | No | Swipe action item displayed on the right of the list item when the item is swiped left (in vertical list layout) or below the list item when the item is swiped up (in horizontal list layout).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 182| edgeEffect | [SwipeEdgeEffect](#swipeedgeeffect9) | No | Scroll effect.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 183| onOffsetChange<sup>11+</sup> | (offset: number) => void | No | Callback invoked when the scroll offset changes.<br>**NOTE**<br>Specifically, this callback is invoked when the location of the list item changes, in vp, when it is swiped left or right (in vertical list layout) or up or down (in horizontal list layout).<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 184 185## SwipeActionItem<sup>10+</sup> 186 187Describes the swipe action item.<br>For a list in vertical layout, it refers to the delete option displayed on the left (or right) of the list item when the list item is swiped right (or left). 188<br>For a list in horizontal layout, it refers to the delete option displayed below (or above) the list item when the list item is swiped up (or down). 189 190**System capability**: SystemCapability.ArkUI.ArkUI.Full 191 192| Name | Type | Mandatory| Description | 193| -------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 194| actionAreaDistance | [Length](ts-types.md#length) | No| Swipe distance threshold for deleting the list item.<br>Default value: **56vp**<br>**NOTE**<br>This parameter cannot be set in percentage.<br>If the value is greater than the list item width minus the width of **swipeAction**, or is less than or equal to 0, the delete area will not be set.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 195| onAction | () => void | No| Callback invoked when the list item is released while in the delete area.<br>**NOTE**<br>This callback is invoked only when the list item is released in a position that meets or goes beyond the specified swipe distance threshold (which must be valid) for deleting the list item.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 196| onEnterActionArea | () => void | No| Callback invoked each time the list item enters the delete area.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 197| onExitActionArea | () => void | No|Callback invoked each time the list item exits the delete area.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 198| builder | [CustomBuilder](ts-types.md#custombuilder8) | No|Swipe action item displayed when the list item is swiped left or right (in vertical list layout) or up or down (in horizontal list layout).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 199| onStateChange<sup>11+</sup> | (swipeActionState) => void | No|Callback invoked when the swipe state of the list item changes.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 200## ListItemOptions<sup>10+</sup> 201 202**Atomic service API**: This API can be used in atomic services since API version 11. 203 204**System capability**: SystemCapability.ArkUI.ArkUI.Full 205 206| Name | Type | Mandatory| Description | 207| ----- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 208| style | [ListItemStyle](#listitemstyle10) | No | Style of the list item.<br>Default value: **ListItemStyle.NONE**<br>If this parameter is set to **ListItemStyle.NONE**, no style is applied.<br>When **ListItemStyle.CARD** is used, you are advised to pair it with **ListItemGroupStyle.CARD** from [ListItemGroup](ts-container-listitemgroup.md) to apply the default card style.<br>In the card style, the default specifications for a list item are as follows: a height of 48 vp, a width of 100%, and horizontal padding of 8 vp on both the left and right sides. If you want to implement an adaptive height for the list item, you can set the **height** attribute to **undefined**.<br>It can be in focus, hover, press, selected, or disable style depending on the state.<br>**NOTE**<br>In the card style, by default, the list runs along the vertical axis, that is, **listDirection** is at **Axis.Vertical**. If **listDirection** is set to **Axis.Horizontal**, a disordered display may result. The **alignListItem** attribute of the list is set to **ListItemAlign.Center** by default, which aligns the list items in the center.| 209 210## ListItemStyle<sup>10+</sup> 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| Name| Value | Description | 217| ---- | ---- | ------------------ | 218| NONE | 0 | No style. | 219| CARD | 1 | Default card style.| 220 221## SwipeActionState<sup>11+</sup> 222 223**Atomic service API**: This API can be used in atomic services since API version 12. 224 225**System capability**: SystemCapability.ArkUI.ArkUI.Full 226 227| Name | Value | Description | 228| --------- | --------- | ------------------------------------------------------------ | 229| COLLAPSED | 0 | Collapsed state.<br>When the list item is swiped left or right (in vertical list layout) or up or down (in horizontal list layout), the swipe action item is hidden.| 230| EXPANDED | 1 | Expanded state.<br>When the list item is swiped left or right (in vertical list layout) or up or down (in horizontal list layout), the swipe action item is shown.<br>**NOTE**<br>When the list item is swiped left or right (in vertical list layout)<br>or up or down (in horizontal list layout), the swipe action item is shown.| 231| ACTIONING | 2 | In-action state. The list item is in this state when it enters the delete area.<br>**NOTE**<br>A list item can enter this state only when it is released in a position that meets or goes beyond the specified swipe distance threshold (which must be valid) for deleting the list item.| 232 233## Events 234 235### onSelect<sup>8+</sup> 236 237onSelect(event: (isSelected: boolean) => void) 238 239Triggered when the selected state of the list item for multiselect changes. 240 241**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 242 243**Atomic service API**: This API can be used in atomic services since API version 11. 244 245**System capability**: SystemCapability.ArkUI.ArkUI.Full 246 247**Parameters** 248 249| Name | Type | Mandatory| Description | 250| ---------- | ------- | ---- | ------------------------------------------------------------ | 251| isSelected | boolean | Yes | Returns **true** if the list item is selected for multselect; returns **false** otherwise.| 252 253## Example 254 255### Example 1 256 257```ts 258// xxx.ets 259@Entry 260@Component 261struct ListItemExample { 262 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 263 264 build() { 265 Column() { 266 List({ space: 20, initialIndex: 0 }) { 267 ForEach(this.arr, (item: number) => { 268 ListItem() { 269 Text('' + item) 270 .width('100%') 271 .height(100) 272 .fontSize(16) 273 .textAlign(TextAlign.Center) 274 .borderRadius(10) 275 .backgroundColor(0xFFFFFF) 276 } 277 }, (item: string) => item) 278 }.width('90%') 279 .scrollBar(BarState.Off) 280 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 281 } 282} 283``` 284 285 286 287### Example 2 288 289 290```ts 291// xxx.ets 292@Entry 293@Component 294struct ListItemExample2 { 295 @State arr: number[] = [0, 1, 2, 3, 4] 296 @State enterEndDeleteAreaString: string = "not enterEndDeleteArea" 297 @State exitEndDeleteAreaString: string = "not exitEndDeleteArea" 298 299 @Builder itemEnd() { 300 Row() { 301 Button("Delete").margin("4vp") 302 Button("Set").margin("4vp") 303 }.padding("4vp").justifyContent(FlexAlign.SpaceEvenly) 304 } 305 306 build() { 307 Column() { 308 List({ space: 10 }) { 309 ForEach(this.arr, (item: number) => { 310 ListItem() { 311 Text("item" + item) 312 .width('100%') 313 .height(100) 314 .fontSize(16) 315 .textAlign(TextAlign.Center) 316 .borderRadius(10) 317 .backgroundColor(0xFFFFFF) 318 } 319 .transition({ type: TransitionType.Delete, opacity: 0 }) 320 .swipeAction({ 321 end: { 322 builder: () => { this.itemEnd() }, 323 onAction: () => { 324 animateTo({ duration: 1000 }, () => { 325 let index = this.arr.indexOf(item) 326 this.arr.splice(index, 1) 327 }) 328 }, 329 actionAreaDistance: 56, 330 onEnterActionArea: () => { 331 this.enterEndDeleteAreaString = "enterEndDeleteArea" 332 this.exitEndDeleteAreaString = "not exitEndDeleteArea" 333 }, 334 onExitActionArea: () => { 335 this.enterEndDeleteAreaString = "not enterEndDeleteArea" 336 this.exitEndDeleteAreaString = "exitEndDeleteArea" 337 } 338 } 339 }) 340 }, (item: string) => item) 341 } 342 Text(this.enterEndDeleteAreaString).fontSize(20) 343 Text(this.exitEndDeleteAreaString).fontSize(20) 344 } 345 .padding(10) 346 .backgroundColor(0xDCDCDC) 347 .width('100%') 348 .height('100%') 349 } 350} 351``` 352 353 354### Example 3 355 356```ts 357// xxx.ets 358@Entry 359@Component 360struct ListItemExample3 { 361 build() { 362 Column() { 363 List({ space: "4vp", initialIndex: 0 }) { 364 ListItemGroup({ style: ListItemGroupStyle.CARD }) { 365 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 366 ListItem({ style: itemStyle }) { 367 Text("" + index) 368 .width("100%") 369 .textAlign(TextAlign.Center) 370 } 371 }) 372 } 373 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 374 ListItem({ style: itemStyle }) { 375 Text("" + index) 376 .width("100%") 377 .textAlign(TextAlign.Center) 378 } 379 }) 380 } 381 .width('100%') 382 .multiSelectable(true) 383 .backgroundColor(0xDCDCDC) 384 } 385 .width('100%') 386 .padding({ top: 5 }) 387 } 388} 389``` 390 391
