状态管理：ArkUI 响应式系统的形式化语义与工程实践

状态管理是声明式 UI 框架的”中枢神经”——UI 是状态的函数 UI = f(State)，状态管理决定了应用的复杂度、可维护性与性能上限。本章按照 MIT 6.831（User Interface Design）、CMU 17-645（Distributed Systems）、Stanford CS147（Introduction to Human-Computer Interaction）等课程标准组织，系统讲解 ArkUI 的状态管理装饰器矩阵（@State/@Prop/@Link/@Provide/@Consume/@ObjectLink/@Observed/@Watch/@StorageLink/@StorageProp/@LocalStorageLink/@LocalStorageProp）、响应式系统的形式化语义（信号模型、依赖追踪、最小化重渲染）、复杂度分析、跨组件数据流的工程模式、不可变更新与可变更新的边界、与 Redux/MobX/Zustand/Recoil 的对比、生产级状态架构、时间旅行调试、跨设备状态同步等核心议题，并对照 React、Vue、SwiftUI、Flutter、Jetpack Compose 等业界方案。

关键词：状态管理、响应式、装饰器、单向数据流、双向绑定、依赖追踪、不可变更新、时间旅行、跨设备同步

1. 学习目标

本章按照 Bloom 教育目标分类法（Bloom’s Taxonomy）的六个层级组织学习目标。读者完成本章后应能够：

1.1 Remember（记忆）

• R1：复述 ArkUI 状态管理装饰器的完整矩阵：@State、@Prop、@Link、@Provide、@Consume、@ObjectLink、@Observed、@Watch、@StorageLink、@StorageProp、@LocalStorageLink、@LocalStorageProp。
• R2：复述每个装饰器的数据流方向：@State（组件内）、@Prop（父→子，单向，深拷贝）、@Link（父↔子，双向，引用）、@Provide/@Consume（跨级，双向）、@ObjectLink（嵌套对象，双向）。
• R3：复述 AppStorage、LocalStorage 两个全局状态容器的差异：AppStorage 应用级、LocalStorage Ability 内级。
• R4：复述 @Watch 的回调签名：@Watch('callbackName')，回调接收 propName: string 参数。
• R5：复述 @Observed 与 @ObjectLink 的协作关系：@Observed 装饰类使其属性可被追踪，@ObjectLink 接收 @Observed 类的实例。
• R6：复述 $$ 双向绑定运算符的使用场景：将 @State 变量以引用形式传入子组件的 @Link。

1.2 Understand（理解）

• U1：解释 ArkUI 响应式系统采用”信号（Signal）“模型而非”脏标记（Dirty Bit）“或”虚拟 DOM Diff”的原因。
• U2：阐明 @Prop 的深拷贝语义在性能上的代价，以及何时应该避免使用 @Prop 传递大对象。
• U3：解释 @Link 双向绑定如何避免无限循环——框架的”赋值抑制”机制。
• U4：阐明 @Provide/@Consume 与 React Context 的差异：前者支持双向，后者单向。
• U5：解释 @ObjectLink 必须与 @Observed 配对使用的根本原因——@Observed 在类的属性上安装 getter/setter，@ObjectLink 让子组件订阅这些 setter。

1.3 Apply（应用）

• A1：使用 @State、@Prop、@Link 实现父子组件的双向计数器。
• A2：使用 @Provide/@Consume 实现主题切换功能，跨 3 层组件共享。
• A3：使用 @Observed/@ObjectLink 实现嵌套对象的响应式更新（如购物车商品列表）。
• A4：使用 AppStorage + @StorageLink 实现全局登录状态管理。

1.4 Analyze（分析）

• An1：分析 @Prop 与 @Link 在数据流方向上的差异，论证”单向数据流”原则的重要性。
• An2：分析 @Provide/@Consume 与 Redux 在大型应用中的适用性差异。
• An3：分析 @State 修饰数组时，push/pop/splice 与直接赋值在响应式触发上的差异。

1.5 Evaluate（评价）

• E1：评价 ArkUI 选择”装饰器矩阵”而非”统一状态管理库”的设计哲学。
• E2：评价 @StorageLink 全局状态的引入是否违背了”状态最小化”原则。
• E3：评价 @ObjectLink 的双向绑定与 React 的”单一数据源”原则的冲突与调和。

1.6 Create（创造）

• C1：设计一个基于 @StorageLink 的全局状态管理库，支持分片（Slicing）、中间件（Middleware）、时间旅行（Time-Travel）。
• C2：设计一个跨设备状态同步方案，使用 distributedDataObject + @StorageLink。
• C3：设计一个状态管理静态分析工具，自动检测循环依赖、未订阅的状态、过度渲染。

2. 历史动机与发展脉络

2.1 前端状态管理的演进（2010-2024）

前端状态管理经历了从”组件内 state”到”全局 store”再到”原子化状态”的范式转变：

ArkUI 的状态管理设计动机有三个：

1. 跨端一致性：HarmonyOS 全形态设备需要统一的状态管理抽象；
2. AOT 友好：装饰器是编译期可分析的元编程机制，适合 AOT 优化；
3. 降低心智负担：前端开发者熟悉装饰器（如 Java 注解、Python 装饰器），学习曲线平缓。

2.2 ArkUI 1.0（2019）：基础三件套

ArkUI 1.0 引入了基础的状态管理装饰器：

• @State：组件内部状态，可读写，触发重渲染；
• @Prop：父→子单向，深拷贝；
• @Link：父↔子双向，引用传递。

这一阶段的设计借鉴了 SwiftUI 的 @State/@Binding，但简化了泛型约束。

2.3 ArkUI 2.0（2021-2022）：跨级共享与全局状态

ArkUI 2.0 引入了跨级与全局状态管理：

• @Provide/@Consume：跨多层级组件共享状态；
• AppStorage：应用级全局状态容器；
• LocalStorage：Ability 内状态容器；
• @StorageLink/@StorageProp：双向/单向绑定 AppStorage；
• @LocalStorageLink/@LocalStorageProp：双向/单向绑定 LocalStorage；
• @Observed/@ObjectLink：嵌套对象的响应式追踪；
• @Watch：状态变化监听。

这一阶段的设计受 React Context 与 Vue Provide/Inject 影响，但保留了装饰器风格。

2.4 ArkUI 3.0 与 NEXT（2024）：细粒度追踪

HarmonyOS NEXT 引入了更细粒度的状态追踪：

• @Trace：属性级追踪，仅订阅被读取的属性；
• @Provider/@Consumer：类型安全的跨级共享，取代 @Provide/@Consume；
• @Sendable：跨线程共享对象（用于 Worker 间通信）。

2.5 设计哲学：ArkUI 状态管理的”五项原则”

ArkUI 状态管理遵循华为公开的”五项原则”：

1. 单一数据源（Single Source of Truth）：每个状态变量有明确的”所有者”；
2. 单向数据流（Unidirectional Data Flow）：状态变化通过显式赋值，而非事件；
3. 最小化订阅（Minimal Subscription）：仅订阅真正使用的状态；
4. 不可变优先（Immutable First）：复杂对象使用整体替换，而非原地修改；
5. 跨端一致（Cross-Device Consistent）：状态管理 API 在不同设备上一致。

3. 形式化定义

3.1 响应式系统的信号模型

ArkUI 的响应式系统遵循”信号（Signal）“模型。定义：

为状态存储（State Store）。每个 @State 变量对应一个信号。当信号被读取时，读取者（通常是渲染闭包）被加入订阅集合：

当信号被写入时，框架通知所有订阅者：

3.2 装饰器的形式化语义

3.2.1 @State 的语义

@State 装饰器将字段 $f$ 转换为带 getter/setter 的属性：

3.2.2 @Prop 的语义

@Prop 在父组件状态变化时，对子组件做深拷贝：

3.2.3 @Link 的语义

@Link 建立父子间的双向绑定：

3.2.4 @Provide/@Consume 的语义

@Provide 在祖先组件注册状态，@Consume 在后代组件订阅：

3.3 复杂度分析

3.3.1 单次状态更新的复杂度

设组件树 $T$ 有 $n$ 个节点，状态变化触发 $k$ 个订阅闭包。单次更新复杂度：

其中 $\text{cost}(r)$ 是渲染闭包执行成本，$\text{cost}(\text{diff}) = O(m)$（$m$ 是同层节点数）。

3.3.2 深拷贝的代价

@Prop 的深拷贝复杂度：

其中 $|o|$ 是对象大小，$d$ 是嵌套深度。对于大数组（1000+ 元素），深拷贝可能耗时 10-50ms。

3.3.3 @ObjectLink vs @Prop 的性能对比

3.4 响应式更新的不变量

命题 1（响应式一致性）：若 @State 变量 $v$ 被修改，则所有依赖 $v$ 的 UI 部分在下一帧渲染前被更新。

命题 2（双向绑定无环）：若 @Link 建立父子双向绑定，框架保证不会产生无限循环——当子组件修改 @Link 变量时，框架抑制父组件的回调。

证明：框架在子组件 set 时标记 isUpdating = true，父组件收到通知后检查 isUpdating，若为 true 则跳过 notify。$\square$

4. 理论推导与复杂度分析

4.1 依赖追踪的最小化

ArkUI 的依赖追踪采用”读取时订阅”策略：

这意味着：

• 若渲染闭包 $f$ 在某次执行中未读取 $v$，则 $v$ 变化不触发 $f$；
• 条件分支（if/else）会导致订阅集合动态变化。

推论 1：若 @State showB: boolean = false，且 build() 中有 if (this.showB) { Text(this.textB) }，则 textB 变化仅在 showB == true 时触发重渲染。

4.2 批处理与异步更新

ArkUI 默认采用”批处理”策略：

这意味着同一帧内多次状态变化只触发一次重渲染。但跨帧的变化会分别触发。

推论 2：在 onClick 回调中连续修改 10 个 @State 变量，只触发一次重渲染。

4.3 @Watch 的执行时机

@Watch 回调在状态变化”之后、重渲染之前”执行：

这意味着 @Watch 可以在重渲染前修改其他状态，所有修改合并为一次重渲染。

4.4 嵌套对象的响应式追踪

@Observed 在类的所有属性上安装 getter/setter：

但 @State 修饰 @Observed 类的实例时，只追踪”实例引用”的变化，不追踪实例内部属性。要追踪内部属性，需要将实例传递给 @ObjectLink 修饰的子组件字段。

命题 3：@State items: ObservedItem[] 中，items.push(x) 触发响应式（数组方法被劫持），但 items[0].prop = x 不触发（属性修改未被劫持）。

要解决此问题，需要：

1. 使用 @ObjectLink 在子组件中接收 items[0]；
2. 或在 @Observed 类内部修改属性（被 @Observed 装饰的类，其属性 setter 触发响应式）。

4.5 AppStorage 与 LocalStorage 的作用域

AppStorage 是应用级单例，所有 Ability 共享；LocalStorage 是 Ability 级，每个 Ability 独立。

跨 Ability 时，AppStorage 中的数据保持，LocalStorage 中的数据隔离。

5. 代码示例

5.1 基础：@State 单组件状态

// 文件：StateBasic.ets
// 功能：演示 @State 的基础用法
// 重点：理解 @State 的响应式触发机制

@Entry
@Component
struct Counter {
  // @State 修饰的变量，变化时触发 build 重新执行
  @State count: number = 0
  // 修饰字符串
  @State title: string = '计数器'
  // 修饰布尔
  @State isVisible: boolean = true
  // 修饰数组（数组方法被劫持）
  @State items: string[] = ['苹果', '香蕉']

  build() {
    Column() {
      // 显示标题
      Text(this.title)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)

      // 显示计数
      Text(`当前计数：${this.count}`)
        .fontSize(20)
        .margin({ top: 20 })

      // 控制可见性
      if (this.isVisible) {
        Text('这段文字可见')
          .fontSize(16)
          .fontColor('#007DFF')
      }

      // 数组渲染
      ForEach(this.items, (item: string) => {
        Text(item).fontSize(14)
      }, (item: string, index: number) => `${item}_${index}`)

      // 按钮区
      Row() {
        Button('加 1')
          .onClick(() => {
            // 修改 @State 触发重渲染
            this.count++
          })

        Button('切换可见性')
          .onClick(() => {
            this.isVisible = !this.isVisible
          })

        Button('添加水果')
          .onClick(() => {
            // 数组 push 被劫持，触发响应式
            this.items.push('橙子' + this.items.length)
          })
      }
      .margin({ top: 20 })
    }
    .padding(20)
  }
}

5.2 进阶：@Prop 单向数据流

// 文件：PropDemo.ets
// 功能：演示 @Prop 的单向数据流与深拷贝语义
// 场景：父组件持有原始状态，子组件接收并展示

// 父组件
@Entry
@Component
struct Parent {
  @State message: string = '来自父组件的消息'
  @State count: number = 0
  @State user: User = { name: '张三', age: 28 }

  build() {
    Column() {
      Text('父组件').fontSize(20).fontWeight(FontWeight.Bold)
      Text(`message: ${this.message}`).fontSize(14)
      Text(`count: ${this.count}`).fontSize(14)
      Text(`user.name: ${this.user.name}`).fontSize(14)

      Divider().margin({ top: 20, bottom: 20 })

      // 子组件接收 @Prop
      // 注意：传入的是值的拷贝，子组件修改不影响父组件
      Child({
        message: this.message,
        count: this.count,
        user: this.user
      })

      Divider().margin({ top: 20, bottom: 20 })

      // 修改父组件状态，观察子组件是否更新
      Button('父组件修改 message')
        .onClick(() => {
          this.message = '父组件修改后的消息 ' + Date.now()
        })

      Button('父组件修改 count')
        .onClick(() => {
          this.count++
        })
    }
    .padding(20)
  }
}

// 子组件
@Component
struct Child {
  // @Prop 修饰的变量会做深拷贝
  // 父组件修改时，子组件接收到新值
  // 子组件修改时，不影响父组件
  @Prop message: string
  @Prop count: number
  @Prop user: User

  build() {
    Column() {
      Text('子组件（@Prop）').fontSize(18).fontWeight(FontWeight.Bold)
      Text(`message: ${this.message}`).fontSize(14)
      Text(`count: ${this.count}`).fontSize(14)
      Text(`user.name: ${this.user.name}`).fontSize(14)

      Button('子组件修改 message')
        .onClick(() => {
          // 子组件修改 @Prop，仅在子组件内部生效
          // 父组件的 message 不会改变
          this.message = '子组件修改的消息'
        })

      Button('子组件修改 user.name')
        .onClick(() => {
          // 由于 @Prop 做了深拷贝
          // 修改 user.name 仅影响子组件的副本
          this.user.name = '李四'
        })
    }
    .padding(12)
    .backgroundColor('#F5F5F5')
    .borderRadius(8)
  }
}

interface User {
  name: string
  age: number
}

5.3 进阶：@Link 双向绑定

// 文件：LinkDemo.ets
// 功能：演示 @Link 的双向绑定
// 场景：父子组件共享同一份数据，任一方修改都同步

@Entry
@Component
struct Parent {
  @State count: number = 0
  @State text: string = '初始文本'

  build() {
    Column() {
      Text('父组件').fontSize(20).fontWeight(FontWeight.Bold)
      Text(`count: ${this.count}`).fontSize(16)
      Text(`text: ${this.text}`).fontSize(16)

      Divider().margin({ top: 20, bottom: 20 })

      // 使用 $ 前缀传递引用，建立双向绑定
      // $count 等价于 $$this.count
      Child({ count: $count, text: $text })

      Divider().margin({ top: 20, bottom: 20 })

      Button('父组件 +1')
        .onClick(() => {
          this.count++
        })
    }
    .padding(20)
  }
}

@Component
struct Child {
  // @Link 修饰的变量建立双向绑定
  // 类型必须与父组件 @State 变量一致
  @Link count: number
  @Link text: string

  build() {
    Column() {
      Text('子组件（@Link）').fontSize(18).fontWeight(FontWeight.Bold)
      Text(`count: ${this.count}`).fontSize(14)
      Text(`text: ${this.text}`).fontSize(14)

      Button('子组件 -1')
        .onClick(() => {
          // 修改 @Link 变量，自动同步到父组件
          this.count--
        })

      Button('子组件修改 text')
        .onClick(() => {
          this.text = '子组件修改的文本'
        })
    }
    .padding(12)
    .backgroundColor('#E8F5E9')
    .borderRadius(8)
  }
}

5.4 高级：@Provide / @Consume 跨级共享

// 文件：ProvideConsumeDemo.ets
// 功能：演示跨多层级组件的状态共享
// 场景：主题、用户信息、应用配置等需要在深层组件中访问

// 顶层组件：作为状态提供者
@Entry
@Component
struct App {
  // @Provide 装饰，子树中任意层级都能 @Consume
  // 必须配合 @State 使用，否则无法响应变化
  @Provide('themeColor') @State themeColor: string = '#007DFF'
  @Provide('fontSize') @State fontSize: number = 16
  @Provide('userInfo') @State userInfo: UserInfo = {
    name: '张三',
    avatar: '/images/avatar.png',
    isLoggedIn: true
  }

  build() {
    Column() {
      Button('切换主题')
        .onClick(() => {
          this.themeColor = this.themeColor === '#007DFF' ? '#FF4081' : '#007DFF'
        })

      Button('增大字体')
        .onClick(() => {
          this.fontSize++
        })

      // 中间层组件，不需要感知主题
      MiddleLayer()

      // 退出登录
      Button('退出登录')
        .onClick(() => {
          this.userInfo.isLoggedIn = false
        })
    }
    .padding(20)
  }
}

// 中间层组件：不直接使用主题，但传递子组件
@Component
struct MiddleLayer {
  build() {
    Column() {
      DeepChild()
      AnotherDeepChild()
    }
  }
}

// 深层组件：直接 @Consume 主题状态
@Component
struct DeepChild {
  // 使用 @Consume 与 @Provide 的 key 匹配
  // 框架向上查找最近的 @Provide
  @Consume('themeColor') themeColor: string
  @Consume('fontSize') fontSize: number
  @Consume('userInfo') userInfo: UserInfo

  build() {
    Column() {
      Text(`用户：${this.userInfo.name}`)
        .fontSize(this.fontSize)
        .fontColor(this.themeColor)
        .padding(10)
        .border({ width: 2, color: this.themeColor })
        .borderRadius(8)

      if (this.userInfo.isLoggedIn) {
        Text('已登录').fontColor('#4CAF50')
      } else {
        Text('未登录').fontColor('#F44336')
      }
    }
  }
}

// 另一个深层组件
@Component
struct AnotherDeepChild {
  @Consume('themeColor') themeColor: string

  build() {
    Button('按钮')
      .backgroundColor(this.themeColor)
      .fontColor('#FFFFFF')
  }
}

interface UserInfo {
  name: string
  avatar: string
  isLoggedIn: boolean
}

5.5 高级：@Observed 与 @ObjectLink 嵌套对象

// 文件：ObservedDemo.ets
// 功能：演示嵌套对象的响应式追踪
// 问题：@State 只能追踪第一层属性变化，嵌套对象内部变化需要 @Observed + @ObjectLink

// 使用 @Observed 标记可观察类
// ArkTS 会在该类的所有属性上自动安装 getter/setter
@Observed
class TodoItem {
  id: number
  text: string
  done: boolean
  priority: number

  constructor(id: number, text: string, priority: number = 0) {
    this.id = id
    this.text = text
    this.done = false
    this.priority = priority
  }

  // 类内部方法修改属性，会触发响应式（因为 setter 已安装）
  toggle() {
    this.done = !this.done
  }

  setPriority(p: number) {
    this.priority = p
  }
}

// 列表项组件：使用 @ObjectLink 接收 @Observed 对象
@Component
struct TodoItemView {
  // @ObjectLink 修饰的变量必须是 @Observed 类的实例
  // 与 @Link 不同，@ObjectLink 建立对对象本身的引用
  // 对象内部属性变化时，子组件会收到通知
  @ObjectLink item: TodoItem
  onToggle: (id: number) => void = () => {}
  onRemove: (id: number) => void = () => {}

  build() {
    Row() {
      // 直接修改 item.done，触发响应式
      Checkbox()
        .select(this.item.done)
        .onChange((value) => {
          this.item.done = value
        })

      Column() {
        Text(this.item.text)
          .fontSize(16)
          .decoration({
            type: this.item.done ? TextDecorationType.LineThrough : TextDecorationType.None
          })

        // 显示优先级
        Text(`优先级：${this.item.priority}`)
          .fontSize(12)
          .fontColor('#999999')
      }
      .layoutWeight(1)
      .margin({ left: 12 })

      // 修改优先级，触发响应式
      Button('↑')
        .fontSize(12)
        .width(32)
        .height(32)
        .onClick(() => {
          this.item.priority++
        })

      Button('删除')
        .fontSize(12)
        .backgroundColor('#FF4D4F')
        .onClick(() => {
          this.onRemove(this.item.id)
        })
    }
    .padding(12)
  }
}

// 列表组件
@Entry
@Component
struct TodoList {
  @State items: TodoItem[] = [
    new TodoItem(1, '学习 ArkTS 基础', 1),
    new TodoItem(2, '完成状态管理实践', 2),
    new TodoItem(3, '阅读官方文档', 0)
  ]

  build() {
    Column() {
      Text('待办事项')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 })

      // 统计信息
      Row() {
        Text(`总数：${this.items.length}`).fontSize(14)
        Text(`已完成：${this.items.filter(i => i.done).length}`).fontSize(14).margin({ left: 20 })
      }
      .margin({ bottom: 20 })

      ForEach(
        this.items,
        (item: TodoItem) => {
          TodoItemView({
            item: item,
            onRemove: (id: number) => {
              // 数组重新赋值，触发响应式
              this.items = this.items.filter(i => i.id !== id)
            }
          })
        },
        (item: TodoItem) => item.id.toString()
      )

      Button('添加')
        .margin({ top: 20 })
        .onClick(() => {
          const newId = Math.max(...this.items.map(i => i.id), 0) + 1
          this.items.push(new TodoItem(newId, `新任务 ${newId}`))
        })
    }
    .padding(20)
  }
}

5.6 高级：@Watch 状态监听

// 文件：WatchDemo.ets
// 功能：演示 @Watch 监听状态变化
// 场景：状态变化时触发副作用（如日志、持久化、API 调用）

@Entry
@Component
struct ShoppingCart {
  @State items: CartItem[] = []
  @State discount: number = 0

  // @Watch 监听 items 变化，回调函数名为 onItemsChange
  @Watch('onItemsChange') @State items watcher: CartItem[] = []

  // 监听 discount 变化
  @Watch('onDiscountChange') @State discountWatcher: number = 0

  // 回调函数：接收变化属性名
  onItemsChange(propName: string) {
    console.info(`[${propName}] changed, length = ${this.items.length}`)
    // 可以在这里做副作用：持久化、统计、API 调用
    this.persistCart()
  }

  onDiscountChange(propName: string) {
    console.info(`[${propName}] changed to ${this.discount}`)
    if (this.discount > 100) {
      // 在 @Watch 中修改其他状态，会被批处理合并为一次重渲染
      this.discount = 100
    }
  }

  persistCart() {
    // 持久化到 AppStorage
    AppStorage.setOrCreate('cart', JSON.stringify(this.items))
  }

  // 计算总价：使用 getter，避免引入额外的 @State
  get totalPrice(): number {
    const subtotal = this.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
    return subtotal * (1 - this.discount / 100)
  }

  build() {
    Column() {
      Text('购物车').fontSize(24).fontWeight(FontWeight.Bold)

      ForEach(this.items, (item: CartItem) => {
        Row() {
          Text(`${item.name} x ${item.quantity}`).fontSize(14)
          Blank()
          Text(`￥${item.price * item.quantity}`).fontSize(14)
        }
        .padding(8)
      }, (item: CartItem) => item.id.toString())

      Divider().margin({ top: 20, bottom: 20 })

      Row() {
        Text('折扣：').fontSize(16)
        TextInput({
          text: this.discount.toString(),
          placeholder: '0-100'
        })
          .width(80)
          .onChange((value) => {
            const num = parseInt(value, 10)
            if (!isNaN(num)) {
              this.discount = num
            }
          })
      }

      Row() {
        Text('总价：').fontSize(20).fontWeight(FontWeight.Bold)
        Blank()
        Text(`￥${this.totalPrice.toFixed(2)}`).fontSize(20).fontColor('#FF4D4F')
      }
      .margin({ top: 20 })

      Button('添加商品')
        .margin({ top: 20 })
        .onClick(() => {
          this.items.push({
            id: Date.now(),
            name: '商品 ' + (this.items.length + 1),
            price: 50,
            quantity: 1
          })
        })
    }
    .padding(20)
  }
}

interface CartItem {
  id: number
  name: string
  price: number
  quantity: number
}

5.7 高级：AppStorage 全局状态

// 文件：AppStorageDemo.ets
// 功能：演示 AppStorage 应用级全局状态管理
// 场景：登录状态、用户信息、主题配置等全局共享

// 在 Ability 启动时初始化全局状态
export class AppInitializer {
  static init() {
    // 初始化全局状态
    AppStorage.setOrCreate('isLogin', false)
    AppStorage.setOrCreate('userInfo', {
      id: 0,
      name: '',
      avatar: '',
      token: ''
    })
    AppStorage.setOrCreate('theme', 'light')
    AppStorage.setOrCreate('language', 'zh-CN')

    // 从持久化存储恢复
    this.restoreFromPersistent()
  }

  static async restoreFromPersistent() {
    try {
      const preferences = await preferencesHelper.getPreferences('app_state')
      const isLogin = await preferences.get('isLogin', false)
      const userInfo = await preferences.get('userInfo', '{}')

      AppStorage.set('isLogin', isLogin)
      AppStorage.set('userInfo', JSON.parse(userInfo as string))
    } catch (error) {
      console.error('恢复状态失败：' + (error as Error).message)
    }
  }

  static async persist() {
    const preferences = await preferencesHelper.getPreferences('app_state')
    await preferences.put('isLogin', AppStorage.get('isLogin'))
    await preferences.put('userInfo', JSON.stringify(AppStorage.get('userInfo')))
    await preferences.flush()
  }
}

// 全局状态访问组件
@Component
export struct UserProfile {
  // @StorageLink 双向绑定 AppStorage 中的 'userInfo'
  // 任一组件修改，所有绑定的组件都更新
  @StorageLink('userInfo') userInfo: UserInfo = {
    id: 0, name: '', avatar: '', token: ''
  }
  @StorageLink('isLogin') isLogin: boolean = false

  build() {
    Row() {
      if (this.isLogin) {
        Image(this.userInfo.avatar)
          .width(40)
          .height(40)
          .borderRadius(20)

        Text(this.userInfo.name)
          .fontSize(14)
          .margin({ left: 8 })
      } else {
        Button('登录')
          .onClick(() => {
            // 跳转登录页
            router.pushUrl({ url: 'pages/Login' })
          })
      }
    }
  }
}

// 登录页：修改全局状态
@Entry
@Component
struct LoginPage {
  @State username: string = ''
  @State password: string = ''
  @StorageLink('isLogin') isLogin: boolean = false
  @StorageLink('userInfo') userInfo: UserInfo = {
    id: 0, name: '', avatar: '', token: ''
  }

  async login() {
    try {
      const result = await api.login(this.username, this.password)
      // 修改 @StorageLink，自动同步到 AppStorage 和其他绑定组件
      this.userInfo = {
        id: result.userId,
        name: this.username,
        avatar: result.avatar,
        token: result.token
      }
      this.isLogin = true

      // 持久化
      await AppInitializer.persist()

      // 返回上一页
      router.back()
    } catch (error) {
      console.error('登录失败：' + (error as Error).message)
    }
  }

  build() {
    Column() {
      TextInput({ placeholder: '用户名' })
        .onChange((v) => { this.username = v })

      TextInput({ placeholder: '密码' })
        .type(InputType.Password)
        .onChange((v) => { this.password = v })

      Button('登录')
        .onClick(() => this.login())
    }
    .padding(20)
  }
}

interface UserInfo {
  id: number
  name: string
  avatar: string
  token: string
}

5.8 高级：LocalStorage Ability 级状态

// 文件：LocalStorageDemo.ets
// 功能：演示 LocalStorage Ability 级状态管理
// 场景：不同 Ability 隔离的状态

// 在 EntryAbility 中创建 LocalStorage
import UIAbility from '@ohos.app.ability.UIAbility'

export default class EntryAbility extends UIAbility {
  // 创建 LocalStorage
  // 同一 Ability 内的所有页面共享
  // 跨 Ability 隔离
  localStorage: LocalStorage = new LocalStorage({
    currentPage: 'home',
    scrollPosition: 0,
    selectedTab: 0
  })

  onWindowStageCreate(windowStage) {
    // 将 LocalStorage 传递给页面
    windowStage.loadContent('pages/Index', this.localStorage)
  }
}

// 页面中使用 @LocalStorageLink 双向绑定
@Entry
@Component
struct HomePage {
  // 双向绑定 LocalStorage 中的 'currentPage'
  @LocalStorageLink('currentPage') currentPage: string = 'home'
  @LocalStorageLink('selectedTab') selectedTab: number = 0
  // 单向读取，不可修改
  @LocalStorageProp('scrollPosition') scrollPosition: number = 0

  build() {
    Column() {
      Text(`当前页面：${this.currentPage}`).fontSize(20)

      Row() {
        Button('首页')
          .backgroundColor(this.selectedTab === 0 ? '#007DFF' : '#CCCCCC')
          .onClick(() => {
            this.selectedTab = 0
            this.currentPage = 'home'
          })

        Button('我的')
          .backgroundColor(this.selectedTab === 1 ? '#007DFF' : '#CCCCCC')
          .onClick(() => {
            this.selectedTab = 1
            this.currentPage = 'profile'
          })
      }
    }
    .padding(20)
  }
}

5.9 综合：完整购物车案例

// 文件：ShoppingCart.ets
// 功能：综合演示状态管理各装饰器的协作
// 涉及：@State/@Prop/@Link/@Provide/@Consume/@Observed/@ObjectLink/@Watch/@StorageLink

// 购物车商品：使用 @Observed 支持嵌套响应式
@Observed
class CartProduct {
  id: number
  name: string
  price: number
  quantity: number
  selected: boolean

  constructor(id: number, name: string, price: number, quantity: number = 1) {
    this.id = id
    this.name = name
    this.price = price
    this.quantity = quantity
    this.selected = true
  }

  // 类内方法修改属性，触发响应式
  increment() {
    this.quantity++
  }

  decrement() {
    if (this.quantity > 1) {
      this.quantity--
    }
  }

  toggleSelect() {
    this.selected = !this.selected
  }

  get subtotal(): number {
    return this.price * this.quantity
  }
}

// 单个商品卡片组件
@Component
struct ProductCard {
  // 使用 @ObjectLink 接收 @Observed 对象
  // 对象内部属性变化时，子组件自动更新
  @ObjectLink product: CartProduct

  build() {
    Row() {
      Checkbox()
        .select(this.product.selected)
        .onChange((v) => {
          // 直接修改 @ObjectLink 对象的属性
          this.product.selected = v
        })

      Column() {
        Text(this.product.name).fontSize(14)
        Text(`￥${this.price}`).fontSize(12).fontColor('#999999')
      }
      .layoutWeight(1)
      .margin({ left: 12 })

      Row() {
        Button('-')
          .width(32).height(32)
          .onClick(() => this.product.decrement())

        Text(`${this.product.quantity}`)
          .fontSize(14)
          .margin({ left: 8, right: 8 })

        Button('+')
          .width(32).height(32)
          .onClick(() => this.product.increment())
      }

      Text(`￥${this.product.subtotal.toFixed(2)}`)
        .fontSize(14)
        .fontColor('#FF4D4F')
        .margin({ left: 12 })
    }
    .padding(12)
    .backgroundColor('#FFFFFF')
    .borderRadius(8)
  }
}

// 顶部栏：显示总数量
@Component
struct CartHeader {
  // 使用 @Consume 获取购物车总数
  @Consume('totalQuantity') totalQuantity: number

  build() {
    Row() {
      Text('购物车').fontSize(20).fontWeight(FontWeight.Bold)
      Blank()
      Text(`共 ${this.totalQuantity} 件商品`).fontSize(14)
    }
    .width('100%')
    .padding(16)
  }
}

// 底部结算栏
@Component
struct CheckoutBar {
  @Consume('totalPrice') totalPrice: number
  @Consume('selectedCount') selectedCount: number
  @Consume('selectAll') selectAll: boolean
  onSelectAllChange: (v: boolean) => void = () => {}
  onCheckout: () => void = () => {}

  build() {
    Row() {
      Checkbox()
        .select(this.selectAll)
        .onChange((v) => this.onSelectAllChange(v))
      Text('全选').fontSize(14).margin({ left: 8 })

      Blank()

      Text('合计：').fontSize(16)
      Text(`￥${this.totalPrice.toFixed(2)}`)
        .fontSize(20)
        .fontColor('#FF4D4F')
        .fontWeight(FontWeight.Bold)
        .margin({ right: 16 })

      Button(`结算(${this.selectedCount})`)
        .backgroundColor('#FF4D4F')
        .fontColor('#FFFFFF')
        .onClick(() => this.onCheckout())
    }
    .width('100%')
    .padding(16)
    .backgroundColor('#FFFFFF')
  }
}

// 主页面
@Entry
@Component
struct ShoppingCartPage {
  // @Provide 提供跨级共享状态
  @Provide('totalQuantity') @State totalQuantity: number = 0
  @Provide('totalPrice') @State totalPrice: number = 0
  @Provide('selectedCount') @State selectedCount: number = 0
  @Provide('selectAll') @State selectAll: boolean = true

  // 购物车数据
  @State products: CartProduct[] = []

  // @Watch 监听 products 变化，自动更新统计信息
  @Watch('updateStats') @State productsWatcher: CartProduct[] = []

  aboutToAppear() {
    // 模拟数据加载
    this.products = [
      new CartProduct(1, '商品 A', 99),
      new CartProduct(2, '商品 B', 199, 2),
      new CartProduct(3, '商品 C', 49, 3)
    ]
    this.updateStats()
  }

  // 监听回调：更新统计
  updateStats(propName?: string) {
    this.totalQuantity = this.products.reduce((s, p) => s + p.quantity, 0)
    this.totalPrice = this.products
      .filter(p => p.selected)
      .reduce((s, p) => s + p.subtotal, 0)
    this.selectedCount = this.products.filter(p => p.selected).length
    this.selectAll = this.products.length > 0 && this.products.every(p => p.selected)
  }

  toggleSelectAll(value: boolean) {
    this.products.forEach(p => p.selected = value)
    this.updateStats()
  }

  checkout() {
    if (this.selectedCount === 0) {
      promptAction.showToast({ message: '请选择商品' })
      return
    }
    // 跳转结算页
    router.pushUrl({ url: 'pages/Checkout' })
  }

  build() {
    Column() {
      // 顶部
      CartHeader()

      // 商品列表
      List({
        space: 8
      }) {
        ForEach(this.products, (product: CartProduct) => {
          ListItem() {
            ProductCard({ product: product })
          }
        }, (product: CartProduct) => product.id.toString())
      }
      .layoutWeight(1)
      .padding(8)

      // 底部结算栏
      Divider()
      CheckoutBar({
        onSelectAllChange: (v: boolean) => this.toggleSelectAll(v),
        onCheckout: () => this.checkout()
      })
    }
  }
}

6. 对比分析

6.1 ArkUI 状态管理装饰器矩阵

6.2 与 React 状态管理对比

6.3 与 Vue 状态管理对比

6.4 与 SwiftUI 状态管理对比

6.5 不可变更新 vs 可变更新

ArkUI 同时支持两种风格，开发者可按场景选择。

7. 常见陷阱与反模式

7.1 陷阱：在 @State 中直接修改对象属性

错误代码：

@State user: User = { name: '张三', age: 28 }

// 错误：直接修改对象属性，不会触发响应式更新
this.user.age = 29

问题分析：@State 只追踪”变量赋值”，不追踪”对象内部属性修改”。修改 this.user.age 不会触发 user 的 setter。

正确做法：

// 方案 1：使用 @Observed + @ObjectLink（推荐）
@Observed
class User {
  name: string
  age: number
  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }
}

@State user: User = new User('张三', 28)
// 修改属性触发响应式
this.user.age = 29

// 方案 2：整体替换（不可变更新）
@State user: User = { name: '张三', age: 28 }
this.user = { ...this.user, age: 29 }

7.2 陷阱：@Prop 与 @Link 混用导致数据不一致

错误代码：

@State count: number = 0

// 子组件 A 使用 @Prop（深拷贝）
ChildA({ value: this.count })

// 子组件 B 使用 @Link（双向绑定）
ChildB({ count: $count })

问题分析：子组件 B 修改 count 后，父组件 @State 更新，但子组件 A 的 @Prop 是旧值的深拷贝，A、B 显示不一致。

正确做法：同一份数据要么全用 @Prop（单向），要么全用 @Link（双向）。

7.3 陷阱：在 build 方法中修改状态

错误代码：

build() {
  // 错误：在 build 中修改状态，触发无限循环
  this.count++

  Column() { Text(`${this.count}`) }
}

问题分析：build 中修改状态会触发新的重渲染，新的重渲染又执行 build，导致无限循环。

正确做法：在事件回调或生命周期中修改状态。

7.4 陷阱：@Watch 中引发循环依赖

错误代码：

@State a: number = 0
@State b: number = 0

@Watch('onAChange') aWatcher: number = 0
@Watch('onBChange') bWatcher: number = 0

onAChange() {
  // 错误：在 a 变化的回调中修改 b
  this.b = this.a + 1
}

onBChange() {
  // 错误：在 b 变化的回调中修改 a
  this.a = this.b - 1
}

问题分析：a 变化触发 onAChange，修改 b，触发 onBChange，修改 a，循环。

正确做法：避免 @Watch 回调中修改互相依赖的状态；若必须，使用标志位避免循环。

7.5 陷阱：@Provide 未配合 @State

错误代码：

// 错误：@Provide 单独使用，无 @State
@Provide('theme') theme: string = 'light'

问题分析：@Provide 必须与 @State 配合，否则修改 theme 不会触发响应式。

正确做法：

@Provide('theme') @State theme: string = 'light'

7.6 陷阱：@ObjectLink 接收非 @Observed 对象

错误代码：

class Item {
  name: string
}

@Component
struct ItemView {
  // 错误：Item 未用 @Observed 装饰
  @ObjectLink item: Item
}

问题分析：@ObjectLink 要求接收的对象是 @Observed 类的实例，否则无法追踪属性变化。

正确做法：

@Observed
class Item {
  name: string
}

7.7 反模式：所有状态都用 @StorageLink

问题：将所有状态放入 AppStorage，导致：

1. 全局重渲染范围扩大；
2. 状态耦合度高，难以测试；
3. 内存占用大。

正确做法：仅将真正需要全局共享的状态（如登录、主题）放入 AppStorage，局部状态用 @State。

7.8 反模式：在 @Observed 类中混入业务逻辑

问题：

@Observed
class Order {
  async submit() {
    // 错误：在 @Observed 类中混入业务逻辑
    const result = await api.submit(this)
    this.status = 'submitted'
  }
}

正确做法：@Observed 类应是纯数据模型，业务逻辑放在 Service 层。

7.9 生产事故：状态丢失

事故背景：某应用在后台被系统杀死后重启，用户购物车数据丢失。

根因分析：

1. 购物车状态仅用 @State 存储，未持久化；
2. 系统在内存压力下杀死应用，所有内存状态丢失。

修复方案：

@Entry
@Component
struct CartPage {
  @State items: CartItem[] = []

  async aboutToAppear() {
    // 从持久化存储恢复
    const saved = await preferences.get('cart', '[]')
    this.items = JSON.parse(saved as string)
  }

  // @Watch 监听变化，自动持久化
  @Watch('persist') itemsWatcher: CartItem[] = []

  async persist() {
    await preferences.put('cart', JSON.stringify(this.items))
    await preferences.flush()
  }
}

7.10 生产事故：过度渲染

事故背景：某列表页滚动卡顿，FPS 仅 20。

根因分析：

1. 列表项组件使用 @Prop 接收整个列表，每次列表变化都深拷贝；
2. 每个列表项内部使用 @StorageLink 绑定全局主题，全局主题变化导致所有列表项重渲染。

修复方案：

1. 列表项改用 @ObjectLink + @Observed；
2. 仅在真正需要主题的组件中 @Consume。

8. 工程实践

8.1 状态管理分层架构

应用状态
├── AppStorage（全局共享）
│   ├── 用户登录状态
│   ├── 主题配置
│   ├── 语言设置
│   └── 应用配置
├── LocalStorage（Ability 级）
│   ├── 当前页面
│   ├── 滚动位置
│   └── 选中标签
├── @Provide（页面级共享）
│   ├── 表单数据
│   ├── 页面状态
│   └── 弹窗控制
└── @State（组件内）
    ├── 局部 UI 状态
    ├── 加载状态
    └── 临时输入

8.2 状态管理设计原则

1. 就近原则：状态尽量放在使用它的组件内；
2. 最小化原则：能用 @State 解决的，不用 @Provide；
3. 不可变优先：复杂对象用整体替换；
4. 单一职责：每个状态变量只承担一个职责；
5. 持久化关键状态：用户数据、配置等需要持久化。

8.3 状态持久化模式

// 文件：utils/PersistHelper.ts
// 通用持久化工具

export class PersistHelper {
  private static cache: Map<string, any> = new Map()

  // 保存状态
  static async save<T>(key: string, value: T): Promise<void> {
    try {
      const json = JSON.stringify(value)
      const preferences = await preferencesHelper.getPreferences('app_state')
      await preferences.put(key, json)
      await preferences.flush()
      PersistHelper.cache.set(key, value)
    } catch (error) {
      console.error(`持久化失败 ${key}: ${(error as Error).message}`)
    }
  }

  // 加载状态
  static async load<T>(key: string, defaultValue: T): Promise<T> {
    // 优先从缓存读取
    if (PersistHelper.cache.has(key)) {
      return PersistHelper.cache.get(key) as T
    }

    try {
      const preferences = await preferencesHelper.getPreferences('app_state')
      const json = await preferences.get(key, JSON.stringify(defaultValue))
      const value = JSON.parse(json as string) as T
      PersistHelper.cache.set(key, value)
      return value
    } catch (error) {
      console.error(`加载失败 ${key}: ${(error as Error).message}`)
      return defaultValue
    }
  }

  // 清除状态
  static async clear(key: string): Promise<void> {
    try {
      const preferences = await preferencesHelper.getPreferences('app_state')
      await preferences.delete(key)
      await preferences.flush()
      PersistHelper.cache.delete(key)
    } catch (error) {
      console.error(`清除失败 ${key}: ${(error as Error).message}`)
    }
  }
}

// 使用装饰器模式封装持久化状态
export function Persistent(key: string) {
  return function (target: any, propertyKey: string) {
    let value: any

    // 在组件 aboutToAppear 时加载
    Object.defineProperty(target, propertyKey, {
      get() {
        return value
      },
      set(newValue) {
        value = newValue
        PersistHelper.save(key, newValue)
      },
      enumerable: true,
      configurable: true
    })
  }
}

8.4 时间旅行调试

// 文件：utils/TimeTravel.ts
// 时间旅行调试工具

export class TimeTravel<T> {
  private history: T[] = []
  private pointer: number = -1
  private listeners: ((state: T) => void)[] = []
  private maxHistory: number = 50

  constructor(initialState: T) {
    this.commit(initialState)
  }

  commit(state: T): void {
    // 截断 pointer 后的历史
    this.history = this.history.slice(0, this.pointer + 1)
    this.history.push(state)
    this.pointer++

    // 限制历史长度
    if (this.history.length > this.maxHistory) {
      this.history.shift()
      this.pointer--
    }

    this.notify()
  }

  undo(): void {
    if (this.pointer > 0) {
      this.pointer--
      this.notify()
    }
  }

  redo(): void {
    if (this.pointer < this.history.length - 1) {
      this.pointer++
      this.notify()
    }
  }

  jump(index: number): void {
    if (index >= 0 && index < this.history.length) {
      this.pointer = index
      this.notify()
    }
  }

  get state(): T {
    return this.history[this.pointer]
  }

  get canUndo(): boolean {
    return this.pointer > 0
  }

  get canRedo(): boolean {
    return this.pointer < this.history.length - 1
  }

  subscribe(listener: (state: T) => void): () => void {
    this.listeners.push(listener)
    return () => {
      this.listeners = this.listeners.filter(l => l !== listener)
    }
  }

  private notify(): void {
    this.listeners.forEach(l => l(this.state))
  }
}

8.5 跨设备状态同步

// 文件：utils/DistributedState.ts
// 跨设备状态同步

import distributedDataObject from '@ohos.data.distributedDataObject'

export class DistributedState<T> {
  private distributedObject: distributedData.DistributedDataObject
  private sessionId: string
  private listeners: ((state: T) => void)[] = []

  constructor(sessionId: string, initialState: T) {
    this.sessionId = sessionId
    this.distributedObject = distributedDataObject.create(initialState as any)
    this.distributedObject.setSessionId(sessionId)

    // 监听远程变更
    this.distributedObject.on('change', () => {
      const state = this.distributedObject as unknown as T
      this.listeners.forEach(l => l(state))
    })
  }

  update(state: Partial<T>): void {
    Object.assign(this.distributedObject, state)
  }

  get state(): T {
    return this.distributedObject as unknown as T
  }

  subscribe(listener: (state: T) => void): () => void {
    this.listeners.push(listener)
    return () => {
      this.listeners = this.listeners.filter(l => l !== listener)
    }
  }

  destroy(): void {
    this.distributedObject.setSessionId('')
    this.listeners = []
  }
}

// 使用示例
@Entry
@Component
struct SharedNotePage {
  @State note: string = ''
  private distState: DistributedState<{ note: string }>

  aboutToAppear() {
    this.distState = new DistributedState('shared-note', { note: '' })
    this.distState.subscribe((state) => {
      this.note = state.note
    })
  }

  aboutToDisappear() {
    this.distState.destroy()
  }

  build() {
    Column() {
      TextInput({ text: this.note })
        .onChange((v) => {
          this.note = v
          this.distState.update({ note: v })
        })
    }
  }
}

8.6 状态管理性能优化

8.6.1 减少 @Prop 的深拷贝

// 错误：大数组用 @Prop
@Component
struct BadList {
  @Prop items: BigItem[]  // 每次父组件修改，深拷贝整个数组
}

// 正确：用 @ObjectLink + @Observed
@Observed
class BigItem { ... }

@Component
struct GoodList {
  @ObjectLink items: BigItem[]  // 引用，不深拷贝
}

8.6.2 使用 @Watch 替代 computed

// 错误：每次重渲染都计算
@State items: Item[] = []

build() {
  // 错误：每次 build 都 reduce
  Text(`总价：${this.items.reduce((s, i) => s + i.price, 0)}`)
}

// 正确：用 @Watch 缓存
@State items: Item[] = []
@State totalPrice: number = 0

@Watch('updateTotal') itemsWatcher: Item[] = []

updateTotal() {
  this.totalPrice = this.items.reduce((s, i) => s + i.price, 0)
}

build() {
  Text(`总价：${this.totalPrice}`)
}

8.6.3 避免在 build 中创建新对象

// 错误：每次 build 创建新对象
build() {
  Column() {
    Text('Hello')
  }
  .padding({ top: 20, bottom: 20 })  // 错误：每次创建新对象
}

// 正确：在组件外定义常量
const PADDING = { top: 20, bottom: 20 }

build() {
  Column() {
    Text('Hello')
  }
  .padding(PADDING)
}

8.7 状态管理测试

// 文件：test/CartStore.test.ets
import { CartStore } from '../stores/CartStore'

describe('CartStore', () => {
  let store: CartStore

  beforeEach(() => {
    store = new CartStore()
  })

  it('should add product', () => {
    store.add({ id: 1, name: 'Test', price: 100, quantity: 1 })
    expect(store.items.length).toBe(1)
    expect(store.totalPrice).toBe(100)
  })

  it('should update quantity', () => {
    store.add({ id: 1, name: 'Test', price: 100, quantity: 1 })
    store.updateQuantity(1, 3)
    expect(store.totalPrice).toBe(300)
  })

  it('should remove product', () => {
    store.add({ id: 1, name: 'Test', price: 100, quantity: 1 })
    store.remove(1)
    expect(store.items.length).toBe(0)
  })

  it('should clear cart', () => {
    store.add({ id: 1, name: 'Test', price: 100, quantity: 1 })
    store.clear()
    expect(store.items.length).toBe(0)
    expect(store.totalPrice).toBe(0)
  })
})

9. 案例研究

9.1 案例一：电商购物车的状态架构

背景：某电商应用购物车需要支持：

• 多设备同步；
• 离线模式；
• 历史回溯。

方案：

// 三层状态架构
// 1. UI 层：@State（局部状态，如输入框）
// 2. 页面层：@Provide（购物车数据，跨组件共享）
// 3. 全局层：AppStorage + distributedData（跨设备同步）

@Entry
@Component
struct CartPage {
  // 全局状态：登录用户
  @StorageLink('userInfo') userInfo: UserInfo = { ... }

  // 页面级状态：购物车
  @Provide('cart') @State cart: CartItem[] = []
  @Provide('cartVersion') @State cartVersion: number = 0

  // 跨设备同步
  private distCart: DistributedState<CartItem[]>

  aboutToAppear() {
    // 加载本地数据
    this.loadLocalCart()
    // 建立跨设备同步
    this.distCart = new DistributedState(`cart_${this.userInfo.id}`, this.cart)
    this.distCart.subscribe((remoteCart) => {
      this.cart = remoteCart
      this.cartVersion++
    })
  }

  build() { ... }
}

9.2 案例二：表单状态管理

背景：某保险投保表单 30+ 字段，需要：

• 步骤间共享数据；
• 表单校验；
• 草稿自动保存。

方案：

@Entry
@Component
struct InsuranceForm {
  // 顶层 Provide 表单数据
  @Provide('formData') @State formData: FormData = { ... }
  @Provide('errors') @State errors: Record<string, string> = {}
  @Provide('currentStep') @State currentStep: number = 1

  // @Watch 自动保存草稿
  @Watch('saveDraft') formDataWatcher: FormData = { ... }

  async saveDraft() {
    await PersistHelper.save('form_draft', this.formData)
  }

  build() { ... }
}

// 各步骤组件 @Consume
@Component
struct Step1Form {
  @Consume('formData') formData: FormData
  @Consume('errors') errors: Record<string, string>

  build() { ... }
}

9.3 案例三：实时协作编辑

背景：某文档应用需要支持多人实时协作编辑。

方案：

@Entry
@Component
struct DocEditor {
  @State content: string = ''
  @State collaborators: Collaborator[] = []
  private distDoc: DistributedState<{ content: string, version: number }>

  aboutToAppear() {
    this.distDoc = new DistributedState(`doc_${this.docId}`, {
      content: '',
      version: 0
    })

    this.distDoc.subscribe((state) => {
      // OT 算法合并远程变更
      this.content = this.mergeChanges(this.content, state.content)
    })
  }

  onLocalChange(newContent: string) {
    this.content = newContent
    this.distDoc.update({ content: newContent, version: Date.now() })
  }
}

9.4 案例四：性能优化前后对比

项目：某新闻应用列表页优化。

优化手段：

1. 列表项从 @Prop 改为 @ObjectLink + @Observed；
2. 移除不必要的 @StorageLink；
3. 使用 @Watch 缓存计算属性；
4. 静态内容提取为 @Builder；
5. 大对象使用整体替换而非原地修改。

10. 习题

10.1 基础题

题 1：简述 @State、@Prop、@Link 的区别。

参考答案要点：

• @State：组件内状态，可读写，变化触发重渲染；
• @Prop：父→子单向，深拷贝，子组件修改不影响父；
• @Link：父↔子双向，引用传递，子组件修改同步父。

题 2：解释 @Observed 与 @ObjectLink 的关系。

参考答案要点：

• @Observed 装饰类，在属性上安装 getter/setter；
• @ObjectLink 在子组件中接收 @Observed 实例；
• 二者配对使用，实现嵌套对象的响应式追踪。

题 3：以下代码有什么问题？

@State user: User = { name: '张三', age: 28 }

updateAge() {
  this.user.age = 29
}

参考答案要点：

• @State 不追踪对象内部属性修改；
• updateAge 不会触发重渲染；
• 修复：用 @Observed + @ObjectLink，或整体替换 this.user = { ...this.user, age: 29 }。

10.2 进阶题

题 4：设计一个支持撤销/重做的状态管理方案。

参考答案要点：

• 维护 history: T[] 与 pointer: number；
• 每次 commit 截断后续历史并压栈；
• undo/redo 移动 pointer；
• 注意防抖避免高频压栈。

题 5：分析 @Provide/@Consume 与 React Context 的差异。

参考答案要点：

• ArkUI 支持双向，React 仅单向；
• ArkUI 通过装饰器查找最近 Provider，React 通过组件树查找；
• ArkUI 性能更高（AOT 优化），React 需要额外优化避免全树重渲染。

题 6：解释 @Watch 的执行时机与限制。

参考答案要点：

• 执行时机：状态变化后、重渲染前；
• 限制：不能在回调中修改自身状态（循环依赖）；
• 限制：不能在回调中执行耗时操作（阻塞重渲染）。

10.3 挑战题

题 7：设计一个跨设备状态同步方案。

参考答案要点：

• 使用 distributedDataObject 建立跨设备共享对象；
• 设置 sessionId 标识同步组；
• 监听 change 事件接收远程变更；
• 使用 OT 或 CRDT 算法解决冲突。

题 8：实现一个状态管理中间件系统。

参考答案要点：

type Middleware<T> = (state: T, next: (newState: T) => void) => void

class StateManager<T> {
  private state: T
  private middlewares: Middleware<T>[] = []

  constructor(initial: T) {
    this.state = initial
  }

  use(mw: Middleware<T>) {
    this.middlewares.push(mw)
  }

  update(newstate: T) {
    // 执行中间件链
    const chain = this.middlewares.reduceRight(
      (next, mw) => () => mw(this.state, next),
      () => { this.state = newstate }
    )
    chain()
  }
}