HarmonyOS应用窗口管理（Stage模型）

 

一、  窗口开发概述

窗口模块的定义

窗口模块用于在同一块物理屏幕上，提供多个应用界面显示、交互的机制。

● 对应用开发者而言，窗口模块提供了界面显示和交互能力。

● 对终端用户而言，窗口模块提供了控制应用界面的方式。

● 对整个操作系统而言，窗口模块提供了不同应用界面的组织管理逻辑。

窗口模块的用途

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

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

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

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

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

基本概念

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

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

● 应用窗口：应用窗口区别于系统窗口，指与应用显示相关的窗口。根据显示内容的不同，应用窗口又分为应用主窗口、应用子窗口两种类型。应用主窗口：应用主窗口用于显示应用界面，会在"任务管理界面"显示。

○ 应用子窗口：应用子窗口用于显示应用的弹窗、悬浮窗等辅助窗口，不会在"任务管理界面"显示。应用子窗口的生命周期跟随应用主窗口。

实现原理

当前窗口的实现和开发与应用开发模型相关联，不同模型下的接口功能略有区别。当前应用开发模型分为FA模型和Stage模型。

两个模型的整体架构和设计思想，详见应用模型解读。

针对窗口开发，推荐使用Stage模型进行相关开发。

约束与限制

● 应用主窗口与子窗口存在大小限制，宽度范围：[320, 2560]，高度范围：[240, 2560]，单位为vp。

二、管理应用窗口（Stage模型）

基本概念

● 窗口沉浸式能力：指对状态栏、导航栏等系统窗口进行控制，减少状态栏导航栏等系统界面的突兀感，从而使用户获得最佳体验的能力。沉浸式能力只在应用主窗口作为全屏窗口时生效。通常情况下，应用子窗口（弹窗、悬浮窗口等辅助窗口）无法使用沉浸式能力。

● 悬浮窗：全局悬浮窗口是一种特殊的应用窗口，具备在应用主窗口和对应Ability退至后台后仍然可以在前台显示的能力。

悬浮窗口可以用于应用退至后台后，使用小窗继续播放视频，或者为特定的应用创建悬浮球等快速入口。应用在创建悬浮窗口前，需要申请对应的权限。

场景介绍

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

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

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

● 体验窗口沉浸式能力

● 设置悬浮窗

以下分别介绍具体开发方式。

接口说明

上述场景涉及的常用接口如下表所示。更多API说明请参见API参考。

实例名	接口名	描述
WindowStage	getMainWindow(callback: AsyncCallback<Window>): void	获取WindowStage实例下的主窗口。 此接口仅可在Stage模型下使用。
WindowStage	loadContent(path: string, callback: AsyncCallback<void>): void	为当前WindowStage的主窗口加载具体页面。 此接口仅可在Stage模型下使用。
WindowStage	createSubWindow(name: string, callback: AsyncCallback<Window>): void	创建子窗口。 此接口仅可在Stage模型下使用。
window静态方法	createWindow(config: Configuration, callback: AsyncCallback<Window>): void	创建系统窗口。 -config：创建窗口时的参数。
Window	setUIContent(path: string, callback: AsyncCallback<void>): void	为当前窗口加载具体页面。
Window	setWindowBackgroundColor(color: string, callback: AsyncCallback<void>): void	设置窗口的背景色。
Window	setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void	设置屏幕亮度值。
Window	setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void	设置窗口是否为可触状态。
Window	moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void	移动当前窗口位置。
Window	resize(width: number, height: number, callback: AsyncCallback<void>): void	改变当前窗口大小。
Window	setWindowSystemBarEnable(names: Array<'status'|'navigation'>): Promise<void>	设置导航栏、状态栏是否显示。
Window	showWindow(callback: AsyncCallback<void>): void	显示当前窗口。
Window	on(type: 'touchOutside', callback: Callback<void>): void	开启本窗口区域外的点击事件的监听。
Window	destroyWindow(callback: AsyncCallback<void>): void	销毁当前窗口。

设置应用主窗口

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

开发步骤

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

2.  设置主窗口属性。可设置主窗口的背景色、亮度值、是否可触等多个属性，开发者可根据需要选择对应的接口。本示例以设置“是否可触”属性为例。

3.  为主窗口加载对应的目标页面。通过loadContent接口加载主窗口的目标页面。

import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage) {
        // 1.获取应用主窗口。
        let windowClass = null;
        windowStage.getMainWindow((err, data) => {
            if (err.code) {
                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.设置主窗口属性。以设置"是否可触"属性为例。
            let isTouchable = true;
            windowClass.setWindowTouchable(isTouchable, (err) => {
                if (err.code) {
                    console.error('Failed to set the window to be touchable. Cause:' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in setting the window to be touchable.');
            })
        })
        // 3.为主窗口加载对应的目标页面。
        windowStage.loadContent("pages/page2", (err) => {
            if (err.code) {
                console.error('Failed to load the content. Cause:' + JSON.stringify(err));
                return;
            }
            console.info('Succeeded in loading the content.');
        });
    }
};

设置应用子窗口

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

开发步骤

1.  创建应用子窗口。通过createSubWindow接口创建应用子窗口。

2.  设置子窗口属性。子窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置窗口背景色、亮度等属性。

3.  加载显示子窗口的具体内容。通过setUIContent和showWindow接口加载显示子窗口的具体内容。

4.  销毁子窗口。当不再需要某些子窗口时，可根据具体实现逻辑，使用destroyWindow接口销毁子窗口。

import UIAbility from '@ohos.app.ability.UIAbility';

let windowStage_ = null;
let sub_windowClass = null;
export default class EntryAbility extends UIAbility {
    showSubWindow() {
        // 1.创建应用子窗口。
        windowStage_.createSubWindow("mySubWindow", (err, data) => {
            if (err.code) {
                console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err));
                return;
            }
            sub_windowClass = data;
            console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
            // 2.子窗口创建成功后，设置子窗口的位置、大小及相关属性等。
            sub_windowClass.moveWindowTo(300, 300, (err) => {
                if (err.code) {
                    console.error('Failed to move the window. Cause:' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in moving the window.');
            });
            sub_windowClass.resize(500, 500, (err) => {
                if (err.code) {
                    console.error('Failed to change the window size. Cause:' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in changing the window size.');
            });
            // 3.为子窗口加载对应的目标页面。
            sub_windowClass.setUIContent("pages/page3", (err) => {
                if (err.code) {
                    console.error('Failed to load the content. Cause:' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in loading the content.');
                // 3.显示子窗口。
                sub_windowClass.showWindow((err) => {
                    if (err.code) {
                        console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
                        return;
                    }
                    console.info('Succeeded in showing the window.');
                });
            });
        })
    }

    destroySubWindow() {
        // 4.销毁子窗口。当不再需要子窗口时，可根据具体实现逻辑，使用destroy对其进行销毁。
        sub_windowClass.destroyWindow((err) => {
            if (err.code) {
                console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err));
                return;
            }
            console.info('Succeeded in destroying the window.');
        });
    }

    onWindowStageCreate(windowStage) {
        windowStage_ = windowStage;
        // 开发者可以在适当的时机，如主窗口上按钮点击事件等，创建子窗口。并不一定需要在onWindowStageCreate调用，这里仅作展示
        this.showSubWindow();
    }

    onWindowStageDestroy() {
        // 开发者可以在适当的时机，如子窗口上点击关闭按钮等，销毁子窗口。并不一定需要在onWindowStageDestroy调用，这里仅作展示
        this.destroySubWindow();
    }
};

　

体验窗口沉浸式能力

在看视频、玩游戏等场景下，用户往往希望隐藏状态栏、导航栏等不必要的系统窗口，从而获得更佳的沉浸式体验。此时可以借助窗口沉浸式能力（窗口沉浸式能力都是针对应用主窗口而言的），达到预期效果。

开发步骤

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

2.  实现沉浸式效果。调用setWindowSystemBarEnable接口，设置导航栏、状态栏不显示，从而达到沉浸式效果。

3.  加载显示沉浸式窗口的具体内容。通过loadContent接口加载沉浸式窗口的具体内容。

 

import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {

onWindowStageCreate(windowStage) {

// 1.获取应用主窗口。

let windowClass = null;

windowStage.getMainWindow((err, data) => {

if (err.code) {

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.实现沉浸式效果：设置导航栏、状态栏不显示。

let names = [];

windowClass.setWindowSystemBarEnable(names, (err) => {

if (err.code) {

console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err));

return;

}

console.info('Succeeded in setting the system bar to be visible.');

});

})

// 3.为沉浸式窗口加载对应的目标页面。

windowStage.loadContent("pages/page2", (err) => {

if (err.code) {

console.error('Failed to load the content. Cause:' + JSON.stringify(err));

return;

}

console.info('Succeeded in loading the content.');

});

}

};

　　

设置悬浮窗

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

开发步骤

前提条件：创建WindowType.TYPE_FLOAT即悬浮窗类型的窗口，需要申请ohos.permission.SYSTEM_FLOAT_WINDOW权限，配置方式请参见配置文件权限声明。

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

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

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

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

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage) {
        // 1.创建悬浮窗。
        let windowClass = null;
        let config = {name: "floatWindow", windowType: window.WindowType.TYPE_FLOAT, ctx: this.context};
        window.createWindow(config, (err, data) => {
            if (err.code) {
                console.error('Failed to create the floatWindow. Cause: ' + JSON.stringify(err));
                return;
            }
            console.info('Succeeded in creating the floatWindow. Data: ' + JSON.stringify(data));
            windowClass = data;
            // 2.悬浮窗窗口创建成功后，设置悬浮窗的位置、大小及相关属性等。
            windowClass.moveWindowTo(300, 300, (err) => {
                if (err.code) {
                    console.error('Failed to move the window. Cause:' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in moving the window.');
            });
            windowClass.resize(500, 500, (err) => {
                if (err.code) {
                    console.error('Failed to change the window size. Cause:' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in changing the window size.');
            });
            // 3.为悬浮窗加载对应的目标页面。
            windowClass.setUIContent("pages/page4", (err) => {
                if (err.code) {
                    console.error('Failed to load the content. Cause:' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in loading the content.');
                // 3.显示悬浮窗。
                windowClass.showWindow((err) => {
                    if (err.code) {
                        console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
                        return;
                    }
                    console.info('Succeeded in showing the window.');
                });
            });
            // 4.销毁悬浮窗。当不再需要悬浮窗时，可根据具体实现逻辑，使用destroy对其进行销毁。
            windowClass.destroyWindow((err) => {
                if (err.code) {
                    console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err));
                    return;
                }
                console.info('Succeeded in destroying the window.');
            });
        });
    }
};