极简弹窗封装，基于 @kit.ArkUI 封装通用工具类

在日常鸿蒙开发中，弹窗是最高频的交互组件之一：操作反馈用 Toast、二次确认用对话框、加载状态用等待框、多选操作用底部菜单。原生@kit.ArkUI虽然提供了完整的弹窗能力，但每次调用都要重复写参数、统一样式麻烦，页面多了之后维护成本很高。

本文带你基于鸿蒙官方原生 API，封装一套零依赖、可直接复用的通用弹窗工具类，涵盖 Toast、确认对话框、加载框、底部操作菜单四大高频场景，一行代码即可调用，全局样式统一，新手也能快速上手。

一、为什么要做统一弹窗封装？

零散调用原生 API 看似简单，项目迭代起来会暴露很多问题：

1. 重复代码多：每次调用都要手写 message、duration、回调等参数，样板代码冗余
2. 样式不统一：不同开发人员写的弹窗圆角、字号、颜色参差不齐，视觉体验割裂
3. 容易出bug：快速重复点击会弹出多层弹窗、页面销毁后未关闭弹窗导致内存泄漏
4. 维护成本高：后续要改弹窗样式，需要逐个页面修改，工作量大且容易遗漏

统一封装后，所有弹窗逻辑收敛到一个工具类，一处修改全项目生效，调用方式极简，能大幅提升开发效率。

二、封装原则与依赖说明

本次封装严格遵循三个原则，保证实用性与兼容性：

• 纯原生实现：全部基于@kit.ArkUI官方 API，无任何第三方依赖，兼容 API 12+ 全版本
• 极简调用：静态方法 + 通用组件，多数场景一行代码即可触发
• 渐进式接入：可以只单独用 Toast，也可以全套接入，不强制绑定
• 防呆设计：内置防抖、防重复弹出逻辑，规避新手常见错误

三、完整工具类实现

新建文件entry/src/main/ets/utils/DialogUtils.ets，以下所有代码都放在这个文件中，复制即可直接使用。

3.1 基础工具：Toast + 底部操作菜单

这两类弹窗不需要额外 UI 组件，直接封装为静态方法，导入即可调用，零配置成本。

import{promptAction}from'@kit.ArkUI';import{hilog}from'@kit.PerformanceAnalysisKit';constTAG='DialogUtils';/** * 通用弹窗工具类 * 基于@kit.ArkUI原生能力封装，零第三方依赖 */exportclassDialogUtils{// Toast防抖标记，避免快速重复调用堆叠privatestaticlastToastTime:number=0;/** * 短Toast提示（显示2秒） * @param message 提示文本 */staticshowToast(message:string):void{constnow=Date.now();if(now-this.lastToastTime<1500)return;this.lastToastTime=now;promptAction.showToast({message:message,duration:2000,bottom:120});}/** * 长Toast提示（显示3.5秒） * @param message 提示文本 */staticshowLongToast(message:string):void{promptAction.showToast({message:message,duration:3500,bottom:120});}/** * 底部操作菜单（ActionSheet） * @param title 弹窗标题 * @param options 选项文本数组 * @param onSelect 选中回调，返回选中项索引 * @param onCancel 取消回调 */staticshowActionSheet(title:string,options:string[],onSelect?:(index:number)=>void,onCancel?:()=>void):void{promptAction.showActionSheet({title:title,buttons:options.map(text=>({text:text})),success:(res)=>{if(res.index!==undefined&&onSelect){onSelect(res.index);}},cancel:()=>{onCancel?.();},fail:(err)=>{hilog.error(0x0000,TAG,`ActionSheet调用失败:${JSON.stringify(err)}`);}});}}

3.2 通用确认对话框

基于@CustomDialog封装标准化确认框，支持自定义标题、内容、按钮文字与颜色，统一项目内二次确认交互样式。

/** * 通用确认对话框组件 */@CustomDialogexportstruct ConfirmDialog{// 弹窗标题title:string='提示';// 弹窗正文内容content:string='';// 取消按钮文字cancelText:string='取消';// 确认按钮文字confirmText:string='确定';// 确认按钮主题色confirmColor:string='#0A59F7';// 取消回调onCancel?:()=>void;// 确认回调onConfirm?:()=>void;build(){Column({space:20}){Text(this.title).fontSize(18).fontWeight(FontWeight.Medium).width('100%').textAlign(TextAlign.Center);Text(this.content).fontSize(15).fontColor('#666666').width('100%').textAlign(TextAlign.Center).lineHeight(22);Row({space:12}){Button(this.cancelText).layoutWeight(1).height(44).borderRadius(22).backgroundColor('#F5F5F5').fontColor('#333333').onClick(()=>{this.controller.close();this.onCancel?.();});Button(this.confirmText).layoutWeight(1).height(44).borderRadius(22).backgroundColor(this.confirmColor).fontColor('#FFFFFF').onClick(()=>{this.controller.close();this.onConfirm?.();});}.width('100%');}.width('85%').padding(24).backgroundColor('#FFFFFF').borderRadius(16);}}

3.3 全局加载弹窗管理器

封装带状态管理的加载弹窗，内置防重复弹出逻辑，全局统一调用，无需每个页面单独维护。

/** * 加载弹窗UI组件 */@CustomDialogstruct LoadingDialog{loadingText:string='加载中...';build(){Column({space:16}){LoadingProgress().width(48).height(48).color('#0A59F7');Text(this.loadingText).fontSize(14).fontColor('#666666');}.padding(24).backgroundColor('#FFFFFF').borderRadius(12);}}/** * 全局加载弹窗管理器 * 单例控制，防止重复弹出 */exportclassLoadingManager{privatestaticcontroller:CustomDialogController|null=null;privatestaticisShowing:boolean=false;/** * 显示加载弹窗 * @param text 加载提示文字 */staticshowLoading(text:string='加载中...'):void{if(this.isShowing)return;this.isShowing=true;this.controller=newCustomDialogController({builder:LoadingDialog({loadingText:text}),autoCancel:false,alignment:DialogAlignment.Center,customStyle:true,backgroundColor:Color.Transparent});this.controller.open();}/** * 隐藏加载弹窗 */statichideLoading():void{if(this.controller&&this.isShowing){this.controller.close();this.isShowing=false;this.controller=null;}}}

四、页面调用完整示例

下面是完整的演示页面，展示四种弹窗的调用方式，代码复制到页面文件即可直接运行。

import{DialogUtils,ConfirmDialog,LoadingManager}from'../utils/DialogUtils';@Entry@Componentstruct DialogDemoPage{// 确认对话框控制器，页面内只需实例化一次privateconfirmDialog:CustomDialogController=newCustomDialogController({builder:ConfirmDialog({title:'温馨提示',content:'确定要删除这条记录吗？删除后无法恢复。',confirmText:'删除',confirmColor:'#FF4D4F',onConfirm:()=>{DialogUtils.showToast('删除成功');},onCancel:()=>{DialogUtils.showToast('已取消操作');}}),alignment:DialogAlignment.Center,customStyle:true,backgroundColor:Color.Transparent});aboutToDisappear(){// 页面销毁时强制关闭加载弹窗，避免泄漏LoadingManager.hideLoading();}build(){Column({space:20}){Text('通用弹窗工具演示').fontSize(28).fontWeight(FontWeight.Bold).width('90%').margin({top:40});// 1. Toast演示Button('普通Toast提示').width('90%').height(50).borderRadius(25).onClick(()=>{DialogUtils.showToast('操作成功');});Button('长Toast提示').width('90%').height(50).borderRadius(25).backgroundColor('#00B578').onClick(()=>{DialogUtils.showLongToast('这是一条较长的提示信息，显示3.5秒');});// 2. 确认对话框演示Button('删除确认对话框').width('90%').height(50).borderRadius(25).backgroundColor('#FF4D4F').onClick(()=>{this.confirmDialog.open();});// 3. 加载弹窗演示Button('显示加载弹窗').width('90%').height(50).borderRadius(25).backgroundColor('#9B59B6').onClick(()=>{LoadingManager.showLoading('数据加载中...');// 模拟2秒网络请求后关闭setTimeout(()=>{LoadingManager.hideLoading();DialogUtils.showToast('加载完成');},2000);});// 4. 底部操作菜单演示Button('底部操作菜单').width('90%').height(50).borderRadius(25).backgroundColor('#F39C12').onClick(()=>{DialogUtils.showActionSheet('请选择操作',['拍照','从相册选择','保存图片'],(index)=>{DialogUtils.showToast(`选中了第${index+1}项`);});});Blank();}.width('100%').height('100%').backgroundColor('#F8F9FA');}}

五、新手高频踩坑与最佳实践

1. 快速重复点击弹出多层弹窗

• 问题：连续点击按钮会弹出多个 Toast 或对话框，堆叠在一起体验很差
• 解决：工具类内置防抖标记位与状态判断，比如 Toast 限制 1500ms 内不能重复触发，加载弹窗通过isShowing防止重复创建

2. 页面销毁后弹窗未关闭报错

• 问题：网络请求过程中退出页面，加载弹窗没关闭，后续回调执行时报空指针异常
• 解决：在页面aboutToDisappear生命周期中强制调用LoadingManager.hideLoading()，确保页面销毁时所有弹窗同步关闭

3. 自定义弹窗背景不透明

• 问题：CustomDialog 默认带系统灰色遮罩，无法实现完全自定义的弹窗样式
• 解决：必须同时设置customStyle: true和backgroundColor: Color.Transparent，才能去掉系统默认遮罩，完全自定义弹窗外观

4. 每个页面重复写对话框控制器

• 优化建议：如果项目中确认框使用非常频繁，可以结合全局状态管理进一步封装，做成全局服务，无需每个页面单独创建控制器

六、进阶扩展方向

这套基础工具类覆盖了 80% 的日常弹窗场景，还可以根据业务需求继续扩展：

1. 自定义 Toast：增加成功/失败图标、顶部弹出、带动画的高级 Toast
2. 输入框对话框：在确认框基础上增加 TextInput，支持文本、密码输入弹窗
3. 中间选择器：封装日期选择、城市选择、枚举选择等通用选择弹窗
4. 全局弹窗队列：多个弹窗按优先级排队显示，避免同时弹出多个互相遮挡

总结

通用弹窗工具类是鸿蒙项目中性价比极高的基建封装：几十行代码就能收敛所有弹窗逻辑，既统一了项目视觉规范，又减少了重复样板代码，还能规避很多新手易犯的低级错误。

对于新手，建议直接复用本文的基础版本，先满足日常开发需求；随着项目迭代，再逐步扩展更多弹窗类型，沉淀成团队专属的 UI 组件库。