列表性能优化 — LazyForEach + List 的虚拟化渲染实战

文章简介

在记账应用中，账单列表和资产列表是最核心的信息展示形式。当用户记账数据累积到成百上千条时，列表的渲染性能直接影响到用户体验。HarmonyOS 提供了 LazyForEach 懒加载机制，结合 List 组件的虚拟化能力，可以高效渲染长列表。本文以 MoneyTrack 中的账单项列表和资产列表为例，深入分析 LazyForEach 的配置与优化方法。

核心知识点

1. LazyForEach 虚拟列表的按需渲染原理

LazyForEach 是 HarmonyOS 提供的声明式懒加载循环渲染接口，其核心思想是按需渲染：只创建和渲染当前可视区域内的列表项，当用户滚动时动态创建新项、回收离开视野的旧项。这与传统 ForEach 的一次性全量渲染有本质区别。

如图所示，当用户滑动列表时，系统持续检测可视区域，动态管理组件的创建与回收，仅保留少量缓存节点，从而将内存占用和渲染开销控制在恒定水平。

2. IDataSource 数据源完整实现

使用 LazyForEach 必须实现 IDataSource 接口，以下是完整的泛型实现框架：

export class BillDataSource implements IDataSource {
  private dataArray: DailyBillGroup[] = [];
  private listeners: DataChangeListener[] = [];

  constructor(data: DailyBillGroup[]) {
    this.dataArray = data;
  }

  totalCount(): number {
    return this.dataArray.length;
  }

  getData(index: number): DailyBillGroup {
    return this.dataArray[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener);
    }
  }

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

  // 增删改数据时通知列表刷新
  addData(index: number, data: DailyBillGroup): void {
    this.dataArray.splice(index, 0, data);
    this.listeners.forEach(listener => {
      listener.onDataAdd(index);
    });
  }

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

3. ForEach vs LazyForEach 详细对比

对比维度	ForEach	LazyForEach
渲染策略	一次性全量渲染所有数据	按需渲染可视区域内的项
内存占用	随数据量线性增长，大列表极易 OOM	仅维持可视区+缓存区，内存稳定
首帧速度	数据量大时首帧耗时极长	首帧只渲染可见项，速度极快
数据源要求	任意数组即可	须实现 IDataSource 接口
组件复用	不支持，所有项独立创建销毁	支持组件回收复用池
滚动性能	全量节点存在于组件树，滚动卡顿	节点数恒定，滚动流畅
增删改响应	需全量重新构建	支持增量通知（onDataAdd/onDataMove 等）
适用场景	数据量 < 50 条的小列表	数据量 > 50 条的长列表或无限滚动列表

4. cachedCount 参数的意义和配置建议

cachedCount 定义了在可视区域外额外缓存的列表项数量（以屏幕为单位）。当用户快速滚动时，系统优先从缓存中取出已创建好的组件绑定新数据，而非重新创建，从而减少白屏和卡顿。

List() {
  LazyForEach(this.billDataSource, (item: DailyBillGroup) => {
    ListItem() {
      BillCard({ card: item });
    }
  }, (item: DailyBillGroup) => item.dateStr)
}
.cachedCount(3)           // 缓存 3 屏外的列表项
.edgeEffect(EdgeEffect.Spring)

配置建议：

• 小型列表（<100 条）：cachedCount 设为 1-2 即可
• 中型列表（100-500 条）：cachedCount 设为 2-3
• 大型列表（>500 条）：cachedCount 设为 3-5，同时关注内存使用
• 快速滚动场景：适当增大 cachedCount 以减少白屏概率

5. 列表项的组件优化

ListItem 的内容应独立封装为组件，避免在 LazyForEach 闭包内直接编写复杂布局：

// ✅ 推荐：ListItem 内容独立封装
@ComponentV2
struct BillCard {
  @Param card: DailyBillGroup;

  build() {
    Row() {
      // 布局保持扁平，避免超过 3 层嵌套
    }
    .width('100%')
    .padding(12)
  }
}

// ❌ 不推荐：在 LazyForEach 闭包内写复杂布局
LazyForEach(this.source, (item: DailyBillGroup) => {
  ListItem() {
    Row() {
      Column() {
        Row() {
          // 层层嵌套严重影响布局性能
        }
      }
    }
  }
})

优化要点：

• 组件化：每个 ListItem 内容独立为 @ComponentV2，使组件树结构清晰
• 减少嵌套：布局层级控制在 3 层以内，避免深层的 Row/Column 嵌套
• 避免条件渲染：ListItem 内部的 if/else 尽量上提到封装组件外部
• 轻量 @Param：传递给 ListItem 组件的参数应尽量精简，避免传递整个大对象

6. 性能监控

通过 DevEco Studio 的 Profiler 工具可以查看列表渲染性能：

// 代码中埋点记录列表渲染耗时
aboutToAppear(): void {
  performance.mark('listStart');
  // ... 数据加载逻辑
}

onPageShow(): void {
  performance.mark('listEnd');
  performance.measure('listRender', 'listStart', 'listEnd');
  const measure = performance.getEntriesByName('listRender')[0];
  console.info(`列表渲染耗时: ${measure.duration}ms`);
  performance.clearMarks();
}

在 DevEco Studio 中使用 Profiler > ArkUI 工具 可以观察：帧率（FPS）、组件树节点数、每帧布局/绘制耗时、列表项创建与回收事件等关键指标。合理的目标是列表滚动时保持 60 FPS，组件节点数控制在 200 以内。

7. 最佳实践

1. 优先使用 LazyForEach：只要是动态列表，默认选择 LazyForEach + IDataSource，仅极少数静态小列表用 ForEach
2. 合理配置 cachedCount：根据列表总长度和滚动速度，一般设为 2-3 屏缓存
3. ListItem 组件化：每个列表项封装为独立组件，避免闭包内写复杂布局
4. Key 生成策略：第三个参数 keyGenerator 必须返回唯一且稳定的键值，通常使用数据 id
5. 避免频繁全量刷新：数据变化时使用 onDataAdd/onDataMove/onDataReloaded 等增量通知，而非每次都调用 notifyDataReload()
6. 监控并优化：定期使用 Profiler 检查列表帧率，发现低于 60 FPS 时分析瓶颈

项目代码案例

账单项列表/资产列表的长列表渲染优化

文件路径：features/home/src/main/ets/views/HomeView.ets
在 HomeView 中，账单列表使用 List + LazyForEach + 自定义 DataSource 实现。

文件路径：features/assets/src/main/ets/views/AssetsView.ets
AssetView 中的资产列表也采用了相同的优化策略。

推荐参考文档

• HarmonyOS LazyForEach 懒加载开发文档
• ArkUI List 组件性能优化指南
• IDataSource 接口定义参考
• DevEco Studio Profiler 使用指南