HarmonyOS Development: Check Structure Transmission Decorator @ Require

Foreword

this article code case based on api13.

In custom components, especially components that are used by others by open source, some parameters must be passed. However, because the caller does not know and forgets to pass them, it is found only after causing abnormalities. Although it can be marked by documentation, there are still careless students who will find out after trial and error. Therefore, at this time, one has to think of a way, if the parameter is not passed, the caller is directly prompted to the method that must be passed. This is the content of this article, @ Require decorator, a decorator that checks the construction to pass parameters.

For example, we have a custom component with a parameter that must be passed. In the following simple case, the content attribute must be passed. If it is not passed, it can be called and run normally.

@Component
struct TextView {
  @Prop content: string

  build() {
    Text(this.content)
  }
}

Of course, the above is just a particularly simple example. In the case of many attributes, the caller will often forget to pass it, and will not find it until he encounters an exception. At this time, we decorate the @ Require decorator.

@Component
struct TextView {
  @Require @Prop content: string

  build() {
    Text(this.content)
  }
}

After decoration, we call again, and we can find that if you do not pass the parameter, you will directly report an exception, prompting you that the parameter must be passed.

What is the @ Require decorator

the main function of the @ Require decorator is automatically verify the validity of incoming parameters during component initialization through predefined verification rules, it can effectively intercept illegal parameters and avoid runtime exceptions or logic errors caused by data problems.

Core Features

The @ Require decorator is only used to decorate variables decorated by @ Prop, @ State, @ Provide, @ BuilderParam, and stateless decorators in struct. Its core features are: 1. Declarative verification: Declares the verification rules of parameters through decorator syntax to decouple from business logic; 2. Type safety: mandatory verification of parameter types to avoid implicit errors caused by type mismatch; 3. Null value protection: supports non-null verification to prevent null pointer exceptions caused by non-passing parameters; 4. Custom Extension: Complex verification can be implemented in combination with other logic, such as range check, regular matching, etc.

Applicable Scenarios

the main applicable scenario is that when you need to verify the passed parameters in a custom component and ensure that the parameters conform to a specific type or business rule, you can use @ Require decorator decorator.

Specification for use

basic example

@Component
struct TextView {
@Require @Prop content: string; //Declare content as a required and string type parameter
build() {
Text(this.content).fontSize(20)
}
}
@Entry
@Component
struct ParentComponent {
build() {
Column() {
//Legitimate transmission of reference
TextView({ content: "Hello HarmonyOS" })
//Illegal parameter transmission (compile report error)
//TextView()//Missing content parameter
//TextView ({content: 123})//Type mismatch
}
}
}

code parsing

the custom component TextView declares content as a required string type parameter through @ Require.

If the content or type error is not passed when calling the component, the compilation phase will trigger an error instead of an error at runtime.

If there are other checks in addition to this, logical judgment can be made during component initialization.

  aboutToAppear(): void {

    if(this.content.length<10){

    }
  }

Precautions

The note is still the above-mentioned point, that is, the @ Require decorator is only used to decorate the variables decorated by @ Prop, @ State, @ Provide, @ BuilderParam and stateless decorators in struct. Of course, the above is the V1 version of the decorator, which is also applicable to the corresponding V2 version of the decorator, and other scenes are not applicable. Its advantages it is to reduce redundant code and improve readability; Compile-time errors expose problems earlier. Of course, also have their own limitations , that is, it cannot cover all runtime scenarios and needs to be combined with other verification methods.

@ the Require decorator relies on the type checking of ArkTs to intercept type errors and missing parameters only during the compilation phase, and for dynamic values that can be determined at runtime, such as data obtained from network requests, secondary validation is still required in the lifecycle function.

Related Summary

the @ Require decorator uses declarative syntax to Prestage parameter verification to the compilation stage, significantly reducing the risk of runtime errors caused by parameter errors. However, for complex business rules, such as scenarios such as joint use of types or custom verification functions, and when verification logic needs to be added to Lifecycle Functions, in addition to the correct use of the @ Require decorator, other judgment logic must be combined.

Finally, for the applicable scenarios mentioned in the article, the decorators in the V2 version also have corresponding decorators, such as the @ Param decorator.