ArkTS 进阶之道（13）：ForEach 循环渲染边界——为啥 build 里不能写 for 循环

ArkTS 进阶之道（13）：ForEach 循环渲染边界------为啥 build 里不能写 for 循环

本文是「ArkTS 进阶之道」系列第 13 篇，「ArkUI 渎染哲学」阶段收尾。上两篇讲渲染树绑定：build() 重渲边界（篇 60，@State 参只刷依赖 UI）+ if 条件渲染边界（篇 61，if 贬饰器绑渲染树分支）。本文讲循环渲染边界：build 里 for 循环报错 vs ForEach 循环渲染装饰器合法 ------根因在 ForEach 编译期绑渲染树循环项不是运行时 for 语句迭代。能力系列篇 18 讲过循环渲染怎么用，本文讲为哈 for 循环报错 ForEach 合法------根因在渲染树循环项绑定不是语句迭代。

一、开篇：build 里 for 不是循环是装饰器，绑渲染树循环项不是迭代执行

你写 TypeScript/React 时，循环渲染是「魔法」（JSX 里 for 循环不能直接写，要用 map 映射数组）：

// React JSX 里 for 循环不能直接写
function Component() {
  const list = ['一', '二', '三']
  return (
    <View>
      {/* for (let i = 0; i < list.length; i++) { <Text>{list[i]}</Text> }    ← JSX 里 for 不能直接写，报错 */}
      {list.map(item => <Text>{item</Text>)}    ← 要用 map 映射数组（魔法）
    </View>
  )
}
// JSX 里 for 循环不能直接写，要用 map 魔法绕

你写鸿蒙 ArkTS 时，build 里 ForEach 贬饰器直接写------不用 map 绕：

// ArkTS build 里 ForEach 贬饰器直接写
@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']
  build() {
    Column() {
      ForEach(this.list, (item: string) => {         ← ForEach 贬饰器直接写，合法（不是 for 循环）
        Text(item)                                   ← 每个元素绑一个 Text 渲染项
      }, (item: string) => item)                     ← keyGenerator 绑元素键值
    }
  }
}
// build 里 ForEach 贬饰器直接写合法，不用 map 绕（不是 for 循环）

魔法 vs 贬饰器的区别：React JSX 把循环渲染当「魔法」（for 循环不能写，map 绕），ArkTS 把 ForEach 当「循环渲染装饰器」（build 里 ForEach 直接写，编译期绑渲染树循环项）。根因不是魔法是渲染树循环项绑定------build 里 for 不是运行时迭代执行，是编译期绑渲染树循环项的装饰器。

二、根因：build 里 ForEach 贬饰器的渲染树循环项绑定机制

鸿蒙 ArkUI 的 build 里 ForEach 是渲染树循环项绑定------编译期把数组每个元素绑成渲染树循环项，运行时按数组变重渲循环项，不是运行时 for 语句迭代，来自三重绑定机制。

机制 1：ForEach 编译期绑渲染树循环项------不是运行时 for 迭代

ForEach 贬饰器编译期绑渲染树循环项------把数组每个元素编成渲染树的循环项，不是运行时迭代的 for 语句：

@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']
  build() {
    Column() {
      ForEach(this.list, (item: string) => {         ← ForEach 贬饰器编译期绑循环项
        Text(item)                                   ← 每个元素绑一个 Text 循环项
      }, (item: string) => item)                     ← keyGenerator 绑元素键值（'一'/'二'/'三')
    }
  }
}
// 编译期：ForEach 绑渲染树循环项1（Text'一'）+ 循环项2（Text'二'）+ 循环项3（Text'三')
// 运行时：按 list 数组渲染循环项（不是运行时 for 循环迭代）

编译期绑循环项 ：ForEach 贬饰器编译期把 list 数组每个元素绑成渲染树循环项------'一' 绑循环项1（Text'一'），'二' 绑循环项2（Text'二'），'三' 绑循环项3（Text'三'）。运行时按数组渲循环项------不是运行时 for 循环迭代执行，是编译期绑的渲染树循环项按数组渲。根因不是迭代是渲染树循环项绑定。

机制 2：数组变自动重渲循环项------不是运行时 for 语句迭代

ForEach 贬饰器数组变自动重渲循环项------数组增删触发重渲循环项，不是运行时 for 语句迭代：

@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']
  build() {
    Column() {
      ForEach(this.list, (item: string) => {
        Text(item)                                  ← 每个元素绑一个 Text 循环项
      }, (item: string) => item)
      Button('加元素')
        .onClick(() => { this.list.push('新') })     ← 数组变 ForEach 自动重渲循环项
    }
  }
}
// 数组加元素：ForEach 自动加循环项（Text'新'），不用 for 循环重新迭代
// 数组删元素：ForEach 自动删循环项，不用 for 循环重新迭代

数组变自动重渲 ：ForEach �贬饰器 list 数组变触发自动重渲循环项------push 加元素自动加循环项（Text'新'），splice 删元素自动删循环项。数组变不用 for 循环重新迭代，ForEach �贬饰器绑的循环项按数组变自动重渲。根因不是 for 语句迭代是渲染树循环项按数组变自动重渲。

机制 3：keyGenerator �绑元素键值------循环项追踪增删改

ForEach �贬饰器 keyGenerator 绑元素键值------给每个元素绑唯一键值，追踪循环项增删改：

@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']
  build() {
    Column() {
      ForEach(this.list, 
        (item: string) => { Text(item) },           ← itemGenerator 绑循环项内容
        (item: string) => item                      ← keyGenerator 绑元素键值（'一'/'二'/'三')
      )
    }
  }
}
// keyGenerator 绑键值：'一' → key='一'，'二' → key='二'，'三' → key='三'
// 数组变按 key 追踪：加 '新' → 加 key='新' 循环项，删 '一' → 删 key='一' 循环项

keyGenerator 绑键值追踪：ForEach 第三参 keyGenerator 给每个元素绑唯一键值------数组变按 key 追踪循环项增删改。加元素按 key 加循环项，删元素按 key 删循环项，改元素按 key 改循环项。不用 for 循环遍历比对，keyGenerator 绑的键值让 ForEach 按数组变精准追踪循环项。根因不是 for 遍历是 keyGenerator 绑键值追踪。

机制 4：for 语句报错边界------build 不是迭代执行流是渲染树

build 里 for 语句报错------build 是渲染树不是迭代执行流，for 语句是运行时迭代跟渲染树绑定冲突：

@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']
  build() {
    Column() {
      // ❌ for 循环报错（build 不是迭代执行流）
      // for (let i = 0; i < this.list.length; i++) { Text(this.list[i]) }    ← for 语句报错
      
      // ✅ ForEach 贬饰器合法（build 是渲染树，ForEach 绑循环项）
      ForEach(this.list, (item: string) => {
        Text(item)                                  ← ForEach 贬饰器绑渲染树循环项，合法
      }, (item: string) => item)
    }
  }
}
// for 语句报错根因：build 是渲染树不是迭代执行流，for 语句运行时迭代跟渲染树绑定冲突
// ForEach 贬饰器合法根因：ForEach 编译期绑渲染树循环项，运行时按数组变重渲不迭代

for 语句报错边界：build 里 for 语句报错根因是 build 是渲染树不是迭代执行流------for 语句是运行时迭代执行，跟渲染树编译期绑定冲突报错。ForEach 贬饰器合法根因是 ForEach 编译期绑渲染树循环项，运行时按数组变重渲不冲突。根因不是语法区别是渲染树循环项绑定 vs for 语句迭代执行的边界冲突。

三、真机配图：for 循环报错 vs ForEach 循环渲染装饰器对比证据

初始态（list=一二三、ForEach 渲染 3 元素均循环渲染边界初始值）：

点调两按钮后（加元素 ForEach 自动加循环项、删首元素 ForEach 自动删循环项均循环渲染边界对比证据齐）：

对比证据：点加元素按钮后 ForEach 自动加循环项（渲染多了新元素），点删首元素按钮后 ForEach 自动删循环项（删了首元素剩余重渲）。ForEach 不是 for 循环是装饰器绑渲染树循环项------ForEach 贬饰器编译期绑渲染树循环项，数组变自动重渲不用 for 语句迭代。for 语句报错根因是 build 是渲染树不是迭代执行流，for 语句运行时迭代跟渲染树绑定冲突。

四、真解法：ForEach 循环渲染的三个场景

场景 1：数组循环渲染（90% 场景首选，数组变自动重渲）

@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']       // ForEach 渲染源
  build() {
    Column() {
      ForEach(this.list, (item: string) => {
        Text(item)                                  ← 每个元素绑一个 Text 循环项
      }, (item: string) => item)
      Button('加')
        .onClick(() => { this.list.push('新') })    ← 数组变 ForEach 自动重渲
    }
  }
}

为哈能跑 ：ForEach 数组循环渲染------每个元素绑一个循环项，数组变自动重渲。首选这个，90% 的场景数组循环渲染用 ForEach 就够。要写「数组循环渲染每个元素」时用这个------不用 for/map 绕，ForEach 贬饰器直接绑循环项按数组变自动重渲。

场景 2：对象数组循环渲染（itemGenerator 渲染对象字段）

interface IUser {
  id: number
  name: string
}

@Entry
@Component
struct Index {
  @State users: IUser[] = [
    { id: 1, name: '张三' } as IUser,
    { id: 2, name: '李四' } as IUser
  ]
  build() {
    Column() {
      ForEach(this.users, (user: IUser) => {
        Text(`id=${user.id}, name=${user.name}`)    ← itemGenerator 渲染对象字段
      }, (user: IUser) => `${user.id}`)             ← keyGenerator 绑 id 键值
      Button('加用户')
        .onClick(() => { this.users.push({ id: 3, name: '王五' } as IUser) })
    }
  }
}

为哈能跑：ForEach 对象数组循环渲染------itemGenerator 渲染对象字段（id/name），keyGenerator 绑 id 键值追踪。要写「对象数组循环渲染字段」时用这个------itemGenerator 渲对象字段，keyGenerator 绑 id 精准追踪增删改，不用 for 循环遍历对象。

场景 3：ForEach + if 嵌套循环渲染（循环项里嵌条件渲染）

@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']
  @State showAll: boolean = true
  build() {
    Column() {
      ForEach(this.list, (item: string) => {
        if (this.showAll) {                         ← 循环项里嵌 if 条件渲染
          Text(`全显：${item}`)
        } else {
          Text(`简显：${item[0]}`)                   ← 显示首字符
        }
      }, (item: string) => item)
      Button('切显')
        .onClick(() => { this.showAll = !this.showAll })
    }
  }
}

为哈能跑：ForEach + if 嵌套循环渲染------循环项里嵌 if 条件渲染，循环+条件组合。要写「循环项里有条件分支」时用这个------ForEach 绑循环项，if 贬饰器嵌在循环项里绑条件分支，循环+条件组合渲染不用 map+三元嵌套。

五、一句话哲学

build 里 for 不是循环是装饰器，绑渲染树循环项不是迭代执行。 ArkUI 的 build 里 ForEach 贬饰器编译期绑渲染树循环项（每个元素绑一个循环项）+ keyGenerator 绑键值追踪增删改，运行时按数组变自动重渲不用 for 语句迭代。根因不是语法区别是渲染树循环项绑定 vs for 语句迭代执行的边界------ForEach 贬饰器编译期绑循环项（合法）+ 数组变自动重渲（不是 for 迭代）+ keyGenerator 绑键值追踪（不用 for 遍历）+ for 语句报错边界（build 是渲染树不是迭代执行流）。对比 React JSX for 循环不能写要 map 绕，ArkTS ForEach 贬饰器直接绑循环项。

渲染哲学阶段收官串讲 ：build() 重渲边界（篇 60，@State 参只刷依赖 UI 不刷全 build）→ if 条件渲染边界（篇 61，if 贬饰器绑渲染树分支不是 if 语句）→ ForEach 循环渲染边界（篇 62，ForEach 贬饰器绑渲染树循环项不是 for 循环）------三篇讲清 ArkUI 渎染哲学：渲染树绑定（build 编译期记依赖/if 绑分支/ForEach 绑循环项），根因都是编译期绑渲染树不是运行时语句执行。

为啥 if/for 语句报错：build 是渲染树不是语句执行流------if/for 语句是运行时跳转/迭代执行，跟渲染树编译期绑定冲突报错。if/ForEach 贬饰器是编译期绑渲染树分支/循环项，运行时按状态/数组变重选重渲不冲突。根因不是语法限制是渲染树绑定 vs 语句执行的边界冲突。

下一阶段预告：ArkUI 组件设计（篇 63 收尾）------从渲染哲学（渲染树绑定）到组件设计（@Builder/@BuilderParam/@Styles/@Extend 复用边界），换角度讲 ArkUI 组件复用哲学，系列收官。

能力系列回链

能力系列篇	本文进阶点
篇 18 循环渲染用法	ForEach 循环渲染边界根因（绑渲染树循环项）
篇 17 条件渲染用法	上一篇：if 条件渲染边界根因
篇 19 @Builder 用法	下篇预告：组件复用边界根因

真机 demo 完整代码

// 篇 62 demo：for 循环报错 vs ForEach 循环渲染装饰器对比
// 对比：build 里 for 循环报错 vs ForEach(...){} 循环渲染合法

@Entry
@Component
struct Index {
  @State list: string[] = ['一', '二', '三']       // ✅ ForEach 渲染源
  @State log: string = '(未操作)'

  build() {
    Column({ space: 12 }) {
      Text('篇 62 配图：for 循环报错 vs ForEach 循环渲染装饰器对比')
        .fontSize(18).fontWeight(FontWeight.Bold).margin({ top: 20, bottom: 8 })
      Text('build 里 for 循环报错 vs ForEach(...){} 循环渲染合法（对比证据）')
        .fontSize(12).fontColor('#888').margin({ bottom: 16 })

      Column({ space: 6 }) {
        Text(`list 镜度 = ${this.list.length}`).fontSize(15).fontWeight(FontWeight.Bold)
        Text(`日志：${this.log}`).fontSize(12).fontColor('#333').margin({ top: 4 })
      }
      .width('92%').padding(12).backgroundColor('#f5f5f5').borderRadius(8)

      // ✅ ForEach 循环渲染装饰器：合法（不是 for 循环）
      Text('ForEach 渲染 list 元素：').fontSize(13).fontColor('#2563eb')
      ForEach(this.list, (item: string) => {
        Text(`✅ ForEach 渲染：${item}`).fontSize(14).fontColor('#2563eb')
      }, (item: string) => item)

      // ❌ build 里 for 循环报错（对比证据，注释掉避编译炸）
      // for (let i = 0; i < this.list.length; i++) { Text(this.list[i]) }    ← for 语句报错

      Button('加元素（ForEach 自动刷循环渲染）')
        .width('92%').height(44).fontSize(14)
        .onClick(() => {
          this.list.push(`新${this.list.length + 1}`)        // ✅ 改 list ForEach 自动刷循环渲染
          this.log = `加元素，list 镜度=${this.list.length}（ForEach 自动刷循环渲染，不是 for 循环）`
        })

      Button('删首元素（ForEach 自动重渲剩余）')
        .width('92%').height(44).fontSize(14)
        .onClick(() => {
          if (this.list.length > 0) {
            this.list.splice(0, 1)                          // ✅ 删首元素 ForEach 自动重渲剩余
            this.log = `删首元素，list 镜度=${this.list.length}（ForEach 自动重渲剩余）`
          }
        })
    }
    .width('100%').height('100%').alignItems(HorizontalAlign.Center)
  }
}

写鸿蒙 ArkUI 记住 ：build 里 for 不是循环是装饰器绑渲染树循环项------ForEach 贬饰器编译期绑渲染树循环项（每个元素绑一个循环项）+ keyGenerator 绑键值追踪增删改，运行时按数组变自动重渲不用 for 语句迭代。根因不是语法区别是渲染树循环项绑定 vs for 语句迭代执行的边界------ForEach 贬饰器编译期绑循环项（合法）+ 数组变自动重渲（不是 for 迭代）+ keyGenerator 绑键值追踪（不用 for 遍历）+ for 语句报错边界（build 是渲染树不是迭代执行流）。数组循环渲染用 ForEach 绑循环项（首选），对象数组循环渲染用 itemGenerator 渲字段 + keyGenerator 绑 id，ForEach + if 嵌套用循环项里嵌条件渲染。ForEach 贬饰器绑渲染树循环项不是 for 循环是 ArkUI 渎染哲学核心收尾！