弹窗库：Toast、Loading、ActionSheet的统一封装（244）

在鸿蒙（HarmonyOS）应用开发中，系统自带的AlertDialog往往样式单一，而频繁手写CustomDialog又会导致代码冗余。为了实现 Toast、Loading、ActionSheet 的统一封装，目前业界主要有两种主流方案：引入成熟的第三方库和基于原生 API 进行高阶自定义封装。

方案一：引入成熟的第三方库（推荐，开箱即用）

鸿蒙生态中已有非常优秀的零侵入弹窗库，例如@pura/harmony-dialog。它仅需一行代码即可实现各种弹窗，极大提升了开发效率。

1. 安装与全局初始化

ohpm install @pura/harmony-dialog

必须在EntryAbility的onCreate生命周期中初始化上下文，否则调用会报错：

import { DialogUtil } from '@pura/harmony-dialog'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.UIAbilityLaunchParam): void { DialogUtil.init(this.context); } }

2. 统一调用示例

import { DialogUtil } from '@pura/harmony-dialog'; // 1. Toast 轻量提示 DialogUtil.toast('操作成功'); // 2. Loading 加载状态（网络请求时使用） DialogUtil.loading('加载中...'); // 请求结束后关闭 DialogUtil.hideLoading(); // 3. ActionSheet 底部菜单 DialogUtil.actionSheet(['拍照', '从相册选择'], (index: number) => { console.log('选择了第', index, '项'); });

注：该库还支持弹窗队列，多个弹窗依次显示不会互相覆盖，非常适合批量提示场景。

方案二：基于原生 API 的高阶自定义封装

如果项目对 UI 样式有极高的定制要求，或者不希望引入第三方依赖，可以基于鸿蒙最新的UIContext.getPromptAction.openCustomDialog进行全局解耦封装。

核心设计思路：

  1. 页面解耦：使用openCustomDialog代替传统的CustomDialogController，实现全局任意位置调用，无需在页面中绑定组件。
  2. 状态双向绑定：使用$$语法进行布尔值绑定，确保弹窗能正确关闭。
  3. 单例模式：封装一个DialogService统一调度。

1. 封装全局 Toast（利用 setTimeout 自动关闭）

@Builder function buildToast(params: { text: string }) { Text(params.text) .fontSize(16) .fontColor(Color.White) .padding(12) .backgroundColor('#CC000000') .borderRadius(8) } export class DialogService { static showToast(text: string, duration: number = 2000) { const uiContext = AppStorage.get<UIContext>('uiContext')!; const dialog = uiContext.getPromptAction().openCustomDialog( wrapBuilder(buildToast), { data: { text: text } } ); // 定时自动关闭 setTimeout(() => { dialog.close(); }, duration); } }

2. 封装通用 Loading 与 ActionSheet
同样地，将 Loading 的转圈动画（如LoadingProgress）和 ActionSheet 的列表布局封装为@Builder，通过openCustomDialog唤起。对于 Loading，可以通过暴露一个close()方法供业务层在异步请求结束后手动关闭。

鸿蒙弹窗选型决策树

在统一封装时，建议根据业务场景自动匹配最合适的底层 API：

  • 纯反馈提示（如保存成功）：使用Toast。
  • 二次确认（如删除操作）：使用showDialog或AlertDialog。
  • 底部选项/动作面板：使用ActionSheet或bindSheet。
  • 自定义复杂 UI 弹窗：使用openCustomDialog。
  • 全屏遮罩/半模态：使用bindContentCover或bindSheet。