一、类与属性级

1. @ObservedV2

作用：标记一个类为“可观测类”。只有被 @ObservedV2 装饰的类，其内部用 @Trace 装饰的属性变化才会被框架追踪，从而驱动 UI 更新。

用在：ViewModel 类、需要跨页/持久化的数据类（如 Setting）。

示例：

@ObservedV2
export default class StudentViewModel {
  @Trace public name: string = '';
  @Trace public age: number = 0;
}

注意：@ObservedV2 只装饰类，不装饰变量或方法。

---

2. @Trace

作用：标记类中的属性为“可观测属性”。该属性一旦被修改，所有依赖它的 UI 会重新计算并刷新。

用在：@ObservedV2 类内部的成员变量（基本类型或数组等）。

示例：

@ObservedV2
export default class StudentViewModel {
  @Trace public name: string = '';   // 变化 → 界面更新
  @Trace public age: number = 0;
  @Trace public remark: string = '';
}

注意：数组里若装的是自定义类，需配合 @Type 使用（见下）。

---

3. @Type(类名)

作用：声明某个 @Trace 数组里元素的类型。框架据此做两件事：
① 深层观测数组里每个对象的 @Trace 属性；
② 持久化（PersistenceV2）时正确序列化/反序列化。

用在：@Trace public xxx: SomeViewModel[] 这类数组属性上。

示例：

@ObservedV2
export default class StudentListViewModel {
  @Type(StudentViewModel)
  @Trace public students: StudentViewModel[] = [];
}

注意：@Type 与 @Trace 一起用在“可观测类的数组”上，缺一可能导致深层不更新或持久化异常。

---

二、组件状态与传参

4. @Local

作用：表示组件内部状态。变量由当前组件持有，变化时只刷新本组件（及依赖该状态的子组件）。

用在：页面或自定义组件里“仅本组件关心”的数据，如输入框内容、是否展开等。

示例：

@ComponentV2
struct BottomView {
  @Local inputName: string = '';   // 仅本组件用，不传给父
  @Local inputAge: string = '';
  @Local inputGender: string = '男';
}

与 @Param 区别：@Local 是组件自己的状态；@Param 是父组件传进来的。

---

5. @Param

作用：表示父组件传入的只读参数。子组件用 @Param 声明的变量接收父组件传入的值，默认不能在子组件里修改（若允许“本地改一次”需配合 @Once）。

用在：子组件需要展示或依赖父组件给的数据时。

示例：

@ComponentV2
struct TitleView {
  @Param setting: Setting = new Setting();   // 父组件传入
  @Param totalCount: number = 0;              // 父组件传入
}

父组件用法：

TitleView({ setting: this.setting, totalCount: this.totalCount })

---

6. @Param @Once

作用（以官方文档为准）：

• “Once”指：父→子只同步一次。变量在初始化时接受父组件传入的值，之后父组件再改这个数据，不会同步给子组件（子保持当时拿到的值）。
• 子组件：可以在本地多次修改该变量，并触发 UI 刷新，效果类似 @Local，但还能接收父传入的初始值。

所以 @Param @Once 不是“子组件只能改一次”，而是“从父只接收一次，子可随意改”。

本工程演示（主页面顶部）：父有 @Local parentNum，按钮「父+1」让父数字递增；同一数据传给两个子组件：

• 子(Param)：仅 @Param value，父改则子跟着变（0→1→2→3…）。
• 子(Once)：@Param @Once value，只同步初始值，父改后子始终显示 0。

注意：

• 若需要父一改、子就跟变，用普通 @Param 即可，不要加 @Once。

---

7. @Event

作用：声明子组件向父组件“发事件”的回调。子组件在合适时机（如点击删除）调用该回调，由父组件决定具体逻辑（如从列表移除）。

用在：子组件需要通知父组件做某件事时（删除、选中、提交等）。

示例：

// 子组件
@ComponentV2
struct StudentItem {
  @Event onDelete: () => void = () => {};   // 父组件传入的回调
  // 点击删除时: this.onDelete();
}

// 父组件
StudentItem({
  student: obj.item,
  onDelete: () => this.studentList.removeStudent(obj.item)
})

---

三、计算与监听

8. @Computed

作用：标记一个 getter 为“计算属性”。框架会记录 getter 里用到的可观测状态（依赖），依赖不变时用缓存；依赖一变就重新计算，并刷新所有使用该 getter 的 UI。

用在：由其它状态“算出来”的值（如列表长度、未完成数量、合计等）。

示例：

@Computed
get totalCount(): number {
  return this.studentList.students.length;   // 依赖 students
}
// 增删学生后，totalCount 自动变，“共 X 人”自动更新

注意：getter 内不要写副作用（如改其它状态），只做纯计算。

---

9. @Monitor('路径')

作用：监听某个可观测属性的变化，在变化时执行你写的方法（如打日志、上报、同步到别处）。路径用字符串表示，如 'student.name'、'student.remark'。

用在：需要“属性一变就执行一段逻辑”时，而不是只刷新 UI。

示例：

@Monitor('student.name')
onNameChange(mon: IMonitor) {
  hilog.info(0x0000, 'StudentList', '姓名: %{public}s -> %{public}s',
    String(mon.value()?.before), String(mon.value()?.now));
}

@Monitor('student.remark')
onRemarkChange(mon: IMonitor) {
  hilog.info(0x0000, 'StudentList', '备注: %{public}s -> %{public}s',
    String(mon.value()?.before), String(mon.value()?.now));
}

注意：只有该路径对应的属性真的发生变化时才会触发；若界面没有修改该属性的操作，不会打印。

---

四、UI 复用与列表

10. @Builder

作用：把一段 UI 结构抽成可复用的“构建函数”，多处调用，减少重复代码。

用在：多个地方用到的相同或相似 UI（如统一风格的按钮、卡片、表单项）。

示例：

@Builder
function ActionButton(label: string, onClick: () => void) {
  Button(label)
    .width('100%')
    .onClick(onClick)
}

// 使用
ActionButton('设置', () => { ... })
ActionButton('添加', () => { ... })

---

11. Repeat

作用：根据数组按项渲染多个子组件，类似“列表循环”。数据源变化时，框架会做增量更新，只更新变化的那几项。

用在：列表、表格行、标签组等“数据驱动的一串子组件”。

示例：

Repeat<StudentViewModel>(this.studentList.students)
  .each((obj: RepeatItem<StudentViewModel>) => {
    StudentItem({
      student: obj.item,
      onDelete: () => this.studentList.removeStudent(obj.item)
    })
  })

注意：本工程中 Repeat.each() 只接受一个参数（构建函数），不支持 keyGenerator 等额外参数。

---

五、全局与持久化

12. AppStorageV2

作用：应用内全局状态。通过 AppStorageV2.connect(类, 键, 初始化函数) 拿到或创建“单例”，多个页面/Ability 共用同一份数据，改一处处处生效。

用在：跨页面、跨 Ability 的配置或状态（如主题、语言、班级名称、是否显示某类数据）。

示例：

// 定义可观测类
@ObservedV2
export class Setting {
  @Trace public className: string = '一年级1班';
}

// 在任意页面连接（无则创建）
@Local setting: Setting = AppStorageV2.connect(Setting, 'Setting', () => new Setting())!;

// 设置页改 className，主页面标题会同步更新

注意：数据只在进程存活期间存在，进程结束就清空；要关应用仍保留需用 PersistenceV2。

---

13. PersistenceV2

作用：把可观测类的实例持久化到本地，应用退出再打开后，通过 PersistenceV2.connect 取回上次的数据。

用在：需要“关应用再打开仍保留”的列表、表单草稿、用户设置等。

示例：

@Local studentList: StudentListViewModel =
  PersistenceV2.connect(StudentListViewModel, 'StudentList', () => new StudentListViewModel())!;

注意：

• 恢复出来的可能是“普通对象”而非 ViewModel 实例，直接绑定到 UI 可能不刷新。本工程在 aboutToAppear 里做了 rehydrate：若检测到是普通对象，则转成新的 ViewModel 实例再赋回列表。
• 持久化类需用 @ObservedV2，数组元素类型需用 @Type 声明。

---

六、本工程中的对应关系速查

装饰器/组件	本工程中的使用位置
@ObservedV2	StudentViewModel、StudentListViewModel、Setting
@Trace	name/age/gender/remark、students、className
@Type	StudentListViewModel.students
@Local	StudentListPage(studentList, setting, parentNum)、BottomView(输入框)、SettingPage(setting)
@Param	主页面 ParamDemoChild(value) 与 OnceDemoChild 对比、TitleView、ListView、StudentItem、BottomView
@Param @Once	主页面 OnceDemoChild(value) 与 ParamDemoChild 对比
@Event	StudentItem(onDelete)
@Computed	StudentListPage(totalCount)
@Monitor	StudentItem(onNameChange, onRemarkChange)
@Builder	BottomView(ActionButton)
Repeat	ListView(学生列表)
AppStorageV2	Setting（班级名称跨页）
PersistenceV2	StudentListViewModel（学生列表持久化）

---

七、文档中提到但本工程未使用的 V2 相关能力

对照 MVVM 模式（V2） 与状态管理 V2 文档，以下能力在文档中有提及，本工程当前未使用，便于后续扩展时参考：

能力	说明
Repeat 懒加载场景（LazyForEach）	文档中 Repeat 有两种用法：非懒加载（本工程已用 Repeat.each）与懒加载。懒加载适用于长列表、按需渲染，需配合 LazyForEach + 数据源接口使用，本工程列表较短，仅用非懒加载。
@Require	与 @Param 搭配表示必填参数，父组件未传时编译/运行会报错。本工程所有 @Param 均提供了默认值，未使用 @Require。
@Provider / @Consume	状态管理 V2 中的跨层级双向同步方案（祖先 ↔ 后代），与 AppStorageV2 不同。本工程跨页/跨 Ability 用 AppStorageV2，未使用 @Provider/@Consume。

小结：MVVM V2 文档里的核心装饰器（@Local、@Param、@Once、@Event、@ObservedV2、@Trace、@Type、@Monitor、@Computed、@Builder）与能力（Repeat、AppStorageV2、PersistenceV2）本工程均已使用；上述三项为“文档有提、工程未用”的扩展点。

---

八、参考

• MVVM 模式（V2）