[HarmonyOS NEXT 实战案例九:List系列] 分组列表组件实战：打造分类设置菜单 基础篇

项目已开源，开源地址： https://gitcode.com/nutpi/HarmonyosNextCaseStudyTutorial ， 欢迎fork & star

效果演示

一、ListItemGroup组件基础介绍

在HarmonyOS NEXT应用开发中，ListItemGroup组件是List组件的扩展，用于创建具有分组功能的列表。它能够将列表项按照逻辑关系进行分组，每个分组可以有自己的头部和尾部，使界面结构更加清晰，提升用户体验。

1.1 ListItemGroup组件特点

特点	说明
分组显示	将相关的列表项组织在一起，形成逻辑分组
自定义头部	支持为每个分组定制头部内容，如分组标题
自定义尾部	支持为每个分组定制尾部内容，如分组总结或分隔区域
折叠展开	支持分组的折叠和展开功能（需要自行实现）
嵌套使用	可以在List组件中嵌套使用，创建多级分组

1.2 ListItemGroup组件常用属性

属性	类型	说明
header	@Builder	分组的头部构建器
footer	@Builder	分组的尾部构建器
space	number	分组内列表项之间的间距
divider	{ strokeWidth?: number, color?: ResourceColor, startMargin?: number, endMargin?: number }	分组内列表项之间的分割线样式

二、分组设置菜单实战案例

2.1 需求分析

我们将实现一个分组设置菜单，包含以下功能：

1. 将设置项按照功能分为多个组：通用、隐私与安全、关于
2. 每个分组有明显的标题
3. 设置项包含图标、标题和右侧内容（文本或开关）
4. 分组之间有明显的视觉分隔

2.2 数据模型定义

首先，我们定义设置项和分组的数据模型：

interface ItemsType {
    title: string,
    icon: Resource,
    rightText?: string,
    toggle?: boolean
}

interface SettingType{
    groupName: string,
    items: ItemsType[]
}

然后，准备设置项数据：

private settingsData: SettingType[] = [
    {
        groupName: '通用',
        items: [
            { title: '语言', icon: $r('app.media.01'), rightText: '简体中文' },
            { title: '字体大小', icon: $r('app.media.02'), rightText: '标准' },
            { title: '存储空间', icon: $r('app.media.03'), rightText: '1.2GB可用' },
            { title: '清除缓存', icon: $r('app.media.04') }
        ]
    },
    {
        groupName: '隐私与安全',
        items: [
            { title: '锁屏密码', icon: $r('app.media.note_icon'), toggle: true },
            { title: '指纹解锁', icon: $r('app.media.music_icon'), toggle: true },
            { title: '隐私政策', icon: $r('app.media.game_icon') },
            { title: '权限管理', icon: $r('app.media.dcc_health_icon') }
        ]
    },
    {
        groupName: '关于',
        items: [
            { title: '版本信息', icon: $r('app.media.img'), rightText: 'v1.0.0' },
            { title: '检查更新', icon: $r('app.media.dcc_health_icon') },
            { title: '用户协议', icon: $r('app.media.game_icon') },
            { title: '帮助与反馈', icon: $r('app.media.map_icon2') }
        ]
    }
]

2.3 分组头部和尾部实现

接下来，我们实现分组的头部和尾部：

// 构建分组头部
@Builder
GroupHeader(groupName: string) {
    Text(groupName)
        .fontSize(16)
        .fontWeight(FontWeight.Medium)
        .backgroundColor('#F1F3F5')
        .width('100%')
        .padding({ left: 16, top: 12, bottom: 12 })
}

// 构建分组底部
@Builder
GroupFooter() {
    Row()
        .height(16)
        .width('100%')
        .backgroundColor('#F1F3F5')
}

分组头部显示分组名称，底部则是一个高度为16的空白区域，用于分隔不同的分组。

2.4 页面结构设计

整个页面采用垂直布局，包含标题栏和设置列表两部分：

build() {
    Column() {
        // 标题栏
        Row() {
            Text('设置')
                .fontSize(24)
                .fontWeight(FontWeight.Bold)
        }
        .width('100%')
        .height(56)
        .padding({ left: 16 })
        .backgroundColor('#F1F3F5')

        // 设置列表
        List() {
            // 列表内容
        }
        .width('100%')
        .layoutWeight(1)
        .divider({
            strokeWidth: 1,
            color: '#E5E5E5',
            startMargin: 56,
            endMargin: 16
        })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#FFFFFF')
}

2.5 分组列表实现

最后，我们实现分组列表的内容：

List() {
    ForEach(this.settingsData, (group:SettingType) => {
        ListItemGroup({
            header: this.GroupHeader(group.groupName),
            footer: this.GroupFooter()
        }) {
            ForEach(group.items, (item:ItemsType) => {
                ListItem() {
                    Row() {
                        // 图标
                        Image(item.icon)
                            .width(24)
                            .height(24)
                            .margin({ right: 16 })

                        // 标题
                        Text(item.title)
                            .fontSize(16)
                            .layoutWeight(1)

                        // 右侧文本或开关
                        if (item.rightText) {
                            Text(item.rightText)
                                .fontSize(14)
                                .fontColor('#666666')
                                .margin({ right: 8 })
                        }

                        if (item.toggle !== undefined) {
                            Toggle({ type: ToggleType.Switch, isOn: item.toggle })
                        } else {
                            Image($r('app.media.arrowright'))
                                .width(16)
                                .height(16)
                        }
                    }
                    .width('100%')
                    .padding({ left: 16, right: 16, top: 12, bottom: 12 })
                }
                .height(56)
            })
        }
    })
}

在这段代码中：

1. 使用ForEach遍历settingsData数组，为每个分组创建一个ListItemGroup
2. 为每个ListItemGroup设置header和footer
3. 在ListItemGroup内部，使用ForEach遍历分组内的items数组，为每个设置项创建一个ListItem
4. 在ListItem内部，使用Row布局包含图标、标题和右侧内容（文本、开关或箭头图标）

三、完整代码解析

@Component
export struct BasicListItemGroup {
    // 设置项数据
    private settingsData: SettingType[] = [
        // 数据定义（同上）
    ]

    // 构建分组头部
    @Builder
    GroupHeader(groupName: string) {
        // 头部实现（同上）
    }

    // 构建分组底部
    @Builder
    GroupFooter() {
        // 底部实现（同上）
    }

    build() {
        Column() {
            // 标题栏
            Row() {
                // 标题栏实现（同上）
            }

            // 设置列表
            List() {
                // 列表实现（同上）
            }
            .width('100%')
            .layoutWeight(1)
            .divider({
                strokeWidth: 1,
                color: '#E5E5E5',
                startMargin: 56,
                endMargin: 16
            })
        }
        .width('100%')
        .height('100%')
        .backgroundColor('#FFFFFF')
    }
}

3.1 代码结构分析

部分	说明
数据模型	定义ItemsType和SettingType接口，描述设置项和分组的数据结构
数据准备	创建settingsData数组，包含三个分组的设置项数据
构建器	定义GroupHeader和GroupFooter两个构建器，用于创建分组的头部和尾部
页面结构	使用Column作为根容器，包含标题栏和设置列表
分组列表	使用List和ListItemGroup创建分组列表，每个分组包含多个ListItem

3.2 样式设置分析

在这个案例中，我们使用了多种样式设置来美化界面：

1. 尺寸设置：

   • 使用width('100%')和height('100%')使组件占满父容器
   • 使用layoutWeight(1)使List组件占据剩余空间
   • 设置具体的像素值，如height(56)、width(24)等

2. 边距和填充：

   • 使用padding设置内边距
   • 使用margin设置外边距

3. 颜色和背景：

   • 设置背景颜色backgroundColor
   • 设置文本颜色fontColor

4. 文本样式：

   • 设置字体大小fontSize
   • 设置字体粗细fontWeight

5. 分割线：

   • 使用divider设置列表项之间的分割线
   • 设置分割线的颜色、粗细和边距

总结

在本篇教程中，我们学习了如何使用HarmonyOS NEXT的ListItemGroup组件创建一个分组的设置菜单。我们从数据模型定义、分组头部和尾部实现、页面结构设计到分组列表实现，全面讲解了分组列表的实现过程。