HarmonyOS应用开发高级认证知识点梳理 （三）状态管理V2装饰器核心规则
以下是针对HarmonyOS应用开发高级认证备考的状态管理V2装饰器核心规则知识点系统梳理：
一、核心装饰器分类与功能
1. 组件声明装饰器
@ComponentV2
(1)基础定义与限制
功能定位
用于装饰自定义组件，启用V2状态管理能力，需配合V2专属装饰器（如@Local、@Param）使用
API支持：从API version 12开始支持
强制限制
不可与@Component混用，同一struct只能选择一种装饰器
内部禁止使用V1装饰器（如@State、@Link）
(2)核心特性
状态管理协同
仅支持V2装饰器家族：
@Local（组件内部状态，禁止外部初始化）
@Param（父子组件单向同步输入）
@Once（需与@Param联用，仅初始化同步一次）
性能优化参数
freezeWhenInactive：可选布尔参数，启用组件冻结功能以减少内存占用
(3)开发规范与认证考点
典型结构示例
@ComponentV2
struct MyComponent { @Local count: number = 0; // 内部状态@Param @Once title: string = "V2"; // 外部单次输入 build() { /* UI构建 */ }
} 高频错误排查
编译报错：尝试在@ComponentV2中使用@State等V1装饰器
状态失效：@Local变量被外部初始化（违反设计原则）
认证重点
装饰器选型对比：@ComponentV2与@Component的适用场景差异
状态管理机制差异
状态变量支持
@ComponentV2
仅支持V2状态装饰器：
@Local：替代@State，禁止外部初始化（纯内部状态）
@Param：父子组件单向同步（外部输入）
@Once：需与@Param联用，仅允许初始化同步一次
@Component
支持V1状态装饰器：
@State/@Prop/@Link等传统方案
@Observed+@ObjectLink实现嵌套监听（需逐层绑定）
嵌套对象监听能力
@ComponentV2：通过@ObservedV2+@Trace实现属性级精准更新，支持深层嵌套监听
@Component：依赖@Observed+@ObjectLink，仅支持第一层属性监听，深层需手动逐级传递
性能优化能力
| 特性 | @ComponentV2 | @Component |
|---|---|---|
| 组件冻结 | 支持freezeWhenInactive参数减少内存占用 | 不支持 |
| 复用机制 | 需配合@ReusableV2实现实例缓存 | 原生支持组件复用 |
| 列表渲染效率 | 搭配@Trace实现数组项级差分更新 | 数组更新常触发全量刷新 |
开发约束与兼容性
强制限制
@ComponentV2：
禁止使用V1装饰器（如@State、@Link）
暂不支持LocalStorage等全局状态管理
@Component：
禁止混用V2装饰器（如@Local）
迁移成本
@ComponentV2需重写状态逻辑，但深度监听场景代码量减少50%
@Component兼容旧项目，但嵌套数据结构维护复杂度更高
典型场景推荐
| 场景 | 推荐方案 | 核心优势 |
|---|---|---|
| 深层嵌套对象监听 | @ComponentV2 | 属性级精准更新，避免全刷新 |
| 高频列表渲染 | @ComponentV2+@ReusableV2 | 复用实例+项级更新提升帧率 |
| 简单父子组件通信 | @Component | @Prop/@Link语法简洁 |
| 全局状态共享 | @Component | 原生支持AppStorage |
关键迁移提示：两者不可共存，同一组件只能选择一种装饰器方案。
状态同步机制：@Param与@Once的同步行为区别
1. @Param的同步行为
持续同步机制：当父组件的源数据变化时，@Param装饰的变量会自动同步更新，并触发子组件刷新。
例如：
@ComponentV2
struct Parent {@Local parentData: string = "Initial";build() {Column() {Child({ childParam: this.parentData }) // 父数据变化时，childParam同步更新}}
}
@ComponentV2
struct Child {@Param childParam: string; // 持续接收父数据变化
}观测范围：支持简单类型（如number、string）和复杂类型（如Array、Object），对复杂类型的整体或元素变化均能观测。
限制：子组件内不允许直接修改@Param变量本身（仅能通过父组件源数据驱动更新）。
2. @Once的同步行为
一次性同步机制：仅在与@Param联用时生效，在子组件初始化时同步父组件数据一次，后续父数据变化不触发同步。
例如：
@ComponentV2
struct Child {@Param @Once childOnceParam: string; // 仅初始化时同步一次
}使用场景：适用于数据初始化后需保持静态的场景（如配置参数），避免后续父数据变更干扰子组件状态。
强制约束：
必须与@Param搭配使用，单独使用无效。
禁止与其他装饰器（如@Local）混用。
3. 关键区别总结
| 特性 | @Param | @Once（需搭配@Param） |
|---|---|---|
| 同步时机 | 父数据实时同步（持续更新） | 仅初始化时同步一次（后续无更新） |
| 更新触发 | 父数据变化时自动刷新子组件 | 初始化后父数据变化不影响子组件 |
| 子组件内可修改性 | 禁止直接修改 | 允许在初始化后本地修改值 |
| 适用场景 | 需动态响应父数据变更（如实时列表） | 静态初始化数据（如一次性配置） |
典型错误示例：
错误：单独使用@Once（如@Once str: string）导致编译失败。
错误：在@Component（非V2）中混用@Once。
附：V1/V2装饰器对比表
| 特性 | V1 | V2 |
|---|---|---|
| 状态变量装饰器 | @State/@Link | @Local/@Param |
| 组件复用 | 支持 | 暂不支持 |
| 对象深度监听 | 需多层@ObjectLink | @Trace精准更新 |
@ReusableV2
(1)基础定义与版本适配
功能定位
用于标记@ComponentV2装饰的自定义组件可复用，通过缓存机制减少重复创建开销
API支持：需API version 12及以上，与V2状态管理系统深度绑定
核心优势
内存优化：复用组件实例及关联JSView对象，降低GC频率
性能提升：减少布局计算和渲染树diff时间（实测列表滑动性能提升95%+）
(2)关键机制与生命周期
复用流程
回收阶段：组件从树移除 → 触发aboutToRecycle() → 存入缓存池
复用阶段：匹配相同reuseId → 调用aboutToReuse(params) → 更新数据后插入新位置
生命周期对比
| 阶段 | 触发条件 | 典型操作 |
|---|---|---|
aboutToRecycle | 组件被移入缓存池前 | 释放非共享资源（如定时器） |
aboutToReuse | 从缓存池复用时 | 重置状态/更新参数 |
(3)开发规范与认证考点
强制约束条件
必须与@ComponentV2联用，不可装饰@Builder函数或嵌套组件
组件需设计为无状态或状态可重置，否则复用会导致数据错乱
最佳实践示例
@ReusableV2
@ComponentV2
struct ListItem { @Param itemData: string; aboutToReuse(params: { itemData: string }) { this.itemData = params.itemData; // 必须显式更新参数 } build() { /* UI构建 */ }
} 高频错误排查
复用失效：未正确设置reuseId导致缓存池匹配失败
状态污染：未在aboutToReuse中清理前次状态
(4)认证核心考点
场景应用题
优化LazyForEach列表性能：通过@ReusableV2减少列表项创建销毁次数
条件渲染(if语句)下的复用策略
@ComponentV2
struct ItemView {@ReusableV2 // 启用实例复用build() {// 条件渲染逻辑（相同组件类型可复用）if (this.item.type === 'text') {Text(this.item.content).fontSize(16)} else {Text(this.item.content).fontSize(20)}}
}@Entry
@ComponentV2
struct MainPage {@Local listData: Array<{id: string, type: string, content: string}> = [...]build() {List() {LazyForEach(this.listData, (item: {id: string}) => {ListItem() {ItemView({ item: item }) // 复用ItemView实例}}, (item) => item.id) // 必须提供唯一key}}
}
@ComponentV2
struct ImageItem { ... } // 独立组件保证类型纯净@ComponentV2
struct TextItem { ... } // 独立组件保证类型纯净@ReusableV2
@ComponentV2
struct DynamicItem {build() {// 根据类型路由到不同组件（各自维护实例池）if (this.item.type === 'image') {ImageItem({ item: this.item })} else {TextItem({ item: this.item })}}
}
原理辨析题
V1与V2复用机制差异：V2需显式声明reuseId且依赖@ComponentV2
与@Local/@Param的状态协同规则
复用机制差异
基础依赖
V1复用：
原生支持组件复用，无需额外装饰器，但复用粒度较粗（基于组件类型）。
V2复用：
必须显式声明@ReusableV2并配合@ComponentV2使用，需通过reuseId精确控制实例池（如reuseId: () => 'customId'）。
生命周期控制
V2新增aboutToReuse（复用前回调）和aboutToRecycle（回收前回调），支持状态重置。
V1复用无生命周期钩子，依赖组件自身aboutToAppear/aboutToDisappear。
性能优化
| 维度 | V1 | V2（@ReusableV2） |
|---|---|---|
| 实例缓存 | 自动按类型缓存 | 需手动指定reuseId分组缓存 |
| 内存占用 | 较高（无法冻结未活跃实例） | 支持freezeWhenInactive冻结 |
| 列表渲染 | 全量刷新 | 项级差分更新 |
状态协同规则
@Local与@Param的协作
@Local：
仅限组件内部使用，禁止外部初始化（类似V1的@State但更严格）。
支持嵌套对象监听（需配合@Trace实现属性级更新）。
@Param：
父子组件单向同步，子组件禁止直接修改（除非搭配@Once）。
与@Local隔离：两者不可混用，@Param数据源必须来自父组件。
特殊场景处理
@Once联用：
@Param @Once组合使子组件仅初始化时同步父数据一次，后续可本地修改（类似@Local但保留初始值来源）。
典型应用：静态配置参数传递。
类型限制：
V2状态变量禁止与V1装饰器（如@State）混用，否则编译报错。
迁移建议
复用场景：高频列表渲染优先使用V2（@ReusableV2 + LazyForEach），简单组件复用可选V1。
状态协同：深层嵌套数据监听必须迁移至V2（@ObservedV2 + @Trace），简单父子通信可保留V1。
附：性能对比数据
| 指标 | 无复用方案 | @ReusableV2方案 |
|---|---|---|
| 内存占用(千列表项) | 120MB | 35MB (-70%) |
| 滑动帧率 | 38fps | 60fps (+58%) |
2. 状态观测装饰器
@ObservedV2
(1)基础定义与版本要求
功能定位
用于装饰类，赋予类深度观测能力，需与@Trace配合实现嵌套对象属性级监听
API支持：从API version 12开始支持，属于状态管理V2的核心能力之一
核心特性
解决V1版本中@Observed+@ObjectLink的嵌套监听缺陷，支持直接观测深层属性无需逐层声明
实现精准更新：仅刷新关联属性的组件，避免整体对象刷新
(2)关键规则与约束
强制配合使用
必须与@Trace联用，单独使用无效
仅在@ComponentV2装饰的组件中生效，与V1装饰器（如@State）不兼容
观测范围限制
嵌套类：嵌套类需被@ObservedV2装饰且属性需@Trace标记才能触发UI更新
继承类：父类/子类属性需同时满足@ObservedV2+@Trace才可观测
数据类型支持
支持number/string/class/Array/Map/Set等类型，但不支持JSON序列化
(3)认证高频考点
场景应用题
电商商品价格更新：通过@ObservedV2+@Trace监听嵌套类Product.price变化
性能优化对比：V2版本比V1减少50%冗余代码（深度监听场景）
@ObservedV2
class Product {@Trace name: string = '';@Trace price: number = 0;
}@ObservedV2
class ShopCart {@Trace items: Product[] = [new Product()];
}@Entry
@ComponentV2
struct Index {@Local cart: ShopCart = new ShopCart();build() {Column() {Button('涨价').onClick(() => {this.cart.items[0].price += 10; // 触发精准更新})ProductView({ cart: this.cart })}}
}@ComponentV2
struct ProductView {@Param cart: ShopCart;build() {Text(`当前价格：${this.cart.items[0].price}`)}
}
错误排查题
UI不更新：检查嵌套属性是否遗漏@Trace或类未加@ObservedV2
编译报错：在@Component中混用@ObservedV2
原理辨析题
与V1的@Observed区别：V2支持属性级更新，V1需@ObjectLink逐层绑定
与@Local/@Param的协同规则：@ObservedV2类实例可作为二者的数据类型
@ObservedV2与V1的@Observed核心区别
监听粒度
V1：
仅能观测类实例的第一层属性变化，嵌套属性需通过@ObjectLink逐层绑定自定义组件实现监听
示例：修改obj.a.b.c需为b和c分别创建@ObjectLink绑定链
V2：
通过@Trace实现属性级精准监听，嵌套属性（如obj.a.b.c）可直接触发UI更新
无需中间组件传递，代码量减少50%以上
性能优化
| 维度 | V1（@Observed+@ObjectLink） | V2（@ObservedV2+@Trace） |
|---|---|---|
| 更新范围 | 全对象刷新（即使仅修改深层属性） | 仅更新关联属性绑定的组件 |
| 内存占用 | 需缓存完整对象树 | 支持freezeWhenInactive冻结未活跃实例 |
| 代码复杂度 | 高（需手动维护绑定链） | 低（直接访问嵌套属性） |
典型场景对比
// V1实现嵌套监听（需链式绑定）
@Observed class A { b: B = new B(); }
@Observed class B { c: number = 0; }
@Component struct Child {@ObjectLink b: B; // 需中间组件传递build() { Text(`${this.b.c}`) }
}// V2实现同等功能
@ObservedV2 class A { @Trace b: B = new B(); // 直接监听嵌套类
}
@ObservedV2 class B { @Trace c: number = 0; // 属性级监听
}
@ComponentV2 struct Child {@Param a: A;build() { Text(`${this.a.b.c}`) } // 直接访问深层属性
}与@Local/@Param的协同规则
数据类型兼容性
@ObservedV2类实例可作为@Local或@Param的数据类型，但需遵守：
@Local：禁止从外部初始化，仅限组件内部使用
@Param：必须由父组件传入，子组件不可直接修改（除非配合@Once）
状态同步机制
@Local + @ObservedV2：
组件内修改@Trace属性自动触发UI更新
示例：
@ComponentV2 struct Demo {@Local product: Product = new Product(); // @ObservedV2类实例build() {Button(`价格：${this.product.price}`).onClick(() => { this.product.price += 10; }) // 直接修改生效}
}@Param + @ObservedV2：
父组件修改数据会同步到子组件，但子组件需通过@Event回调通知父组件修改
示例：
@Entry @ComponentV2 struct Parent {@Local cart: ShopCart = new ShopCart(); // @ObservedV2类build() {Child({ cart: this.cart, onPriceChange: (v) => { this.cart.price = v; } })}
}@ComponentV2 struct Child {@Param cart: ShopCart;@Event onPriceChange: (v: number) => void;build() {Button(`修改价格`).onClick(() => { this.onPriceChange(99); })}
}
静态属性支持
@ObservedV2类的静态属性若被@Trace装饰，同样支持状态管理：
@ObservedV2 class Config {@Trace static discount: number = 0.8; // 全局状态
}迁移建议
优先使用V2的场景：
深层嵌套对象监听（如电商商品SKU树）
高频数据更新（如实时价格刷新）
保留V1的场景：
简单父子组件通信（无需嵌套监听）
兼容旧版代码库时
附：V1/V2性能对比
| 场景 | V1方案 | V2方案 |
|---|---|---|
| 嵌套对象监听 | 需多层@ObjectLink | 单层@Trace直达 |
| 数组更新效率 | 全量刷新 | 项级差分更新 |
@Trace
(1)基础特性
作用机制
必须与@ObservedV2配合使用，单独使用无效
仅能修饰类属性（如number/string/class/Array等），不能用于struct
属性变化时触发精准UI更新（仅刷新关联组件）
深度观测能力
支持嵌套类属性监听（需逐层标记@ObservedV2和@Trace）
@ObservedV2 class A { @Trace b: B = new B(); // 嵌套类属性
}
@ObservedV2 class B { @Trace value: number = 0; // 深层属性
}(2)使用限制
作用域规则
仅能在@ComponentV2组件中使用
禁止与V1装饰器（如@State、@ObjectLink）混用
特殊场景
静态属性：支持@Trace static全局状态管理
继承类：父类/子类属性需分别标记@Trace
未标记属性：修改时不会触发UI刷新
(3)性能优化
对比V1方案
| 维度 | V1（@ObjectLink） | V2（@Trace） |
|---|---|---|
| 代码量 | 需手动维护绑定链（冗余50%+） | 直接访问嵌套属性 |
| 更新范围 | 全对象刷新 | 属性级差分更新 |
| 内存占用 | 缓存完整对象树 | 冻结未活跃实例（freezeWhenInactive） |
3. 数据流控制装饰器
@Local
(1)基础特性
作用定位
专用于@ComponentV2组件内部状态管理，对标V1的@State但语义更严格
被装饰的变量禁止从外部初始化，必须组件内初始化
变量变化时自动触发关联UI刷新
观测能力
支持基本类型（number/string/boolean）和复杂类型（Object/Array/Map等）
对复杂类型：
对象整体赋值可观测
数组元素变化可观测（通过API调用）
(2)与V1的@State核心区别
| 维度 | V1 @State | V2 @Local |
|---|---|---|
| 数据来源 | 允许外部初始化（父组件传入） | 仅限内部初始化 |
| 语义明确性 | 状态来源混杂难维护 | 强制内部状态隔离 |
| 兼容性 | 支持V1组件 | 仅限@ComponentV2组件 |
(3)使用规范与限制
强制规则
必须与@ComponentV2配合使用，在V1组件中无效
禁止与@Observed（V1）混用，需改用@ObservedV2
初始化要求
@ComponentV2
struct MyComponent {@Local count: number = 0; // 合法（内部初始化）// @Local msg: string; // 非法（未初始化）
}(4)高级应用场景
与@Param协作
@Local用于组件内部状态，@Param用于父组件传参
典型模式：父组件通过@Param传参，子组件用@Local维护衍生状态
性能优化
相比V1减少冗余状态监听，精准触发UI更新
支持freezeWhenInactive冻结非活跃实例内存
@Param
(1)基础特性
作用定位
专用于@ComponentV2组件接收父组件传入的状态数据，实现单向数据流
被装饰变量禁止组件内部直接修改，需通过@Event回调通知父组件修改
数据同步机制
父组件数据源变化时自动同步到子组件的@Param变量
对复杂类型（如类对象），子组件可修改其属性并同步回父组件
(2)与V1装饰器对比
| 维度 | V1 @Prop | V2 @Param |
|---|---|---|
| 数据方向 | 严格单向（父→子） | 单向但支持属性级修改 |
| 类型支持 | 基础类型+简单对象 | 全类型（含Map/Set等） |
| 初始化 | 必须父组件传入 | 支持本地初始化（非必须） |
(3)核心规则
强制约束
必须与@ComponentV2组件配合使用，V1组件中无效
变量类型需与父组件数据源严格一致
观测能力
基本类型：整体赋值可观测
对象类型：仅观测对象引用变化（属性修改需配合@ObservedV2）
数组/Map：API调用引发的变化可观测（如push/set）
(4)高级用法
联合@Once
@Param @Once变量仅初始化时同步一次，后续父组件变化不更新子组件
@ComponentV2 struct Child {@Param @Once initValue: string; // 仅首次同步
}联合@Require
强制要求父组件传参，否则编译报错
@ComponentV2 struct Child {@Require @Param requiredData: string;
}@Once
(1)基础特性
作用定位
专用于实现变量仅初始化时同步一次外部值，后续数据源变化不更新子组件
必须与@Param联合使用，不可单独使用或搭配其他装饰器
数据拦截机制
仅拦截数据源变化，不影响@Param的观测能力
允许子组件本地修改@Param变量的值（解除常规@Param不可修改限制）
(2)核心规则
| 维度 | 说明 |
|---|---|
| 装饰顺序 | @Once @Param或@Param @Once均可，顺序无影响 |
| 使用范围 | 仅限@ComponentV2组件，V1组件无效 |
| 类型支持 | 支持@Param所有类型（基础类型/对象/数组等） |
(3)典型应用场景
初始化后隔离父组件更新
@ComponentV2 struct Child {@Param @Once fixedConfig: string; // 仅首次同步父组件配置
}本地可修改的只读参数
@ComponentV2 struct Child {@Param @Once mutableValue: number; // 父组件初始化后可本地修改
}(4)与相似装饰器对比
| 装饰器 | 数据同步机制 | 可修改性 | 典型场景 |
|---|---|---|---|
@Param | 父→子持续同步 | 子组件不可修改 | 需响应父组件变化的参数 |
@Local | 完全内部状态 | 可自由修改 | 纯组件内部状态管理 |
@Once | 仅首次同步 | 初始化后可修改 | 需初始值但隔离更新的配置 |
二、高级特性与规则
1. 跨组件通信
@Provider与@Consumer
(1)基础特性
作用定位
实现跨组件层级的双向数据同步，无需逐层传递参数
@Provider为数据提供方，@Consumer为数据消费方，通过aliasName建立绑定关系
版本要求
仅支持@ComponentV2组件，V1组件使用会编译报错
从API version 12开始支持
(2)核心规则
| 维度 | @Provider | @Consumer |
|---|---|---|
| 初始化 | 必须本地初始化 | 可本地初始化（未找到@Provider时使用默认值） |
| 数据同步 | 数据变化自动同步到所有绑定的@Consumer | 自动同步最近的@Provider数据 |
| 类型约束 | 需与@Consumer类型严格一致 | 需与@Provider类型严格一致 |
(3)关键机制
绑定规则
通过相同变量名或相同aliasName建立绑定
若未指定aliasName，默认使用属性名匹配
作用域
@Consumer向上查找最近父节点的@Provider
支持一对多绑定（一个@Provider可对应多个@Consumer）
复杂类型支持
支持对象/数组等复杂类型，需配合@ObservedV2实现属性级观测
@Event
(1)基础特性
作用定位
专用于实现父子组件事件回调，简化组件间通信逻辑
需与@ComponentV2配合使用，V1组件无效
核心能力
支持定义带参数的回调函数，参数类型需显式声明
通过事件触发父组件状态更新，实现数据反向传递
(2)核心规则
| 维度 | 说明 |
|---|---|
| 装饰对象 | 仅能修饰回调函数（不能修饰变量） |
| 参数传递 | 支持多参数传递，需在声明时指定类型（如(count: number, text: string) => void） |
| 绑定方式 | 父组件通过属性传递回调函数，子组件通过@Event接收 |
| 命名规范 | 建议以on前缀命名（如onCountChange） |
(3)典型应用场景
子组件通知父组件
// 父组件
handleUpdate = (newVal: number) => { this.parentVal = newVal;
}
ChildComponent({ onUpdate: this.handleUpdate })// 子组件
@Event onUpdate: (val: number) => void;
Button('+1').onClick(() => this.onUpdate(100))双向数据流实现（配合@Param）
// 父组件
@Local count: number = 0;
ChildComponent({ count: this.count, onCountChange: (v) => { this.count = v }
})// 子组件
@Param count: number;
@Event onCountChange: (v: number) => void;(4)与相似装饰器对比
| 装饰器 | 数据流向 | 典型场景 |
|---|---|---|
@Param | 父→子单向 | 父组件传递只读数据 |
@Link | 父子双向 | 需双向绑定的状态 |
@Event | 子→父单向 | 子组件触发父组件逻辑 |
2. 性能优化装饰器
@Computed
(1)基础特性
作用定位
用于定义计算属性，优化重复计算的性能开销
依赖的状态变量变化时自动触发重新计算，但仅计算一次
版本要求
仅支持@ComponentV2组件，V1组件无效
(2)核心规则
| 维度 | 说明 |
|---|---|
| 装饰对象 | 只能修饰getter方法，不能修饰普通属性或方法 |
| 计算时机 | 首次访问时计算，依赖项变化后再次访问时重新计算 |
| 数据流 | 单向只读，不可用于双向绑定 |
| 依赖限制 | 计算函数内不能修改其他状态变量 |
(3)典型应用场景
复杂计算逻辑封装
@Computed get fullName() {return `${this.firstName} ${this.lastName}`; // 合并姓名
}性能敏感场景优化
@Computed get filteredList() {return this.rawList.filter(item => item.score > 60); // 避免重复过滤
}(4)与相似装饰器对比
| 装饰器 | 数据特性 | 典型场景 |
|---|---|---|
@Local | 可读写状态 | 组件内部状态管理 |
@Param | 父→子单向 | 父组件传递只读数据 |
@Computed | 只读计算值 | 依赖多项数据的派生状态 |
@Monitor
(1)基础特性
作用定位
增强状态变量变化的监听能力，支持深度监听嵌套对象/数组等复杂数据结构
对标V1的@Watch，但功能更强大，支持变化前后值对比
版本要求
仅支持@ComponentV2组件，API version 12起支持
(2)核心规则
| 维度 | 说明 |
|---|---|
| 监听对象 | 需被@Local、@Param、@Provider、@Consumer或@Computed修饰的变量 |
| 变化检测 | 使用严格相等（===）比较，若不等则触发回调 |
| 回调时机 | 避免在回调中修改其他状态变量，可能引发循环更新 |
| 深度监听 | 需配合@ObservedV2和@Trace实现嵌套类/对象数组的属性级监听 |
(3)典型应用场景
基础监听
@Local @Monitor('onCountChange') count: number = 0;
onCountChange(newVal: number, oldVal: number) {console.log(`值从${oldVal}变为${newVal}`);
}复杂类型监听
@ObservedV2 class NestedClass {@Trace value: string = '';
}
@Local @Monitor('onNestedChange') obj: NestedClass = new NestedClass();(4)与@Watch对比
| 特性 | @Watch (V1) | @Monitor (V2) |
|---|---|---|
| 监听范围 | 仅一级属性 | 支持深度嵌套属性 |
| 回调参数 | 无变化前后值 | 提供newVal/oldVal |
| 多属性监听 | 需单独声明 | 单装饰器可监听多属性 |
3. 关键约束规则
依赖关系：
@ObservedV2必须搭配@Trace使用，单独使用无效
@Once必须与@Param联用，否则无法生效
更新机制：
嵌套类中，需同时满足@ObservedV2装饰类和@Trace装饰属性才触发更新
修改Map/Set等内置类型需通过UIUtils.getTarget()获取原始对象
// 修改Map值示例
let rawMap = UIUtils.getTarget(this.stateMap);
rawMap.set('key', newValue); // 自动更新UI
三、认证高频考点
1. 装饰器选型场景
| 场景 | 推荐装饰器 |
|---|---|
| 组件内部状态 | @Local（禁止外部初始化） |
| 父子组件数据同步 | @Param（外部输入）+ @Event（输出） |
| 深层嵌套对象监听 | @ObservedV2 + @Trace |
2. 典型错误排查
UI不更新：
检查嵌套属性是否遗漏@Trace装饰
确认类是否被@ObservedV2装饰
初始化报错：
@Local变量尝试从外部传入值
@Once未与@Param配合使用
3. 性能优化考点
避免在@Computed中执行耗时操作
优先使用@Trace替代@ObjectLink减少冗余渲染
附：V2 性能优势对比
| 场景 | V1 方案 | V2 方案 | 优化点 |
|---|---|---|---|
| 嵌套对象监听 | 需多层@ObjectLink | @Trace单层精准更新 | 减少 50% 冗余代码 |
| 数组更新 | 整体刷新 | 项级差分更新 | 降低渲染耗时 |