干货分享|窗口管理

本文深入探讨了HarmonyOS中的窗口管理机制，涵盖了应用主窗口的管理、应用子窗口的管理以及实现窗口沉浸式体验的技术细节。在创建WindowStage对象后，可通过监听windowStageEvent事件类型，监听窗口进入前台、后台、前台可交互、前台不可交互等事件，应用可根据这些上报的事件状态进行相应的业务处理。侧边栏恢复：对于已开启悬浮窗模式的应用，其最小化后会暂存在屏幕上的侧边栏中，单击或者

全栈开发圈

438人浏览 · 2026-02-03 15:16:26

全栈开发圈 · 2026-02-03 15:16:26 发布

HarmonyOS通过窗口模块实现在同一块物理屏幕上提供多个应用界面的显示和交互。本文将介绍窗口管理的相关概念及开发方法。

1.窗口开发概述

HarmonyOS通过窗口模块实现窗口管理，包括：

l 针对应用开发者，提供了界面显示和交互能力。

l 针对终端用户，提供了控制应用界面的方式。

l 针对整个操作系统，提供了不同应用界面的组织管理逻辑。

1.1 窗口的分类

HarmonyOS的窗口模块将窗口界面分为系统窗口、应用窗口两种基本类型。

（1）系统窗口是指完成系统特定功能的窗口，如音量条、壁纸、通知栏、状态栏、导航栏等。

（2）应用窗口是指与应用显示相关的窗口。根据显示内容的不同，应用窗口又分为应用主窗口和应用子窗口两种类型。

l 应用主窗口：用于显示应用界面，可在“任务管理界面”显示。

l 应用子窗口：用于显示应用的弹窗、悬浮窗等辅助窗口，不会在“任务管理界面”显示。

1.2 窗口模块的用途

窗口模块提供管理窗口的一些基础能力，包括对当前窗口的创建、销毁、各属性的设置，以及各窗口间的管理调度。该模块提供以下窗口相关的常用功能：

l Window：当前窗口实例，窗口管理器管理的基本单元。

l WindowStage：窗口管理器，用于管理各个基本窗口单元。

在HarmonyOS中，窗口模块主要具有以下职责：

l 提供应用和系统界面的窗口对象。应用开发者通过窗口加载UI界面，实现界面显示功能。

l 组织不同窗口的显示关系，即维护不同窗口间的叠加层次和位置属性。应用和系统的窗口具有多种类型，不同类型的窗口具有不同的默认位置和叠加层次（z轴高度）。同时，用户操作也可以在一定范围内对窗口的位置和叠加层次进行调整。

l 提供窗口装饰。窗口装饰是指窗口标题栏和窗口边框。窗口标题栏通常包括窗口最大化、最小化及关闭按钮等界面元素，具有默认的单击行为，方便用户进行操作；窗口边框则方便用户对窗口进行拖动、缩放等行为。窗口装饰是系统的默认行为，开发者可选择启用/禁用，无须关注UI代码层面的实现。

l 提供窗口动效。在窗口显示、隐藏及窗口间切换时，窗口模块通常会添加动画效果，以使各个交互过程更加连贯流畅。在HarmonyOS中，应用窗口的动效为默认行为，不需要开发者进行设置或者修改。

l 指导输入事件分发。即根据当前窗口的状态或焦点，进行事件的分发。触摸和鼠标事件根据窗口的位置和尺寸进行分发，而键盘事件会被分发至焦点窗口。应用开发者可以通过窗口模块提供的接口来设置窗口是否可以触摸和是否可以获焦。

1.3 窗口沉浸式能力

窗口沉浸式能力是指对状态栏、导航栏等系统窗口进行控制，减少状态栏、导航栏等系统界面的突兀感，从而使用户获得最佳体验。

沉浸式能力只在应用主窗口作为全屏窗口时生效。通常情况下，应用子窗口（弹窗、悬浮窗口等辅助窗口）和处于自由窗口下的应用主窗口无法使用沉浸式能力。

1.4 应用窗口模式

应用窗口模式是应用主窗口启动时的显示方式。HarmonyOS目前支持全屏、分屏、自由窗口3种应用窗口模式。这种对多种应用窗口模式的支持能力，也被称为操作系统的“多窗口能力”。

l 全屏：应用主窗口启动时铺满整个屏幕。

l 分屏：应用主窗口启动时占据屏幕的某个部分，当前支持二分屏。两个分屏窗口之间具有分界线，可通过拖动分界线调整两个分屏窗口的尺寸。

l 自由窗口：其大小和位置可自由改变。同一个屏幕上可同时显示多个自由窗口，这些自由窗口按照打开或者获取焦点的顺序在z轴上排列。当自由窗口被单击或触摸时，将导致其z轴高度提升，并获取焦点。

下图展示了3种应用窗口模式。

2.窗口管理

在Stage模型下，管理应用窗口的典型场景有：

l 设置应用主窗口属性及目标页面。

l 设置应用子窗口属性及目标页面。

l 体验窗口的沉浸式能力。

l 设置悬浮窗口。

l 监听窗口包含不可交互与可交互事件。

2.1 设置应用主窗口属性及目标页面

在Stage模型下，应用主窗口由UIAbility创建并维护生命周期。在UIAbility的onWindowStageCreate回调中，通过WindowStage获取应用主窗口，即可对它进行属性设置等操作。还可以在应用配置文件中设置应用主窗口的属性，如最大窗口宽度maxWindowWidth等。

常用API如下：

l getMainWindow(callback: AsyncCallback<Window>)：获取WindowStage实例下的主窗口。

l loadContent(path: string, callback: AsyncCallback<void>)：为当前WindowStage的主窗口加载具体页面。

l setBrightness(brightness:number,callback:AsyncCallback<void>)：设置屏幕亮度值。

l setTouchable(isTouchable:boolean,callback:AsyncCallback<void>)：设置窗口是否为可触状态。

2.2 设置应用子窗口属性及目标页面

开发者可以按需创建应用子窗口，如弹窗等，并对它进行属性设置。

常用API如下：

l createSubWindow(name:string,callback:AsyncCallback<Window>)：创建子窗口。

l loadContent(path: string, callback: AsyncCallback<void>)：为当前窗口加载具体页面。

l show(callback: AsyncCallback<void>)：显示当前窗口。

2.3 体验窗口沉浸式能力

在看视频、玩游戏等场景下，用户往往希望隐藏状态栏、导航栏等不必要的系统窗口，以获得更佳的沉浸式体验。此时可以借助窗口沉浸式能力（窗口沉浸式能力仅针对应用主窗口），达到预期效果。从API 10开始，沉浸式窗口默认配置为全屏大小，并由组件模块控制布局，状态栏、导航栏背景颜色为透明，文字颜色为黑色。应用窗口调用setWindowLayoutFullScreen接口，设置为true表示由组件模块控制忽略状态栏、导航栏的沉浸式全屏布局，设置为false表示由组件模块控制避让状态栏、导航栏的非沉浸式全屏布局。在观看视频、玩游戏等场景下，用户通常希望隐藏状态栏、导航栏等非必要的系统窗口，以获得更佳的沉浸式体验。此时可借助窗口沉浸式能力（该能力仅针对应用主窗口）实现预期效果。从API 10开始，沉浸式窗口默认配置为全屏尺寸，并由组件模块控制布局，状态栏和导航栏的背景色为透明，文字颜色为黑色。应用窗口可通过调用setWindowLayoutFullScreen接口进行设置：

设为true表示由组件模块控制，忽略状态栏和导航栏，采用沉浸式全屏布局。

设为false表示由组件模块控制，避让状态栏和导航栏，采用非沉浸式全屏布局。

注意：

当前沉浸式界面开发仅支持Window级别的配置，暂不支持Page级别的配置。若有Page级别切换的需要，可以在页面生命周期开始，例如在onPageShow中设置沉浸模式，然后在页面退出，例如在onPageHide中恢复默认设置。

实现沉浸式效果有以下两种方式：

当应用主窗口为全屏窗口时，调用setWindowSystemBarEnable接口，并设置导航栏、状态栏不显示，从而达到沉浸式效果。

调用setWindowLayoutFullScreen接口，设置应用主窗口为全屏布局；然后调用setWindowSystemBarProperties接口，并设置导航栏、状态栏的透明度、背景颜色、文字颜色以及高亮图标等属性，使之与主窗口显示保持协调一致，从而达到沉浸式效果。

2.4 设置悬浮窗

悬浮窗可以在已有任务基础上创建一个始终在前台显示的窗口，即使创建悬浮窗的任务退至后台，悬浮窗仍然可以在前台显示。通常悬浮窗位于所有应用窗口之上，开发者可以创建悬浮窗，并对悬浮窗进行属性设置等操作。

创建WindowType.TYPE_FLOAT（即悬浮窗类型的窗口），需要申请ohos.permission.SYSTEM_ FLOAT_WINDOW权限，该权限为受控开放权限，仅符合指定场景的在2in1设备上的应用可申请该权限。

悬浮窗的开发步骤如下：

（1）创建悬浮窗。通过window.createWindow接口创建悬浮类型的窗口。

（2）对悬浮窗进行属性设置。悬浮窗创建成功后，可以改变其大小、位置等，还可以根据应用需要设置悬浮窗背景色、亮度等属性。

（3）加载显示悬浮窗的具体内容。通过setUIContent和showWindow接口加载显示悬浮窗的具体内容。

（4）销毁悬浮窗。当不再需要悬浮窗时，可根据具体实现逻辑，使用destroyWindow接口销毁悬浮窗。

2.5 监听窗口不可交互与可交互事件

应用在前台显示的过程中可能会进入某些不可交互的场景，比较典型的是进入多任务界面。此时，对于一些应用可能需要选择暂停某个与用户正在交互的业务，如视频类应用暂停正在播放的视频或者相机暂停预览流等。而当该应用从多任务界面切换回前台时，又变成了可交互的状态，此时需要恢复被暂停的业务，如恢复视频播放或相机预览流等。

在创建WindowStage对象后，可通过监听windowStageEvent事件类型，监听窗口进入前台、后台、前台可交互、前台不可交互等事件，应用可根据这些上报的事件状态进行相应的业务处理。

3.实战：实现窗口沉浸式效果

本节将演示窗口管理的常用操作，包括应用主窗口的操作以及窗口沉浸式能力的使用。

打开DevEco Studio，选择一个Empty Ability工程模板，创建一个名为“ArkTSWindowLayoutFullScreen”的工程作为演示示例。

3.1 获取应用主窗口

可通过getMainWindow接口获取应用主窗口。

修改EntryAbility.ets的onWindowStageCreate方法，在windowStage.loadContent方法之前添加如下内容：

// 1.获取应用主窗口
let windowClass: window.Window | null = null;
windowStage.getMainWindow((err: BusinessError, data) => {
    let errCode: number = err.code;
    if (errCode) {
    console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err));
    return;
    }
    windowClass = data;
    console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));

    // 2.实现沉浸式效果
    // ...
})

在上述代码中，windowStage.getMainWindow方法获取到了应用主窗口windowClass。

接下来就可以对windowClass进行设置，以实现沉浸式效果。

3.2 实现沉浸式效果

实现沉浸式效果有以下两种方式。

方式一

方式一是当应用主窗口为全屏窗口时，调用setWindowSystemBarEnable接口，设置导航栏、状态栏不显示，从而达到沉浸式效果。代码如下：

// 2.实现沉浸式效果。方式一：设置导航栏、状态栏不显示
let names: Array<'status' | 'navigation'> = [];
windowClass.setWindowSystemBarEnable(names)
.then(() => {
    console.info('Succeeded in setting the system bar to be visible.');
})
.catch((err: BusinessError) => {
    console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err));
});

方式二

方式二是首先调用setWindowLayoutFullScreen接口，设置应用主窗口为全屏布局；然后调用setWindowSystemBarProperties接口，设置导航栏、状态栏的透明度、背景颜色、文字颜色以及高亮图标等属性，使其与主窗口显示保持协调一致，从而达到沉浸式效果。代码如下：

let isLayoutFullScreen = true;
windowClass.setWindowLayoutFullScreen(isLayoutFullScreen)
.then(() => {
    console.info('Succeeded in setting the window layout to full-screen mode.');
})
.catch((err: BusinessError) => {
    console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err));
});
let sysBarProps: window.SystemBarProperties = {
statusBarColor: '#ff00ff',
navigationBarColor: '#00ff00',
// 以下两个属性从API 8开始支持
statusBarContentColor: '#ffffff',
navigationBarContentColor: '#ffffff'
};
windowClass.setWindowSystemBarProperties(sysBarProps)
.then(() => {
    console.info('Succeeded in setting the system bar properties.');
})
.catch((err: BusinessError) => {
    console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err));
});

3.3 运行

未设置沉浸式效果的界面效果如下图所示。