窗口模块的用途

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

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

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

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

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

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

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

系统窗口：系统窗口指完成系统特定功能的窗口。如音量条、壁纸、通知栏、状态栏、导航栏等。 应用窗口：应用窗口区别于系统窗口，指与应用显示相关的窗口。根据显示内容的不同，应用窗口又分为应用主窗口、应用子窗口两种类型。 应用主窗口：应用主窗口用于显示应用界面，会在"任务管理界面"显示。 应用子窗口：应用子窗口用于显示应用的弹窗、悬浮窗等辅助窗口，不会在"任务管理界面"显示。 应用窗口模式 应用窗口模式指应用主窗口启动时的显示方式。OpenHarmony目前支持全屏、分屏、自由窗口三种应用窗口模式。这种对多种应用窗口模式的支持能力，也称为操作系统的“多窗口能力”。

全屏：应用主窗口启动时铺满整个屏幕。 分屏：应用主窗口启动时占据屏幕的某个部分，当前支持二分屏。两个分屏窗口之间具有分界线，可通过拖拽分界线调整两个部分的窗口尺寸。 自由窗口：自由窗口的大小和位置可自由改变。同一个屏幕上可同时显示多个自由窗口，这些自由窗口按照打开或者获取焦点的顺序在Z轴排布。当自由窗口被点击或触摸时，将导致其Z轴高度提升，并获取焦点。

约束与限制 在FA模型下，不支持系统窗口的相关开发。

管理应用窗口（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静态方法 create(ctx: Context, id: string, type: WindowType, callback: AsyncCallback<Window>): void 创建子窗口。 -ctx：为应用上下文信息。 -type：为创建的窗口类型。 Window loadContent(path: string, callback: AsyncCallback<void>): void 为当前窗口加载具体页面。 Window setBackgroundColor(color: string, callback: AsyncCallback<void>): void 设置窗口的背景色。 Window setBrightness(brightness: number, callback: AsyncCallback<void>): void 设置屏幕亮度值。 Window setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 设置窗口是否为可触状态。 Window moveTo(x: number, y: number, callback: AsyncCallback<void>): void 移动当前窗口位置。 Window resetSize(width: number, height: number, callback: AsyncCallback<void>): void 改变当前窗口大小。 Window setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void 设置窗口是否全屏显示。 Window setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 设置窗口布局是否为全屏布局。 Window setSystemBarEnable(names: Array<'status'|'navigation'>): Promise<void> 设置导航栏、状态栏是否显示。 Window setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 设置窗口内导航栏、状态栏属性。 systemBarProperties：导航栏、状态栏的属性集合。 Window show(callback: AsyncCallback<void>): void 显示当前窗口。 Window on(type: 'touchOutside', callback: Callback<void>): void 开启本窗口区域外的点击事件的监听。 Window destroy(callback: AsyncCallback<void>): void 销毁当前窗口。 设置应用主窗口 在Stage模型下，应用主窗口由Ability创建并维护生命周期。在Ability的onWindowStageCreate回调中，通过WindowStage获取应用主窗口，即可对其进行属性设置等操作

开发步骤 获取应用主窗口。 通过getMainWindow接口获取应用主窗口。

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

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

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

开发步骤 创建/获取应用子窗口。 通过createSubWindow接口创建应用子窗口。

通过getSubWindow接口获取已创建的应用子窗口。

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

加载显示子窗口的具体内容。 通过loadContent和show接口加载显示子窗口的具体内容。

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

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

开发步骤 获取应用主窗口。 通过getMainWindow接口获取应用主窗口。

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

方式一：调用setFullScreen接口，设置应用主窗口为全屏显示，此时导航栏、状态栏将隐藏，从而达到沉浸式效果。 方式二：调用setSystemBarEnable接口，设置导航栏、状态栏不显示，从而达到沉浸式效果。 方式三：调用setLayoutFullScreen接口，设置应用主窗口为全屏布局；然后调用setSystemPropertites接口，设置导航栏、状态栏的透明度、背景/文字颜色以及高亮图标等属性，使之保持与主窗口显示协调一致，从而达到沉浸式效果。 加载显示沉浸式窗口的具体内容。 通过loadContent和show接口加载显示沉浸式窗口的具体内容。

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

开发步骤 申请权限。 创建WindowType.TYPE_FLOAT即悬浮窗类型的窗口，需要在module.json5文件的requestPermissions对象中配置ohos.permission.SYSTEM_FLOAT_WINDOW权限。更多配置信息详见应用包结构配置文件的说明。

说明： 虽然悬浮窗具备始终在前台显示的能力，但如果创建悬浮窗的应用任务被系统回收，仍然会导致悬浮窗从界面移除。如果想要保持悬浮窗口始终在前台显示，请申请长时任务。

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

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

加载显示悬浮窗的具体内容。 通过loadContent和show接口加载显示悬浮窗的具体内容。

销毁悬浮窗。

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

管理系统窗口（仅Stage模型支持） 管理系统窗口概述 在Stage模型下， 允许系统应用创建和管理系统窗口，包括音量条、壁纸、通知栏、状态栏、导航栏等。具体支持的系统窗口类型见API参考-WindowType。

接口说明 更多API说明请参见API参考。

实例名 接口名 描述 window静态方法 create(ctx: Context, id: string, type: WindowType, callback: AsyncCallback<Window>): void 创建窗口。 -ctx：为应用上下文信息。当Context为ServiceExtensionContext时，创建系统窗口。 -type：为创建的窗口类型。 Window resetSize(width: number, height: number, callback: AsyncCallback<void>): void 改变当前窗口大小。 Window moveTo(x: number, y: number, callback: AsyncCallback<void>): void 移动当前窗口位置。 Window loadContent(path: string, callback: AsyncCallback<void>): void 为当前窗口加载具体页面。 Window show(callback: AsyncCallback<void>): void 显示当前窗口。 Window on(type: 'touchOutside', callback: Callback<void>): void 开启本窗口区域外的点击事件的监听。 Window hide (callback: AsyncCallback<void>): void 隐藏当前窗口。此接口为系统接口。 Window destroy(callback: AsyncCallback<void>): void 销毁当前窗口。 开发步骤 本文以音量条窗口为例，介绍系统窗口的基本开发和管理步骤。

创建系统窗口。

在ServiceExtensionContext下，使用window.create接口创建音量条系统窗口。

操作或设置系统窗口的属性。

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

加载显示系统窗口的具体内容。

通过loadContent和show接口加载显示音量条窗口的具体内容。

隐藏/销毁系统窗口。

当不再需要音量条窗口时，可根据具体实现逻辑，使用hide接口或destroy接口对其进行隐藏或销毁。