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 9 10## Child Components 11 12This component can contain a single child component. 13 14## APIs 15 16Since API version 9, this API is supported in ArkTS widgets. 17 18### ListItem<sup>10+</sup> 19 20ListItem(value?: ListItemOptions) 21 22**Parameters** 23 24| Name| Type | Mandatory| Description | 25| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 26| value | [ListItemOptions](#listitemoptions10) | No | Value of the list item, containing the **style** parameter of the **ListItemStyle** enum type.| 27 28### ListItem<sup>(deprecated)</sup> 29 30ListItem(value?: string) 31 32This API is deprecated since API version 10. You are advised to use [ListItem<sup>10+</sup>](#listitem10) instead. 33 34**Parameters** 35 36| Name| Type | Mandatory| Description| 37| ------ | ----------------------------- | ---- | -------- | 38| value | string | No | N/A | 39 40## Attributes 41 42In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 43 44| Name| Type| Description| 45| -------- | -------- | -------- | 46| sticky<sup>(deprecated)</sup> | [Sticky](#stickydeprecated) | Sticky effect of the list item.<br>Default value: **Sticky.None**<br>This 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.| 47| editable<sup>(deprecated)</sup> | boolean \| [EditMode](#editmodedeprecated) | Whether to enter editing mode, where the list item can be deleted or moved.<br>This API is deprecated since API version 9. There is no substitute API.<br>Default value: **false**| 48| selectable<sup>8+</sup> | boolean | Whether the current list item is selectable by mouse drag.<br>**NOTE**<br>This attribute takes effect only when mouse frame selection is enabled for the parent **\<List>** container.<br>Default value: **true**| 49| selected<sup>10+</sup> | boolean | Whether the list item is selected. This attribute supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.<br>**NOTE**<br>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.<br>Default value: **false**| 50| swipeAction<sup>9+</sup> | {<br>start?: [CustomBuilder](ts-types.md#custombuilder8) \| [SwipeActionItem](#swipeactionitem10),<br>end?:[CustomBuilder](ts-types.md#custombuilder8) \| [SwipeActionItem](#swipeactionitem10),<br>edgeEffect?: [SwipeEdgeEffect](#swipeedgeeffect9),<br>} | Swipe action displayed when the list item is swiped out from the screen edge.<br>- **start**: swipe action 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>- **end**: swipe action 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>- **edgeEffect**: scroll effect.<br>**NOTE**<br>- The 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.<br> - The 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.| 51 52## Sticky<sup>(deprecated)</sup> 53This 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. 54| Name| Value| Description| 55| -------- | -------- | -------- | 56| None | 0 | The list item is not sticky.| 57| Normal | 1 | The list item is sticky with no special effects.| 58| Opacity | 2 | The list item is sticky with opacity changes.| 59 60## EditMode<sup>(deprecated)</sup> 61This API is deprecated since API version 9. There is no substitute API. 62| Name | Value| Description | 63| ------ | ------ | --------- | 64| None | 0 | The editing operation is not restricted. | 65| Deletable | 1 | The list item can be deleted.| 66| Movable | 2 | The list item can be moved.| 67 68## SwipeEdgeEffect<sup>9+</sup> 69| Name | Value| Description | 70| ------ | ------ | --------- | 71| 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.| 72| 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.| 73 74## SwipeActionItem<sup>10+</sup> 75Describes the swipe action item. 76 77For 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). 78 79For 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). 80 81| Name | Type | Mandatory| Description | 82| -------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 83| 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.| 84| 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.| 85| onEnterActionArea | () => void | No| Callback invoked each time the list item enters the delete area.| 86| onExitActionArea | () => void | No|Callback invoked each time the list item exits the delete area.| 87| 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).| 88## ListItemOptions<sup>10+</sup> 89 90| Name | Type | Mandatory| Description | 91| ----- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 92| 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>If this parameter is set to **ListItemStyle.CARD**, the default card style is applied, but only when **ListItemGroupStyle.CARD** is set for [\<ListItemGroup>](ts-container-listitemgroup.md).<br>In the default card style, the list item has a 48 vp height and 100% width. It can be in focus, hover, press, selected, or disable style depending on the state.<br>**NOTE**<br>In the default card style, the list has its **listDirection** attribute fixed at **Axis.Vertical** and **alignListItem** attribute at **ListItemAlign.Center**.<br>If **ListItemStyle.CARD** is set and **ListItemGroupStyle.CARD** is not, only some card styles and functions are available.| 93 94## ListItemStyle<sup>10+</sup> 95 96| Name| Value | Description | 97| ---- | ---- | ------------------ | 98| NONE | 0 | No style. | 99| CARD | 1 | Default card style.| 100 101 102## Events 103 104| Name| Description| 105| -------- | -------- | 106| onSelect(event: (isSelected: boolean) => void)<sup>8+</sup> | Triggered when the selected state of the **\<ListItem>** changes.<br>**isSelected**: Returns **true** if the **\<ListItem>** is selected by mouse drag; returns **false** otherwise.| 107 108## Example 109 110### Example 1 111 112```ts 113// xxx.ets 114@Entry 115@Component 116struct ListItemExample { 117 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 118 119 build() { 120 Column() { 121 List({ space: 20, initialIndex: 0 }) { 122 ForEach(this.arr, (item: number) => { 123 ListItem() { 124 Text('' + item) 125 .width('100%') 126 .height(100) 127 .fontSize(16) 128 .textAlign(TextAlign.Center) 129 .borderRadius(10) 130 .backgroundColor(0xFFFFFF) 131 } 132 }, (item: string) => item) 133 }.width('90%') 134 .scrollBar(BarState.Off) 135 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 136 } 137} 138``` 139 140 141 142### Example 2 143 144 145```ts 146// xxx.ets 147@Entry 148@Component 149struct ListItemExample2 { 150 @State arr: number[] = [0, 1, 2, 3, 4] 151 @State enterEndDeleteAreaString: string = "not enterEndDeleteArea" 152 @State exitEndDeleteAreaString: string = "not exitEndDeleteArea" 153 154 @Builder itemEnd() { 155 Row() { 156 Button("Delete").margin("4vp") 157 Button("Set").margin("4vp") 158 }.padding("4vp").justifyContent(FlexAlign.SpaceEvenly) 159 } 160 161 build() { 162 Column() { 163 List({ space: 10 }) { 164 ForEach(this.arr, (item: number) => { 165 ListItem() { 166 Text("item" + item) 167 .width('100%') 168 .height(100) 169 .fontSize(16) 170 .textAlign(TextAlign.Center) 171 .borderRadius(10) 172 .backgroundColor(0xFFFFFF) 173 } 174 .transition({ type: TransitionType.Delete, opacity: 0 }) 175 .swipeAction({ 176 end: { 177 builder: () => { this.itemEnd() }, 178 onAction: () => { 179 animateTo({ duration: 1000 }, () => { 180 let index = this.arr.indexOf(item) 181 this.arr.splice(index, 1) 182 }) 183 }, 184 actionAreaDistance: 56, 185 onEnterActionArea: () => { 186 this.enterEndDeleteAreaString = "enterEndDeleteArea" 187 this.exitEndDeleteAreaString = "not exitEndDeleteArea" 188 }, 189 onExitActionArea: () => { 190 this.enterEndDeleteAreaString = "not enterEndDeleteArea" 191 this.exitEndDeleteAreaString = "exitEndDeleteArea" 192 } 193 } 194 }) 195 }, (item: string) => item) 196 } 197 Text(this.enterEndDeleteAreaString).fontSize(20) 198 Text(this.exitEndDeleteAreaString).fontSize(20) 199 } 200 .padding(10) 201 .backgroundColor(0xDCDCDC) 202 .width('100%') 203 .height('100%') 204 } 205} 206``` 207 208 209### Example 3 210 211```ts 212// xxx.ets 213@Entry 214@Component 215struct ListItemExample3 { 216 build() { 217 Column() { 218 List({ space: "4vp", initialIndex: 0 }) { 219 ListItemGroup({ style: ListItemGroupStyle.CARD }) { 220 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 221 ListItem({ style: itemStyle }) { 222 Text("" + index) 223 .width("100%") 224 .textAlign(TextAlign.Center) 225 } 226 }) 227 } 228 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 229 ListItem({ style: itemStyle }) { 230 Text("" + index) 231 .width("100%") 232 .textAlign(TextAlign.Center) 233 } 234 }) 235 } 236 .width('100%') 237 .multiSelectable(true) 238 .backgroundColor(0xDCDCDC) 239 } 240 .width('100%') 241 .padding({ top: 5 }) 242 } 243} 244``` 245 246
