自定义组件封装策略 — 从通用 Header 到业务组件的分层设计一、引言在大型应用中合理的组件化设计是保证代码可维护性和复用性的基石。鸿蒙的 ArkTS 通过ComponentV2装饰器支持自定义组件允许开发者将页面拆分为可复用的独立模块。MoneyTrack 项目从通用基础组件如 CommonHeader到业务领域组件如 AssetSummaryCard、AssetCard构建了一套清晰的组件分层体系实现了代码的高复用和低耦合。二、核心知识点2.1 ComponentV2 与 Component(V1) 对比鸿蒙 ArkTS 提供了两代组件装饰器。ComponentV2推荐相较于Component(V1)在响应式和性能上有显著提升对比维度ComponentV2Component(V1)数据装饰器Param / Local / ComputedState / Prop / Link响应式粒度属性级精准触发更新对象引用级整体替换才触发性能表现仅更新变动的属性整个组件重建语法简洁度不需要 .build() 内部赋初值略繁琐推荐程度强烈推荐新项目应使用兼容旧项目// ComponentV2 写法推荐ComponentV2exportstruct MyComponent{Paramcount:number0LocalisVisible:booleantruebuild(){/* ... */}}// Component(V1) 写法旧Componentexportstruct OldComponent{Statecount:number0PropisVisible:booleantruebuild(){/* ... */}}2.2 Param 与 Local 的角色分配在ComponentV2中数据装饰器的选择决定了属性的职责Param接收父组件传入的外部属性即 props由父组件驱动更新。子组件不应修改Param属性。Local组件内部管理的私有状态仅供组件自身使用外界不可直接赋值。ComponentV2exportstruct UserCard{ParamuserName:string// 父组件传入只读ParamavatarUrl:string// 父组件传入只读LocalisExpanded:booleanfalse// 组件内部状态LocallikeCount:number0// 组件内部状态build(){Column(){Text(this.userName).fontSize(16)if(this.isExpanded){Text(详细资料...)}}}}分配原则凡是从父组件传入的数据用Param组件自己管理的交互状态用Local。2.3 组件通信方式自定义组件之间通过单向数据流进行通信父→子通过Param属性传递数据子→父通过回调函数事件通知父组件// 父组件使用ComponentV2exportstruct ParentPage{Localitems:number[][1,2,3]build(){Column(){ForEach(this.items,(item:number){ChildCard({value:item,onDelete:(id:number){this.itemsthis.items.filter(vv!id)}})})}}}// 子组件定义ComponentV2exportstruct ChildCard{Paramvalue:number0ParamonDelete:(id:number)void(){}build(){Row(){Text(${this.value})Button(删除).onClick(()this.onDelete(this.value))}}}这种模式确保了数据从父到子单向流动子组件通过回调通知父组件执行修改避免了双向绑定的混乱。2.4 组件封装的最佳粒度组件拆分需要遵循高内聚、低耦合原则。MoneyTrack 的组件分为三个层次App应用根节点TabBar底部导航BillPage账单页StatisticsPage统计页MinePage我的页CommonHeader通用标题栏DailyBillGroup每日分组BillCard账单卡片CategoryIcon分类图标ChartSummary图表摘要CalendarSummary日历摘要MemberCard会员卡片SettingItem设置项经验法则单一职责一个组件只做一件事。BillCard只负责展示单条账单不负责布局列表。接口归一化组件的Param应设计为统一的 Model 类型而非零散的基础类型。props 不可变性子组件应只读地消费Param不直接修改父组件数据。2.5 CommonHeader 完整实现以下是 MoneyTrack 中 CommonHeader 的完整代码ComponentV2exportstruct CommonHeader{Paramtitle:stringParamonBack:()void(){}ParamrightText:stringParamonRightClick:()void(){}ParamisDarkMode:booleanfalsebuild(){Row(){// 左侧返回按钮Image($r(app.media.ic_back)).width(24).height(24).onClick(()this.onBack())// 中间标题Text(this.title).fontSize(18).fontWeight(FontWeight.Bold).fontColor(this.isDarkMode?#FFFFFF:#333333)Blank()// 右侧可选操作if(this.rightText.length0){Text(this.rightText).fontSize(14).fontColor(#007AFF).onClick(()this.onRightClick())}}.padding({left:16,right:16,top:12,bottom:12}).width(100%).backgroundColor(this.isDarkMode?#1A1A1A:#FFFFFF)}}三、项目代码案例3.1 CommonHeader 通用标题栏在products/entry/src/main/ets/components/CommonHeader.ets中CommonHeader 封装了统一的导航栏。该组件在 BillDetailPage、AssetDetailPage、SettingPage 等多个页面中复用保证了导航栏的视觉统一。3.2 AssetSummaryCard / AssetCard 业务卡片在资产模块中业务卡片组件封装了资产数据展示的公共逻辑AssetSummaryCard展示资产总览摘要总资产、净资产等汇总指标AssetCard展示单个资产项目名称、金额、账期信息这些组件通过Param接收AssetGroupModel或AssetItemModel数据对象渲染出统一的卡片 UI。3.3 组件定义示例ComponentV2exportstruct AssetCard{ParamassetData:AssetGroupModelnewAssetGroupModel()ParamonTap:(id:number)void(){}build(){Column(){Text(this.assetData.name).fontSize(16).fontWeight(FontWeight.Bold)Text(¥${this.assetData.amount.toFixed(2)}).fontSize(24)}.gesture(TapGesture().onAction((){this.onTap(this.assetData.id)})).padding(16).backgroundColor(Color.White).borderRadius(12)}}四、最佳实践总结优先使用 ComponentV2新一代装饰器性能更好、语法更简洁。Param 与 Local 职责分明外部数据用Param内部状态用Local。单向数据流父传子通过 props子传父通过回调。组件粒度适中过细则文件碎片化过粗则不可复用。保持 props 不可变子组件不修改传入的数据确保数据流可预测。接口归一化推荐传入完整 Model 对象而非零散字段。五、参考文档自定义组件最佳实践ComponentV2 装饰器说明Param 装饰器