鸿蒙开发：校验构造传参装饰器@Require

前言

本文代码案例基于Api13。

在自定义组件中，特别是开源给到他人使用的组件中，有些参数是必须要传递的，然而往往由于调用者不知，尝尝出现忘记传递的情况，以至于造成异常后才发现，虽然可以通过文档说明的方式进行标记，但是仍有粗心大意的同学试错后才会发现，所以在这时，就不得不想一种方式，如果参数未传递，就直接提示调用者必须传递的方法，这就是本篇文章的内容，@Require装饰器，一个校验构造传参的装饰器。

比如，我们有一个自定义组件，有一个参数是必须传递，如下简单案例，content属性是必须要传递的，未传递，也能正常调用运行。

@Component
struct TextView {
  @Prop content: string//必须传递

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

当然了，以上只是一个特别简单的例子，在属性很多的情况下，调用者往往会忘记传递，到了遇到异常的时候才会发现，这时，我们把@Require装饰器修饰上。

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

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

修饰完，我们再次进行调用，就可以发现，如果你未传递参数，就会直接报出异常，提示你，参数必须传递。

什么是@Require装饰器

@Require装饰器其主要功能是在组件初始化时自动校验传入参数的合法性，通过预定义的校验规则，它可以有效拦截非法参数，避免因数据问题导致的运行时异常或逻辑错误。

核心特性

@Require装饰器仅用于装饰struct内的@Prop、@State、@Provide、@BuilderParam和无状态装饰器修饰的变量，其核心特点有：1、声明式校验：通过装饰器语法声明参数的校验规则，与业务逻辑解耦；2、类型安全：强制校验参数类型，避免因类型不匹配导致的隐式错误；3、空值防护：支持非空校验，防止因未传参引发的空指针异常；4、自定义扩展：可结合其他逻辑实现复杂校验，如范围检查、正则匹配等。

适用场景

主要适用的场景，就是在自定义组件中，需要针对传递的参数做校验时，需要确保参数符合特定类型或业务规则时 ，这时就可以使用@Require装饰器装饰器。

使用规范

基本示例

@Component
struct TextView {
  @Require @Prop content: string; // 声明content为必传且类型为string的参数
  build() {
    Text(this.content).fontSize(20)
  }
}

@Entry
@Component
struct ParentComponent {
  build() {
    Column() {
      // 合法传参
      TextView({ content: "Hello HarmonyOS" })
      // 非法传参（编译时报错）
      // TextView() // 缺少content参数
      // TextView({ content: 123 }) // 类型不匹配
    }
  }
}

代码解析

自定义组件TextView通过@Require声明content为必传的string类型参数。

调用组件时若未传递content或类型错误，编译阶段即会触发报错，而非在运行时报错。

如果除此之外还有其他的校验，可以在组件初始化时进行逻辑判断。

  aboutToAppear(): void {
    //其它逻辑判断
    if(this.content.length<10){
      
    }
  }

注意事项

注意事项还是上述所说的一点，那就是，@Require装饰器仅用于装饰struct内的@Prop、@State、@Provide、@BuilderParam和无状态装饰器修饰的变量，当然了以上的是V1版本的装饰器，也适用于对应的V2版本的装饰器，除此之外的场景均不适用。其优点就是减少冗余代码，提升可读性；编译时错误更早暴露问题。 当然，也有自己的局限性，那就是无法覆盖所有运行时场景，需结合其他校验手段。

@Require装饰器依赖ArkTs的类型检查，仅在编译阶段拦截类型错误和缺失参数，对于运行时才能确定的动态值，如从网络请求获取的数据，仍需在生命周期函数中进行二次校验。

相关总结

@Require装饰器以声明式语法将参数校验前置到编译阶段，显著降低因参数错误导致的运行时报错风险；然而，对于复杂的业务规则，比如联合使用类型或自定义校验函数等场景，以及需在生命周期函数中补充校验逻辑时，除了正确使用@Require装饰器，还需要结合其它的判断逻辑。

最后一点，文章中提到的适用场景，在V2版本中的装饰器，也有对应的装饰器使用，比如@Param装饰器。