鸿蒙应用开发 @Builder 使用教程：从入门到精通

文章目录一、引言二、Builder 装饰器简介主要特点三、基础用法3.1 组件内 Builder私有3.2 全局 Builder四、参数传递按值传递 vs 按引用传递4.1 按值传递默认4.2 按引用传递响应外部变化五、高级用法与最佳实践5.1 在 Builder 中使用循环5.2 嵌套 Builder5.3 与 Prop 和 Link 配合六、注意事项七、总结一、引言在 HarmonyOS 应用开发中UI 代码的复用性是提升开发效率和代码可维护性的关键。ArkTS 作为鸿蒙的声明式开发语言提供了Builder装饰器专门用于构建可复用的 UI 片段。本文将深入浅出地介绍Builder的核心概念、使用场景、参数传递机制以及最佳实践帮助你彻底掌握这一重要工具。二、Builder 装饰器简介Builder是 ArkTSHarmonyOS 5.0.0中用于构建可复用 UI 片段的核心装饰器。它允许开发者将重复的 UI 结构抽象为独立的函数提升代码的模块化和可维护性。Builder装饰的函数称为“自定义构建函数”遵循 ArkUI 的build()函数语法规则用于返回一组 UI 描述。主要特点复用性封装重复的 UI 结构避免代码冗余。灵活性可在组件内部定义私有或全局定义跨组件使用。与组件关系Builder通常用于 UI 片段的复用而Component用于定义完整的、带有独立状态和生命周期的自定义组件。三、基础用法3.1 组件内 Builder私有在自定义组件内部定义仅在该组件内可调用能够通过this访问组件的状态变量。Componentstruct MyComponent{Statecount:number0;BuilderItemBuilder(text:string){Text(text).padding(10).backgroundColor(0xeeeeee)}build(){Column(){this.ItemBuilder(条目1)this.ItemBuilder(条目2)}}}3.2 全局 Builder在模块级别定义可在整个应用内调用但不允许使用this因此不适合依赖组件状态的场景。BuilderfunctionGlobalBuilder(param:string){Text(param).fontSize(16)}Componentstruct MyComponent{build(){Column(){GlobalBuilder(全局构建函数)}}}四、参数传递按值传递 vs 按引用传递这是Builder使用中最关键的概念理解不当会导致 UI 不刷新的问题。4.1 按值传递默认传递的参数在Builder内部是值的拷贝外部状态变化不会触发Builder内部的 UI 刷新。// 按值传递不响应外部变化BuilderfunctionValueBuilder(paramA1:string){Row(){Text(Builder - 按值传递:${paramA1}).fontSize(20)}}EntryComponentstruct Parent{Statelabel:stringHello;build(){Column({space:20}){ValueBuilder(this.label)// label 变化不会更新Divider()Text(label的值${this.label}).fontSize(20)Button(点击).width(80%).onClick((){this.labelArkUI})}.width(100%)}}运行效果4.2 按引用传递响应外部变化使用对象字面量传递参数当状态变量变化时Builder内部的 UI 会同步刷新。Builder按引用传递的核心规则是必须且只能传入一个参数且该参数必须是一个对象字面量。以下是具体的实现步骤和示例定义一个类或接口用于封装需要传递的参数。在Builder函数中将参数类型指定为该类或接口。在调用Builder时使用对象字面量 { 属性名: 状态变量 }的形式传入。// 1. 定义一个类用于封装参数classTmp{param:string;}// 按引用传递响应外部变化// 2. 定义全局 Builder 函数参数类型为 TmpBuilderfunctionRefBuilder(tmp:Tmp){Row(){Text(Builder - 按引用传递:${tmp.param}).fontSize(20)}}EntryComponentstruct ReferencePassingExample{Statelabel:stringHello;build(){Column({space:20}){// 3. 调用时使用对象字面量形式传入状态变量RefBuilder({param:this.label})Divider()Text(label的值${this.label}).fontSize(20)Button(改变值).width(80%).onClick((){this.labelArkUI;// 修改状态变量会触发 Builder 内 UI 刷新})}.width(100%)}}运行效果关键点与常见错误必须使用对象字面量{ param: this.myParam }这种形式是触发按引用传递的必要条件。只能传入一个参数如果Builder函数需要多个值必须将它们封装到同一个对象中如上面的Tmp类不能写成RefBuilder({ param: this.myParam }, 12)。不能使用new构造对象RefBuilder(new Tmp(this.myParam))这种方式会变成按值传递UI 不会刷新。不能直接传字符串RefBuilder(this.myParam)是典型的按值传递UI 不会刷新。禁止修改参数值在Builder函数内部不允许修改传入的参数如tmp.param new否则会抛出运行时错误。BuilderfunctionRefBuilder(tmp:Tmp){Row(){Text(Builder - 按引用传递:${tmp.param}).fontSize(20).onClick((){tmp.paramnew;})}}运行效果注意按值传递时修改参数值不会报错BuilderfunctionValueBuilder(paramA1:string){Row(){Text(Builder - 按值传递:${paramA1}).fontSize(20).onClick((){paramA1Worldconsole.log(修改后的值为${paramA1})})}}运行效果五、高级用法与最佳实践5.1 在 Builder 中使用循环结合ForEach可以动态生成多个 UI 片段。BuilderfunctionListBuilder(items:string[]){Column(){ForEach(items,(item:string){Text(item).padding(8).width(100%)})}}5.2 嵌套 BuilderBuilder函数内部可以调用其他Builder函数实现更细粒度的复用。BuilderfunctionHeaderBuilder(title:string){Text(title).fontSize(20).fontWeight(FontWeight.Bold)}BuilderfunctionCardBuilder(title:string,content:string){Column(){HeaderBuilder(title)Text(content).fontSize(14)}.padding(16).backgroundColor(0xffffff).borderRadius(8)}5.3 与 Prop 和 Link 配合在组件内Builder中可以直接使用this访问组件的State、Prop、Link等装饰器修饰的变量。Componentstruct ChildComponent{Propmessage:string;BuilderMessageBuilder(){Text(this.message).fontColor(Color.Blue)}build(){Column(){this.MessageBuilder()}}}六、注意事项参数传递机制若Builder需要响应状态变化务必使用按引用传递封装为对象。直接传递基本类型如number、string会导致 UI 不更新。作用域选择仅在单个组件内复用的 UI 使用组件内Builder无状态、全局复用的 UI 使用全局Builder。避免滥用Builder适合静态或简单动态 UI 片段对于具有独立生命周期或复杂逻辑的 UI应使用Component。参数不可变在Builder函数内部不要修改参数值ArkTS 强制约束如需双向同步考虑使用Link装饰器。性能考量按引用传递可能引起更多 UI 刷新合理设计参数结构以避免不必要的重绘。七、总结Builder是 ArkUI 声明式开发范式中提升 UI 复用性的重要工具。正确理解其参数传递机制按值 vs 按引用是避免 UI 更新问题的关键。在开发中根据场景灵活选择Builder与Component能够构建出既高效又易维护的 HarmonyOS 应用界面。