鸿蒙开发入门：通过ListItemGroup实现列表分组展示及吸顶吸底效果

浏览43发布于2026-06-08 15:21山东

ListItemGroup是鸿蒙系统中用于实现列表分组展示的核心组件，它必须作为List组件的子组件使用，List、ListItem、ListItemGroup构成了三层架构，其层级关系如下：

收起
自动换行
深色代码主题
复制
List
├── ListItemGroup（分组容器）
│   ├── ListItem（列表项1）
│   ├── ListItem（列表项2）
├── ListItem（独立列表项）

我们通过实际代码来看一下用法：

收起
自动换行
深色代码主题
复制
// 定义数据项接口
interface DataGroup {
  title: string;
  items: string[];
}

@Entry
@Component
struct TestListItemGroupPage {
  private dataGroups: DataGroup[] = [
    { title: '2026年', items: ['事件1', '事件2', '事件3', '事件2', '事件3', '事件2', '事件3'] },
    { title: '2025年', items: ['事件1', '事件5', '事件5', '事件5', '事件5', '事件5', '事件5'] },
  ]

  // 分组头部——即年份分隔条
  @Builder
  groupHeader(title: string) {
    Column() {
      Divider()
        .color('#ffff8400')
        .strokeWidth(5)
      Text(title)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .backgroundColor('#fff1f3f5')
        .width('100%')
        .padding({ left: 16, top: 10, bottom: 10 })
    }
  }

  // 分组底部
  @Builder
  groupFooter() {
    Divider()
      .color('#ff003aff')
      .strokeWidth(5)
  }

  build() {
    List({ space: 0 }) {
      ForEach(this.dataGroups, (group: DataGroup) => {
        ListItemGroup({ header: this.groupHeader(group.title), footer: this.groupFooter() }) {
          ForEach(group.items, (item: string) => {
            ListItem() {
              Text(item)
                .width('100%')
                .height(60)
                .fontSize(16)
                .padding({ left: 16 })
            }
          }, (item: string, index) => item + '_' + index)
        }
        // 设置分组内 item 之间的分割线
        .divider({
          strokeWidth: 1,
          //color: '#e5e5e5',
          color: '#ffff0000',
          startMargin: 16,
          endMargin: 0
        })
      })
    }
    .sticky(StickyStyle.Header) // 吸顶效果，需要配合ListItemGroup使用
    //.sticky(StickyStyle.Footer)  // 吸底效果，需要配合ListItemGroup使用
    //.sticky(StickyStyle.Header | StickyStyle.Footer) // 吸顶+吸底效果，需要配合ListItemGroup使用
    //.sticky(StickyStyle.BOTH) // API20开始支持，吸顶+吸底效果，需要配合ListItemGroup使用
    .width('100%')
    .height('100%')
  }
}