Builder 与 BuilderParam — 鸿蒙 UI 复用最佳实践概述在鸿蒙 ArkTS 开发中UI 复用是提升开发效率和保持界面一致性的关键。面对复杂的业务页面如果没有有效的复用机制build()方法会迅速膨胀到数百行的规模充斥着大量重复的布局代码。更棘手的是跨场景复用问题——同一个基础容器组件在不同的业务模块中可能需要完全不同的内部内容。ArkTS 提供了Builder和BuilderParam两种装饰器来解决这一挑战Builder用于定义可复用的 UI 构建函数将一段 UI 结构封装为函数BuilderParam则允许父组件向子组件注入自定义的 UI 片段实现类似 Web 框架中插槽slot的模式。MoneyTrack 项目广泛使用这两种装饰器来构建灵活、可组合的 UI 组件体系。核心知识点1. 内联 Builder 的定义与使用Builder装饰器可用于组件内部定义仅在该组件内使用的 UI 构建函数。MoneyTrack 中的StatisticsView使用内联Builder将复杂的 UI 拆分为多个独立的构建方法ComponentV2exportstruct StatisticsView{BuilderfilterBarBuilder(){Row(){// 月份选择器、成员选择器、视图切换、分享按钮}}BuildermonthSheetBuilder(){CommonMonthPicker({...});}BuildermemberSheetBuilder(){Column(){Text(选择成员)List(){...}}}}每个Builder方法管理一个独立的 UI 区域使得build()方法的结构清晰易懂各区域逻辑互不干扰。2. Builder 的有参形式Builder可以接受参数实现参数化的 UI 构建。以下是MemberPrivacy中的带参构建器示例BuilderexportfunctionMemberPrivacy(content:string){Scroll(){Text(content).fontSize(14).lineHeight(20);}.height(100%).align(Alignment.Top).padding(16).scrollBar(BarState.Off);}参数化Builder使得同一段 UI 逻辑可以根据传入参数渲染不同的内容减少了重复的模板代码。参数类型可以是基础类型、对象、甚至是回调函数。3. BuilderParam 的插槽模式BuilderParam是 ArkTS 实现组件间 UI 注入的核心机制。它允许父组件将一段 UI 构建逻辑传入子组件由子组件在合适的位置渲染。下图展示了这种模式的数据流子组件父组件定义 BuildercustomContent()传入子组件contentBuilder: customContentBuilderParamcontentBuilder在 build() 中调用this.contentBuilder()渲染注入的 UI 内容MoneyTrack 中的ContainerRow组件是这一模式的典型应用ComponentV2exportstruct ContainerRow{BuilderParamcustomBuilderParam:()void;build(){Row(){this.customBuilderParam();}.width($r(app.string.width_percent_full)).alignItems(VerticalAlign.Center).borderRadius($r(app.string.border_radius_16)).padding($r(app.string.space_m));}}父组件使用时只需传入自定义构建器ContainerRow({customBuilderParam:this.myContentBuilder})这种模式使ContainerRow成为了一个带样式的容器内部内容完全由父组件控制实现了容器样式与内容的完美解耦。4. 全局 Builder 跨模块复用通过export关键字Builder可以被导出为全局函数供其他模块甚至跨 HAR 包引用。这在router_map.json的页面路由注册场景中尤为重要{name:BillDetailPage,pageSourceFile:src/main/ets/views/BillDetailPage.ets,buildFunction:billDetailPageBuilder}对应的全局构建器定义如下// BillDetailPage.etsBuilderexportfunctionbillDetailPageBuilder(){BillDetailPage();}在 MoneyTrack 中home、assets、statistics、mine等各特性模块的router_map.json都使用buildFunction字段引用Builder导出的全局函数。这种跨模块的构建器导出机制是实现基于 NavDestination 的路由导航体系的基础。5. Builder 与自定义组件的选择Builder和自定义组件ComponentV2都可以封装 UI但适用场景不同使用Builder当UI 结构简单、无独立状态管理需求、仅作为较大组件的一部分。使用自定义组件当UI 区域需要独立的状态管理、生命周期钩子、或需要被多个页面单独复用。一个经验法则如果一段 UI 需要自己的Local或Param就应该提取为独立组件否则用Builder足够了。项目案例d:\HarmonyOS\WorkSpace\MoneyTrack1.0.3\features\statistics\src\main\ets\views\StatisticsView.ets中filterBarBuilder()是内联Builder的典型使用。d:\HarmonyOS\WorkSpace\MoneyTrack1.0.3\components\feedback\src\main\ets\FeedbackTrigger.ets的BuilderParam contentBuilder展示了外部注入 UI 的模式。d:\HarmonyOS\WorkSpace\MoneyTrack1.0.3\commons\commonlib\src\main\ets\components\ContainerRow.ets中的BuilderParam customBuilderParam实现了容器样式与内容的解耦。总结Builder和BuilderParam是 ArkTS 中实现 UI 复用的两大利器。Builder解决了相同 UI 逻辑多处调用的问题支持无参和有参两种形式还能通过export实现跨模块导出BuilderParam更进一步解决了相同容器不同内容的问题通过插槽模式让父组件控制子组件的内部渲染内容。在 MoneyTrack 中从页面内的区域拆分到跨模块的页面路由注册再到通用容器的内容注入Builder和BuilderParam贯穿了整个 UI 层是构建模块化、可组合应用的基石。最佳实践是用Builder拆分页面内的 UI 区域用BuilderParam设计高度灵活的可注入容器组件用全局Builder实现页面路由和跨 HAR 的 UI 共享。参考文档Builder 装饰器指南BuilderParam 装饰器指南组件化 UI 构建与复用最佳实践