引言

弹窗是应用中常见的 UI 组件，用于打开应用时自动弹出或响应用户操作时弹出，在短时间内展示需要用户关注的信息或待处理操作。HarmonyOS 提供了丰富的弹窗能力，主要分为固定样式弹窗和自定义弹窗两类。本节课将系统讲解弹窗的基础概念、常见固定样式弹窗的分类与使用方法，以及自定义弹窗的实现逻辑。

核心内容

弹窗基础概述

弹窗定义：弹窗是打开应用时自动弹出，或响应用户操作时弹出的 UI 界面，用于短时间展示需要用户关注的信息或待处理操作。

弹窗分类对比：

对比维度	固定样式弹窗	自定义弹窗
样式	固定样式，与系统一致	根据应用需求自定义设计
交互方式	标准化交互（如"确定"、"取消"按钮）	可完全自定义交互逻辑
内容复杂度	简单，开发者可直接调用 API	复杂，可包含多种交互元素

常见固定样式弹窗分类与用途

即时反馈（Toast）

• 用途：向用户显示简短的操作反馈或状态信息。

• 特点：临时性提示，通常在屏幕顶部/底部短暂弹出后自动消失，不干扰用户当前操作流程，示例为保存成功提示。

• 使用注意事项：

  1. 合理控制使用频率，避免频繁弹出打扰用户。

  2. 控制文本长度，展示时间有限避免内容过长。

  3. 禁止违规内容展示。

  4. 遵循系统默认展示位置。

警告弹窗（AlertDialog）

• 用途：展示用户当前必须关注的信息或操作，常用于敏感操作的二次确认。

• 注意：警告弹窗会中断用户当前操作，仅在必要场景使用；避免仅用警告弹窗展示不可操作的纯信息，会打断用户操作流程。示例：未保存数据退出时的确认弹窗。

列表选择弹窗（ActionSheet）

• 用途：当需要确认的信息为列表选择项时使用，适合仅需展示操作列表无其他内容的场景。

选择器弹窗（PickerDialog）

• 用途：用户需要在弹窗内选择日期、时间或文本时使用，包含日期滑动选择器弹窗（DatePickerDialog）、文本滑动选择器弹窗（TextPickerDialog）子类。示例为出生日期选择弹窗。

操作菜单（showActionMenu）

• 用途：用户执行长按、手势等特定操作时弹出，提供和当前上下文相关的操作选项，让用户快速访问常用功能，无需跳转其他界面。

固定样式弹窗使用规范

核心优势：采用固定布局，开发者无需关心布局细节，仅需传入显示内容，简化开发流程，提升便捷性。

使用约束：弹窗的弹出依赖 UI 执行上下文，不可在 UI 上下文不明确的位置使用。

开发步骤：

1. 导入对应公共 JS 模块。

2. 获取 PromptAction 上下文对象。

3. 调用对应显示方法，传入配置参数即可显示。

即时弹窗开发

使用即时反馈分为三个步骤：

// 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();

开发步骤：

1. 自定义弹窗组件，实现需要的内容布局与交互逻辑，可自定义关闭弹窗业务逻辑。

2. 获取应用上下文与 PromptAction 对象。

3. 调用 openCustomDialog() 传入自定义内容与配置打开弹窗。

4. 需要关闭时调用对应关闭接口即可。

总结

本节课系统讲解了 HarmonyOS 弹窗开发的核心知识：

1. 弹窗基础概念：弹窗是展示需要用户关注的信息或操作的 UI 组件，分为固定样式弹窗和自定义弹窗两类。

2. 固定样式弹窗：系统提供的标准化弹窗，包含即时反馈（Toast）、警告弹窗（AlertDialog）、列表选择弹窗（ActionSheet）、选择器弹窗（PickerDialog）、操作菜单（showActionMenu）五种类型。使用时需遵循对应的使用规范和约束。

3. 自定义弹窗：开发者可根据需求自主设计样式与交互，通过 openCustomDialog 打开、updateCustomDialog 动态更新、closeCustomDialog 关闭，可承载复杂内容和功能。