20 — 自定义组件与 Builder/BuilderParam一、引言当同一 UI 片段在多个页面反复出现图标、头像、页签将其封装为自定义组件是 ArkUI 声明式开发的基本功而占位 插槽则让公共壳子具备无限扩展性。本项目通过自定义组件 MSVTextIcon、Builder 构建函数与 BuilderParam 插槽实现了公共 Builder 复用与插槽化设计支撑同一页面多种外壳的多设备策略。本文以common/multishortvideobase/src/main/ets/components/MSVTextIcon.ets、products/default/src/main/ets/components/Builders.ets、features/multishortvideoindividual/src/main/ets/components/Builders.ets为主线。二、自定义组件结构与生命周期MSVTextIcon 将图标 可选文字组合为可配置组件头像、点赞、搜索、分享等场景复用ComponentV2 export struct MSVTextIcon { Require Param src: PixelMap | ResourceStr | DrawableDescriptor; Param iconSize: Length 32; Param iconOnly: boolean true; Param content: string | Resource ; Param fontSize: ... $r(sys.float.Body_M); Param gap: Length 2; build() { Column({ space: this.gap }) { Image(this.src).width(this.iconSize).aspectRatio(1).objectFit(ImageFit.Contain) if (!this.iconOnly) { Text(this.content).fontSize(this.fontSize).fontColor(this.fontColor) } } } }设计要点Require Param标记必传参数 src编译期约束调用方其余 Param 提供默认值调用方按需覆盖如评论头像iconSize: deviceInfo.deviceType tv ? 44 : 32组件自带 aboutToAppear/aboutToDisappear 生命周期可做数据加载与资源释放。三、Builder 局部构建函数Builder 将一段 UI 封装为可复用构建函数支持参数传递。MSVTabs 用它定义页签样式Builder MSVTabBar(params: MSVDataModel, currentIndex: number) { if (params.iconOnly) { Image(this.isDark ? params.iconDark : params.icon) .width(params.iconSize).aspectRatio(1) } else { Column() { Text(params.text) .fontColor(this.activeIndex currentIndex ? this.selectedLightColor : this.lightColor) } .border({ width: { bottom: this.showBarUnderline (this.activeIndex currentIndex) ? 1 : 0 } }) } }SplitComment 用 Builder 定义自定义标题栏渐变遮罩 标题 关闭按钮Builder CustomTitleBuilder() { Column() { Column().width(CommonConstants.FULL_PERCENT).height(36) .linearGradient({ direction: GradientDirection.Bottom, colors: [[#4D000000, 0.0], [#00000000, 1.0]] }) Row() { Text($r(app.string.comment_title, this.commentCount)) Row() { SymbolGlyph($r(sys.symbol.xmark)).fontSize(18) } .onClick(() { this.pathStack.pop(); this.showSideComment false; }) } } }四、BuilderParam 内容插槽BuilderParam 接收外部传入的 Builder形成占位-填充插槽。MSVTabs 内部封装 MSVTabContent让每个 TabContent 的内容由调用方决定ComponentV2 struct MSVTabContent { Local stackId: string MSVTabContent; BuilderParam content: BuilderCallback; // 外部注入的页签内容 build() { Stack() { this.content() } .id(this.stackId) } }使用侧把页签内容 Builder 传入Builder MSVTabContent(data: MSVDataModel[]) { ForEach(data, (tabItem: MSVDataModel, index: number) { TabContent() { if (tabItem.content) { MSVTabContent({ content: tabItem.content }) } } .tabBar(this.MSVTabBar(tabItem, index)) }, (tabItem: MSVDataModel) JSON.stringify(tabItem.content)) }BuilderCallback是 ArkUI 通用构建函数类型BuilderParam 与导出 Builder 天然兼容。五、Builders.ets 公共 Builder 复用产品层将页面级 Builder 统一收敛在 Builders.ets作为 MSVDataModel.content 注入页签实现数据驱动 内容可换// products/default/.../components/Builders.ets Builder export function home() { SubTabs().width(CommonConstants.FULL_PERCENT).height(CommonConstants.FULL_PERCENT) .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]) } Builder export function recommend() { Column() { AdaptiveVideoForDefault() } .width(CommonConstants.FULL_PERCENT).height(CommonConstants.FULL_PERCENT) .backgroundColor(Color.Black) }individual 模块的 Builders.ets 同样导出作品页等Builder export function works() { Column() { Works() } ... }。数据层直接引用 Builder 完成页签组装MainTabsViewModelthis.mainTabsData.push(new MSVDataModel(home, $r(app.string.home_title))); this.mainTabsData.push(new MSVDataModel(add, , true, $r(app.media.ic_plus), $r(app.media.ic_plus_dark)));六、插槽化设计在个人作品页与评论区头部的应用个人作品页 Individual.ets 的头部信息区与 MSVTabs 内容区解耦评论区头部CustomTitleBuilder与评论列表Comment解耦。二者共享同一模式外壳组件只负责布局与关闭逻辑业务内容通过 Builder/插槽注入实现同一评论页面手机半模态、大屏分栏、TV 全屏三种外壳下内容零重复。应用场景壳组件插槽/组合内容多形态评论区SplitComment / bindSheetComment半模态、分栏、全屏个人主页IndividualByRouterIndividual全屏、侧面板底部页签MSVTabs MSVTabContentBuilders.ets 各页面手机/TV/PC七、总结与最佳实践高频 UI 片段封装为自定义组件MSVTextIcon必传参数用 Require Param可选参数给默认值。组件内复用用 Builder跨模块复用用导出 BuilderBuilders.ets。BuilderParam 提供插槽能力壳组件与业务内容彻底解耦支撑一内容多外壳。页面内容以 Builder 注入 MSVDataModel实现页签数据驱动、内容可热替换。生命周期方法保持轻量aboutToAppear 只做数据加载避免卡顿。