声明式 UI 构建范式——ArkTS 的 Builder 装饰器深入引言在 HarmonyOS 的 ArkTS 声明式 UI 框架中Builder装饰器是一个极其重要的构建工具。它允许开发者将 UI 片段封装为可复用的构建函数从而避免在build()方法中编写臃肿的嵌套代码。本文将通过我们英语学习 App 的实际源码深入剖析Builder的四种使用场景组件内 Builder、全局 Builder、参数传递、以及导出复用。一、Builder 的基本概念Builder是 ArkTS 提供的 UI 构建函数装饰器它的核心特性有封装 UI 片段将一个独立的 UI 区块封装成一个函数在build()中直接调用支持两种定义位置组件内部定义为成员方法或组件外部定义为全局函数支持参数传递可以通过参数向 Builder 传入数据具备响应式能力Builder 内部引用组件的Local/Param变量时变化会自动触发重绘在我们的MainPage.ets中总共使用了 6 个Builder来组织首页的各个 UI 区块形成了一套清晰的 UI 分层结构HomePage (主组件) ├── topBarBuilder() — 顶部导航栏 ├── todayStudyBuilder() — 今日学习卡片 ├── swiperBuilder() — 轮播 Banner ├── functionBarBuilder() — 5 宫格功能栏 ├── practiceModeBuilder() — 2×2 练习模式 └── subjectPracticeBuilder() — 学习进度区二、组件内 Builder2.1 基础用法组件内的Builder方法可以直接访问当前组件的所有属性和状态变量。以下是我们HomePage中的topBarBuilder()ComponentV2exportstruct HomePage{// ...build(){Column(){// 直接调用 Builderthis.topBarBuilder();Scroll(){Column({space:10}){this.todayStudyBuilder();this.swiperBuilder();this.functionBarBuilder();this.practiceModeBuilder();this.subjectPracticeBuilder();}}// ...}}BuildertopBarBuilder(){Row(){Text(英语学习).fontSize(20).fontWeight(FontWeight.Bold).layoutWeight(1);Image($r(app.media.ic_practice_camera)).width(28).height(28).onClick((){RouterModule.push({url:RouterMap.SEARCH_INPUT_PAGE});});}.width(100%).height(56).padding({left:4,right:4});}// ...}关键点解析Builder 内部直接使用this.functions、this.dataSource等组件状态变量调用时只需写this.topBarBuilder()无需传递任何参数Builder 内引用的状态变量变化时Builder 会自动触发重新渲染2.2 访问组件状态的典型示例todayStudyBuilder()展示了如何通过 Builder 读取组件数据并渲染 UIBuildertodayStudyBuilder(){Column(){Row(){Text(今日学习).fontSize(16).fontWeight(FontWeight.Medium);Text(坚持 7 天).fontSize(12).fontColor($r(sys.color.font_secondary)).layoutWeight(1).textAlign(TextAlign.End);}.width(100%).margin({bottom:8});Row(){Text(已学 15 词 / 目标 30 词).fontSize(13).fontColor($r(sys.color.font_secondary)).layoutWeight(1);Text(50%).fontSize(20).fontWeight(FontWeight.Bold).fontColor($r(sys.color.comp_background_emphasize));}.width(100%).margin({bottom:8});Progress({value:15,total:30,type:ProgressType.Linear}).color($r(sys.color.comp_background_emphasize)).height(8).width(100%);}.padding(16).borderRadius(16).backgroundColor($r(sys.color.background_primary));}这个 Builder 封装了一个完整的学习进度卡片包含标题行、数据行和进度条形成了一个独立的视觉模块。三、全局 Builder当一个 Builder 需要被多个组件复用时可以将其定义在组件外部成为全局 Builder。3.1 全局 Builder 的定义在MainPage.ets的末尾我们定义了多个全局 Builder// 全局 Builder直接返回一个组件实例BuilderexportfunctionHomePageBuilder(){HomePage();}// 全局 Builder封装核心功能图标BuilderexportfunctionCourseCoreBuilder(mainFunctionItem:CourseCoreBar){Column(){Image(mainFunctionItem.showIcon).height($r(app.float.vp_24)).width($r(app.float.vp_24)).margin({bottom:$r(app.float.vp_2)});Text(mainFunctionItem.description).fontSize($r(sys.float.Caption_M));}.width(100%).height(72).justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center).stateStyles({pressed:{.scale({x:0.97,y:0.97})}}).onClick((){// 路由跳转逻辑// ...});}// 全局 Builder封装课程练习卡片BuilderexportfunctionCoursePracticeBuilder(questions:CourseQuestions){Column(){Row(){Text(questions.subjectName).fontSize($r(sys.float.Subtitle_S)).fontWeight(FontWeight.Medium);// ...}// ...}}3.2 全局 Builder 的导出与导入使用export关键字可以将 Builder 导出供其他模块使用// 在 RouterTable 注册页面BuilderexportfunctionHomePageBuilder(){HomePage();}在路由表中可以这样注册RouterTable.register(HomePage,wrapBuilder(HomePageBuilder));同样在CourseHomePage.ets中也有类似用法BuilderexportfunctionCourseHomePageBuilder(){CourseHomePage();}四、Builder 的参数传递4.1 传递数据对象全局 BuilderCourseCoreBuilder展示如何传递一个自定义对象BuilderexportfunctionCourseCoreBuilder(mainFunctionItem:CourseCoreBar){Column(){Image(mainFunctionItem.showIcon).height($r(app.float.vp_24)).width($r(app.float.vp_24));Text(mainFunctionItem.description).fontSize($r(sys.float.Caption_M));}// ...}在functionBarBuilder中调用BuilderfunctionBarBuilder(){Grid(){ForEach(this.functions,(item:CourseCoreBar){GridItem(){// 传递 item 参数给全局 BuilderCourseCoreBuilder(item);};},(item:CourseCoreBar,index:number)item.descriptionindex);}.columnsTemplate(1fr 1fr 1fr 1fr 1fr)// ...}4.2 传递基础类型全局 BuilderCoursePracticeBuilder接收CourseQuestions对象展示了更复杂的数据传递BuilderexportfunctionCoursePracticeBuilder(questions:CourseQuestions){Column(){Row(){Text(questions.subjectName).fontSize($r(sys.float.Subtitle_S)).fontWeight(FontWeight.Medium);};Row(){Text(开始学习).fontSize($r(sys.float.Caption_L)).fontWeight(FontWeight.Regular).fontColor($r(sys.color.font_secondary));Image($r(app.media.icon_right)).width($r(app.float.vp_16)).height($r(app.float.vp_16));}.layoutWeight(1).justifyContent(FlexAlign.End);Row(){Text(已掌握).margin({right:8}).fontSize($r(sys.float.Body_S));Text(){Span(questions.masteredWords).fontColor($r(sys.color.comp_background_emphasize));Span( / questions.totalWords);}.fontSize($r(sys.float.Body_S));}// ...}}4.3 参数传递规范参数类型示例说明自定义对象CourseCoreBuilder(item)推荐结构清晰基础类型Text(hello)适用于简单场景Resource 类型$r(app.media.ic_home)用于资源引用五、复用粒度控制5.1 何时使用 Builder vs 子组件场景推荐方案原因UI 片段 30 行Builder轻量、无额外上下文开销UI 片段 30-50 行Builder或子组件视复用范围而定UI 片段 50 行独立Component便于维护和测试需要在多页面复用全局Builderexport模块化共享需要独立生命周期独立ComponentBuilder 不拥有生命周期5.2 实际项目中的粒度选择在我们的项目中Banner 组件因为需要独立的响应式逻辑和生命周期所以抽成了独立组件BuilderswiperBuilder(){Banner();// 直接复用 Banner 子组件}而topBarBuilder、todayStudyBuilder等 UI 片段因为相对简单20-40 行且仅在HomePage中使用所以保留为组件内 Builder保持了良好的封装性。六、最佳实践6.1 Builder 命名规范组件内 Builder 使用camelCase命名以Builder结尾topBarBuilder、todayStudyBuilder全局 Builder 使用PascalCase命名以Builder结尾HomePageBuilder、CourseCoreBuilder6.2 避免 Builder 嵌套过深如果 Builder 内部逻辑变得复杂应将其拆解为多个小型 Builder// ❌ 不推荐一个 Builder 包含太多逻辑 Builder complexBuilder() { /* 100 行代码 */ } // ✅ 推荐拆分为多个小型 Builder Builder partA() { /* 30 行 */ } Builder partB() { /* 30 行 */ }6.3 导出 Builder 的最佳实践在路由注册场景中习惯使用全局 Builder 包装页面组件// HomePage.ets 末尾BuilderexportfunctionHomePageBuilder(){HomePage();}// CourseHomePage.ets 末尾BuilderexportfunctionCourseHomePageBuilder(){CourseHomePage();}这种方式比直接导出组件更灵活允许在实际调用时注入参数或包装逻辑。总结Builder装饰器是 ArkTS 声明式 UI 开发的核心工具之一。通过本文的源码分析我们可以看到组件内 Builder适合封装单页面内的 UI 片段直接访问组件状态全局 Builder支持跨页面复用通过export导出参数传递让 Builder 具备数据驱动能力支持自定义对象和基础类型粒度控制根据复杂度和复用范围在 Builder 和子组件之间做合理选择用好Builder能让你的 ArkTS 代码保持清爽、模块化和可维护。
