一、前置思考

几乎所有内容型应用的核心页面都是长列表——Feed流、商品列表、通讯录、聊天记录。HarmonyOS为长列表提供了LazyForEach替代ForEach，但很多开发者用了一堆LazyForEach列表仍然掉帧，原因往往是无法理解它底层的缓存复用机制和IDataSource生命周期。

本文的核心目标：让你真正理解LazyForEach的三个核心概念——DataChangeListener、keyGenerator、item缓存复用——并能在实际业务中做到满帧60fps的长列表。

二、核心原理

2.1 ForEach vs LazyForEach

ForEach (全量渲染):
┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐
│Item0│Item1│Item2│Item3│Item4│Item5│Item6│Item7│ ← 全部创建
└─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

LazyForEach (按需渲染 + 缓存复用):
屏幕可见区 → [Item2][Item3][Item4]
缓存池     → [Item0][Item1] ← 回收复用
待创建     → Item5, Item6, Item7...

LazyForEach只创建屏幕可见区域+少量预加载的item。滑出屏幕的item进入缓存池，滑动进来时直接复用，避免反复创建/销毁的开销。

2.2 IDataSource接口

interface IDataSource {
  totalCount(): number;
  getData(index: number): Object;
  registerDataChangeListener(listener: DataChangeListener): void;
  unregisterDataChangeListener(listener: DataChangeListener): void;
}

2.3 DataChangeListener

interface DataChangeListener {
  onDataReloaded(): void;           // 全量刷新
  onDataAdded(index: number): void; // 新增
  onDataDeleted(index: number): void; // 删除
  onDataChanged(index: number): void; // 更新
  onDataMoved(from: number, to: number): void; // 移动
}

2.4 keyGenerator的稳定性

key必须全局唯一且稳定，否则LazyForEach无法正确追踪item的移动/删除/新增：

.keyGenerator((item: Item) => item.id.toString()) // ✅ 用唯一ID
.keyGenerator((item: Item) => index.toString())     // ❌ 列表变化后key错乱

2.5 item缓存复用机制

当item滑出屏幕时的处理：

• @Reusable标记的组件进入缓存池
• aboutToReuse(params)被调用，重置状态
• 下次需要同类型item时从池中取出

@Reusable
@ComponentV2
struct ListItemCard {
  @Param item: DataItem = new DataItem();

  aboutToReuse(params: Record<string, Object>): void {
    // 重置@Local状态
  }
}

三、企业级实战落地

本Demo演示：

四、性能优化速查

五、避坑速查

六、总结

LazyForEach是鸿蒙长列表性能的基石。理解其缓存复用机制和IDataSource生命周期是写出丝滑列表的前置条件。

对应Demo文件：entry/src/main/ets/pages/ListPerformanceDemo.ets