harmony 鸿蒙\@Once: Implementing Initialization Once

2025-06-12
浏览 (4)

\@Once: Implementing Initialization Once

To initialize data only once and deny subsequent changes, you can use \@Once decorator together with \@Param decorator.

Before reading this topic, you are advised to read \@Param.

NOTE

The \@Once decorator is supported in custom components decorated by \@ComponentV2 since API version 12.

Overview

The \@Once decorator accepts values passed in only during variable initialization. When the data source changes, the decorator does not synchronize the changes to child components:

\@Once must be used with \@Param. Using it independently or with other decorators is not allowed.
\@Once does not affect the observation capability of \@Param. Only changes in data source are intercepted.
The sequence of the variables decorated by \@Once and \@Param does not affect the actual features.
When \@Once and \@Param are used together, you can change the value of \@Param variables locally.

Rules of Use

As an auxiliary decorator, the \@Once decorator does not have requirements on the decoration type and the capability of observing variables.

\@Once Variable Decorator	Description
Decorator parameters	None.
Condition	It cannot be used independently and must be used together with the \@Param decorator.

Constraints

\@Once can be used only in custom components decorated by \@ComponentV2 and can be used only with \@Param.

  @ComponentV2
  struct MyComponent {
    @Param @Once onceParam: string = "onceParam"; // Correct usage.
    @Once onceStr: string = "Once"; // Incorrect usage. @Once cannot be used independently.
    @Local @Once onceLocal: string = "onceLocal"; // Incorrect usage. @Once cannot be used with @Local.
  }
  @Component
  struct Index {
    @Once @Param onceParam: string = "onceParam"; // Incorrect usage.
  }

The order of \@Once and \@Param does not matter. Both \@Param \@Once and \@Once \@Param are correct.

  @ComponentV2
  struct MyComponent {
    @Param @Once param1: number;
    @Once @Param param2: number;
  }

Use Scenarios

Initializing Variables Only Once

\@Once is used in the scenario where the expected variables synchronize the data source once during initialization and then stop synchronizing the subsequent changes.

@ComponentV2
struct ChildComponent {
  @Param @Once onceParam: string = "";
  build() {
  	Column() {
  	  Text(`onceParam: ${this.onceParam}`)
  	}
  }
}
@Entry
@ComponentV2
struct MyComponent {
  @Local message: string = "Hello World";
  build() {
  	Column() {
      Text(`Parent message: ${this.message}`)
      Button("change message")
        .onClick(() => {
          this.message = "Hello Tomorrow";
        })
      ChildComponent({ onceParam: this.message })
  	}
  }
}

Changing the \@Param Variables Locally

When \@Once is used together with \@Param, the constraint that \@Param cannot be changed locally can be removed, and this change triggers UI re-rendering. In this case, using \@Param and \@Once is equivalent to using \@Local. The difference is that \@Param and \@Once can accept the external initialization passed in.

@ObservedV2
class Info {
  @Trace name: string;
  constructor(name: string) {
    this.name = name;
  }
}
@ComponentV2
struct Child {
  @Param @Once onceParamNum: number = 0;
  @Param @Once @Require onceParamInfo: Info;

  build() {
    Column() {
      Text(`Child onceParamNum: ${this.onceParamNum}`)
      Text(`Child onceParamInfo: ${this.onceParamInfo.name}`)
      Button("changeOnceParamNum")
        .onClick(() => {
          this.onceParamNum++;
        })
      Button("changeParamInfo")
        .onClick(() => {
          this.onceParamInfo = new Info("Cindy");
        })
    }
  }
}
@Entry
@ComponentV2
struct Index {
  @Local localNum: number = 10;
  @Local localInfo: Info = new Info("Tom");

  build() {
    Column() {
      Text(`Parent localNum: ${this.localNum}`)
      Text(`Parent localInfo: ${this.localInfo.name}`)
      Button("changeLocalNum")
        .onClick(() => {
          this.localNum++;
        })
      Button("changeLocalInfo")
        .onClick(() => {
          this.localInfo = new Info("Cindy");
        })
      Child({
        onceParamNum: this.localNum,
        onceParamInfo: this.localInfo
      })
    }
  }
}