还在为每个弹窗写 CustomDialog？鸿蒙通用弹窗组件 HappyDialog 从想法到落地

还在为每个弹窗写 CustomDialog？鸿蒙通用弹窗组件 HappyDialog 从想法到落地

源码已开源：AppCustomizationDemo/HappyDialog

做鸿蒙应用开发，弹窗这块儿是最让人头疼的重复劳动。确认框、提示框、输入框、底部操作表、隐私协议……官方CustomDialogController确实强大，但每个弹窗都要新建@CustomDialog组件、定义布局、管理控制器、处理生命周期，代码冗长且容易出错。更麻烦的是，弹窗内容需要动态变化（倒计时、进度）时，只能关闭再打开，体验差还易出 bug。

能不能用数据描述弹窗，让组件自动渲染，并且支持静态/动态双模式？这就是HappyDialog要解决的问题。

一、痛点：官方弹窗的“重复造轮子”

先看一段官方典型用法：

@CustomDialogstruct MyConfirmDialog{controller:CustomDialogController;title:string='';content:string='';onConfirm:()=>void=()=>{};build(){Column(){Text(this.title).fontSize(18).fontWeight(FontWeight.Medium)Text(this.content).fontSize(14).margin({top:10})Row(){Button('取消').onClick(()=>this.controller.close())Button('确认').onClick(()=>{this.onConfirm();this.controller.close();})}.justifyContent(FlexAlign.SpaceAround).width('100%')}.padding(24).width('80%')}}// 调用处letdialogController=newCustomDialogController({builder:MyConfirmDialog({...})});dialogController.open();

每个弹窗都要重复这些步骤：

• 新建@CustomDialog组件，手写布局、样式、按钮事件
• 在页面中创建CustomDialogController实例
• 手动管理open()/close()，多个弹窗时容易重叠或内存泄漏
• 动态内容（倒计时、进度）只能关闭重建，代码复杂且体验差
• 样式（圆角、颜色、宽度）硬编码在组件中，深色模式适配或设计改版时逐个修改

每个页面、每种弹窗类型都在重复造轮子——这是工程化的大忌。

二、HappyDialog 设计目标

三、技术亮点：分层设计与响应式更新

3.1 数据驱动与可观察状态

核心思想：用数据描述弹窗，UI 根据数据自动渲染。

• 使用@ObservedV2+@Trace装饰数据模型的属性，使其成为可观察状态。属性改变时，依赖该属性的 UI 自动重新渲染。
• 数据模型StandardDialogModel包含所有可变内容：标题、内容、按钮数组、按钮排列方向、按钮高度、取消/确认按钮颜色等。
• 按钮数组中的每个按钮也是可观察对象：ButtonItemModel类使用@ObservedV2和@Trace装饰其text和color属性，因此直接修改model.buttons[0].text = '新文字'即可触发 UI 刷新，无需整体替换数组。

3.2 动态 UI 绑定：mutableBuilder

wrapBuilder只能静态封装@Builder，无法在运行时切换。而mutableBuilder（API 22+）返回的MutableBuilder对象支持动态替换@Builder。

DialogComponent根据弹窗类型（STANDARD、ALERT、BOTTOM_SHEET）选择不同的 UI 构建器，同时保持对数据模型的引用，实现响应式刷新。

3.3 数据与样式职责分离

为了避免歧义，将字段明确分为两类：

这样弹窗的行为和外观互不干扰，开发者可以灵活组合。

四、快速上手

4.1 安装与初始化

"dependencies":{"@happy/dialog":"file:./happy_dialog"}

在EntryAbility中初始化一次：

import{HappyDialog}from'@happy/dialog';exportdefaultclassEntryAbilityextendsUIAbility{onCreate(){HappyDialog.init(this.context);// 仅需一次}}

4.2 静态弹窗（最常用）

// 最简单的提示，单个按钮（相当于 Alert）HappyDialog.showStandard({title:'提示',content:'操作成功',buttons:[{text:'知道了',onClick:()=>console.log('关闭')}]});

// 带取消/确认的双按钮弹窗，自定义样式HappyDialog.showStandard({title:'删除确认',content:'此操作不可恢复，确定删除吗？',buttons:[{text:'取消',color:'#8A8F93',onClick:()=>console.log('取消')},{text:'删除',color:'#FF3B30',onClick:()=>console.log('删除')}],buttonDirection:'column',// 按钮上下排列buttonHeight:52,style:{width:'90%',cornerRadius:24,titleColor:'#FF3B30'// 覆盖默认标题颜色}});

4.3 动态弹窗（内容实时刷新）

创建StandardDialogModel实例，之后修改其@Trace属性，弹窗 UI 会自动更新。下面演示一个倒计时弹窗，按钮文字每秒变化：

import{HappyDialog,StandardDialogModel}from'@happy/dialog';constmodel=newStandardDialogModel({title:'倒计时演示',content:'5 秒后自动关闭',buttons:[{text:'5s',onClick:()=>{}}]// 初始按钮文字});HappyDialog.showStandard(model);letseconds=5;consttimer=setInterval(()=>{if(seconds===0){clearInterval(timer);model.content='倒计时结束';model.buttons[0].text='知道了';// ✅ 直接修改按钮文字，UI 自动刷新！}else{model.content=`${seconds}秒后关闭`;model.buttons[0].text=`${seconds}s`;// ✅ 每秒更新按钮文字seconds--;}},1000);

效果：弹窗显示后，内容每秒更新，按钮文字从 “5s” → “4s” → … → “0s” → “知道了”，整个过程无需手动刷新或重建弹窗。

💡 动态更新原理：buttons数组中的每个元素都是ButtonItemModel实例，其text和color被@Trace装饰，因此直接修改属性即可触发 UI 重新渲染。

4.4 运行效果

五、核心代码解读

5.1 分层架构

┌─────────────────────────────────────────────────┐ │ 调用层：HappyDialog.showStandard(data) │ └─────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────┐ │ 入口层：HappyDialog（静态方法，全局单例） │ └─────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────┐ │ 视图模型层：DialogViewModel（管理弹窗生命周期） │ └─────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────┐ │ 视图层：DialogComponent + Builder（UI 渲染） │ └─────────────────────────────────────────────────┘ │ ┌─────────────────────────────────────────────────┐ │ 模型层：BaseDialog, StandardDialogModel（数据） │ └─────────────────────────────────────────────────┘

5.2 可观察按钮模型

// model/ButtonItemModel.ets@ObservedV2exportclassButtonItemModelimplementsButtonItem{@Tracetext:ResourceStr;@Tracecolor?:ResourceColor;onClick?:()=>void;constructor(init:ButtonItem){this.text=init.text;this.color=init.color;this.onClick=init.onClick;}}

5.3 基础样式接口（所有弹窗共用）

// interface/BaseStyle.etsexportinterfaceBaseStyle{alignment?:DialogAlignment;maskColor?:ResourceColor;autoCancel?:boolean;isModal?:boolean;width?:Length;cornerRadius?:number;contentPadding?:number;}

5.4 标准弹窗样式接口（继承基础样式）

// interface/standard/StandardStyle.etsexportinterfaceStandardStyleextendsBaseStyle{titleColor?:ResourceColor;contentColor?:ResourceColor;}

5.5 标准弹窗数据接口

// interface/standard/StandardData.etsexportinterfaceStandardDataextendsBaseDialogData{buttons:ButtonItem[];buttonDirection?:'row'|'column';buttonHeight?:number;cancelButtonColor?:ResourceColor;confirmButtonColor?:ResourceColor;style?:StandardStyle;}

5.6 可观察数据模型

// model/StandardDialogModel.ets@ObservedV2exportclassStandardDialogModelextendsBaseDialogimplementsStandardData{@Tracetitle?:ResourceStr;@Tracecontent:ResourceStr='';@Tracebuttons:ButtonItemModel[]=[];// ✅ 元素是可观察的 ButtonItemModel@TracebuttonDirection?:'row'|'column'='row';@TracebuttonHeight?:number=48;@TracecancelButtonColor?:ResourceColor;@TraceconfirmButtonColor?:ResourceColor;@Tracestyle?:StandardStyle;constructor(init:StandardData){super(DialogType.STANDARD);// 将传入的普通 ButtonItem 转换为 ButtonItemModelthis.buttons=init.buttons?.map(btn=>newButtonItemModel(btn))??[];// ... 其他属性赋值}}

5.7 容器组件：动态 Builder 绑定

// components/DialogComponent.ets@ComponentV2exportstruct DialogComponent{@Param@Requiremodel:BaseDialog;@LocalcontentBuilder?:MutableBuilder<[BaseDialog]>;aboutToAppear(){switch(this.model.type){caseDialogType.STANDARD:// 使用 mutableBuilder 动态绑定标准弹窗的 UI 构建器this.contentBuilder=mutableBuilder(standardContentBuilder);break;// 未来可扩展其他类型}}build(){Column(){this.contentBuilder?.builder(this.model);}.width(this.model.style?.width).backgroundColor($r('app.color.background_color')).borderRadius(this.model.style?.cornerRadius??16)}}

5.8 UI 构建器（standardContentBuilder）

// builders/StandardContentBuilder.ets@BuilderexportfunctionstandardContentBuilder(model:StandardDialogModel){Column(){// 内容区域：标题 + 内容Column(){if(model.title){Text(model.title).fontSize($r('app.float.modal_title_font_size')).fontWeight(FontWeight.Medium).fontColor(model.style?.titleColor??$r('app.color.title_color'))}Text(model.content).fontSize($r('app.float.modal_content_font_size')).fontColor(model.style?.contentColor??$r('app.color.content_color'))}.padding(model.style?.contentPadding??20)Divider().strokeWidth(0.5)// 按钮区域：根据 buttonDirection 决定行/列布局if(model.buttonDirection==='column'){Column(){ForEach(model.buttons,(item:ButtonItemModel,index)=>{Button(item.text).width('100%').height(model.buttonHeight??48).backgroundColor(Color.Transparent).fontColor(item.color??(index===0?model.cancelButtonColor:model.confirmButtonColor)).onClick(()=>{item.onClick?.();HappyDialog.close();})if(index!==model.buttons.length-1)Divider()})}}else{Row(){ForEach(model.buttons,(item:ButtonItemModel,index)=>{Button(item.text).layoutWeight(1).height(model.buttonHeight??48).backgroundColor(Color.Transparent).fontColor(item.color??(index===0?model.cancelButtonColor:model.confirmButtonColor)).onClick(()=>{item.onClick?.();HappyDialog.close();})if(index!==model.buttons.length-1)Divider().vertical(true)})}}}.backgroundColor($r('app.color.background_color'))}

5.9 视图模型：管理弹窗生命周期

// viewmodel/DialogViewModel.etsexportclassDialogViewModel{privatecurrentContent:ComponentContent<object>|null=null;asyncshowStandard(data:StandardData|StandardDialogModel){letmodel=datainstanceofStandardDialogModel?data:newStandardDialogModel(data);// 合并默认样式与用户自定义样式model.style=mergeStyle({...DEFAULT_STANDARD_STYLE},model.style??{});constbuilder=mutableBuilder(DialogBuilder);awaitthis.showDialogInternal(model,builder,model.style);}privateasyncshowDialogInternal<TextendsBaseDialog>(model:T,builder:MutableBuilder<[T]>,style:BaseStyle){constuiContext=awaitgetCurrentUIContext();awaitthis.close();// 关闭前一个弹窗constcontentNode=newComponentContent(uiContext,builder,model);this.currentContent=contentNode;awaituiContext.getPromptAction().openCustomDialog(contentNode,{alignment:style.alignment??DialogAlignment.Center,maskColor:style.maskColor??'rgba(0,0,0,0.4)',autoCancel:style.autoCancel??false,isModal:style.isModal??true,// ... 生命周期回调});}asyncclose(){/* 关闭当前弹窗 */}}

5.10 对外接口（HappyDialog）

// HappyDialog.etsexportclassHappyDialog{staticinit(context:common.UIAbilityContext){setAbilityContext(context);}staticasyncshowStandard(data:StandardData|StandardDialogModel){awaitviewModel.showStandard(data);}staticasyncclose(){awaitviewModel.close();}}

六、扩展新弹窗类型（以底部操作表为例）

虽然标准弹窗已覆盖多数场景，但若需增加底部操作表，只需遵循相同模式：

1. 定义BottomSheetData接口（包含title,items等）
2. 创建BottomSheetDialogModel继承BaseDialog，用@Trace标记动态字段
3. 编写bottomSheetContentBuilderUI 构建器
4. 在DialogComponent的aboutToAppear中添加case DialogType.BOTTOM_SHEET
5. 在HappyDialog中添加showBottomSheet方法

核心管理逻辑完全复用，符合开闭原则。

七、总结与避坑指南

常见问题

Q：如何动态修改按钮文字或颜色？
A：直接修改model.buttons[index].text或model.buttons[index].color即可，因为每个按钮都是ButtonItemModel可观察对象。示例：model.buttons[0].text = '新文字'。

Q：为什么不支持style内部属性的动态更新？
A：样式通常属于静态配置，如宽度、圆角等，运行时很少改变。如果确实需要动态改变样式，可以整体替换model.style对象。

Q：mutableBuilder要求的最低 API 版本？
A：mutableBuilder从 API 22 开始支持。如果你的应用需要支持更低版本，可以提前注册所有 Builder 类型，但建议最低 API 22。

Q：如何实现全局 loading 弹窗？
A：可以创建一个没有按钮、内容为加载动画的StandardDialogModel，并通过@Trace控制显示/隐藏。或者扩展一个新的LoadingDialog类型。

Q：为什么传入的buttons数组会自动变成ButtonItemModel[]？
A：StandardDialogModel的构造函数会将普通对象转换为ButtonItemModel实例，确保每个按钮都具备可观察能力。如果你手动创建StandardDialogModel并传入ButtonItemModel[]，也会被原样保留。

八、结语

HappyDialog 的核心价值在于数据驱动 + 样式分离，让你从繁琐的弹窗模板代码中解放出来，专注于业务逻辑。无论你是需要快速搭建一个确认框，还是实现一个带有倒计时、进度更新的复杂弹窗，只需几行配置即可完成。

鸿蒙开发，从“重复造轮子”到“专注于业务”，HappyDialog 希望能帮你迈出这一步。如果你在使用中遇到任何问题，或者有更好的想法，欢迎在评论区交流。