一、前言
很多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 │ ├────UserArkUI只知道：
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 ↓ nickState根本不知道：
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 | 替换整个数组 | 组件拆分 + 精细化更新 |
十四、最佳实践
在企业级 HarmonyOS 项目中，建议遵循以下原则：
- 列表数据必须提供稳定唯一的 Key，避免使用索引作为 Key。
- 列表项拆分为独立组件，降低刷新粒度。
- 可变对象统一使用
@Observed修饰。 - 子组件通过
@ObjectLink持有对象引用，实现属性级更新。 - 避免频繁整体替换数组，减少内存分配和 Diff 开销。
- 复杂业务（如电商、IM、通讯录）采用多层组件结构，让刷新范围限制在最小组件。
