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

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

@Provider和@Consumer属于状态管理V2装饰器，所以只能在[@ComponentV2](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-custom-components#componentv2)中才能使用，在[@Component](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-custom-components)中使用会编译报错。

@Provider和@Consumer提供了跨组件层级数据双向同步的能力。在阅读本文档前，建议提前阅读：[@ComponentV2](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-custom-components#componentv2)。常见问题请参考[组件内状态变量常见问题](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-state-management-faq-inner-component)。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c8/v3/8pUWL-UbTNuh6Lo5zexR5g/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073257Z&HW-CC-Expire=86400&HW-CC-Sign=102E6758A740E4E7CEBD267CEFA1BE349FC6ED6D81EF937E6FA0CBC448C480C9)

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

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

从API version 23开始，通过配置[BuilderNode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-buildernode)的[BuildOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-buildernode#buildoptions12)参数enableProvideConsumeCrossing为true，使得@Provider和@Consumer支持跨[BuilderNode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-buildernode)双向同步。在BuilderNode挂载到自定义组件节点树之后，@Consumer会重新获取最近的@Provider数据，与之建立双向同步关系。具体可见[@Consumer在跨BuilderNode场景下和@Provider建立双向同步](#consumer在跨buildernode场景下和provider建立双向同步过程)。

从API version 23开始，@Provider和@Consumer装饰器支持在ArkTS卡片中使用。

#### 概述

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

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

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2d/v3/1R5NBcphSP2mpkVx2vZC9Q/zh-cn_image_0000002594667756.png?HW-CC-KV=V1&HW-CC-Date=20260612T073257Z&HW-CC-Expire=86400&HW-CC-Sign=BD750369871AA63A1A1EA5C783B33FA5E74F46EB6BADD65469CE9521AE79FF82)

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

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

*   @Provider和@Consumer强依赖自定义组件层级，@Consumer会因为所在组件的父组件不同，而被初始化为不同的值。
*   @Provider和@Consumer相当于把组件粘合在一起了，从组件独立角度考虑，应减少使用@Provider和@Consumer。

#### @Provider和@Consumer vs @Provide和@Consume能力对比

在状态管理V1版本中，提供跨组件层级双向的装饰器为[@Provide和@Consume](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-provide-and-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](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-observedv2-and-trace)一起使用。 | 观察第一层变化，如果要观察嵌套场景，配合[@Observed和@ObjectLink](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-observed-and-objectlink)一起使用。 |
| alias和属性名 | alias是唯一匹配的key，缺省时默认属性名为alias。 | alias和属性名都为key，优先匹配alias，匹配不到可以匹配属性名。 |
| @Provide(r) 从父组件初始化 | 不允许。 | 允许。 |
| @Provide(r)支持重载 | 默认开启，即@Provider可以重名，@Consumer向上查找最近的@Provider。 | 默认关闭，即在组件树上不允许有同名@Provide。如果需要重载，则需要配置allowOverride。 |

#### 装饰器说明

#### \[h2\]基本规则

@Provider语法：

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

| @Provider属性装饰器 | 说明 |
| :-- | :-- |
| 装饰器参数 | aliasName?: string，别名，缺省时默认为属性名。 |
| 支持类型 | 自定义组件中成员变量。属性的类型可以为number、string、boolean、class、[Array](#装饰array类型变量)、[Date](#装饰date类型变量)、[Map](#装饰map类型变量)、[Set](#装饰set类型变量)等类型。支持装饰[箭头函数](#provider和consumer装饰回调事件用于组件之间完成行为抽象)。 |
| 从父组件初始化 | 禁止。 |
| 本地初始化 | 必须本地初始化。 |
| 观察能力 | 能力等同于@Trace。变化会同步给对应的@Consumer。 |

@Consumer语法：

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

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

#### \[h2\]aliasName和属性名

@Provider和@Consumer接受可选参数aliasName，没有配置参数时，使用属性名作为默认的aliasName。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/13/v3/eBQGzWgNTASemsJ1keHC6Q/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073257Z&HW-CC-Expire=86400&HW-CC-Sign=E84FBA8F61F0C06B9C1DDBACE57FEDEDA4F13E68B7505037B6A40A48B07EDA60)

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](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-param)装饰的变量。 |

#### 使用限制

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

#### 使用场景

#### \[h2\]@Provider和@Consumer双向同步

**建立双向绑定**

1.  自定义组件Parent和Child初始化：
    *   Child中@Consumer() str: string = 'world'向上查找，查找到Parent中声明的@Provider() str: string = 'hello'。
    *   @Consumer() str: string = 'world'初始化为其查找到的@Provider的值，即'hello'。
    *   两者建立双向同步关系。
2.  点击Parent中的按钮，改变@Provider装饰的str，通知其对应的@Consumer，对应UI刷新。
3.  点击Child中的按钮，改变@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和Parent组件中@Provider装饰的属性str名称相同，因此建立了双向绑定关系
  @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中的按钮，改变@Provider装饰的str1，仅刷新@Provider关联的Button组件。
3.  点击Child中的按钮，改变@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和Parent组件中@Provider装饰的属性str1名称不同，无法建立双向绑定关系
  @Consumer() str: string = 'world';

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

#### \[h2\]装饰Array类型变量

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

@Entry
@ComponentV2
struct Parent {
  @Provider() count: number\[\] = \[1, 2, 3\];

  build() {
    Row() {
      Column() {
        ForEach(this.count, (item: number) => {
          Text(\`parent: ${item}\`).fontSize(30)
          Divider()
        })
        // count被@Provider装饰，可以被观察到Array整体的赋值以及调用Array接口带来的变化
        Button('push').onClick(() => {
          this.count.push(111);
        })
        Button('reverse').onClick(() => {
          this.count.reverse();
        })
        Button('fill').onClick(() => {
          this.count.fill(6);
        })
        Child()
      }
      .width('100%')
    }
    .height('100%')
  }
}

@ComponentV2
struct Child {
  @Consumer() count: number\[\] = \[9, 8, 7\];

  build() {
    Column() {
      ForEach(this.count, (item: number) => {
        Text(\`child: ${item}\`).fontSize(30)
        Divider()
      })
      // count被@Consumer装饰，可以被观察到Array整体的赋值以及调用Array接口带来的变化
      Button('push').onClick(() => {
        this.count.push(222);
      })
      Button('reverse').onClick(() => {
        this.count.reverse();
      })
      Button('fill').onClick(() => {
        this.count.fill(8);
      })
    }
    .width('100%')
  }
}

#### \[h2\]装饰Date类型变量

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

@Entry
@ComponentV2
struct Parent {
  @Provider() selectedDate: Date = new Date('2021-08-08');

  build() {
    Column() {
      Text(\`parent: ${this.selectedDate}\`)
      // selectedDate被@Provider装饰，可以被观察到Date整体的赋值以及调用Date接口带来的变化
      Button('update the new date')
        .onClick(() => {
          this.selectedDate = new Date('2023-07-07');
        })
      Button('increase the year by 1')
        .onClick(() => {
          this.selectedDate.setFullYear(this.selectedDate.getFullYear() + 1);
        })
      Button('increase the month by 1')
        .onClick(() => {
          this.selectedDate.setMonth(this.selectedDate.getMonth() + 1);
        })
      Button('increase the day by 1')
        .onClick(() => {
          this.selectedDate.setDate(this.selectedDate.getDate() + 1);
        })
      Child()
    }
  }
}

@ComponentV2
struct Child {
  @Consumer() selectedDate: Date = new Date('2022-07-07');

  build() {
    Column() {
      Text(\`child: ${this.selectedDate}\`)
      // selectedDate被@Consumer装饰，可以被观察到Date整体的赋值以及调用Date接口带来的变化
      Button('update the new date')
        .onClick(() => {
          this.selectedDate = new Date('2025-01-01');
        })
      Button('increase the year by 1')
        .onClick(() => {
          this.selectedDate.setFullYear(this.selectedDate.getFullYear() + 1);
        })
      Button('increase the month by 1')
        .onClick(() => {
          this.selectedDate.setMonth(this.selectedDate.getMonth() + 1);
        })
      Button('increase the day by 1')
        .onClick(() => {
          this.selectedDate.setDate(this.selectedDate.getDate() + 1);
        })
    }
  }
}

#### \[h2\]装饰Map类型变量

当装饰Map类型变量时，可以观察到数据源对Map整体的赋值，以及调用Map的接口set, clear, delete带来的变化。

@Entry
@ComponentV2
struct Parent {
  @Provider() message: Map<number, string> = new Map(\[\[0, 'a'\], \[1, 'b'\], \[3, 'c'\]\]);

  build() {
    Column() {
      Text('Parent').fontSize(30)
      ForEach(Array.from(this.message.entries()), (item: \[number, string\]) => {
        Text(\`${item\[0\]}\`).fontSize(30)
        Text(\`${item\[1\]}\`).fontSize(30)
        Divider()
      })
      // message被@Provider装饰，可以被观察到Map整体的赋值以及调用Map接口带来的变化
      Button('init map').onClick(() => {
        this.message = new Map(\[\[0, 'aa'\], \[1, 'bb'\], \[3, 'cc'\]\]);
      })
      Button('set new one').onClick(() => {
        this.message.set(4, 'd');
      })
      Button('clear').onClick(() => {
        this.message.clear();
      })
      Button('replace the first one').onClick(() => {
        this.message.set(0, 'a~');
      })
      Button('delete the first one').onClick(() => {
        this.message.delete(0);
      })
      Child()
    }
  }
}

@ComponentV2
struct Child {
  @Consumer() message: Map<number, string> = new Map(\[\[0, 'd'\], \[1, 'e'\], \[3, 'f'\]\]);

  build() {
    Column() {
      Text('Child').fontSize(30)
      ForEach(Array.from(this.message.entries()), (item: \[number, string\]) => {
        Text(\`${item\[0\]}\`).fontSize(30)
        Text(\`${item\[1\]}\`).fontSize(30)
        Divider()
      })
      // message被@Consumer装饰，可以被观察到Map整体的赋值以及调用Map接口带来的变化
      Button('init map').onClick(() => {
        this.message = new Map(\[\[0, 'dd'\], \[1, 'ee'\], \[3, 'ff'\]\]);
      })
      Button('set new one').onClick(() => {
        this.message.set(4, 'g');
      })
      Button('clear').onClick(() => {
        this.message.clear();
      })
      Button('replace the first one').onClick(() => {
        this.message.set(0, 'a\*');
      })
      Button('delete the first one').onClick(() => {
        this.message.delete(0);
      })
    }
  }
}

#### \[h2\]装饰Set类型变量

当装饰Set类型变量时，可以观察到数据源对Set整体的赋值，以及调用Set的接口 add, clear, delete带来的变化。

@Entry
@ComponentV2
struct Parent {
  @Provider() message: Set<number> = new Set(\[1, 2, 3, 4\]);

  build() {
    Column() {
      Text('Parent').fontSize(30)
      ForEach(Array.from(this.message.entries()), (item: \[number, number\]) => {
        Text(\`${item\[0\]}\`).fontSize(30)
        Divider()
      })
      // message被@Provider装饰，可以被观察到Set整体的赋值以及调用Set接口带来的变化
      Button('init set').onClick(() => {
        this.message = new Set(\[1, 2, 3, 4\]);
      })
      Button('set new one').onClick(() => {
        this.message.add(5);
      })
      Button('clear').onClick(() => {
        this.message.clear();
      })
      Button('delete the first one').onClick(() => {
        this.message.delete(1);
      })
      Child()
    }
  }
}

@ComponentV2
struct Child {
  @Consumer() message: Set<number> = new Set(\[1, 2, 3, 4, 5, 6\]);

  build() {
    Column() {
      Text('Child').fontSize(30)
      ForEach(Array.from(this.message.entries()), (item: \[number, number\]) => {
        Text(\`${item\[0\]}\`).fontSize(30)
        Divider()
      })
      // message被@Consumer装饰，可以被观察到Set整体的赋值以及调用Set接口带来的变化
      Button('init set').onClick(() => {
        this.message = new Set(\[1, 2, 3, 4, 5, 6\]);
      })
      Button('set new one').onClick(() => {
        this.message.add(7);
      })
      Button('clear').onClick(() => {
        this.message.clear();
      })
      Button('delete the first one').onClick(() => {
        this.message.delete(1);
      })
    }
  }
}

#### \[h2\]@Provider和@Consumer装饰回调事件用于组件之间完成行为抽象

当需要在父组件中向子组件注册回调函数时，可以使用@Provider和@Consumer装饰回调方法来实现。

在拖拽场景中，若需将子组件的拖拽起始位置信息同步给父组件，可参考以下示例。

@Entry
@ComponentV2
struct Parent {
  @Local childX: number = 0;
  @Local childY: number = 1;
  @Provider() onDrag: (x: number, y: number) => void = (x: number, y: number) => {
    console.info(\`onDrag event at x=${x} y:${y}\`);
    this.childX = x;
    this.childY = y;
  }

  build() {
    Column() {
      Text(\`child position x: ${this.childX}, y: ${this.childY}\`)
      Child()
    }
  }
}

@ComponentV2
struct Child {
  @Consumer() onDrag: (x: number, y: number) => void = (x: number, y: number) => {};

  build() {
    Button('changed')
      .draggable(true)
      .onDragStart((event: DragEvent) => {
        // 当前预览器上不支持通用拖拽事件
        this.onDrag(event.getDisplayX(), event.getDisplayY());
      })
  }
}

#### \[h2\]@Provider和@Consumer装饰复杂类型，配合@Trace一起使用

1.  @Provider和@Consumer只能观察到数据本身的变化。如果需要观察其装饰的复杂数据类型的属性变化，可以配合@Trace一起使用，也可以使用[makeObserved](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-makeobserved)将非可观察数据变为可观察数据。
2.  装饰内置类型：Array、Map、Set、Date时，可以观察到某些API的变化，观察能力同[@Trace](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-observedv2-and-trace#观察变化)。

@ObservedV2
class User {
  // 复杂数据类型的属性被@Trace装饰，可以被观察到属性变化
  @Trace public name: string;
  @Trace public age: number;

  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }
}
const data: User\[\] = \[new User('Json', 10), new User('Eric', 15)\];
@Entry
@ComponentV2
struct Parent {
  @Provider('data') users: User\[\] = data;

  build() {
    Column() {
      Child()
      Button('add new user')
        .onClick(() => {
          this.users.push(new User('Molly', 18));
        })
      Button('age++')
        .onClick(() => {
          this.users\[0\].age++;
        })
      Button('change name')
        .onClick(() => {
          this.users\[0\].name = 'Shelly';
        })
    }
  }
}

@ComponentV2
struct Child {
  @Consumer('data') users: User\[\] = \[\];

  build() {
    Column() {
      ForEach(this.users, (item: User) => {
        Column() {
          Text(\`name: ${item.name}\`).fontSize(30)
          Text(\`age: ${item.age}\`).fontSize(30)
          Divider()
        }
      })
    }
  }
}

#### \[h2\]@Provider重名时，@Consumer向上查找其最近的@Provider

@Provider可以在组件树上重名，@Consumer会向上查找其最近父节点的@Provider的数据。

@Entry
@ComponentV2
struct Index {
  @Provider() val: number = 10;

  build() {
    Column() {
      Parent()
    }
  }
}

@ComponentV2
struct Parent {
  @Provider() val: number = 20;
  @Consumer('val') val2: number = 0; // 10

  build() {
    Column() {
      Text(\`${this.val2}\`)
      Child()
    }
  }
}

@ComponentV2
struct Child {
  @Consumer() val: number = 0; // 20

  build() {
    Column() {
      Text(\`${this.val}\`)
    }
  }
}

上面的例子中：

*   Parent中的@Consumer向上查找，查找到Index中定义的@Provider() val: number = 10，初始化为10。
*   Child中的@Consumer向上查找，查找到Parent中定义的@Provider() val: number = 20后停止，初始化为20。

#### \[h2\]@Provider和@Consumer初始化@Param

@Provider和@Consumer装饰的变量可以初始化子组件中@Param装饰的变量。

@Entry
@ComponentV2
struct Index {
  @Provider() val: number = 10;

  build() {
    Column() {
      Text(\`Index @Provider val: ${this.val}\`).fontSize(30)
      // @Provider装饰的变量val可以初始化@Param装饰的变量val2
      Parent({ val2: this.val })
    }
  }
}

@ComponentV2
struct Parent {
  @Consumer() val: number = 0;
  @Require @Param val2: number;

  build() {
    Column() {
      Text(\`Parent @Consumer val: ${this.val}\`).fontSize(30)
      Button('change val').onClick(() => {
        this.val++;
      })
      Text(\`Parent @Param val2: ${this.val2}\`).fontSize(30)
      // @Consumer装饰的变量val可以初始化@Param装饰的变量val
      Child({ val: this.val })
    }.border({ width: 2, color: Color.Green })
  }
}

@ComponentV2
struct Child {
  @Require @Param val: number;

  build() {
    Column() {
      Text(\`Child @Param val ${this.val}\`).fontSize(30)
    }.border({ width: 2, color: Color.Pink })
  }
}

上面的例子中：

*   Index中@Provider装饰的变量val与Parent中@Consumer装饰的变量val建立双向数据绑定。Parent中@Param装饰的变量val2接收Index中数据源val的数据，并同步其变化。Child中@Param装饰的变量val接收Parent中数据源val的数据，并同步其变化。
*   点击Parent中的按钮，触发@Consumer() val的变化，变化同步给Index中的@Provider() val和Child中的@Param val，对应UI刷新。
*   Index中@Provider() val的变化同步给Parent中的@Param val2，对应UI刷新。

#### \[h2\]@Consumer在跨BuilderNode场景下和@Provider建立双向同步过程

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/64/v3/eu-ywsABStK0Ll-TD8yhfA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073257Z&HW-CC-Expire=86400&HW-CC-Sign=3D030BE0209A562AE00B8D070CD923080ECEF8807E7136C4E8B069C4C3BC204B)

从API version 23开始，支持跨BuilderNode配对@Provider和@Consumer。

下面给出一个示例，实现如下功能：

1.  BuilderNode通过[全局自定义构建函数](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builder#全局自定义构建函数)构建组件树，组件树的根[FrameNode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-framenode)节点可通过[getFrameNode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-buildernode#getframenode)获取，该节点可直接由[NodeController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-arkui-nodecontroller)返回并挂载于[NodeContainer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-nodecontainer)节点下。
2.  挂载到自定义组件节点树时，BuilderNode会通过addBuilderNode方法挂载在自定义组件下，此时BuilderNode节点下的@Consumer会向上查找@Provider，根据key的匹配规则找到最近的@Provider后，会和@Provider建立双向同步关系。如果找不到配对的@Provider，则@Consumer仍使用默认值。
3.  建立双向同步的关系后，如果@Provider装饰变量的值和@Consumer的默认值不同，则会回调@Consumer的@Monitor方法，以及与@Consumer有同步关系的变量的[@Monitor](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-new-monitor)方法，例如：@Consumer通知其子组件中的@Param触发@Monitor方法。
4.  BuilderNode从组件树卸载后，@Consumer会再次试图查找对应的@Provider，如果发现从组件树卸载后无法再找到之前配对的@Provider，则断开和@Provider的双向同步关系，@Consumer装饰的变量恢复成默认值。
5.  @Consumer断开和@Provider的连接，恢复成默认值时，会判断@Consumer装饰变量的值相对于从@Provider变为@Consumer的默认值是否有变化，如果有变化，则会回调@Consumer的@Monitor方法以及与该@Consumer存在同步关系的变量的@Monitor方法。

import { BuilderNode, FrameNode, NodeController } from '@kit.ArkUI';

@Builder
function buildText() {
  TestRemove()
}

let globalBuilderNode: BuilderNode<\[\]> | null = null;

class TextNodeController extends NodeController {
  private rootNode: FrameNode | null = null;
  private uiContext: UIContext | null = null;

  constructor() {
    super();
  }

  makeNode(context: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(context);
    this.uiContext = context;
    return this.rootNode;
  }

  addBuilderNode(): void {
    if (globalBuilderNode === null && this.uiContext) {
      globalBuilderNode = new BuilderNode(this.uiContext);
      // 构建BuilderNode，TestRemove作为子组件
      globalBuilderNode.build(wrapBuilder<\[\]>(buildText), undefined, { enableProvideConsumeCrossing: true });
    }
    if (this.rootNode && globalBuilderNode) {
      this.rootNode.appendChild(globalBuilderNode.getFrameNode());
    }
  }

  removeBuilderNode(): void {
    if (this.rootNode && globalBuilderNode) {
      this.rootNode.removeChild(globalBuilderNode.getFrameNode());
    }
  }

  disposeNode(): void {
    if (this.rootNode && globalBuilderNode) {
      globalBuilderNode.dispose();
    }
  }
}

@Entry
@ComponentV2
struct RemoChildDisconnectProvider {
  @Provider() content: string = 'Index: hello world';
  @Monitor('content')
  providerWatch() {
    console.info(\`Provider change ${this.content}\`);
  }

  controllerIndex: TextNodeController = new TextNodeController();

  build() {
    Column({ space: 8 }) {
      Text(\`Provider: ${this.content}\`)

      // 添加BuilderNode，@Consumer与@Provider建立双向同步
      Button('add child')
        .onClick(() => {
          this.controllerIndex.addBuilderNode();
        })

      // 移除BuilderNode，@Consumer与@Provider断开连接，恢复默认值
      Button('remove child')
        .onClick(() => {
          this.controllerIndex.removeBuilderNode();
        })

      // 释放BuilderNode的子节点TestRemove，随后该子节点销毁，触发子节点的aboutToDisappear回调
      Button('dispose child')
        .onClick(() => {
          this.controllerIndex.disposeNode();
        })

      // @Provider/@Consumer双向同步更新
      Button('change Provider')
        .onClick(() => {
          this.content += 'Pro';
        })
      NodeContainer(this.controllerIndex)
    }
    .width('100%')
    .height('100%')
  }
}

@ComponentV2
struct TestRemove {
  @Consumer() content: string = 'default value';
  @Monitor('content')
  consumerWatch() {
    console.info(\`Consumer change ${this.content}\`);
  }

  aboutToDisappear() {
    console.info(\`TestRemove aboutToDisappear\`);
  }

  build() {
    Column() {
      Text('Consumer ' + this.content)

      // @Provider和@Consumer绑定的Text组件刷新，并回调@Provider和@Consumer的@Monitor方法
      Button('change cc')
        .onClick(() => {
          this.content += 'cc';
        })
    }
  }
}

上面的例子中：

*   点击add Child，TestRemove中@Consumer向上找到最近的RemoChildDisconnectProvider中的@Provider，将@Consumer从默认值更新为@Provider的值，并回调@Consumer的@Monitor方法。
*   @Provider和@Consumer配对后，建立双向同步关系。点击change Provider和Text(change cc)，@Provider和@Consumer绑定的Text组件刷新，并回调@Provider和@Consumer的@Monitor方法。
*   点击remove Child，BuilderNode子节点从组件树卸载，TestRemove中的@Consumer和RemoChildDisconnectProvider中的@Provider断开连接，TestRemove中的@Consumer恢复成默认值，并回调@Consumer的@Monitor方法。
*   点击dispose Child，释放BuilderNode下的子节点TestRemove，随后该子节点销毁，执行aboutToDisappear回调。