弹窗概述
====

弹窗一般指打开应用时自动弹出或者用户行为操作时弹出的UI界面，用于短时间内展示用户需关注的信息或待处理的操作。

从ArkUI组件树层级上来看，Overlay浮层、弹窗、模态、带Order的Overlay浮层都挂载在Root节点下。弹窗、模态、带Order的Overlay浮层根据设置的层级（数字大小）进行逐层显示，并且全部显示在Overlay浮层上面。如图所示：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/4f/v3/LFlKyPkyRLiWs2Ojq0BBGw/zh-cn_image_0000002625107585.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=F66F92C26D72A447E20FA4CCAA633BA2244C2C99ED98FF03F2150DCED1817E53)

对于一个多页面应用，基本树结构如下所示。多个Page页面之间使用[Router](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-router)的接口进行跳转。[NavBar](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navigation#navbar12)和[Navdestination](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navdestination)组成的页面可以通过[Navigation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navigation)接口进行跳转。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/87/v3/Tq-9obJ6QNqkyCmHmmXyOQ/zh-cn_image_0000002594668068.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=915A2B3600A34D93B2BC04E21360C43696ABA709B3D9A3CAA2EDF58591A2BF6A)

而[Dialog](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-base-dialog-overview)、[Popup](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-popup-overview)、[Menu](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-menu-overview)、[OverlayManager](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-overlaymanager)、[Toast](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-toast)、[bindSheet](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sheet-page)以及[bindContentCover](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-contentcover-page)的组件在结合路由、导航使用时存在如下几种显示模式。

*   弹窗显示在当前应用窗口最上层，层级高于应用主窗内所有页面（默认行为）。
    
    如下图所示，触发弹窗显示时，弹窗层级要高于Page页面和Navigation页面，即如果弹窗组件没有被关闭的话，页面切换前后，弹窗组件都会显示在页面上方，而不会出现新的路由/导航页面覆盖在弹窗之上的情况。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b/v3/GD3iP0ABSJ-vTSbwLbvU9g/zh-cn_image_0000002594827996.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=7D98823AC8A9333BB3ABC93B3BE91F405138FD5B992877ED9EDF943D4563D5ED)
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c1/v3/QbsPwxW-SIm3Mby2Z5lLpg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=159971B921244D44F8DAAD2E81CC1091D3ADCDDE0AE9406971B234D586E32874)
    
    如果Popup或Menu等存在绑定组件的弹窗组件，在页面跳转后因为所绑定的组件不在新页面显示，系统内部会自动关闭对应弹窗组件。但因为弹窗组件显示同时受开发者配置的参数控制，例如当[Popup](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-popup-overview)的show参数设置为显示时，弹窗组件会覆盖在下一个页面上显示。
    
*   弹窗显示在当前页面内，层级低于下一跳页面。
    
    当开发者期望弹窗是一个页面内的弹窗，即当路由/导航切换页面时，弹窗会被跳转的页面覆盖，随着页面切回原页面，弹窗仍然正常显示。此时弹窗层级如下图所示：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c8/v3/W7KXA3mdTOS03lfdRWz_XQ/zh-cn_image_0000002625187443.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=7730308D7976055DB86D4E039A9B1FBB380AEA33C56452FE4D6C433121925580)
    
    页面级弹窗功能需要结合弹窗组件的页面级能力使用，当前支持页面级能力的有[Dialog](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-base-dialog-overview)和[bindSheet](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-sheet-page)。
    
*   弹窗显示在独立窗口内，窗口层级高于应用所在窗口。
    
    在PC/2in1等设备上，开发者常期望弹窗的显示在应用窗口之外，此时需要借助子窗的能力。例如自定义弹窗可以通过[CustomDialogControllerOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-methods-custom-dialog-box#customdialogcontrolleroptions对象说明)中的showInSubwindow属性控制是否使用子窗功能。基于子窗显示的弹窗效果如下图所示。
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/22/v3/UmJccOzwRLC9HvzYxanzQg/zh-cn_image_0000002625107587.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=0CB8DF1E31FEE5FAEC8DA60C5B8C8237A1AC57F30A8864C73060E0857AE872B9)
    
    此时弹窗组件的显示层级受窗口的层级管理控制，会高于当前应用所在的窗口，低于系统窗口（如系统输入法、系统弹窗等）。
    

#### 弹窗的种类

根据用户交互操作场景，弹窗可分为**模态弹窗**和**非模态弹窗**两种类型，其区别在于用户是否必须对其做出响应。

*   **模态弹窗：** 为强交互形式，会中断用户当前的操作流程，要求用户必须做出响应才能继续其他操作，通常用于需要向用户传达重要信息的场景。
*   **非模态弹窗：** 为弱交互形式，不会影响用户当前操作行为，用户可以不对其进行回应，通常都有时间限制，出现一段时间后会自动消失。一般用于告诉用户信息内容外还需要用户进行功能操作的场景。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/38/v3/PCiIrZokTdG5fBwhHTc1Kg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=663DD6E350F2B6F811DBA7AD4948343715A896EB32070636807DE052F19D5B80)

当前模态弹窗通过设置指定属性变成非模态，例如AlertDialog，可以设置[AlertDialogParam](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-methods-alert-dialog-box#alertdialogparam对象说明)中的isModal属性值为false变成非模态，其他弹窗详见API说明。

不建议在非前台状态下，调用弹窗显示接口。

系统弹窗由系统弹出，出于安全考虑，不支持自定义样式。

系统弹窗出现时，调用非系统弹窗的显示接口（例如：[promptAction](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-promptaction)的[openCustomDialog](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-promptaction#promptactionopencustomdialogdeprecated)、[CustomDialogController](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-methods-custom-dialog-box#customdialogcontroller)的[open](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-methods-custom-dialog-box#open)等），禁止该类弹窗显示。

#### 使用场景

开发者可根据实际应用场景选择合适的弹窗进行页面开发。

| 弹窗名称 | 应用场景 |
| :-- | :-- |
| [弹出框（Dialog）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-base-dialog-overview) | 当需要展示用户当前需要或必须关注的信息内容或操作时，例如二次退出应用等，应优先考虑使用此弹出框。 |
| [菜单（Menu/openMenu）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-menu-overview) | 当需要给用户提供可执行的操作时，例如长按图标展示操作选项等，应优先考虑使用此弹窗。 |
| [气泡提示（Popup/openPopup）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-popup-overview) | 当需要给用户提供提示时，例如点击一个问号图标弹出一段帮助提示等，应优先考虑使用此弹窗。 |
| [绑定模态页面（bindContentCover/bindSheet）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-modal-overview) | 当需要新的界面覆盖在旧的界面上，且旧的界面不消失的一种转场方式时，例如缩略图片点击后查看大图等，应优先考虑使用此弹窗。 |
| [即时反馈（Toast）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-toast) | 当需要在一个小的窗口中提供用户当前操作的简单反馈时，例如提示文件保存成功等，应优先考虑使用此弹窗。 |
| [设置浮层（OverlayManager）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-create-overlaymanager) | 当需要完全自定义内容、行为、样式时，可以使用浮层将UI展示在页面之上，例如音乐/语音播放悬浮球/胶囊等，应优先考虑使用此弹窗。 |

上表列出了各类弹窗的适用场景。实际开发中，在使用自定义弹窗能力时，还需考虑侧滑拦截、点击外部关闭、自定义动画、页面切换后弹窗保留、键盘避让等交互特性，不同弹窗方案对这些特性的支持程度各异。推荐阅读[自定义弹窗选型与开发](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/custom-dialog-select-develop)，该文对比了UIContext下面的openBindSheet、openCustomDialog、getOverlayManager弹窗与Navigation.Dialog的[能力差异](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/custom-dialog-select-develop#能力支持情况)，并提供了隐私弹窗、进度弹窗等常见场景的实现方案，帮助开发者完成弹窗选型与开发。

#### 规格约束

*   多个弹窗组件先后弹出时，后弹出的组件的层级高于先弹出的层级，退出时按照层级从高到低的顺序逐次退出。
    
*   在移动设备中，子窗模式的弹窗当前无法超出主窗口。而在2in1设备上，使用模态类弹窗时，会出现需要超出主窗口显示的场景，开发者可以通过设置showInSubWindow为true实现超出主窗口的显示效果。如下图所示：
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3/v3/Ud62PzQWToil_95lpy9BzA/zh-cn_image_0000002594668070.png?HW-CC-KV=V1&HW-CC-Date=20260612T073306Z&HW-CC-Expire=86400&HW-CC-Sign=B78EC2DE72068258D66D1DD3692678B646B1900CA4378AF09C0DA9F4C2B3C8F4)