#我的鸿蒙开发手记#HarmonyOS ArkTS 组件进阶—ListItem 全面自学指南原创精华

李游LEO

发布于 2025-5-15 10:53

浏览

0收藏

一、ListItem 是什么？什么时候要用它？

在 ArkTS 里做 UI，如果你要展示一堆“有规律、可操作”的列表内容，比如待办清单、联系人、消息列表，ListItem 就是你的首选“列表单元格”组件。

注意：ListItem 只能配合 List 或 ListItemGroup 使用，自己单飞是没用的。

它最初从 API 7 支持到现在，功能越来越多，滑动删除、卡片样式、选中、多选、滑动操作……全都能玩，适合做复杂的业务型列表。

二、ListItem 的基本用法——最简单的案例入门

假如你就是想简单罗列一组内容，先来个最简版体验下：

@Entry
@Component
struct SimpleListDemo {
  private items: string[] = ['鸿蒙', 'ArkTS', '组件', '自学指南']

  build() {
    Column() {
      List({ space: 14 }) { // 控制item间距
        ForEach(this.items, (item: string, idx: number) => {
          ListItem() {
            Text(`#${idx + 1}：${item}`)
              .fontSize(17)
              .width('100%')
              .padding(12)
              .backgroundColor(0xF7F7F7)
              .borderRadius(8)
              .margin({ bottom: 2 })
          }
        })
      }
      .width('92%')
      .backgroundColor(0xE9E9EF)
      .padding({ top: 10 })
    }
    .alignItems(HorizontalAlign.Center)
    .height('100%')
  }
}

#我的鸿蒙开发手记#HarmonyOS ArkTS 组件进阶—ListItem 全面自学指南-鸿蒙开发者社区

几点说明：

列表元素就是ListItem，里面你想放啥都行，只能有一个直接子组件（可以是Row/Column/Text等）。
记得外层用List包起来，不然直接用 ListItem 会报错。

三、选中态/多选 & 高级交互（selected/selectable）

默认 ListItem 是能被鼠标框选的，如果想定制“选中”效果，可以用 selected 属性，双向绑定支持“点谁谁高亮”，适合做选择类的交互。

@Entry
@Component
struct SelectableListDemo {
  @State selectedIdx: number = 0
  private fruits: string[] = ['苹果', '香蕉', '橙子', '柚子']

  build() {
    Column() {
      List({ space: 8 }) {
        ForEach(this.fruits, (name: string, idx: number) => {
          ListItem() {
            Text(name)
              .width('100%')
              .fontSize(18)
              .textAlign(TextAlign.Center)
              .backgroundColor(this.selectedIdx === idx ? 0xFFF7D6 : 0xFFFFFF)
              .padding(16)
          }
          .selected(this.selectedIdx === idx)
          .onClick(() => {
            this.selectedIdx = idx
          })
        })
      }
      .width('90%')
      .border({ width: 1, color: 0xCCCCCC })
    }
    .width('100%').height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

#我的鸿蒙开发手记#HarmonyOS ArkTS 组件进阶—ListItem 全面自学指南-鸿蒙开发者社区

技巧点：

用selected() + 自己控制的@State变量，交互逻辑清晰，且样式自定义方便。
也可以加 .multiSelectable(true) 实现多选，这里就不展开了。

四、进阶操作——滑动删除与自定义滑动区（swipeAction）

有时候你想加点“左滑删除、右滑更多”的体验？
ListItem 的 swipeAction 属性直接满足你，还能自定义滑动区的内容，想怎么组合都行。
#我的鸿蒙开发手记#HarmonyOS ArkTS 组件进阶—ListItem 全面自学指南-鸿蒙开发者社区
实用建议：

builder 区自定义内容很灵活，但最多只放一个组件，想放两个就包个 Row/Column。
actionAreaDistance 控制滑到多少距离才触发长距离删除操作，建议不要设置得太小，不然容易误删。
建议配合 scroller 使用，能随时关闭所有滑动区。

五、ListItem 卡片样式的正确姿势

想要让你的 List 看起来更有“卡片感”？ListItem 支持内置卡片风格（ListItemStyle.CARD），但推荐和 ListItemGroup 组合用，这样布局更工整，视觉更统一。

@Entry
@Component
struct CardStyleListDemo {
  build() {
    Column() {
      List({ space: 8 }) {
        ListItemGroup({ style: ListItemGroupStyle.CARD }) {
          ForEach(['一号', '二号', '三号'], (name: string, idx: number) => {
            ListItem({ style: ListItemStyle.CARD }) {
              Text(`卡片：${name}`)
                .width('100%')
                .fontSize(18)
                .padding(18)
            }
          })
        }
      }
      .width('95%')
      .backgroundColor(0xEFF7FF)
      .multiSelectable(true)
      .padding({ top: 12 })
    }
    .alignItems(HorizontalAlign.Center)
    .width('100%').height('100%')
  }
}

#我的鸿蒙开发手记#HarmonyOS ArkTS 组件进阶—ListItem 全面自学指南-鸿蒙开发者社区

特别提醒：

如果用卡片模式，List 的方向建议默认竖直，横向模式下卡片样式可能会乱掉。
配合 Group 的 Card 样式，列表分组、分割线、分区头都很容易做出来。

六、更多常用属性和小知识

selectable()：控制单个 ListItem 是否可被框选，默认是 true，业务需要时可以设为 false。
onSelect()：监听框选状态变化，用于做批量操作，比如批量删除、批量导出。
swipeAction 下的 onAction/onEnterActionArea/onExitActionArea：做复杂交互时特别有用，比如滑动到某个区间提示用户“将要删除”。
老版属性如 sticky、editable 已废弃，不建议新项目再用，直接用 List 或 ListItemGroup 的新能力。