HarmonyOS ArkUI 长列表性能优化实战：LazyForEach、cachedCount 与节点复用

一、列表卡顿的根源：一次性构建

信息流、聊天记录、搜索结果——列表是大多数应用的核心界面。在 ArkUI 中，如果直接用 ForEach 渲染上千条数据，框架会在首次加载时为全部数据创建组件节点，即使它们远在屏幕之外。结果是首帧耗时陡增、内存占用虚高，滑动时还可能出现明显掉帧。

LazyForEach 就是为这个场景设计的：它按需创建屏幕内及临近区域的节点，滑出可视区的节点被回收复用，内存占用与列表长度解耦。

二、LazyForEach 的三个组成部分

使用 LazyForEach 需要一个实现了 IDataSource 接口的数据源，以及稳定的键值生成函数。

class BasicDataSource implements IDataSource {
  private listeners: DataChangeListener[] = [];
  private repository: string[] = [];

  totalCount(): number { return this.repository.length; }
  getData(index: number): string { return this.repository[index]; }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.listeners.push(listener);
  }
  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener);
    if (pos >= 0) this.listeners.splice(pos, 1);
  }

  notifyDataReload(): void {
    this.listeners.forEach(listener => listener.onDataReloaded());
  }
}

数据源的关键在于“变更即通知”。增删改数据后必须调用对应的监听回调，否则界面不会刷新，这是 LazyForEach 最常见的使用错误。

三、缓存与占位：滑动体验的两道保险

cachedCount：LazyForEach 默认只构建可视区节点，快速滑动时新节点来不及构建，会出现白屏闪烁。通过 List 或 Grid 的 cachedCount 属性预构建若干屏外节点，牺牲少量内存换取滑动连续性。经验值是 3~5，过大反而失去懒加载意义。

节点复用：配合 @Reusable 装饰器声明可复用组件，滑出屏幕的节点组件被缓存，滑入时直接复用，避免反复创建销毁的开销。

@Reusable
@Component
struct MessageItem {
  @State item: string = '';
  aboutToReuse(params: Record<string, Object>): void {
    this.item = params.item as string;
  }
  build() {
    Text(this.item).fontSize(16).padding(12)
  }
}

四、键值的稳定性：比性能更致命的问题

LazyForEach 的键值生成函数返回的 key 必须与数据一一对应且稳定。使用数组下标作 key，在插入、删除数据后，后续所有条目的 key 都会变化，框架会销毁重建大量节点，轻则闪烁，重则组件内部状态错乱——勾选了第一行，刷新后勾选跑到了另一行。正确做法是使用业务主键：

LazyForEach(this.dataSource, (item: Message) => {
  ListItem() { MessageItem({ item: item }) }
}, (item: Message) => item.id)

五、常见性能陷阱清单

1. 在列表项里做重计算。 日期格式化、字符串拼接应提前在数据层完成，构建函数只做绑定。
2. 嵌套滚动容器。 List 内嵌 ScrollView 会破坏懒加载的可见性计算，尽量用 List 的分组能力替代。
3. 图片不设尺寸。 网络图片未约束宽高，加载后触发重新布局，导致列表跳动。固定尺寸并使用 .objectFit 控制裁剪。
4. 一次性全量刷新。 分页追加数据时，只对新增部分调用 onDataAdd，不要整表 onDataReloaded。

六、验证方法

改造完成后，用 DevEco Studio Profiler 的 ArkUI 视图观察节点数量：滑动到第 500 条时，存活节点应保持在“可视区 + cachedCount”的量级，而不是随列表长度线性增长。同时对比改造前后的首帧耗时与滑动帧率，量化收益。

七、小结

长列表性能优化的本质是“让框架只处理看得见的数据”。LazyForEach 负责按需构建，cachedCount 负责滑动预加载，@Reusable 负责节点复用，稳定键值负责状态正确性。四者配合到位，千行列表与十行列表的内存占用和流畅度可以几乎一致。