ArkUI 列表性能优化：LazyForEach 与组件复用深度解析

掌握本文后，你将能诊断并修复鸿蒙应用中最常见的列表卡顿问题，让万级数据量的 List 组件在中低端机型上也能丝滑滚动。

适用版本：HarmonyOS NEXT / API 12+阅读时长：约 18 分钟

场景切入：10000 条消息列表为什么会卡？

某社交 App 在真机测试中，联系人列表滑动帧率跌至 20fps。分析 Profiler 后发现：ForEach 渲染了全部 10000 个 ListItem，内存占用高达 1.2GB，每次滑动都触发大规模 Reflow。问题根源不在业务逻辑，而在于错误选择了 ForEach 而非 LazyForEach，以及没有开启组件复用机制。

一、ForEach vs LazyForEach：根本差异

ForEach（全量渲染）
┌─────────────────────────────────────┐
│  数据源 N 条  →  一次性创建 N 个节点  │
│  内存 ∝ N（线性增长）                │
│  首帧慢、滑动慢、OOM 风险高           │
└─────────────────────────────────────┘

LazyForEach（按需渲染）
┌─────────────────────────────────────────────────────┐
│  数据源 N 条  →  仅渲染可视区 + 预加载缓冲区 K 条    │
│  滑入视口 → 创建节点                                 │
│  滑出视口 → 进入缓存池（可复用）                      │
│  内存 ∝ 可视区高度（几乎恒定）                        │
└─────────────────────────────────────────────────────┘

LazyForEach 实现的核心接口：

// foundation/arkui/ace_engine/frameworks/core/components_ng/
//   pattern/list/list_pattern.cpp  — 虚拟化逻辑入口

interface IDataSource {
  totalCount(): number;                        // 数据总量
  getData(index: number): Object;              // 按索引取数据
  registerDataChangeListener(listener: DataChangeListener): void;
  unregisterDataChangeListener(listener: DataChangeListener): void;
}

关键约束：LazyForEach 只能作为 List、Grid、Swiper、WaterFlow 的直接子组件，不能脱离这四个容器单独使用。

二、IDataSource 正确实现

2.1 基础实现（错误写法 → 正确写法）

错误写法：

// ❌ 直接用数组当数据源
List() {
  ForEach(this.items, (item: MessageItem) => {
    ListItem() { MessageCard({ data: item }) }
  }, (item: MessageItem) => item.id.toString())
}

问题：万条数据全部实例化，首帧渲染超过 3 秒，低端机直接 ANR。

正确写法：

// ✅ 实现 IDataSource
class MessageDataSource implements IDataSource {
private data: MessageItem[] = [];
private listeners: DataChangeListener[] = [];

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

  totalCount(): number {
returnthis.data.length;
  }

  getData(index: number): MessageItem {
returnthis.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);
    }
  }

// 通知框架指定索引数据已变更（精准刷新）
  notifyDataChange(index: number): void {
this.listeners.forEach(l => l.onDataChange(index));
  }

// 尾部追加一条数据（常用于分页加载）
  pushData(item: MessageItem): void {
this.data.push(item);
this.listeners.forEach(l => l.onDataAdd(this.data.length - 1));
  }

// 删除指定索引
  deleteData(index: number): void {
this.data.splice(index, 1);
this.listeners.forEach(l => l.onDataDelete(index));
  }
}

2.2 LazyForEach 使用

@Component
struct MessageList {
private dataSource: MessageDataSource = new MessageDataSource(generateMessages(10000));

  build() {
    List({ space: 8 }) {
      LazyForEach(
this.dataSource,
(item: MessageItem) => {
          ListItem() {
            MessageCard({ data: item })
          }
        },
(item: MessageItem, index: number) =>`${item.id}_${index}`// keyGenerator
      )
    }
    .cachedCount(5)   // 可视区外预加载 5 条，减少滑动白屏
  }
}

cachedCount 的最优值：根据单个 ListItem 高度计算，通常设为「屏幕高度 / 单项高度 × 0.5」，一般取 3~8。

三、组件复用：@Reusable 机制

3.1 复用原理

不开启复用（每次滑出都销毁）
  滑入  → new MessageCard()   → mount   → 渲染
  滑出  → destroy()           → GC 压力
  再滑入 → new MessageCard()  → 重新创建

开启 @Reusable（节点进缓存池）
  滑入  → 从缓存池取节点      → aboutToReuse() → 渲染
  滑出  → aboutToRecycle()    → 节点入缓存池
  再滑入 → 从缓存池取节点      → 跳过创建，直接复用

3.2 @Reusable 组件写法