HarmonyKit | 鸿蒙开发Builder 与 BuilderParam 的插槽模式与作用域规则引言Builder 是 ArkUI 独有的武器Flutter 有 Widget 方法React 有函数组件Vue 有 template slot——每个框架都有自己的可复用 UI 片段方案。ArkUI 的答案是Builder装饰器——一种比 Component 更轻量的 UI 构建方式。在 HarmonyKit 中Builder被用于两个关键场景主页的ToolGrid被 5 个 TabContent 共享调用文本统计工具的StatCard被 6 次调用生成了 6 个统计卡片。这篇文章将拆解 Builder 的作用域规则、参数传递、与 Component 的边界、以及 BuilderParam 的插槽模式。项目仓库https://atomgit.com/VON-/harmony-kitBuilder 的本质轻量级 UI 工厂Builder 的本质是一个带 UI DSL 上下文的函数。它和普通函数的区别在于普通函数返回 string/number/voidBuilder 函数直接输出 UI 组件树Builder 内部只能使用 UI DSL与 build() 相同的语法约束Builder 不能有 State——它依赖于父组件的状态ToolGrid参数化的复用 Builder主页 5 个分类 Tab每个都需要渲染一个工具卡片网格。如果不用 Builder5 段几乎完全相同的 Grid 代码分布在 5 个 TabContent 中BuilderToolGrid(category:string){Scroll(){Grid(){ForEach(getToolsByCategory(category),(tool:ToolItem){GridItem(){ToolCard({tool:tool})}})}.columnsTemplate(1fr 1fr).columnsGap(12).rowsGap(12).padding({left:16,right:16,top:8,bottom:80}).width(100%)}.scrollBar(BarState.Off)}5 个 Tab 各自调用this.ToolGrid(cat)——同一个 Builder不同的cat参数。如果以后网格从 2 列改为 3 列只需要改columnsTemplate(1fr 1fr 1fr)——5 个 Tab 同时生效。这种模式的另一个好处是减少缩进深度。如果不用 Builder每个 TabContent 内部需要完整写一遍 Grid Scroll ForEach ToolCard缩进可以达到 8 层阅读体验极差。Builder 的抽象让主页的 build() 方法保持扁平build(){Column(){HdsTabs(){TabContent(){this.ToolGrid(format)}// 格式化工具TabContent(){this.ToolGrid(encoder)}// 编解码工具TabContent(){this.ToolGrid(converter)}// 转换工具TabContent(){this.ToolGrid(generator)}// 生成工具TabContent(){this.ToolGrid(analyzer)}// 分析工具}}}一眼能看出主页的结构5 个 Tab每个内部是同类工具的网格。不需要关心 Grid 内部具体怎么布局——那是 ToolGrid Builder 的事。StatCard为什么用 Builder 而不用 Component文本统计工具页需要 6 个统计卡片展示总字符数“字节数”行数等指标。每个卡片结构完全相同一个大数字 一个小标签。BuilderStatCard(label:string,value:string,color:string){Column(){Text(value).fontSize(20).fontWeight(FontWeight.Bold).fontColor(color).fontFamily(monospace);Text(label).fontSize(10).fontColor(#999).margin({top:4});}.width(100%).padding({top:14,bottom:14}).backgroundColor(#ffffff).borderRadius(10);}调用this.StatCard(总字符数, String(this.charCount), #007aff)为什么不用 ComponentStatCard 不需要自己的状态不需要生命周期回调不需要属性装饰器。它只是一个纯函数——给定参数返回 UI。Builder 是这种场景下最轻量的选择。如果用 Component每个 StatCard 会创建独立的组件实例产生额外的实例管理开销。6 个 StatCard 就是 6 个组件实例。无状态时用 Builder有状态时用 Component是值得养成的代码习惯。// 使用 Builder 的完整上下文build(){Column(){// 6 次调用生成 6 个统计卡片Row(){this.StatCard(总字符数,String(this.charCount),#007aff)this.StatCard(字节数,String(this.byteCount),#34c759)}Row(){this.StatCard(行数,String(this.lineCount),#ff9500)this.StatCard(单词数,String(this.wordCount),#ff3b30)}Row(){this.StatCard(中文字数,String(this.cjkCount),#5856d6)this.StatCard(空格数,String(this.spaceCount),#af52de)}}}这种6 次调用产生 6 个卡片的模式清晰直观。如果用 Component需要定义 StatCard 组件并传入 6 组不同的参数组件注册和声明的开销对于纯展示型组件来说过于沉重。Builder 的作用域陷阱Builder 可以访问 State/Prop 和传入的参数但不能访问普通类成员变量// 错误privateprefix:string工具: ;BuildermyBuilder(name:string){Text(this.prefixname)// 编译错误Builder 不能访问非响应式成员}// 正确声明为 StateStateprefix:string工具: ;限制是合理的。Builder 不创建独立组件实例运行在父组件的上下文中。如果 Builder 可以随意访问父组件所有成员任意改动都可能破坏 Builder 的渲染。限制为只能访问响应式变量让 Builder 的依赖关系显式可追踪。更完整的说明Builder 中可以访问✅ 通过参数传入的变量Builder myBuilder(param: string) { Text(param) }✅ 当前组件的 State / Prop 变量Text(this.stateVar)✅ 组件方法getter 方法Text(this.getDisplayText())❌ 普通类成员变量非 State/Propprivate temp: string这个限制在实际开发中几乎不会造成困扰——需要展示的数据天然应该是 State 或 Prop如果某个变量不应该是响应式的那它很可能不需要在 UI 中展示。BuilderParam插槽模式BuilderParam 是 ArkUI 的插槽——父组件将自己的 Builder 传给子组件子组件在指定位置渲染。类似于 React 的 render props// 子组件暴露一个 Builder 插槽Componentstruct CustomContainer{BuilderParamheader:()void;build(){Column(){this.header()// 渲染父组件传入的 headerText(Content)}}}// 父组件定义并传入 BuilderBuildermyHeader(){Text(Header).fontSize(20)}CustomContainer({header:this.myHeader})BuilderParam 的典型应用场景是容器组件——弹窗、对话框、抽屉等。容器提供壳背景、动画、关闭按钮业务提供肉内容区域// 通用弹窗组件Componentexportstruct ModalDialog{BuilderParamcontent:()void;Statevisible:booleanfalse;build(){Stack(){if(this.visible){Column(){// 弹窗背景Column(){// 标题栏Row(){Text(提示).fontSize(18)}.padding(16)// 业务内容 — 由 BuilderParam 注入this.content()}.width(80%).backgroundColor(#fff).borderRadius(12)}.width(100%).height(100%).backgroundColor(rgba(0,0,0,0.3)).onClick((){this.visiblefalse;})}}}}// 使用BuilderconfirmContent(){Column(){Text(确定要删除吗)Row(){Button(取消)Button(确定).backgroundColor(#ff3b30)}}}ModalDialog({content:this.confirmContent})HarmonyKit 暂未使用此模式。但对于容器组件弹出面板、对话框、抽屉极有价值——“框架写壳业务写肉”。Builder 的全局 vs 局部作用域在 ArkUI 中Builder 可以定义在组件内部局部 Builder或组件外部全局 Builder// 全局 Builder — 在任何组件中都能引用BuilderfunctionGlobalBuilder(){Text(全局 Builder)}// 局部 Builder — 只能在当前组件中通过 this 引用Componentstruct MyComponent{BuilderLocalBuilder(){Text(局部 Builder)}build(){Column(){GlobalBuilder()// 直接调用this.LocalBuilder()// 通过 this 调用}}}全局 Builder 适用于所有页面共享的 UI 片段如统一错误提示样式。局部 Builder 适用于页面内部复用的 UI 片段。Builder 的另一个受限之处全局 Builder 不能访问任何组件的 State。它只能使用传入的参数。这使得全局 Builder 更像一个纯粹的 UI 函数——输入参数输出 UI没有副作用。Builder 的性能考量Builder 不创建独立组件实例所以它的性能开销比 Component 更小。在需要频繁调用如 ForEach 中的每个 item或创建大量实例如 Grid 中的 GridItem的场景中Builder 比 Component 更高效。但这不意味着永远用 Builder 代替 Component。当 UI 片段需要自己的 State状态隔离生命周期回调aboutToAppear 等被多个页面共享复用此时应该选择 Component。Builder 适合轻量、无状态、局部复用的场景。Builder vs Component 决策树需求选择需要 StateComponent需要生命周期Component需要 Prop/ConsumeComponent纯展示、无状态Builder跨组件传递 UI 片段BuilderParam全局复用多个页面共享全局 Builder 或 Component页面内部局部复用局部 BuilderForEach/Grid 中的重复项Builder轻量优先项目仓库https://atomgit.com/VON-/harmony-kit
