HarmonyOS NEXT列表性能优化：从LazyForEach迁移到Repeat实战指南

HarmonyOS NEXT 从 API 12 开始，官方在懒加载列表这块悄悄铺了一条新路——Repeat 组件。如果你还在用 LazyForEach 写长列表，且被 IDataSource 那一套回调折磨过，这篇鸿蒙学习实战指南就是给你准备的。我会把 LazyForEach 迁移到 Repeat 的完整思路、核心差异、实操步骤和踩坑记录都摊开来讲，代码可直接抄。

Repeat 并不是简单换个名字，它在更新机制、缓存复用、多模板支持上都做了重构。我的建议是：新项目直接上 Repeat，老项目按这篇指南逐步迁移。接下来我会从底层机制开始讲透，再带你完整走一遍迁移流程。

1. 为什么要从 LazyForEach 迁移到 Repeat

1.1 LazyForEach 的运作机制与瓶颈

LazyForEach 是鸿蒙应用开发里老牌的懒加载方案，它的核心价值在于：配合 List 使用时，不会一次性创建所有子组件，而是按需创建、离屏销毁，从而撑住长列表和海量数据。

它的基本用法需要你实现一个 IDataSource 接口，如下所示：

typescript复制interface IDataSource {
  totalCount(): number;
  getData(index: number): any;
  registerDataChangeListener(listener: DataChangeListener): void;
  unregisterDataChangeListener(listener: DataChangeListener): void;
}

然后还得在业务代码里维护数据源的增删改逻辑，手动调用 listener 的 onDataAdd、onDataDelete、onDataChange 等回调来通知界面刷新。每个列表页都得写一套 DataSource 类，代码量不小，而且数据结构复杂的时候，回调很容易漏调或者多调，界面就出现“数据变了但 UI 没动”这种诡异问题。

LazyForEach 的第三参数 keyGenerator 也是一个重灾区。它生成的键必须唯一且稳定，不仅用于组件复用，还用于差分更新。很多开发者图省事用 index 做 key，结果列表中间插一条数据，后面所有 item 全部重建，性能直接拉胯。更麻烦的是，如果 key 的生成规则和数据源的数据结构耦合太紧，后续加字段改逻辑，key 一变，缓存池就频繁失效，出现滚动闪烁。

1.2 Repeat 到底改了什么

Repeat 是 HarmonyOS 5.0（API 12+）推出的新懒加载组件，官方定位就是用来替代 LazyForEach 的。它的 API 设计直接砍掉了 IDataSource 这一层抽象，改为直接接收一个数组，并提供了内置的差异化更新能力。

先看 Repeat 的接口定义：

typescript复制Repeat(
  items: any[],
  itemTemplate: (item: any, index?: number) => void | object,
  key?: (item: any, index?: number) => string,
  template?: (item: any, index?: number) => number
)

第一眼看上去，Repeat 和 ForEach 有点像，但底层完全不同。Repeat 依然走懒加载通道，只在滚动到可视区域时才创建子组件，离屏组件会进入缓存池复用。而 ForEach 是一次性全量渲染，数据量大的时候该卡的还是卡。

我把 LazyForEach 和 Repeat 的核心差异整理成了一张表：

从上表能看出来，Repeat 的核心变化是：把“数据变更检测”从业务方手里收回了框架内部。你不用再关心什么 DataChangeListener，只需要正确地管理状态数组，剩下的交给 Repeat 去比对和刷新。这个思路和 ArkUI 状态管理模型是一脉相承的，代码写起来舒服很多。

2. 迁移前需要搞懂的核心概念

2.1 接口差异对照

要顺利迁移，你得先知道老的写法里每个参数在新写法里对应什么。我列一个对照表，迁移的时候照着填就行。

这里有一个容易被忽视的差异：LazyForEach 的 itemGenerator 回调里，你不能保证 index 和 dataSource 内部索引严格一致，因为 LazyForEach 的组件复用是按 key 走的。而 Repeat 的 itemTemplate 回调里，index 直接对应 items 数组的下标，这给很多需要根据位置做布局的逻辑省了不少事。

另一个差异是更新粒度。LazyForEach 里你调 listener.onDataChange(index) 时，系统会重新执行一次 keyGenerator 对比，决定要不要重建该 index 对应的组件。Repeat 更简单：它直接对比 key 集合，新增的 key 创建新组件，消失的 key 销毁组件，不变的 key 且数据内容变化时，只把新数据刷到已有组件上。

2.2 懒加载复用机制的本质区别

LazyForEach 的缓存池复用是基于 key 字符串的。当 item 滚出可视区时，组件不会立刻销毁，而是进入缓存池。下一次有相同 key 的 item 需要显示时，直接从缓存池里捞出来用。这个机制要求 key 必须能精确标识一个数据项，如果 key 生成错误（比如两个 item 共用同一个 key），就会出现组件内容“串位”的现象。

Repeat 的缓存池机制做了两件事。第一，默认按模板维度拆分了多个缓存池，每个模板索引对应一个独立的池子。这个设计对多模板列表非常关键，等下我会用代码演示。第二，Repeat 内置了差异化更新算法，它会在数据变化时先比较新旧 key 集合，确定哪些 item 需要创建、哪些需要销毁、哪些需要原地刷新。这个算法不需要你手动触发，而是自动完成的。

不过要提醒一句：Repeat 的差异化更新是“数据驱动”的，它要求传给 Repeat 的数组必须是 @State 状态或能够触发刷新的方式。如果你直接修改数组元素某个属性，比如 this.products[0].liked = true，Repeat 不会感知到变化，因为 @State 监听的是数组本身，不是数组元素的属性。这个坑我后面会专门讲。

2.3 差异化更新的触发条件

Repeat 传不传 key，行为差异很大，这是迁移时最容易踩坑的地方。

不传 key 时，Repeat 默认使用“索引 + 模板索引”作为比较键。也就是说，数据变化后，它会按位置逐一比对。如果你只是简单地把数组整体重新赋值，且数据项数量和顺序基本不变，那没问题，界面能正常刷新。但如果你在列表中间插入了新数据，或者做了排序操作，索引全部错位，Repeat 会认为每个 item 的 key 都变了，于是把所有组件都重建一遍。数据量小的时候无所谓，列表一长，性能就露馅。

传了 key 时，Repeat 会以你返回的字符串作为业务键。它只做“局部更新”：插入、删除、移动都只影响被改动位置附近的组件，其他 item 原样保留。key 的稳定性也很重要，如果同一个数据项两次渲染时 key 不同，Repeat 会认为它是新 item，旧 item 对应的组件会被回收，等于没起到缓存复用效果。

我的建议是：业务数据只要有一个稳定 id，就一定要传 key。只有一种情况可以考虑不传，就是纯展示型列表、数据量小且增删改都不频繁。不过既然都上了 Repeat，说明列表规模不会小，还是老老实实传 key 稳一点。

3. 实战迁移：商品列表完整改造

3.1 改造成 Repeat 版本的完整步骤（可直接抄）

下面我用一个商品列表场景来演示迁移。这个列表支持下拉刷新和分页加载，每条商品有图片、标题、价格和点赞按钮。

先看迁移前用 LazyForEach 写的版本：

typescript复制interface Product {
  id: string;
  title: string;
  price: number;
  liked: boolean;
  cover: string;
}

class ProductDataSource implements IDataSource {
  private products: Product[] = [];
  private listeners: DataChangeListener[] = [];

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

  getData(index: number): Product {
    return this.products[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.listeners.push(listener);
  }

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

  updateLike(index: number, liked: boolean) {
    this.products[index].liked = liked;
    this.listeners.forEach(listener => {
      listener.onDataChange(index);
    });
  }

  addProducts(newProducts: Product[]) {
    const startIndex = this.products.length;
    this.products = this.products.concat(newProducts);
    this.listeners.forEach(listener => {
      listener.onDataAdd(startIndex);
    });
  }
}

@Entry
@Component
struct ProductListPage {
  private dataSource = new ProductDataSource();

  aboutToAppear() {
    this.dataSource.addProducts(fetchProducts(1, 20));
  }

  build() {
    List({ space: 12 }) {
      LazyForEach(this.dataSource, (item: Product) => {
        ListItem() {
          ProductCard({ product: item })
        }
      }, (item: Product) => item.id)
    }
    .width('100%')
    .layoutWeight(1)
  }
}

这个写法能用，但问题很明显：ProductDataSource 这套类在每个列表页都要写一遍，updateLike、addProducts 这类方法还得根据业务场景不断扩展。一旦数据源的方法变多，listener 的维护成本就上来了。

现在改造为 Repeat 版本。第一步，删掉 ProductDataSource 类，把商品数组提升为 @State：

typescript复制@Entry
@Component
struct ProductListPage {
  @State products: Product[] = [];
  private page: number = 1;
  private pageSize: number = 20;

  aboutToAppear() {
    this.loadNextPage();
  }

  loadNextPage() {
    const newProducts = fetchProducts(this.page, this.pageSize);
    this.products = this.products.concat(newProducts);
    this.page++;
  }

  toggleLike(id: string) {
    const index = this.products.findIndex(p => p.id === id);
    if (index >= 0) {
      const updated = [...this.products];
      updated[index] = {
        ...updated[index],
        liked: !updated[index].liked
      };
      this.products = updated;
    }
  }

  build() {
    List({ space: 12 }) {
      Repeat(this.products, (item: Product) => {
        ListItem() {
          ProductCard({
            product: item,
            onLike: () => this.toggleLike(item.id)
          })
        }
      }, (item: Product) => item.id)
    }
    .width('100%')
    .layoutWeight(1)
  }
}

改造完之后，整个页面少了一个完整的类，数据变更逻辑也平铺到了业务方法里，读代码的时候思路清晰多了。这里的关键点有两个：

第一，数据必须是 @State。Repeat 感知数据变化的唯一途径是状态系统，所以数组一定要用 @State 管理，不然你改了数组 UI 没反应。

第二，更新单项数据时要“整体换数组”。比如 toggleLike 里，我先复制数组，再修改目标元素，最后整体赋值。直接 this.products[index].liked = true 是无效的，因为 @State 监听不到数组元素的属性变化。

3.2 多模板场景的迁移：图文混排消息列表

如果你的列表里有不同类型的 item，比如消息列表里既有文本消息又有图片消息，还需要显示时间分隔条，那多模板迁移就是必须掌握的。

LazyForEach 时代的多模板写法很粗糙，基本是 itemGenerator 内部写 if 分支：

typescript复制LazyForEach(this.messages, (item: Message) => {
  ListItem() {
    if (item.type === 'text') {
      TextMessageView({ message: item })
    } else if (item.type === 'image') {
      ImageMessageView({ message: item })
    } else {
      TimeDivider({ time: item.time })
    }
  }
}, (item: Message) => item.id)

这个写法线上也能跑，但有两个毛病。第一，LazyForEach 的组件复用池是按 key 维度组织的，不同类型 item 的 key 如果不小心重复，就会串组件。第二，缓存池里的组件类型混杂，复用时无法预测拿回来的组件是哪种类型，只能依靠框架做类型检查，白白浪费性能。

Repeat 的多模板设计直接把这个问题解决了。template 参数返回一个数字模板索引，框架会按模板索引分别建立独立的缓存池。每个池子里只存放一种组件类型，复用效率高，也从根本上避免了类型串位问题。

改造后的代码：

typescript复制List({ space: 8 }) {
  Repeat(this.messages, {
    template: (item: Message) => {
      if (item.type === 'text') {
        return 0;
      } else if (item.type === 'image') {
        return 1;
      } else {
        return 2;
      }
    },
    itemGenerator: (item: Message) => {
      if (item.type === 'text') {
        ListItem() {
          TextMessageView({ message: item })
        }
      } else if (item.type === 'image') {
        ListItem() {
          ImageMessageView({ message: item })
        }
      } else {
        ListItem() {
          TimeDivider({ time: item.time })
        }
      }
    }
  }, (item: Message) => item.id)
}

注意这里 Repeat 的第二个参数传的是一个对象，包含 template 和 itemGenerator 两个字段。template 返回模板索引，itemGenerator 负责根据 item 类型构建对应的 UI。key 还是照旧传 id。

迁移完成后，这三点是我实际测试后确认的收益：

• 不同模板的缓存池相互隔离，滚动时不会出现“图片消息闪一下变成文本消息”的错乱。
• 模板索引变化的 item，比如某条消息从“加载中”变成“加载完成”，Repeat 会把它的缓存从一个池子迁到另一个池子，UI 平滑过渡。
• 新插入的时间分隔条不会破坏已有 item 的缓存状态，滚动位置保持稳定。

3.3 迁移后的性能表现

我在真机上对两种写法做了个简单的对比测试。测试环境是 HarmonyOS 5.0 真机，列表数据 500 条商品，每条 item 包含图片、标题、价格三个区域。

这个结果符合预期。Repeat 的差异化更新算法在原地上优于 LazyForEach 的“手动通知 + key 对比”，尤其是中间插入数据这种操作，Repeat 能精确到局部创建新组件，而不是让后面的 item 全部重建。

当然，真实性能提升幅度跟你列表的 item 复杂度、key 的设计、数据变更频率都有关系，但方向是确定的。如果你的列表 item 越复杂、数据变更越频繁，Repeat 的优势越明显。

4. 迁移中的常见问题与排查技巧

4.1 列表不刷新？八成是数组操作姿势不对

迁移到 Repeat 之后，最常遇到的问题就是“数据变了，列表不动”。

我见过最多的写法是这样：

typescript复制// 错误示范：直接修改元素属性
this.products[index].liked = true;

Repeat 是懒加载组件，它的数据更新完全依赖状态系统。@State 修饰的数组，状态系统会监听数组引用变化和数组方法调用，但不会监听数组元素的属性变化。你直接改了元素属性，数组引用没变、数组方法没调，UI 自然不会刷新。

正确做法是整体换引用，或者用数组方法替换元素：

typescript复制// 方式一：整体赋值
this.products = [...this.products];

// 方式二：先复制再改再赋值
const newArr = [...this.products];
newArr[index] = { ...newArr[index], liked: true };
this.products = newArr;

// 方式三：splice 替换目标元素
this.products.splice(index, 1, {
  ...this.products[index],
  liked: true
});

这三种方式都能触发刷新。方式二可读性最好，方式三代码最短。我一般用方式二，因为写起来直观，也方便在赋值前加调试日志。

如果你是用了 @Observed 装饰类而非 @State 数组，那规则又有不同：@Observed 会深度监听对象属性变化，但 @Observed 对数组的原生方法支持有限。我的建议是统一用 @State 数组，迁移思路最干净。

4.2 item 状态串位，优先级最高的排查项

Repeat 复用组件时，如果 key 不稳定，就会出现一个 item 的本地状态被另一个 item “继承”的诡异现象。典型场景是列表里有输入框、播放器、视频进度这类带内部状态的组件。

比如你写了一个视频列表，每条视频 item 里有个播放进度的 @State 变量。你给 Repeat 传的 key 用的是 index，那么当你下拉刷新在第二项插入一条新视频后，原来的第二项变成了第三项，key 也跟着变了。Repeat 对比 key 后发现第三项是“新”的，于是重新创建组件。这时候从缓存池里复用的可能是之前第二项留下的旧组件，播放进度还是原来的，界面看起来就是“进度串了”。

排查方式很简单：把 key 打出来看一眼。

typescript复制Repeat(this.videos, (item: Video) => {
  ListItem() {
    VideoCard({ video: item })
  }
}, (item: Video) => {
  console.info(`Repeat key: ${item.videoId}`);
  return item.videoId;
})

如果发现同一个视频的 key 在两次刷新中不一致，那就说明 key 的生成规则有问题，比如用了 index、时间戳、或者依赖了会变化的字段。

我的经验法则：key 只能用“与数据项一一对应且永不变化”的字段。实体数据用数据库主键，临时数据用生成时创建的 uuid，千万不要用当前时间、随机数或者列表索引。

4.3 关于缓存池的常见误区

Repeat 的缓存池机制对开发者是黑盒，但有几个行为规律值得记住。

第一个误区是“组件在缓存池里就不会被销毁”。实际上缓存池有容量上限，超出后会按 LRU 策略淘汰最久未使用的组件。如果你的 item 很高（比如全屏卡片），而缓存池默认只按一个相对保守的数量缓存，那么高 item 列表在快速滚动时还是会出现创建销毁的抖动。这时候优先去做 item 内部的结构精简，而不是纠结池子大小。

第二个误区是“模板索引变了组件就一定重建”。Repeat 的 template 返回值决定组件进入哪个缓存池。如果返回的模板索引变了，组件确实会从旧池子迁到新池子，但这个迁移过程是复用还是重建，取决于旧池子里有没有可用的同类型组件。所以多模板场景下，尽量保证同一类型 item 的 template 返回值稳定，避免模板索引频繁跳变。

第三个误区是把 Repeat 当万能组件，内部塞了非常重的布局。Repeat 只负责懒加载和复用，它不解决 item 自身渲染性能问题。如果 item 内部有复杂的嵌套布局、大量图片加载、频繁的动画，该卡的还是会卡。迁移 Repeat 之后，最好顺手把 item 的布局层级压一压，图片用 Image 组件的懒加载策略，收益会更大。

4.4 常见问题速查表

5. 迁移后的进一步优化建议

5.1 key 策略到底怎么选

Repeat 的 key 参数在设计上比 LazyForEach 的 keyGenerator 宽容很多，它的要求是“尽可能稳定”。但“尽可能”这三个字给不少人留了坑。

我的建议是分场景处理。对于从服务端拉取的数据，服务端返回了什么唯一标识就用什么，常见的有 id、uuid、商品编号。对于本地临时数据，比如用户临时创建的草稿、会话消息，在创建时就用 UUID 生成一个 key 字段，塞进数据对象里，后续一直用它。

这里特别提醒一种情况：如果你的数据源本身是“可变组合”的，比如列表页可以筛选、排序、分组，那么 key 一定不要用排序字段或分组字段。不然你点一下排序，所有 key 全变，Repeat 会认为整个列表是全新的，一次性重建所有 item，性能比不传 key 还差。

5.2 什么场景仍然需要 LazyForEach

虽然 Repeat 是官方推荐方案，但有一个边界场景 LazyForEach 仍然有优势：自定义数据源 + 精确控制加载时机。

Repeat 的 items 直接绑定一个数组，数组有多大，理论上可滚动的范围就有多大。而 LazyForEach 的 dataSource 是惰性的，totalCount 和 getData 都是按需调用，某些极端的“无限滚动”场景下，你可以通过控制 totalCount 的返回值实现流式加载，而不需要真的维护一个不断增长的数组。

不过说实话，这个边界优势在实际项目里并不明显。现在设备内存都够大，一个列表数组哪怕放几万条对象，内存也不会有压力。真正有压力的是 item 对应的组件，而组件层面 Repeat 已经做了懒加载。所以我个人判断：新项目一律用 Repeat，老项目除非有特殊的自定义数据源需求，否则也建议逐步迁过来。

5.3 配合动画和手势的进阶玩法

Repeat 还有一个 LazyForEach 没有的内置能力：数据项插入和删除时的过渡动画。这个动画不是 item 内部的动画，而是列表层面“新 item 滑入、旧 item 滑出”的过渡效果。

要启用这个能力，只需要在 Repeat 外面包一层 animateTo：

typescript复制animateTo({ duration: 300, curve: Curve.EaseInOut }, () => {
  this.products.splice(0, 0, newProduct);
});

Repeat 会自动感知数组中新增的数据项，并给这个新 item 的插入过程补一个位移动画。删除数据也是同理：

typescript复制animateTo({ duration: 300, curve: Curve.EaseInOut }, () => {
  this.products.splice(index, 1);
});

删除时，被删 item 会先保持位置，然后平滑让位给后面的 item。这个效果在消息列表、通知列表这种频繁增删的场景里非常实用，比你自己在 item 内部写动画轻量得多。

不过要注意，动画期间尽量避免再次修改数组，否则多个动画叠加可能互相干扰。如果必须连续操作，建议在动画回调完成后再执行下一次变更，或者把多次变更合并成一次数组赋值。

5.4 状态管理选 V1 还是 V2

最后聊一个迁移过程中容易被忽略的问题：状态装饰器版本。

Repeat 的差异化更新依赖 ArkUI 的状态系统，而状态系统在 HarmonyOS 5.0 之后分了 V1 和 V2 两套。V2 是较新的状态管理方案，用的装饰器是 @ComponentV2、@StateV2、@ObservedV2 这套。Repeat 对 V1 和 V2 都兼容，但迁移时你要先确认自己项目用的是哪套。

如果你用的是 V1，@State 数组的“整体重新赋值”套路完全适用。如果你已经切到 V2，数组更新的写法略有不同。V2 里 @StateV2 对数组的监听更加精细，支持监听数组元素的属性变化，所以直接修改元素属性也能触发刷新。但为了代码风格统一，我建议不管 V1 还是 V2，都采用“先复制再整体赋值”的写法，保证迁移过程不会被装饰器版本差异卡住。

在实际迁移过程中，我最深的体会是：Repeat 真正解决的不是 API 好不好用的问题，而是把“数据变更检测”这件最容易出错的事，从业务代码里彻底抽走了。你不需要再记得什么时候该调 onDataChange，不需要担心 listener 重复注册，只需要保证状态数组是干净的，Repeat 自己会算出最小更新范围。

最后再分享一个小技巧：迁移完成后，用 DevEco Studio 自带的 ArkUI Inspector 跑一遍页面，打开“显示渲染范围”选项，检查列表滚动时高亮区域是否集中在可视区附近。如果滚动过程中整页都在高亮，说明组件复用没有生效，优先查 key 是否稳定，再查模板索引是否频繁跳变。这个检查方法比任何文字说明都直观。