鸿蒙Next组件扩展全面解析：从构建函数到样式复用的完整指南

1 组件扩展概述

鸿蒙操作系统（HarmonyOS）的ArkUI框架提供了一套强大的组件扩展机制，允许开发者通过装饰器（Decorator）来增强组件的功能和复用性。ArkTS作为HarmonyOS优选的主力应用开发语言，在TypeScript生态基础上做了进一步扩展，提供了声明式UI描述、状态管理和渲染控制等能力。组件扩展机制让我们能够将UI元素和业务逻辑封装成可复用的单元，从而提高代码的可维护性和开发效率。

在ArkUI中，组件扩展主要通过各种装饰器来实现，每个装饰器都有其特定的用途和应用场景。这些装饰器可以分为以下几类：构建函数装饰器（如@Builder、@LocalBuilder、@BuilderParam）、样式装饰器（如@Styles、@Extend、stateStyles）、功能增强装饰器（如@AnimatableExtend、@Require、@Reusable）等。通过合理使用这些装饰器，开发者可以构建出结构清晰、维护方便的高质量应用程序。

表：鸿蒙Next组件扩展主要装饰器概览

装饰器类型	装饰器名称	主要功能	适用场景
构建函数	@Builder	自定义构建函数，复用UI元素	需要复用UI结构但不形成独立组件的场景
构建函数	@LocalBuilder	维持组件父子关系的构建函数	需要保持状态管理一致性的组件内部使用
构建函数	@BuilderParam	引用@Builder函数，类似slot占位符	自定义组件需要外部传入UI结构的场景
样式扩展	@Styles	定义组件重用样式	提取通用样式，提高样式代码复用性
样式扩展	@Extend	扩展原生组件样式	为特定组件类型添加扩展样式方法
样式扩展	stateStyles	多态样式	根据组件状态应用不同样式
功能增强	@AnimatableExtend	定义可动画属性	扩展组件属性支持动画效果
功能增强	@Require	校验构造传参	确保自定义组件接收必要的参数
功能增强	@Reusable	组件复用	优化组件实例复用，提升性能

2 @Builder装饰器：自定义构建函数

2.1 基本概念与使用场景

@Builder装饰器是ArkUI提供的一种轻量级UI元素复用机制，它允许开发者将重复使用的UI元素抽象成一个方法，在build方法中调用。使用@Builder可以避免在多个地方编写重复的UI代码，提高代码的可读性和可维护性。与自定义组件不同，@Builder构建的函数内部UI结构固定，仅通过与使用方进行数据传递来实现一定程度的定制化。

@Builder装饰器可以在全局范围或组件内部定义，两种方式有不同的使用方式和作用域。全局@Builder可以在整个应用中使用，而局部@Builder仅限于所在组件内部使用。在实际开发中，应根据是否需要访问组件状态和数据来选择使用全局还是局部@Builder。

2.2 全局与局部定义方法

全局@Builder需要在函数前添加function关键字，并且不能访问组件内的状态变量。这种定义方式适合于那些不需要依赖组件状态的静态UI结构复用。

// 全局@Builder定义 @Builder function globalBuilder(title: string, content: string) { Row() { Text(title) Text('-------') Text(`这个${content}也不一样`) Blank() Text("查看更多-----") } .border({ width: 1, color: '#f00' }) .width('100%') } // 全局@Builder使用 @Entry @Component struct MyComponent { build() { Column() { globalBuilder('标题', '内容') } } }

局部@Builder不需要function关键字，可以直接在组件内部定义，并且能够访问组件的状态变量。这使得局部@Builder可以创建基于组件状态的动态UI结构。

// 局部@Builder定义与使用 @Component struct MyComponent { @State count: number = 0 // 局部@Builder定义 @Builder localBuilder() { Row() { Text(`计数: ${this.count}`) .fontSize(20) .fontColor(Color.Red) } } build() { Column() { // 局部@Builder使用 this.localBuilder() Button('增加计数') .onClick(() => { this.count++ }) } } }

2.3 参数传递规则

@Builder装饰器支持两种参数传递方式：按值传递和按引用传递。这两种方式都遵循以下规则：

• 参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式
• 在@Builder装饰的函数内部，不允许改变参数值
• @Builder内UI语法遵循UI语法规则

按值传递是默认的参数传递方式。当传递的参数为状态变量时，状态变量的改变不会引起@Builder方法内的UI刷新。这种方式适用于不需要响应数据变化的静态内容。

@Entry @Component struct ValuePassExample { @State value: string = '初始值' @Builder function valueBuilder(text: string) { Text(text) .fontSize(20) } build() { Column() { // 按值传递，不会响应value的变化 this.valueBuilder(this.value) Button('更新值') .onClick(() => { this.value = '新值' }) } } }

按引用传递需要通过特定的语法实现，当传递的参数为状态变量时，状态变量的改变会引起@Builder方法内的UI刷新。这种方式适用于需要响应数据变化的动态内容。

@Entry @Component struct RefPassExample { @State value: string = '初始值' @Builder function refBuilder($$: { text: string }) { Text($$.text) .fontSize(20) } build() { Column() { // 按引用传递，会响应value的变化 this.refBuilder({ text: this.value }) Button('更新值') .onClick(() => { this.value = '新值' }) } } }

2.4 最佳实践与常见应用场景

@Builder装饰器在实际开发中有多种应用场景，主要包括：

• 复用复杂UI结构：当多个地方需要用到相似的UI结构时，可以使用@Builder将UI结构提取出来，减少代码重复。
• 条件性渲染复杂UI：根据应用状态有条件地渲染复杂的UI结构时，使用@Builder可以使代码更加清晰。
• 分离大型组件：当组件过于庞大时，可以使用多个@Builder函数将组件拆分成更小的逻辑块，提高代码可读性。

需要注意的是，过度使用@Builder可能会导致组件结构分散，因此应合理评估使用场景。对于需要完全封装的独立功能单元，建议使用自定义组件而非@Builder。

3 @LocalBuilder装饰器：维持组件关系

3.1 产生背景与解决的问题

在ArkUI应用开发中，当使用@Builder进行引用数据传递时，如果使用了bind(this)来改变this指向，会导致组件的父子关系和状态管理的父子关系不一致。这种不一致性可能会引发状态管理上的问题，使组件行为变得不可预测。

@LocalBuilder装饰器从API version 12开始支持，旨在解决上述问题。它拥有和局部@Builder相同的功能，但能够更好地保持组件的父子关系和状态管理的父子关系的一致性。使用@LocalBuilder可以确保组件的层级结构和状态管理层级保持一致，使应用的行为更加 predictable。

3.2 与普通@Builder的区别

@LocalBuilder与普通@Builder在功能上相似，但在一些关键方面存在差异：

• this指向：@LocalBuilder不需要使用bind(this)来改变this指向，它的this始终指向当前所属组件
• 父子关系：@LocalBuilder能够保持组件父子关系和状态管理父子关系的一致性，而普通@Builder使用bind(this)后会破坏这种一致性
• 定义位置：@LocalBuilder只能在组件内部定义，不允许全局定义

class ReferenceType { paramString: string = ''; } @Entry @Component struct TestLocalBuilder { @State variableValue: string = 'Hello World'; // @LocalBuilder定义 @LocalBuilder citeLocalBuilder(params: ReferenceType) { Row() { Text(`UseStateVarByReference: ${params.paramString} `) } } build() { Column({ space: 10 }) { this.citeLocalBuilder({ paramString: this.variableValue }) Button('Click me') .onClick(() => { this.variableValue = 'Hi World'; }) } .padding(20) } }

3.3 使用限制与注意事项

使用@LocalBuilder装饰器时，需要了解以下限制条件：

• @LocalBuilder只能在所属组件内声明，不允许全局声明
• @LocalBuilder不能被内置装饰器和自定义装饰器使用
• 自定义组件内的静态方法不能和@LocalBuilder一起使用
• @LocalBuilder函数的参数传递有按值传递和按引用传递两种，都需要遵守特定规则

参数传递规则方面，@LocalBuilder与普通@Builder有相似之处，但也有一些特有规则：

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

3.4 实际应用示例

@LocalBuilder特别适用于需要在组件内部维护复杂UI结构，并且需要保持状态管理一致性的场景。以下是一个更复杂的示例，展示了@LocalBuilder如何用于构建可复用的UI部分：

// 自定义数据类型 class UserInfo { name: string = '' age: number = 0 avatar: string = '' } @Entry @Component struct UserProfile { @State user: UserInfo = { name: '张三', age: 25, avatar: 'user1.jpg' } @State isEditing: boolean = false // 使用@LocalBuilder构建用户头像组件 @LocalBuilder buildAvatar($$: UserInfo) { Column() { Image($$.avatar) .width(80) .height(80) .borderRadius(40) Text($$.name) .fontSize(16) .fontWeight(FontWeight.Bold) Text(`${$$.age}岁`) .fontSize(14) .opacity(0.6) } .alignItems(HorizontalAlign.Center) } // 使用@LocalBuilder构建编辑按钮 @LocalBuilder buildEditButton() { Button(this.isEditing ? '保存' : '编辑') .width(120) .margin(10) .onClick(() => { this.isEditing = !this.isEditing }) } build() { Column({ space: 10 }) { this.buildAvatar(this.user) this.buildEditButton() if (this.isEditing) { // 编辑表单元件 TextInput({ text: this.user.name }) .onChange((value) => { this.user.name = value }) .margin(5) TextInput({ text: this.user.age.toString() }) .onChange((value) => { this.user.age = parseInt(value) }) .margin(5) } } .padding(20) .width('100%') } }

在这个示例中，我们使用@LocalBuilder创建了两个可复用的UI部分：用户头像显示和编辑按钮。由于@LocalBuilder保持了正确的组件父子关系，状态管理（如isEditing状态）能够正常工作，确保了UI与状态的同步更新。

4 @BuilderParam装饰器：引用@Builder函数

4.1 基本概念与功能说明

@BuilderParam装饰器用于声明任意UI描述的一个元素，类似于其他UI框架中的slot占位符。它允许开发者在使用自定义组件时，向组件内部传递UI结构，极大地增强了组件的灵活性和可定制性。@BuilderParam装饰的方法只能被自定义构建函数（@Builder装饰的方法）初始化。

@BuilderParam的主要使用场景是当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。如果直接在组件内嵌入事件方法，会导致所有引入该自定义组件的地方均增加该功能。使用@BuilderParam可以在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能而不影响其他使用该组件的地方。

4.2 初始化方式与语法

@BuilderParam可以通过多种方式进行初始化，每种方式适用于不同的场景：

使用所属自定义组件的自定义构建函数或者全局的自定义构建函数在本地初始化@BuilderParam：

@Builder function globalBuilder() {} @Component struct Child { @Builder doNothingBuilder() {}; // 使用自定义组件的自定义构建函数初始化@BuilderParam @BuilderParam customBuilderParam: () => void = this.doNothingBuilder; // 使用全局自定义构建函数初始化@BuilderParam @BuilderParam customOverBuilderParam: () => void = globalBuilder; build(){} }

用父组件自定义构建函数初始化子组件@BuilderParam装饰的方法：

@Component struct Child { @BuilderParam customBuilderParam: () => void; build() { Column() { this.customBuilderParam() } } } @Entry @Component struct Parent { @Builder componentBuilder() { Text(`Parent builder `) } build() { Column() { Child({ customBuilderParam: this.componentBuilder }) } } }

4.3 尾随闭包初始化方式

在自定义组件中使用@BuilderParam装饰的属性时，可通过尾随闭包进行初始化。这种语法类似于SwiftUI和Flutter中的尾随闭包，使代码更加简洁易读。

使用尾随闭包初始化时，需要满足以下条件：

• 自定义组件内有且仅有一个使用@BuilderParam装饰的属性
• 自定义组件不支持使用通用属性

// 自定义组件定义 @Component struct CustomContainer { @Prop header: string = ''; @BuilderParam closer: () => void; build() { Column() { Text(this.header) .fontSize(30) this.closer() } } } // 使用尾随闭包初始化 @Entry @Component struct ContainerUser { @State text: string = 'header'; build() { Column() { // 创建CustomContainer，通过尾随闭包{}传入UI内容 CustomContainer({ header: this.text }) { Column() { Text('关闭按钮') .fontSize(20) .onClick(() => { this.text = '新标题'; }) } } } } }

4.4 参数传递与使用场景

@BuilderParam装饰的方法可以是有参数和无参数的两种形式，需与指向的@Builder方法类型匹配。@BuilderParam装饰的方法类型需要和@Builder方法类型一致。

无参数类型的@BuilderParam使用较为简单，适用于不需要传递数据的静态UI内容：

@Component struct Child { label: string = 'Child' @Builder customBuilder() {} // 无参数类型 @BuilderParam customBuilderParam: () => void = this.customBuilder; build() { Column() { this.customBuilderParam() } } }

有参数类型的@BuilderParam需要定义参数类型，适用于需要传递数据的动态UI内容：

class Tmp { label: string = '' } @Builder function globalBuilder($$: Tmp) { Text($$.label) .width(400) .height(50) .backgroundColor(Color.Green) } @Component struct Child { label: string = 'Child' // 有参数类型，指向的globalBuilder也是有参数类型的方法 @BuilderParam customOverBuilderParam: ($$: Tmp) => void = globalBuilder; build() { Column() { this.customOverBuilderParam({ label: 'global Builder label' }) } } }

4.5 this指向的正确处理

在使用@BuilderParam时，需要特别注意this指向的问题。开发者应谨慎使用bind改变函数调用的上下文，可能会使this指向混乱。

以下示例展示了this指向的处理方式：

@Component struct Child { label: string = `Child` @Builder customBuilder() {} @BuilderParam customBuilderParam: () => void = this.customBuilder; @BuilderParam customChangeThisBuilderParam: () => void = this.customBuilder; build() { Column() { this.customBuilderParam() this.customChangeThisBuilderParam() } } } @Entry @Component struct Parent { label: string = `Parent` @Builder componentBuilder() { Text(`${this.label}`) } build() { Column() { this.componentBuilder() Child({ customBuilderParam: this.componentBuilder, customChangeThisBuilderParam: (): void => { this.componentBuilder() } }) } } }

在这个示例中，Parent组件在调用this.componentBuilder()时，this指向其所属组件即"Parent"。当@Builder componentBuilder传给子组件@BuilderParam customBuilderParam时，在Child组件中调用this.customBuilderParam()时，this指向在Child的label，即"Child"。

5 @Styles与@Extend装饰器：样式重用与扩展

5.1 @Styles装饰器：定义组件重用样式

5.1.1 基本概念与使用规则

@Styles装饰器可以将多条样式设置提炼成一个方法，直接在组件声明的位置调用，通过这种方式快速定义并复用自定义样式。如果每个组件的样式都需要单独设置，会出现大量重复样式设置的代码，使用@Styles可以大大提高代码的简洁性和可维护性。

@Styles装饰器有以下使用规则：

• 当前@Styles仅支持通用属性和通用事件
• @Styles方法不支持参数
• @Styles可以定义在组件内或全局，在全局定义时需在方法名前面添加function关键字，组件内定义时则不需要添加function关键字
• 组件内@Styles的优先级高于全局@Styles，框架优先找当前组件内的@Styles，如果找不到，则会全局查找
• 定义在组件内的@Styles可以通过this访问组件的常量和状态变量，并可以在@Styles里通过事件来改变状态变量的值

5.1.2 全局样式与组件内样式

全局@Styles可以在整个应用程序中复用，适用于那些不依赖组件状态的通用样式：

// 定义在全局的@Styles封装的样式 @Styles function globalFancy () { .width(150) .height(100) .backgroundColor(Color.Pink) }

组件内@Styles可以访问组件的状态和常量，适用于需要根据组件状态动态变化的样式：

@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) } } }

5.1.3 限制条件与注意事项

使用@Styles装饰器时需要注意以下限制条件：

• @Styles方法不能有参数，编译期会报错
• 不支持在@Styles方法内使用逻辑组件，逻辑组件内的属性不生效
• 只能在当前文件内使用@Styles，不支持export。若需要实现样式导出，推荐使用AttributeModifier

5.2 @Extend装饰器：定义扩展组件样式

5.2.1 基本概念与语法规则

@Extend装饰器用于扩展原生组件样式，与@Styles不同，@Extend仅支持在全局定义，不支持在组件内部定义。@Extend支持封装指定组件的私有属性、私有事件和自身定义的全局方法，这使得它可以更深入地定制特定类型组件的样式。

@Extend装饰器的基本语法如下：

@Extend(UIComponentName) function functionName { ... }

其中，UIComponentName表示要扩展的组件类型，如Text、Button等。

5.2.2 与@Styles的区别

@Extend与@Styles主要有以下区别：

• @Extend仅支持在全局定义，而@Styles支持全局和组件内定义
• @Extend支持封装指定组件的私有属性、私有事件，而@Styles仅支持通用属性和通用事件
• @Extend装饰的方法支持参数，而@Styles方法不支持参数
• @Extend的参数可以为function，作为Event事件的句柄
• @Extend的参数可以为状态变量，当状态变量改变时，UI可以正常的被刷新渲染

5.2.3 参数传递与状态管理

@Extend装饰器支持参数传递，开发者可以在调用时传递参数，调用遵循TS方法传值调用。这使得@Extend可以创建更加灵活和动态的样式。

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

@Extend还支持参数为function，可以作为Event事件的句柄：

// 参数为函数的@Extend @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.bind(this)) } } }

5.2.4 使用场景与最佳实践

@Extend特别适用于以下场景：

• 为特定组件类型创建复用样式：例如，为Text组件创建一组预定义的文本样式
• 创建带参数的样式方法：根据需要动态调整样式属性
• 组合多个样式属性：将经常一起使用的样式属性组合在一起

以下是一个综合使用@Extend的示例：

// 定义扩展样式 @Extend(Text) function fancyText(weightValue: number, color: Color) { .fontStyle(FontStyle.Italic) .fontWeight(weightValue) .backgroundColor(color) .padding(10) .borderRadius(5) } @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%') } }

在这个示例中，我们使用@Extend创建了一个可复用的文本样式方法fancyText，它接受字重和颜色两个参数，应用于Text组件。这样大大简化了重复的样式代码，提高了代码的可维护性。

6 其他装饰器与扩展功能

6.1 wrapBuilder：封装全局@Builder

wrapBuilder提供了一种封装全局@Builder的方法，使其更容易在不同的组件和模块中使用。通过wrapBuilder，开发者可以创建更加模块化和可测试的UI组件。

wrapBuilder的使用方式类似于高阶函数，它接受一个@Builder函数作为参数，并返回一个增强版的@Builder函数。这种方式可以用于添加日志、性能监控、条件渲染等跨领域功能。

// 封装全局@Builder示例 function wrapBuilder(originalBuilder: () => void) { return () => { console.log('Builder执行时间:', new Date().toISOString()); originalBuilder(); }; } @Builder function originalBuilder() { Text('原始Builder内容') .fontSize(20) } // 使用wrapBuilder封装 const wrappedBuilder = wrapBuilder(originalBuilder); @Entry @Component struct WrappedExample { build() { Column() { // 使用封装后的Builder wrappedBuilder() } } }

6.2 stateStyles：多态样式

stateStyles允许开发者根据组件的不同状态应用不同的样式。这对于创建交互式UI元素非常有用，如按钮在按下、禁用、聚焦等状态下显示不同的样式。

stateStyles使用语法类似于CSS中的伪类选择器，可以根据组件的状态自动切换样式：

@Entry @Component struct StateStylesExample { @State isPressed: boolean = false build() { Column() { Button('点击我') .stateStyles({ normal: { .backgroundColor(Color.Blue) .fontColor(Color.White) }, pressed: { .backgroundColor(Color.Red) .fontColor(Color.White) } }) .onClick(() => { this.isPressed = !this.isPressed }) } } }

6.3 @AnimatableExtend装饰器：定义可动画属性

@AnimatableExtend装饰器用于定义可动画属性，允许开发者创建自定义动画效果。通过@AnimatableExtend，可以为组件属性添加动画能力，使其能够平滑过渡 between values。

@AnimatableExtend(Text) function animatableFontSize(size: number) { .fontSize(size) } @Entry @Component struct AnimatableExample { @State fontSize: number = 20 build() { Column() { Text('动画文字') .animatableFontSize(this.fontSize) .animation({ duration: 1000, curve: Curve.EaseInOut }) Button('增大字体') .onClick(() => { this.fontSize += 10 }) } } }

6.4 @Require装饰器：校验构造传参

@Require装饰器用于校验构造传参，确保自定义组件接收必要的参数。当缺少必需参数时，开发期或运行时会给出警告或错误信息。

@Component struct RequiredExample { @Require label: string build() { Text(this.label) .fontSize(20) } } @Entry @Component struct ParentComponent { build() { Column() { // 必须传递label参数，否则会报错 RequiredExample({ label: '必传参数' }) } } }

6.5 @Reusable装饰器：组件复用

@Reusable装饰器用于标识组件可被复用，优化组件实例复用，提升性能。使用@Reusable装饰的组件会被框架缓存和重用，减少组件创建和销毁的开销。

@Reusable @Component struct ReusableExample { @Prop message: string build() { Text(this.message) .fontSize(20) .backgroundColor(Color.Gray) } } @Entry @Component struct ReusableUser { @State messages: string[] = ['消息1', '消息2', '消息3'] build() { List() { ForEach(this.messages, (item: string) => { ListItem() { ReusableExample({ message: item }) } }) } } }

7 总结与最佳实践

通过本文的详细讲解，我们全面了解了鸿蒙Next平台中ArkUI框架提供的各种组件扩展装饰器。这些装饰器各具特色，适用于不同的场景：

• @Builder：适用于UI结构的复用，特别是需要在多个地方使用相同UI结构但又不适合做成独立组件的场景
• @LocalBuilder：解决了组件父子关系和状态管理一致性問題，适用于组件内部复杂UI结构的构建
• @BuilderParam：增强了组件的灵活性和可定制性，允许从外部传入UI结构
• @Styles：用于样式代码的复用，提高样式的一致性和可维护性
• @Extend：扩展了原生组件的能力，可以创建组件特定的样式方法

在实际开发中，我们应该根据具体需求选择合适的装饰器。以下是一些最佳实践建议：

1. 保持简洁：不要过度使用装饰器，特别是对于简单的UI和样式，直接使用组件和属性可能更清晰
2. 考虑性能：对于频繁使用的UI元素，使用@Builder和@Reusable可以提高性能
3. 保持一致性：在项目中建立统一的装饰器使用规范，保持代码风格一致
4. 测试不同场景：在真实设备上测试使用各种装饰器的组件，确保在不同条件下的正确性

鸿蒙Next的ArkUI框架提供了强大的组件扩展能力，通过合理使用这些装饰器，我们可以构建出更加灵活、可维护和高性能的应用程序。随着鸿蒙生态的不断发展，这些功能也将进一步完善和增强，为开发者提供更好的开发体验。