关于鸿蒙开发中装饰器@Extend、@Styles、@Builder的介绍

总结

名称	适合	是否可以参数
@Extend	抽取特定组件样式、事件	√
@Styles	抽取公共样式、事件	×
@Builder	抽取结构、样式、事件	√

@Extend

语法：

@Extend(要扩展的组件，例如Text、Column、Row等) function functionName { ... }

使用规则：

1、@Extend仅支持在全局定义，不支持在组件内部定义。

2、@Extend支持封装指定组件的私有属性、私有事件和自身定义的全局方法

// @Extend(Text)可以支持Text的私有属性fontColor
@Extend(Text) function fancy () {.fontColor(Color.Red)
}
// superFancyText可以调用预定义的fancy
@Extend(Text) function superFancyText(size:number) {.fontSize(size).fancy()
}

3、@Extend装饰的方法支持参数，开发者可以在调用时传递参数，调用遵循TS方法传值调用。

@Extend(Text) function fancy (fontSize: number) {.fontColor(Color.Red).fontSize(fontSize)
}@Entry
@Component
struct FancyUse {build() {Row({ space: 10 }) {Text('Fancy').fancy(16)Text('Fancy').fancy(24)}}
}

4、@Extend装饰的方法的参数可以为function，作为Event事件的句柄。

@Extend(Text) function makeMeClick(onClick: () => void) {.backgroundColor(Color.Blue).onClick(onClick)
}@Entry
@Component
struct FancyUse {@State label: string = 'Hello World';onClickHandler() {this.label = 'Hello ArkUI';}build() {Row({ space: 10 }) {Text(`${this.label}`).makeMeClick(() => {this.onClickHandler()})}}
}

5、@Extend的参数可以为状态变量，当状态变量改变时，UI可以正常的被刷新渲染。

@Extend(Text) function fancy (fontSize: number) {.fontColor(Color.Red).fontSize(fontSize)
}@Entry
@Component
struct FancyUse {@State fontSizeValue: number = 20build() {Row({ space: 10 }) {Text('Fancy').fancy(this.fontSizeValue).onClick(() => {this.fontSizeValue = 30})}}
}

使用场景

以下示例声明了3个Text组件，每个Text组件均设置了fontStyle、fontWeight和backgroundColor样式。

@Entry
@Component
struct FancyUse {@State label: string = 'Hello World'build() {Row({ space: 10 }) {Text(`${this.label}`).fontStyle(FontStyle.Italic).fontWeight(100).backgroundColor(Color.Blue)Text(`${this.label}`).fontStyle(FontStyle.Italic).fontWeight(200).backgroundColor(Color.Pink)Text(`${this.label}`).fontStyle(FontStyle.Italic).fontWeight(300).backgroundColor(Color.Orange)}.margin('20%')}
}

@Extend将样式组合复用，示例如下。

@Extend(Text) function fancyText(weightValue: number, color: Color) {.fontStyle(FontStyle.Italic).fontWeight(weightValue).backgroundColor(color)
}

通过@Extend组合样式后，使得代码更加简洁，增强可读性。

@Entry
@Component
struct FancyUse {@State label: string = 'Hello World'build() {Row({ space: 10 }) {Text(`${this.label}`).fancyText(100, Color.Blue)Text(`${this.label}`).fancyText(200, Color.Pink)Text(`${this.label}`).fancyText(300, Color.Orange)}.margin('20%')}
}

@Styles

说明

1、当前@Styles仅支持通用属性和通用事件。

2、@Styles可以定义在组件内或全局，在全局定义时需在方法名前面添加function关键字，组件内定义时则不需要添加function关键字。

// 全局
@Styles function functionName() { ... }// 在组件内
@Component
struct FancyUse {@Styles fancy() {.height(100)}
}

3、定义在组件内的@Styles可以通过this访问组件的常量和状态变量，并可以在@Styles里通过事件来改变状态变量的值，示例如下：

@Component
struct FancyUse {@State heightValue: number = 100@Styles fancy() {.height(this.heightValue).backgroundColor(Color.Yellow).onClick(() => {this.heightValue = 200})}
}

4、组件内@Styles的优先级高于全局@Styles。

使用场景

// 定义在全局的@Styles封装的样式
@Styles function globalFancy  () {.width(150).height(100).backgroundColor(Color.Pink)
}@Entry
@Component
struct FancyUse {@State heightValue: number = 100// 定义在组件内的@Styles封装的样式@Styles fancy() {.width(200).height(this.heightValue).backgroundColor(Color.Yellow).onClick(() => {this.heightValue = 200})}build() {Column({ space: 10 }) {// 使用全局的@Styles封装的样式Text('FancyA').globalFancy().fontSize(30)// 使用组件内的@Styles封装的样式Text('FancyB').fancy().fontSize(30)}}
}

@Builder

限制条件

@Builder通过按引用传递的方式传入参数，才会触发动态渲染UI，并且参数只能是一个。
@Builder如果传入的参数是两个或两个以上，不会触发动态渲染UI。
@Builder传入的参数中同时包含按值传递和按引用传递两种方式，不会触发动态渲染UI。
@Builder的参数必须按照对象字面量的形式，把所需要的属性一一传入，才会触发动态渲染UI。

私有自定义构建函数

语法：

@Builder MyBuilderFunction() {}

使用：

this.MyBuilderFunction()

说明：

允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。

自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。

在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。

全局自定义构建函数

语法：

@Builder function MyGlobalBuilderFunction() { ... }

使用：

MyGlobalBuilderFunction()

说明：

如果不涉及组件状态变化，建议使用全局的自定义构建方法。

参数传递规则

自定义构建函数测参数传递有按值传递和按引用传递两种，均需遵守以下规则：

参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式。
在@Builder修饰的函数内部，不允许改变参数值。
@Builder内UI语法遵循UI语法规则。
只有传入一个参数，且参数需要直接传入对象字面量才会按引用传递该参数，其余传递方式均为按值传递。

按引用传递参数

按引用传递参数时，传递的参数可为状态变量，且状态变量的改变会引起@Builder方法内的UI刷新。

class Tmp {paramA1: string = ''
}@Builder function overBuilder(params: Tmp) {Row() {Text(`UseStateVarByReference: ${params.paramA1} `)}
}
@Entry
@Component
struct Parent {@State label: string = 'Hello';build() {Column() {overBuilder({ paramA1: this.label })Button('Click me').onClick(() => {this.label = 'ArkUI';})}}
}

按引用传递参数时，如果在@Builder方法内调用自定义组件，ArkUI提供$$作为按引用传递参数的范式。

class Tmp {paramA1: string = ''
}@Builder function overBuilder($$: Tmp) {Row() {Column() {Text(`overBuilder===${$$.paramA1}`)HelloComponent({message: $$.paramA1})}}
}@Component
struct HelloComponent {@Prop message: string;build() {Row() {Text(`HelloComponent===${this.message}`)}}
}@Entry
@Component
struct Parent {@State label: string = 'Hello';build() {Column() {overBuilder({paramA1: this.label})Button('Click me').onClick(() => {this.label = 'ArkUI';})}}
}

按值传递参数

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

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

使用场景

自定义组件内使用自定义构建函数

创建私有的@Builder方法，在Column里面使用this.builder()方式调用，通过aboutToAppear生命周期函数和按钮的点击事件改变builder_value的内容，实现动态渲染UI。

@Entry
@Component
struct PrivateBuilder {@State builder_value: string = 'Hello';@Builder builder() {Column(){Text(this.builder_value).fontSize(30).fontWeight(FontWeight.Bold)}}aboutToAppear(): void {setTimeout(() => {this.builder_value = 'Hello World';},3000)}build() {Row() {Column() {Text(this.builder_value).fontSize(30).fontWeight(FontWeight.Bold)this.builder()Button('点击改变builder_value内容').onClick(() => {this.builder_value ='builder_value被点击了'})}}}
}

使用全局自定义构建函数

创建全局的@Builder方法，在Column里面使用overBuilder()方式调用，通过以对象字面量的形式传递参数，无论是简单类型还是复杂类型，值的改变都会引起UI界面的刷新。

class ChildTmp {val: number = 1;
}class Tmp {str_value: string = 'Hello';num_value: number = 0;tmp_value: ChildTmp = new ChildTmp();arrayTmp_value: Array<ChildTmp> = [];
}@Builder function overBuilder(param: Tmp) {Column() {Text(`str_value: ${param.str_value}`)Text(`num_value: ${param.num_value}`)Text(`tmp_value: ${param.tmp_value.val}`)ForEach(param.arrayTmp_value, (item: ChildTmp) => {Text(`arrayTmp_value: ${item.val}`)}, (item: ChildTmp) => JSON.stringify(item))}
}@Entry
@Component
struct Parent {@State objParam: Tmp = new Tmp();build() {Column() {Text('通过调用@Builder渲染UI界面').fontSize(20)overBuilder({str_value: this.objParam.str_value, num_value: this.objParam.num_value, tmp_value: this.objParam.tmp_value, arrayTmp_value: this.objParam.arrayTmp_value})Line().width('100%').height(10).backgroundColor('#000000').margin(10)Button('点击改变参数值').onClick(() => {this.objParam.str_value = 'Hello World';this.objParam.num_value = 1;this.objParam.tmp_value.val = 8;const child_value: ChildTmp = {val: 2}this.objParam.arrayTmp_value.push(child_value)})}}
}

修改装饰器修饰的变量触发UI刷新

此种方式是使用了装饰器的特性，监听值的改变触发UI刷新，不通过@Builder传递参数。

class Tmp {str_value: string = 'Hello';
}@Entry
@Component
struct Parent {@State objParam: Tmp = new Tmp();@State label: string = 'World';@Builder privateBuilder() {Column() {Text(`wrapBuilder str_value: ${this.objParam.str_value}`)Text(`wrapBuilder num: ${this.label}`)}}build() {Column() {Text('通过调用@Builder渲染UI界面').fontSize(20)this.privateBuilder()Line().width('100%').height(10).backgroundColor('#000000').margin(10)Button('点击改变参数值').onClick(() => {this.objParam.str_value = 'str_value Hello World';this.label = 'label Hello World'})}}
}

使用全局和局部的@Builder传入customBuilder类型

@Builder
function overBuilder() {Row() {Text('全局 Builder').fontSize(30).fontWeight(FontWeight.Bold)}
}@Entry
@Component
struct customBuilderDemo {@State arr: number[] = [0, 1, 2, 3, 4];@Builder privateBuilder() {Row() {Text('局部 Builder').fontSize(30).fontWeight(FontWeight.Bold)}}build() {Column() {List({ space: 10 }) {ForEach(this.arr, (item: number) => {ListItem(){Text(`${item}`).width('100%').height(100).fontSize(16).textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)}.swipeAction({start: {builder: overBuilder()},end: {builder: () => { this.privateBuilder() }}})}, (item: string) => JSON.stringify(item))}}}
}

多层@Builder方法嵌套使用

在@Builder方法内调用自定义组件或者其他@Builder方法，ArkUI提供$$作为按引用传递参数的范式。

class Tmp {paramA1: string = '';
}@Builder function parentBuilder($$: Tmp) {Row() {Column() {Text(`parentBuilder===${$$.paramA1}`).fontSize(30).fontWeight(FontWeight.Bold)HelloComponent({message: $$.paramA1})childBuilder({paramA1: $$.paramA1})}}
}@Component
struct HelloComponent {@Prop message: string = '';build() {Row() {Text(`HelloComponent===${this.message}`).fontSize(30).fontWeight(FontWeight.Bold)}}
}@Builder
function childBuilder($$: Tmp) {Row() {Column() {Text(`childBuilder===${$$.paramA1}`).fontSize(30).fontWeight(FontWeight.Bold)HelloChildComponent({message: $$.paramA1})grandsonBuilder({paramA1: $$.paramA1})}}
}@Component
struct HelloChildComponent {@State message: string = '';build() {Row() {Text(`HelloChildComponent===${this.message}`).fontSize(30).fontWeight(FontWeight.Bold)}}
}@Builder function grandsonBuilder($$: Tmp) {Row() {Column() {Text(`grandsonBuilder===${$$.paramA1}`).fontSize(30).fontWeight(FontWeight.Bold)HelloGrandsonComponent({message: $$.paramA1})}}
}@Component
struct HelloGrandsonComponent {@Prop message: string;build() {Row() {Text(`HelloGrandsonComponent===${this.message}`).fontSize(30).fontWeight(FontWeight.Bold)}}
}@Entry
@Component
struct Parent {@State label: string = 'Hello';build() {Column() {parentBuilder({paramA1: this.label})Button('Click me').onClick(() => {this.label = 'ArkUI';})}}
}