引言弹窗是应用中常见的 UI 组件用于打开应用时自动弹出或响应用户操作时弹出在短时间内展示需要用户关注的信息或待处理操作。HarmonyOS 提供了丰富的弹窗能力主要分为固定样式弹窗和自定义弹窗两类。本节课将系统讲解弹窗的基础概念、常见固定样式弹窗的分类与使用方法以及自定义弹窗的实现逻辑。核心内容弹窗基础概述弹窗定义弹窗是打开应用时自动弹出或响应用户操作时弹出的 UI 界面用于短时间展示需要用户关注的信息或待处理操作。弹窗分类对比对比维度固定样式弹窗自定义弹窗样式固定样式与系统一致根据应用需求自定义设计交互方式标准化交互如确定、取消按钮可完全自定义交互逻辑内容复杂度简单开发者可直接调用 API复杂可包含多种交互元素常见固定样式弹窗分类与用途即时反馈Toast用途向用户显示简短的操作反馈或状态信息。特点临时性提示通常在屏幕顶部/底部短暂弹出后自动消失不干扰用户当前操作流程示例为保存成功提示。使用注意事项合理控制使用频率避免频繁弹出打扰用户。控制文本长度展示时间有限避免内容过长。禁止违规内容展示。遵循系统默认展示位置。警告弹窗AlertDialog用途展示用户当前必须关注的信息或操作常用于敏感操作的二次确认。注意警告弹窗会中断用户当前操作仅在必要场景使用避免仅用警告弹窗展示不可操作的纯信息会打断用户操作流程。示例未保存数据退出时的确认弹窗。列表选择弹窗ActionSheet用途当需要确认的信息为列表选择项时使用适合仅需展示操作列表无其他内容的场景。选择器弹窗PickerDialog用途用户需要在弹窗内选择日期、时间或文本时使用包含日期滑动选择器弹窗DatePickerDialog、文本滑动选择器弹窗TextPickerDialog子类。示例为出生日期选择弹窗。操作菜单showActionMenu用途用户执行长按、手势等特定操作时弹出提供和当前上下文相关的操作选项让用户快速访问常用功能无需跳转其他界面。固定样式弹窗使用规范核心优势采用固定布局开发者无需关心布局细节仅需传入显示内容简化开发流程提升便捷性。使用约束弹窗的弹出依赖 UI 执行上下文不可在 UI 上下文不明确的位置使用。开发步骤导入对应公共 JS 模块。获取PromptAction上下文对象。调用对应显示方法传入配置参数即可显示。即时弹窗开发使用即时反馈分为三个步骤// 1. 导入 common 模块 // 2. 获取上下文对象 // 3. 调用 showToast promptAction.showToast({ message: 保存成功, duration: 2000 });即时反馈提供两种显示模式Default模式不会创建子窗口显示在主窗口内层级和主窗口一致。Topmost模式会创建子窗口显示层级比主窗口更高。两种模式对软键盘的适配逻辑也有区别。警告弹窗开发promptAction.showAlertDialog({ title: 提示, message: 确定要退出吗, buttons: [ { text: 取消, color: #666 }, { text: 确定, color: #007dff } ] });日期滑动选择器弹窗入参中可设置选择的起始日期、结束日期默认选中日期还可以设置是否显示日历切换开关。change回调方法在点击确定按钮时触发返回选中的日期结果。文本滑动选择器弹窗入参中传入待选择的文本数组设置默认选中项可配置是否开启循环滚动。选中回调方法在点击确定按钮触发变更回调在文本选择变化时触发。列表选择弹窗可配置弹窗标题、默认焦点、按钮风格、文本内容、点击回调每个选择项都支持单独配置选中回调。操作菜单入参中可配置弹窗标识、菜单选项、点击回调处理。自定义弹窗基础定义开发者根据特定需求设计实现的弹窗样式、布局、内容、交互行为都可个性化定制满足特殊业务场景需求。示例多选兴趣爱好的选择弹窗。核心 API 说明通过promptAction.openCustomDialog()接口创建显示自定义弹窗。核心参数dialogContent自定义弹窗展示的组件内容类型为ComponentContent支持灵活封装自定义 UI满足各类布局需求。options弹窗样式配置类型为CustomDialogOptions可配置对齐方式、弹窗尺寸、是否允许点击遮罩关闭、软键盘自动避让等属性。动态更新调用promptAction.updateCustomDialog()可以动态更新弹窗内容与样式。// 打开自定义弹窗 promptAction.openCustomDialog({ dialogContent: new ComponentContent(this.context, wrapBuilder(CustomDialogBuilder)), options: { alignment: DialogAlignment.Center, isModal: true, autoCancel: false } }); // 动态更新弹窗内容 promptAction.updateCustomDialog({ dialogContent: new ComponentContent(this.context, wrapBuilder(UpdatedDialogBuilder)), options: { alignment: DialogAlignment.Top } }); // 关闭自定义弹窗 promptAction.closeCustomDialog();开发步骤自定义弹窗组件实现需要的内容布局与交互逻辑可自定义关闭弹窗业务逻辑。获取应用上下文与PromptAction对象。调用openCustomDialog()传入自定义内容与配置打开弹窗。需要关闭时调用对应关闭接口即可。总结本节课系统讲解了 HarmonyOS 弹窗开发的核心知识弹窗基础概念弹窗是展示需要用户关注的信息或操作的 UI 组件分为固定样式弹窗和自定义弹窗两类。固定样式弹窗系统提供的标准化弹窗包含即时反馈Toast、警告弹窗AlertDialog、列表选择弹窗ActionSheet、选择器弹窗PickerDialog、操作菜单showActionMenu五种类型。使用时需遵循对应的使用规范和约束。自定义弹窗开发者可根据需求自主设计样式与交互通过openCustomDialog打开、updateCustomDialog动态更新、closeCustomDialog关闭可承载复杂内容和功能。