HarmonyOS Next应用分层架构下组件封装开发实践

基于鸿蒙应用分层架构的ArkUI组件封装实践

在鸿蒙应用开发中，合理利用 ArkUI 组件进行封装，可以实现代码复用，提升开发效率。本文将结合鸿蒙应用分层架构的特点，详细探讨几个典型的 ArkUI 组件封装场景及其实现方案。

华为鸿蒙应用分层架构概览

鸿蒙应用架构分层：将应用划分为产品定制层、基础特性层和公共能力层，可以降低层间的依赖性，从而提升代码的可维护性。通过分层架构设计进一步明确了每层的职责和层间的交互机制，为开发者呈现了一个清晰且结构化的开发框架，通过封装可复用的组件，为上层业务逻辑提供支持。

一、公用组件封装

在应用开发中，不同业务场景常需要相同功能和样式的 ArkUI 组件，例如统一的登录按钮或弹窗按钮。以 Button 组件为例，封装统一的样式和逻辑后，可提供给不同业务团队使用。

封装方案探讨

传统方法是通过自定义组件，并将通用逻辑抽取封装。但此方法存在一些问题，如使用方式与系统组件不一致、自定义组件入参过大、不利于后期维护。

为解决这些问题，ArkTS 提供了 attributeModifier 属性方法。通过自定义 Class 类实现 AttributeModifier 接口，可对系统组件属性进行扩展。

实现方案对比

方案一：适用于组合多个系统组件的场景。提供方创建自定义组件并导出，同时接受外部传入的 AttributeModifier 类实例。

方案二：适用于单一类型组件的场景。提供方直接创建 AttributeModifier 接口实现类，并导出供使用方调用。

二、分层架构介绍和实现

产品定制层

产品定制层的各个子目录会被编译成一个Entry类型的HAP，作为应用的主入口。该层面向多种设备，集成相应功能和特性。产品定制层划分为多个功能模块，每个模块针对特定设备或使用场景设计，并根据产品需求进行功能和交互的定制开发。在产品定制层，开发者可以从不同设备对应的应用UX设计和功能两个维度，结合具体的业务场景，选择一次编译生成相同或者不同的HAP（或其组合）。通过使用定制多目标构建产物的定制功能，可以将应用所对应的HAP编译成各自的.app文件，用于上架到应用市场。

基础特性层

在基础特性层中，功能模块根据部署需求被分为两类。对于需要通过Ability承载的功能，可以设计为Feature类型的HAP，而对于不需要通过Ability承载的功能，根据是否需要实现按需加载，可以选择设计为HAR模块或者HSP模块，编译后对应HAR包或者HSP包。

公共能力层

公共能力层的各子目录将编译成HAR包，仅产品定制层和基础特性层可依赖，不允许反向依赖。该层提取模块化公共基础能力，为上层提供标准接口和协议，提高复用率和开发效率。

应用分层架构实现

此次我们的组件封装就是在common文件中的compontHAR静态共享包中，需要将自定义组件在HAR的index.ets中导出组件，在使用方的oh-package.json5文件中引入

三、公用组件封装

基础组件封装

场景描述
在应用开发过程中，不同的业务场景可能需要使用相同功能或样式的ArkUI组件。例如，登录页面登录按钮和购物页面结算按钮可能样式相同。该场景常用方法是抽取相同样式的逻辑部分，并将其封装成一个自定义组件到公共组件库中。在业务场景开发时，统一从公共组件库获取封装好的公用组件。
ArkTS为每个系统组件提供了attributeModifier属性方法。该方法将组件属性设置分离到系统提供的AttributeModifier接口实现类实例中，通过自定义Class类实现AttributeModifier接口对系统组件属性进行扩展.

使用wrapBuilder方法有以下限制：

wrapBuilder方法只支持传入全局@Builder方法。
wrapBuilder方法返回的WrappedBuilder对象的builder属性方法只能在struct内部使用。

/*** @FileName : BaseButtonAttributeModifier* @Author : kirk.wang* @Time : 2025/5/16 10:23* @Description : 基础组件Button封装*/
//创建AttributeModifier接口的实现类
export class BaseButtonAttributeModifier implements AttributeModifier<ButtonAttribute> {// 私有定义Button组件特有属性private _buttonType: ButtonType = ButtonType.Normal;private _enabled: boolean = false;// 实现组件的普通状态下的样式方法，系统还提供了hover状态和其他状态下的样式方法applyNormalAttribute(instance: ButtonAttribute): void {instance.type(this._buttonType).stateEffect(true).fontSize(16).height(48).enabled(this._enabled)}// 链式配置方法type(buttonType: ButtonType): BaseButtonAttributeModifier {this._buttonType = buttonType;return this;}enabled(enabled: boolean): BaseButtonAttributeModifier {this._enabled = enabled;return this;}
}

使用方创建提供方的AttributeModifier实现类实例，并作为系统组件attributeModifier属性方法的参数传入。

/*** @FileName : GQButton* @Author : kirk.wang* @Time : 2025/5/16 15:35* @Description : 自定义Button组件*/
// src/main/ets/pages/CommonComponent.ets
import { BaseButtonAttributeModifier } from "./BaseButtonAttributeModifier";//提供方自定义组件并导出
@Component
export struct GQButton {@Prop text: string = '';// 接受外部传入的AttributeModifier类实例@Prop modifier: BaseButtonAttributeModifier;build() {Button(this.text)// 将入参的AttributeModifier类实例与系统组件绑定.attributeModifier(this.modifier).fontSize(20).width(200).height(50)}
}

通过以上方案，使组件封装更灵活，也保持了与系统组件一致的使用方式。

组合组件封装

在实际应用开发中，会有需要抽取复用的组件为多个系统组件的组合是情况，比如新闻APP，新闻列表的item就需要经常被使用，就需要封装一个。
封装自定义组件MediaCard并导出：

/*** @FileName : MediaCard* @Author : kirk.wang* @Time : 2025/5/16 15:05* @Description : 复合组件封装-图片文本组件*/
@Component
export struct MediaCard {@Prop imageSrc: PixelMap | ResourceStr | DrawableDescriptor;@Prop title: string;@Prop content: string;@Prop imageModifier: AttributeModifier<ImageAttribute>;@Prop titleModifier: AttributeModifier<TextAttribute>;@Prop contentModifier: AttributeModifier<TextAttribute>;build() {Column({ space: 8 }) {Image(this.imageSrc).attributeModifier(this.imageModifier)Text(this.title).attributeModifier(this.titleModifier)Text(this.content).attributeModifier(this.contentModifier)}.padding(12).backgroundColor(Color.White).borderRadius(8)}
}export class ImageModifier implements AttributeModifier<ImageAttribute> {// 实现 AttributeModifier 接口private imageWidth: Length = 0;private imageHeight: Length = 0;constructor(width: Length, height: Length) {this.imageWidth = width;this.imageHeight = height;}width(width: Length) {this.imageWidth = width;return this;}height(height: Length) {this.imageHeight = height;return this;}applyNormalAttribute(instance: ImageAttribute): void {instance.width(this.imageWidth);instance.height(this.imageHeight);instance.borderRadius($r('app.float.padding_borderRadius'))}
}export class TextModifier {private _fontSize: number | string | Resource| null = 14;constructor(fontSize?: number | string | Resource) {if(fontSize!==null){this._fontSize = fontSize!;}}fontSize(fontSize: number | string | Resource): TextModifier {this._fontSize= fontSize;return this;}applyNormalAttribute(instance: TextAttribute): void {instance.fontSize(this._fontSize);}
}

导出自定义组件：

export { MediaCard,TextModifier,ImageModifier } from './src/main/ets/components/MediaCard';

使用：

import {BaseButtonAttributeModifier,GQButton,MediaCard,ImageModifier,TextModifier,DialogUtils,factoryMap
} from "component";
@Component
export struct HomePage {build() {NavDestination() {MediaCard({imageModifier: this.imagesAttribute,titleModifier: this.titleAttribute,contentModifier: this.contentAttribute,imageSrc: $r('app.media.icon_header'),title: 'title',content: 'content'})
}
```ets
### 自定义弹窗封装1. 使用方通过全局 @Builder 封装弹窗结构，定义弹窗的内容和样式。
2. 提供方通过 UIContext 获取 PromptAction 对象，封装弹窗工具类。
3. 提供方创建打开和关闭弹窗的接口，使用方通过调用这些接口实现弹窗的显示和隐藏。以下是弹窗工具类实现代码：```ets
// 提供方封装的弹窗工具类
/*** @FileName : DialogUtils* @Author : kirk.wang* @Time : 2025/5/16 16:25* @Description : 封装弹窗的工具类*/
import { ComponentContent, promptAction } from '@kit.ArkUI';
export class DialogUtils{private static dialog:DialogUtils;private data:PopViewModel[] = new Array<PopViewModel>;static getInstance(): DialogUtils {if (!DialogUtils.dialog) {DialogUtils.dialog = new DialogUtils();}return DialogUtils.dialog;}//通过openCustomDialog创建打开弹窗的showDialog函数。static showDialog<T extends object>(type: PopViewShowType, contentView: WrappedBuilder<[T]>, args: T,options?: promptAction.BaseDialogOptions):void {let uiContext = AppStorage.get<UIContext>('uiContext');if (uiContext) {// The promptAction object was obtained.let prompt = uiContext.getPromptAction();let componentContent = new ComponentContent(uiContext, contentView, args);let customOptions: promptAction.BaseDialogOptions = {alignment: options?.alignment || DialogAlignment.Bottom};// Open pop-ups using openCustomDialogprompt.openCustomDialog(componentContent, customOptions);let data = DialogUtils.getInstance().data;let info: PopViewModel = {com: componentContent,popType: type};data[0] = info;}}
//通过closeCustomDialog创建关闭弹窗的closeDialog函数static closeDialog(popType:PopViewShowType):void{let context = AppStorage.get<UIContext>('uiContext');if(context){let prompt = context.getPromptAction();let sameTypeList = DialogUtils.getInstance().data.filter((model) => {return model.popType === popType;})let info = sameTypeList[sameTypeList.length - 1];if (info.com) {DialogUtils.getInstance().data = DialogUtils.getInstance().data.filter((model) => {return model.com !== info.com;})prompt.closeCustomDialog(info.com);}}}static showPopView<T extends object>(contentView: WrappedBuilder<[T]>, args: T,options?: promptAction.BaseDialogOptions):void {DialogUtils.showDialog(PopViewShowType.OPEN, contentView, args, options);}static closePopView():void {DialogUtils.closeDialog(PopViewShowType.OPEN);}
}
interface PopViewModel {com: ComponentContent<object>;popType: PopViewShowType;
}export enum PopViewShowType {OPEN
}
//使用DialogUtils.showPopView<Object>(wrapBuilder(buildDialogView), new Object(),{ alignment: DialogAlignment.Center });
//构建buildDialogView
@Builder
export function buildDialogView(_obj: Object) {Column({ space: 16 }) {Text($r('app.string.tips')).fontSize(16).fontWeight(FontWeight.Bold)Text($r('app.string.content')).fontSize(16)Row() {Button($r('app.string.cancel')).fontColor(Color.Blue).backgroundColor(Color.White).margin({ right: 10 }).width('42%').onClick(() => {DialogUtils.closePopView();})Button($r('app.string.confirm')).width('42%').onClick(() => {DialogUtils.closePopView();})}.justifyContent(FlexAlign.Center).width(328)}.padding(18).justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center).backgroundColor(Color.White).borderRadius($r('app.float.border_radius'))
}

弹窗组件的封装更加简洁高效，使用方可以快速实现自定义弹窗。

三、组件工厂类封装

当需要为不同的业务需求提供多种组件时，组件工厂类封装是一种有效的解决方案。

实现流程优化

1. 在组件工厂实现方，通过全局 @Builder 方法封装需要工厂化的组件。

2. 将封装好的 @Builder 方法使用 wrapBuilder 函数包裹，并存入 Map 结构中，其中 key 为组件名，value 为 WrappedBuilder 对象。

3. 在使用方，通过组件工厂的 key 值获取对应的 WrappedBuilder 对象，并在 build 方法中调用其 builder 属性方法获取组件。
   以选择月份的组件为例，项目种有多个地方需要选择月份，那么以下是组件工程封装的实现代码：

// 组件工厂实现方
/*** @FileName : FactoryMap* @Author : kirk.wang* @Time : 2025/5/18 00:50* @Description :月份选择组件*/
let mothList = ["1","2","3","4","5","6","7","8","9","10","11","12"];
@Builder
function monthRadio() {Text($r('app.string.month')).width('100%').fontColor($r('sys.color.mask_secondary'))List(){ForEach(mothList, (item: string, index: number) => {ListItem(){Row() {Radio({ value: `${index}`, group: 'radioGroup' })Text(`${item}月`)}.width('100%')}});}}// 创建组件工厂的集合
let factoryMap: Map<string, object> = new Map();//把需要的工厂存储在组件工厂中的组件。
factoryMap.set('monthRadio', wrapBuilder(monthRadio));// Export assembly factory
export { factoryMap };//使用 HomePage.ets
import { factoryMap} from "component";@Component
export struct HomePage {monthRadio: WrappedBuilder<[]> = factoryMap.get('monthRadio') as WrappedBuilder<[]>;build() {NavDestination() {this.monthRadio.builder();}
}

四、总结与展望

在鸿蒙应用分层架构下进行 ArkUI 组件封装，可以提高开发效率和代码复用率。通过合理利用 ArkTS 提供的 attributeModifier 属性方法、PromptAction 对象以及组件工厂模式，可以实现灵活、高效的组件封装。未来，随着鸿蒙应用生态的发展，组件封装技术将不断完善。开发者们可以探索更多创新的封装方式，为鸿蒙应用开发提供更强大的支持。

四、Demo代码仓

https://gitcode.com/kirkWang/componentMaster