这是一个使用鸿蒙技术开发的本地原生记账应用，非常适合大家用来练手。相关源码已上传至 Github，点击此处查看项目。欢迎大家交流、指正，也欢迎提交 PR。
一、引言
在鸿蒙（HarmonyOS）应用开发中，组件间的数据传递是构建复杂 UI 的核心。对于简单的父子组件通信，我们可以使用 @Prop 或 @Link。但当组件嵌套层级较深时，逐层传递参数会变得繁琐且难以维护。
为了解决这一问题，HarmonyOS 状态管理 V1 版本提供了 @Provide 和 @Consume 装饰器。它们允许祖先组件"提供"一个状态变量，而任意层级的后代组件都可以"消费"这个变量，并建立双向数据同步，从而彻底摆脱逐层传参的束缚。
本文将详细介绍 @Provide 和 @Consume 的核心概念、绑定方式、装饰器规则，并通过完整的代码示例，带你掌握这一高效的状态管理技巧。
二、核心概念
@Provide 和 @Consume 是一对用于跨层级组件双向数据同步的装饰器。
- @Provide：在祖先组件中装饰一个状态变量，表示该变量对其所有后代组件"可用"。这个变量会自动成为其组件子树中的一个"数据源"。
- @Consume ：在后代组件中装饰一个变量，表示该变量需要"消费"祖先组件中某个
@Provide提供的数据。两者通过变量名或别名建立绑定关系。
关键特性 ：一旦绑定，@Provide 和 @Consume 之间就建立了双向数据同步 。无论是祖先组件修改了 @Provide 变量，还是后代组件修改了 @Consume 变量，变化都会立即同步到对方。
三、绑定方式
@Provide 和 @Consume 支持两种绑定方式，以适应不同的命名场景。
3.1 通过相同的变量名绑定
这是最直接的方式。祖先组件和后代组件使用完全相同的变量名进行绑定。
typescript
// 祖先组件
@Provide count: number = 0;
// 后代组件
@Consume count: number;3.2 通过相同的别名绑定
当变量名不方便直接对应（例如，祖先组件中的变量名是 primaryColor，但后代组件希望用 color 来消费）时，可以使用别名。别名通过装饰器的参数传入。
typescript
// 祖先组件：提供数据，别名为 'themeColor'
@Provide('themeColor') primaryColor: string = '#007DFF';
// 后代组件：消费数据，使用相同的别名 'themeColor'
@Consume('themeColor') color: string;推荐使用别名形式，因为它可以避免不同模块或不同场景下的变量名冲突，使代码的意图更加清晰。
四、装饰器规则对比
为了更清晰地理解两者的区别，下表对比了 @Provide 和 @Consume 的关键规则：
| 属性 | @Provide | @Consume |
|---|---|---|
| 装饰器参数 | 别名（可选），未指定时默认使用变量名 | 别名（可选），需与祖先的 @Provide 变量名或别名匹配 |
| 同步类型 | 双向同步（与所有匹配的 @Consume 变量） |
双向同步（与匹配的 @Provide 变量） |
| 允许的变量类型 | Object、class、string、number、boolean、enum 及这些类型的数组、Date | 必须与 @Provide 类型完全一致 |
| 初始值 | 必须显式指定 | API version 19 及以前：禁止本地初始化禁止本地初始化 ，其值完全由 @Provide 决定。如果找不到匹配的 @Provide，框架会抛出异常。 API version 20 开始：支持设置默认值，找不到匹配的 @Provide，@Consume变量使用默认值进行初始化，不会抛出异常 |
| 作用范围 | 私有，仅限所属组件内 | 私有，仅限所属组件内 |
五、注意事项
在使用 @Provide 和 @Consume 时，需要留意以下几点：
- 禁止同名 ：不允许在同一个自定义组件内（含其子组件）声明多个同名或同别名的
@Provide，否则运行时会报错。 - 类型一致 ：
@Provide和@Consume的变量类型必须相同，否则会发生隐式类型转换导致行为异常。 - 不支持 any ：
@Provide和@Consume均不支持any类型。
六、示例：跨层级双向同步
以下示例展示了 @Provide 和 @Consume 在深层嵌套组件中的强大能力。CompA 是祖先组件，CompD 是深层后代组件，中间隔了 CompB 和 CompC 两层。点击 CompA 或 CompD 中的按钮，reviewVotes 的变化会双向同步。
typescript
// 后代组件 CompD：通过 @Consume 消费祖先组件提供的 reviewVotes
@Component
struct CompD {
@Consume reviewVotes: number
build() {
Column({space: 20}) {
Text(`CompD - reviewVotes(${this.reviewVotes})`).fontSize(20)
Button(`CompD - reviewVotes(${this.reviewVotes}), give +1`)
.fontSize(20)
.onClick(() => this.reviewVotes += 1)
}
.width('100%')
.backgroundColor(Color.Orange)
}
}
// 中间组件 CompC：仅做布局，不需要传递参数
@Component
struct CompC {
build() {
Column({ space: 5 }) {
Text("CompC").fontSize(20)
CompD()
CompD()
}
.backgroundColor(Color.Pink)
}
}
// 中间组件 CompB：仅做布局，不需要传递参数
@Component
struct CompB {
build() {
Column() {
Text("CompB").fontSize(20)
CompC()
}
.backgroundColor(Color.Red)
}
}
// 祖先组件 CompA：通过 @Provide 提供 reviewVotes 给所有后代
@Entry
@Component
struct CompA {
@Provide reviewVotes: number = 0
build() {
Column({space: 20}) {
Button(`CompA - reviewVotes(${this.reviewVotes}), give +1`)
.fontSize(20)
.onClick(() => this.reviewVotes += 1)
CompB()
}
.backgroundColor(Color.Green)
}
}运行效果：
七、示例：使用别名绑定
当变量名不方便直接对应时，可以通过别名进行绑定，使代码更具可读性和灵活性。
typescript
@Component
struct ChildPage {
// 通过别名 'themeColor' 消费祖先组件提供的数据
@Consume('themeColor') color: string
build() {
Text('主题色文本')
.fontColor(this.color)
}
}
@Entry
@Component
struct ParentPage {
// 通过别名 'themeColor' 提供数据给后代组件
@Provide('themeColor') primaryColor: string = '#007DFF'
build() {
Column() {
Button('切换主题色')
.onClick(() => {
this.primaryColor = this.primaryColor === '#007DFF' ? '#E84026' : '#007DFF'
})
ChildPage()
}
}
}运行效果：
八、与逐层传参的对比
使用 @Prop / @Link 逐层传递数据时，中间每一层组件都需要声明并传递参数，即使该组件本身并不使用该数据。这不仅增加了代码量，也使得组件间的耦合度变高。
而 @Provide / @Consume 摆脱了参数传递机制的束缚，中间组件无需感知该数据的存在，直接由祖先"提供"、后代"消费"，大幅简化了深层嵌套场景下的代码，提升了开发效率和代码的可维护性。
九、总结
@Provide 和 @Consume 是 HarmonyOS 中处理跨层级组件状态共享的利器。通过本文的学习，你应该已经掌握了它们的使用方法、绑定规则和注意事项。在实际开发中，当遇到多层嵌套组件需要共享状态时，可以先考虑这对装饰器，或许能让你的代码更加简洁和优雅。