当前位置：首页 > news >正文

鸿蒙中级课程笔记2—状态管理V2—@Provider装饰器和@Consumer装饰器：跨组件层级双向同步

news 2026/3/27 3:09:44

@Provider和@Consumer用于跨组件层级数据双向同步，可以使得开发者不用拘泥于组件层级。

@Provider和@Consumer属于状态管理V2装饰器，所以只能在@ComponentV2中才能使用，在@Component中使用会编译报错。

@Provider和@Consumer提供了跨组件层级数据双向同步的能力。在阅读本文档前，建议提前阅读：@ComponentV2。常见问题请参考组件内状态变量常见问题。

说明

@Provider和@Consumer装饰器从API version 12开始支持。

从API version 12开始，@Provider和@Consumer装饰器支持在元服务中使用。

从API version 22开始，通过配置BuilderNode的BuildOptions参数enableProvideConsumeCrossing为true，使得@Provider和@Consumer支持跨BuilderNode双向同步。在BuilderNode挂载到自定义组件节点树之后，@Consumer会重新获取最近的@Provider数据，与之建立双向同步关系。具体可见@Consumer在跨BuilderNode场景下和@Provider建立双向同步。

概述

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

装饰器说明

基本规则

@Provider语法：

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

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

@Consumer语法：

@Consumer(aliasName?: 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装饰的变量仅允许本地初始化，不允许从外部传入初始化。
初始化子组件	@Provider和@Consumer装饰的变量可以初始化子组件中@Param装饰的变量。

使用限制

@Provider和@Consumer为自定义组件的属性装饰器，只能装饰自定义组件内的属性，不能装饰class的属性。
@Provider和@Consumer为状态管理V2装饰器，只能在@ComponentV2中使用，不能在@Component中使用。
@Provider和@Consumer只支持本地初始化，不支持外部传入初始化。

使用场景

例子参考鸿蒙中级课程笔记2—状态管理V2—@Provider装饰器和@Consumer装饰器：跨组件层级双向同步

@Provider和@Consumer双向同步

建立双向绑定

自定义组件Parent和Child初始化：
- Child中@Consumer() str: string = 'world'向上查找，查找到Parent中声明的@Provider() str: string = 'hello'。
- @Consumer() str: string = 'world'初始化为其查找到的@Provider的值，即'hello'。
- 两者建立双向同步关系。
点击Parent中的按钮，改变@Provider装饰的str，通知其对应的@Consumer，对应UI刷新。同时Parent中UI也刷新。
点击Child中的按钮，改变@Consumer装饰的str，通知其对应的@Provider，对应UI刷新。同时Child中UI也刷新。

未建立双向绑定

下面的例子中，@Provider和@Consumer由于aliasName值不同，无法建立双向同步关系。

自定义组件Parent和Child初始化：
- Child中@Consumer() str: string = 'world'向上查找，未查找到其数据提供方@Provider。
- @Consumer() str: string = 'world'使用其本地默认值为'world'。
- 两者未建立双向同步关系。
点击Parent中的按钮，改变@Provider装饰的str1，仅刷新@Provider关联的Button组件。
点击Child中的按钮，改变@Consumer装饰的str，仅刷新@Consumer关联的Button组件。

装饰Array类型变量

当装饰的对象是Array时，可以观察到Array整体的赋值，同时可以通过调用Array的接口push, pop, shift, unshift, splice, copyWithin, fill, reverse, sort更新Array中的数据。

装饰Date类型变量

当装饰Date类型变量时，可以观察到数据源对Date整体的赋值，以及调用Date的接口setFullYear, setMonth, setDate, setHours, setMinutes, setSeconds, setMilliseconds, setTime, setUTCFullYear, setUTCMonth, setUTCDate, setUTCHours, setUTCMinutes, setUTCSeconds, setUTCMilliseconds带来的变化。