当前位置：首页 > news >正文

【HarmonyOS】List组件多层对象嵌套ForEach渲染更新完全指南（@Observed、@ObjectLink、@State、Array刷新原理

news 2026/7/12 18:27:34

一、前言

很多HarmonyOS开发者都会遇见下面这种情况。

例如：

@State list: User[] = []

页面：

List() { ForEach(this.list, (item) => { ListItem() { Text(item.name) } }) }

点击按钮：

this.list[0].name = "Tom"

结果：

UI没有刷新！！

很多人第一反应：

我不是修改数据了吗？

实际上：

ArkUI并不是监听Java Bean，也不是Vue那种Proxy。

它有自己的响应式系统。

理解它以后，所有刷新问题都会迎刃而解。

二、List为什么不刷新？

例如：

class User { id:number name:string }

页面：

@State users:User[] = [ new User(1,"Jack"), new User(2,"Rose") ]

List

List(){ ForEach(this.users,(item)=>{ ListItem(){ Text(item.name) } }) }

点击：

this.users[0].name="Lucy"

发现：

页面没变化

为什么？

因为：

State │ │ users(Array) │ ├────User │ │ │ name │ ├────User

ArkUI只知道：

users

并不知道：

users[0].name

发生变化。

三、ArkUI真正监听的是谁？

实际上监听的是：

变量引用

例如：

@State users=[]

监听的是：

users

不是：

users[0]

更不是：

users[0].name

所以：

users.push()

刷新。

因为：

Array改变

而

users[0].name="Tom"

没有通知State。

四、ForEach刷新机制

很多人认为：

ForEach

每次都会重新执行。

实际上不是。

真正流程：

State变化 ↓ Array Diff ↓ 计算新增 ↓ 计算删除 ↓ 计算移动 ↓ 更新对应ListItem

所以：

ForEach不是重新创建全部Item

而是：

Diff更新

五、为什么官方要求Key？

例如：

ForEach( list, (item)=>{ }, item=>item.id )

这里：

id

就是Diff依据。

没有Key：

全部刷新

有Key：

精准刷新

这就是Recycler思想。

六、多层对象嵌套

实际项目：

class User{ id:number info:UserInfo }

UserInfo

class UserInfo{ avatar:string nick:string }

页面：

Text(item.info.nick)

点击：

item.info.nick="Tom"

结果：

仍然不刷新

为什么？

因为：

State ↓ User ↓ UserInfo ↓ nick

State根本不知道：

nick

发生变化。

七、三层对象更加明显

例如：

Order ↓ Goods ↓ Sku ↓ Price

修改：

order.goods.sku.price=100

页面：

不会刷新

原因完全一样。

八、正确方案一：整体替换对象

例如：

this.users[0] = { ...this.users[0], name:"Tom" }

然后：

this.users=[...this.users]

这样：

Array引用变化

UI刷新。

优点：

简单

缺点：

大量对象复制

九、正确方案二：@Observed

定义：

@Observed class User{ id:number name:string }

List：

@State users:User[]=[]

Item：

@Component struct Item{ @ObjectLink user:User build(){ Text(this.user.name) } }

修改：

user.name="Lucy"

立即刷新。

原因：

Observed ↓ 属性变化 ↓ ObjectLink收到通知 ↓ 组件刷新

十、多层对象如何写？

例如：

@Observed class Address{ city:string }

再定义：

@Observed class User{ address:Address }

Item：

@ObjectLink user:User

修改：

user.address.city="北京"

即可触发深层更新。

十一、ForEach嵌套ForEach

例如：

List(){ ForEach(orderList,(order)=>{ ListItem(){ Column(){ Text(order.name) ForEach(order.goods,(good)=>{ Text(good.name) }) } } }) }

更新：

good.name="苹果"

如果：

没有Observed

不会刷新。

正确方案：

Goods ↓ Observed ↓ ObjectLink ↓ Item组件

十二、企业项目推荐架构

推荐拆分：

Page ↓ OrderList ↓ OrderItem ↓ GoodsList ↓ GoodsItem

数据：

@State ↓ @ObjectLink ↓ @Observed

形成完整响应链：

State ↓ Observed ↓ ObjectLink ↓ UI

这样即使四层、五层对象嵌套，也只刷新发生变化的组件，而不会整页重建。

十三、常见踩坑总结

问题	原因	推荐方案
修改对象属性不刷新	`@State`不监听对象成员	使用`@Observed + @ObjectLink`
List 更新整个页面	未设置稳定 Key	为`ForEach`提供唯一`id`
嵌套对象不刷新	深层对象未观察	所有需要响应更新的类使用`@Observed`
`@Prop`修改无效	单向传递，不支持回写	改用`@Link`或`@ObjectLink`
每次刷新整个 List	替换整个数组	组件拆分 + 精细化更新