HarmonyOS 之 @Require 装饰器自学指南

在 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 时必须传参，否则编译不通过。以下是一个示例代码：

1. @Entry
2. @Component
3. struct Index {
4.   @State message: string = 'Hi, HarmonyOS';
6.   @Builder buildTest() {
7.     Row() {
8.       Text('Hi, Harmony World')
9.         .fontSize(40)
10.     }
11.   }
13.   build() {
14.     Row() {
15.       Child({
16.         regular_value: this.message,
17.         state_value: this.message,
18.         provide_value: this.message,
19.         initMessage: this.message,
20.         message: this.message,
21.         buildTest: this.buildTest,
22.         initBuildTest: this.buildTest
23.       })
24.     }
25.   }
26. }
28. @Component
29. struct Child {
30.   @Builder buildFunction() {
31.     Column() {
32.       Text('initBuilderParam - Custom')
33.         .fontSize(40)
34.         .fontColor('#FF8C00')
35.     }
36.   }
37.   @Require regular_value: string = 'Hi';
38.   @Require @State state_value: string = "Hi";
39.   @Require @Provide provide_value: string = "Hi";
40.   @Require @BuilderParam buildTest: () => void;
41.   @Require @BuilderParam initBuildTest: () => void = this.buildFunction;
42.   @Require @Prop initMessage: string = 'Hi';
43.   @Require @Prop message: string;
45.   build() {
46.     Column() {
47.       Text(this.initMessage)
48.         .fontSize(40)
49.         .fontColor('#008080')
50.       Text(this.message)
51.         .fontSize(40)
52.         .fontColor('#008080')
53.       this.initBuildTest();
54.       this.buildTest();
55.     }
56.     .width('100%')
57.     .height('100%')
58.   }
59. }

复制代码

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

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

1. @ObservedV2
2. class Info {
3.   @Trace name: string = '';
4.   @Trace age: number = 0;
5. }
7. @ComponentV2
8. struct ChildPage {
9.   @Require @Param childInfo: Info = new Info();
10.   @Require @Param state_value: string = "Hi";
11.   build() {
12.     Column() {
13.       Text(`ChildPage childInfo name :${this.childInfo.name}`)
14.         .fontSize(30)
15.         .fontWeight(FontWeight.Bold)
16.         .fontColor('#FF69B4')
17.       Text(`ChildPage childInfo age :${this.childInfo.age}`)
18.         .fontSize(30)
19.         .fontWeight(FontWeight.Bold)
20.         .fontColor('#FF69B4')
21.       Text(`ChildPage state_value :${this.state_value}`)
22.         .fontSize(30)
23.         .fontWeight(FontWeight.Bold)
24.         .fontColor('#FF69B4')
25.     }
26.   }
27. }
29. @Entry
30. @ComponentV2
31. struct ParentPage {
32.   info1: Info = { name: "Charlie", age: 35 };
33.   label1: string = "HarmonyOS Is Great";
34.   @Local info2: Info = { name: "Charlie", age: 35 };
35.   @Local label2: string = "HarmonyOS Is Great";
37.   build() {
38.     Column() {
39.       Text(`info1: ${this.info1.name}  ${this.info1.age}`)
40.         .fontSize(40)
41.         .fontWeight(FontWeight.Bold)
42.         .fontColor('#8A2BE2')
43.       ChildPage({ childInfo: this.info1, state_value: this.label1})
44.       Line()
45.         .width('100%')
46.         .height(8)
47.         .backgroundColor('#FF0000').margin(15)
48.       Text(`info2: ${this.info2.name}  ${this.info2.age}`)
49.         .fontSize(40)
50.         .fontWeight(FontWeight.Bold)
51.         .fontColor('#8A2BE2')
52.       ChildPage({ childInfo: this.info2, state_value: this.label2})
53.       Line()
54.         .width('100%')
55.         .height(8)
56.         .backgroundColor('#FF0000').margin(15)
57.       Button("Update info1&info2")
58.         .onClick(() => {
59.           this.info1 = { name: "David", age: 28}
60.           this.info2 = { name: "David", age: 28}
61.           this.label1 = "New Fantastic Message";
62.           this.label2 = "New Fantastic Message";
63.         })
64.     }
65.   }
66. }

复制代码

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

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

1. @Entry
2. @Component
3. struct Index {
4.   @State message: string = 'Hello World';
6.   @Builder buildTest() {
7.     Row() {
8.       Text('Hello, world')
9.         .fontSize(32)
10.     }
11.   }
13.   build() {
14.     Row() {
15.       Child()
16.     }
17.   }
18. }
20. @Component
21. struct Child {
22.   @Builder buildFunction() {
23.     Column() {
24.       Text('initBuilderParam - Error Case')
25.         .fontSize(32)
26.         .fontColor('#FF00FF')
27.     }
28.   }
29.   // 使用@Require必须构造时传参。
30.   @Require regular_value: string = 'Hello';
31.   @Require @State state_value: string = "Hello";
32.   @Require @Provide provide_value: string = "Hello";
33.   @Require @BuilderParam initBuildTest: () => void = this.buildFunction;
34.   @Require @Prop initMessage: string = 'Hello';
36.   build() {
37.     Column() {
38.       Text(this.initMessage)
39.         .fontSize(32)
40.         .fontColor('#FF00FF')
41.       this.initBuildTest();
42.     }
43.   }
44. }

复制代码

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

@Require 装饰器在 HarmonyOS 开发中是一个非常实用的工具，它可以帮助我们在编译阶段就发现组件构造传参的问题，制止运行时错误，进步代码的稳固性和可维护性。通过本文的先容，你应该对 @Require 装饰器的使用有了更深入的明白。在实际开发中，合理运用 @Require 装饰器，能够让你的代码更加结实，开发过程更加顺畅。
最后希望这篇自学指南能对你有所帮助，让你在 HarmonyOS 开发的道路上更进一步，固然对鸿蒙有兴趣的同砚也接待点赞、收藏～！