android2harmony 0.1.4 → 0.1.5

package/skills/{hmos-batch-ui-align → a2h-ui-transfer}/references/mvvm-v2/_/350/214/203/345/274/217/351/200/211/346/213/251/350/257/264/346/230/216.md

@@ -4,7 +4,7 @@
 
 ## 探测规则（项目级判定）
 
-扫描 `harmony_project_dir/entry/src/main/ets` 下已有 `.ets` 文件的装饰器：
+扫描 `harmony_project_dir/{ui_module}/src/main/ets` 下已有 `.ets` 文件的装饰器：
 
 | 判定结果 | 依据 |
 |---|---|

package/skills/a2h-ui-transfer/references/mvvm-v2/_/350/243/205/351/245/260/345/231/250/351/200/237/346/237/245.md

@@ -0,0 +1,133 @@
+# V2 状态管理装饰器速查（选型 + 最小语法）
+
+> **用途**：Phase 2.1 判定为 V2 时**只读本文件**即可开始转换。本文件覆盖全部 V2 装饰器的
+> **选型判据 + 最小可用语法**。仅当遇到本文件未覆盖的边界情形（见每节「深读」指引）时，
+> 才去读同目录下对应的完整文档。
+>
+> **铁律**：V1 与 V2 不在同一工程混用。本文件内的装饰器可自由组合，
+> 但不得与 `@Component`/`@State`/`@Prop`/`@Link`/`@Provide`/`@Consume`/`@Observed`/`@ObjectLink`/`@Watch`/`@Track` 同时出现。
+
+## 一、选型决策表（按需求查，命中即用）
+
+| 需求 | 用什么 | 深读 |
+|---|---|---|
+| 声明一个 UI 组件 | `@ComponentV2` + `struct`（V2 组件**必须**用它，不能用 `@Component`） | `MVVM模式（V2）.md` |
+| 组件**自己**持有的可变状态 | `@Local` | `@Local装饰器：组件内部状态.md` |
+| 从父组件**传入**的值（单向） | `@Param`（**只读**，不可在子组件内赋值） | `@Param装饰器：组件外部输入.md` |
+| 传入值只在**首次**同步，之后子组件可自行改 | `@Param` + `@Once` 同时标注 | `@Once装饰器：初始化同步一次.md` |
+| 子组件要**通知父组件**（回调） | `@Event`（声明为函数类型属性） | `@Event装饰器：规范组件输出.md` |
+| 父子**双向绑定**一个值 | 父 `@Local` + 子 `@Param`/`@Event`，父传参写 `value: this.x!!` | `!!语法：双向绑定.md` |
+| **跨多层**祖先↔后代双向同步（中间层不参与） | 祖先 `@Provider()` + 后代 `@Consumer()` | `@Provider装饰器和@Consumer装饰器：跨组件层级双向同步.md` |
+| **自定义类**的属性变化要驱动 UI 刷新 | 类上 `@ObservedV2` + 需观测属性上 `@Trace` | `@ObservedV2装饰器和@Trace装饰器：类属性变化观测.md` |
+| 某状态变化时执行**副作用**（拉数据、打日志） | `@Monitor('路径')` 方法 | `@Monitor装饰器：状态变量修改异步监听.md` |
+| 由其他状态**推导**出的只读值（避免手工同步） | `@Computed` getter | `@Computed装饰器：计算属性.md` |
+| 类属性是 `Date`/`Map`/`Set`/`Array` 等需明确类型 | `@Type` | `@Type装饰器：标记类属性的类型.md` |
+| 跨页面共享、**不需要**落盘的全局状态 | `AppStorageV2.connect()` | `AppStorageV2：应用全局UI状态存储.md` |
+| 跨页面共享、**需要**落盘持久化（设置项等） | `PersistenceV2.connect()` | `PersistenceV2：持久化存储UI状态.md` |
+| 要在**既有 V1 工程**里局部扩展 | 见迁移文档，勿混用 | `状态管理V1向V2迁移与混用指导.md` |
+
+## 二、最小语法
+
+```ts
+// 1) 组件 + 内部状态 + 外部输入 + 事件输出
+@ComponentV2
+struct ChildView {
+  @Param readonlyTitle: string = '';           // 父传入，子内部只读
+  @Param @Once initialCount: number = 0;       // 仅首次同步，之后可自行改
+  @Local count: number = 0;                    // 组件内部状态
+  @Event onCountChange: (v: number) => void = () => {};   // 子 → 父
+
+  build() {
+    Text(`${this.readonlyTitle}: ${this.count}`)
+      .onClick(() => { this.count++; this.onCountChange(this.count); })
+  }
+}
+```
+
+```ts
+// 2) 父组件：双向绑定用 !!
+@ComponentV2
+struct ParentView {
+  @Local count: number = 0;
+  build() {
+    // !! 等价于同时传 count 和 $count（自动生成 onCountChange 回写）
+    ChildView({ initialCount: this.count!! })
+  }
+}
+```
+
+```ts
+// 3) 可观测数据类：@ObservedV2 + @Trace（未加 @Trace 的属性改动不刷新 UI）
+@ObservedV2
+class ItemModel {
+  @Trace title: string = '';           // 改动会刷新 UI
+  @Trace count: number = 0;
+  @Trace tags: string[] = [];          // 数组整体替换/元素增删均可观测
+  @Type(Date) @Trace updatedAt: Date = new Date();
+  cacheKey: string = '';               // 无 @Trace：改动不刷新 UI（有意为之）
+}
+```
+
+```ts
+// 4) ViewModel：@Computed 推导 + @Monitor 副作用
+@ObservedV2
+class PageViewModel {
+  @Trace model: ItemModel = new ItemModel();
+  @Trace loading: boolean = false;
+
+  @Computed
+  get displayLabel(): string { return `${this.model.title} (${this.model.count})`; }
+
+  @Monitor('model.count')
+  onCountChanged(mon: IMonitor): void {
+    mon.dirty.forEach((path: string) => { console.info(`changed: ${path}`); });
+  }
+}
+```
+
+```ts
+// 5) 跨层级双向同步（中间组件无需转发）
+@ComponentV2
+struct AncestorView {
+  @Provider() theme: string = 'dark';
+  build() { MiddleView() }
+}
+
+@ComponentV2
+struct DeepChildView {
+  @Consumer() theme: string = 'light';   // 自动向上找同名 @Provider
+  build() { Text(this.theme).onClick(() => { this.theme = 'light'; }) }  // 可回写
+}
+```
+
+```ts
+// 6) 全局 / 持久化状态
+@ObservedV2
+class SettingsStore {
+  static readonly KEY: string = 'SettingsStore';
+  @Trace useCelsius: boolean = true;
+}
+// 落盘（设置项、用户偏好）：
+const store: SettingsStore = PersistenceV2.connect(SettingsStore, SettingsStore.KEY, () => new SettingsStore())!;
+// 仅内存、跨页面共享：
+const session: SettingsStore = AppStorageV2.connect(SettingsStore, 'session', () => new SettingsStore())!;
+```
+
+## 三、高频错误（本表即验收清单）
+
+| 错误 | 后果 | 正确做法 |
+|---|---|---|
+| 在子组件内给 `@Param` 赋值 | 编译报错 | 需可改 → 加 `@Once`；需回写父 → `@Event` 或 `!!` |
+| 类属性只加 `@ObservedV2`、漏 `@Trace` | 数据变了 **UI 不刷新**（无报错，最难查） | 所有参与渲染的属性都要 `@Trace` |
+| 用 `@Local` 接收父组件传入值 | 父更新后子不同步 | 改用 `@Param` |
+| `@Computed` getter 里写副作用/赋值 | 行为未定义 | getter 保持纯函数；副作用放 `@Monitor` |
+| `@Monitor` 写在 `struct` 里监听非状态变量 | 不触发 | 只监听 `@Local`/`@Param`/`@Trace` 路径 |
+| `PersistenceV2.connect` 的类未加 `@ObservedV2` | 不持久化/不刷新 | 存储类必须 `@ObservedV2` + `@Trace` |
+| `@ComponentV2` 里出现 `@State`/`@Link` 等 V1 装饰器 | 编译报错或行为异常 | 全程单一范式，见开头铁律 |
+| **（V1）`@Observed` 类里用了 `@Track`，却让 UI 读到未被 `@Track` 的成员** | **首帧运行时崩溃**：`BusinessError 140110: Illegal usage of not @Track'ed property 'x' on UI!` | `@Track` 是 **all-or-nothing**：类里一旦出现任何 `@Track`，UI 读到的每一个成员都必须是 `@Track` 字段（依据 `../mvvm/@Track装饰器：class对象属性级更新.md:15`、`:198`） |
+| **（V1）用 `get x()` 给 UI 暴露派生值** | 同上，首帧崩溃。**编译通过、零告警、字段侧完备性检查全过** —— getter 不是数据属性，无法被 `@Track` 装饰 | **V1 没有 `@Computed`**（那是 V2 能力）。派生值改成**普通方法**（`title(): string`，UI 侧 `vm.title()`；原型方法不经过 `@Track` 代理），或提升为真正的 `@Track` 字段。注意「getter 会重新求值」只说明**响应性**没问题，**不说明合法性** |
+
+> **V1 专有陷阱，务必读完上面两行。** V2 的派生值有 `@Computed` 这条正路，V1 没有，
+> 于是「用裸 getter 暴露派生值」成了 V1 侧极自然却必崩的写法。上面两行是该缺陷的完整判据；
+> 需要完整约束与官方示例时读 `../mvvm/@Track装饰器：class对象属性级更新.md`。
+> 机械兜底：`scripts/arkts_static_check.js` 的 GATE 规则 `track-class-getter-in-ui`。