HarmonyOS（ArkTS）中 ForEach 的使用教程

下面是一篇关于 HarmonyOS（ArkTS）中 ForEach 的使用教程文章，结合了详细讲解与示例代码，适用于初学者和希望进一步掌握 ArkTS UI 编程的开发者。

⸻

鸿蒙 HarmonyOS 中 ForEach 的使用教程（含代码示例）

一、ForEach 是什么？

在 ArkTS（方舟 TypeScript）中，ForEach 是用于构建重复 UI 组件的声明式语法结构。通过 ForEach，你可以根据数组或数据集合动态生成视图，类似于其他框架中的 v-for（Vue）或 map()（React）。

⸻

二、使用场景

• 根据数据列表生成 UI 组件（如列表项、卡片、按钮等）

• 响应式刷新：当数据变化时，视图自动更新

• 可配合 @State、@Observed 等响应式数据源使用

⸻

三、基础用法

示例：渲染一个名字列表

@Entry
@Component
struct Index {
  @State names: string[] = ['张三', '李四', '王五', '赵六']

  build() {
    Column() {
      Text('学生名单')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .margin(10)

      ForEach(this.names, (item: string, index: number) => {
        Text(`${index + 1}. ${item}`)
          .fontSize(18)
          .padding(5)
      })
    }
    .padding(20)
  }
}

输出效果：

学生名单
1. 张三
2. 李四
3. 王五
4. 赵六

⸻

四、带交互功能的 ForEach 示例

我们可以结合 Button 和 @State 添加删除功能，实现一个动态可更新的列表。

@Entry
@Component
struct Index {
  @State names: string[] = ['张三', '李四', '王五']

  build() {
    Column({ space: 12 }) {
      Text('学生列表').fontSize(22).fontWeight(FontWeight.Bold)

      ForEach(this.names, (item: string, index: number) => {
        Row({ space: 10 }) {
          Text(`${index + 1}. ${item}`)
            .fontSize(18)

          Button('删除')
            .fontSize(14)
            .onClick(() => {
              this.names.splice(index, 1)
            })
        }
        .padding(5)
      })

      Button('添加学生')
        .onClick(() => {
          this.names.push('新学生')
        })
        .backgroundColor('#0A59F7')
        .fontColor(Color.White)
        .padding(10)
    }
    .padding(20)
  }
}

说明：

• 使用 splice(index, 1) 实现删除操作

• 使用 push() 添加新项

• 数据源变化时，界面自动刷新（因为使用了 @State）

⸻

五、ForEach 的键值优化（避免重复）

当你使用复杂数据结构（如对象数组）时，推荐显式设置 唯一 key 值，以提高渲染效率。

interface Student {
  id: number;
  name: string;
}

@Entry
@Component
struct Index {
  @State students: Student[] = [
    { id: 1, name: '张三' },
    { id: 2, name: '李四' }
  ]

  build() {
    Column({ space: 10 }) {
      Text('学生表').fontSize(22).fontWeight(FontWeight.Bold)

      ForEach(this.students, item => item.id, (item: Student) => {
        Text(`${item.id}: ${item.name}`)
          .fontSize(18)
          .padding(4)
      })
    }
    .padding(20)
  }
}

⸻

六、注意事项

• 注意点 说明

• 必须设置响应式数据（如 @State） 否则不会触发 UI 更新

• 尽量提供唯一 key（特别是对象列表） 否则 UI 可能出现重绘错误

• 可嵌套使用 ForEach 用于多层结构（如分类列表）

⸻

七、小练习：待办事项清单（TODO List）

@Entry
@Component
struct TodoList {
  @State todos: string[] = ['写代码', '测试功能', '提交 PR']
  @State newTodo: string = ''

  build() {
    Column({ space: 15 }) {
      Text('待办事项')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)

      ForEach(this.todos, (item: string, index: number) => {
        Row({ space: 10 }) {
          Text(`• ${item}`)
            .fontSize(18)

          Button('完成')
            .onClick(() => {
              this.todos.splice(index, 1)
            })
        }
      })

      TextInput({ placeholder: '输入新的待办事项' })
        .onChange((val: string) => this.newTodo = val)
        .textInputStyle({ fontSize: 16 })

      Button('添加')
        .onClick(() => {
          if (this.newTodo.trim().length > 0) {
            this.todos.push(this.newTodo)
            this.newTodo = ''
          }
        })
    }
    .padding(20)
  }
}

⸻

八、总结

• 功能 描述

• ForEach 用于遍历并动态生成 UI

• 支持索引 (item, index) 回调支持下标操作

• 支持键值优化 ForEach(list, keyFunc, callback)

• 配合响应式数据 自动触发 UI 刷新，适用于动态场景

⸻

九、官方文档参考

• ArkTS 语法指南 - ForEach

• HarmonyOS UI 组件开发

⸻