流浪小鱼做鸿蒙应用开发的朋友应该都有过这种体验：列表页数据量一上来，用 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 是给每本书贴了唯一的编号，哪本动了就只处理哪本，其他书原地不动。数据量越大，这种“精确打击”的优势就越明显。
| 维度 | ForEach | Repeat |
|---|---|---|
| 渲染机制 | 全量 diff 后更新 | 按 key 精准匹配，局部更新 |
| 模板生成 | 每项独立生成 | 循环体编译为单一模板 |
| 节点复用 | 差，key 变化时容易重建 | 好，key 不变则原地复用 |
| 性能特征 | 数据量小时可接受 | 数据量越大优势越明显 |
| 适用场景 | 静态列表、小数据量 | 高频交互、动态增删改 |
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
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 直接退化成性能更差的 ForE