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#sticky9)。 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（创建ListItem） 256该实例实现了创建ListItem的基本用法。 257 258```ts 259// xxx.ets 260@Entry 261@Component 262struct ListItemExample { 263 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 264 265 build() { 266 Column() { 267 List({ space: 20, initialIndex: 0 }) { 268 ForEach(this.arr, (item: number) => { 269 ListItem() { 270 Text('' + item) 271 .width('100%') 272 .height(100) 273 .fontSize(16) 274 .textAlign(TextAlign.Center) 275 .borderRadius(10) 276 .backgroundColor(0xFFFFFF) 277 } 278 }, (item: string) => item) 279 }.width('90%') 280 .scrollBar(BarState.Off) 281 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 282 } 283} 284``` 285 286 287 288### 示例2（设置划出组件） 289该示例展示了ListItem设置了swipeAction的横滑效果。 290 291```ts 292// xxx.ets 293@Entry 294@Component 295struct ListItemExample2 { 296 @State arr: number[] = [0, 1, 2, 3, 4] 297 @State enterEndDeleteAreaString: string = "not enterEndDeleteArea" 298 @State exitEndDeleteAreaString: string = "not exitEndDeleteArea" 299 private scroller: ListScroller = new ListScroller() 300 301 @Builder itemEnd() { 302 Row() { 303 Button("Delete").margin("4vp") 304 Button("Set").margin("4vp").onClick(() => { 305 this.scroller.closeAllSwipeActions() 306 }) 307 }.padding("4vp").justifyContent(FlexAlign.SpaceEvenly) 308 } 309 310 build() { 311 Column() { 312 List({ space: 10, scroller: this.scroller }) { 313 ForEach(this.arr, (item: number) => { 314 ListItem() { 315 Text("item" + item) 316 .width('100%') 317 .height(100) 318 .fontSize(16) 319 .textAlign(TextAlign.Center) 320 .borderRadius(10) 321 .backgroundColor(0xFFFFFF) 322 } 323 .transition({ type: TransitionType.Delete, opacity: 0 }) 324 .swipeAction({ 325 end: { 326 builder: () => { this.itemEnd() }, 327 onAction: () => { 328 animateTo({ duration: 1000 }, () => { 329 let index = this.arr.indexOf(item) 330 this.arr.splice(index, 1) 331 }) 332 }, 333 actionAreaDistance: 56, 334 onEnterActionArea: () => { 335 this.enterEndDeleteAreaString = "enterEndDeleteArea" 336 this.exitEndDeleteAreaString = "not exitEndDeleteArea" 337 }, 338 onExitActionArea: () => { 339 this.enterEndDeleteAreaString = "not enterEndDeleteArea" 340 this.exitEndDeleteAreaString = "exitEndDeleteArea" 341 } 342 } 343 }) 344 }, (item: string) => item) 345 } 346 Text(this.enterEndDeleteAreaString).fontSize(20) 347 Text(this.exitEndDeleteAreaString).fontSize(20) 348 } 349 .padding(10) 350 .backgroundColor(0xDCDCDC) 351 .width('100%') 352 .height('100%') 353 } 354} 355``` 356 357 358### 示例3（设置卡片样式） 359该示例展示了ListItem的卡片样式效果。 360 361```ts 362// xxx.ets 363@Entry 364@Component 365struct ListItemExample3 { 366 build() { 367 Column() { 368 List({ space: "4vp", initialIndex: 0 }) { 369 ListItemGroup({ style: ListItemGroupStyle.CARD }) { 370 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 371 ListItem({ style: itemStyle }) { 372 Text("" + index) 373 .width("100%") 374 .textAlign(TextAlign.Center) 375 } 376 }) 377 } 378 ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => { 379 ListItem({ style: itemStyle }) { 380 Text("" + index) 381 .width("100%") 382 .textAlign(TextAlign.Center) 383 } 384 }) 385 } 386 .width('100%') 387 .multiSelectable(true) 388 .backgroundColor(0xDCDCDC) 389 } 390 .width('100%') 391 .padding({ top: 5 }) 392 } 393} 394``` 395
