【学习目标】掌握 ForEach 循环渲染核心语法、键值生成规则与组件创建逻辑理解 ForEach 首次渲染与非首次渲染的差异避免渲染异常规避 ForEach 常见错误键值重复、性能损耗、数据不渲染掌握 ForEach 性能优化技巧实现高效循环渲染。一、本节工程目录结构ForEachDemo/ ├── entry/ │ └── src/main/ │ ├── ets/ │ │ ├── components/ │ │ │ ├── CustomListItem.ets # 自定义列表组件 │ │ ├── pages/ │ │ │ ├── Index.ets # 首页功能导航入口 │ │ │ ├── BasicRenderDemo.ets # 基础渲染与键值示例 │ │ │ └── SkeletonListDemo.ets # 静态列表/骨架屏示例 │ └── resources/ │ └── base/media/ # 图片资源 └── build-profile.json5二、ForEach 核心认知2.1 什么是 ForEachForEach 是鸿蒙 ArkTS 提供的循环渲染接口基于数组数据源批量生成组件需与容器组件配合使用核心价值是简化重复组件的开发提升代码复用性。2.2 核心语法ForEach(dataSource:ArrayT,// 数据源数组类型itemGenerator:(item:T,index?:number)void,// 组件生成函数遍历数组项创建组件keyGenerator?:(item:T,index?:number)string// 键值生成函数可选默认按 indexJSON.stringify(item) 生成)2.3 键值生成规则键值Key是 ForEach 识别组件唯一性的核心用于判断组件是否需要创建/复用/销毁若自定义keyGenerator需返回唯一且持久的字符串如对象的唯一 ID若未自定义框架默认生成规则为index __ JSON.stringify(item)键值重复后果框架仅创建第一个重复键值对应的组件后续重复项不渲染键值变化后果框架视为组件替换销毁旧组件并创建新组件。三、ForEach 渲染机制详解3.1 首次渲染遍历数据源为每个数组项生成唯一键值根据键值创建对应组件并渲染流程遍历数组每一项调用keyGenerator生成键值若键值未存在创建组件并记录键值若键值已存在跳过组件创建避免重复渲染。自定义列表项// 子组件自定义列表项Componentexportstruct CustomListItem{Prop content:string;aboutToAppear():void{console.log(CustomListItem - 组件即将出现 ----${this.content})}aboutToDisappear():void{console.log(CustomListItem - 组件即将消失 ----${this.content})}build(){Text(this.content).fontSize(18).padding(15).backgroundColor(#F7F8FA).borderRadius(8).width(100%)}}ForEach基础渲染示例import{CustomListItem}from../components/CustomListItem;Entry Component struct BasicRenderDemo{State fruitList:string[][苹果,香蕉,橙子,葡萄];build(){Column({space:12}){Text(ForEach核心细节).fontSize(20).fontWeight(FontWeight.Bold).margin({bottom:10})// ForEach 首次渲染无重复项ForEach(this.fruitList,(item:string)CustomListItem({content:item}),// 生成组件(item:string)item// 键值为数组项本身确保唯一)}.padding(20).width(100%).height(100%).backgroundColor($r(sys.color.point_color_checked))}}首次渲染—无重复项修改数据源// 数据源包含重复项State fruitList:string[][苹果,香蕉,香蕉,葡萄];首次渲染—有重复项仅渲染「苹果、香蕉、葡萄」三项重复的「香蕉」因键值重复被跳过。3.2 非首次渲染数据源变化后当数据源发生变化增删改查时框架触发重新渲染流程遍历新数据源生成新键值列表对比新旧键值列表新键值不存在创建新组件新键值已存在复用旧组件不重新创建旧键值不存在于新列表销毁对应组件。修改示例Entry Component struct BasicRenderDemo{State fruitList:string[][苹果,香蕉,香蕉,葡萄];// 修改第三项值updateThirdItem(){this.fruitList[2]芒果;}// 插入第一行insertFirstItem(){this.fruitList.splice(0,0,车厘子);}build(){Column({space:12}){Text(ForEach核心细节).fontSize(20).fontWeight(FontWeight.Bold).margin({bottom:10})Button(修改第三项为芒果).width(100%).backgroundColor($r(sys.color.brand)).fontColor(Color.White).onClick(()this.updateThirdItem())Button(新增插入第一行车厘子).width(100%).backgroundColor($r(sys.color.brand)).fontColor(Color.White).onClick(()this.insertFirstItem())ForEach(this.fruitList,(item:string)CustomListItem({content:item}),// 生成组件(item:string)item// 键值为数组项本身确保唯一)}.padding(20).width(100%).height(100%).backgroundColor($r(sys.color.point_color_checked))}}点击修改第三项为芒果按钮后原本重复项香蕉只创建了一个修改后键值改变无重复项创建了芒果其他组件复用。CustomListItem - 组件即将出现 ----苹果 CustomListItem - 组件即将出现 ----香蕉 CustomListItem - 组件即将出现 ----芒果 CustomListItem - 组件即将出现 ----葡萄点击插入第一行车厘子按钮后新创建了车厘子其他组件复用。CustomListItem - 组件即将出现 ---- 车厘子修改键值使用系统默认index __ JSON.stringify(item)当使用 index 进行新增、删除、修改数据源后键值会变动造成组件重复销毁与创建产生性能损耗。ForEach(this.fruitList,(item:string)CustomListItem({content:item}),// 生成组件// (item:string) item // 键值为数组项本身确保唯一)首次运行日志输出组件全部显示CustomListItem - 组件即将出现 ---- 苹果 CustomListItem - 组件即将出现 ---- 香蕉 CustomListItem - 组件即将出现 ---- 香蕉 CustomListItem - 组件即将出现 ---- 葡萄点击插入第一行车厘子按钮后数组存储[车厘子,苹果,香蕉,香蕉,葡萄]键值改变为车厘子_0 苹果_1 香蕉_2 香蕉_3 葡萄_4而原键值为苹果_0 香蕉_1 香蕉_2 葡萄_3。此时香蕉_2无变动其他组件键值已变化日志输出如下CustomListItem - 组件即将消失 ---- 苹果 CustomListItem - 组件即将消失 ---- 葡萄 CustomListItem - 组件即将消失 ---- 香蕉 CustomListItem - 组件即将出现 ---- 车厘子 CustomListItem - 组件即将出现 ---- 苹果 CustomListItem - 组件即将出现 ---- 香蕉 CustomListItem - 组件即将出现 ---- 葡萄示例 List ForEachimport{CustomListItem}from../components/CustomListItem;Entry Component struct ListRenderDemo{State fruitList:string[][];aboutToAppear():void{for(letindex0;index100;index){this.fruitList.push(组件${index})}}// 修改第三项值updateThirdItem(){this.fruitList[2]芒果;}// 插入第一行insertFirstItem(){this.fruitList.splice(0,0,车厘子);console.log(JSON.stringify(this.fruitList))}build(){Column({space:12}){Text(List ForEach核心细节).fontSize(20).fontWeight(FontWeight.Bold).margin({bottom:10})Button(修改第三项为芒果).width(100%).backgroundColor($r(sys.color.brand)).fontColor(Color.White).onClick(()this.updateThirdItem())Button(新增插入第一行车厘子).width(100%).backgroundColor($r(sys.color.brand)).fontColor(Color.White).onClick(()this.insertFirstItem())this.scrollerBuilder()// this.listBuilder()}.padding(20).width(100%).height(100%).backgroundColor($r(sys.color.point_color_checked))}LocalBuilderscrollerBuilder(){Scroll(){Column(){ForEach(this.fruitList,(item:string){CustomListItem({content:item})// 生成组件},(item:string)item)}}.width(100%).layoutWeight(1)}LocalBuilderlistBuilder(){List(){ForEach(this.fruitList,(item:string){ListItem(){CustomListItem({content:item})// 生成组件}},(item:string)item)}.width(100%).layoutWeight(1)}}scrollerBuilder 首次运行CustomListItem - 组件即将出现 ----组件0 ... 连续输出 CustomListItem - 组件即将出现 ----组件99检查视图组件从0创建到99总计100条可视区域仅10条不可视区域也同样创建并挂载到组件树上。如果是1000条数据ForEach依然会全部创建渲染性能极低内存消耗极大。使用ListForEachlistBuilder// this.scrollerBuilder()this.listBuilder()再次运行查看日志配合List组件后循环渲染性能有所提升。从0创建到23并未全部创建。页面可视区域显示11条0-10不可见区域预创建13条。检查UI视图我们发现ListForEach循环渲染组件性能大幅提升。虽然首次运行创建了23个组件可视区域显示10条但不可见区域的13条并未直接挂载到组件树上。点击修改第三项为芒果销毁原来的组件2新创建芒果其他组件复用。CustomListItem - 组件即将消失 ---- 组件2 CustomListItem - 组件即将出现 ----芒果滑动列表查看日志向上滑动屏幕直到组件10消失组件11成为可视区域第一行。日志开始继续输出从第24条至34条停止。由此可见List会提前预创建组件在即将显示时挂载到组件树上。CustomListItem - 组件即将出现 ---- 组件24 CustomListItem - 组件即将出现 ---- 组件25 ..... CustomListItem - 组件即将出现 ---- 组件33 CustomListItem - 组件即将出现 ---- 组件34通过以上演示List虽然提升了加载性能但使用ForEach修改State状态变量时仍会销毁并重新创建组件。使用index作为键值数据源变化后键值会重新排序销毁State之后的所有组件并重新创建。因此ForEach仅适合静态少量列表、数据源不变的场景。注意使用JSON.stringify(item)作为键值时数据量不宜过大内存会飙升若数据中包含bigint类型JSON.stringify会直接抛出错误导致程序无法正常运行。四、ForEach适用场景适用于静态无变动的数据源列表、数据量较小通常少于100条。例如骨架屏、固定选项列表、设置页等场景。示例骨架屏静态渲染Entry Component struct SkeletonListDemo{// 静态数据源仅用于控制骨架屏数量State skeletonCount:number[][1,2,3,4,5];State translateX:string-100%;// 动画偏移量State duration:number1500;// 动画速度aboutToAppear():void{// 页面渲染后自动开始流光动画this.startShineAnimation();}// 流光动画无限循环startShineAnimation(){// 延迟100ms等待组件渲染完成否则动画会因组件未挂载而不生效setTimeout((){this.translateX-100%;// 设置起始位置this.getUIContext()?.animateTo({duration:this.duration,iterations:-1,// 无限循环curve:Curve.Linear},(){// 动画事件回调 让渐变组件移动100%this.translateX100%;});},100)}// 流光遮罩层LocalBuildershineOverlay(){Row().width(100%).height(100%).translate({x:this.translateX}).linearGradient({// 线性渐变angle:90,colors:[[rgba(255,255,255,0),0],[rgba(255,255,255,0.8),0.5],[rgba(255,255,255,0),1]]})}LocalBuilderskeletonItem(){Column({space:8}){Row().width(60).height(60).backgroundColor(#ECECEC).borderRadius(8)Row().width(80%).height(20).backgroundColor(#ECECEC).borderRadius(4)Row().width(70%).height(20).backgroundColor(#ECECEC).borderRadius(4)}.padding(10).backgroundColor(#F7F8FA).borderRadius(8).width(100%).alignItems(HorizontalAlign.Start).overlay(this.shineOverlay()).clip(true);// 必须加否则流光会超出圆角}build(){Column({space:12}){ForEach(this.skeletonCount,(item:number){this.skeletonItem()},(item:number)item.toString())}.padding(20).width(100%).height(100%).backgroundColor(#F1F3F5)}}运行效果五、ForEach 性能优化技巧键值优化优先使用对象唯一 ID 作为键值避免使用 index 或动态变化的字段组件复用子组件尽量轻量化避免在itemGenerator中创建复杂组件如嵌套多层布局数据源优化大数据量场景千条以上建议使用LazyForEach懒加载而非 ForEach避免混用List/Grid 容器中不要同时使用 ForEach 和 LazyForEach。六、内容总结核心逻辑ForEach 基于键值判断组件创建/复用/销毁键值必须唯一渲染机制首次渲染创建所有组件非首次渲染仅处理键值变化的组件场景选型静态列表基本类型数组 数组项作为键值动态列表对象数组 唯一 ID 作为键值避坑核心不使用 index 作为键值不省略keyGenerator性能优化轻量化子组件、优化键值、大数据量用 LazyForEach、长列表用 List 容器。七、代码仓库工程名称ForEachDemo仓库地址https://gitee.com/HarmonyOS-UI-Basics/harmony-os-ui-basics.git八、下节预告下一节我们将深入学习鸿蒙应用开发中的长列表性能优化核心 —— LazyForEach 懒加载实战掌握千条级数据列表的流畅滚动实现方案。