当前位置：首页 > article >正文

HarmonyOS 之 @Require 装饰器自学指南

article 2026/2/21 18:31:26

在 HarmonyOS 应用开发工作中，我频繁碰到组件初始化传参校验的难题。在复杂的组件嵌套里，要是无法确保必要参数在构造时准确传入，就极易引发运行时错误，而且排查起来费时费力。一次偶然的机会，我接触到了 @Require 装饰器，它能在编译阶段就对组件构造传参进行严格校验，大大提升了代码的健壮性和开发效率。然而在学习过程中，我发现相关资料零散且缺乏系统性。因此，我决定撰写这篇博客，把自己的学习经验和实践成果分享出来，助力更多开发者快速掌握 @Require 装饰器的使用方法。

1. HarmonyOS 开发文档概述

HarmonyOS 开发文档为开发者提供了全面且细致的指导，涵盖了从基础入门到高级 API 应用的各个方面。当前使用的是 HarmonyOS 5.0.3 (15) 版本，其 API 能力级别为 API 15 Release。详细的版本配套关系可参考版本说明文档，这有助于我们精准地使用适合当前版本的 API 功能。

2. @Require 装饰器概述

2.1 定义与作用

@Require 是一个用于校验 @Prop、@State、@Provide、@BuilderParam 和普通变量（无状态装饰器修饰的变量）是否需要构造传参的装饰器。当它与这些变量结合使用时，在构造自定义组件时，这些变量必须在构造时传参，否则编译将无法通过。

2.2 版本支持情况

从 API version 11 开始，@Require 对 @Prop 和 @BuilderParam 进行校验，并且支持在元服务中使用。
从 API version 12 开始，它对 @State、@Provide 和普通变量（无状态装饰器修饰的变量）进行校验。

3. @Require 装饰器的限制条件

3.1 修饰范围限制

@Require 装饰器仅能用于装饰 struct 内的 @Prop、@State、@Provide、@BuilderParam 和普通变量（无状态装饰器修饰的变量）。如果在其他地方使用，会导致代码不符合规范。

3.2 预览器限制

预览器限制场景需要参考 PreviewChecker 检测规则。这意味着在使用预览器查看组件效果时，需要确保代码符合相关规则，否则可能无法正常预览。

4. @Require 装饰器的使用场景

4.1 父子组件传参校验

当 Child 组件内使用 @Require 装饰器和 @Prop、@State、@Provide、@BuilderParam 和普通变量（无状态装饰器修饰的变量）结合使用时，父组件 Index 在构造 Child 时必须传参，否则编译不通过。以下是一个示例代码：

@Entry
@Component
struct Index {@State message: string = 'Hi, HarmonyOS';@Builder buildTest() {Row() {Text('Hi, Harmony World').fontSize(40)}}build() {Row() {Child({ regular_value: this.message, state_value: this.message, provide_value: this.message, initMessage: this.message, message: this.message,buildTest: this.buildTest, initBuildTest: this.buildTest })}}
}@Component
struct Child {@Builder buildFunction() {Column() {Text('initBuilderParam - Custom').fontSize(40).fontColor('#FF8C00')}}@Require regular_value: string = 'Hi';@Require @State state_value: string = "Hi";@Require @Provide provide_value: string = "Hi";@Require @BuilderParam buildTest: () => void;@Require @BuilderParam initBuildTest: () => void = this.buildFunction;@Require @Prop initMessage: string = 'Hi';@Require @Prop message: string;build() {Column() {Text(this.initMessage).fontSize(40).fontColor('#008080')Text(this.message).fontSize(40).fontColor('#008080')this.initBuildTest();this.buildTest();}.width('100%').height('100%')}
}

在这个示例中，父组件 Index 在构造 Child 组件时，为 Child 组件的所有使用 @Require 装饰的变量都传递了参数，确保了编译的顺利通过。同时，对文本的字体大小和颜色进行了修改，增强了视觉效果。

4.2 使用 @ComponentV2 修饰的组件初始化

使用 @ComponentV2 修饰的自定义组件 ChildPage 通过父组件 ParentPage 进行初始化，因为有 @Require 装饰，所以父组件必须进行构造赋值。以下是示例代码：

@ObservedV2
class Info {@Trace name: string = '';@Trace age: number = 0;
}@ComponentV2
struct ChildPage {@Require @Param childInfo: Info = new Info();@Require @Param state_value: string = "Hi";build() {Column() {Text(`ChildPage childInfo name :${this.childInfo.name}`).fontSize(30).fontWeight(FontWeight.Bold).fontColor('#FF69B4')Text(`ChildPage childInfo age :${this.childInfo.age}`).fontSize(30).fontWeight(FontWeight.Bold).fontColor('#FF69B4')Text(`ChildPage state_value :${this.state_value}`).fontSize(30).fontWeight(FontWeight.Bold).fontColor('#FF69B4')}}
}@Entry
@ComponentV2
struct ParentPage {info1: Info = { name: "Charlie", age: 35 };label1: string = "HarmonyOS Is Great";@Local info2: Info = { name: "Charlie", age: 35 };@Local label2: string = "HarmonyOS Is Great";build() {Column() {Text(`info1: ${this.info1.name}  ${this.info1.age}`) .fontSize(40).fontWeight(FontWeight.Bold).fontColor('#8A2BE2')ChildPage({ childInfo: this.info1, state_value: this.label1}) Line().width('100%').height(8).backgroundColor('#FF0000').margin(15)Text(`info2: ${this.info2.name}  ${this.info2.age}`) .fontSize(40).fontWeight(FontWeight.Bold).fontColor('#8A2BE2')ChildPage({ childInfo: this.info2, state_value: this.label2}) Line().width('100%').height(8).backgroundColor('#FF0000').margin(15)Button("Update info1&info2").onClick(() => {this.info1 = { name: "David", age: 28} this.info2 = { name: "David", age: 28} this.label1 = "New Fantastic Message"; this.label2 = "New Fantastic Message"; })}}
}

在这个示例中，父组件 ParentPage 在初始化 ChildPage 组件时，为 ChildPage 组件的 childInfo 和 state_value 传递了参数，保证了组件的正常初始化。同时，对文本的字体大小、颜色以及线条的高度、颜色和边距进行了修改，使界面更加美观。

5. 错误场景分析

如果在使用 @Require 装饰器时没有在构造时传参，会导致编译错误。以下是一个错误示例：

@Entry
@Component
struct Index {@State message: string = 'Hello World';@Builder buildTest() {Row() {Text('Hello, world').fontSize(32)}}build() {Row() {Child()}}
}@Component
struct Child {@Builder buildFunction() {Column() {Text('initBuilderParam - Error Case').fontSize(32).fontColor('#FF00FF')}}// 使用@Require必须构造时传参。@Require regular_value: string = 'Hello';@Require @State state_value: string = "Hello";@Require @Provide provide_value: string = "Hello";@Require @BuilderParam initBuildTest: () => void = this.buildFunction;@Require @Prop initMessage: string = 'Hello';build() {Column() {Text(this.initMessage).fontSize(32).fontColor('#FF00FF')this.initBuildTest();}}
}

在这个示例中，父组件 Index 在构造 Child 组件时没有传递任何参数，由于 Child 组件中的变量使用了 @Require 装饰器，所以这段代码在编译时会报错。同时，对文本的字体大小和颜色进行了修改，方便区分不同的代码部分。

6. 总结

@Require 装饰器在 HarmonyOS 开发中是一个非常实用的工具，它可以帮助我们在编译阶段就发现组件构造传参的问题，避免运行时错误，提高代码的稳定性和可维护性。通过本文的介绍，你应该对 @Require 装饰器的使用有了更深入的理解。在实际开发中，合理运用 @Require 装饰器，能够让你的代码更加健壮，开发过程更加顺畅。

最后希望这篇自学指南能对你有所帮助，让你在 HarmonyOS 开发的道路上更进一步，当然对鸿蒙有兴趣的同学也欢迎点赞、收藏～！