自定义组件写到第二阶段,都会遇到同一个问题:业务页面要求卡片整体一致但局部可变——菜谱卡片的结构固定,但列表页要显示收藏按钮,详情推荐位要显示烹饪时长,搜索结果要高亮关键词。硬写三个组件是重复劳动,硬塞一个万能参数又会让组件膨胀。ArkUI 给出的答案是插槽与 Builder:组件对外暴露位置,内容由使用方注入。这篇把这些机制的设计取舍、真实用法与三个坑完整记录。一、尾随插槽:最简单的扩展点自定义组件的尾随闭包就是天然插槽:RecipeCard() { Text(额外信息) } 里,Text 会被渲染到组件内 marked 为尾随内容的位置。它的限制是只有一个插槽,内容顺序由组件内部决定。适合主体固定尾部附加的场景——卡片底部加一条备注、列表项尾部加个状态徽标。当需求变成头部也要定制时,尾随插槽就不够了,需要进入命名插槽的世界。二、Builder 传参:把 UI 片段当参数传ArkUI 没有直接的命名插槽语法,等价能力是 Builder 函数作为参数传递:组件声明一个 Builder 类型的属性,使用方传入自己的 Builder 方法,组件在内部用该函数渲染对应区域。菜谱卡片改造时,我定义了 leading、trailing、extra 三个 Builder 属性,分别渲染卡片左上角、右下角与底部的可变区域,不传时组件给默认内容。Component struct RecipeCard { BuilderParam leading: () void this.defaultLeading BuilderParam trailing: () void this.defaultTrailing Builder defaultLeading() { Text(默认角标) } Builder defaultTrailing() { Text() } build() { Stack() { Image(this.item.cover) Row() { this.leading() }.position({ x: 8, y: 8 }) Row() { this.trailing() }.position({ x: 80%, y: 100 }) } } } // 使用方 RecipeCard({ item, leading: favBadgeBuilder, trailing: durationBuilder })三、Builder 的按值与按引用传参Builder 函数的参数传递有两种形态,行为差异是个隐蔽坑:传字面量对象是按值传递,组件内部数据变化时 UI **不会**刷新;传对象字面量加 $$ 前缀的按引用传递才能保持响应。菜谱页的标签数量动态变化时,最初用按值传参导致标签不更新,排查一小时才定位到这个语义差异。经验固化为一条规则:传给 Builder 的参数,只要涉及状态刷新,一律用按引用形态;纯静态展示才用按值。// 按引用:状态变化会刷新 Builder renderTags($$:{ tags: string[] }) { ForEach($$.tags, (t) Text(t)) } // 按值:只在首次渲染生效 Builder renderStatic(tags: string[]) { ... }四、BuilderParam 与 this 指向的陷阱Builder 函数内部的 this 指向是另一个高频坑:使用方定义的 Builder 方法,在组件内部执行时 this 指向的是**宿主组件**而不是使用方页面——访问使用方的状态变量会得到 undefined 或直接报错。解法有两种:一是 Builder 方法只接收参数不访问 this,所有依赖显式传入;二是用 bind 绑定使用方的 this。我采用第一种,它让 Builder 保持纯函数特性,可测试性也好。this 陷阱的本质是UI 片段作为值传递时的执行上下文问题,理解了这一点,各种表现异常都能解释。五、全局 Builder:跨组件复用的 UI 片段库不带组件归属的全局 Builder(定义在组件外)适合沉淀跨页面的 UI 片段库:标签行的渲染、空态提示、分割线组合,写一次全应用复用。全局 Builder 没有 this,所有依赖通过参数进入,反而是最干净的形态。我把应用里重复三次以上的 UI 片段全部抽成全局 Builder,集中放在 builders.ets 里,后来统计这文件覆盖了十一个页面的三十多处复用——UI 片段的复用收益不比逻辑函数小。形态this 指向适用组件内 Builder所属组件组件内部复用BuilderParam宿主组件(注意!)插槽注入全局 Builder无(纯参数)跨页面片段库六、插槽设计的三条边界插槽给了灵活性,但滥用会让组件变成什么都得外部给的空壳。三条边界守着:第一,主体结构不开放插槽——卡片的图片标题元信息是组件的身份,拆给外部注入后组件失去存在意义;第二,插槽只开放内容可变、位置固定的区域;第三,插槽的默认值必须可用——不传 leading 时组件依然完整,而不是缺一块。用这三条检验,菜谱卡片最终只开放了两个插槽,另外两个想开放的可变区被判定为应该拆成独立组件。七、Reusable 与插槽的配合列表滚动场景下,带插槽的组件要配合 Reusable 复用框架。坑在于:复用时 BuilderParam 也会被重新赋值,如果使用方的 Builder 每次渲染都创建新的函数实例,复用收益会被抵消。解法是把使用方的 Builder 定义为组件成员方法(而不是内联箭头),保证引用稳定。实测同一列表,内联写法的复用命中率只有六成,成员方法形态接近满额。复用与插槽的配合细节,是这两个特性各自文档都没提的盲区。八、调试:插槽内容的定位技巧插槽内容渲染在宿主组件的位置,ArkUI Inspector 里它显示在宿主的组件树下,初看会找不到我传的那个 Text 去哪了。定位技巧:给插槽内容的根组件加一个特征 background 色或 id,Inspector 里按 id 搜索。另外插槽内容报错时的堆栈指向使用方文件,不是宿主组件文件——看堆栈先看最后帧属于哪个文件,能少走弯路。这两个调试技巧让插槽相关的问题排查时间从半小时缩到五分钟。九、总结:插槽是把双刃剑收束全文:插槽与 Builder 解决结构复用局部可变的经典矛盾,BuilderParam 提供命名插槽等价能力,按引用传参保住响应式,全局 Builder 沉淀片段库。三条设计边界防止组件空壳化,this 指向与复用配合是两大盲区。当你的组件第三个调用方提出能不能改这块时,就是引入插槽的时机——在那之前,复制粘贴反而是更诚实的选择。参考资料:华为开发者:Builder 函数华为开发者:BuilderParam 装饰器华为开发者:Reusable 组件复用#鸿蒙 #HarmonyOS 7(API 26)十、实战案例:一个卡片组件的三次插槽重构用菜谱卡片的三次重构完整展示插槽设计的演进。第一版零插槽:三种使用场景(列表页、详情推荐位、搜索结果)各复制一份组件改差异,三个月后样式改动需要同步三处,漏改一次搜索页的圆角就和其他页面不一致。第二版参数化:把所有差异做成配置项(showFavorite、showDuration、highlightWord……),配置项很快膨胀到十一个,每加一个场景就要加一个开关,组件内部满是 if 分支,谁也不敢动。第三版插槽化:主体收敛为不可变的图片加标题,四个可变区开放为 BuilderParam,配置项只剩 data 一个。三次重构的代码量对比:第一版三份共 480 行,第二版 520 行(分支复杂度暴涨),第三版 290 行且新增场景零改动组件。插槽不是提前设计的,是重复劳动逼出来的。// 第三版:只保留两个高频插槽,其余场景用默认 RecipeCard({ item, leading: this.isSearch ? highlightBuilder : undefined, trailing: this.showFav ? favBuilder : undefined })十一、插槽与多态组件:一个组件还是多个组件插槽用深了会遇到组件职责的边界问题:菜谱卡片和食材卡片结构有六成相似,是抽一个带大量插槽的万能卡片,还是保留两个独立组件?我先后试过两种,最终回到两个独立组件,重合部分抽成三个全局 Builder。万能卡片路线的问题:为了容纳两种卡片的差异,插槽开到五个,参数类型联合了三种,内部条件渲染四处分支,改任何一个卡片的样式都要在分支里小心确认影响面。独立组件加重合片段的路线:两份结构各自清晰,重合的标签行、图片容器、角标逻辑集中在片段库里单点维护。组件设计的目标不是最大复用,是最大可维护——复用是手段不是目的。方案代码量改动影响面新增卡片成本复制粘贴最高需同步多处低万能组件中牵一发动全身高(理解成本)独立组件片段库中低单点清晰中(拼装片段)十二、性能视角:插槽对渲染的影响带 BuilderParam 的组件在渲染上有一个值得注意的行为:插槽内容的重新渲染跟随使用方的状态变化,而不是宿主组件——这意味着使用方页面上的任何状态更新,都可能触发插槽内容的重渲染,即使内容与该状态无关。实测一个列表页:页面级的筛选状态变化时,十张卡片的固定主体不重渲染,但两张用了插槽的卡片其插槽区域被重新执行。缓解方式是插槽内容里的状态引用尽量局部化(传入切片数据而非整个对象),以及重渲染成本高的插槽内容内部再做组件拆分让框架可以跳过静态部分。这个行为没有开关可关,只能靠内容设计规避,知道它的存在就赢了一半。十三、写给你的 Adoption 路线:三步引入插槽给准备在自己的工程里引入插槽的同学一条渐进路线,避免一步到位的改造风险。第一步,先在新增组件上尝试 BuilderParam,老组件不动,用一两个新组件积累对 this 指向与按引用传参的手感;第二步,把应用里重复三次以上的 UI 片段抽成全局 Builder 片段库,这一步不涉及组件改造,收益立竿见影;第三步,对重复劳动最严重的老组件(通常已经复制出三份以上)做插槽化重构,重构时用本文第十一节的三方案对照说服自己和评审。三步走完通常需要一到两个月,期间应用不需要停止迭代——插槽的引入是渐进的,不是运动式的。组件化写作至此是这个系列的第八篇,布局六篇加组件两篇,ArkUI 的结构层已经写完。下一篇进入状态管理系列,从 State 与 Prop 的单向数据流开始——那是 ArkUI 里另一个看着简单、边界丛生的领域。补充回答一个写作过程中的疑问:Builder 会不会被后续版本的能力替代?从 API 26 的演进方向看,V2 状态体系与组件复用机制在持续增强,但 Builder 作为 UI 片段的组合原语,与状态体系是正交关系而非替代关系。我的判断是至少在可见的版本周期里,这篇的机制与边界都是有效的投资。框架会变,组合的思想不会。这也是把这篇放进系列的理由:学机制是入口,学组合的思维方式才是出口。组件化的最终形态,是团队里每个人都在同一套插槽约定下搭积木,而不是每个人造自己的轮子。十四、与路由的配合:插槽内容里的页面跳转插槽内容里出现页面跳转按钮是常见需求,但跳转逻辑归属谁是个设计问题。直接在插槽闭包里写 router 跳转,会让展示型片段持有导航依赖;更干净的做法是插槽内容只发事件,导航由使用方页面统一处理。菜谱卡片的做法是插槽内容接收一个回调参数,点击收藏角标时回调 onFavTap(item),跳转与否由宿主页面决定。这个分离让同一个卡片组件在需要不同跳转行为的位置(列表进详情、推荐位进专题)复用时,不需要修改组件本身。回调参数的设计也有讲究:传 item 完整对象而不是 id,使用方拿到的信息一次到位,避免为了跳转再去查一遍数据。Component struct RecipeCard { onFavTap?: (item: RecipeItem) void BuilderParam trailing: () void this.defaultTrailing Builder defaultTrailing() { Image(this.favIcon).onClick(() { if (this.onFavTap) this.onFavTap(this.item) }) } }十五、文档化:让团队用对插槽的三份材料组件插槽写完只是完成了一半,另一半是让团队正确使用。我沉淀了三份材料:一份组件 API 表,列出每个 BuilderParam 的位置、默认行为与使用示例——表格比注释容易被找到;一份决策指引,回答这个场景该用插槽还是传参数还是新开组件,三问三答;一份反例集,收录 this 陷阱、按值传参不刷新这两个经典错误的错误代码与修正代码对照。三份材料放在组件文件同目录,随组件一起演进。组件的文档化程度决定了插槽是被正确使用还是被滥用,这份投入不能省。本篇至此完整收笔。从尾随插槽到全局片段库,从传参语义到复用配合,从三次重构到文档沉淀,插槽体系的每个环节都过了一遍。下一片进入状态管理系列,那里有更多的边界与更深的坑等着记录。
