前言在移动应用开发中长列表是最常见的 UI 形态之一。HarmonyOS 提供了ForEach和LazyForEach两种渲染控制方式——前者一次性创建所有组件适合少量数据后者按需加载适合大量数据的列表场景。本文以「猫猫大作战」的高分排行榜1000 条成绩记录为实战锚点深入对比ForEach与LazyForEach的性能差异详细拆解IDataSource数据源实现、键值生成规则、滚动加载策略以及LazyForEach与Reusable、cachedCount如何组成列表性能优化的“三件套“。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–67 篇。本篇是阶段二第 68 篇列表性能优化三部曲的第二篇。一、ForEach vs LazyForEach核心差别1.1 渲染流程对比维度ForEach循环渲染LazyForEach懒加载数据加载一次性全量加载按需加载只加载可视区所需组件创建为每条数据创建组件并挂载到组件树只为可视区缓存区的数据创建组件内存占用大所有组件常驻内存小只保持可视区缓存区组件首次加载耗时O(N)N 为总数据量O(M)M 为可视区可见项数适用数据量 100 条100 条以上、甚至数万条配合 cachedCount不支持✅ 支持1.2 性能差距实测以渲染 1000 条「猫猫大作战」排行榜记录为例// ForEach — 一次性全量加载 加载 1000 条数据: 320ms 创建 1000 个组件: 280ms 构建组件树: 180ms 首次渲染耗时: 780ms 页面长时间白屏 内存峰值: 42MB // LazyForEach — 按需加载每屏约 10 条 加载 10 条数据: 3ms 创建 10 个组件: 3ms 构建组件树: 2ms 首次渲染耗时: 8ms 瞬间展示 内存峰值: 4MB 内存只有 ForEach 的 1/101.3 何时选 ForEach// ✅ 适合 ForEach固定且少于 100 项的列表 State gameLevels: Level[] [ { id: 1, name: 新手村 }, { id: 2, name: 猫咪森林 }, { id: 3, name: 合并峡谷 }, // ... 总共 50 个关卡 ]; build() { List() { ForEach(this.gameLevels, (level: Level) { ListItem() { Text(level.name) } }, (level: Level) level.id.toString()) } }// ✅ 适合 LazyForEach排行榜、消息列表、动态流 ≥ 100 条 State records: IDataSource new LeaderboardDataSource(); // 1000 条 build() { List() { LazyForEach(this.records, (record: GameRecord) { ListItem() { RecordCard({ record: record }) } }, (record: GameRecord) record.id.toString()) } }选型金标准数据量 50 条或数据量不确定 → 默认选LazyForEach。二、IDataSource 接口详解2.1 接口定义LazyForEach的数据源必须实现IDataSource接口该接口定义在kit.ArkUI中interface IDataSource { totalCount(): number; // 数据总量 getData(index: number): Object; // 获取指定索引的数据 registerDataChangeListener(listener: DataChangeListener): void; unregisterDataChangeListener(listener: DataChangeListener): void; }DataChangeListener接口提供了数据变更通知方法interface DataChangeListener { onDataReload(): void; // 全量刷新 onDataAdd(index: number): void; // 新增一条 onDataMove(from: number, to: number): void; // 移动一条 onDataDelete(index: number): void; // 删除一条 onDataChange(index: number): void; // 修改一条 onDataAdd(index: number): void; // 新增旧接口 }2.2 完整实现排行榜数据源// LeaderboardDataSource.ets import { IDataSource, DataChangeListener } from kit.ArkUI; export class GameRecord { id: number; rank: number; playerName: string; score: number; date: string; constructor(id: number, rank: number, name: string, score: number, date: string) { this.id id; this.rank rank; this.playerName name; this.score score; this.date date; } } export class LeaderboardDataSource implements IDataSource { private data: GameRecord[] []; private listeners: DataChangeListener[] []; constructor(count: number 1000) { for (let i 0; i count; i) { this.data.push(new GameRecord( i, i 1, 玩家${i 1}, Math.floor(Math.random() * 99999), 2026-07-24 )); } } totalCount(): number { return this.data.length; } getData(index: number): GameRecord { return this.data[index]; } registerDataChangeListener(listener: DataChangeListener): void { if (!this.listeners.includes(listener)) { this.listeners.push(listener); } } unregisterDataChangeListener(listener: DataChangeListener): void { const idx this.listeners.indexOf(listener); if (idx 0) { this.listeners.splice(idx, 1); } } // ---- 数据变更方法 ---- // 末尾追加新记录 addRecord(record: GameRecord): void { this.data.push(record); const insertIndex this.data.length - 1; // 通知所有监听器数据已新增 this.listeners.forEach(l l.onDataAdd(insertIndex)); } // 删除指定记录 deleteRecord(index: number): void { this.data.splice(index, 1); this.listeners.forEach(l l.onDataDelete(index)); } // 更新指定记录 updateRecord(index: number, record: GameRecord): void { this.data[index] record; this.listeners.forEach(l l.onDataChange(index)); } // 全量刷新如从服务器拉取新数据 reloadRecords(records: GameRecord[]): void { this.data records; this.listeners.forEach(l l.onDataReload()); } }2.3 增量更新 vs 全量更新更新方式方法性能适用场景增量新增onDataAdd(index)✅ 仅新建一个组件追加新战绩增量删除onDataDelete(index)✅ 仅删除一个组件删除误录记录增量修改onDataChange(index)✅ 仅刷新指定项更新排名变化批量移动onDataMove(from, to)✅ 仅调整两项位置排行榜重排全量刷新onDataReload()⚠️ 重建所有可见组件从服务器重新拉取// 错误粗暴方式直接替换整个数据源 this.records newDataSource; // ❌ 触发 LazyForEach 重建全部组件 // 正确增量方式使用 IDataSource 的变更通知 dataSource.addRecord(newRecord); // ✅ 只创建一个新的 ListItem dataSource.updateRecord(0, updatedRecord); // ✅ 只刷新第 0 项三、键值生成策略3.1 keyGenerator 的重要性LazyForEach的第三个参数keyGenerator决定了 ArkUI 如何追踪列表项的身份LazyForEach( this.dataSource, // 数据源 (item: GameRecord) { /* ... */ }, // 组件生成函数 (item: GameRecord) item.id.toString() // 键值生成函数 )keyGenerator 实现效果建议item.id.toString()✅ 唯一且稳定强烈推荐item item.playerName⚠️ 可能重复不推荐JSON.stringify(item) 性能差 每次换新key禁止使用item Math.random() 每帧都重建组件绝对禁止3.2 JSON.stringify 的陷阱// 错误key 生成器中使用 JSON.stringify LazyForEach(this.records, (item) { ListItem() { RecordCard({ record: item }) } }, (item) JSON.stringify(item)) // ❌ 每次渲染 key 都不同为什么不行JSON.stringify对大型对象序列化耗时在滑动时频繁调用导致卡顿数据对象即使内容相同但引用不同时key 也会变化导致 LazyForEach 认为“全是新数据“重建所有组件// ✅ 正确使用稳定且唯一的 id LazyForEach(this.records, (item) { ListItem() { RecordCard({ record: item }) } }, (item) item.id.toString()) // ✅ 唯一且持久的 key3.3 key 生成规则总结正确 key 的三大原则 1. 唯一性同一数据在不同渲染周期中 key 相同 2. 稳定性数据内容不变时 key 不变 3. 高效性生成 key 的计算开销极小最好只是一个属性访问四、三件套组合Reusable LazyForEach cachedCount4.1 为什么需要三件套单独使用LazyForEach虽然实现了按需加载但快速滑动时仍然存在两个问题白块问题滑动太快新组件来不及创建创建开销每次划入都重新创建组件仍有一定耗时三件套各司其职技术解决问题效果LazyForEach避免全量创建首屏秒开cachedCount预先生成附近组件滑动无白块Reusable复用滑出组件创建零开销4.2 三件套完整代码import { IDataSource, DataChangeListener } from kit.ArkUI; Entry Component struct LeaderboardPage { private dataSource: LeaderboardDataSource new LeaderboardDataSource(10000); // 1万条数据 build() { Column() { // 标题栏 Text( 全球排行榜) .fontSize(24) .fontWeight(FontWeight.Bold) .padding(16) // 三件套组合LazyForEach cachedCount Reusable List({ space: 8 }) { LazyForEach(this.dataSource, (item: GameRecord) { ListItem() { RecordCard({ record: item }) // 已在第 67 篇中标记 Reusable } }, (item: GameRecord) item.id.toString()) } .cachedCount(10) // 预加载上下各 10 个 .width(100%) .layoutWeight(1) .backgroundColor(#F5F6FA) } .height(100%) } } // 已在第 67 篇标记 Reusable 的复用组件 Reusable Component struct RecordCard { Prop record: GameRecord new GameRecord(); aboutToReuse(params: Recordstring, Object) { // 复用时的数据更新由 Prop 自动完成 } build() { Row() { Text(#${this.record.rank}) .width(45) .fontSize(16) .fontWeight(FontWeight.Bold) .textAlign(TextAlign.Center) Text(this.record.playerName) .layoutWeight(1) .fontSize(16) .margin({ left: 8 }) Text(this.record.score.toString()) .fontSize(18) .fontWeight(FontWeight.Bold) .fontColor(#2ECC71) } .padding({ left: 12, right: 12, top: 10, bottom: 10 }) .backgroundColor(#FFFFFF) .borderRadius(10) .shadow({ radius: 2, color: rgba(0,0,0,0.05), offsetY: 1 }) .width(100%) } }4.3 性能对比// 1 万条数据排行榜滚动性能 指标 | ForEach | LazyForEach | LazyForEachcachedCountReusable --------------------|-------------|-------------|---------------------------------- 首次渲染耗时 | 5s (崩溃) | 8ms | 8ms 滑动帧率 (低端机) | 无法运行 | 35fps | 58fps 峰值内存 | — | 12MB | 8MB 组件节点数 | 10000 | 12 | 32 (10 可见 20 缓存) GC 暂停频率 | — | 频繁 | 几乎为 0 白块现象 | — | 快速滑动有 | 无五、项目实战排行榜动态排名更新5.1 场景说明排行榜需要实时更新——玩家每局结束得分可能会超越其他人排名需要重新排序。使用IDataSource的增量更新方法只刷新变化的部分。5.2 实现代码// 玩家完成一局后更新排行榜 function submitNewScore(playerName: string, newScore: number) { // 1. 找到玩家现有记录 const existingIndex dataSource.findIndexByPlayer(playerName); if (existingIndex 0) { // 2. 更新得分 const oldRecord dataSource.getData(existingIndex); oldRecord.score newScore; // 3. 重新排序并通知 dataSource.reSortByScore(); // 4. 通知 LazyForEach 全量刷新因为排名顺序变了 dataSource.reloadRecords(dataSource.getAllData()); } else { // 新玩家追加记录 const newRecord new GameRecord( nextId, 1000, playerName, newScore, 2026-07-24 ); dataSource.addRecord(newRecord); } }在实际项目中可以使用onDataMove和onDataChange实现更精细的增量更新而非全量reloadRecords// LeaderboardDataSource.ets — 精细增量更新 moveRecord(fromIndex: number, toIndex: number): void { const [moved] this.data.splice(fromIndex, 1); this.data.splice(toIndex, 0, moved); this.listeners.forEach(l l.onDataMove(fromIndex, toIndex)); } updateScoreAndRank(playerIndex: number, newScore: number): void { const oldRank this.data[playerIndex].rank; this.data[playerIndex].score newScore; // 重排 this.data.sort((a, b) b.score - a.score); this.data.forEach((r, i) r.rank i 1); // 只通知变更不是全量 reload const newIndex this.data.findIndex(r r.id this.data[playerIndex].id); if (newIndex ! playerIndex) { this.moveRecord(playerIndex, newIndex); // 移动 } this.listeners.forEach(l l.onDataChange(newIndex)); // 刷新 }六、LazyForEach 在 Grid 和 WaterFlow 中使用6.1 Grid 中的 LazyForEachGrid() { LazyForEach(this.catsDataSource, (cat: CatConfig) { GridItem() { Image(cat.icon) .width(80) .height(80) } }, (cat: CatConfig) cat.id.toString()) } .columnsTemplate(1fr 1fr 1fr) // 三列 .rowsTemplate(1fr 1fr 1fr 1fr) .cachedCount(6) // 缓存 6 个6.2 WaterFlow 中的 LazyForEachWaterFlow() { LazyForEach(this.flowDataSource, (item: MediaItem) { FlowItem() { VideoCard({ video: item }) } }, (item: MediaItem) item.id.toString()) } .columnsTemplate(1fr 1fr) .cachedCount(8)在 Scroll LazyVGridLayout/LazyVWaterFlowLayout 中的使用方式类似详见第 69 篇 cachedCount。七、LazyForEach 与 V2 状态管理在 V2 模式下LazyForEach的使用方式基本相同但数据源中的对象需要用ObservedV2Trace装饰ObservedV2 class GameRecordV2 { Trace id: number 0; Trace rank: number 0; Trace playerName: string ; Trace score: number 0; } ComponentV2 struct RecordCardV2 { Param record: GameRecordV2 new GameRecordV2(); // ... }V2 注意LazyForEach的键值生成器在 V2 中同样遵循唯一且稳定的原则。八、常见踩坑8.1 坑一keyGenerator 返回不唯一的 key// 错误以排名为 key排名会变 LazyForEach(this.records, (item) { ListItem() { RecordCard({ record: item }) } }, (item) item.rank.toString()) // ❌ 排名变化时key 变化组件重建后果排行榜重排后所有组件的 key 都变了LazyForEach 会销毁所有旧组件、创建新组件相当于全量刷新。解决用不变的唯一标识如数据库自增 id(item) item.id.toString() // ✅ id 永不变8.2 坑二IDataSource 不通知变更// 错误修改数据但不通知 this.dataSource.data[0].score 99999; // ❌ LazyForEach 不知道数据变了UI 不刷新 // ✅ 正确通过接口通知 this.dataSource.updateRecord(0, updatedRecord);8.3 坑三列表项高度频繁变化当 LazyForEach 的列表项高度在渲染过程中频繁变化时会导致cachedCount的预加载数量不足出现白块。解决方法给列表项设置确定的高度或constraintSize。九、最佳实践清单数据量 50 条时默认使用 LazyForEachkeyGenerator 使用唯一且稳定的 id禁止 JSON.stringify总是配合 cachedCount Reusable三件套使用数据变更通过IDataSource 的增量通知禁止全量替换优先使用onDataAdd/onDataDelete/onDataChange而非onDataReload列表项高度尽量固定避免动态高度导致缓存不足LazyForEach Scroll 做混合布局时Scroll 方向必须为VerticalaboutToReuse 中不做耗时操作十、总结LazyForEach是 HarmonyOS 处理大数据量列表的核心渲染控制手段与Reusable、cachedCount组成列表性能优化的“三件套“——按需加载解决首屏速度预缓存解决滑动白块组件复用解决创建开销。核心要点ForEach全量加载适合 50 条LazyForEach按需加载适合 50 条IDataSource负责数据提供和变更通知增量更新优于全量刷新keyGenerator使用唯一 id禁止JSON.stringify和Math.random三件套组合LazyForEachcachedCount(N)Reusable下一篇预告第 69 篇将深入cachedCount— 预加载缓存策略讲解如何精准设置缓存数量来平衡内存与滚动流畅度。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源HarmonyOS LazyForEach 官方文档LazyForEach API 参考懒加载优化最佳实践IDataSource 接口参考开源鸿蒙跨平台社区第 67 篇Reusable 组件复用第 69 篇cachedCount 预加载第 70 篇IDataSource 自定义数据源