鸿蒙应用开发之跨组件传参：@Provide 与 @Consume 跨层级数据同步详解

这是一个使用鸿蒙技术开发的本地原生记账应用，非常适合大家用来练手。相关源码已上传至 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 中处理跨层级组件状态共享的利器。通过本文的学习，你应该已经掌握了它们的使用方法、绑定规则和注意事项。在实际开发中，当遇到多层嵌套组件需要共享状态时，可以先考虑这对装饰器，或许能让你的代码更加简洁和优雅。