HarmonyOS开发实战：笔友-CommonComponents 组件库设计哲学——聚合与拆分的权衡

前言在 ArkUI 声明式开发范式中组件复用是提升开发效率和 UI 一致性的关键手段。xiexin 将 5 个通用组件集中放在一个 146 行的CommonComponents.ets文件中这种单文件聚合的设计在小型项目中极具性价比但随着项目规模增长需要向多文件拆分演进。本文将以CommonComponents.ets为蓝本详细剖析组件库设计中的聚合 vs 拆分选择、组件的导出/引用机制、Component/Prop/BuilderParam在组件封装中的配合以及组件库随着项目规模增长的演进路线。一、CommonComponents 的整体设计1.1 文件结构xiexin 的CommonComponents.ets位于entry/src/main/ets/components/CommonComponents.ets整个文件 146 行包含 5 个组件组件行数装饰器用途AvatarComponent34ComponentProp头像显示首字母回退StatusBadge22ComponentProp信件/笔友状态标签CardContainer19ComponentBuilderParam通用卡片容器EmptyState49ComponentProp空状态占位DividerLine10ComponentProp分割线1.2 所有组件代码// entry/src/main/ets/components/CommonComponents.etsimport{AppColors}from../common/Constants;// 通用头像组件Componentexportstruct AvatarComponent{Propname:string;PropavatarSize:number48;PropfontSize:number18;privategetAvatarColor():string{constcolors:string[][#E8D5B7,#D4C4A8,#C9B896,#BFA98A,#D1C0A5,#C2B59B];lethash:number0;for(leti0;ithis.name.length;i){hashthis.name.charCodeAt(i)((hash5)-hash);}returncolors[Math.abs(hash)%colors.length];}build(){Stack(){Circle().width(this.avatarSize).height(this.avatarSize).fill(this.getAvatarColor())Text(this.name.length0?this.name.charAt(0):?).fontSize(this.fontSize).fontColor(AppColors.TEXT_PRIMARY).fontWeight(FontWeight.Medium)}.width(this.avatarSize).height(this.avatarSize)}}// 状态标签组件Componentexportstruct StatusBadge{Proptext:string;Propcolor:stringAppColors.PRIMARY;PropbgColor:stringAppColors.AMBER_LIGHT;build(){Text(this.text).fontSize(11).fontColor(this.color).backgroundColor(this.bgColor).borderRadius(10).padding({left:8,right:8,top:3,bottom:3}).fontWeight(FontWeight.Medium)}}// 通用卡片容器Componentexportstruct CardContainer{BuilderParamcontent:()void;PropcardPadding:number16;build(){Column(){this.content()}.width(100%).padding(this.cardPadding).backgroundColor(AppColors.CARD_BG).borderRadius(16).shadow({radius:8,color:#0D000000,offsetX:0,offsetY:2})}}// 空状态组件Componentexportstruct EmptyState{Proptitle:string暂无内容;Propsubtitle:string;PropshowButton:booleanfalse;PropbuttonText:string;onButtonClick?:()void;build(){Column({space:16}){Column(){Text().fontSize(64).opacity(0.3)}.margin({top:60})Text(this.title).fontSize(16).fontColor(AppColors.TEXT_SECONDARY)if(this.subtitle.length0){Text(this.subtitle).fontSize(13).fontColor(AppColors.TEXT_SECONDARY).opacity(0.7)}if(this.showButton){Button(this.buttonText).fontSize(14).fontColor(AppColors.WHITE).backgroundColor(AppColors.PRIMARY).borderRadius(24).height(40).width(140).margin({top:16}).onClick((){if(this.onButtonClick){this.onButtonClick();}})}}.width(100%).justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center)}}// 分割线组件Componentexportstruct DividerLine{PropmarginH:number16;build(){Divider().strokeWidth(0.5).color(AppColors.DIVIDER).margin({left:this.marginH,right:this.marginH})}}二、单文件聚合 vs 多文件拆分2.1 两种模式的对比维度单文件聚合xiexin 当前多文件拆分文件数量1 个N 个代码定位在同一文件中滚动在目录中查找文件名组件耦合可见便于发现耦合隐藏独立文件导入语句一次 import 全部每个组件独立 import适合阶段小型项目 10 组件中大型项目 10 组件2.2 导入方式的差异// 单文件聚合一次 import 全部import{AvatarComponent,StatusBadge,CardContainer,EmptyState,DividerLine}from../components/CommonComponents;// 多文件拆分每个组件独立 importimport{AvatarComponent}from../components/AvatarComponent;import{StatusBadge}from../components/StatusBadge;2.3 组件库目录结构演进// 小型项目单文件 components/CommonComponents.ets // 中型项目按类别拆分 components/ ├── AvatarComponent.ets ├── StatusBadge.ets ├── CardContainer.ets ├── EmptyState.ets └── DividerLine.ets // 大型项目按模块分组 components/ ├── avatars/ │ ├── AvatarComponent.ets │ └── GroupAvatar.ets ├── badges/ │ ├── StatusBadge.ets │ └── CountBadge.ets ├── cards/ │ ├── CardContainer.ets │ └── StatsCard.ets └── states/ └── EmptyState.ets三、Component 的导出与引用3.1 export struct 的语义Componentexportstruct AvatarComponent{Propname:string;PropavatarSize:number48;PropfontSize:number18;}3.2 在页面中引用import{AvatarComponent,StatusBadge,EmptyState}from../components/CommonComponents;BuilderLetterCard(letter:Letter){Row(){AvatarComponent({name:letter.penPalName,avatarSize:40,fontSize:16})Column({space:6}){Text(letter.penPalName).fontSize(16)StatusBadge({text:this.getStatusText(letter),color:AppColors.PRIMARY})}}}四、BuilderParam 插槽设计4.1 CardContainer 的插槽Componentexportstruct CardContainer{BuilderParamcontent:()void;PropcardPadding:number16;build(){Column(){this.content()}.width(100%).padding(this.cardPadding).backgroundColor(AppColors.CARD_BG).borderRadius(16).shadow({radius:8,color:#0D000000,offsetX:0,offsetY:2})}}五、计算属性在组件中的使用privategetAvatarColor():string{constcolors:string[][#E8D5B7,#D4C4A8,#C9B896,#BFA98A,#D1C0A5,#C2B59B];lethash:number0;for(leti0;ithis.name.length;i){hashthis.name.charCodeAt(i)((hash5)-hash);}returncolors[Math.abs(hash)%colors.length];}六、条件渲染在组件中的应用if(this.subtitle.length0){Text(this.subtitle)}if(this.showButton){Button(this.buttonText)}七、组件参数设计原则// 好的参数设计明确的默认值Propname:string;PropavatarSize:number48;PropfontSize:number18;// 可选回调函数onButtonClick?:()void;八、组件库的测试策略import{describe,it,expect}fromohos/hypium;describe(EmptyState,(){it(should display title when provided,(){constcomponentnewEmptyState();component.title测试标题;expect(component.title).toBe(测试标题);});});九、组件的扩展建议Componentexportstruct AvatarComponent{Propname:string;PropavatarUrl:string;PropavatarSize:number48;PropfontSize:number18;build(){Stack(){if(this.avatarUrl.length0){Image(this.avatarUrl).width(this.avatarSize).height(this.avatarSize).borderRadius(this.avatarSize/2)}else{Circle().width(this.avatarSize).height(this.avatarSize).fill(this.getAvatarColor())Text(this.name.charAt(0)).fontSize(this.fontSize).fontColor(AppColors.TEXT_PRIMARY)}}.width(this.avatarSize).height(this.avatarSize)}}九、组件库的版本管理策略当组件库需要版本迭代时推荐以下策略新增组件在 CommonComponents 文件中新增组件不影响现有组件修改组件修改Prop参数时考虑向后兼容性废弃组件保留旧接口添加deprecated注释/** * deprecated 请使用 NewAvatarComponent 替代 */Componentexportstruct AvatarComponent{// 旧接口}十、组件库的文档化组件库的文档化是团队协作的关键每个组件需要标注Prop参数说明提供使用示例代码标注不兼容的变更/** * 头像组件 * param name 用户名用于首字母和颜色计算 * param avatarSize 头像尺寸默认 48 * param fontSize 首字母字号默认 18 */Componentexportstruct AvatarComponent{Propname:string;PropavatarSize:number48;PropfontSize:number18;}十一、从 xiexin 看组件库设计xiexin 的组件库设计体现了够用就好的原则单文件聚合5 个组件146 行适合当前阶段Prop 参数化所有组件可通过参数定制BuilderParam 插槽CardContainer 支持内容注入可选回调EmptyState 的 onButtonClick 可选提示当组件数量超过 10 个时建议按组件类型拆分到独立文件避免单文件膨胀。十二、组件库的 CI/CD 集成在团队协作中组件库的自动化测试和发布是保证质量的关键单元测试每个组件需要有对应的ohos/hypium测试用例视觉回归测试使用截图对比工具检测 UI 变化自动发布组件库可以发布为 HAR 包供其他模块使用// oh-package.json5 { dependencies: { xiexin/common-components: 1.0.0 } }总结本文详细剖析了 xiexin 的 CommonComponents 组件库设计哲学重点讲解了单文件聚合 vs 多文件拆分的权衡、Prop 参数化设计、BuilderParam 插槽模式以及组件库随着项目规模增长的演进路线。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.netHarmonyOS 应用开发指南https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-dev-guideHarmonyOS 状态管理概述https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-state-management-overviewHarmonyOS 高性能编程实践https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-high-performance-programmingHarmonyOS 组件复用https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-component-reusableHarmonyOS 自定义组件https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-custom-componentsHarmonyOS 组件封装https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-component-encapsulationHarmonyOS Builder 装饰器https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builderHarmonyOS BuilderParam 装饰器https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builderparamHarmonyOS 自定义组件https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-custom-componentsHarmonyOS 组件封装https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-component-encapsulationHarmonyOS Builder 装饰器https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builderHarmonyOS BuilderParam 装饰器https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builderparamHarmonyOS Prop 装饰器https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-propHarmonyOS 组件复用开发实践https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-component_reuseHarmonyOS 状态管理概述https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-state-management-overviewHarmonyOS 自定义组件生命周期https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-custom-components-lifecycle