> **节选说明 / Excerpt note**：本文件为官方文档节选（CC-BY-4.0）：仅保留以下小节，未修改任何文字。原文：https://gitee.com/openharmony/docs/raw/b84779874332bd7c2afee0ca3875494fa4793f1f/zh-cn/application-dev/reference/apis-arkui/arkts-apis-window-Window.md ## showWindow9+ showWindow(callback: AsyncCallback<void>): void 显示当前窗口，使用callback异步回调，支持系统窗口、应用子窗口、模态窗和全局悬浮窗，或将已显示的应用主窗口层级提升至顶部。 > **说明：** > > 调用该接口前，建议先通过[loadContent](../apis-arkui/arkts-apis-window-WindowStage.md#loadcontent9)方法或者[setUIContent](arkts-apis-window-Window.md#setuicontent9-1)方法完成页面加载。如果应用主窗口没有完成页面加载，直接调用该接口，界面会一直显示启动界面；如果系统窗口、应用子窗口、模态窗和全局悬浮窗没有完成页面加载，直接调用该接口，窗口会处于前台，但不可见。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | -- | --------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 1300002 | This window state is abnormal. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); windowStage.loadContent('pages/Index', (err) => { if (err.code) { console.error('Failed to load the content. Cause: %{public}s', JSON.stringify(err)); return; } console.info('Succeeded in loading the content.'); try { // 创建子窗 windowStage.createSubWindow("testSubWindow").then((subWindow) => { if (subWindow == null) { console.error('Failed to create the subWindow. Cause: The data is empty'); return; } subWindow.setUIContent('pages/Index', (err) => { if (err.code) { console.error('Failed to load the subWindow content. Cause: %{public}s', JSON.stringify(err)); return; } console.info('Succeeded in loading the subWindow content.'); try { subWindow.showWindow((err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to show the window. Error code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in showing the window.'); }); } catch (exception) { console.error(`Failed to show the window. Cause code: ${exception.code}, message: ${exception.message}`); } }) }); } catch (exception) { console.error(`Failed to create the sub window. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## showWindow9+ showWindow(): Promise<void> 显示当前窗口，使用Promise异步回调，支持系统窗口、应用子窗口、模态窗和全局悬浮窗，或将已显示的应用主窗口层级提升至顶部。 > **说明：** > > 调用该接口前，建议优先通过[loadContent](../apis-arkui/arkts-apis-window-WindowStage.md#loadcontent9)方法或者[setUIContent](arkts-apis-window-Window.md#setuicontent9-1)方法完成页面加载。如果应用主窗口没有完成页面加载，直接调用该接口，界面会一直显示启动界面；如果系统窗口、应用子窗口、模态窗和全局悬浮窗没有完成页面加载，直接调用该接口，窗口会处于前台，但不可见。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **返回值：** | 类型 | 说明 | | ------------------- | ----------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 1300002 | This window state is abnormal. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); windowStage.loadContent('pages/Index', (err) => { if (err.code) { console.error('Failed to load the content. Cause: %{public}s', JSON.stringify(err)); return; } console.info('Succeeded in loading the content.'); try { // 创建子窗 windowStage.createSubWindow("testSubWindow").then((subWindow) => { if (subWindow == null) { console.error('Failed to create the subWindow. Cause: The data is empty'); return; } subWindow.setUIContent('pages/Index', (err) => { if (err.code) { console.error('Failed to load the subWindow content. Cause: %{public}s', JSON.stringify(err)); return; } console.info('Succeeded in loading the subWindow content.'); try { let promise = subWindow.showWindow(); promise.then(() => { console.info('Succeeded in showing the window.'); }).catch((err: BusinessError) => { console.error(`Failed to show the window. Error code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to show window. Cause code: ${exception.code}, message: ${exception.message}`); } }); }); } catch (exception) { console.error(`Failed to create the sub window. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## showWindow20+ showWindow(options: ShowWindowOptions): Promise<void> 显示当前窗口或将已显示的应用主窗口的层级提升至顶部，支持传入参数来控制窗口显示的行为，使用Promise异步回调。 仅支持除TYPE_DIALOG类型的窗口和模态子窗口（即使用setSubWindowModal启用了子窗的模态属性）之外的应用子窗口、应用主窗、全局悬浮窗以及系统窗口。 > **说明：** > > 调用该接口前，建议优先通过[loadContent](../apis-arkui/arkts-apis-window-WindowStage.md#loadcontent9)方法或者[setUIContent](arkts-apis-window-Window.md#setuicontent9-1)方法完成页面加载。如果应用主窗口没有完成页面加载，直接调用该接口，界面会一直显示启动界面；如果系统窗口、应用子窗口和全局悬浮窗没有完成页面加载，直接调用该接口，窗口会处于前台，但不可见。 **系统能力：** SystemCapability.Window.SessionManager **原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | -- | --------- | | options | [ShowWindowOptions](arkts-apis-window-i.md#showwindowoptions20) | 是 | 显示子窗口或系统窗口时的参数。 | **返回值：** | 类型 | 说明 | | ------------------- | ----------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 801 | Capability not supported. Function showWindow can not work correctly due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | | 1300004 | Unauthorized operation. Possible cause: Invalid window type. Modal subwindow and dialog window can not set focusOnShow. | | 1300016 | Parameter validation error. Possible cause: 1. The value of the parameter is out of the allowed range; 2. The length of the parameter exceeds the allowed length; 3. The parameter format is incorrect. | **示例：** ```ts // EntryAbility.ets import { window } from '@kit.ArkUI'; import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); windowStage.loadContent('pages/Index', (err) => { if (err.code) { console.error('Failed to load the content. Cause: %{public}s', JSON.stringify(err)); return; } console.info('Succeeded in loading the content.'); // 创建子窗 try { windowStage.createSubWindow('subWindow').then((data) => { if (data == null) { console.error('Failed to create the subWindow. Cause: The data is empty'); return; } data.setUIContent('pages/Index', (err) => { if (err.code) { console.error('Failed to load the subWindow content. Cause: %{public}s', JSON.stringify(err)); return; } console.info('Succeeded in loading the subWindow content.'); let options: window.ShowWindowOptions = { focusOnShow: false }; try { data.showWindow(options).then(() => { console.info('Succeeded in showing window'); }).catch((err: BusinessError) => { console.error(`Failed to show window. Error code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to show window. Cause code: ${exception.code}, message: ${exception.message}`); } }); }); } catch (exception) { console.error(`Failed to create the sub window. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## destroyWindow9+ destroyWindow(callback: AsyncCallback<void>): void 销毁当前窗口，使用callback异步回调，支持系统窗口及应用子窗口，全局悬浮窗和模态窗。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | -- | --------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; windowClass.destroyWindow((err) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in destroying the window.'); }); ``` ## destroyWindow9+ destroyWindow(): Promise<void> 销毁当前窗口，使用Promise异步回调，支持系统窗口及应用子窗口，全局悬浮窗和模态窗。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let promise = windowClass.destroyWindow(); promise.then(() => { console.info('Succeeded in destroying the window.'); }).catch((err: BusinessError) => { console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); }); ``` ## moveWindowTo9+ moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void 移动窗口位置，使用callback异步回调。调用成功即返回，但返回后无法立即获取最终生效结果。如需立即获取，请使用[moveWindowToAsync()](#movewindowtoasync12)。 > **说明：** > > - 不建议在除自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）外的其他窗口模式下使用。 > > - 在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，窗口相对于屏幕左上顶点移动；在非自由窗口状态下，窗口相对于父窗口左上顶点移动。 > > - 若需在非自由窗口状态下实现相对于屏幕左上顶点的移动，请使用[moveWindowToGlobal()](#movewindowtoglobal15)。 > > - 该方法对非自由窗口状态下的主窗口无效。 > > - [自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，若主窗口或子窗口的标题栏移出屏幕可视区域，系统将自动回弹窗口，确保标题栏保持可见。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | -- | --------------------------------------------- | | x | number | 是 | 窗口在x轴方向移动到的坐标位置，单位为px，值为正表示在原点右侧，值为负表示在原点左侧。该参数仅支持整数输入，浮点数输入将向下取整。 | | y | number | 是 | 窗口在y轴方向移动到的坐标位置，单位为px，值为正表示在原点下方，值为负表示在原点上方。该参数仅支持整数输入，浮点数输入将向下取整。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { windowClass.moveWindowTo(300, 300, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in moving the window.'); }); } catch (exception) { console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## moveWindowTo9+ moveWindowTo(x: number, y: number): Promise<void> 移动窗口位置，使用Promise异步回调。调用成功即返回，但返回后无法立即获取最终生效结果。如需立即获取，请使用[moveWindowToAsync()](#movewindowtoasync12)。 > **说明：** > > - 不建议在除自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）外的其他窗口模式下使用。 > > - 在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，窗口相对于屏幕左上顶点移动；在非自由窗口状态下，窗口相对于父窗口左上顶点移动。 > > - 若需在非自由窗口状态下实现相对于屏幕左上顶点的移动，请使用[moveWindowToGlobal()](#movewindowtoglobal15)。 > > - 该方法对非自由窗口状态下的主窗口无效。 > > - [自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，若主窗口或子窗口的标题栏移出屏幕可视区域，系统将自动回弹窗口，确保标题栏保持可见。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -- | ----- | -- | --------------------------------------------- | | x | number | 是 | 窗口在x轴方向移动到的坐标位置，单位为px，值为正表示在原点右侧，值为负表示在原点左侧。该参数仅支持整数输入，浮点数输入将向下取整。 | | y | number | 是 | 窗口在y轴方向移动到的坐标位置，单位为px，值为正表示在原点下方，值为负表示在原点上方。该参数仅支持整数输入，浮点数输入将向下取整。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { let promise = windowClass.moveWindowTo(300, 300); promise.then(() => { console.info('Succeeded in moving the window.'); }).catch((err: BusinessError) => { console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## resize9+ resize(width: number, height: number, callback: AsyncCallback<void>): void 基于窗口左上角顶点改变当前窗口大小，使用callback异步回调。 调用成功即返回，该接口返回后无法立即获取最终生效结果，如需立即获取，建议使用接口[resizeAsync()](#resizeasync12)。 窗口存在大小限制[WindowLimits](arkts-apis-window-i.md#windowlimits11)，具体尺寸限制范围可以通过[getWindowLimits](#getwindowlimits11)接口进行查询。 调用该接口设置的宽度与高度受到此限制约束，规则： 若所设置的窗口宽/高尺寸小于窗口最小宽/高限制值，则窗口最小宽/高限制值生效，系统窗口和全局悬浮窗设置最小值不受窗口最小宽/高限制值限制； 若所设置的窗口宽/高尺寸大于窗口最大宽/高限制值，则窗口最大宽/高限制值生效。 该接口仅在窗口为自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，窗口模式可通过[getWindowStatus()](#getwindowstatus12)获取）时调用生效，在其他窗口模式下调用返回1300002错误码。 > **说明：** > > - 主窗口处于自由悬浮窗口模式时，在非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下调用不报错不生效。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | -- | ------------------------ | | width | number | 是 | 当前窗口的目标宽度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数（抛出错误码401）。 | | height | number | 是 | 当前窗口的目标高度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数（抛出错误码401）。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error; 3. Invalid window status type. Only supports windows in floating window mode. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { windowClass.resize(500, 1000, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in changing the window size.'); }); } catch (exception) { console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## resize9+ resize(width: number, height: number): Promise<void> 基于窗口左上角顶点改变当前窗口大小，使用Promise异步回调。 调用成功即返回，该接口返回后无法立即获取最终生效结果，如需立即获取，建议使用接口[resizeAsync()](#resizeasync12)。 窗口存在大小限制[WindowLimits](arkts-apis-window-i.md#windowlimits11)，具体尺寸限制范围可以通过[getWindowLimits](#getwindowlimits11)接口进行查询。 调用该接口设置的宽度与高度受到此限制约束，规则： 若所设置的窗口宽/高尺寸小于窗口最小宽/高限制值，则窗口最小宽/高限制值生效，系统窗口和全局悬浮窗设置最小值不受窗口最小宽/高限制值限制； 若所设置的窗口宽/高尺寸大于窗口最大宽/高限制值，则窗口最大宽/高限制值生效。 该接口仅在窗口为自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，窗口模式可通过[getWindowStatus()](#getwindowstatus12)获取）时调用生效，在其他窗口模式下调用返回1300002错误码。 > **说明：** > > - 主窗口处于自由悬浮窗口模式时，在非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下调用不报错不生效。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | -- | ------------------------ | | width | number | 是 | 当前窗口的目标宽度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数（抛出错误码401）。 | | height | number | 是 | 当前窗口的目标高度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数（抛出错误码401）。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error; 3. Invalid window status type. Only supports windows in floating window mode. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { let promise = windowClass.resize(500, 1000); promise.then(() => { console.info('Succeeded in changing the window size.'); }).catch((err: BusinessError) => { console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## getWindowProperties9+ getWindowProperties(): WindowProperties 获取当前窗口的属性。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **返回值：** | 类型 | 说明 | | ------------------------------------- | ------------- | | [WindowProperties](arkts-apis-window-i.md#windowproperties) | 当前窗口属性。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | **示例：** ```ts try { let properties = windowClass.getWindowProperties(); } catch (exception) { console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## getWindowAvoidArea9+ getWindowAvoidArea(type: AvoidAreaType): AvoidArea 获取当前窗口避让区域。 主窗口/子窗口： - [自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的自由悬浮窗口模式（即窗口模式为[window.WindowStatusType.FLOATING](arkts-apis-window-e.md#windowstatustype11)）下，仅存在固定态软键盘（[AvoidAreaType](arkts-apis-window-e.md#avoidareatype7)为TYPE_KEYBOARD）类型的避让区域。 - 主窗口在非自由窗口状态的自由悬浮窗口模式下，仅存在系统栏（[AvoidAreaType](arkts-apis-window-e.md#avoidareatype7)为TYPE_SYSTEM）类型的避让区域。 - 主窗口在其余场景下，仅当在非自由悬浮窗口模式下或设备类型为Phone和Tablet，才能通过此接口获取计算后的避让区域，否则获取的避让区域为空。 - 子窗口在非自由窗口状态或非自由悬浮窗口模式下，仅当窗口的位置和大小与主窗口一致时，才能通过此接口获取计算后的避让区域，否则获取的避让区域为空。 全局悬浮窗、模态窗或系统窗口： - 仅在调用[setSystemAvoidAreaEnabled](#setsystemavoidareaenabled18)方法使能后，才能通过此接口获取避让区域，否则获取的避让区域为空。 该接口一般适用于两种场景： - 在[onWindowStageCreate()](../apis-ability-kit/js-apis-app-ability-uiAbility.md#onwindowstagecreate)方法中，获取应用启动时的初始布局避让区域时可调用该接口。 - 当应用内子窗需要临时显示，对显示内容做布局避让时可调用该接口。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- |----------------------------------| -- | ------------------------------------------------------------ | | type | [AvoidAreaType](arkts-apis-window-e.md#avoidareatype7) | 是 | 表示避让区域类型。 | **返回值：** | 类型 | 说明 | |--------------------------| ----------------- | | [AvoidArea](arkts-apis-window-i.md#avoidarea7) | 窗口内容避让区域。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Convert avoid area failed. | **示例：** ```ts let type = window.AvoidAreaType.TYPE_SYSTEM; try { let avoidArea = windowClass.getWindowAvoidArea(type); } catch (exception) { console.error(`Failed to obtain the area. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowLayoutFullScreen9+ setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 设置应用主窗口或应用子窗口的布局是否为沉浸式布局，使用Promise异步回调。其余窗口调用不生效也不报错。 沉浸式布局生效时，布局不避让状态栏与三键导航栏，组件可能产生与其重叠的情况。 非沉浸式布局生效时，布局避让状态栏与三键导航栏，组件不会与其重叠。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **设备行为差异：** 在OpenHarmony 5.0.2之前，该接口在所有设备中可正常调用。 从OpenHarmony 5.0.2开始，该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错，切换到非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态时生效；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ | | isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局（该沉浸式布局状态栏、三键导航栏仍然显示）。true表示沉浸式布局；false表示非沉浸式布局。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let isLayoutFullScreen = true; try { let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen); promise.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 code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## setImmersiveModeEnabledState12+ setImmersiveModeEnabledState(enabled: boolean): void 设置当前窗口是否开启沉浸式布局，该调用不会改变窗口模式和窗口大小。仅主窗口和子窗口可调用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **设备行为差异：** 在OpenHarmony 5.0.2之前，该接口在所有设备中可正常调用。 从OpenHarmony 5.0.2开始，该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------- | ---- | ------------------------------------------------------------ | | enabled | boolean | 是 | 是否开启沉浸式布局。
true表示开启，false表示关闭。
| **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | | 1300003 | This window manager service works abnormally. Possible cause: Internal IPC error. | | 1300004 | Unauthorized operation. Possible cause: Invalid window type. Only main windows and subwindows are supported. | **示例：** ```ts try { let enabled = false; windowClass.setImmersiveModeEnabledState(enabled); } catch (exception) { console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowSystemBarEnable9+ setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 设置主窗口状态栏、三键导航栏的可见模式，状态栏通过status控制、三键导航栏通过navigation控制，使用Promise异步回调。 调用生效后返回并不表示状态栏、三键导航栏的显示或隐藏已完成。主窗口在非全屏/最大化模式（悬浮窗、分屏等场景）下配置不生效，进入全屏/最大化模式后配置生效。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **设备行为差异：** 在OpenHarmony 5.0.0之前，该接口在所有设备中可正常调用。 从OpenHarmony 5.0.0开始，该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | -- | --------------------------------- | | names | Array<'status'\|'navigation'> | 是 | 设置窗口全屏/最大化模式时状态栏、三键导航栏是否显示。
例如，需全部显示，该参数设置为['status', 'navigation']；设置为[]，则不显示。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // 此处以状态栏等均不显示为例 // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let names: Array<'status' | 'navigation'> = []; try { let promise = windowClass.setWindowSystemBarEnable(names); promise.then(() => { console.info('Succeeded in setting the system bar to be invisible.'); }).catch((err: BusinessError) => { console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## setSpecificSystemBarEnabled11+ setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void> 设置主窗口状态栏、三键导航栏的显示或隐藏，使用Promise异步回调。 调用生效后返回并不表示状态栏、三键导航栏的显示或隐藏已完成。子窗口调用后不生效。主窗口在非全屏/最大化模式（悬浮窗、分屏等场景）下配置不生效，进入全屏/最大化模式后配置生效。 **系统能力：** SystemCapability.Window.SessionManager **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **设备行为差异：** 在OpenHarmony 5.0.0之前，该接口在所有设备中可正常调用。 从OpenHarmony 5.0.0开始，该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | -- | --------------------------------- | | name | [SpecificSystemBar](arkts-apis-window-t.md#specificsystembar11) | 是 | 设置窗口全屏模式时，显示或隐藏的系统栏类型。 | | enable | boolean | 是 | 设置窗口全屏模式时状态栏或三键导航栏是否显示，true表示显示， false表示隐藏。| | enableAnimation12+ | boolean | 否 | 设置状态栏或三键导航栏显示状态变化时是否使用动画，true表示使用， false表示不使用，默认值为false。| **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // 此处以隐藏状态栏为例 // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; try { let promise = windowClass.setSpecificSystemBarEnabled('status', false); promise.then(() => { console.info('Succeeded in setting the system bar to be invisible.'); }).catch((err: BusinessError) => { console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## setWindowSystemBarProperties9+ setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 设置主窗口三键导航栏、状态栏的属性，使用Promise异步回调。 子窗口调用后不生效。主窗口在非全屏/最大化模式（悬浮窗、分屏等场景）下配置不生效，进入全屏/最大化模式后配置生效。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **设备行为差异：** 该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------- | ------------------------------------------- | ---- | ---------------------- | | systemBarProperties | [SystemBarProperties](arkts-apis-window-i.md#systembarproperties) | 是 | 三键导航栏、状态栏的属性。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let SystemBarProperties: window.SystemBarProperties = { statusBarColor: '#ff00ff', navigationBarColor: '#00ff00', // 以下两个属性从API Version8开始支持 statusBarContentColor: '#ffffff', navigationBarContentColor: '#00ffff' }; try { let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties); promise.then(() => { console.info('Succeeded in setting the system bar properties.'); }).catch((err: BusinessError) => { console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## setUIContent9+ setUIContent(path: string, callback: AsyncCallback<void>): void 根据当前工程中指定的某个页面路径为窗口加载具体页面内容，使用callback异步回调。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | -- | -------------------- | | path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。不支持相对路径写法，需与main_pages.json或config.json中的src取值保持一致。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { windowClass.setUIContent('pages/page2/page3', (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in loading the content.'); }); } catch (exception) { console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setUIContent9+ setUIContent(path: string): Promise<void> 根据当前工程中指定的某个页面路径为窗口加载具体页面内容，使用Promise异步回调。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | -- | ------------------ | | path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。不支持相对路径写法，需与main_pages.json或config.json中的src取值保持一致。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { let promise = windowClass.setUIContent('pages/page2/page3'); promise.then(() => { console.info('Succeeded in loading the content.'); }).catch((err: BusinessError) => { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## loadContent9+ loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 根据当前工程中指定的页面路径为窗口加载具体页面内容，通过LocalStorage传递状态属性给加载的页面，使用callback异步回调。 建议在UIAbility启动过程中使用该接口，重复调用将先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。 当前UI的执行上下文可能不明确，所以不建议在本接口的回调函数中做UI相关的操作。 **模型约束：** 此接口仅可在Stage模型下使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | 是 | 要加载到窗口中的页面内容的路径，该路径需添加到工程的main_pages.json文件中。不支持相对路径写法，需与main_pages.json中的src取值保持一致。 | | storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 是 | 页面级UI状态存储单元，这里用于为加载到窗口的页面内容传递状态属性。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter.| | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let storage: LocalStorage = new LocalStorage(); storage.setOrCreate('storageSimpleProp', 121); windowClass.loadContent('pages/page2', storage, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in loading the content.'); }); ``` ## loadContent9+ loadContent(path: string, storage: LocalStorage): Promise<void> 根据当前工程中指定的页面路径为窗口加载具体页面内容，通过LocalStorage传递状态属性给加载的页面，使用Promise异步回调。 建议在UIAbility启动过程中使用该接口，重复调用将先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。 当前UI的执行上下文可能不明确，所以不建议在本接口的回调函数中做UI相关的操作。 **模型约束：** 此接口仅可在Stage模型下使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | 是 | 要加载到窗口中的页面内容的路径，该路径需添加到工程的main_pages.json文件中。不支持相对路径写法，需与main_pages.json中的src取值保持一致。 | | storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 是 | 页面级UI状态存储单元，这里用于为加载到窗口的页面内容传递状态属性。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter.| | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let storage: LocalStorage = new LocalStorage(); storage.setOrCreate('storageSimpleProp', 121); let promise = windowClass.loadContent('pages/page2', storage); promise.then(() => { console.info('Succeeded in loading the content.'); }).catch((err: BusinessError) => { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); }); ``` ## on('windowSizeChange')7+ on(type: 'windowSizeChange', callback: Callback<Size>): void 开启窗口尺寸变化的监听。仅在主线程调用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------ | ---- | -------------------------------------------------------- | | type | string | 是 | 监听事件，固定为'windowSizeChange'，即窗口尺寸变化事件。 | | callback | Callback<[Size](arkts-apis-window-i.md#size7)> | 是 | 回调函数。返回当前的窗口尺寸。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | **示例：** ```ts try { windowClass.on('windowSizeChange', (data) => { console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data)); }); } catch (exception) { console.error(`Failed to enable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## on('avoidAreaChange')9+ on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void 开启当前应用窗口系统避让区域变化的监听。 主窗口/子窗口： - [自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的自由悬浮窗口模式（即窗口模式为[window.WindowStatusType.FLOATING](arkts-apis-window-e.md#windowstatustype11)）下触发回调时，仅存在固定态软键盘（[AvoidAreaType](arkts-apis-window-e.md#avoidareatype7)为TYPE_KEYBOARD）类型的避让区域。 - 主窗口在非自由窗口状态的自由悬浮窗口模式下触发回调时，仅存在系统栏（[AvoidAreaType](arkts-apis-window-e.md#avoidareatype7)为TYPE_SYSTEM）类型的避让区域。 - 主窗口在其余场景下触发回调时，仅当在非自由悬浮窗口模式下或设备类型为Phone和Tablet，才能返回计算后的避让区域，否则直接返回空的避让区域。 - 子窗口在非自由窗口状态或非自由悬浮窗口模式下触发回调时，仅当子窗口的位置和大小与主窗口一致时，才能返回计算后的子窗口避让区域，否则直接返回空的避让区域。 全局悬浮窗、模态窗或系统窗口： - 仅在调用[setSystemAvoidAreaEnabled](#setsystemavoidareaenabled18)方法使能后，触发回调时才能返回计算后的避让区域，否则直接返回空的避让区域。 常见的触发避让区回调的场景如下：应用窗口在全屏模式、悬浮模式、分屏模式之间的切换；应用窗口旋转；可折叠设备在屏幕折叠状态发生变化；应用窗口在多设备之间的流转。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- |----------------------------------| ---- |--------------------------------------| | type | string | 是 | 监听事件，固定为'avoidAreaChange'，即系统避让区变化事件。 | | callback | Callback<[AvoidAreaOptions](arkts-apis-window-i.md#avoidareaoptions12)> | 是 | 回调函数。返回当前避让区以及避让区类型。| **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | **示例：** ```ts try { windowClass.on('avoidAreaChange', (data) => { console.info('Succeeded in enabling the listener for system avoid area changes. type:' + JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area)); }); } catch (exception) { console.error(`Failed to enable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## on('keyboardHeightChange')7+ on(type: 'keyboardHeightChange', callback: Callback<number>): void 开启固定态软键盘高度变化的监听。当软键盘从本窗口唤出且与窗口有重叠区域时，通知键盘高度变化。从API version 10开始，有关将软键盘设置为固定态或悬浮态的方法，请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------- | ---- |-------------------------------------------| | type | string | 是 | 监听事件，固定为'keyboardHeightChange'，即键盘高度变化事件。 | | callback | Callback<number> | 是 | 回调函数。返回当前的键盘高度。返回值为整数，单位为px。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { windowClass.on('keyboardHeightChange', (data) => { console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data)); }); } catch (exception) { console.error(`Failed to enable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## on('windowEvent')10+ on(type: 'windowEvent', callback: Callback<WindowEventType>): void 开启窗口生命周期变化的监听。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | | type | string | 是 | 监听事件，固定为'windowEvent'，即窗口生命周期变化事件。 | | callback | Callback<[WindowEventType](arkts-apis-window-e.md#windoweventtype10)> | 是 | 回调函数。返回当前的窗口生命周期状态。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | **示例：** ```ts try { windowClass.on('windowEvent', (data) => { console.info('Window event happened. Event:' + JSON.stringify(data)); }); } catch (exception) { console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowBackgroundColor9+ setWindowBackgroundColor(color: string | ColorMetrics): void 设置窗口的背景色。 未调用该接口时，窗口在浅色模式默认背景色为`'#FFF0F0F0'`，在深色模式默认背景色为`'#FF1A1A1A'`。 Stage模型下，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | -- | ----------------------------------------------------------------------- | | color | string \| [ColorMetrics](js-apis-arkui-graphics.md#colormetrics12)18+ | 是 | 需要设置的背景色，为十六进制RGB或ARGB颜色，不区分大小写，例如`'#00FF00'`或`'#FF00FF00'`。
从API version 18开始，此参数支持ColorMetrics类型。| **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { ColorMetrics } from '@kit.ArkUI'; let storage: LocalStorage = new LocalStorage(); storage.setOrCreate('storageSimpleProp', 121); windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { let errCode: number = err.code; if (errCode) { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in loading the content.'); let color1: string = '#00FF33'; let color2: ColorMetrics = ColorMetrics.numeric(0xff112233); try { windowClass?.setWindowBackgroundColor(color1); windowClass?.setWindowBackgroundColor(color2); } catch (exception) { console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`); }; }); ``` ## setWindowBrightness9+ setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void 主窗口设置窗口亮度。当窗口处于前台且获焦时，窗口亮度生效。使用callback异步回调。 窗口亮度生效时只会影响当前设备屏幕亮度，无法修改虚拟屏（如投屏所在的屏幕）的屏幕亮度。 当接口入参为-1时，窗口亮度恢复为系统屏幕亮度（可以通过控制中心或快捷键调整）。 当窗口退至后台时，窗口亮度失效，可以通过控制中心或快捷键调整。不建议连续调用或窗口退至后台时调用此接口，否则可能产生时序问题。 **设备行为差异：** - 针对TV设备：当前接口不生效也不报错。 - 针对非2in1设备（不包含TV设备）： - 在OpenHarmony 6.1之前，当前窗口的窗口亮度生效时，控制中心调整系统屏幕亮度不生效。 - 从OpenHarmony 6.1开始，当前窗口的窗口亮度生效时，控制中心可以调整系统屏幕亮度，同时会将当前窗口恢复为系统屏幕亮度。 - 针对2in1设备： - 在OpenHarmony 5.0.2之前，窗口设置屏幕亮度生效时，控制中心或快捷键调整系统屏幕亮度不生效。 - 从OpenHarmony 5.0.2开始，窗口亮度与系统屏幕亮度保持一致，可以通过本接口、控制中心或者快捷键设置系统屏幕亮度。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------------------------- | -- |-------------------------------------------| | brightness | number | 是 | 屏幕亮度值。该参数为浮点数，取值范围为[0.0, 1.0]或-1.0。1.0表示最亮，-1.0表示恢复成设置窗口亮度前的系统控制中心亮度。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); windowStage.loadContent('pages/Index', (loadError: BusinessError) => { if (loadError.code) { console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`); return; } let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let brightness: number = 1.0; try { windowClass.setWindowBrightness(brightness, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the brightness.'); }); } catch (exception) { console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); } }); }); } } ``` ## setWindowBrightness9+ setWindowBrightness(brightness: number): Promise<void> 主窗口设置窗口亮度。当窗口处于前台且获焦时，窗口亮度生效。使用Promise异步回调。 窗口亮度生效时只会影响当前设备屏幕亮度，无法修改虚拟屏（如投屏所在的屏幕）的屏幕亮度。 当接口入参为-1时，窗口亮度恢复为系统屏幕亮度（可以通过控制中心或快捷键调整）。 当窗口退至后台时，窗口亮度失效，可以通过控制中心或快捷键调整。不建议连续调用或窗口退至后台时调用此接口，否则可能产生时序问题。 **设备行为差异：** - 针对TV设备：当前接口不生效也不报错。 - 针对非2in1设备（不包含TV设备）： - 在OpenHarmony 6.1之前，当前窗口的窗口亮度生效时，控制中心调整系统屏幕亮度不生效。 - 从OpenHarmony 6.1开始，当前窗口的窗口亮度生效时，控制中心可以调整系统屏幕亮度，同时会将当前窗口恢复为系统屏幕亮度。 - 针对2in1设备： - 在OpenHarmony 5.0.2之前，窗口设置屏幕亮度生效时，控制中心或快捷键调整系统屏幕亮度不生效。 - 从OpenHarmony 5.0.2开始，窗口亮度与系统屏幕亮度保持一致，可以通过本接口、控制中心或者快捷键设置系统屏幕亮度。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------ | -- |----------------------------------------| | brightness | number | 是 | 屏幕亮度值。该参数为浮点数，取值范围为[0.0, 1.0]或-1.0。1.0表示最亮，-1.0表示恢复成设置窗口亮度前的系统控制中心亮度。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); windowStage.loadContent('pages/Index', (loadError: BusinessError) => { if (loadError.code) { console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`); return; } let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let brightness: number = 1.0; try { let promise = windowClass.setWindowBrightness(brightness); promise.then(() => { console.info('Succeeded in setting the brightness.'); }).catch((err: BusinessError) => { console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); } }); }); } } ``` ## setWindowFocusable9+ setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 设置窗口是否具有获得焦点的能力，使用callback异步回调。 从API version 22开始，调用[createVirtualScreen](js-apis-display.md#displaycreatevirtualscreen16)接口创建虚拟屏，并设置supportsFocus配置项为false时，位于该虚拟屏的窗口无法调用该接口修改窗口的可获焦能力，如果调用，会抛出1300002错误码。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------------------------- | -- | ------------------------------------------------------- | | isFocusable | boolean | 是 | 窗口是否可获焦。true表示支持；false表示不支持。设置为false时，该窗口不支持绑定输入法和接收键盘事件，如需处理输入逻辑，建议参考[不可获焦窗口中输入框与输入法交互指南](../../inputmethod/use-inputmethod-in-not-focusable-window.md)。| | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isFocusable: boolean = true; try { windowClass.setWindowFocusable(isFocusable, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the window to be focusable.'); }); } catch (exception) { console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowFocusable9+ setWindowFocusable(isFocusable: boolean): Promise<void> 设置窗口是否具有获得焦点的能力，使用Promise异步回调。 从API version 22开始，调用[createVirtualScreen](js-apis-display.md#displaycreatevirtualscreen16)接口创建虚拟屏，并设置supportsFocus配置项为false时，位于该虚拟屏的窗口无法调用该接口修改窗口的可获焦能力，如果调用，会抛出1300002错误码。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------- | -- | -------------------------------------------------------- | | isFocusable | boolean | 是 | 窗口是否可获焦。true表示支持；false表示不支持。设置为false时，该窗口不支持绑定输入法和接收键盘事件，如需处理输入逻辑，建议参考[不可获焦窗口中输入框与输入法交互指南](../../inputmethod/use-inputmethod-in-not-focusable-window.md)。| **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isFocusable: boolean = true; try { let promise = windowClass.setWindowFocusable(isFocusable); promise.then(() => { console.info('Succeeded in setting the window to be focusable.'); }).catch((err: BusinessError) => { console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowKeepScreenOn9+ setWindowKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 设置当前窗口位于前台时当前设备的屏幕是否为常亮状态，异源虚拟屏下不生效。使用callback异步回调。 仅在必要场景（导航、视频播放、绘画、游戏等场景）下，设置该属性为true；退出上述场景后，应当重置该属性为false；其他场景（无屏幕互动、音频播放等）下，不使用该接口；系统检测到非规范使用该接口时，可能会恢复自动灭屏功能。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------------- | ------------------------- | -- | ---------------------------------------------------- | | isKeepScreenOn | boolean | 是 | 设置屏幕是否为常亮状态。true表示常亮；false表示不常亮。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isKeepScreenOn: boolean = true; try { windowClass.setWindowKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the screen to be always on.'); }); } catch (exception) { console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowKeepScreenOn9+ setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 设置当前窗口位于前台时当前设备的屏幕是否为常亮状态，异源虚拟屏下不生效。使用Promise异步回调。 仅在必要场景（导航、视频播放、绘画、游戏等场景）下，设置该属性为true；退出上述场景后，应当重置该属性为false；其他场景（无屏幕互动、音频播放等）下，不使用该接口；系统检测到非规范使用该接口时，可能会恢复自动灭屏功能。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------------- | ------- | -- | --------------------------------------------------- | | isKeepScreenOn | boolean | 是 | 设置屏幕是否为常亮状态。true表示常亮；false表示不常亮。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isKeepScreenOn: boolean = true; try { let promise = windowClass.setWindowKeepScreenOn(isKeepScreenOn); promise.then(() => { console.info('Succeeded in setting the screen to be always on.'); }).catch((err: BusinessError) => { console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowPrivacyMode9+ setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 设置窗口是否为隐私模式，使用callback异步回调。 设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。 隐私模式窗口退后台后在多任务卡片中显示为白色蒙层或隐私蒙层。 未调用此接口时，窗口默认不开启隐私模式，可以被截屏或录屏。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **需要权限：** ohos.permission.PRIVACY_WINDOW **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------- | ------------------------- | -- | ------------------------------------------------------ | | isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示为隐私模式，false表示为非隐私模式。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 201 | Permission verification failed. The application does not have the permission required to call the API. Possible cause: Need ohos.permission.PRIVACY_WINDOW permission. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isPrivacyMode: boolean = true; try { windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the window to privacy mode.'); }); } catch (exception) { console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowPrivacyMode9+ setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 设置窗口是否为隐私模式，使用Promise异步回调。 设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。 隐私模式窗口退后台后在多任务卡片中显示为白色蒙层或隐私蒙层。 未调用此接口时，窗口默认不开启隐私模式，可以被截屏或录屏。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **需要权限：** ohos.permission.PRIVACY_WINDOW **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------- | ------- | -- | ----------------------------------------------------- | | isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示为隐私模式，false表示为非隐私模式。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 201 | Permission verification failed. The application does not have the permission required to call the API. Possible cause: Need ohos.permission.PRIVACY_WINDOW permission. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isPrivacyMode: boolean = true; try { let promise = windowClass.setWindowPrivacyMode(isPrivacyMode); promise.then(() => { console.info('Succeeded in setting the window to privacy mode.'); }).catch((err: BusinessError) => { console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowTouchable9+ setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 设置窗口是否为可点击状态，使用callback异步回调。 当窗口处于可点击状态时，若用户点击命中该窗口，事件将发送给该窗口处理。当窗口处于不可点击状态时，透传点击事件，传递给下层窗口。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------------------------- | -- | ----------------------------------------------- | | isTouchable | boolean | 是 | 窗口是否为可点击状态。true表示可点击；false表示不可点击。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isTouchable = true; try { windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the window to be touchable.'); }); } catch (exception) { console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowTouchable9+ setWindowTouchable(isTouchable: boolean): Promise<void> 设置窗口是否为可点击状态，使用Promise异步回调。 当窗口处于可点击状态时，若用户点击命中该窗口，事件将发送给该窗口处理。当窗口处于不可点击状态时，透传点击事件，传递给下层窗口。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------- | -- | ----------------------------------------------- | | isTouchable | boolean | 是 | 窗口是否为可点击状态。true表示可点击；false表示不可点击。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | -------------------------------------------- | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let isTouchable: boolean = true; try { let promise = windowClass.setWindowTouchable(isTouchable); promise.then(() => { console.info('Succeeded in setting the window to be touchable.'); }).catch((err: BusinessError) => { console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## snapshot9+ snapshot(callback: AsyncCallback<image.PixelMap>): void 获取窗口截图，使用callback异步回调。若当前窗口设置为隐私模式（可通过[setWindowPrivacyMode](#setwindowprivacymode9)接口设置），截图结果为白屏。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------------------------- | ---- | -------------------- | | callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Get pixelMap failed; 3. Internal task error. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { image } from '@kit.ImageKit'; windowClass.snapshot((err: BusinessError, pixelMap: image.PixelMap) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); pixelMap.release(); // PixelMap使用完后及时释放内存 }); ``` ## snapshot9+ snapshot(): Promise<image.PixelMap> 获取当前窗口截图。若当前窗口设置为隐私模式（可通过[setWindowPrivacyMode](#setwindowprivacymode9)接口设置），截图结果为白屏。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象。返回当前窗口截图。 | **错误码：** 以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Get pixelMap failed; 3. Internal task error. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { image } from '@kit.ImageKit'; let promise = windowClass.snapshot(); promise.then((pixelMap: image.PixelMap) => { console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); pixelMap.release(); // PixelMap使用完后及时释放内存 }).catch((err: BusinessError) => { console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); }); ``` ## minimize11+ minimize(callback: AsyncCallback<void>): void 此接口根据调用对象不同，实现不同的功能： - 当调用对象为主窗口时，实现最小化功能，可在Dock栏中还原，2in1 设备上可以使用[restore()](#restore14)进行还原。 - 当调用对象为子窗口或全局悬浮窗时，实现隐藏功能，不可在Dock栏中还原，可以使用[showWindow()](#showwindow9)进行还原。 该接口仅支持主窗口、子窗口或全局悬浮窗，其它窗口调用返回1300002错误码，使用callback异步回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.Window.SessionManager **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error; 3.Invalid window type. Only main windows, subwindows, and float windows are supported. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; windowClass.minimize((err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in minimizing the window.'); }); ``` ## minimize11+ minimize(): Promise<void> 此接口根据调用对象不同，实现不同的功能： - 当调用对象为主窗口时，实现最小化功能，可在Dock栏中还原，2in1 设备上可以使用[restore()](#restore14)进行还原。 - 当调用对象为子窗口或全局悬浮窗时，实现隐藏功能，不可在Dock栏中还原，可以使用[showWindow()](#showwindow9)进行还原。 该接口仅支持主窗口、子窗口或全局悬浮窗，其它窗口调用返回1300002错误码，使用Promise异步回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.Window.SessionManager **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error; 3.Invalid window type. Only main windows, subwindows, and float windows are supported. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let promise = windowClass.minimize(); promise.then(() => { console.info('Succeeded in minimizing the window.'); }).catch((err: BusinessError) => { console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); }); ``` ## maximize12+ maximize(presentation?: MaximizePresentation): Promise<void> 实现最大化功能。主窗口可调用此接口实现最大化功能；子窗口需在创建时设置子窗口参数maximizeSupported为true，再调用此接口可实现最大化功能。使用Promise异步回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.Window.SessionManager **设备行为差异：** 该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | -- | --------------------------------- | | presentation | [MaximizePresentation](arkts-apis-window-e.md#maximizepresentation12) | 否 | 主窗口或子窗口最大化时的布局枚举。默认值window.MaximizePresentation.ENTER_IMMERSIVE，即默认最大化时进入全屏模式。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 801 | Capability not supported. Function maximize can not work correctly due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | | 1300003 | This window manager service works abnormally. | | 1300004 | Unauthorized operation. Possible cause: Invalid window type. Only main windows and maximizable subwindows are supported. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage) { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let promise = windowClass.maximize(); // let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); promise.then(() => { console.info('Succeeded in maximizing the window.'); }).catch((err: BusinessError) => { console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`); }); }); } }; ``` ## maximize22+ maximize(presentation?: MaximizePresentation, acrossDisplay?: boolean): Promise<void> 实现最大化功能。主窗口可调用此接口实现最大化功能；子窗口需在创建时设置子窗口参数maximizeSupported为true，再调用此接口可实现最大化功能。在具备折叠功能的2in1设备上，支持控制悬停态（参考[折叠屏悬停态最佳实践](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-folded-hover)）下主窗口的瀑布流模式行为，即窗口在悬停态下最大化时是否跨上下两个半屏显示。使用Promise异步回调。 **系统能力：** SystemCapability.Window.SessionManager **设备行为差异：** 该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | -- | --------------------------------- | | presentation | [MaximizePresentation](arkts-apis-window-e.md#maximizepresentation12) | 否 | 主窗口或子窗口最大化时的布局枚举。默认值window.MaximizePresentation.ENTER_IMMERSIVE，即默认最大化时进入全屏模式。 | | acrossDisplay | boolean | 否 | 控制悬停态下主窗口在最大化时的瀑布流模式行为。默认值为`undefined`。
仅主窗口可设置此参数，非主窗口调用时返回错误码`1300004`。
取值为`true`时：
- 悬停态下，窗口将直接进入瀑布流模式；
- 展开态下，窗口进入最大化，并在悬停态下保持瀑布流模式。
取值为`false`时：
- 悬停态下，窗口将退出瀑布流模式，进入单面最大化（即窗口最大化时只在上半屏或下半屏显示）；
- 展开态下，窗口进入最大化，并在悬停态下退出瀑布流模式。
取值为`undefined`时，不修改窗口瀑布流模式行为：
- 悬停态下，窗口进入单面最大化；
- 展开态下，窗口进入最大化，并在悬停态下默认保持瀑布流模式。
**设备行为差异：** 仅在具备折叠功能的2in1设备可正常调用；在其他设备上调用不生效。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | Promise对象，无返回结果。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 801 | Capability not supported. Function maximize can not work correctly due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: The window is not created or destroyed. | | 1300003 | This window manager service works abnormally. | | 1300004 | Unauthorized operation. Possible cause: Invalid window type. Only main windows and maximizable subwindows are supported. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.loadContent('pages/Index', (err) => { if (err.code) { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); return; } let mainWindow = windowStage.getMainWindowSync(); mainWindow.maximize(window.MaximizePresentation.ENTER_IMMERSIVE, true) .then(() => { console.info('Window maximized successfully.'); }) .catch((err: BusinessError) => { console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`); }); }); } }; ``` ## recover11+ recover(): Promise<void> 将主窗口从全屏、最大化、分屏模式下还原为自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING），并恢复到进入该模式之前的大小和位置，已经是自由悬浮窗口模式不可再还原。使用Promise异步回调。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.Window.SessionManager **设备行为差异：** 该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用返回801错误码。 **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300001 | Repeated operation. | | 1300002 | This window state is abnormal. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); try { let windowClass = windowStage.getMainWindowSync(); if (!windowClass) { console.error('Failed to get main window.'); return; } let promise = windowClass.recover(); promise.then(() => { console.info('Succeeded in recovering the window.'); }).catch((err: BusinessError) => { console.error(`Failed to recover the window. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to recover the window. Cause code: ${exception.code}, message: ${exception.message}`); } } } ``` ## setWindowTitle15+ setWindowTitle(titleName: string): Promise<void> 设置窗口标题，使用Promise异步回调。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.Window.SessionManager **设备行为差异：** 该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备调用不报错不生效，切换到[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态后生效；在不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用返回1300002或801错误码。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------- | ---- | --------------------------------------------- | | titleName | string | 是 | 窗口标题。标题显示区域最右端不超过系统三键区域最左端，超过部分以省略号表示。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------ | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { let title = "title"; windowClass.setWindowTitle(title).then(() => { console.info('Succeeded in setting the window title.'); }).catch((err: BusinessError) => { console.error(`Failed to set the window title. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set the window title. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## getWindowStatus12+ getWindowStatus(): WindowStatusType 获取当前应用窗口的模式。 > **说明：** > > 在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，应用的[targetAPIVersion](../../quick-start/app-configuration-file.md#配置文件标签)设置小于14时，在窗口最大化状态（窗口铺满整个屏幕，2in1设备会有dock栏和状态栏，Tablet设备会有状态栏）时返回值对应为WindowStatusType::FULL_SCREEN。应用的[targetAPIVersion](../../quick-start/app-configuration-file.md#配置文件标签)设置大于等于14时，在窗口最大化状态（窗口铺满整个屏幕，2in1设备会有dock栏和状态栏，Tablet设备会有状态栏）时返回值对应为WindowStatusType::MAXIMIZE。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.Window.SessionManager **返回值：** | 类型 | 说明 | | ------------------------------ | ----------------------------------------| | [WindowStatusType](arkts-apis-window-e.md#windowstatustype11) | 当前窗口模式。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | ------- | ------------------------------ | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300002 | This window state is abnormal. | **示例：** ```ts try { let windowStatusType = windowClass.getWindowStatus(); } catch (exception) { console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowCornerRadius17+ setWindowCornerRadius(cornerRadius: number): Promise<void> 设置子窗或全局悬浮窗的圆角半径值，使用Promise异步回调。 圆角半径值过大将会导致三键（最大化、最小化、关闭按钮）位置被裁切，且会导致热区不易识别，请根据窗口大小设置合适的圆角半径值。 在调用此接口之前调用[getWindowCornerRadius()](#getwindowcornerradius17)接口可以获得窗口默认圆角半径值。 **系统能力**：SystemCapability.Window.SessionManager **设备行为差异：** 在OpenHarmony 6.0之前，该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用返回801错误码。 从OpenHarmony 6.0开始，该接口在Phone设备、Tablet设备和2in1设备下可正常调用，在其他设备中返回801错误码。 **原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------- | ---- |----------------------------------------------------| | cornerRadius | number | 是 | 表示窗口圆角的半径值。该参数为浮点数，单位为vp，取值范围为[0.0, +∞)，取值为0.0时表示没有窗口圆角。 | **返回值：** | 类型 | 说明 | | ---------------------- | ------------------------------------------------------------------------------------ | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | |---------|-------------------------------------------------------------------------------------------------------------------| | 401 | Parameter error. Possible cause: The corner radius is less than zero. | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300002 | This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error. | | 1300003 | This window manager service works abnormally. | | 1300004 | Unauthorized operation. | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; try { let promise = windowClass.setWindowCornerRadius(1.0); promise.then(() => { console.info('Succeeded in setting window corner radius.'); }).catch((err: BusinessError) => { console.error(`Failed to set window corner radius. Cause code: ${err.code}, message: ${err.message}`); }); } catch (exception) { console.error(`Failed to set corner radius. Cause code: ${exception.code}, message: ${exception.message}`); } ``` ## setWindowSystemBarProperties(deprecated) setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 设置主窗口三键导航栏、状态栏的属性，使用callback异步回调，该接口在2in1设备上调用不生效。 子窗口调用后不生效。 > **说明：** > > 从API version 9开始支持，从API version 12开始废弃，建议使用Promise方式的[setWindowSystemBarProperties()](#setwindowsystembarproperties9)替代。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------- | ------------------------------------------- | ---- | ---------------------- | | systemBarProperties | [SystemBarProperties](arkts-apis-window-i.md#systembarproperties) | 是 | 三键导航栏、状态栏的属性。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------------------------------------------------------ | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 801 | Capability not supported. Failed to call the API due to limited device capabilities. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let SystemBarProperties: window.SystemBarProperties = { statusBarColor: '#ff00ff', navigationBarColor: '#00ff00', // 以下两个属性从API Version8开始支持 statusBarContentColor: '#ffffff', navigationBarContentColor: '#00ffff' }; try { windowClass.setWindowSystemBarProperties(SystemBarProperties, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the system bar properties.'); }); } catch (exception) { console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## setWindowSystemBarEnable(deprecated) setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 设置主窗口状态栏、三键导航栏的可见模式，状态栏通过status控制、三键导航栏通过navigation控制，使用callback异步回调。
从API version 12开始，该接口在2in1设备上调用不生效。 调用生效后返回并不表示状态栏、三键导航栏的显示或隐藏已完成。子窗口调用后不生效。非全屏模式（悬浮窗、分屏等场景）下配置不生效。 > **说明：** > > 从API version 9开始支持，从API version 12开始废弃，建议使用Promise方式的[setWindowSystemBarEnable()](#setwindowsystembarenable9)替代。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------- | | names | Array<'status'\|'navigation'> | 是 | 设置窗口全屏模式时状态栏和三键导航栏是否显示。
例如，需全部显示，该参数设置为['status', 'navigation']；设置为[]，则不显示。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------------------------------------------------------ | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // 此处以状态栏等均不显示为例 // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let names: Array<'status' | 'navigation'> = []; try { windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the system bar to be invisible.'); }); } catch (exception) { console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## setWindowLayoutFullScreen(deprecated) setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 设置主窗口或子窗口的布局是否为沉浸式布局，使用callback异步回调。系统窗口调用不生效。 沉浸式布局生效时，布局不避让状态栏与三键导航栏，组件可能产生与其重叠的情况。 非沉浸式布局生效时，布局避让状态栏与三键导航栏，组件不会与其重叠。 > **说明：** > > 从API version 9开始支持，从API version 12开始废弃，建议使用Promise方式的[setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9)替代。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **设备行为差异：** 在OpenHarmony 5.0.2之前，该接口在所有设备中可正常调用。 从OpenHarmony 5.0.2开始，该接口在支持并处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上调用不生效也不报错；在支持但不处于[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备及不支持[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态的设备上可正常调用。 **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------------ | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------- | | isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局（该沉浸式布局状态栏、三键导航栏仍然显示）。true表示沉浸式布局；false表示非沉浸式布局。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------------------------------------------------------ | | 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | | 1300002 | This window state is abnormal. | | 1300003 | This window manager service works abnormally. | **示例：** ```ts // EntryAbility.ets import { UIAbility } from '@kit.AbilityKit'; import { BusinessError } from '@kit.BasicServicesKit'; import { window } from '@kit.ArkUI'; export default class EntryAbility extends UIAbility { // ... onWindowStageCreate(windowStage: window.WindowStage): void { console.info('onWindowStageCreate'); let windowClass: window.Window | undefined = undefined; windowStage.getMainWindow((err: BusinessError, data) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); return; } windowClass = data; let isLayoutFullScreen = true; try { windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in setting the window layout to full-screen mode.'); }); } catch (exception) { console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); } }); } } ``` ## loadContent(deprecated) loadContent(path: string, callback: AsyncCallback<void>): void 为当前窗口加载具体页面内容，使用callback异步回调。 建议在UIAbility启动过程中使用该接口，多次调用该接口会先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。 当前UI的执行上下文可能不明确，所以不建议在本接口的回调函数中做UI相关的操作。 > **说明：** > > 从API version 7开始支持，从API version 9开始废弃，建议使用[setUIContent()](#setuicontent9)替代。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | -------------------- | | path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。不支持相对路径写法，需与main_pages.json或config.json中的src取值保持一致。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; windowClass.loadContent('pages/page2/page3', (err: BusinessError) => { const errCode: number = err.code; if (errCode) { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); return; } console.info('Succeeded in loading the content.'); }); ``` ## loadContent(deprecated) loadContent(path: string): Promise<void> 为当前窗口加载具体页面内容，使用Promise异步回调。 建议在UIAbility启动过程中使用该接口，多次调用该接口会先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。 当前UI的执行上下文可能不明确，所以不建议在本接口的回调函数中做UI相关的操作。 > **说明：** > > 从API version 7开始支持，从API version 9开始废弃，建议使用[setUIContent()](#setuicontent9-1)替代。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | -------------------- | | path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。不支持相对路径写法，需与main_pages.json或config.json中的src取值保持一致。| **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **示例：** ```ts import { BusinessError } from '@kit.BasicServicesKit'; let promise = windowClass.loadContent('pages/page2/page3'); promise.then(() => { console.info('Succeeded in loading the content.'); }).catch((err: BusinessError) => { console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); }); ```