在 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 开发的道路上更进一步，当然对鸿蒙有兴趣的同学也欢迎点赞、收藏～！
