How to use HarmonyOS NEXT - @Provide and @Consume?

@Provide and @Consume are used for two-way data synchronization with future generations of components, and for scenarios where state data is transmitted between multiple levels. Different from the above-mentioned transfer between father and son components through named parameter mechanism, @Provide and @Consume get rid of the constraints of parameter transfer mechanism and realize cross-level transfer. Among them, the variable decorated by @Provide is in the ancestor component, which can be understood as a state variable that is "provided" to future generations. The variable decorated by @Consume is the variable provided by the ancestor component in the descendant component. @Provide/@Consume is a two-way synchronization across component levels. Before reading the @Provide and @Consume documents, it is recommended that developers have a basic understanding of the basic syntax and custom components of the UI paradigm. It is recommended to read in advance: basic syntax overview, declarative UI description, custom components-creating custom components. The status variable decorated by @Provide/@Consume has the following characteristics: The state variable decorated by-@Provide is automatically available to all its descendant components, that is, the variable is "provided" to his descendant components. Thus, the convenience of @Provide is that developers don't need to pass variables between components many times. Descendants use @Consume to obtain variables provided by @Provide, and establish two-way data synchronization between @Provide and @Consume. Unlike @State/@link, the former can be passed between multi-level parent-child components. @Provide and @Consume can be bound by the same variable name or the same variable alias, suggesting the same type, otherwise implicit type conversion will occur, resulting in abnormal application behavior. @Provide/@Consume must specify the type, and the variable types that allow decoration are as follows: Object, class, string, number, boolean, enum types, and arrays of these types. Date type is supported. API11 and above support Map and Set types. Support the union types defined by the ArkUI framework, such as Length, ResourceStr and ResourceColor. The type of @Consume variable of-@Provide variable must be the same. any is not supported. API11 and above support the union types of the above supported types, such as string | number, string | undefined or ClassA | null. For an example, see @Provide_and_Consume for an example of supporting union types. Code example // Bound by the same variable name @Provide a: number = 0; @Consume a: number; // Bound by the same variable alias @Provide('a') b: number = 0; @Consume('a') c: number; Code example ProvideConsumePage import { SonComponent } from './components/SonComponent'; @Entry @Component struct ProvideConsumePage { @State message: string = '@Provide and @Consume'; @Provide('count') stateCount: number = 0 build() { Column({space:10}) { Text(this.message) .fontSize(20) .fontWeight(FontWeight.Bold) Button('增加次数').onClick(()=>{ this.stateCount++ }) Text('stateCount='+this.stateCount) SonComponent() } .height('100%') .width('100%') } } SonComponent import { GrandsonComponent } from './GrandsonComponent' @Component export struct SonComponent { build() { Column({ space: 10 }) { Text('这是子组件') GrandsonComponent() } .width('100%') .padding(10) .backgroundColor(Color.Orange) } } GrandsonComponent @Component export struct GrandsonComponent { @Consume('count') grandsonCount: number build() { Column({space:10}){ Text('孙组件') Button('增加次数').onClick(()=>{ this.grandsonCount++ }) Text('grandsonCount='+this.grandsonCount) } .width('100%') .padding(10) .backgroundColor('#EEEEEE') } }

Mar 25, 2025 - 14:13

How to use HarmonyOS NEXT - @Provide and @Consume?

@Provide and @Consume are used for two-way data synchronization with future generations of components, and for scenarios where state data is transmitted between multiple levels. Different from the above-mentioned transfer between father and son components through named parameter mechanism, @Provide and @Consume get rid of the constraints of parameter transfer mechanism and realize cross-level transfer.

Among them, the variable decorated by @Provide is in the ancestor component, which can be understood as a state variable that is "provided" to future generations. The variable decorated by @Consume is the variable provided by the ancestor component in the descendant component.

@Provide/@Consume is a two-way synchronization across component levels. Before reading the @Provide and @Consume documents, it is recommended that developers have a basic understanding of the basic syntax and custom components of the UI paradigm. It is recommended to read in advance: basic syntax overview, declarative UI description, custom components-creating custom components.

The status variable decorated by @Provide/@Consume has the following characteristics:

The state variable decorated by-@Provide is automatically available to all its descendant components, that is, the variable is "provided" to his descendant components. Thus, the convenience of @Provide is that developers don't need to pass variables between components many times.
Descendants use @Consume to obtain variables provided by @Provide, and establish two-way data synchronization between @Provide and @Consume. Unlike @State/@link, the former can be passed between multi-level parent-child components.
@Provide and @Consume can be bound by the same variable name or the same variable alias, suggesting the same type, otherwise implicit type conversion will occur, resulting in abnormal application behavior.

@Provide/@Consume must specify the type, and the variable types that allow decoration are as follows:

Object, class, string, number, boolean, enum types, and arrays of these types.
Date type is supported.
API11 and above support Map and Set types.
Support the union types defined by the ArkUI framework, such as Length, ResourceStr and ResourceColor.
The type of @Consume variable of-@Provide variable must be the same.
any is not supported.
API11 and above support the union types of the above supported types, such as string | number, string | undefined or ClassA | null. For an example, see @Provide_and_Consume for an example of supporting union types.

Code example

// Bound by the same variable name
@Provide a: number = 0;
@Consume a: number;

// Bound by the same variable alias
@Provide('a') b: number = 0;
@Consume('a') c: number;

Code example
ProvideConsumePage

import { SonComponent } from './components/SonComponent';

@Entry
@Component
struct ProvideConsumePage {
  @State message: string = '@Provide and @Consume';
  @Provide('count') stateCount: number = 0

  build() {
    Column({space:10}) {
      Text(this.message)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)

      Button('增加次数').onClick(()=>{
        this.stateCount++
      })
      Text('stateCount='+this.stateCount)

      SonComponent()
    }
    .height('100%')
    .width('100%')
  }
}

SonComponent

import { GrandsonComponent } from './GrandsonComponent'

@Component
export struct SonComponent {
  build() {
    Column({ space: 10 }) {
      Text('这是子组件')

      GrandsonComponent()
    }
    .width('100%')
    .padding(10)
    .backgroundColor(Color.Orange)
  }
}

GrandsonComponent

@Component
export struct GrandsonComponent {
  @Consume('count') grandsonCount: number

  build() {
    Column({space:10}){
      Text('孙组件')
      Button('增加次数').onClick(()=>{
        this.grandsonCount++
      })
      Text('grandsonCount='+this.grandsonCount)
    }
    .width('100%')
    .padding(10)
    .backgroundColor('#EEEEEE')
  }
}