状态管理 V1 主要装饰器
- @State：组件内部状态，可被外部初始化，修改后触发 UI 刷新。
- @Prop：父组件向子组件单向传递数据，子组件可修改但不会同步回父组件。
- @Link：实现父子组件双向绑定，一方修改另一方同步更新。
- @Provide / @Consume：跨多层组件共享状态（提供者与消费者）。
- @Observed / @ObjectLink：用于嵌套对象，配合实现深度属性监听（需逐层封装）。
- @Watch：监听状态变量变化，但仅能观测第一层属性，无法获取变更前值。
- @StorageProp / @StorageLink 等：用于与应用级存储（如 AppStorage）联动。
V1 基于“代理观察者”机制，仅能监听对象第一层变化，嵌套属性修改不会触发 UI 更新 **。
状态管理 V2 主要装饰器
- @ComponentV2：声明 V2 组件（替代 V1 的 @Component）。
- @Local：组件内部私有状态，禁止外部初始化或修改，仅限内部使用 **。
- @Param：父传子单向只读状态，子组件不可直接修改（编译报错），需配合 @Event 通知父组件 **。
- @Once：与 @Param 搭配使用，仅初始化时同步一次父值，之后解耦为本地变量 **。
- @Event：子组件向父组件发送事件的标准回调，实现可控双向通信 **。
- @ObservedV2 + @Trace：实现深度属性监听，任意层级嵌套对象属性变化均可触发 UI 更新 **。
- @Monitor：替代 @Watch，支持同时监听多个变量，可获取变更前后值，并支持深度观测（需配合 @Trace）**。
- @Computed：计算属性，依赖状态变化时才重新计算，避免重复运算 **。
- @Provider / @Consumer：跨层级状态共享，强制别名匹配，@Consumer 必须提供兜底默认值 **。
V2 采用“深度观察”机制，无需代理即可精准感知任意层级数据变更，性能更优、结构更清晰 **。
V1 与 V2 主要状态装饰器对照
| 功能/场景 | V1 装饰器/API | V2 装饰器/API | 简要说明 |
|---|---|---|---|
| 组件装饰器 | @Component | @ComponentV2 | V2 的组件装饰器需搭配 V2 状态变量使用，禁止与 V1 装饰器混用。 |
| 内部状态 | @State | @Local | 两者都用于声明组件内部的可变状态。V2 的 @Local 更明确表示局部状态。 |
| 组件参数 | @Prop, @Link | @Param, @Event | V1 的 @Prop 和 @Link 分别实现单向和双向同步。V2 解耦为 @Param（输入）和 @Event（输出），通过事件驱动实现通信。 |
| 对象观察 | @Observed, @Track | @ObservedV2, @Trace | V1 需搭配 @ObjectLink 观察第一层属性；V2 通过 @ObservedV2 标记可观察类，@Trace 修饰属性，支持任意深度嵌套属性的观察。 |
| 状态监听 | @Watch | @Monitor | V1 监听状态变量本身及第一层属性变化；V2 结合 @Trace 支持深层监听，且在一次事件中合并多次更新。 |
| 提供/消费 | @Provide, @Consume | @Provider, @Consumer | 功能兼容，用于跨组件层级共享状态。 |
| 计算属性 | 不支持 | @Computed | V2 新增，用于缓存计算结果，避免重复计算。 |
| 全局状态 | AppStorage, LocalStorage | AppStorageV2, @ObservedV2/@Trace | V1 的全局状态管理与持久化逻辑耦合；V2 的 AppStorageV2 功能解耦，持久化能力由独立的 PersistenceV2 提供。 |
| 环境变量 | Environment | 调用 Ability 接口 | V2 建议直接调用系统接口获取环境变量，不再与 AppStorage 耦合。 |
| 持久化存储 | PersistentStorage | PersistenceV2 | V2 的持久化能力可独立使用。 |
二、V1 与 V2 的核心区别
关键区别总结
| 特性 | V1 | V2 |
|---|---|---|
| 观测深度 | 仅第一层 | 支持任意嵌套层级（@ObservedV2 + @Trace） |
| 父子通信 | @Prop（可改）、@Link（双向） | @Param（只读） + @Event（回调） |
| 内部状态 | @State（可外部传入） | @Local（仅内部初始化） |
| 性能优化 | 无计算属性，重复渲染风险高 | 支持 @Computed 缓存结果 |
| 混合使用 | 可与 V2 组件共存于同一项目 | 但同一组件内不能混用 V1/V2 装饰器 ** |
V1 与 V2 的核心区别
-
设计理念与观察能力
- V1 以组件层级为核心。其装饰器（如
@State、@Link）主要管理组件级别的状态，但仅支持对象第一层属性的浅层观察 2。若要观察嵌套对象（如person.address.city），必须手动为每个嵌套类添加@Observed，并通过@ObjectLink逐层绑定，代码冗余且易出错。 - V2 以数据对象为核心。通过
@ObservedV2和@Trace装饰器，能够直接对嵌套属性进行深度观察 3。修改深层属性（如person.address.city）可直接触发 UI 更新，无需额外的链路声明，极大简化了复杂数据结构的响应式管理。
- V1 以组件层级为核心。其装饰器（如
-
组件通信机制
- V1 依赖双向绑定（如
@Link），父子组件之间的数据同步由框架隐式处理，导致组件耦合度高，逻辑交织，调试和维护相对困难。 - V2 倡导单向数据流 + 事件驱动 2。父组件通过
@Param传递数据给子组件，子组件通过@Event触发事件回调来通知父组件更新。这种显式通信使数据流更清晰，提升了代码的可维护性和可测试性。
- V1 依赖双向绑定（如
-
性能与渲染优化
- V1 在状态更新时，常因对象整体赋值（如
this.obj = newObj）而触发所有依赖组件的重新渲染，可能导致冗余刷新 3。 - V2 支持属性级更新。当只有某个深层属性（如
city）发生变化时，框架能够精准定位并仅重绘依赖该属性的 UI 组件（如特定的Text组件），有效减少了渲染开销，提升了应用性能。
- V1 在状态更新时，常因对象整体赋值（如
-
功能增强与工程化改进
- V2 引入了新能力：
@Computed用于定义计算属性，避免重复计算；@Monitor在监听状态变化时不仅能感知变化后的数据，还能获取变化前的数据，更利于实现风控、日志等场景。 - 状态管理解耦：V1 的
AppStorage将全局状态、环境变量、持久化存储能力耦合在一起。V2 将其拆分为独立的AppStorageV2（全局状态）、系统 Ability 接口（环境变量）和PersistenceV2（持久化），架构更清晰，职责更单一。 - 内存管理优化：V2 引入了自动清理机制，减少了组件销毁后状态残留的风险；而 V1 需要开发者更多关注手动管理。
- V2 引入了新能力：
使用建议
- 新项目：优先使用 V2，官方推荐，更适合复杂应用 **。
- 旧项目：若 V1 已满足需求，可暂不迁移；若需优化性能或支持深度数据绑定，建议渐进式迁移到 V2 **。
- 注意兼容性：V1 和 V2 组件可互相引用，但装饰器不能混用在同一组件中
