HarmonyOS List 组件完全指南：从接口参数到设置页实战

黄健华Yeah

282人浏览 · 2026-08-06 09:41:26

黄健华Yeah · 2026-08-06 09:41:26 发布

引言

在应用开发中，列表展示是非常常见的业务场景，如通讯录、音乐列表、购物清单、设置页菜单等。List 组件是 HarmonyOS 中用于高效展示结构化可滚动信息的容器组件，支持不同类型数据的组合展示（如文字+图片）。本节课将以个人设置页为例，系统讲解 List 组件的接口参数、常用属性、层级关系及完整开发流程。

核心内容

设置页面结构分析

个人设置页整体采用纵向 Column 布局，从上到下分为四个部分：

页面区域	选用组件	功能说明
标题区域	`Text`	展示"我的"标题
用户信息区域	`Row` + `Image` + `Text`	横向排列头像与用户信息
核心列表区域	`List`	展示可滚动结构化列表内容
底部按钮区域	`Button`	展示"退出登录"按钮

设置页核心内容为 List 列表区域，是本课学习的重点。

List 组件基础介绍

List 是可滚动复杂容器，适合高效展示结构化可滚动信息，支持不同类型数据组合（如文字+图片），常见场景包括通讯录、音乐列表、购物清单、设置页菜单等。

List 组件接口定义

List(value?: { space?: number | string, initialIndex?: number, scroller?: Scroller })

接口参数说明

参数	说明
`space`	设置 List 子组件主轴方向的间距，示例 `List({ space: 10 })` 会让每个 ListItem 之间产生 10vp 的间距
`initialIndex`	设置 List 初次加载时，视口起始位置显示的 item 的索引值，默认值为 0。设置为 `initialIndex: 1` 时，加载后第一个显示的 item 索引为 1
`scroller`	可滚动组件的控制器，用于控制 List 的滚动行为，需要先实例化后传入

Scroller 控制器使用

// 先实例化 Scroller
scroller: Scroller = new Scroller();

// 将实例传入 List
List({ scroller: this.scroller }) {
  // 列表内容
}

// 调用控制器方法
this.scroller.scrollTo(100);      // 滑动到指定位置
this.scroller.scrollEdge(Edge.Top); // 滚动到容器边缘（顶部）
this.scroller.scrollBy(0, 50);    // 向下滑动 50vp

List 组件常用属性

属性	说明
`listDirection`	设置 List 组件排列方向，参数为 Axis 枚举
`lanes`	设置 List 组件的布局列数（纵向）或行数（横向）
`divider`	设置 ListItem 之间分割线的样式，默认无分割线
`scrollBar`	设置滚动条的显示状态

listDirection

设置 List 组件的排列方向：

Axis.Vertical：默认值，方向为纵向，列表沿垂直方向排列
Axis.Horizontal：方向为横向，列表沿水平方向排列

lanes

设置 List 组件的布局列数（纵向）或行数（横向），可接受 number 或 LengthConstrain 类型参数，可选参数 gutter 设置列/行间距。

List() {
  // 列表内容
}
.lanes(2)  // 创建一个两列的垂直列表，默认值为 1

divider

设置 ListItem 之间分割线的样式，可以设置分割线的宽度、颜色、起点边距和终点边距。

List() {
  // 列表内容
}
.divider({
  strokeWidth: 1,
  color: '#e0e0e0',
  startMargin: 16,
  endMargin: 16
})

scrollBar

设置滚动条的显示状态：

取值	说明
`BarState.Auto`	默认状态，滚动时显示，停止滚动 2 秒后消失
`false`	滚动时始终隐藏滚动条
`BarState.On`	滚动条常驻显示

List 组件层级关系

结构规则：List 的子节点只能是 ListItem 或 ListItemGroup。

ListItem：单个列表项
ListItemGroup：用于给列表分组，内部放置多个 ListItem

分组用法：需要分组展示列表数据时，可以使用 List → ListItemGroup → ListItem 的三层结构。

List() {
  ListItemGroup() {
    ListItem() {
      // 分组1的列表项1
    }
    ListItem() {
      // 分组1的列表项2
    }
  }
  ListItemGroup() {
    ListItem() {
      // 分组2的列表项1
    }
    ListItem() {
      // 分组2的列表项2
    }
  }
}

使用 List 构建设置页实践

数据层准备

创建 item 数据类文件，定义列表项需要的属性：ID、展示文本、图标、开关状态等。
在 ViewModel 中定义获取列表数据的方法，使用二维数组保存分组后的列表数据，返回格式化后的列表数据。

// 列表项数据类
export class SettingItem {
  id: string = '';
  title: string = '';
  icon: Resource = $r('app.media.ic_default');
  isSwitch: boolean = false;
  isOn: boolean = false;
}

// ViewModel 中获取分组数据
getSettingData(): SettingItem[][] {
  return [
    [ /* 分组1的列表项 */ ],
    [ /* 分组2的列表项 */ ]
  ];
}

页面层实现

1. 分组展示：使用双层 ForEach 遍历二维数组，外层 ForEach 遍历分组对应 ListItemGroup，内层 ForEach 遍历列表项对应 ListItem。

@Builder
buildList() {
  List() {
    ForEach(this.settingData, (group: SettingItem[]) => {
      ListItemGroup() {
        ForEach(group, (item: SettingItem) => {
          ListItem() {
            this.buildListItem(item)
          }
        })
      }
    })
  }
}

2. 封装列表项组件：所有列表项结构一致，封装一个公共组件渲染：用 Row 横向布局，左侧放置图标，中间放置文本，右侧根据数据类型判断展示箭头或开关组件。

@Builder
buildListItem(item: SettingItem) {
  Row() {
    Image(item.icon)
      .width(24)
      .height(24)
    Text(item.title)
      .layoutWeight(1)
      .margin({ left: 12 })
    if (item.isSwitch) {
      Toggle({ type: ToggleType.Switch, isOn: item.isOn })
    } else {
      Image($r('app.media.ic_arrow'))
        .width(16)
        .height(16)
    }
  }
  .padding(16)
  .width('100%')
}

完整页面组装

整体使用 Column 纵向排列，从上到下依次放入：

Text 展示标题"我的"
Row 容器放入 Image 头像和 Text 用户信息
构建好的 List 列表区域
Button 展示"退出登录"按钮

@Entry
@Component
struct SettingPage {
  @State settingData: SettingItem[][] = getSettingData();

  build() {
    Column() {
      // 标题
      Text('我的')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .padding(16)

      // 用户信息
      Row() {
        Image($r('app.media.avatar'))
          .width(60)
          .height(60)
          .borderRadius(30)
        Column() {
          Text('用户名')
            .fontSize(18)
          Text('user@example.com')
            .fontSize(14)
            .fontColor('#999')
        }
        .margin({ left: 12 })
      }
      .padding(16)
      .width('100%')

      // 列表区域
      this.buildList()

      // 退出登录按钮
      Button('退出登录')
        .type(ButtonType.Capsule)
        .width('90%')
        .margin(16)
        .backgroundColor('#ff4444')
        .fontColor(Color.White)
        .onClick(() => {
          // 退出登录逻辑
        })
    }
    .width('100%')
    .height('100%')
  }
}

总结

本节课学习了 List 组件的核心知识：

应用场景：List 是可滚动复杂容器，适合高效展示结构化可滚动信息，支持不同类型数据组合。
接口参数：space（子组件间距）、initialIndex（初始显示位置索引）、scroller（滚动控制器，提供 scrollTo、scrollEdge、scrollBy 方法）。
常用属性：listDirection（排列方向）、lanes（列数/行数）、divider（分割线样式）、scrollBar（滚动条状态）。
层级结构：List 的子节点只能是 ListItem 或 ListItemGroup，分组场景使用 List → ListItemGroup → ListItem 三层结构。
实战流程：从数据层准备（定义数据类 → ViewModel 返回二维数组）到页面层实现（双层 ForEach 遍历 → 封装列表项组件 → 完整页面组装）。