@Observed/@ObjectLink深层监听：嵌套对象更新失效根源与修复

一、前言

在鸿蒙 ArkTS 开发中，90% 的UI 不刷新疑难 Bug，都集中在「嵌套对象、嵌套数组深度修改不更新」场景。

很多开发者遇到过这种诡异现象：

明明接口数据已经变更、打印日志字段已更新
页面 UI 纹丝不动、完全不刷新
强行赋值、解构替换又能刷新，代码写得极其冗余

绝大多数人只会无脑加 @State ，不知道 @State 只支持浅层监听，无法穿透嵌套对象。

而官方专门解决深层监听的 @Observed + @ObjectLink，大部分人都用错了：要么只加单个装饰器、要么嵌套层级缺失监听、要么数组场景适配错误。

本文彻底讲透：失效底层根源、错误示范、企业标准正确写法、多层嵌套/数组嵌套完整修复方案、高频踩坑总结，一次性根治嵌套数据 UI 不刷新问题。

二、先搞懂：为什么 @State 嵌套修改不刷新？

1. @State 核心机制：浅层监听

ArkUI V1 状态管理核心规则：@State 仅监听第一层引用变化，不做深度递归监听。

简单理解：

外层对象 重新赋值、替换引用 → 可以触发刷新
内层属性、嵌套对象、数组元素 局部修改 → 引用未变，无法触发刷新

2. 错误示范（全网最高频垃圾写法）

嵌套对象直接使用 @State，修改内层属性，UI 完全不刷新：

typescript 复制代码

// 嵌套数据模型
class UserInfo {
  name: string = ""
  // 嵌套子对象
  address: Address = new Address()
}
class Address {
  city: string = ""
  detail: string = ""
}

@Entry
@Component
struct StateErrorDemo {
  // 错误：@State 无法监听深层属性
  @State user: UserInfo = new UserInfo()

  // 内层修改，UI 不刷新
  changeAddr() {
    this.user.address.city = "深圳市"
    this.user.address.detail = "鸿蒙产业园"
  }

  build() {
    Column() {
      Text(`城市：${this.user.address.city}`)
      Text(`详情：${this.user.address.detail}`)
      Button("修改嵌套数据").onClick(() => this.changeAddr())
    }
  }
}

3. 失效根源总结（核心考点）

UI 刷新的本质是：状态标记「脏节点」。

内层属性修改，外层 user 对象的内存引用地址未发生改变，ArkUI 不会标记脏节点，视图自然不会重绘。

这就是所有嵌套数据不刷新的根本原因。

三、官方深度监听方案：@Observed + @ObjectLink 组合

1. 两个装饰器分工（必须成对使用）

@Observed：修饰实体类，让类的属性具备「可监听能力」，开启细粒度变更捕获
@ObjectLink：子组件接收父组件数据，建立双向深度监听链路，追踪内层属性变化

关键铁律：嵌套链路每一层实体类，必须全部加 @Observed，缺一不可。

2. 完整正确可运行代码（多层嵌套修复）

typescript 复制代码

// 1. 所有嵌套层级全部增加 @Observed
@Observed
class UserInfo {
  name: string = ""
  address: Address = new Address()
}

@Observed
class Address {
  city: string = ""
  detail: string = ""
}

// 子组件：通过 @ObjectLink 接收深度监听对象
@Component
struct AddressItem {
  // 建立深度双向监听
  @ObjectLink addr: Address

  build() {
    Column() {
      Text(`城市：${this.addr.city}`)
      Text(`详情：${this.addr.detail}`)
    }
  }
}

@Entry
@Component
struct ObservedCorrectDemo {
  @State user: UserInfo = new UserInfo()

  changeAddr() {
    // 直接修改内层嵌套属性，正常触发UI刷新
    this.user.address.city = "深圳市"
    this.user.address.detail = "鸿蒙产业园"
  }

  build() {
    Column() {
      AddressItem({ addr: this.user.address })
      Button("修改嵌套数据").onClick(() => this.changeAddr())
    }
  }
}

四、高频难点：嵌套数组对象更新失效修复

业务中 80% 场景是「数组嵌套对象」，单纯修改数组 item 属性，UI 同样不刷新，也是项目重灾区。

1. 数组场景错误示例

typescript 复制代码

class Goods {
  name: string = ""
  status: number = 0
}

@Entry
@Component
struct ListErrorDemo {
  @State goodsList: Goods[] = [new Goods()]

  changeStatus() {
    // 数组子对象属性修改，不刷新
    this.goodsList[0].status = 1
  }
}

2. 数组场景标准修复方案

typescript 复制代码

// 数组子项必须加 @Observed
@Observed
class Goods {
  name: string = "默认商品"
  status: number = 0
}

@Component
struct GoodsItem {
  // 子组件监听数组子对象
  @ObjectLink item: Goods

  build() {
    Row() {
      Text(`商品状态：${this.item.status === 0 ? "未上架" : "已上架"}`)
      Button("切换状态").onClick(() => {
        this.item.status = this.item.status === 0 ? 1 : 0
      })
    }
  }
}

@Entry
@Component
struct ListCorrectDemo {
  @State goodsList: Goods[] = [new Goods()]

  build() {
    Column() {
      ForEach(this.goodsList, (item: Goods) => {
        GoodsItem({ item: item })
      })
    }
  }
}

核心逻辑：数组本身无需 @Observed，数组内部每一个实体类必须 @Observed，子组件通过 @ObjectLink 绑定。

五、@ObjectLink 与 @Prop 核心区别（选型必看）

很多人混淆两个装饰器，导致监听失效、双向数据流混乱。

装饰器	数据流	深度监听	适用场景
@Prop	单向拷贝	浅层监听	简单数据、不需要修改原数据
@ObjectLink	双向引用联动	深度监听（支持嵌套）	嵌套对象、子组件修改父组件数据源

结论：只要是嵌套对象、子组件需要修改原数据，一律用 @ObjectLink。

六、企业开发高频踩坑全集（99% 人踩过）

坑点1：只加 @ObjectLink，实体类不加 @Observed

现象：代码不报错，但永远不刷新。

原因：类没有被监听代理，属性变更无法被捕获。

规范：所有嵌套层级实体类，全部强制添加 @Observed。

坑点2：多层嵌套，中间层级漏加 @Observed

现象：深层修改失效，浅层修改正常。

原理：监听链路断裂，无法穿透中间层。

规范：监听链路必须完整，一层不能少。

坑点3：使用 @ObjectLink 同时本地重新实例化

现象：双向绑定失效、数据错乱。

规范：@ObjectLink 变量禁止 new 覆盖，保持引用联动。

坑点4：ForEach 渲染嵌套对象，未使用子组件托管

现象：直接在 ForEach 内部修改属性，不刷新。

规范：复杂嵌套数据必须抽离子组件，由子组件 @ObjectLink 托管监听。

坑点5：误以为 @State 可以深度监听

无论多少层嵌套，只要是内层属性修改，@State 永远无法监听，只能靠 Observed+ObjectLink。

七、官方标准选型总结（可直接落地团队规范）

简单基础数据（字符串、数字、布尔）：直接使用 @State
单层普通对象：优先 @State + 外层替换刷新
多层嵌套对象、嵌套数组对象：强制 @Observed + @ObjectLink
子组件需要修改父组件原数据：必须使用 @ObjectLink，禁止 @Prop

八、面试高频问答

Q1：嵌套对象修改后 UI 不刷新的根本原因？

ArkUI @State 为浅层监听，仅监听外层对象引用变化；修改嵌套内层属性不会改变外层引用，无法触发脏节点标记，视图不会重绘。需要通过 @Observed 开启类的细粒度监听，搭配 @ObjectLink 建立深度监听链路解决。

Q2：@Observed 和 @ObjectLink 各自作用是什么？必须配套使用吗？

@Observed 用于修饰实体类，让类属性具备可监听能力；@ObjectLink 用于子组件接收数据，实现双向深度监听。处理嵌套数据刷新问题必须配套使用，缺一不可。

Q3：@Prop 和 @ObjectLink 最大区别？

@Prop 是单向数据拷贝，仅支持浅层监听，子组件修改不影响父组件；@ObjectLink 是双向引用联动，支持嵌套深度监听，子组件修改会同步父组件原始数据源，适合复杂嵌套业务。

九、全文总结

嵌套数据 UI 不刷新，不是 Bug，是对 ArkUI 浅层监听机制不熟悉。

记住核心口诀：单层用State、嵌套用组合、实体全Observed、子层ObjectLink。