前言

在 HarmonyOS NEXT 开发过程中，很多开发者都会遇到这样一个问题：

例如：

• DialogHub 自定义弹框
• OpenCustomDialog
• CustomDialog
• bindContentCover
• bindSheet

弹出以后，再调用：

PromptAction.showToast()

或者

Popup

或者

Tips

发现：

Toast 被 Dialog 挡住了！

或者：

Popup 根本显示不出来。

甚至：

Loading 永远在 Dialog 后面。

这是因为 ArkUI 的浮层（Overlay）并不是同一级别。

很多同学第一反应就是：

"设置 zIndex 行不行？"

答案：

绝大多数情况下，不行。

本文将深入介绍 HarmonyOS NEXT 的：

• OverlayManager
• Window Overlay
• DialogHub
• CustomDialog
• Popup
• Toast
• Sheet
• ContentCover

之间的层级关系，并介绍几种官方推荐方案。

---

一、问题现象

例如：

页面：

HomePage

点击：

打开支付弹框

代码：

DialogHub.show(PayDialog)

弹出：

====================
支付确认

确定支付？

【取消】【确定】

====================

随后：

promptAction.showToast({
    message:'支付成功'
})

结果：

Toast 根本看不到。

实际上：

Toast

↓

Dialog

↓

Page

Toast 被挡住。

---

二、为什么会这样？

很多人认为：

Toast

属于：

Window

实际上并不是。

ArkUI 中有多个 Overlay。

例如：

Window

下面：

Page

Page 上：

Overlay

Overlay 内：

Popup

Menu

Toast

Tips

但是：

CustomDialog

很多情况下：

并不是 Overlay。

而是：

独立 Window Layer

因此：

Toast

永远在下面。

---

三、HarmonyOS Overlay 层级详解

建议画图：

Window

│
├── Navigation
│
├── Page
│
│
├── OverlayManager
│      │
│      ├── Toast
│      ├── Popup
│      ├── Menu
│      ├── Bubble
│
├── Sheet
│
├── ContentCover
│
├── DialogHub
│
├── CustomDialog
│
└── System Window

很多开发者误认为：

zIndex

可以跨 Layer。

实际上：

zIndex

仅作用于

同一个 RenderNode

跨 Window：

完全无效。

---

四、各种弹框层级关系

详细介绍：

Popup

特点：

• 页面级
• Overlay
• 生命周期绑定页面

优点：

• 不遮挡
• 性能最高

缺点：

无法覆盖：

Dialog

---

Toast

也是：

Overlay

因此：

Toast

<

Dialog

---

Menu

例如：

.bindMenu()

也是：

Overlay

---

bindSheet

属于：

Modal

层级：

Sheet

>

Popup

>

Toast

---

bindContentCover

属于：

FullScreen Modal

优先级更高。

---

OpenCustomDialog

属于：

Dialog Window

优先级：

远高于：

Toast

---

DialogHub

本质也是：

Dialog Window

---

五、为什么 zIndex 无效？

例如：

Text("Toast")
    .zIndex(9999)

Dialog：

CustomDialog()

很多人希望：

9999

>

Dialog

实际上：

不是。

因为：

Toast

属于 Overlay A

Dialog

属于 Overlay B

RenderTree：

Overlay A

Overlay B

已经决定了：

Overlay B

>

Overlay A

zIndex 无法跨树。

---

六、方案一：使用 OverlayManager

这是 HarmonyOS 官方推荐方式。

例如：

OverlayManager.show()

统一管理：

Loading

Toast

Popup

Dialog

所有浮层：

统一一个 Overlay。

优点：

• 不冲突
• 不遮挡
• 生命周期统一

完整实现包括：

• OverlayController
• OverlayEntry
• OverlayRoot
• 全局管理器
• 自动回收机制
• 页面销毁处理

（本节可配完整源码。）

---

七、方案二：Dialog 内部显示提示

如果提示内容仅服务于当前弹框，可以直接将提示组件放入 Dialog 内部，而不是依赖全局 Toast。

例如：

Column() {
  Text("支付成功")
    .fontColor(Color.Green)
}

配合状态变量：

@State showTip: boolean = false

这样提示始终位于 Dialog 内部，不受层级影响。

---

八、方案三：关闭 Dialog 后再显示 Toast

适用于操作完成后的反馈。

dialogController.close()

setTimeout(() => {
  promptAction.showToast({
    message: '支付成功'
  })
}, 200)

需要注意动画结束时间，避免 Toast 仍被遮挡。

---

九、方案四：使用 bindContentCover 替代 Dialog

对于复杂业务场景，可以将原来的 Dialog 重构为全屏内容覆盖层，通过统一页面状态管理提示与交互，减少多层浮层叠加。

适用场景：

• 登录
• 支付
• 大型表单
• 多步骤流程

---

十、方案五：统一全局弹框管理

大型项目建议设计：

App
 ├── DialogManager
 ├── ToastManager
 ├── LoadingManager
 ├── PopupManager
 └── OverlayManager

所有浮层统一由管理器调度：

DialogManager.show()

ToastManager.show()

LoadingManager.show()

优势：

• 统一层级
• 避免重复弹框
• 支持队列
• 支持优先级
• 易于维护

---

十一、常见问题（FAQ）

Q1：为什么 Toast 被 Dialog 挡住？

因为两者位于不同的 Overlay/Window 层级，Dialog 优先级更高。

Q2：设置 zIndex 为 99999 为什么没用？

zIndex 仅影响同一渲染树中的兄弟节点，无法跨 Overlay 或 Window 生效。

Q3：Popup 能覆盖 Dialog 吗？

不能，Popup 属于页面 Overlay，通常位于 Dialog 之下。

Q4：如何实现全局 Loading 不被任何弹框遮挡？

建议基于 OverlayManager 或统一浮层管理架构实现，而不是多个独立弹框混用。

Q5：什么时候选择 Sheet、Dialog 或 ContentCover？

• Sheet：轻量级底部操作面板。
• Dialog：确认、输入等短流程交互。
• ContentCover：复杂流程或全屏模态页面。

---

十二、最佳实践总结

在 HarmonyOS NEXT 中，自定义弹框遮挡 Toast、Popup 等提示，本质是 Overlay 与 Window 层级设计 导致的问题，而不是 zIndex 设置错误。

推荐遵循以下原则：

1. 理解不同浮层的层级关系，避免依赖 zIndex 解决跨层问题。
2. 优先使用统一的 OverlayManager 或全局浮层管理方案。
3. Dialog 内部提示优先在 Dialog 内展示，减少跨层通信。
4. 操作完成后的 Toast 尽量在 Dialog 关闭后再显示。
5. 大型项目统一管理 Dialog、Toast、Loading、Popup，建立一致的浮层体系，避免层级冲突与维护成本增加。