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 映射数组）：
typescript
// 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 绕：
typescript
// 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 语句：
typescript
@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 语句迭代：
typescript
@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 绑元素键值------给每个元素绑唯一键值，追踪循环项增删改：
typescript
@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 语句是运行时迭代跟渲染树绑定冲突：
typescript
@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% 场景首选，数组变自动重渲）
typescript
@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 渲染对象字段）
typescript
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 嵌套循环渲染（循环项里嵌条件渲染）
typescript
@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 完整代码
typescript
// 篇 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 渎染哲学核心收尾！