Builder装饰器自定义构建函数前面章节介绍了如何创建一个自定义组件。该自定义组件内部UI结构固定仅与使用方进行数据传递。ArkUI还提供了一种更轻量的UI元素复用机制BuilderBuilder所装饰的函数遵循build()函数语法规则开发者可以将重复使用的UI元素抽象成一个方法在build方法里调用。为了简化语言我们将Builder装饰的函数也称为“自定义构建函数”。说明从API version 9开始该装饰器支持在ArkTS卡片中使用。装饰器使用说明自定义组件内自定义构建函数定义的语法Builder MyBuilderFunction(){ ... }使用方法this.MyBuilderFunction(){ ... }允许在自定义组件内定义一个或多个Builder方法该方法被认为是该组件的私有、特殊类型的成员函数。自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用但不允许在组件外调用。在自定义函数体中this指代当前所属组件组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。全局自定义构建函数定义的语法Builder function MyGlobalBuilderFunction(){ ... }使用方法MyGlobalBuilderFunction()全局的自定义构建函数可以被整个应用获取不允许使用this和bind方法。如果不涉及组件状态变化建议使用全局的自定义构建方法。参数传递规则自定义构建函数的参数传递有按值传递和按引用传递两种均需遵守以下规则参数的类型必须与参数声明的类型一致不允许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} ) }}EntryComponentstruct 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} ) }}EntryComponentstruct Parent { label: string Hello; build() { Column() { ABuilder(this.label) } }}BuilderParam装饰器引用Builder函数当开发者创建了自定义组件并想对该组件添加特定功能时例如在自定义组件中添加一个点击跳转操作。若直接在组件内嵌入事件方法将会导致所有引入该自定义组件的地方均增加了该功能。为解决此问题ArkUI引入了BuilderParam装饰器BuilderParam用来装饰指向Builder方法的变量开发者可在初始化自定义组件时对此属性进行赋值为自定义组件增加特定的功能。该装饰器用于声明任意UI描述的一个元素类似slot占位符。说明从API version 9开始该装饰器支持在ArkTS卡片中使用。装饰器使用说明初始化BuilderParam装饰的方法BuilderParam装饰的方法只能被自定义构建函数Builder装饰的方法初始化。使用所属自定义组件的自定义构建函数或者全局的自定义构建函数在本地初始化BuilderParam。Builder function GlobalBuilder0() {} Componentstruct Child { Builder doNothingBuilder() {}; BuilderParam aBuilder0: () void this.doNothingBuilder; BuilderParam aBuilder1: () void GlobalBuilder0; build(){}}用父组件自定义构建函数初始化子组件BuilderParam装饰的方法。Componentstruct Child { BuilderParam aBuilder0: () void; build() { Column() { this.aBuilder0() } }} EntryComponentstruct Parent { Builder componentBuilder() { Text(Parent builder ) } build() { Column() { Child({ aBuilder0: this.componentBuilder }) } }}需注意this指向正确。以下示例中Parent组件在调用this.componentBuilder()时this指向其所属组件即“Parent”。Builder componentBuilder()传给子组件BuilderParam aBuilder0在Child组件中调用this.aBuilder0()时this指向在Child的label即“Child”。说明开发者谨慎使用bind改变函数调用的上下文可能会使this指向混乱。Componentstruct Child { label: string Child BuilderParam aBuilder0: () void; build() { Column() { this.aBuilder0() } }} EntryComponentstruct Parent { label: string Parent Builder componentBuilder() { Text(${this.label}) } build() { Column() { this.componentBuilder() Child({ aBuilder0: this.componentBuilder }) } }}使用场景参数初始化组件BuilderParam装饰的方法可以是有参数和无参数的两种形式需与指向的Builder方法类型匹配。BuilderParam装饰的方法类型需要和Builder方法类型一致。Builder function GlobalBuilder1($$ : {label: string }) { Text($$.label) .width(400) .height(50) .backgroundColor(Color.Green)} Componentstruct Child { label: string Child // 无参数类指向的componentBuilder也是无参数类型 BuilderParam aBuilder0: () void; // 有参数类型指向的GlobalBuilder1也是有参数类型的方法 BuilderParam aBuilder1: ($$ : { label : string}) void; build() { Column() { this.aBuilder0() this.aBuilder1({label: global Builder label } ) } }} EntryComponentstruct Parent { label: string Parent Builder componentBuilder() { Text(${this.label}) } build() { Column() { this.componentBuilder() Child({ aBuilder0: this.componentBuilder, aBuilder1: GlobalBuilder1 }) } }}尾随闭包初始化组件在自定义组件中使用BuilderParam装饰的属性时也可通过尾随闭包进行初始化。在初始化自定义组件时组件后紧跟一个大括号“{}”形成尾随闭包场景。说明此场景下自定义组件内有且仅有一个使用BuilderParam装饰的属性。开发者可以将尾随闭包内的内容看做Builder装饰的函数传给BuilderParam。示例如下// xxx.etsComponentstruct 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) }} EntryComponentstruct 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; }) } } }}最后这里整理了一份《鸿蒙零基础入门学习指南》希望能对那些想要学习鸿蒙但是有没有方向的人提供一点帮助。本文档适用于HarmonyOS应用开发的初学者由于文档内容过多因此为了避免影响到大家的阅读体验在此只以截图展示部分内容详细完整版的看文末有免费的获取方式《鸿蒙零基础入门学习指南》目录一、快速入门适用于HarmonyOS应用开发的初学者。通过构建一个简单的具有页面跳转/返回功能的应用快速了解工程目录的主要文件熟悉HarmonyOS应用开发流程。开发准备基本概念工具准备构建第一个ArkTS应用Stage模型构建第一个ArkTS应用FA模型构建第一个JS应用FA模型二、开发基础知识应用程序包基础知识应用程序包概述应用程序包结构应用程序包多HAP机制应用程序包安装和卸载流程应用程序包更新流程共享包应用程序包快速修复应用配置文件Stage模型应用配置文件概述Stage模型app.json5配置文件module.json5配置文件应用配置文件概述FA模型应用配置文件概述FA模型app对象内部结构deviceConfig内部结构module对象内部结构三、资源分类与访问应用开发过程中经常需要用到颜色、字体、间距、图片等资源在不同的设备或配置中这些资源的值可能不同。资源分类与访问资源分类资源目录资源组目录创建资源目录和资源文件创建资源目录和资源文件创建资源目录创建资源文件资源访问应用资源系统资源资源匹配四、学习ArkTs语言ArkTS是HarmonyOS优选的主力应用开发语言。ArkTS围绕应用开发在TypeScript简称TS生态基础上做了进一步扩展继承了TS的所有特性是TS的超集。因此在学习ArkTS语言之前建议开发者具备TS语言开发能力。初识ArkTS语言基本语法基本语法概述声明式UI描述自定义组件状态管理其他状态管理其他状态管理概述Watch装饰器状态变量更改通知$$语法内置组件双向同步渲染控制渲染控制概述if/else条件渲染ForEach循环渲染LazyForEach数据懒加载扫描下方二维码免费领取《鸿蒙5.0零基础入门学习指南》|