文档开发者中心
我的
|

ArkUI (方舟UI框架)

HarmonyOS 6

元服务

ForEach 使用 index 作为键值在数据更新时引发列表渲染错乱

已解决

应用使用 ForEach 渲染商品列表,每个商品卡片内有 @Local 的选中状态、展开状态等。为图省事使用 (item, index) => index.toString() 作为键值生成器。在以下场景出现错乱:

  1. 头部插入:列表已有 [A, B, C],在头部插入 D 变为 [D, A, B, C]。视觉上 D 出现在第一位,但 D 卡片的展开状态显示为 true(应该是 false),A 卡片的展开状态变为 false(原本是 true)
  2. 中间删除:删除 B 后列表变为 [A, C]。C 卡片显示的是 B 的内容,且 C 的 @Local 计数器保留了 B 的值
  3. 排序变更:按价格排序后,列表 UI 与数据顺序对不上

代码大致如下:

收起
自动换行
深色代码主题
复制
@Local
private items: Product[] = []

build() {
  List() {
    ForEach(this.items, (item: Product, index: number) => {
      ProductCard({ item: item })
    }, (item: Product, index: number) => index.toString())  // 问题
  }
}

疑问:为什么 index 作为键值会出问题?键值到底应该怎么设计?

点赞
收藏
回复
12
分享
举报
浏览225 发布于2026-06-30 03:34湖南
全部评论
最多点赞
最新发布
最早发布
|
采纳答复

根因是 index 只代表当前位置,不是数据项的稳定身份。插入、删除或排序后,原数据项的 index 会变化,ArkUI 可能把不同数据复用到原节点上,从而出现列表内容错位。

请使用数据自身“唯一且不随位置变化”的 id 作为 key,不要写成 item.id + index:

收起
自动换行
深色代码主题
复制
ForEach(this.list, (item: ListData) => {
  ListItem() {
    ItemView({ item: item })
  }
}, (item: ListData) => item.id)

若当前是字符串等基础类型数组,建议先包装为带固定唯一 id 的对象再渲染;同时保证 id 不重复、更新后也不变。官方案例中,使用 index 作为 key 后在中间插入数据,会出现类似 ['one', 'two', 'three', 'three'] 的非预期结果。

参考:ForEach:循环渲染(“渲染结果非预期”案例及键值使用建议)。长列表且 API 12+ 的场景也可评估使用 Repeat:可复用的循环渲染,同样应以稳定唯一 ID 作为 .key()。

若按上述方式仍可稳定复现,建议携带最小复现工程、DevEco Studio/SDK 版本、设备型号与日志,通过在线提单反馈官方进一步定位

12楼回复于2026-09-22 06:49 来自湖南

建议不要用 index 做 ForEach 的 key。ForEach 的键值用于标识并复用对应组件;键值包含数据项索引 index 时,插入、删除、排序会导致渲染结果非预期和性能下降。

你这里错乱的原因是:index 表示“当前位置”,不是“商品身份”。

原来 [A, B, C] 的 key 是 0,1,2,头部插入 D 后变成 [D, A, B, C],D 仍然拿到 key 0,ArkUI 会复用原来 A 的 ProductCard 实例,所以卡片里的 @Local 展开、选中、计数状态也被一起带过去。

推荐写法:用业务唯一 ID,并保证同一商品每次生成同一个 key。

收起
自动换行
深色代码主题
复制
ForEach(this.items, (item: Product) => {
  ProductCard({ item: item })
}, (item: Product) => item.id)

如果 id 是 number:

收起
自动换行
深色代码主题
复制
ForEach(this.items, (item: Product) => {
  ProductCard({ item: item })
}, (item: Product) => item.id.toString())

如果 itemGenerator 里确实要用 index,keyGenerator 也建议声明 index 参数,但不要把它拼进 key:

收起
自动换行
深色代码主题
复制
ForEach(this.items, (item: Product, index: number) => {
  ProductCard({ item: item, index: index })
}, (item: Product, index: number) => item.id)

键值设计原则:

  • 用 product.id、skuId、服务端主键、本地生成后持久保存的 UUID。
  • 不要用 index、Math.random()、Date.now()、每次渲染都会变化的值。
  • 列表会插入、删除、排序、筛选、拖拽、分页合并时,必须用稳定唯一 key。
  • 如果“选中/展开”本质上属于商品状态,建议提升到父组件或 Map<productId, state>,不要只放在卡片内部 @Local。

官方文档参考:

展开全部
3楼编辑于2026-06-30 06:40 来自广东

开发者您好,ForEach的第三个参数keyGenerator必须为每个数组项生成唯一且持久的键值,用于标识对应的组件,当键值未变化时,框架会认为该数组项未被替换,直接复用旧组件,导致状态错乱。

正确做法:键值应使用数据项的业务唯一标识(如商品 ID、订单号等),确保在数据增删改、排序后仍能保持唯一。

参考文档:

https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-rendering-control-foreach

https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-arkui-619

7楼回复于2026-06-30 08:23 来自山东

这个问题一般是 ForEach 的 key 选错导致的。

ForEach 的第三个参数 keyGenerator 是用来标识每一项组件身份的。列表发生插入、删除、排序或更新时,ArkUI 会根据 key 判断组件是复用、移动还是重新创建。如果直接用 index 作为 key,数据位置一变,index 也会变,框架就可能把上一项的组件状态复用到另一条数据上,结果就会出现列表内容、选中态、输入框值等渲染错乱。

建议做法是:给每条数据一个稳定唯一 id,keyGenerator 只返回这个 id,不要返回 index,也不要每次渲染临时生成随机值。

示例:

interface TodoItem {

  id: string

  title: string

  checked: boolean

}

@State list: TodoItem[] = [

  { id: '1001', title: '任务A', checked: false },

  { id: '1002', title: '任务B', checked: true }

]

ForEach(this.list, (item: TodoItem) => {

  Row() {

    Checkbox()

      .select(item.checked)

    Text(item.title)

  }

}, (item: TodoItem) => item.id)

删除或更新时也建议按 id 操作:

deleteItem(id: string) {

  this.list = this.list.filter(item => item.id !== id)

}

这样即使数组顺序变化,每条数据的组件身份仍然稳定,ArkUI 就不会因为 index 变化而误复用组件。简单说:index 只适合展示位置,不适合当列表项的唯一身份。

展开全部
11楼回复于2026-07-01 07:21 来自湖北

核心结论:index 是"位置标识"而非"身份标识"。当数组发生插入、删除、排序等操作时,index 会重新分配,导致框架错误地复用了其他数据项的组件实例,从而引发状态错乱。

https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-rendering-control-foreach

在ForEach循环渲染过程中,系统会为每个数组元素生成一个唯一且持久的键值,用于标识对应的组件。当键值变化时,ArkUI框架会视为该数组元素已被替换或修改,并会基于新的键值创建一个新的组件。

ForEach提供了一个名为keyGenerator的参数,这是一个函数,开发者可以通过它自定义键值的生成规则。如果开发者没有定义keyGenerator函数,则ArkUI框架会使用默认的键值生成函数,即(item: Object, index: number) => { return index + '__' + JSON.stringify(item); }。

ArkUI框架对于ForEach的键值生成有一套特定的判断规则,这主要与itemGenerator函数和keyGenerator函数的第二个参数index有关。具体的键值生成规则判断逻辑如下图所示。

cke_842.png

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-rendering-control-foreach

10楼回复于2026-07-01 02:43 来自广东
开发者你好可以参考官网键值生成规则以及使用建议:
  • 为满足键值的唯一性,对于对象数据类型,建议使用对象数据中的唯一id作为键值。
  1. ArkUI框架会对重复的键值发出运行时警告。在UI更新时,如果出现重复的键值,框架可能无法正常工作,具体请参见渲染结果非预期。
  2. 不建议在键值中包含数据项索引index,这可能会导致渲染结果非预期和渲染性能降低。
  3. 如果开发者在itemGenerator函数中声明了index参数,但未在keyGenerator函数中声明index参数,框架会在keyGenerator函数返回值的基础上拼接index,作为最终的键值,这将会引发上述第二点中的问题。为避免此现象,请在keyGenerator函数中声明index参数。
9楼回复于2026-07-01 02:27 来自广东

`ForEach` 的 key 用来关联旧组件实例和新数据项。index 代表位置,不代表数据身份;插入、删除、排序后,同一个 index 会指向另一条商品,框架就可能复用错旧卡片里的 @Local/@State、输入框内容或动画状态。

key 应该使用业务稳定唯一值,比如商品 id、订单号、数据库主键。示例:`(item: Product) => item.id`。如果临时数据没有 id,也应在创建时生成一次稳定 id,并随数据项一起保存,不能在 build 里每次随机生成。列表项内部有本地状态时,稳定 key 尤其重要。

8楼回复于2026-06-30 09:57 来自四川
期待解决
6楼回复于2026-06-30 08:04 来自湖南
主要是index.toString()引发的问题;
由于后续操作需要顺序变更,重新排序等操作,索引重新分配,而键值绑定的是数组位置而非数据身份;
建议Product 类中新增id等字段,确保同一数据项无论位置如何变化,键值始终不变; 例如使用Item.id作为索引
5楼回复于2026-06-30 06:50 来自江苏

ForEach 的第三个参数是组件复用的 key,框架会按 key 关联旧组件实例和状态。index 是位置,不是数据身份;插入、删除、排序后,同一个 index 会指向另一条数据,于是旧卡片里的 @State、动画状态、TextInput 内容等就被复用到错误项上。

key 要用稳定且唯一的业务字段,例如商品 id、skuId、消息 id。没有后端 id 时,在数据创建时生成一次 _uiKey 并跟随数据保存,不要在 keyGenerator 里用 Date.now()/Math.random() 每次重建。写法类似:ForEach(this.items, item => { ProductCard({ item }) }, item => item.id)。只有纯静态且不会增删排序的列表,才可以考虑 index。

4楼回复于2026-06-30 06:48 未知归属地
共2页
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。