大网数据广告活动
OpenHarmony 设备与应用开发

窗口层级

· 52CE 我爱测

**窗口层级**是指多个窗口在屏幕上的堆叠顺序,决定窗口的前后显示关系,通常称为**Z序(ZOrder)**。

窗口层级

场景介绍

窗口层级是指多个窗口在屏幕上的堆叠顺序,决定窗口的前后显示关系,通常称为Z序(ZOrder)。

ZOrder值越大,窗口越靠前显示,能够覆盖ZOrder值较小的窗口;反之,ZOrder值较小的窗口则可能被其他窗口遮挡。

对于三方应用,无法直接修改窗口的ZOrder,但可以通过控制zLevel属性来间接影响子窗口的显示层级。

系统通过管理ZOrder和zLevel实现对用户界面可见性与交互优先级的控制。

本节将从基本概念、层级规则、父子窗口关系、TopMost窗口机制以及相关接口示例五个方面,系统化阐述窗口层级管理机制。

基本概念与层级规则

ZOrder与zLevel

ZOrder表示系统内部维护的窗口堆叠顺序。数值越大,窗口越靠前。三方应用不可直接修改ZOrder。

zLevel表示三方应用可控制的应用内子窗口之间的相对层级,仅针对非模态子窗口有效。zLevel取值范围为[-10000, 10000],默认值为0。zLevel越高,对应的ZOrder越大,窗口越靠前。

窗口zLevel层级规则

  • 不同zLevel的子窗口

    • zLevel高的窗口始终覆盖zLevel低的窗口,即使点击zLevel较低的窗口,也不会将其抬升至zLevel更高的窗口之上。
  • 相同zLevel的子窗口

    • 默认后创建的窗口层级更高。

    • 用户点击某个子窗口时,该窗口的ZOrder会被提升至同zLevel中的最高位置,实现“点击置顶”。

    • 若调用setRaiseByClickEnabled(false)接口,则禁用点击抬升功能,点击时层级保持不变。

窗口类型层级规则

父子窗口层级规则

  • 当父窗口被抬升时,其所有子窗口也会随之抬升;当子窗口被抬升时,其父窗口也会随之抬升。
  • 子窗口的层级始终高于其父窗口。
  • 窗口抬升可通过调用raiseToAppTop()接口或点击窗口实现。

TopMost置顶窗口层级规则

  • 在自由窗口状态下,应用主窗口可通过setWindowTopmost(true)将自身置于其他应用窗口之上,以实现“不被遮挡”的常驻显示效果,需合理使用,避免影响用户体验。

  • 使用该接口需要申请权限ohos.permission.WINDOW_TOPMOST。

窗口层级控制机制汇总表

特性/操作 控制方式 生效范围 适用场景
ZOrder 系统管理 可跨应用生效 内部渲染顺序管理
zLevel setSubWindowZLevel()/创建窗口时设置 仅同应用内生效 子窗口层级管理
窗口置顶 setWindowTopmost() 可跨应用生效 视频、导航等常驻窗口
点击抬升 setRaiseByClickEnabled() 可跨应用生效 防误触、固定布局

层级相关开发场景

功能 典型场景 对应接口
设置主窗口置顶 用于实现将窗口置于其他应用窗口之上不被遮挡。如视频通话、导航等场景。 setWindowTopmost()
提升子窗口到顶层 将子窗口提升至当前应用内同类型子窗口的最顶层,只在当前应用同一个父窗口下相同zLevel值的子窗范围内生效。
例如,视频会议中的悬浮工具栏,主窗口是视频画面,子窗口包括聊天框、共享控制栏等。点击聊天框时,可调用raiseToAppTop()将其提升到顶层,避免被其他子窗口遮挡。
raiseToAppTop()
禁止/使能子窗点击抬升功能 可用于固定布局的工具面板,防止用户误操作导致层级混乱。 setRaiseByClickEnabled()
获取当前应用内层级最高的窗口 可判断当前最前显示的窗口(可能是主窗口或子窗口),用于日志记录或状态同步等场景。 getLastWindow()

说明:

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。