77916ee3创建于 12 天前历史提交

状态变量变化监听

状态变量监听模块提供了对状态变量变化的感知能力。

本文档仅为API参考说明。实际功能使用与限制见各接口对应的开发指南。

说明：

本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

Watch

Watch: (value: string) => PropertyDecorator

@Watch装饰器用于状态管理V1中对状态变量变化的监听。@Watch的详细使用方式见@Watch装饰器：状态变量更改通知。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string	是	用于监听的回调函数名，内容由开发者指定。

返回值：

类型	说明
PropertyDecorator	属性装饰器，开发者无需关注该返回值。

示例：

@Entry
@Component
struct Index {
  @State @Watch('onChange') num: number = 0; // @Watch入参为函数名

  onChange() {
    console.info(`num change to ${this.num}`);
  }

  build() {
    Column() {
      Text(`num is: ${this.num}`)
        .onClick(() => {
          this.num++; // 会触发onChange函数回调
        })
    }
  }
}

Monitor¹²⁺

Monitor: MonitorDecorator

@Monitor装饰器用于状态管理V2中对状态变量变化的监听。@Monitor相关内容的详细使用方式见@Monitor装饰器：状态变量修改异步监听。

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

MonitorDecoratorOptions

@Monitor装饰器的配置选项。

属性

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

卡片能力： 从API版本26.0.0开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
enableWildcard	boolean	否	是	是否支持通配符能力。true：使能通配符能力，false：关闭通配符能力。默认值为true，即默认使能通配符能力。

MonitorDecorator¹²⁺

type MonitorDecorator = (value: string | MonitorDecoratorOptions, ...args: string[]) => MethodDecorator

@Monitor装饰器的实际类型。

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string \| MonitorDecoratorOptions	是	在API版本26.0.0之前，该参数为监听的变量名路径，内容由开发者指定。当开发者仅传入一个字符串时，入参为string类型。从API版本26.0.0开始，该参数也可以为MonitorDecoratorOptions类型的对象，用于配置通配符能力。
...args	string[]	否	用于监听的变量名路径数组，内容由开发者指定。当开发者传入多个字符串时，入参为该类型。

返回值：

类型	说明
MethodDecorator	方法装饰器，开发者无需关注该返回值。

示例：

@ObservedV2
class Info {
  @Trace name: string = 'Tom';
  @Trace age: number = 25;
  @Trace height: number = 175;

  // 监听一个变量
  @Monitor('name')
  onNameChange() {
    console.info(`name change to ${this.name}`);
  }

  // 监听多个变量
  @Monitor('age','height')
  onRecordChange(monitor: IMonitor) {
    monitor.dirty.forEach((path: string) => {
      console.info(`${path} change from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`);
    })
  }
}

@Entry
@ComponentV2
struct Index {
  @Local info: Info = new Info();

  build() {
    Column() {
      Text(`info.name: ${this.info.name}`)
        .onClick(() => {
          this.info.name = 'Bob'; // 输出日志：name change to Bob
        })
      Text(`info.age: ${this.info.age}, info.height: ${this.info.height}`)
        .onClick(() => {
          this.info.age++; // 输出日志：age change from 25 to 26
          this.info.height++; // 输出日志：height change from 175 to 176
        })
    }
  }
}

IMonitor¹²⁺

当监听的变量变化时，状态管理框架侧将回调开发者注册的函数，并传入变化信息。变化信息的类型即为IMonitor类型。

属性

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
dirty¹²⁺	Array<string>	否	否	变化路径的数组。

value¹²⁺

value<T>(path?: string): IMonitorValue<T> | undefined

获取指定path的变化信息。

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
path	string	否	可选，被监听的变量路径名。未指定时默认使用变化路径数组dirty中的第一个路径。

返回值：

类型	说明
IMonitorValue<T> \| undefined	@Monitor监听变量的路径以及变化前后值信息。 T为监听变量的类型。当监听的路径不存在时，返回undefined。 API版本26.0.0之前，当未指定路径时，默认返回变化路径数组dirty中第一个路径对应的信息。从API版本26.0.0开始，当未指定路径时，默认返回变化路径数组dirty中第一个非通配符路径。当指定路径为通配符路径时，返回undefined。当未指定路径，且变化路径数组dirty中所有路径均为通配符路径时，返回undefined。

类型

说明

IMonitorValue<T> | undefined

@Monitor监听变量的路径以及变化前后值信息。
T为监听变量的类型。
当监听的路径不存在时，返回undefined。
API版本26.0.0之前，当未指定路径时，默认返回变化路径数组dirty中第一个路径对应的信息。
从API版本26.0.0开始，当未指定路径时，默认返回变化路径数组dirty中第一个非通配符路径。
当指定路径为通配符路径时，返回undefined。
当未指定路径，且变化路径数组dirty中所有路径均为通配符路径时，返回undefined。

示例：

@ObservedV2
class Info {
  @Trace name: string = 'Tom';
  @Trace age: number = 25;
  @Trace height: number = 175;

  // 监听一个变量
  @Monitor('name')
  onNameChange(monitor: IMonitor) {
    // 未指定value的入参时，默认使用dirty中的第一个路径作为入参
    console.info(`path: ${monitor.value()?.path} change from ${monitor.value()?.before} to ${monitor.value()?.now}`);
  }

  // 监听多个变量
  @Monitor('age','height')
  onRecordChange(monitor: IMonitor) {
    // 指定value的入参时，将返回入参路径path对应的变量变化值信息
    monitor.dirty.forEach((path: string) => {
      console.info(`path: ${path} change from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`);
    })
  }
}

@Entry
@ComponentV2
struct Index {
  @Local info: Info = new Info();

  build() {
    Column() {
      Text(`info.name: ${this.info.name}`)
        .onClick(() => {
          this.info.name = 'Bob'; // 输出日志：path: name change from Tom to Bob
        })
      Text(`info.age: ${this.info.age}, info.height: ${this.info.height}`)
        .onClick(() => {
          this.info.age++; // 输出日志：path: age change from 25 to 26
          this.info.height++; // 输出日志：path: height change from 175 to 176
        })
    }
  }
}

IMonitorValue<T>¹²⁺

@Monitor监听变量变化的具体信息，通过IMonitor的value接口获取。T为变量类型。

属性

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
before¹²⁺	T	否	否	变量变化前的值。
now¹²⁺	T	否	否	变量当前的值。
path¹²⁺	string	否	否	变量的路径。

示例：

@ObservedV2
class Info {
  @Trace name: string = 'Tom';
  @Monitor('name')
  onNameChange(monitor: IMonitor) {
    // value的返回值为IMonitorValue类型，可以通过该返回值获取变量变化的信息
    console.info(`path: ${monitor.value()?.path} change from ${monitor.value()?.before} to ${monitor.value()?.now}`);
  }
}
@Entry
@ComponentV2
struct Index {
  @Local info: Info = new Info();
  build() {
    Column() {
      Text(`info.name: ${this.info.name}`)
        .onClick(() => {
          this.info.name = 'Bob'; // 输出日志：path: name change from Tom to Bob
        })
    }
  }
}

SyncMonitor²³⁺

SyncMonitor: MonitorDecorator

@SyncMonitor装饰器用于状态管理V2中对状态变量变化的监听。@SyncMonitor相关内容的详细使用方式见@SyncMonitor装饰器：状态变量修改同步监听。

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

模型约束：此接口仅可在Stage模型下使用。

名称	类型	说明
SyncMonitor	MonitorDecorator	属性装饰器，监听状态变量的修改。

错误码：

以下错误码的详细介绍请参见状态管理错误码。

错误码ID	错误信息
130001	The path is invalid.

示例：

import { hilog } from '@kit.PerformanceAnalysisKit';

@ObservedV2
class Info {
  @Trace name: string = 'Tom';
  @Trace age: number = 25;
  @Trace height: number = 175;

  // 监听一个变量
  @SyncMonitor('name')
  onNameChange() {
    hilog.info(0xFF00, 'testTag', '%{public}s', `name change to ${this.name}`);
  }

  // 监听多个变量
  @SyncMonitor('age','height')
  onRecordChange(monitor: IMonitor) {
    monitor.dirty.forEach((path: string) => {
      hilog.info(0xFF00, 'testTag', '%{public}s',
        `${path} change from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`);
    })
  }
}

@Entry
@ComponentV2
struct Index {
  @Local info: Info = new Info();

  build() {
    Column() {
      Text(`info.name: ${this.info.name}`)
        .onClick(() => {
          this.info.name = 'Bob'; // 输出日志：name change to Bob
        })
      Text(`info.age: ${this.info.age}, info.height: ${this.info.height}`)
        .onClick(() => {
          this.info.age++; // 输出日志：age change from 25 to 26
          this.info.height++; // 输出日志：height change from 175 to 176
        })
    }
  }
}

状态变量变化监听

Watch

Monitor12+

MonitorDecoratorOptions

属性

MonitorDecorator12+

IMonitor12+

属性

value12+

IMonitorValue<T>12+

属性

SyncMonitor23+

Monitor¹²⁺

MonitorDecorator¹²⁺

IMonitor¹²⁺

value¹²⁺

IMonitorValue<T>¹²⁺

SyncMonitor²³⁺