When to Use
Window z-order (ZOrder) refers to the stacking order of multiple windows on the screen, which determines the front-to-back display relationship of windows.
The larger the z-order value, the closer the window is displayed to the front and can cover windows with smaller z-order values. Conversely, windows with smaller z-order values may be obscured by other windows.
For third-party apps, the z-order of a window cannot be directly modified, but the display z-order of subwindows can be indirectly affected by controlling the zLevel attribute.
The system controls the visibility and interaction priority of the user interface by managing ZOrder and zLevel.
This section systematically explains the window z-order management mechanism from five aspects: basic concepts, z-order rules, parent-child window relationships, the TopMost window mechanism, and related API examples.
[h2]ZOrder and zLevel
ZOrder represents the window stacking order maintained internally by the system. The larger the value, the closer the window is to the front. Third-party apps cannot directly modify ZOrder.
zLevel represents the relative z-order between subwindows within an app that can be controlled by third-party apps, and is only effective for non-modal subwindows. The value range of zLevel is [-10000, 10000], and the default value is 0. The greater the zLevel value, the larger the corresponding ZOrder, and the closer the window is to the front.
[h2]Z-Order Rules for Window zLevel
-
Subwindows with different zLevels
- A window with a higher zLevel always covers a window with a lower zLevel. Even if a window with a lower zLevel is clicked, it will not be raised above the window with a higher zLevel.
-
Subwindows with the same zLevel
-
By default, the window created later has a higher z-order.
-
When the user taps a subwindow, its z-order is raised to the highest position within the same zLevel, implementing "tap-to-top."
-
If setRaiseByClickEnabled() is called with false, the raise-on-tap feature is disabled, and the z-order remains unchanged when tapped.
-
[h2]Z-Order Rules for Window Types
-
Z-order adjustment for windows of the same type
For windows of the same type (multiple main windows, multiple regular subwindows), the z-order can be adjusted by tapping or using shortcuts (such as Alt+Tab).
-
Default z-order of in-app subwindow types
The system assigns default z-orders to different types of subwindows. The priorities from high to low are as follows:
Window Type Creation Method App-modal subwindow Call the createSubWindowWithOptions() API and set isModal to true and modalityType to APPLICATION_MODALITY in the subwindow parameters SubWindowOptions. Toast subwindow Call the showToast() API and set showMode to TOP_MOST. Text menu subwindow Call the showActionMenu() API and set showInSubWindow to true. Dialog subwindow Call openCustomDialog() with dialogContent and options parameters, and set showInSubWindow to true.
Call openCustomDialog() with the options parameter, and set showInSubWindow to true.
Call openCustomDialogWithController(), and set showInSubWindow to true.
Modal subwindow Call the createSubWindowWithOptions() API and set isModal to true and modalityType to WINDOW_MODALITY in the subwindow parameters SubWindowOptions. Normal subwindow The default subwindow created by calling the createSubWindowWithOptions() API. Windows of different types cannot cross their z-order ranges by tapping or through APIs.
[h2]Z-Order Rules for Parent-Child Windows
- When a parent window is raised, all its child windows are raised along with it; when a child window is raised, its parent window is also raised.
- The z-order of a child window is always higher than that of its parent window.
- A window can be raised by calling the raiseToAppTop() API or by tapping the window.
[h2]Z-Order Rules for TopMost Windows
-
In the freeform window state, an app's main window can call the setWindowTopmost() API with true to place itself above other app windows, achieving an always-on-top display effect that is not obscured. This should be used appropriately to avoid affecting the user experience.
-
Using this API requires the ohos.permission.WINDOW_TOPMOST permission.
Z-Order Control Mechanisms
| Feature/Operation | Control Method | Effective Scope | Applicable Scenario |
|---|---|---|---|
| Z-order | System-managed | Effective across apps | Internal rendering order management |
| zLevel | setSubWindowZLevel()/Set when creating a window | Effective only within the same app | z-order management for subwindows |
| Window topmost | setWindowTopmost() | Effective across apps | Persistent windows such as video and navigation |
| Raise by click | setRaiseByClickEnabled() | Between subwindows of the same type within the same application | Prevent accidental touches, fixed layout |
Z-Order Related Development Scenarios
| Feature | Typical Scenario | Corresponding API |
|---|---|---|
| Set main window to topmost | Used to place a window above other app windows without being obscured, such as in video calls, navigation, and other scenarios. | setWindowTopmost() |
| Raise a subwindow to the top | Used to raise a subwindow to the topmost position among subwindows of the same type within the current app. This only takes effect within the scope of subwindows that share the same parent window and the same zLevel value in the current app. For example, in a video conference with a floating toolbar, the main window displays the video feed, while subwindows include a chat box, a sharing control bar, and so on. When the chat box is tapped, raiseToAppTop() can be called to bring it to the top, preventing it from being obscured by other subwindows. | raiseToAppTop() |
| Disable/enable the subwindow raise-on-tap feature | Can be used for tool panels with fixed layouts to prevent z-order confusion caused by accidental user operations. | setRaiseByClickEnabled() |
| Get the topmost window in the current app | Can determine the currently displayed topmost window (which may be the main window or a subwindow), used for scenarios such as logging or state synchronization. | getLastWindow() |
-
Set zLevel appropriately to avoid z-order conflicts.
-
Use the TopMost feature with caution to avoid disrupting the system's multi-window experience.
-
For critical interfaces that require high-priority display, you can use raiseToAppTop() to ensure visibility. Before using this API, ensure that the window has called a showWindow() type API (showWindow()/showWindow(options: ShowWindowOptions)) and that the call has completed.
-
setWindowTopmost() takes effect only in the freeform window state. You can use isInFreeWindowMode() to check whether the current window is in freeform window mode, and combine it with the on('freeWindowModeChange') event listener to listen for window mode changes in real time, thereby accurately determining when it is safe to call setWindowTopmost().