鸿蒙开发实战:详解 List 列表组件与数据联动

今天我们来深入探讨鸿蒙开发中非常核心的一个组件——列表（List）。

在移动应用开发中，列表几乎无处不在。它是一种常用的 UI 容器，主要功能是自动按滚动方向排列子组件。在 ArkTS 中，我们通常使用 List、ListItem 和 ListItemGroup 这三个组件配合来展示列表数据。

注意：List 是一个“严格”的容器，它的直接子组件必须是 ListItemGroup 或 ListItem。也就是说，你不能直接在 List 里面写 Text 或 Button，它们必须被包裹在 ListItem 中。

1. 基础布局：确定滚动方向

列表是横着滚还是竖着滚？这取决于列表的“主轴方向”。

我们可以通过设置 List 组件的 listDirection 属性来控制它。

1build() {2    Column() {3        // 设置为水平滚动4        List() {5            // ... ListItem 放在这里6        }7        .listDirection(Axis.Horizontal)8    }9}

2. 实战演练：构建一个 TodoList 应用

为了更好地理解 List 的用法，我们来做一个经典的 TodoList（待办事项） 应用。

2.1 鸿蒙的数据驱动 UI（MVVM）

在开始写代码前，我们需要理解鸿蒙 UI 的核心机制。鸿蒙采用的是 MVVM（Model-View-ViewModel） 模式，简单来说就是数据驱动 UI。

如果你有 Vue 的开发经验，会发现这非常眼熟。我们需要用 @State 装饰器来修饰那些“会变化的数据”。当数据变了，UI 会自动刷新。

由浅入深的例子：

 1@State 2message: string = '' 3 4build() { 5  Column() { 6    Text(this.message) 7    // 点击按钮修改变量，Text 组件会自动更新内容 8    Button('Change Message').onClick(() => { this.message = 'hello world' }) 9  }10}

这种体验非常流畅。但在处理列表这种复杂数据时，ArkTS 提供了一种更强大的机制，允许子组件直接修改父组件传入的数据，并同步更新父组件的 UI。

2.2 进阶痛点：@State 的“浅层监听”陷阱

在开发列表时，我们经常会遇到一个坑：数组或对象内部的属性变了，但 UI 没动。

这是因为 @State 装饰器默认只能监听到第一层数据的变化（引用变化）。

举个反例：

 1@State 2obj: TestObj = { 3  name: 'zhangsan', 4  hobbies: ['basketball', 'soccer'] 5} 6 7// 修改 obj.name，UI 会更新（第一层） 8this.obj.name = 'lisi'; 910// 修改数组内部元素，UI 不会更新！（因为 obj 的引用地址没变）11this.obj.hobbies[1] = 'tennis';

解决方案：为了监听嵌套对象或数组内部的变化，我们需要配合使用 @Observed（修饰类）和 @ObjectLink（修饰子组件接收的变量）。

2.3 编写 TodoList 数据模型

基于上面的知识，我们首先定义 TodoList 的数据结构。必须使用 @Observed 装饰类，否则后续在数组中修改对象的属性（如是否完成）时，UI 无法感知。

 1interface ITodo { 2  index: number; 3  desc: string; 4  completed: boolean; 5} 6 7// 关键点：使用 @Observed 修饰类，让其实例变得“可观察” 8@Observed 9class TodoItem implements ITodo {10  public desc: string = "";11  public completed: boolean = false;12  public index: number = 0;1314  constructor(index: number, desc: string) {15    this.desc = desc;16    this.index = index;17  }18}

2.4 编写子组件（列表项）

接下来是列表中每一项的 UI 实现。这里有两点需要注意：

1. 使用 @ObjectLink 接收父组件传来的 TodoItem，实现双向同步。
2. 使用 @BuilderParam 接收父组件传递的 UI 构建函数（用于删除按钮）。

 1@Component 2struct TodoItemView { 3    // 使用 @ObjectLink 接收数据，当 item 内部属性变化时，此组件会刷新 4    @ObjectLink 5    item: TodoItem; 6 7    // 接收父组件传递过来的 UI 构建逻辑 8    // 这里的参数是一个函数，该函数接收 index 并返回 void 9    @BuilderParam10    deleteButtonBuilder?: (index: number) => void;1112    build() {13        ListItem() {14            Flex({ justifyContent: FlexAlign.SpaceAround, alignItems: ItemAlign.Center }) {15                // 待办事项文本16                Text(this.item.desc)17                    .width(200)18                    .padding(20)19                    .decoration({20                        // 根据完成状态显示删除线21                        type: this.item.completed ? TextDecorationType.LineThrough : TextDecorationType.None,22                        color: Color.Black23                    })2425                // 状态文本26                Text(this.item.completed ? '完成' : '未完成')2728                // 切换状态按钮29                // 亮点：直接修改 this.item.completed，父组件的数据也会同步改变！30                Button(!this.item.completed ? '✅' : '❌')31                    .onClick(() => {32                        this.item.completed = !this.item.completed33                    })3435                // 如果父组件传递了删除按钮的构建逻辑，则渲染它36                if (this.deleteButtonBuilder) {37                    this.deleteButtonBuilder(this.item.index)38                }39            }40        }41    }42}

关于 deleteButtonBuilder 的补充说明：为什么要从父组件传一个 UI Builder 进来，而不是直接在子组件里写一个删除按钮？这就涉及到了数据权限的问题。列表数据 list 实际上保存在父组件中。虽然子组件可以修改 item 自身的属性（如 completed），但子组件无法把自己从父组件的数组中“移除”（即 splice 操作）。因此，删除操作的逻辑必须在父组件执行。

通过 @BuilderParam，父组件可以把“怎么长样子”和“点击干什么”都封装好传给子组件，子组件只负责展示。

2.5 父组件实现

最后是入口组件。我们需要在这里处理列表的增删逻辑。

 1@Component 2struct TodoList { 3    // 这里的 list 也是通过 @ObjectLink 或者是 @Link 等方式从更上层传来，或者直接 @State 定义 4    // 为了演示清晰，我们假设它是由上层 Index 传入的响应式数据 5    @ObjectLink 6    list: TodoItem[]; 7 8    // 定义删除按钮的构建逻辑 9    // 注意：@Builder 装饰器用于定义 UI 构建函数10    @Builder11    deleteButtonBuilder(index: number) {12        Button('删除')13            .onClick(() => {14                console.log('delete todolist item: ', index);15                // 执行删除操作，UI 会自动刷新16                this.list.splice(index, 1);17                // 注意：删除后需要重新校准后续 item 的 index，18                // 或者在真实项目中使用唯一 ID 而非 index 作为 key19                this.updateIndexes();20            })21    }2223    // 辅助方法：更新索引（简化演示用）24    updateIndexes() {25        this.list.forEach((item, idx) => item.index = idx);26    }2728    build() {29        List() {30            // 循环渲染列表31            ForEach(this.list, (item: TodoItem) => {32                TodoItemView({33                    item: item,34                    // 传递 UI 构建函数35                    // 关键点：使用箭头函数包裹，确保 this 指向父组件实例36                    deleteButtonBuilder: (index: number) => {37                        this.deleteButtonBuilder(index)38                    }39                })40            })41        }42    }43}

2.6 应用入口 (Index)

将所有部分组合在一起：

 1@Entry 2@Component 3struct Index { 4    // 初始化空数组，用于存放 TodoItem 5    @State 6    todoList: TodoItem[] = []; 7    @State 8    inputText: string = '' 910    build() {11        Row() {12            Column() {13                Text('待办列表').fontSize(24).margin({ bottom: 20 })1415                // 输入区域16                Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {17                    TextInput({ text: this.inputText, placeholder: '输入待办事项' })18                        .onChange((v: string) => {19                            this.inputText = v;20                        })21                        .flexGrow(1)2223                    Button('Add')24                        .onClick(() => {25                            if (this.inputText.trim() === '') return;26                            // 添加新项27                            this.todoList.push(new TodoItem(this.todoList.length, this.inputText))28                            this.inputText = ''; // 清空输入框29                        })30                        .margin({ left: 10 })31                        .width(80)32                }33                .width('90%')34                .margin({ bottom: 20 })3536                // 调试用：显示当前输入37                Text(`当前输入: ${this.inputText}`).fontSize(12).fontColor(Color.Gray)3839                Divider().margin(10)4041                // 列表区域42                TodoList({ list: $todoList })43            }44            .alignSelf(ItemAlign.Start)45            .width('100%')46        }47        .height('100%')48    }49}

总结

通过这个实战，我们掌握了：

1. List 组件
   ：必须配合 ListItem 使用。
2. 数据观测
   ：使用 @Observed 和 @ObjectLink 解决嵌套对象更新不刷新的问题。
3. 组件通信
   ：子组件通过直接修改对象属性同步父组件数据，以及通过 @BuilderParam 复用父组件的构建逻辑。

希望这篇文章能帮你更好地理解鸿蒙的列表开发！

完整项目地址：arkts-example-List:the demo for List UI Componet usage. - AtomGit:

https://gitcode.com/cymo/arkts-example-List