1# ListItem 2 3用来展示列表具体item，必须配合List来使用。 4 5> **说明：** 6> 7> - 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> - 该组件的父组件只能是[List](ts-container-list.md)或者[ListItemGroup](ts-container-listitemgroup.md)。 9> - 当ListItem配合LazyForEach使用时，ListItem子组件在ListItem创建时创建。配合if/else、ForEach使用时，或父组件为List/ListItemGroup时，ListItem子组件在ListItem布局时创建。 10 11## 子组件 12 13可以包含单个子组件。 14 15## 接口 16 17### ListItem<sup>10+</sup> 18 19ListItem(value?: ListItemOptions) 20 21**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 22 23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 31| value | [ListItemOptions](#listitemoptions10对象说明) | 否 | 为ListItem提供可选参数, 该对象内含有ListItemStyle枚举类型的style参数。 | 32 33### ListItem<sup>(deprecated)</sup> 34 35ListItem(value?: string) 36 37从API version 10开始, 该接口不再维护，推荐使用[ListItem<sup>10+</sup>](#listitem10)。 38 39**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 40 41**系统能力：** SystemCapability.ArkUI.ArkUI.Full 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| ------ | ----------------------------- | ---- | -------- | 47| value | string | 否 | 无 | 48 49## 属性 50 51除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 52 53### sticky<sup>(deprecated)</sup> 54 55sticky(value: Sticky) 56 57设置ListItem吸顶效果。 58 59从API version9开始废弃不再使用，推荐使用[List组件sticky属性](ts-container-list.md#属性)。 60 61**系统能力：** SystemCapability.ArkUI.ArkUI.Full 62 63**参数：** 64 65| 参数名 | 类型 | 必填 | 说明 | 66| ------ | ----------------------------------- | ---- | ------------------------------------------ | 67| value | [Sticky](#stickydeprecated枚举说明) | 是 | ListItem吸顶效果。<br/>默认值：Sticky.None | 68 69### editable<sup>(deprecated)</sup> 70 71editable(value: boolean | EditMode) 72 73设置当前ListItem元素是否可编辑，进入编辑模式后可删除或移动列表项。 74 75从API version9开始废弃不再使用，无替代接口。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79**参数：** 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------ | 83| value | boolean \| [EditMode](#editmodedeprecated枚举说明) | 是 | ListItem元素是否可编辑。<br/>默认值：false | 84 85### selectable<sup>8+</sup> 86 87selectable(value: boolean) 88 89设置当前ListItem元素是否可以被鼠标框选。外层List容器的鼠标框选开启时，ListItem的框选才生效。 90 91**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 92 93**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 94 95**系统能力：** SystemCapability.ArkUI.ArkUI.Full 96 97**参数：** 98 99| 参数名 | 类型 | 必填 | 说明 | 100| ------ | ------- | ---- | ------------------------------------------------- | 101| value | boolean | 是 | ListItem元素是否可以被鼠标框选。<br/>默认值：true | 102 103### selected<sup>10+</sup> 104 105selected(value: boolean) 106 107设置当前ListItem选中状态。该属性支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。该属性需要在设置[选中态样式](./ts-universal-attributes-polymorphic-style.md)前使用才能生效选中态样式。 108 109**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 110 111**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 112 113**系统能力：** SystemCapability.ArkUI.ArkUI.Full 114 115**参数：** 116 117| 参数名 | 类型 | 必填 | 说明 | 118| ------ | ------- | ---- | ---------------------------------------- | 119| value | boolean | 是 | 当前ListItem选中状态。<br/>默认值：false | 120 121### swipeAction<sup>9+</sup> 122 123swipeAction(value: SwipeActionOptions) 124 125用于设置ListItem的划出组件。 126 127**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| ------ | ------------------------------------------------- | ---- | -------------------- | 135| value | [SwipeActionOptions](#swipeactionoptions9对象说明) | 是 | ListItem的划出组件。 | 136 137## Sticky<sup>(deprecated)</sup>枚举说明 138从API version9开始废弃不再使用，推荐使用[List组件stickyStyle枚举](ts-container-list.md#stickystyle9枚举说明)。 139 140**系统能力：** SystemCapability.ArkUI.ArkUI.Full 141 142| 名称 | 值 | 说明 | 143| -------- | -------- | -------- | 144| None | 0 | 无吸顶效果。 | 145| Normal | 1 | 当前item吸顶。 | 146| Opacity | 2 | 当前item吸顶显示透明度变化效果。 | 147 148## EditMode<sup>(deprecated)</sup>枚举说明 149从API version9开始废弃不再使用，无替代接口。 150 151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 152 153| 名称 | 值 | 说明 | 154| ------ | ------ | --------- | 155| None | 0 | 编辑操作不限制。 | 156| Deletable | 1 | 可删除。 | 157| Movable | 2 | 可移动。 | 158 159## SwipeEdgeEffect<sup>9+</sup>枚举说明 160 161**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 162 163**系统能力：** SystemCapability.ArkUI.ArkUI.Full 164 165| 名称 | 值 | 说明 | 166| ------ | ------ | --------- | 167| Spring | 0 | ListItem划动距离超过划出组件大小后可以继续划动。<br>如果设置了删除区域，ListItem划动距离超过删除阈值后可以继续划动，<br/>松手后按照弹簧阻尼曲线回弹。 | 168| None | 1 | ListItem划动距离不能超过划出组件大小。<br>如果设置了删除区域，ListItem划动距离不能超过删除阈值，<br/>并且在设置删除回调的情况下，达到删除阈值后松手触发删除回调。 | 169 170## SwipeActionOptions<sup>9+</sup>对象说明 171 172start和end对应的@builder函数中顶层必须是单个组件，不能是if/else、ForEach、LazyForEach语句。 173 174滑动手势只在listItem区域上，如果子组件划出ListItem区域外，在ListItem以外部分不会响应划动手势。所以在多列模式下，建议不要将划出组件设置太宽。 175 176**系统能力：** SystemCapability.ArkUI.ArkUI.Full 177 178| 名称 | 类型 | 必填 | 说明 | 179| ---------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 180| start | [CustomBuilder](ts-types.md#custombuilder8) \| [SwipeActionItem](#swipeactionitem10对象说明) | 否 | ListItem向右划动时item左边的组件（List垂直布局时）或ListItem向下划动时item上方的组件（List水平布局时）。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 181| end | [CustomBuilder](ts-types.md#custombuilder8) \| [SwipeActionItem](#swipeactionitem10对象说明) | 否 | ListItem向左划动时item右边的组件（List垂直布局时）或ListItem向上划动时item下方的组件（List水平布局时）。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 182| edgeEffect | [SwipeEdgeEffect](#swipeedgeeffect9枚举说明) | 否 | 滑动效果。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 183| onOffsetChange<sup>11+</sup> | (offset: number) => void | 否 | 滑动操作偏移量更改时调用。 <br/>**说明：** <br/> 当列表项向左或向右滑动（当列表方向为“垂直”时），向上或向下滑动（当列方向为“水平”时）位置发生变化触发，以vp为单位。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 184 185## SwipeActionItem<sup>10+</sup>对象说明 186 187List垂直布局，ListItem向右滑动，item左边的长距离滑动删除选项或向左滑动时，item右边的长距离滑动删除选项。 188</br>List水平布局，ListItem向上滑动，item下边的长距离滑动删除选项或向下滑动时，item上边的长距离滑动删除选项。 189 190**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192| 名称 | 类型 | 必填 | 说明 | 193| -------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 194| actionAreaDistance | [Length](ts-types.md#length) | 否 | 设置组件长距离滑动删除距离阈值。<br/>默认值：56vp <br/>**说明：** <br/>不支持设置百分比。<br/>删除距离阈值大于item宽度减去划出组件宽度，或删除距离阈值小于等于0就不会设置删除区域。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 195| onAction | () => void | 否 | 组件进入长距删除区后删除ListItem时调用，进入长距删除区后抬手时触发。<br/>**说明：** <br/> 滑动后松手的位置超过或等于设置的距离阈值，并且设置的距离阈值有效时才会触发。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 196| onEnterActionArea | () => void | 否 | 在滑动条目进入删除区域时调用，只触发一次，当再次进入时仍触发。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 197| onExitActionArea | () => void | 否 |当滑动条目退出删除区域时调用，只触发一次，当再次退出时仍触发。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 198| builder | [CustomBuilder](ts-types.md#custombuilder8) | 否 |当列表项向左或向右滑动（当列表方向为“垂直”时），向上或向下滑动（当列方向为“水平”时）时显示的操作项。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 199| onStateChange<sup>11+</sup> | (state:[SwipeActionState](#swipeactionstate11枚举说明)) => void | 否 |当列表项滑动状态变化时候触发。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 200## ListItemOptions<sup>10+</sup>对象说明 201 202**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 203 204**系统能力：** SystemCapability.ArkUI.ArkUI.Full 205 206| 名称 | 类型 | 必填 | 说明 | 207| ----- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 208| style | [ListItemStyle](#listitemstyle10枚举说明) | 否 | 设置List组件卡片样式。<br/>默认值: ListItemStyle.NONE<br/>设置为ListItemStyle.NONE时无样式。<br/>设置为ListItemStyle.CARD时，建议配合[ListItemGroup](ts-container-listitemgroup.md)的ListItemGroupStyle.CARD同时使用，显示默认卡片样式。 <br/>卡片样式下，ListItem默认规格：高度48vp，宽度100%，左右内边距8vp。如果需要实现ListItem高度自适应，可以把height设置为undefined。<br/>卡片样式下, 为卡片内的列表选项提供了默认的focus、hover、press、selected和disable样式。<br/>**说明：**<br/>当前卡片模式下，使用默认Axis.Vertical排列方向，如果listDirection属性设置为Axis.Horizontal，会导致显示混乱；List属性alignListItem默认为ListItemAlign.Center，居中对齐显示。 | 209 210## ListItemStyle<sup>10+</sup>枚举说明 211 212**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 213 214**系统能力：** SystemCapability.ArkUI.ArkUI.Full 215 216| 名称 | 值 | 说明 | 217| ---- | ---- | ------------------ | 218| NONE | 0 | 无样式。 | 219| CARD | 1 | 显示默认卡片样式。 | 220 221## SwipeActionState<sup>11+</sup>枚举说明 222 223**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 224 225**系统能力：** SystemCapability.ArkUI.ArkUI.Full 226 227| 名称 | 值 | 说明 | 228| --------- | --------- | ------------------------------------------------------------ | 229| COLLAPSED | 0 | 收起状态，当ListItem向左或向右滑动（当列表方向为“垂直”时），<br/>向上或向下滑动（当列方向为“水平”时）时操作项处于隐藏状态。 | 230| EXPANDED | 1 | 展开状态，当ListItem向左或向右滑动（当列表方向为“垂直”时），<br/>向上或向下滑动（当列方向为“水平”时）时操作项处于显示状态。<br/>**说明：**<br/>需要ListItem设置向左或向右滑动（当列表方向为“垂直”时），<br/>向上或向下滑动（当列方向为“水平”时）时显示的操作项。 | 231| ACTIONING | 2 | 长距离状态，当ListItem进入长距删除区后删除ListItem的状态。<br/>**说明**:<br/>滑动后松手的位置超过或等于设置的距离阈值，并且设置的距离阈值有效时才能进入该状态。 | 232 233## 事件 234 235### onSelect<sup>8+</sup> 236 237onSelect(event: (isSelected: boolean) => void) 238 239ListItem元素被鼠标框选的状态改变时触发回调。 240 241**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 242 243**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 244 245**系统能力：** SystemCapability.ArkUI.ArkUI.Full 246 247**参数：** 248 249| 参数名 | 类型 | 必填 | 说明 | 250| ---------- | ------- | ---- | ------------------------------------------------------------ | 251| isSelected | boolean | 是 | 进入鼠标框选范围即被选中返回true， 移出鼠标框选范围即未被选中返回false。 | 252 253## 示例 254 255### 示例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### 示例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 private scroller: ListScroller = new ListScroller() 299 300 @Builder itemEnd() { 301 Row() { 302 Button("Delete").margin("4vp") 303 Button("Set").margin("4vp").onClick(() => { 304 this.scroller.closeAllSwipeActions() 305 }) 306 }.padding("4vp").justifyContent(FlexAlign.SpaceEvenly) 307 } 308 309 build() { 310 Column() { 311 List({ space: 10, scroller: this.scroller }) { 312 ForEach(this.arr, (item: number) => { 313 ListItem() { 314 Text("item" + item) 315 .width('100%') 316 .height(100) 317 .fontSize(16) 318 .textAlign(TextAlign.Center) 319 .borderRadius(10) 320 .backgroundColor(0xFFFFFF) 321 } 322 .transition({ type: TransitionType.Delete, opacity: 0 }) 323 .swipeAction({ 324 end: { 325 builder: () => { this.itemEnd() }, 326 onAction: () => { 327 animateTo({ duration: 1000 }, () => { 328 let index = this.arr.indexOf(item) 329 this.arr.splice(index, 1) 330 }) 331 }, 332 actionAreaDistance: 56, 333 onEnterActionArea: () => { 334 this.enterEndDeleteAreaString = "enterEndDeleteArea" 335 this.exitEndDeleteAreaString = "not exitEndDeleteArea" 336 }, 337 onExitActionArea: () => { 338 this.enterEndDeleteAreaString = "not enterEndDeleteArea" 339 this.exitEndDeleteAreaString = "exitEndDeleteArea" 340 } 341 } 342 }) 343 }, (item: string) => item) 344 } 345 Text(this.enterEndDeleteAreaString).fontSize(20) 346 Text(this.exitEndDeleteAreaString).fontSize(20) 347 } 348 .padding(10) 349 .backgroundColor(0xDCDCDC) 350 .width('100%') 351 .height('100%') 352 } 353} 354``` 355 356 357### 示例3 358 359```ts 360// xxx.ets 361@Entry 362@Component 363struct ListItemExample3 { 364 build() { 365 Column() { 366 List({ space: "4vp", initialIndex: 0 }) { 367 ListItemGroup({ style: ListItemGroupStyle.CARD }) { 368 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 369 ListItem({ style: itemStyle }) { 370 Text("" + index) 371 .width("100%") 372 .textAlign(TextAlign.Center) 373 } 374 }) 375 } 376 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 377 ListItem({ style: itemStyle }) { 378 Text("" + index) 379 .width("100%") 380 .textAlign(TextAlign.Center) 381 } 382 }) 383 } 384 .width('100%') 385 .multiSelectable(true) 386 .backgroundColor(0xDCDCDC) 387 } 388 .width('100%') 389 .padding({ top: 5 }) 390 } 391} 392``` 393
