鸿蒙ArkTS Repeat组件实战：从ForEach迁移到高性能循环渲染

做鸿蒙应用开发的朋友应该都有过这种体验：列表页数据量一上来，用 ForEach 渲染就有点绷不住了，尤其是在购物车、订单流这种高频交互场景里，用户每点一次按钮，列表跟着卡一下，体验非常糟糕。后来我在重构项目时把循环渲染从 ForEach 换成了 Repeat，同样一套界面，操作明显顺畅了很多，这才真正理解了“可复用的循环渲染”这几个字的分量。

这篇文章就围绕 ArkTS 语法里的 Repeat 组件展开，把它的核心设计逻辑、每个参数背后的用意、从 ForEach 迁移过去的完整实操过程，以及我实际踩过的几个坑一次讲清楚。无论你是刚接触鸿蒙开发的新手，还是已经在用 ForEach 写业务的老手，这篇文章都能帮你少走不少弯路。

1. Repeat是什么：先搞懂它解决的核心痛点

1.1 从ForEach到Repeat：循环渲染的演进逻辑

要理解 Repeat 的价值，得先回顾一下 ForEach 的工作方式。ForEach 是 ArkUI 第一代循环渲染方案，它接收一个数组，遍历每一项生成对应的 UI 组件。看起来很简单，但它内部维护了数组项与组件节点的对应关系，每当数组发生变化，ForEach 会执行一次全量 diff，对比新旧数据项，找出哪些需要创建、哪些需要删除、哪些需要移动。

这种全量 diff 在数据量小的时候问题不大，但数据量一旦上去，每次状态变更都做全量对比，性能开销就很明显了。更重要的是，ForEach 对组件节点的复用能力很弱，即使只是数组中某一个数据项的某个属性发生了变化，它也可能触发大量无关节点的重建，导致页面掉帧。

Repeat 组件就是针对这个问题推出的新一代循环渲染方案。它的核心设计思路是“以 key 为中心”，每个数据项通过 key 建立唯一标识，当数据变化时，Repeat 只对 key 匹配成功的节点做原位更新，对 key 新增的节点做创建，对 key 移除的节点做销毁，不再做全量 diff。

1.2 “可复用”的含义：模板与节点的双重复用

“可复用的循环渲染”这个描述其实包含两层意思。

第一层是模板复用。在 ArkUI 的编译过程中，Repeat 会把循环体里的 UI 描述编译成一个可复用的模板函数。无论列表里有 10 条数据还是 1000 条数据，模板函数只生成一次，运行时通过参数传入不同的数据项来实例化不同的组件树。这就避免了每渲染一条数据就重新生成一遍 UI 描述的开销。

第二层是节点复用。当数据变更导致列表重新渲染时，Repeat 会通过 key 匹配新旧数据项的对应关系。只要 key 没有变，组件节点就原地复用，只更新发生变化的属性；只有 key 是新增的，才会走组件创建的完整流程。

我打个比方。ForEach 像是每次都要把所有书架上的书全部拿下来，清点一遍，再重新摆回去。而 Repeat 是给每本书贴了唯一的编号，哪本动了就只处理哪本，其他书原地不动。数据量越大，这种“精确打击”的优势就越明显。

2. Repeat语法逐行拆解：每个参数背后的设计

2.1 基本语法结构：arr、template、key

Repeat 的基本语法结构大致如下：

typescript复制Repeat<CartItem>(this.cartItems)
  .key((item: CartItem) => item.id)
  .template((item: CartItem) => {
    Row() {
      Text(item.name)
      Text(`¥${item.price}`)
    }
  })

三个核心部分我来逐个拆解。

首先是 Repeat<T>(arr)，泛型参数 T 是数组元素类型，arr 就是你要渲染的数据源。和 ForEach 一样，Repeat 的第一个参数必须是数组，但和 ForEach 不同的是，Repeat 在编译期就能拿到 T 的类型信息，从而对 template 中的属性访问做静态检查，写错属性名在编译阶段就会报错，不用等运行时崩溃。

然后是 .template()，这就是前面提到的模板函数。它接收一个数据项作为参数，在函数体内描述这个数据项对应的 UI 结构。这里有一个关键设计：template 函数内部只能基于传入的 item 来描述 UI，不建议在循环体内声明独立的状态变量。原因后面会详细说，简单理解就是模板要保证“纯函数”特性，相同的 item 输入必须产生相同的 UI 输出，这样编译期才能做优化。

最后是 .key()，key 生成器函数。它接收一个数据项，返回一个稳定的字符串或数字标识。Repeat 底层会维护一个 key 到组件节点的映射表，每次数据变化后，通过查找映射表来判断哪些节点需要复用、哪些需要重建。key 没设好，Repeat 直接退化成性能更差的 ForEach。

提示：这里展示的是 API 12 及以后版本的通用写法。ArkTS 的 Repeat 接口在不同 DevEco Studio 版本上可能有细节差异，有的版本把 key 和 template 放在 RepeatOptions 参数对象中传入，写法略有不同，但核心概念一致。实际开发以上手版本对应的官方接口文档为准。

2.2 keyGen：决定复用效率的“生死线”

很多初学者不太重视 key，随手用数组下标 index 充当 key。在 Repeat 里这是大忌。

用 index 作 key 会带来什么后果？举个例子。一个有序列表，你在开头插入了一条新数据，此时所有数据项的 index 都变了。Repeat 按照新 index 去找旧的 key，会发现每一个 key 对应的数据项都不是原来的数据项了，于是只能全部销毁重建。这等于把 Repeat 的精准更新机制彻底废掉，性能反而比 ForEach 更差。

正确的 key 生成原则有三个：

1. 稳定性：同一个数据项在列表生命周期内的 key 不能变。
2. 唯一性：key 在列表内不能重复，重复会导致节点错乱。
3. 可预测性：key 应该由数据项自身的属性生成，而不是由位置、时间等外部因素生成。

最稳妥的做法是使用数据项中自带的业务主键，比如商品 id、订单号、用户 id。如果数据项本身没有唯一标识字段，可以考虑在数据进入列表时为每一项生成一个唯一 ID。我在项目里就是这么做的，在数据层为每一项分配一个 uid，生成规则可以参考时间戳加随机数。

2.3 template模板的执行时机与UI更新机制

template 函数看起来只是普通的箭头函数，但它在 Repeat 内部有特殊的调度逻辑。

Repeat 并不是每次数据变化时都重新执行所有数据的 template。它会把上一次渲染后各个 key 对应的节点缓存起来，数据变更后先对比 key 集合的差异，再决定对哪些节点调用 template 进行重建，对哪些节点只做属性级更新。这意味着 template 函数的执行频率实际上远低于列表长度乘以更新次数，这是 Repeat 性能优势的底层来源。

不过这里有个容易踩的坑。在 template 内部直接访问 item 的属性和在普通 build 函数中访问 @State 变量的机制不同。Repeat 的 template 首次执行后，组件节点和数据项之间的绑定关系是通过 key 来维系的，而不是通过某种自动的深层监听。如果你在 template 里写了这样的代码：

typescript复制.template((item: CartItem) => {
  Text(this.getDisplayName(item.id))
})

也就是说，通过一个外部函数加工后再展示 item 的属性，那么当 item 的属性变化时，Repeat 可能感知不到这个变化，界面上显示的内容就不会更新。因为 Repeat 认为 key 没有变化，节点可以复用，复用的意思是它不会重新执行 template，只会更新组件节点上的已绑定属性。

所以 template 里的 UI 描述应该直接绑定 item 的属性字段，而不是通过间接调用生成。如果确实需要加工逻辑，应该在数据层先处理完成，保证 item 上的属性就是最终展示所需的格式。

3. 从ForEach迁移到Repeat：一次完整的实操记录

3.1 场景设定与数据结构

为了讲清楚迁移过程，我用一个真实做过的购物车页面来举例。这个页面的需求是：展示商品列表，每项包含选中框、商品名、单价、数量加减按钮，底部显示当前选中商品的总金额。用户操作频率很高，需要在秒级内连续切换选中状态、调整数量，同时总金额实时变化。

数据结构是这样的：

typescript复制interface CartItem {
  id: string;
  name: string;
  price: number;
  count: number;
  selected: boolean;
}

页面状态：

typescript复制@State cartItems: CartItem[] = [];
@State totalPrice: number = 0;

这里我没有使用 @Observed 装饰器，原因后面说。先看最直接的迁移过程。

3.2 改造前：ForEach版本怎么写的

整个列表的 ForEach 写法如下：

typescript复制build() {
  Column() {
    List() {
      ForEach(this.cartItems, (item: CartItem) => {
        ListItem() {
          Row() {
            Checkbox()
              .select(item.selected)
              .onChange((value: boolean) => {
                this.updateSelected(item.id, value);
              })
            Text(item.name)
              .fontSize(16)
              .fontWeight(FontWeight.Medium)
            Blank()
            Text(`¥${item.price.toFixed(2)}`)
              .fontSize(14)
              .fontColor('#999999')
            Row() {
              Button('-')
                .onClick(() => this.updateCount(item.id, -1))
              Text(`${item.count}`)
                .fontSize(14)
              Button('+')
                .onClick(() => this.updateCount(item.id, 1))
            }
          }
          .padding(12)
        }
      }, (item: CartItem) => item.id)
    }
    .layoutWeight(1)

    Text(`合计：¥${this.totalPrice.toFixed(2)}`)
      .fontSize(18)
      .fontWeight(FontWeight.Bold)
      .padding(16)
  }
}

updateSelected 和 updateCount 的逻辑就是遍历 cartItems，找到对应 id 的项，修改属性，然后重新计算 totalPrice。在数据量二十来条时完全够用，但一百条以上，连续操作时就能感受到掉帧。

3.3 改造后：Repeat版本的完整实现

迁移到 Repeat，主要改动的是列表部分的渲染代码。我分步说明。

第一步，把 ForEach 换掉，改成 Repeat 加 key、template 的结构：

typescript复制List() {
  Repeat<CartItem>(this.cartItems)
    .key((item: CartItem) => item.id)
    .template((item: CartItem) => {
      ListItem() {
        Row() {
          Checkbox()
            .select(item.selected)
            .onChange((value: boolean) => {
              this.updateSelected(item.id, value);
            })
          Text(item.name)
            .fontSize(16)
            .fontWeight(FontWeight.Medium)
          Blank()
          Text(`¥${item.price.toFixed(2)}`)
            .fontSize(14)
            .fontColor('#999999')
          Row() {
            Button('-')
              .onClick(() => this.updateCount(item.id, -1))
            Text(`${item.count}`)
              .fontSize(14)
            Button('+')
              .onClick(() => this.updateCount(item.id, 1))
          }
        }
        .padding(12)
      }
    })
}
.layoutWeight(1)

看起来改动不大，但运行时行为差别很大。Repeat 模式下，当 item.count 变化时，只有对应 key 的 Row 组件会收到更新指令，其他列表项完全不受影响。而 ForEach 模式下，即使只有一个数据项变化，框架也需要对整个列表做一次 diff 判断。

第二步，优化状态更新函数。在 Repeat 下，如果还是用遍历数组、修改属性、重新赋值整个数组的方式，会导致新建数组引用，Repeat 会认为数据源整体变化了，虽然 key 能匹配上，但性能打了折扣。更合理的做法是细化更新粒度：

typescript复制updateCount(id: string, delta: number) {
  const index = this.cartItems.findIndex((item) => item.id === id);
  if (index === -1) return;

  const item = this.cartItems[index];
  const newCount = Math.max(0, item.count + delta);
  if (newCount === item.count) return;

  this.cartItems[index] = { ...item, count: newCount };
  this.calcTotal();
}

这里 this.cartItems[index] = { ...item, count: newCount } 只替换了目标项的引用，Repeat 通过 key 能精确锁定这一项。数据源整体引用没有变，其他项不会被波及。

3.4 迁移后的性能验证方法

换完写法之后，怎么确认性能真的提升了？这里分享一个我实测中用到的验证路径。

DevEco Studio 自带的 Profiler 工具非常有用。打开 Profiler，选择 Frame 分析，在操作前先记录一段静默期的帧率基线，然后连续快速点击“+”按钮十次，对比操作期间的掉帧次数和单帧渲染耗时。我在同一个页面上对比过，ForEach 版本在快速操作时偶尔会出现 30ms 以上的长帧，Repeat 版本基本稳定在 16ms 以内。

另一种更直接的验证方式是在 Repeat 的 template 入口加日志：

typescript复制.template((item: CartItem) => {
  console.info(`Repeat template executed: ${item.id}`);
  // UI描述...
})

然后在操作数量加减时观察日志。理想情况下，点击某个商品的“+”只会打印该商品对应 key 的 template 执行日志，其他商品不会打印。如果所有商品的日志都刷了一遍，说明 key 的设置有问题或者状态更新方式触发了全量更新。

我实测下来的结论是，Repeat 在数据量超过五十项、操作频率较高的场景下收益非常明显。数据量低于二十项时性能差异不大，如果项目已经用 ForEach 写好了，小列表没必要强行迁移，避免无谓的改动风险。

4. 状态管理与组件复用的工程实践

4.1 为什么Repeat场景下更推荐精细化状态管理

前面示例里我用了展开对象的方式更新单项数据，这种写法在 Repeat 场景下工作得很好，但有个前提：数据项本身是普通对象，且每次更新都替换数组中该项的引用。这种方式写起来简单，理解成本低，适合中小型页面。

如果你的页面数据层级更深，比如商品项下面还嵌套了促销信息、库存信息等多个子对象，普通对象的浅替换就不够用了。这时候官方推荐的方案是使用 @Observed 和 @ObjectLink 做精细化状态管理。

typescript复制@Observed
class CartItem {
  id: string = '';
  name: string = '';
  price: number = 0;
  count: number = 1;
  selected: boolean = false;

  constructor(id: string, name: string, price: number) {
    this.id = id;
    this.name = name;
    this.price = price;
  }
}

然后在 Repeat 的 template 中通过 @ObjectLink 接收数据项：

typescript复制@Component
struct CartItemView {
  @ObjectLink item: CartItem;
  onCountChange: (id: string, delta: number) => void = () => {};

  build() {
    Row() {
      // 直接访问 this.item.count、this.item.selected
    }
  }
}

这样在子组件里修改 this.item.count 时，框架能精确感知到是哪个对象、哪个属性发生了变化，并把更新范围收敛到最小的 UI 子树。Repeat 负责定位到正确的 key，@ObjectLink 负责定位到正确的属性，两者配合起来，渲染效率非常接近原生手写。

不过我也要提醒一句：@Observed 和 @ObjectLink 有一定的学习成本，如果页面数据没那么复杂，不建议一上来就用。架构上的过度设计比性能问题更难处理。我自己的判断标准是——数据项有二级以上嵌套结构，或者有多个子组件共享同一数据项的某个属性时，才考虑上这套方案。

4.2 长列表的懒加载与Repeat的配合

Repeat 虽然优化了列表项的更新效率，但它本身不是一个懒加载方案。也就是说，如果列表有一万个数据项，Repeat 仍然会一次性创建一万个组件节点，这对内存和启动性能都是很大的压力。

真正的长列表场景需要把 Repeat 和 LazyForEach 配合使用，或者直接使用基于懒加载的容器组件。

在 ArkUI 中，List 组件本身支持懒加载能力，配合 LazyForEach 时可以做到只创建可视区域内的节点。而 Repeat 目前更适合用在数据量可控（比如几百条以内）、但更新频率很高的场景。

这和很多人的直觉相反。我刚接触 Repeat 时也以为它是“升级版 ForEach”就什么都用它，结果在处理千级数据列表时反而被 Recylce 的懒加载特性和 Repeat 的全量创建逻辑拖累了。后来我总结出一套选择策略：

这套策略不是绝对的，但可以作为选型时的参考起点。我从项目实践中得到的体会是：Repeat 最适合的场景是“数据量中等、变化频繁、交互复杂”的界面，比如购物车、多选列表、动态表单。它不是一个万能方案，用对地方才是好方案。

5. 常见问题与排查技巧实录

5.1 key重复导致的内容错乱

有一次我在一个多选列表里用了 key 生成器返回商品名称作为 key。结果列表重排、商品名重复时，出现了勾选状态互相串的问题。点这一项，另一项跟着变。

排查过程很简单，我先把 key 生成器改成返回商品 id，问题立刻消失。但更值得反思的是为什么商品名称会重复——业务上允许同名商品存在，而我在设计 key 时没有结合业务约束。后来我给所有列表数据统一增加了 uid 字段，key 一律用 uid，再没出现过这个问题。

这里的关键经验是：key 的设计不能只看“有没有唯一性”，还要考虑业务上的长期稳定性。名称、时间、价格这类字段理论上都可能变化，不适合做 key。数据库主键、自增 ID、UUID 这类业务无关的稳定标识才是最优解。

5.2 数据更新后页面不刷新

另一个高频问题出现在深层属性上。比如数据项是个对象：

typescript复制interface CartItem {
  id: string;
  info: {
    name: string;
    remark: string;
  };
}

直接修改 item.info.name = '新名字'，Repeat 页面不刷新。原因前面提过，Repeat 的依赖追踪粒度默认停留在 item 的第一层属性，深层嵌套属性需要配合 @Observed 和数据项的引用替换才能触发更新。

解决办法有两个方向。简单做法是替换整个数据项引用：

typescript复制this.cartItems[index] = {
  ...item,
  info: { ...item.info, name: '新名字' }
};

正规做法是让数据项类加上 @Observed，深层属性变化就能被精确感知。优先推荐第二种，因为深层数据越到项目后期越多，靠手工展开替换容易漏。

5.3 template中使用了外部状态变量

还有一类问题是逻辑写错了但报错不明显。有人在 template 里直接访问组件外的 @State 变量：

typescript复制Repeat<CartItem>(this.cartItems)
  .template((item: CartItem) => {
    Text(this.globalNote) // 外部状态
    Text(item.name)
  })

这个写法在某些版本上能跑，但 this.globalNote 变化时页面可能不更新，或者影响 Repeat 的模板优化效果。Repeat 的 template 应该是纯粹基于当前数据项的纯函数，外部状态应该通过数据项属性提前传入，或者在更深层的子组件中用普通状态管理去处理。这不是 API 限制的问题，而是 Repeat 的工作机制决定了它只能精确感知数据项的变更，感知不了外部变量的变更。

5.4 Repeat和ForEach嵌套使用的隐患

最后提醒一个工程上的坑：不要在 Repeat 的 template 里再写一层 ForEach 来渲染同一数据源的子列表。这种嵌套会导致外层 Repeat 更新时，内层 ForEach 也触发全量 diff，性能损耗翻倍。

如果确实需要嵌套列表，我的做法是：外层用 Repeat 定位数据块，内层用子组件封装，子组件内部再用 Repeat 管理子列表。这样每一层的数据隔离清晰，各自的 key 都能正确匹配，不会互相干扰。

写在最后

Repeat 这个组件给了我一个很深的体会：声明式 UI 框架的循环渲染，关键在于“告诉框架哪些东西没变”，而不是“让框架自己算哪些东西变了”。用好 key、规范 template、合理管理数据引用，Repeat 在 ArkTS 项目里能发挥出接近原生列表的渲染效率。

从我踩过的坑来看，排序大致是：key 设计失误排第一，深层属性不刷新排第二，过度使用导致懒加载缺失排第三。这些问题在项目初期都很隐蔽，一旦列表数据量上来就集中爆发。所以我的建议是，从一开始就为列表数据建立稳定的 uid 字段，为可能深层次变更的数据建立 @Observed 类，在数据模型层面就把底子打好，后面切换渲染方案或做性能优化时会轻松很多。

如果你最近刚好在处理 ArkTS 列表性能问题，不妨把代码里高频率交互的列表依次迁到 Repeat 试试，配合 Profiler 工具做前后对比，效果会让你惊喜。