鸿蒙开发之 Component 变革

ZHONG_YU
597 阅读18分钟

状态管理(V2)

随着时间的推进，鸿蒙发展也越来越快。Component 也迎来了ComponentV2 ，接下来聊聊 ComponentV2 的所属装饰器。

ComponentV2 的所属装饰器

更详细的请访问官网：

V2所属装饰器-状态管理（V2）-状态管理-学习ArkTS语言-基础入门 - 华为HarmonyOS开发者

@ComponentV2装饰器：自定义组件

概述

和@Component装饰器一样，@ComponentV2装饰器用于装饰自定义组件：

  • 在@ComponentV2装饰的自定义组件中，开发者仅可以使用全新的状态变量装饰器，包括@Local、@Param、@Once、@Event、@Provider、@Consumer等。
  • @ComponentV2装饰的自定义组件暂不支持组件复用、LocalStorage等现有自定义组件的能力。
  • 无法同时使用@ComponentV2与@Component装饰同一个struct结构。
  • @ComponentV2支持一个可选的boolean类型参数freezeWhenInactive，来实现组件冻结功能。
  • 一个简单的@ComponentV2装饰的自定义组件应具有以下部分：
@ComponentV2 // 装饰器
struct Index { // struct声明的数据结构
  build() { // build定义的UI
  }
}

@ObservedV2装饰器和@Trace装饰器：类属性变化观测

@ObservedV2装饰器与@Trace装饰器用于装饰类以及类中的属性，使得被装饰的类和属性具有深度观测的能力：

  • @ObservedV2装饰器与@Trace装饰器需要配合使用，单独使用@ObservedV2装饰器或@Trace装饰器没有任何作用。
  • 被@Trace装饰器装饰的属性property变化时，仅会通知property关联的组件进行刷新。
  • 在嵌套类中，嵌套类中的属性property被@Trace装饰且嵌套类被@ObservedV2装饰时，才具有触发UI刷新的能力。
  • 在继承类中，父类或子类中的属性property被@Trace装饰且该property所在类被@ObservedV2装饰时，才具有触发UI刷新的能力。
  • 未被@Trace装饰的属性用在UI中无法感知到变化，也无法触发UI刷新。
  • @ObservedV2的类实例目前不支持使用JSON.stringify进行序列化。
装饰器说明
@ObservedV2类装饰器说明
装饰器参数无
类装饰器装饰class。需要放在class的定义前，使用new创建类对象。
@Trace成员变量装饰器说明
装饰器参数无
可装饰的变量class中成员属性。属性的类型可以为number、string、boolean、class、Array、Date、Map、Set等类型。

@Local装饰器：组件内部状态

概述

@Local表示组件内部的状态，使得自定义组件内部的变量具有观测变化的能力：

  • 被@Local装饰的变量无法从外部初始化，因此必须在组件内部进行初始化。
  • 当被@Local装饰的变量变化时，会刷新使用该变量的组件。
  • @Local支持观测number、boolean、string、Object、class等基本类型以及Array、Set、Map、Date等内嵌类型。
  • @Local的观测能力仅限于被装饰的变量本身。当装饰简单类型时，能够观测到对变量的赋值；当装饰对象类型时，仅能观测到对对象整体的赋值；当装饰数组类型时，能观测到数组整体以及数组元素项的变化；当装饰Array、Set、Map、Date等内嵌类型时，可以观测到通过API调用带来的变化。详见观察变化。
  • @Local支持null、undefined以及联合类型。
装饰器说明
@Local变量装饰器说明
装饰器参数无。
可装饰的变量类型Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型。支持null、undefined以及联合类型。
装饰变量的初始值必须本地初始化，不允许外部传入初始化。
变量传递
传递规则说明
从父组件初始化@Local装饰的变量仅允许本地初始化，无法从外部传入初始化。
初始化子组件@Local装饰的变量可以初始化子组件中@Param装饰的变量。
观察变化

使用@Local装饰的变量具有被观测变化的能力。当装饰的变量发生变化时，会触发该变量绑定的UI组件刷新。相当于之前 Component 的@State装饰器

@Param：组件外部输入

概述

@Param表示组件从外部传入的状态，使得父子组件之间的数据能够进行同步：

  • @Param装饰的变量支持本地初始化，但是不允许在组件内部直接修改变量本身。
  • 被@Param装饰的变量能够在初始化自定义组件时从外部传入，当数据源也是状态变量时，数据源的修改会同步给@Param。
  • @Param可以接受任意类型的数据源，包括普通变量、状态变量、常量、函数返回值等。
  • @Param装饰的变量变化时，会刷新该变量关联的组件。
  • @Param支持观测number、boolean、string、Object、class等基本类型以及Array、Set、Map、Date等内嵌类型。
  • 对于复杂类型如类对象，@Param会接受数据源的引用。在组件内可以修改类对象中的属性，该修改会同步到数据源。
  • @Param的观测能力仅限于被装饰的变量本身。当装饰简单类型时，对变量的整体改变能够观测到；当装饰对象类型时，仅能观测对象整体的改变；当装饰数组类型时，能观测到数组整体以及数组元素项的改变；当装饰Array、Set、Map、Date等内嵌类型时，可以观测到通过API调用带来的变化。详见观察变化。
  • @Param支持null、undefined以及联合类型。
装饰器说明
@Param变量装饰器说明
装饰器参数无。
能否本地修改否，修改值需使用@Event装饰器的能力。
同步类型由父到子单向同步。
允许装饰的变量类型Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型。支持null、undefined以及联合类型。
被装饰变量的初始值允许本地初始化，若不在本地初始化，则需要和@Require装饰器一起使用，要求必须从外部传入初始化。
变量传递
传递规则说明
从父组件初始化@Param装饰的变量允许本地初始化，若无本地初始化则必须从外部传入初始化。当同时存在本地初始值与外部传入值时，会优先使用外部传入值进行初始化
初始化子组件@Param装饰的变量可以初始化子组件中@Param装饰的变量。
同步@Param可以和父组件传入的状态变量数据源（即@Local或@Param装饰的变量）进行同步，当数据源发生变化时，会将修改同步给子组件的@Param。
观察变化

使用@Param装饰的变量具有被观测变化的能力。当装饰的变量发生变化时，会触发该变量绑定的UI组件刷新。

@Once：初始化同步一次

概述

@Once装饰器仅在变量初始化时接受外部传入值进行初始化，当后续数据源更改时，不会将修改同步给子组件：

  • @Once必须搭配@Param使用，单独使用或搭配其他装饰器使用都是不允许的。
  • @Once不影响@Param的观测能力，仅针对数据源的变化做拦截。
  • @Once与@Param装饰变量的先后顺序不影响实际功能。
  • @Once与@Param搭配使用时，可以在本地修改@Param变量的值。
装饰器使用规则说明

@Once装饰器作为辅助装饰器，本身没有对装饰类型的要求以及对变量的观察能力。

@Once变量装饰器说明
装饰器参数无。
使用条件无法单独使用，必须配合@Param装饰器使用。
限制条件

  • @Once只能用在@ComponentV2装饰的自定义组件中且仅能与@Param搭配使用。

  • @Once与@Param的先后顺序无关，可以写成@Param @Once也可以写成@Once @Param。

使用场景
变量仅初始化同步一次

@Once使用在期望变量仅初始化时同步数据源一次，之后不再继续同步变化的场景。

本地修改@Param变量

当@Once搭配@Param使用时，可以解除@Param无法在本地修改的限制，且修改能够触发UI刷新。此时，使用@Param @Once相当于使用@Local，区别在于@Param @Once能够接受外部传入初始化。

@Event装饰器：规范组件输出

概述

由于@Param装饰的变量在本地无法更改，使用@Event装饰器装饰回调方法并调用，可以实现更改数据源的变量，再通过@Local的同步机制，将修改同步回@Param，以此达到主动更新@Param装饰变量的效果。

@Event用于装饰组件对外输出的方法：

  • @Event装饰的回调方法中参数以及返回值由开发者决定。
  • @Event装饰非回调类型的变量不会生效。当@Event没有初始化时，会自动生成一个空的函数作为默认回调。
  • 当@Event未被外部初始化，但本地有默认值时，会使用本地默认的函数进行处理。

@Param标志着组件的输入，表明该变量受父组件影响，而@Event标志着组件的输出，可以通过该方法影响父组件。使用@Event装饰回调方法是一种规范，表明该回调作为自定义组件的输出。父组件需要判断是否提供对应方法用于子组件更改@Param变量的数据源。

装饰器说明
@Event属性装饰器说明
装饰器参数无。
允许装饰的变量类型回调方法，例如()=>void、(x:number)=>boolean等。回调方法是否含有参数以及返回值由开发者决定。
允许传入的函数类型箭头函数。
限制条件
  • @Event只能用在@ComponentV2装饰的自定义组件中。当装饰非方法类型的变量时，不会有任何作用。
使用场景
更改父组件中变量

使用@Event可以更改父组件中变量，当该变量作为子组件@Param变量的数据源时，该变化会同步回子组件的@Param变量。

值得注意的是，使用@Event修改父组件的值是立刻生效的，但从父组件将变化同步回子组件的过程是异步的，即在调用完@Event的方法后，子组件内的值不会立刻变化。这是因为@Event将子组件值实际的变化能力交由父组件处理，在父组件实际决定如何处理后，将最终值在渲染之前同步回子组件。

@Monitor装饰器：状态变量修改监听

概述

@Monitor装饰器用于监听状态变量修改，使得状态变量具有深度监听的能力：

  • @Monitor装饰器支持在@ComponentV2装饰的自定义组件中使用，未被状态变量装饰器@Local、@Param、@Provider、@Consumer、@Computed装饰的变量无法被@Monitor监听到变化。
  • @Monitor装饰器支持在类中与@ObservedV2、@Trace配合使用，不允许在未被@ObservedV2装饰的类中使用@Monitor装饰器。未被@Trace装饰的属性无法被@Monitor监听到变化。
  • 当观测的属性变化时，@Monitor装饰器定义的回调方法将被调用。判断属性是否变化使用的是严格相等（===），当严格相等为false的情况下，就会触发@Monitor的回调。当在一次事件中多次改变同一个属性时，将会使用初始值和最终值进行比较以判断是否变化。
  • 单个@Monitor装饰器能够同时监听多个属性的变化，当这些属性在一次事件中共同变化时，只会触发一次@Monitor的回调方法。
  • @Monitor装饰器具有深度监听的能力，能够监听嵌套类、多维数组、对象数组中指定项的变化。对于嵌套类、对象数组中成员属性变化的监听要求该类被@ObservedV2装饰且该属性被@Trace装饰。
  • 在继承类场景中，可以在父子组件中对同一个属性分别定义@Monitor进行监听，当属性变化时，父子组件中定义的@Monitor回调均会被调用。
  • 和@Watch装饰器类似，开发者需要自己定义回调函数，区别在于@Watch装饰器将函数名作为参数，而@Monitor直接装饰回调函数。@Monitor与@Watch的对比可以查看@Monitor与@Watch的对比。
装饰器说明
@Monitor属性装饰器说明
装饰器参数字符串类型的对象属性名。可同时监听多个对象属性，每个属性以逗号隔开，例如@Monitor("prop1", "prop2")。可监听深层的属性变化，如多维数组中的某一个元素，嵌套对象或对象数组中的某一个属性。详见监听变化。
装饰对象@Monitor装饰成员方法。当监听的属性发生变化时，会触发该回调方法。该回调方法以IMonitor类型的变量作为参数，开发者可以从该参数中获取变化前后的相关信息。
接口说明
IMonitor类型

IMonitor类型的变量用作@Monitor装饰方法的参数。

属性类型参数返回值说明
dirtyArray无无保存发生变化的属性名。
valuefunctionpath?: stringIMonitorValue获得指定属性（path）的变化信息。当不填path时返回@Monitor监听顺序中第一个改变的属性的变化信息。
IMonitorValue类型

IMonitorValue类型保存了属性变化的信息，包括属性名、变化前值、当前值。

属性类型说明
beforeT监听属性变化之前的值。
nowT监听属性变化之后的当前值。
pathstring监听的属性名。
监听变化
在@ComponentV2装饰的自定义组件中使用@Monitor

使用@Monitor监听的状态变量发生变化时，会触发@Monitor的回调方法。

  • @Monitor监听的变量需要被@Local、@Param、@Provider、@Consumer、@Computed装饰，未被状态变量装饰器装饰的变量在变化时无法被监听。@Monitor可以同时监听多个状态变量，这些变量名之间用","隔开。
@Entry
@ComponentV2
struct Index {
  @Local message: string = "Hello World";
  @Local name: string = "Tom";
  @Local age: number = 24;
  @Monitor("message", "name")
  onStrChange(monitor: IMonitor) {
    monitor.dirty.forEach((path: string) => {
      console.log(`${path} changed from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`)
    })
  }
  build() {
    Column() {
      Button("change string")
        .onClick(() => {
          this.message += "!";
          this.name = "Jack";
      })
    }
  }
}
  • @Monitor监听的状态变量为类对象时，仅能监听对象整体的变化。监听类属性的变化需要类属性被@Trace装饰。
    class Info {
  name: string;
  age: number;
  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }
}
@Entry
@ComponentV2
struct Index {
  @Local info: Info = new Info("Tom", 25);
  @Monitor("info")
  infoChange(monitor: IMonitor) {
    console.log(`info change`);
  }
  @Monitor("info.name")
  infoPropertyChange(monitor: IMonitor) {
    console.log(`info name change`);
  }
  build() {
    Column() {
      Text(`name: ${this.info.name}, age: ${this.info.age}`)
      Button("change info")
        .onClick(() => {
          this.info = new Info("Lucy", 18); // 能够监听到
        })
      Button("change info.name")
        .onClick(() => {
          this.info.name = "Jack"; // 监听不到
        })
    }
  }
}

@Computed装饰器：计算属性

概述

@Computed为方法装饰器，装饰getter方法。@Computed会检测被计算的属性变化，当被计算的属性变化时，@Computed只会被求解一次。

对于复杂的计算，@Computed会有性能收益。

装饰器说明

@Computed语法：

@Computedget varName(): T {    return value;}
@Computed方法装饰器说明
支持类型getter访问器。
从父组件初始化禁止。
可初始化子组件@Param
被执行的时机@ComponentV2被初始化时，计算属性会被触发计算。当被计算的值改变的时候，计算属性也会发生计算。
是否允许赋值@Computed装饰的属性是只读的，不允许赋值，详情见使用限制。
使用限制

  • @Computed为方法装饰器，仅能装饰getter方法。

    @Computed
get fullName() { // 正确用法
return this.firstName + ' ' + this.lastName;
}
@Computed val: number = 0; // 错误用法，编译时报错
@Computed
func() { // 错误用法，编译时报错
}

  • 在@Computed装饰的getter方法中，不能改变参与计算的属性。

    @Computed
    get fullName() {
     this.lastName += 'a'; // 错误，不能改变参与计算的属性
     return this.firstName + ' ' + this.lastName;
    }
  • @Computed不能和双向绑定!!连用，@Computed装饰的是getter访问器，不会被子组件同步，也不能被赋值。开发者自己实现的计算属性的setter不生效，且产生运行时报错。
 @ComponentV2
 struct Child {
 @Param double: number = 100;
@Event $double: (val: number) => void;

build() {
 Button('ChildChange')
 .onClick(() => {
 this.$double(200);
})
 }
 }

 @Entry
 @ComponentV2
 struct Index {
 @Local count: number = 100;

 @Computed
 get double() {
 return this.count * 2;
 }
// @Computed装饰的属性是只读的，开发者自己实现的setter不生效，且产生运行时报错
 set double(newValue : number) {
 this.count = newValue / 2;
}
build() {
Scroll() {
Column({ space: 3 }) {
 Text(`${this.count}`)
// 错误写法，@Computed装饰的属性方法是只读的，无法和双向绑定连用
Child({ double: this.double!! })
}}}}
  • @Computed为状态管理V2提供的能力，只能在@ComponentV2和@ObservedV2中使用。
  • 多个@Computed一起使用时，警惕循环求解。
    @Local a : number = 1;
@Computed
get b() {
  return this.a + ' ' + this.c;  // 错误写法，存在循环b -> c -> b
}
@Computed
get c() {
  return this.a + ' ' + this.b; // 错误写法，存在循环c -> b -> c
}

@Provider装饰器和@Consumer装饰器：跨组件层级双向同步

概述

@Provider，即数据提供方，其所有的子组件都可以通过@Consumer绑定相同的key来获取@Provider提供的数据。

@Consumer，即数据消费方，可以通过绑定同样的key获取其最近父节点的@Provider的数据，当查找不到@Provider的数据时，使用本地默认值。

@Provider和@Consumer装饰数据类型需要一致。

开发者在使用@Provider和@Consumer时要注意：

  • @Provider和@Consumer强依赖自定义组件层级，@Consumer会因为所在组件的父组件不同，而被初始化为不同的值。
  • @Provider和@Consumer相当于把组件粘合在一起了，从组件独立角度，要减少使用@Provider和@Consumer。
@Provider和@Consumer vs @Provide和@Consume能力对比

在状态管理V1版本中，提供跨组件层级双向的装饰器为@Provide和@Consume，当前文档介绍的是状态管理V2装饰器@Provider和@Consumer。虽然两者名字和功能类似，但在特性上还存在一些差异。

如果开发者对状态管理V1中@Provide和@Consume完全不曾了解过，可以直接跳过本节。

能力V2装饰器@Provider和@ConsumerV1装饰器@Provide和@Consume
@Consume(r)允许本地初始化，当找不到@Provider的时候使用本地默认值。禁止本地初始化，当找不到对应的的@Provide时候，会抛出异常。
支持类型支持function。不支持function。
观察能力仅能观察自身赋值变化，如果要观察嵌套场景，配合@Trace一起使用。观察第一层变化，如果要观察嵌套场景，配合@Observed和@ObjectLink一起使用。
alias和属性名alias是唯一匹配的key，如果缺省alias，则默认属性名为alias。alias和属性名都为key，优先匹配alias，匹配不到可以匹配属性名。
@Provide(r) 从父组件初始化禁止。允许。
@Provide(r)支持重载默认开启，即@Provider可以重名，@Consumer向上查找最近的@Provider。默认关闭，即在组件树上不允许有同名@Provide。如果需要重载，则需要配置allowOverride。
装饰器说明
基本规则

@Provider语法：

@Provider(alias?: string) varName : varType = initValue

@Provider属性装饰器说明
装饰器参数aliasName?: string，别名，缺省时默认为属性名。
支持类型自定义组件中成员变量。属性的类型可以为number、string、boolean、class、Array、Date、Map、Set等类型。支持装饰箭头函数。
从父组件初始化禁止。
本地初始化必须本地初始化。
观察能力能力等同于@Trace。变化会同步给对应的@Consumer。

@Consumer语法：

@Consumer(alias?: string) varName : varType = initValue

@Consumer属性装饰器说明
装饰器参数aliasName?: string，别名，缺省时默认为属性名，向上查找最近的@Provider。
可装饰的变量自定义组件中成员变量。属性的类型可以为number、string、boolean、class、Array、Date、Map、Set等类型。支持装饰箭头函数。
从父组件初始化禁止。
本地初始化必须本地初始化。
观察能力能力等同于@Trace。变化会同步给对应的@Provider。
aliasName和属性名

@Provider和@Consumer可接受可选参数aliasName，如果开发者没有配置参数，则使用属性名作为默认的aliasName。注意：aliasName是用于@Provider和@Consumer进行匹配的唯一指定key。 以下三个例子可清楚介绍@Provider和@Consumer如何使用aliasName进行查找匹配。

@ComponentV2
struct Parent {
  // 未定义aliasName, 使用属性名'str'作为aliasName
  @Provider() str: string = 'hello';
}

@ComponentV2
struct Child {
  // 定义aliasName为'str'，使用aliasName去寻找
  // 能够在Parent组件上找到, 使用@Provider的值'hello'
  @Consumer('str') str: string = 'world';
}

@ComponentV2
struct Parent {
  // 定义aliasName为'alias'
  @Provider('alias') str: string = 'hello';
}

@ComponentV2 struct Child {
  // 定义aliasName为 'alias'，找到@Provider并获得值'hello'
  @Consumer('alias') str: string = 'world';
}

@ComponentV2
struct Parent {
  // 定义aliasName为'alias'
  @Provider('alias') str: string = 'hello';
}

@ComponentV2
struct Child {
  // 未定义aliasName，使用属性名'str'作为aliasName
  // 没有找到对应的@Provider，使用本地值'world'
  @Consumer() str: string = 'world';
}
变量传递
传递规则说明
从父组件初始化@Provider和@Consumer装饰的变量仅允许本地初始化，无法从外部传入初始化。
初始化子组件@Provider和@Consumer装饰的变量可以初始化子组件中@Param装饰的变量。
使用限制
  1. @Provider和@Consumer为自定义组件的属性装饰器，仅能装饰自定义组件内的属性，不能装饰class的属性。
  2. @Provider和@Consumer为状态管理V2装饰器，只能在@ComponentV2中使用，不能在@Component中使用。
  3. @Provider和@Consumer仅支持本地初始化，不支持外部传入初始化。
使用场景

@Provider和@Consumer双向同步

建立双向绑定

  1. 自定义组件Parent和Child初始化:

    • Child中@Consumer() str: string = 'world'向上查找，查找到Parent中声明的@Provider() str: string = 'hello'。
    • @Consumer() str: string = 'world'初始化为其查找到的@Provider的值，即‘hello’。
    • 两者建立双向同步关系。

  2. 点击Parent中的Button，改变@Provider装饰的str，通知其对应的@Consumer，对应UI刷新。

  3. 点击Child中Button，改变@Consumer装饰的str，通知其对应的@Provider，对应UI刷新。

@Entry
@ComponentV2
struct Parent {
  @Provider() str: string = 'hello';

  build() {
    Column() {
      Button(this.str)
        .onClick(() => {
          this.str += '0';
        })
      Child()
    }
  }
}

@ComponentV2
struct Child {
  @Consumer() str: string = 'world';

  build() {
    Column() {
      Button(this.str)
        .onClick(() => {
          this.str += '0';
        })
    }
  }
}

未建立双向绑定

一些情况下，@Provider和@Consumer由于aliasName值不同，无法建立双向同步关系。

  1. 自定义组件Parent和Child初始化:

    • Child中@Consumer() str: string = 'world'向上查找，未查找到其数据提供方@Provider。
    • @Consumer() str: string = 'world'使用其本地默认值为‘world’。
    • 两者未建立双向同步关系。

  2. 点击Parent中的Button，改变@Provider装饰的str1，仅刷新@Provider关联的Button组件。

  3. 点击Child中Button，改变@Consumer装饰的str，仅刷新@Consumer关联的Button组件。

@Entry
@ComponentV2
struct Parent {
  @Provider() str1: string = 'hello';

  build() {
    Column() {
      Button(this.str1)
        .onClick(() => {
          this.str1 += '0';
        })
      Child()
    }
  }
}

@ComponentV2
struct Child {
  @Consumer() str: string = 'world';

  build() {
    Column() {
      Button(this.str)
        .onClick(() => {
          this.str += '0';
        })
    }
  }
}
avatar
文章
阅读
粉丝