ArkTs 语法学习 ---- 组件相关装饰器

装饰器

特殊装饰器

组件相关装饰器

• @Entry
• @Component
• @Builder
• @BuilderParam
• @CustomDialog

@Entry 页面入口装饰器

@Entry	说明
装饰器参数	无
装饰对象	自定义组件
特性	被装饰的自定义组件作为页面入口， 单个UI页面中，最多可以使用@Entry装饰一个自定义组件 @Entry可以接受一个可选的LocalStorage的参数

@Component 自定义组件装饰器

自定义组件的基本结构:

• struct：自定义组件基于struct实现，struct + 自定义组件名 + {…}的组合构成自定义组件，不能有继承关系。对于struct的实例化，可以省略new。
• 自定义组件名、类名、函数名不能和系统组件名相同。

@Component	说明
装饰器参数	无
装饰对象	仅能装饰struct关键字声明的数据结构。
特性	struct被@Component装饰后具备组件化的能力， 需要实现build方法描述UI， 一个struct只能被一个@Component装饰。

@Builder

@Builder	说明
装饰器参数	无
装饰对象	函数，被装饰的函数被称为自定义构造函数
语法规则	@Builder所装饰的函数遵循build()函数语法规则， 开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。
创建，使用语法	自定义组件内：创建@Builder MyBuilderFunction(){ … }，使用this.MyBuilderFunction() 全局：创建@Builder function MyGlobalBuilderFunction(){ … }，使用MyGlobalBuilderFunction()
自定义组件内	可以定义一个或多个, 该方法被认为是该组件的私有、特殊类型的成员函数。 可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。
全局	可以被整个应用获取，不允许使用this和bind方法。 如果不涉及组件状态变化，建议使用全局的自定义构建方法。
this指向	this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。 建议通过this访问自定义组件的状态变量而不是参数传递。
参数传递方式	按值传递和按引用传递
参数传递规则	参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式。 不允许改变参数值。如果需要改变参数值，且同步回调用点，建议使用@Link。 @Builder内UI语法遵循UI语法规则 只有传入一个参数，且参数需要直接传入对象字面量才会按引用传递该参数，其余传递方式均为按值传递。

• 按引用传递参数
  参数可为状态变量，且状态变量的改变会引起@Builder方法内的UI刷新。ArkUI提供$$作为按引用传递参数的范式。

ABuilder( $$ : { paramA1: string, paramB1 : string } );

@Builder function ABuilder($$: { paramA1: string }) {
  Row() {
    Text(`UseStateVarByReference: ${$$.paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      // 在Parent组件中调用ABuilder的时候，将this.label引用传递给ABuilder
      ABuilder({ paramA1: this.label })
      Button('Click me').onClick(() => {
        // 点击“Click me”后，UI从“Hello”刷新为“ArkUI”
        this.label = 'ArkUI';
      })
    }
  }
}

• 按值传递参数
  调用@Builder装饰的函数默认按值传递。当传递的参数为状态变量时，状态变量的改变不会引起@Builder方法内的UI刷新。所以当使用状态变量的时候，推荐使用按引用传递。

@Builder function ABuilder(paramA1: string) {
  Row() {
    Text(`UseStateVarByValue: ${paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      ABuilder(this.label)
    }
  }
}

@BuilderParam 装饰指向@Builder方法的变量

@BuilderParam	说明
装饰器参数	无
值类型	@Builder 装饰的函数 即 @BuilderParam装饰的方法只能被自定义构建函数（@Builder装饰的方法）初始化。
this指向	this指向 绘制时的父组件

• @BuilderParam装饰的方法可以是有参数和无参数的两种形式，需与指向的@Builder方法类型匹配。@BuilderParam装饰的方法类型需要和@Builder方法类型一致。
• 尾随闭包初始化组件
  自定义组件内有且仅有一个使用@BuilderParam装饰的属性才能使用
  在初始化自定义组件时，组件后紧跟一个大括号“{}”形成尾随闭包场景。
  可以将尾随闭包内的内容看做@Builder装饰的函数传给@BuilderParam

@Component
struct CustomContainer {
  @Prop header: string;
  @BuilderParam closer: () => void

  build() {
    Column() {
      Text(this.header)
        .fontSize(30)
      this.closer()
    }
  }
}

@Builder function specificParam(label1: string, label2: string) {
  Column() {
    Text(label1)
      .fontSize(30)
    Text(label2)
      .fontSize(30)
  }
}

@Entry
@Component
struct CustomContainerUser {
  @State text: string = 'header';

  build() {
    Column() {
      // 创建CustomContainer，在创建CustomContainer时，通过其后紧跟一个大括号“{}”形成尾随闭包
      // 作为传递给子组件CustomContainer @BuilderParam closer: () => void的参数
      CustomContainer({ header: this.text }) {
        Column() {
          specificParam('testA', 'testB')
        }.backgroundColor(Color.Yellow)
        .onClick(() => {
          this.text = 'changeHeader';
        })
      }
    }
  }
}