目录

@ohos.window (窗口)

窗口提供管理窗口的一些基础能力,包括对当前窗口的创建、销毁、各属性设置,以及对各窗口间的管理调度。

该模块提供以下窗口相关的常用功能:

本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

import { window } from '@kit.ArkUI';

WindowType7+

窗口类型枚举。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称 值 说明
TYPE_APP 0

表示应用子窗口。

模型约束: 此接口仅可在FA模型下使用。

TYPE_SYSTEM_ALERT 1

表示系统告警窗口。

- 说明: 从API version 11开始废弃。

- 从 API version 7开始支持。

TYPE_FLOAT9+ 8

表示悬浮窗。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

TYPE_DIALOG10+ 16

表示模态窗口。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

Configuration9+

创建子窗口或系统窗口时的参数。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称 类型 必填 说明
name string 是 窗口名字。
windowType WindowType 是 窗口类型。
ctx BaseContext 否

当前应用上下文信息。不设置,则默认为空。

FA模型下不需要使用该参数,即可创建子窗口,使用该参数时会报错。

Stage模型必须使用该参数,用于创建悬浮窗、模态窗或系统窗口。

displayId number 否 当前物理屏幕id。不设置,则默认为-1,该参数应为整数。
parentId number 否 父窗口id。不设置,则默认为-1,该参数应为整数。
decorEnabled12+ boolean 否

是否显示窗口装饰,仅在windowType为TYPE_DIALOG时生效。true表示显示,false表示不显示。此参数默认值为false。

系统能力: SystemCapability.Window.SessionManager

title12+ string 否

decorEnabled属性设置为true时,窗口的标题内容。标题显示区域最右端不超过系统三键区域最左端,超过部分以省略号表示。不设置,则默认为空字符串。

系统能力: SystemCapability.Window.SessionManager

AvoidAreaType7+

窗口内容需要规避区域的类型枚举。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

名称 值 说明
TYPE_SYSTEM 0 表示系统默认区域。一般包括状态栏、导航栏,各设备系统定义可能不同。
TYPE_CUTOUT 1 表示刘海屏区域。
TYPE_SYSTEM_GESTURE9+ 2 表示手势区域。
TYPE_KEYBOARD9+ 3 表示软键盘区域。
TYPE_NAVIGATION_INDICATOR11+ 4 表示导航条区域。

SystemBarProperties

状态栏、导航栏的属性。在设置窗口级状态栏、导航栏属性时使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

名称 类型 必填 说明
statusBarColor string 否

状态栏背景颜色,为十六进制RGB或ARGB颜色,不区分大小写,例如'#00FF00'或'#FF00FF00'。默认值:'#66000000'。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

isStatusBarLightIcon7+ boolean 否

状态栏图标是否为高亮状态。true表示高亮;false表示不高亮。默认值:false。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

statusBarContentColor8+ string 否

状态栏文字颜色。当设置此属性后, isStatusBarLightIcon属性设置无效。默认值:'#E5FFFFFF'。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

navigationBarColor string 否

导航栏背景颜色,为十六进制RGB或ARGB颜色,不区分大小写,例如'#00FF00'或'#FF00FF00'。默认值:'#66000000'。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

isNavigationBarLightIcon7+ boolean 否

导航栏图标是否为高亮状态。true表示高亮;false表示不高亮。默认值:false。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

navigationBarContentColor8+ string 否

导航栏文字颜色。当设置此属性后, isNavigationBarLightIcon属性设置无效。默认值:'#E5FFFFFF'。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

enableStatusBarAnimation12+ boolean 否

是否使能状态栏属性变化时动画效果。true表示变化时使能动画效果;false表示没有使能动画效果。默认值:false。

系统能力: SystemCapability.Window.SessionManager。

enableNavigationBarAnimation12+ boolean 否

是否使能导航栏属性变化时动画效果。true表示变化时使能动画效果;false表示没有使能动画效果。默认值:false。

系统能力: SystemCapability.Window.SessionManager。

SystemBarStyle12+

状态栏的属性。在设置页面级状态栏属性时使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称 类型 只读 可选 说明
statusBarContentColor string 是 是 状态栏文字颜色。默认值:'#E5FFFFFF'。

Orientation9+

窗口显示方向类型枚举。

名称 值 说明
UNSPECIFIED 0

表示未定义方向模式,由系统判定。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

PORTRAIT 1

表示竖屏显示模式。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

LANDSCAPE 2

表示横屏显示模式。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

PORTRAIT_INVERTED 3

表示反向竖屏显示模式。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

LANDSCAPE_INVERTED 4

表示反向横屏显示模式。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

AUTO_ROTATION 5

跟随传感器自动旋转,可以旋转到竖屏、横屏、反向竖屏、反向横屏四个方向。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

AUTO_ROTATION_PORTRAIT 6

跟随传感器自动竖向旋转,可以旋转到竖屏、反向竖屏,无法旋转到横屏、反向横屏。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

AUTO_ROTATION_LANDSCAPE 7

跟随传感器自动横向旋转,可以旋转到横屏、反向横屏,无法旋转到竖屏、反向竖屏。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

AUTO_ROTATION_RESTRICTED 8

跟随传感器自动旋转,可以旋转到竖屏、横屏、反向竖屏、反向横屏四个方向,且受控制中心的旋转开关控制。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

AUTO_ROTATION_PORTRAIT_RESTRICTED 9

跟随传感器自动竖向旋转,可以旋转到竖屏、反向竖屏,无法旋转到横屏、反向横屏,且受控制中心的旋转开关控制。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

AUTO_ROTATION_LANDSCAPE_RESTRICTED 10

跟随传感器自动横向旋转,可以旋转到横屏、反向横屏,无法旋转到竖屏、反向竖屏,且受控制中心的旋转开关控制。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

LOCKED 11

表示锁定模式。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

AUTO_ROTATION_UNSPECIFIED12+ 12

跟随传感器自动旋转,受控制中心的旋转开关控制,且可旋转方向受系统判定(如在某种设备,可以旋转到竖屏、横屏、反向横屏三个方向,无法旋转到反向竖屏)。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager。

USER_ROTATION_PORTRAIT12+ 13

调用时临时旋转到竖屏,之后跟随传感器自动旋转,受控制中心的旋转开关控制,且可旋转方向受系统判定。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager。

USER_ROTATION_LANDSCAPE12+ 14

调用时临时旋转到横屏,之后跟随传感器自动旋转,受控制中心的旋转开关控制,且可旋转方向受系统判定。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager。

USER_ROTATION_PORTRAIT_INVERTED12+ 15

调用时临时旋转到反向竖屏,之后跟随传感器自动旋转,受控制中心的旋转开关控制,且可旋转方向受系统判定。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager。

USER_ROTATION_LANDSCAPE_INVERTED12+ 16

调用时临时旋转到反向横屏,之后跟随传感器自动旋转,受控制中心的旋转开关控制,且可旋转方向受系统判定。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager。

FOLLOW_DESKTOP12+ 17

表示跟随桌面的旋转模式。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager。

Rect7+

窗口矩形区域。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

名称 类型 可读 可写 说明
left number 是 是 矩形区域的左边界,单位为px,该参数为整数。
top number 是 是 矩形区域的上边界,单位为px,该参数应为整数。
width number 是 是 矩形区域的宽度,单位为px,该参数应为整数。
height number 是 是 矩形区域的高度,单位为px,该参数应为整数。

AvoidArea7+

窗口内容规避区域。如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。在规避区无法响应用户点击事件。

除此之外还需注意规避区域的如下约束,具体为:

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

名称 类型 可读 可写 说明
visible9+ boolean 是 是 规避区域是否可见。true表示可见;false表示不可见。
leftRect Rect 是 是 屏幕左侧的矩形区。
topRect Rect 是 是 屏幕顶部的矩形区。
rightRect Rect 是 是 屏幕右侧的矩形区。
bottomRect Rect 是 是 屏幕底部的矩形区。

Size7+

窗口大小。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

名称 类型 可读 可写 说明
width number 是 是 窗口宽度,单位为px,该参数应为整数。
height number 是 是 窗口高度,单位为px,该参数应为整数。

RectChangeReason12+

窗口矩形(窗口位置及窗口大小)变化的原因。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

名称 值 说明
UNDEFINED 0 默认值。
MAXIMIZE 1 窗口最大化。
RECOVER 2 窗口恢复到上一次的状态。
MOVE 3 窗口拖拽移动。
DRAG 4 窗口拖拽缩放。
DRAG_START 5 窗口开始拖拽缩放。
DRAG_END 6 窗口结束拖拽缩放。

RectChangeOptions12+

窗口矩形(窗口位置及窗口大小)变化返回的值及变化原因。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

名称 类型 可读 可写 说明
rect Rect 是 是 窗口矩形变化后的值。
reason RectChangeReason 是 是 窗口矩形变化的原因。

AvoidAreaOptions12+

系统规避区变化后返回当前规避区域以及规避区域类型。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

名称 类型 可读 可写 说明
type AvoidAreaType 是 是 系统规避区变化后返回的规避区域类型。
area AvoidArea 是 是 系统规避区变化后返回的规避区域。

WindowProperties

窗口属性。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称 类型 只读 可选 说明
windowRect7+ Rect 否 否

窗口尺寸,可在页面生命周期onPageShow或应用生命周期onForeground阶段获取。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

drawableRect11+ Rect 否 否

窗口内可绘制区域尺寸,其中左边界上边界是相对窗口计算。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

type7+ WindowType 否 否

窗口类型。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

isFullScreen boolean 否 否

是否全屏,默认为false。true表示全屏;false表示非全屏。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

isLayoutFullScreen7+ boolean 否 否

窗口是否为沉浸式,默认为false。true表示沉浸式;false表示非沉浸式。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

focusable7+ boolean 是 否

窗口是否可聚焦,默认为true。true表示可聚焦;false表示不可聚焦。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

touchable7+ boolean 是 否

窗口是否可触摸,默认为true。true表示可触摸;false表示不可触摸。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

brightness number 否 否

屏幕亮度。该参数为浮点数,可设置的亮度范围为[0.0, 1.0],其取1.0时表示最大亮度值。如果窗口没有设置亮度值,表示亮度跟随系统,此时获取到的亮度值为-1。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

dimBehindValue(deprecated) number 否 否

靠后窗口的暗度值。该参数为浮点数,取值范围为[0.0, 1.0],其取1.0表示最暗。

- 说明: 从API version 9开始废弃。

- 从 API version 7开始支持。

isKeepScreenOn boolean 否 否

屏幕是否常亮,默认为false。true表示常亮;false表示不常亮。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

isPrivacyMode7+ boolean 否 否

隐私模式,默认为false。true表示模式开启;false表示模式关闭。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

isRoundCorner(deprecated) boolean 否 否

窗口是否为圆角。默认为false。true表示圆角;false表示非圆角。

- 说明: 从API version 9开始废弃。

- 从 API version 7开始支持。

isTransparent7+ boolean 否 否

窗口是否透明。默认为false。true表示透明;false表示不透明。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

id9+ number 是 否

窗口ID,默认值为0,该参数应为整数。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

displayId12+ number 是 是

窗口所在屏幕ID,默认返回主屏幕ID,该参数应为整数。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

ColorSpace8+

色域模式。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

名称 值 说明
DEFAULT 0 默认SRGB色域模式。
WIDE_GAMUT 1 广色域模式。

WindowEventType10+

窗口生命周期。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

名称 值 说明
WINDOW_SHOWN 1

切到前台。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

WINDOW_ACTIVE 2

获焦状态。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

WINDOW_INACTIVE 3

失焦状态。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

WINDOW_HIDDEN 4

切到后台。

系统能力: SystemCapability.WindowManager.WindowManager.Core。

WINDOW_DESTROYED11+ 7

窗口销毁。

系统能力: SystemCapability.Window.SessionManager。

WindowLimits11+

窗口尺寸限制参数。可以通过setWindowLimits设置窗口尺寸限制,并且可以通过getWindowLimits获得当前的窗口尺寸限制。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

名称 类型 可读 可写 说明
maxWidth number 是 是 窗口的最大宽度。单位为px,该参数为整数。值默认为0,表示该属性不发生变化。下限值为0,上限值为系统限定的最大宽度。
maxHeight number 是 是 窗口的最大高度。单位为px,该参数为整数。值默认为0,表示该属性不发生变化。下限值为0,上限值为系统限定的最大高度。
minWidth number 是 是 窗口的最小宽度。单位为px,该参数为整数。值默认为0,表示该属性不发生变化。下限值为0,上限值为系统限定的最小宽度。
minHeight number 是 是 窗口的最小高度。单位为px,该参数为整数。值默认为0,表示该属性不发生变化。下限值为0,上限值为系统限定的最小高度。

WindowStatusType11+

窗口模式枚举。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

名称 值 说明
UNDEFINED 0 表示APP未定义窗口模式。
FULL_SCREEN 1 表示APP全屏模式。
MAXIMIZE 2 表示APP窗口最大化模式。
MINIMIZE 3 表示APP窗口最小化模式。
FLOATING 4 表示APP自由悬浮形式窗口模式。
SPLIT_SCREEN 5 表示APP分屏模式。

TitleButtonRect11+

标题栏上的最小化、最大化、关闭按钮矩形区域,该区域位置坐标相对窗口右上角。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

名称 类型 可读 可写 说明
right number 是 是 矩形区域的右边界,单位为vp,该参数为整数。
top number 是 是 矩形区域的上边界,单位为vp,该参数为整数。
width number 是 是 矩形区域的宽度,单位为vp,该参数为整数。
height number 是 是 矩形区域的高度,单位为vp,该参数为整数。

MaximizePresentation12+

窗口最大化时的布局枚举。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

名称 值 说明
FOLLOW_APP_IMMERSIVE_SETTING 0 最大化时,跟随应用app当前设置的沉浸式布局。
EXIT_IMMERSIVE 1 最大化时,如果当前窗口设置了沉浸式布局会退出沉浸式布局。
ENTER_IMMERSIVE 2 最大化时,进入沉浸式布局。

window.createWindow9+

createWindow(config: Configuration, callback: AsyncCallback<Window>): void

创建子窗口或者系统窗口,使用callback异步回调。

需要权限: 当创建窗口类型为window.WindowType.TYPE_FLOAT时,需要ohos.permission.SYSTEM_FLOAT_WINDOW权限

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
config Configuration 是 创建窗口时的参数。
callback AsyncCallback<Window> 是 回调函数。返回当前创建的窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
201 Permission verification failed. The application does not have the permission required to call the API.
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.
1300001 Repeated operation.
1300002 This window state is abnormal.
1300004 Unauthorized operation.
1300006 This window context is abnormal.
1300008 The display device is abnormal.
1300009 The parent window is invalid.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
let config: window.Configuration = {
  name: "test",
  windowType: window.WindowType.TYPE_DIALOG,
  ctx: this.context
};
try {
  window.createWindow(config, (err: BusinessError, data) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    windowClass = data;
    console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data));
    windowClass.resize(500, 1000);
  });
} catch (exception) {
  console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.createWindow9+

createWindow(config: Configuration): Promise<Window>

创建子窗口或者系统窗口,使用Promise异步回调。

需要权限: 当创建窗口类型为window.WindowType.TYPE_FLOAT时,需要ohos.permission.SYSTEM_FLOAT_WINDOW权限

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
config Configuration 是 创建窗口时的参数。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前创建的窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
201 Permission verification failed. The application does not have the permission required to call the API.
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.
1300001 Repeated operation.
1300002 This window state is abnormal.
1300004 Unauthorized operation.
1300006 This window context is abnormal.
1300008 The display device is abnormal.
1300009 The parent window is invalid.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
let config: window.Configuration = {
  name: "test",
  windowType: window.WindowType.TYPE_DIALOG,
  ctx: this.context
};
try {
  let promise = window.createWindow(config);
  promise.then((data) => {
    windowClass = data;
    console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.findWindow9+

findWindow(name: string): Window

查找name所对应的窗口。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 窗口名字,即Configuration中的name。

返回值:

类型 说明
Window 当前查找的窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.

示例:

let windowClass: window.Window | undefined = undefined;
try {
  windowClass = window.findWindow('test');
} catch (exception) {
  console.error(`Failed to find the Window. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.getLastWindow9+

getLastWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void

获取当前应用内最上层的子窗口,若无应用子窗口,则返回应用主窗口,使用callback异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ctx BaseContext 是 当前应用上下文信息。
callback AsyncCallback<Window> 是 回调函数。返回当前应用内最后显示的窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.
1300006 This window context is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    try {
      window.getLastWindow(this.context, (err: BusinessError, data) => {
        const errCode: number = err.code;
        if (errCode) {
          console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        windowClass = data;
        console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
      });
    } catch (exception) {
      console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

window.getLastWindow9+

getLastWindow(ctx: BaseContext): Promise<Window>

获取当前应用内最上层的子窗口,若无应用子窗口,则返回应用主窗口,使用Promise异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ctx BaseContext 是 当前应用上下文信息。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前应用内最后显示的窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.
1300006 This window context is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    try {
      let promise = window.getLastWindow(this.context);
      promise.then((data) => {
        windowClass = data;
        console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
      }).catch((err: BusinessError) => {
        console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

window.shiftAppWindowFocus11+

shiftAppWindowFocus(sourceWindowId: number, targetWindowId: number): Promise<void>

在同应用内将窗口焦点从源窗口转移到目标窗口,仅支持应用主窗和子窗的焦点转移。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
sourceWindowId number 是 源窗口id,必须是获焦状态。
targetWindowId number 是 目标窗口id。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // ...
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    let subWindowClass: window.Window | undefined = undefined;
    let windowClassId: number = -1;
    let subWindowClassId: number = -1;

    try {
      // 获取应用主窗及ID
      let promise = windowStage.getMainWindow();
      promise.then((data) => {
        if (data == null) {
          console.error("Failed to obtaining the window. Cause: The data is empty");
          return;
        }
        windowClass = data;
        windowClass.setUIContent("pages/Index");
        windowClassId = windowClass.getWindowProperties().id;
        console.info('Succeeded in obtaining the window')
      }).catch((err: BusinessError) => {
        console.error(`Failed to obtaining the window. Cause code: ${err.code}, message: ${err.message}`);
      });

      // 创建或获取子窗及ID,此时子窗口获焦
      let promiseSub = windowStage.createSubWindow("testSubWindow");
      promiseSub.then((data) => {
        if (data == null) {
          console.error("Failed to obtaining the window. Cause: The data is empty");
          return;
        }
        subWindowClass = data;
        subWindowClassId = subWindowClass.getWindowProperties().id;
        subWindowClass.resize(500, 500);
        subWindowClass.setUIContent("pages/Index2");
        subWindowClass.showWindow();

        // 监听Window状态,确保已经就绪
        subWindowClass.on("windowEvent", (windowEvent) => {
          if (windowEvent == window.WindowEventType.WINDOW_ACTIVE) {
            // 切换焦点
            let promise = window.shiftAppWindowFocus(subWindowClassId, windowClassId);
            promise.then(() => {
              console.info('Succeeded in shifting app window focus');
            }).catch((err: BusinessError) => {
              console.error(`Failed to shift app window focus. Cause code: ${err.code}, message: ${err.message}`);
            });
          }
        });
      });
    } catch (exception) {
      console.error(`Failed to shift app focus. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

window.create(deprecated)

create(id: string, type: WindowType, callback: AsyncCallback<Window>): void

创建子窗口,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用createWindow()。

模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
id string 是 窗口名字,即Configuration中的name。
type WindowType 是 窗口类型。
callback AsyncCallback<Window> 是 回调函数。返回当前创建的子窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
window.create('test', window.WindowType.TYPE_APP, (err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  windowClass = data;
  console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data));
});

window.create(deprecated)

create(id: string, type: WindowType): Promise<Window>

创建子窗口,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用createWindow()。

模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
id string 是 窗口名字,即Configuration中的name。
type WindowType 是 窗口类型。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前创建的子窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
let promise = window.create('test', window.WindowType.TYPE_APP);
promise.then((data) => {
  windowClass = data;
  console.info('Succeeded in creating the subWindow. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to create the subWindow. Cause code: ${err.code}, message: ${err.message}`);
});

window.create(deprecated)

create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void

创建系统窗口,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用createWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ctx BaseContext 是 当前应用上下文信息。
id string 是 窗口名字,即Configuration中的name。
type WindowType 是 窗口类型。
callback AsyncCallback<Window> 是 回调函数。返回当前创建的子窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
window.create('test', window.WindowType.TYPE_SYSTEM_ALERT, (err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  windowClass = data;
  console.info('Succeeded in creating the window. Data: ' + JSON.stringify(data));
  windowClass.resetSize(500, 1000);
});

window.create(deprecated)

create(ctx: BaseContext, id: string, type: WindowType): Promise<Window>

创建系统窗口,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用createWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ctx BaseContext 是 当前应用上下文信息。
id string 是 窗口名字,即Configuration中的name。
type WindowType 是 窗口类型。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前创建的子窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
let promise = window.create('test', window.WindowType.TYPE_SYSTEM_ALERT);
promise.then((data) => {
  windowClass = data;
  console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`);
});

window.find(deprecated)

find(id: string, callback: AsyncCallback<Window>): void

查找id所对应的窗口,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用findWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
id string 是 窗口名字,即Configuration中的name。
callback AsyncCallback<Window> 是 回调函数。返回当前查找到的窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
window.find('test', (err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  windowClass = data;
  console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data));
});

window.find(deprecated)

find(id: string): Promise<Window>

查找id所对应的窗口,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用findWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
id string 是 窗口名字,即Configuration中的name。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前查找的窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
let promise = window.find('test');
promise.then((data) => {
  windowClass = data;
  console.info('Succeeded in finding the window. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to find the Window. Cause code: ${err.code}, message: ${err.message}`);
});

window.getTopWindow(deprecated)

getTopWindow(callback: AsyncCallback<Window>): void

获取当前应用内最后显示的窗口,使用callback异步回调。

从 API version 6开始支持,从API version 9开始废弃,推荐使用getLastWindow()。

模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<Window> 是 回调函数。返回当前应用内最后显示的窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
window.getTopWindow((err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  windowClass = data;
  console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
});

window.getTopWindow(deprecated)

getTopWindow(): Promise<Window>

获取当前应用内最后显示的窗口,使用Promise异步回调。

从 API version 6开始支持,从API version 9开始废弃,推荐使用getLastWindow()。

模型约束: 此接口仅可在FA模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<Window> Promise对象。返回当前应用内最后显示的窗口对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let windowClass: window.Window | undefined = undefined;
let promise = window.getTopWindow();
promise.then((data)=> {
    windowClass = data;
    console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError)=>{
    console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
});

window.getTopWindow(deprecated)

getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void

获取当前应用内最后显示的窗口,使用callback异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用getLastWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ctx BaseContext 是 当前应用上下文信息。
callback AsyncCallback<Window> 是 回调函数。返回当前应用内最后显示的窗口对象。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage:window.WindowStage){
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    try {
      window.getTopWindow(this.context, (err: BusinessError, data) => {
        const errCode: number = err.code;
        if(errCode){
          console.error(`Failed to obtain the top window. Cause code: ${err.code}, message: ${err.message}`);
          return ;
        }
        windowClass = data;
        console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
      });
    } catch(error){
      console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`);
    }
  }
}

window.getTopWindow(deprecated)

getTopWindow(ctx: BaseContext): Promise<Window>

获取当前应用内最后显示的窗口,使用Promise异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用getLastWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ctx BaseContext 是 当前应用上下文信息。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前应用内最后显示的窗口对象。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage:window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    let promise = window.getTopWindow(this.context);
    promise.then((data) => {
      windowClass = data;
      console.info('Succeeded in obtaining the top window. Data: ' + JSON.stringify(data));
    }).catch((error: BusinessError) => {
      console.error(`Failed to obtain the top window. Cause code: ${error.code}, message: ${error.message}`);
    });
  }
}

SpecificSystemBar11+

type SpecificSystemBar = 'status' | 'navigation' | 'navigationIndicator'

当前支持显示或隐藏的系统栏类型。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 11开始,该接口支持在元服务中使用。

类型 说明
'status' 状态栏。
'navigation' 三键导航栏。
'navigationIndicator' 底部导航条。

Window

当前窗口实例,窗口管理器管理的基本单元。

下列API示例中都需先使用getLastWindow()、createWindow()、findWindow()中的任一方法获取到Window实例(windowClass),再通过此实例调用对应方法。

[h2]showWindow9+

showWindow(callback: AsyncCallback<void>): void

显示当前窗口,使用callback异步回调,仅支持系统窗口及应用子窗口,或将已显示的应用主窗口的层级提升至顶部。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.showWindow((err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in showing the window.');
});

[h2]showWindow9+

showWindow(): Promise<void>

显示当前窗口,使用Promise异步回调,仅支持系统窗口及应用子窗口,或将已显示的应用主窗口的层级提升至顶部。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.showWindow();
promise.then(() => {
  console.info('Succeeded in showing the window.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]destroyWindow9+

destroyWindow(callback: AsyncCallback<void>): void

销毁当前窗口,使用callback异步回调,仅支持系统窗口及应用子窗口。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例:

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.');
});

[h2]destroyWindow9+

destroyWindow(): Promise<void>

销毁当前窗口,使用Promise异步回调,仅支持系统窗口及应用子窗口。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例:

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}`);
});

[h2]moveWindowTo9+

moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void

移动窗口位置,使用callback异步回调。

在2in1设备上所有窗口模式都能生效,其他设备仅在除智慧多窗外的自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)下生效。

在2in1设备上窗口相对于屏幕移动,其他设备上窗口相对于父窗口移动。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
x number 是 窗口在x轴方向移动到的坐标位置,单位为px,值为正表示位置在x轴右侧;值为负表示位置在x轴左侧;值为0表示位置在x轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。
y number 是 窗口在y轴方向移动到的坐标位置,单位为px,值为正表示位置在y轴下侧;值为负表示位置在y轴上侧;值为0表示位置在y轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]moveWindowTo9+

moveWindowTo(x: number, y: number): Promise<void>

移动窗口位置,使用Promise异步回调。调用成功即返回,该接口返回后无法立即获取最终生效结果,如需立即获取,建议使用接口moveWindowToAsync()。

在2in1设备上所有窗口模式都能生效,其他设备仅在除智慧多窗外的自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)下生效。

在2in1设备上窗口相对于屏幕移动,其他设备上窗口相对于父窗口移动。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
x number 是 窗口在x轴方向移动到的坐标位置,单位为px,值为正表示位置在x轴右侧;值为负表示位置在x轴左侧;值为0表示位置在x轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。
y number 是 窗口在y轴方向移动到的坐标位置,单位为px,值为正表示位置在y轴下侧;值为负表示位置在y轴上侧;值为0表示位置在y轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]moveWindowToAsync12+

moveWindowToAsync(x: number, y: number): Promise<void>

移动窗口位置,使用Promise异步回调。调用生效后返回,回调中可使用getWindowProperties(见示例)立即获取最终生效结果。

仅在自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)下生效。

在2in1设备上窗口相对于屏幕移动,其他设备上窗口相对于父窗口移动。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
x number 是 窗口在x轴方向移动到的坐标位置,单位为px,值为正表示位置在x轴右侧;值为负表示位置在x轴左侧;值为0表示位置在x轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。
y number 是 窗口在y轴方向移动到的坐标位置,单位为px,值为正表示位置在y轴下侧;值为负表示位置在y轴上侧;值为0表示位置在y轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.
1300010 The operation is not supported in full-screen mode.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let promise = windowClass.moveWindowToAsync(300, 300);
  promise.then(() => {
    console.info('Succeeded in moving the window.');
    let rect = windowClass?.getWindowProperties().windowRect;
    console.info(`Get window rect: ` + JSON.stringify(rect));
  }).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}`);
}

[h2]resize9+

resize(width: number, height: number, callback: AsyncCallback<void>): void

改变当前窗口大小,使用callback异步回调。

应用主窗口与子窗口存在大小限制,默认宽度范围:[320, 1920],默认高度范围:[240, 1920],单位为vp。

应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置,配置后的最小宽度与最小高度以产品段配置值为准,具体尺寸限制范围可以通过getWindowLimits接口进行查询。

系统窗口存在大小限制,宽度范围:(0, 1920],高度范围:(0, 1920],单位为vp。

设置的宽度与高度受到此约束限制,规则:

若所设置的窗口宽/高尺寸小于窗口最小宽/高限值,则窗口最小宽/高限值生效;

若所设置的窗口宽/高尺寸大于窗口最大宽/高限值,则窗口最大宽/高限值生效。

全屏模式窗口不支持该操作。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
width number 是 目标窗口的宽度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。
height number 是 目标窗口的高度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300003 This window manager service works abnormally.

示例:

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}`);
}

[h2]resize9+

resize(width: number, height: number): Promise<void>

改变当前窗口大小,使用Promise异步回调。调用成功即返回,该接口返回后无法立即获取最终生效结果,如需立即获取,建议使用接口resizeAsync()。

应用主窗口与子窗口存在大小限制,默认宽度范围:[320, 1920],默认高度范围:[240, 1920],单位为vp。

应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置,配置后的最小宽度与最小高度以产品段配置值为准,具体尺寸限制范围可以通过getWindowLimits接口进行查询。

系统窗口存在大小限制,宽度范围:(0, 1920],高度范围:(0, 1920],单位为vp。

设置的宽度与高度受到此约束限制,规则:

若所设置的窗口宽/高尺寸小于窗口最小宽/高限值,则窗口最小宽/高限值生效;

若所设置的窗口宽/高尺寸大于窗口最大宽/高限值,则窗口最大宽/高限值生效。

全屏模式窗口不支持该操作。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
width number 是 目标窗口的宽度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。
height number 是 目标窗口的高度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300003 This window manager service works abnormally.

示例:

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}`);
}

[h2]resizeAsync12+

resizeAsync(width: number, height: number): Promise<void>

改变当前窗口大小,使用Promise异步回调。调用生效后返回,回调中可使用getWindowProperties(见示例)立即获取最终生效结果。

应用主窗口与子窗口存在大小限制,默认宽度范围:[320, 1920],默认高度范围:[240, 1920],单位为vp。

应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置,配置后的最小宽度与最小高度以产品段配置值为准,具体尺寸限制范围可以通过getWindowLimits接口进行查询。

系统窗口存在大小限制,宽度范围:(0, 1920],高度范围:(0, 1920],单位为vp。

设置的宽度与高度受到此约束限制,规则:

若所设置的窗口宽/高尺寸小于窗口最小宽/高限值,则窗口最小宽/高限值生效;

若所设置的窗口宽/高尺寸大于窗口最大宽/高限值,则窗口最大宽/高限值生效。

全屏模式窗口不支持该操作。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
width number 是 目标窗口的宽度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。
height number 是 目标窗口的高度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.
1300010 The operation is not supported in full-screen mode.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let promise = windowClass.resizeAsync(500, 1000);
  promise.then(() => {
    console.info('Succeeded in changing the window size.');
    let rect = windowClass?.getWindowProperties().windowRect;
    console.info(`Get window rect: ` + JSON.stringify(rect));
  }).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}`);
}

[h2]getWindowProperties9+

getWindowProperties(): WindowProperties

获取当前窗口的属性,返回WindowProperties。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
WindowProperties 当前窗口属性。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

try {
  let properties = windowClass.getWindowProperties();
} catch (exception) {
  console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]getWindowAvoidArea9+

getWindowAvoidArea(type: AvoidAreaType): AvoidArea

获取当前应用窗口内容规避的区域。如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。

该接口一般适用于两种场景:1、在onWindowStageCreate方法中,获取应用启动时的初始布局避让区域时可调用该接口;2、当应用内子窗需要临时显示,对显示内容做布局避让时可调用该接口。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type AvoidAreaType 是 表示规避区类型。

返回值:

类型 说明
AvoidArea 窗口内容规避区域。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]setWindowLayoutFullScreen9+

setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>

设置主窗口或子窗口的布局是否为沉浸式布局,使用Promise异步回调。

沉浸式布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。

非沉浸式布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
isLayoutFullScreen boolean 是 窗口的布局是否为沉浸式布局(该沉浸式布局状态栏、导航栏仍然显示)。true表示沉浸式布局;false表示非沉浸式布局。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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}`);
      }
    });
  }
}

[h2]setImmersiveModeEnabledState12+

setImmersiveModeEnabledState(enabled: boolean): void

设置当前窗口是否开启沉浸式布局,该调用不会改变窗口模式和窗口大小。

系统能力:SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
enabled boolean 是

是否开启沉浸式布局。

true表示开启,false表示关闭。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

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}`);
}

[h2]getImmersiveModeEnabledState12+

getImmersiveModeEnabledState(): boolean

查询当前窗口是否已经开启沉浸式布局。

系统能力:SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

返回值:

类型 说明
boolean

是否已经开启沉浸式布局。

true表示开启,false表示关闭。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation.

示例:

try {
  let isEnabled = windowClass.getImmersiveModeEnabledState();
} catch (exception) {
  console.error(`Failed to get the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]setWindowSystemBarEnable9+

setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void>

设置主窗口三键导航栏、状态栏、底部导航条的可见模式,状态栏与底部导航条通过status控制、三键导航栏通过navigation控制,使用Promise异步回调。从API version 12开始,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

调用生效后返回并不表示三键导航栏、状态栏和底部导航条的显示或隐藏已完成。子窗口调用后不生效。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
names Array<'status'|'navigation'> 是

设置窗口全屏模式时状态栏、三键导航栏和底部导航条是否显示。

例如,需全部显示,该参数设置为['status', 'navigation'];不设置,则默认不显示。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// 此处以不显示三键导航栏、状态栏、底部导航条为例
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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}`);
      }
    });
  }
}

[h2]setSpecificSystemBarEnabled11+

setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void>

设置主窗口三键导航栏、状态栏、底部导航条的显示和隐藏,使用Promise异步回调。从API version 12开始,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

调用生效后返回并不表示三键导航栏、状态栏和底部导航条的显示或隐藏已完成。子窗口调用后不生效。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name SpecificSystemBar 是 设置窗口全屏模式时,显示或隐藏的系统栏类型。
enable boolean 是 设置窗口全屏模式时状态栏、三键导航栏或底部导航条是否显示,true表示显示, false表示隐藏。
enableAnimation12+ boolean 否 设置状态栏、三键导航栏或底部导航条显示状态变化时是否使用动画,true表示使用, false表示不使用,默认值为false。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// 此处以隐藏底部导航条为例
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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('navigationIndicator', 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}`);
      }
    });
  }
}

[h2]setWindowSystemBarProperties9+

setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void>

设置主窗口三键导航栏、状态栏的属性,使用Promise异步回调,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

子窗口调用后不生效。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
systemBarProperties SystemBarProperties 是 三键导航栏、状态栏的属性。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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}`);
      }
    });
  }
}

[h2]getWindowSystemBarProperties12+

getWindowSystemBarProperties(): SystemBarProperties

主窗口获取三键导航栏、状态栏的属性。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

返回值:

类型 说明
SystemBarProperties 当前三键导航栏、状态栏属性。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    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 systemBarProperty = windowClass.getWindowSystemBarProperties();
        console.info('Success in obtaining system bar properties. Property: ' + JSON.stringify(systemBarProperty));
      } catch (err) {
        console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`);
      }
    });
  }
};

[h2]setPreferredOrientation9+

setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void

设置主窗口的显示方向属性,使用callback异步回调。仅在支持跟随sensor旋转的设备上生效,2in1设备上调用不生效,自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不生效,子窗调用后不生效。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
orientation Orientation 是 窗口显示方向的属性。
callback AsyncCallback<void> 是 回调函数。该回调函数返回调用结果是否成功,非应用旋转动效结束。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 orientation = window.Orientation.AUTO_ROTATION;
      try {
        windowClass.setPreferredOrientation(orientation, (err: BusinessError) => {
          const errCode: number = err.code;
          if (errCode) {
            console.error(`Failed to set window orientation. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in setting window orientation.');
        });
      } catch (exception) {
        console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

[h2]setPreferredOrientation9+

setPreferredOrientation(orientation: Orientation): Promise<void>

设置主窗口的显示方向属性,使用Promise异步回调。仅在支持跟随sensor旋转的设备上生效,2in1设备上调用不生效,自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不生效,子窗调用后不生效。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
orientation Orientation 是 窗口显示方向的属性。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 orientation = window.Orientation.AUTO_ROTATION;
      try {
        let promise = windowClass.setPreferredOrientation(orientation);
        promise.then(() => {
          console.info('Succeeded in setting the window orientation.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to set the window orientation. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

[h2]getPreferredOrientation12+

getPreferredOrientation(): Orientation

主窗口调用,获取窗口的显示方向属性。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

返回值:

类型 说明
Orientation 窗口显示方向的属性。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
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;
      try {
        let orientation = windowClass.getPreferredOrientation();
      } catch (exception) {
        console.error(`Failed to get window orientation. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
};

[h2]getUIContext10+

getUIContext(): UIContext

获取UIContext实例。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
UIContext 返回UIContext实例对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { window, UIContext } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // 为主窗口加载对应的目标页面。
    windowStage.loadContent("pages/page2", (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 windowClass: window.Window | undefined = undefined;
      windowStage.getMainWindow((err: BusinessError, data) => {
        let errCode: number = err.code;
        if (errCode) {
          console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        windowClass = data;
        console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
        // 获取UIContext实例。
        let uiContext: UIContext | null = null;
        uiContext = windowClass.getUIContext();
      });
    });
  }
};

[h2]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文件中。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]setUIContent9+

setUIContent(path: string): Promise<void>

根据当前工程中某个页面的路径为窗口加载具体页面内容,使用Promise异步回调。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,Stage模型下该路径需添加到工程的main_pages.json文件中,FA模型下该路径需添加到工程的config.json文件中。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]loadContent9+

loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void

根据当前工程中某个页面的路径为窗口加载具体页面内容,通过LocalStorage传递状态属性给加载的页面,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,该路径需添加到工程的main_pages.json文件中。
storage LocalStorage 是 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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.');
});

[h2]loadContent9+

loadContent(path: string, storage: LocalStorage): Promise<void>

根据当前工程中某个页面的路径为窗口加载具体页面内容,通过LocalStorage传递状态属性给加载的页面,使用Promise异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,该路径需添加到工程的main_pages.json文件中。
storage LocalStorage 是 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
});

[h2]loadContentByName11+

loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void

为当前窗口加载命名路由页面,通过LocalStorage传递状态属性给加载的页面,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 命名路由页面的名称。
storage LocalStorage 是 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // 导入命名路由页面

console.info('onWindowStageCreate');
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
try {
  (windowClass as window.Window).loadContentByName(Index.entryName, 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.');
  });
} catch (exception) {
  console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

[h2]loadContentByName11+

loadContentByName(name: string, callback: AsyncCallback<void>): void

为当前窗口加载命名路由页面内容,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 命名路由页面的名称。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // 导入命名路由页面

try {
  (windowClass as window.Window).loadContentByName(Index.entryName, (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}`);
}
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName})
@Component
export struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

[h2]loadContentByName11+

loadContentByName(name: string, storage?: LocalStorage): Promise<void>

为当前窗口加载命名路由页面,通过LocalStorage传递状态属性给加载的页面,使用Promise异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 命名路由页面的名称。
storage LocalStorage 否 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // 导入命名路由页面

let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
try {
  let promise = (windowClass as window.Window).loadContentByName(Index.entryName, 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}`);
  });
} catch (exception) {
  console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
}
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

[h2]isWindowShowing9+

isWindowShowing(): boolean

判断当前窗口是否已显示。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
boolean 当前窗口是否已显示。true表示当前窗口已显示,false则表示当前窗口未显示。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

try {
  let data = windowClass.isWindowShowing();
  console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data));
} catch (exception) {
  console.error(`Failed to check whether the window is showing. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('windowSizeChange')7+

on(type: 'windowSizeChange', callback: Callback<Size>): void

开启窗口尺寸变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowSizeChange',即窗口尺寸变化事件。
callback Callback<Size> 是 回调函数。返回当前的窗口尺寸。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

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}`);
}

[h2]off('windowSizeChange')7+

off(type: 'windowSizeChange', callback?: Callback<Size>): void

关闭窗口尺寸变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowSizeChange',即窗口尺寸变化事件。
callback Callback<Size> 否 回调函数。返回当前的窗口尺寸。如果传入参数,则关闭该监听。如果未传入参数,则关闭窗口尺寸变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

示例:

const callback = (size: window.Size) => {
  // ...
}
try {
  // 通过on接口开启监听
  windowClass.on('windowSizeChange', callback);
  // 关闭指定callback的监听
  windowClass.off('windowSizeChange', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('windowSizeChange');
} catch (exception) {
  console.error(`Failed to disable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('avoidAreaChange')9+

on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void

开启当前应用窗口系统规避区变化的监听。

常见的触发避让区回调的场景如下:应用窗口在全屏模式、悬浮模式、分屏模式之间的切换;应用窗口旋转;多折叠设备在屏幕折叠态和展开态之间的切换;应用窗口在多设备之间的流转。实现沉浸式布局可参考开发应用沉浸式效果。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'avoidAreaChange',即系统规避区变化事件。
callback Callback<AvoidAreaOptions> 是 回调函数。返回当前规避区以及规避区类型。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

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}`);
}

[h2]off('avoidAreaChange')9+

off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaOptions>): void

关闭当前窗口系统规避区变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'avoidAreaChange',即系统规避区变化事件。
callback Callback<AvoidAreaOptions> 否 回调函数。返回当前规避区以及规避区类型。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有系统规避区变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.

示例:

interface Param {
  type: window.AvoidAreaType,
  area: window.AvoidArea
}
const callback = (data: Param) => {
  // ...
}
try {
  windowClass.on('avoidAreaChange', callback);

  windowClass.off('avoidAreaChange', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('avoidAreaChange');
} catch (exception) {
  console.error(`Failed to enable or disable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('keyboardHeightChange')7+

on(type: 'keyboardHeightChange', callback: Callback<number>): void

开启固定态软键盘高度变化的监听,当软键盘由本窗口唤出并存在重叠区域时通知键盘高度变化。从API version 10开始,改变软键盘为固定态或者悬浮态方法详细介绍请参见输入法服务。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'keyboardHeightChange',即键盘高度变化事件。
callback Callback<number> 是 回调函数。返回当前的键盘高度,返回值为整数,单位为px。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

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}`);
}

[h2]off('keyboardHeightChange')7+

off(type: 'keyboardHeightChange', callback?: Callback<number>): void

关闭固定态软键盘高度变化的监听。从API version 10开始,改变软键盘为固定态或者悬浮态方法详细介绍请参见输入法服务。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'keyboardHeightChange',即键盘高度变化事件。
callback Callback<number> 否 回调函数。返回当前的键盘高度,返回值为整数,单位为px。若传入参数,则关闭该监听。如果未传入参数,则关闭所有固定态软键盘高度变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

const callback = (height: number) => {
  // ...
}
try {
  windowClass.on('keyboardHeightChange', callback);

  windowClass.off('keyboardHeightChange', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('keyboardHeightChange');
} catch (exception) {
  console.error(`Failed to disable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('touchOutside')11+

on(type: 'touchOutside', callback: Callback<void>): void

开启本窗口区域范围外的点击事件的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'touchOutside',即本窗口范围外的点击事件。
callback Callback<void> 是 回调函数。当点击事件发生在本窗口范围之外的回调。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

try {
  windowClass.on('touchOutside', () => {
    console.info('touch outside');
  });
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]off('touchOutside')11+

off(type: 'touchOutside', callback?: Callback<void>): void

关闭本窗口区域范围外的点击事件的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'touchOutside',即本窗口范围外的点击事件。
callback Callback<void> 否 回调函数。当点击事件发生在本窗口范围之外的回调。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有本窗口区域范围外的点击事件的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

示例:

const callback = () => {
  // ...
}
try {
  windowClass.on('touchOutside', callback);
  windowClass.off('touchOutside', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('touchOutside');
} catch (exception) {
  console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('screenshot')9+

on(type: 'screenshot', callback: Callback<void>): void

开启截屏事件的监听。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'screenshot',即截屏事件,对控制中心截屏、hdc命令截屏、整屏截屏接口生效。
callback Callback<void> 是 回调函数。发生截屏事件时的回调。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

try {
  windowClass.on('screenshot', () => {
    console.info('screenshot happened');
  });
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]off('screenshot')9+

off(type: 'screenshot', callback?: Callback<void>): void

关闭截屏事件的监听。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'screenshot',即截屏事件。
callback Callback<void> 否 回调函数。发生截屏事件时的回调。若传入参数,则关闭该监听。若未传入参数,则关闭所有截屏事件的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

示例:

let callback = () => {
  console.info('screenshot happened');
};
try {
  windowClass.on('screenshot', callback);
  windowClass.off('screenshot', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('screenshot');
} catch (exception) {
  console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('dialogTargetTouch')10+

on(type: 'dialogTargetTouch', callback: Callback<void>): void

开启模态窗口所遮盖窗口的点击或触摸事件的监听,除模态窗口以外其他窗口调用此接口不生效。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'dialogTargetTouch',即模态窗口所遮盖窗口的点击或触摸事件。
callback Callback<void> 是 回调函数。当点击或触摸事件发生在模态窗口所遮盖窗口的回调。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

try {
  windowClass.on('dialogTargetTouch', () => {
    console.info('touch dialog target');
  });
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]off('dialogTargetTouch')10+

off(type: 'dialogTargetTouch', callback?: Callback<void>): void

关闭模态窗口目标窗口的点击事件的监听。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'dialogTargetTouch',即模态窗口目标窗口的点击事件。
callback Callback<void> 否 回调函数。当点击事件发生在模态窗口目标窗口的回调。若传入参数,则关闭该监听。若未传入参数,则关闭所有模态窗口目标窗口的点击事件的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

示例:

const callback = () => {
  // ...
}
try {
  windowClass.on('dialogTargetTouch', callback);
  windowClass.off('dialogTargetTouch', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('dialogTargetTouch');
} catch (exception) {
  console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('windowEvent')10+

on(type: 'windowEvent', callback: Callback<WindowEventType>): void

开启窗口生命周期变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowEvent',即窗口生命周期变化事件。
callback Callback<WindowEventType> 是 回调函数。返回当前的窗口生命周期状态。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例:

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}`);
}

[h2]off('windowEvent')10+

off(type: 'windowEvent', callback?: Callback<WindowEventType>): void

关闭窗口生命周期变化的监听。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowEvent',即窗口生命周期变化事件。
callback Callback<WindowEventType> 否 回调函数。返回当前的窗口生命周期状态。若传入参数,则关闭该监听。若未传入参数,则关闭所有窗口生命周期变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

示例:

const callback = (windowEventType: window.WindowEventType) => {
  // ...
}
try {
  // 通过on接口开启监听
  windowClass.on('windowEvent', callback);
  // 关闭指定callback的监听
  windowClass.off('windowEvent', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('windowEvent');
} catch (exception) {
  console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('windowVisibilityChange')11+

on(type: 'windowVisibilityChange', callback: Callback<boolean>): void

开启本窗口可见状态变化事件的监听。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowVisibilityChange',即本窗口可见状态变化的事件。
callback Callback<boolean> 是 回调函数。当本窗口可见状态发生变化后的回调。回调函数返回boolean类型参数,当返回参数为true时表示窗口可见,否则表示窗口不可见。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.

示例:

try {
  windowClass.on('windowVisibilityChange', (boolean) => {
    console.info('Window visibility changed, isVisible=' + boolean);
  });
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]off('windowVisibilityChange')11+

off(type: 'windowVisibilityChange', callback?: Callback<boolean>): void

关闭本窗口可见状态变化事件的监听。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowVisibilityChange',即本窗口可见状态变化的事件。
callback Callback<boolean> 否 回调函数。当本窗口可见状态发生变化时的回调。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有本窗口可见状态变化事件的回调。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
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.

示例:

const callback = (bool: boolean) => {
  // ...
}
try {
  // 通过on接口开启监听
  windowClass.on('windowVisibilityChange', callback);
  // 关闭指定callback的监听
  windowClass.off('windowVisibilityChange', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('windowVisibilityChange');
} catch (exception) {
  console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('noInteractionDetected')12+

on(type: 'noInteractionDetected', timeout: number, callback: Callback<void>): void

开启本窗口在指定超时时间内无交互事件的监听,交互事件支持物理键盘输入事件和屏幕触控点击事件,不支持软键盘输入事件。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'noInteractionDetected',即本窗口在指定超时时间内无交互的事件。
timeout number 是 指定本窗口在多长时间内无交互即回调,单位为秒(s)。该参数仅支持整数输入,负数和小数为非法参数。
callback Callback<void> 是 回调函数。当本窗口在指定超时时间内无交互事件时的回调。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.

示例:

try {
  windowClass.on('noInteractionDetected', 60, () => {
    console.info('no interaction in 60s');
  });
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]off('noInteractionDetected')12+

off(type: 'noInteractionDetected', callback?: Callback<void>): void

关闭本窗口在指定超时时间内无交互事件的监听,交互事件支持物理键盘输入事件和屏幕触控点击事件,不支持软键盘输入事件。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'noInteractionDetected',即本窗口在指定超时时间内无交互的事件。
callback Callback<void> 否 回调函数,当本窗口在指定超时时间内无交互事件时的回调。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有本窗口在指定超时时间内无交互事件的监听。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
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.

示例:

const callback = () => {
  // ...
}
try {
  windowClass.on('noInteractionDetected', 60, callback);
  windowClass.off('noInteractionDetected', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('noInteractionDetected');
} catch (exception) {
  console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]on('windowStatusChange')11+

on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void

开启窗口模式变化的监听,当窗口windowStatus发生变化时进行通知(此时窗口属性可能还没有更新)。

在2in1设备上调用本接口时,在窗口最大化状态时返回值对应为WindowStatusType::FULL_SCREEN。

若想在2in1设备上区分当前窗口状态为最大化还是全屏,可在窗口状态为WindowStatusType::FULL_SCREEN的情况下,再调用getImmersiveModeEnabledState() 接口进行进一步判断,到底是最大化状态还是全屏状态。若接口返回true则表示当前窗口为全屏状态,若接口返回false则表示当前窗口为最大化状态。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowStatusChange',即窗口模式变化事件。
callback Callback<WindowStatusType> 是 回调函数。返回当前的窗口模式。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.

示例:

try {
    windowClass.on('windowStatusChange', (WindowStatusType) => {
        console.info('Succeeded in enabling the listener for window status changes. Data: ' + JSON.stringify(WindowStatusType));
    });
} catch (exception) {
    console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]off('windowStatusChange')11+

off(type: 'windowStatusChange', callback?: Callback<WindowStatusType>): void

关闭窗口模式变化的监听。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowStatusChange',即窗口模式变化事件。
callback Callback<WindowStatusType> 否 回调函数。返回当前的窗口模式。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有窗口模式变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.

示例:

const callback = (windowStatusType: window.WindowStatusType) => {
    // ...
}
try {
    windowClass.on('windowStatusChange', callback);
    windowClass.off('windowStatusChange', callback);
    // 如果通过on开启多个callback进行监听,同时关闭所有监听:
    windowClass.off('windowStatusChange');
} catch (exception) {
    console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]setWindowGrayScale12+

setWindowGrayScale(grayScale: number): Promise<void>

设置窗口灰阶,使用Promise异步回调。该接口需要在调用loadContent()或setUIContent()使窗口加载页面内容后调用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
grayScale number 是 窗口灰阶。该参数为浮点数,取值范围为[0.0, 1.0]。0.0表示窗口图像无变化,1.0表示窗口图像完全转为灰度图像,0.0至1.0之间时效果呈线性变化。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass?.setUIContent('pages/Index', (error: BusinessError) => {
  if (error.code) {
    console.error(`Failed to set the content. Cause code: ${error.code}`);
    return;
  }
  console.info('Succeeded in setting the content.');
  let grayScale: number = 0.5;
  try {
    if (canIUse("SystemCapability.Window.SessionManager")) {
      let promise = windowClass?.setWindowGrayScale(grayScale);
      promise?.then(() => {
        console.info('Succeeded in setting the grayScale.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to set the grayScale. Cause code: ${err.code}, message: ${err.message}`);
      });
    }
  } catch (exception) {
    console.error(`Failed to set the grayScale. Cause code: ${exception.code}, message: ${exception.message}`);
  }
});

[h2]on('windowTitleButtonRectChange')11+

on(type: 'windowTitleButtonRectChange', callback: Callback<TitleButtonRect>): void

开启窗口标题栏上的最小化、最大化、关闭按钮矩形区域变化的监听,对存在标题栏和三键区的窗口形态生效。如果使用Stage模型,该接口需要在loadContent()或setUIContent()调用生效后使用。

此接口仅可在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowTitleButtonRectChange',即标题栏上的最小化、最大化、关闭按钮矩形区域变化事件。
callback Callback<TitleButtonRect> 是 回调函数。返回当前标题栏上的最小化、最大化、关闭按钮矩形区域。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.

示例:

windowClass.setUIContent('pages/WindowPage').then(() => {
  try {
    windowClass?.on('windowTitleButtonRectChange', (titleButtonRect) => {
      console.info('Succeeded in enabling the listener for window title buttons area changes. Data: ' + JSON.stringify(titleButtonRect));
    });
  } catch (exception) {
    console.error(`Failed to enable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`);
  }
})

[h2]off('windowTitleButtonRectChange')11+

off(type: 'windowTitleButtonRectChange', callback?: Callback<TitleButtonRect>): void

关闭窗口标题栏上的最小化、最大化、关闭按钮矩形区域变化的监听,对存在标题栏和三键区的窗口形态生效。如果使用Stage模型,该接口需要在loadContent()或setUIContent()调用生效后使用。

此接口仅可在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowTitleButtonRectChange',即标题栏上的最小化、最大化、关闭按钮矩形区域变化事件。
callback Callback<TitleButtonRect> 否 回调函数。返回当前标题栏上的最小化、最大化、关闭按钮矩形区域。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有标题栏上的最小化、最大化、关闭按钮矩形区域变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.

示例:

windowClass.setUIContent('pages/WindowPage').then(() => {
    const callback = (titleButtonRect: window.TitleButtonRect) => {
        // ...
    }
  try {
    // 通过on接口开启监听
    windowClass?.on('windowTitleButtonRectChange', callback);
    // 关闭指定callback的监听
    windowClass?.off('windowTitleButtonRectChange', callback);
    // 如果通过on开启多个callback进行监听,同时关闭所有监听:
    windowClass?.off('windowTitleButtonRectChange');
  } catch (exception) {
    console.error(`Failed to disable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`);
  }
})

[h2]on('windowRectChange')12+

on(type: 'windowRectChange', callback: Callback<RectChangeOptions>): void

开启窗口矩形(窗口位置及窗口大小)变化的监听。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowRectChange',即窗口矩形变化事件。
callback Callback<RectChangeOptions> 是 回调函数。返回当前窗口矩形变化值及变化原因。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.

示例:

windowClass.on('windowRectChange', (data: window.RectChangeOptions) => {
    console.info('Succeeded window rect changes. Data: ' + JSON.stringify(data));
});

[h2]off('windowRectChange')12+

off(type: 'windowRectChange', callback?: Callback<RectChangeOptions>): void

关闭窗口矩形(窗口位置及窗口大小)变化的监听。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'windowRectChange',即窗口矩形变化事件。
callback Callback<RectChangeOptions> 否 回调函数。返回当前的窗口矩形及变化原因。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有窗口矩形变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
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.

示例:

const callback = (rectChangeOptions: window.RectChangeOptions) => {
  // ...
}
windowClass.on('windowRectChange', callback);
windowClass.off('windowRectChange', callback);
// 如果通过on开启多个callback进行监听,同时关闭所有监听:
windowClass.off('windowRectChange');

[h2]on('subWindowClose')12+

on(type: 'subWindowClose', callback: Callback<void>): void

开启子窗口关闭事件的监听。此监听仅在点击系统提供的右上角关闭按钮关闭子窗时触发,其余关闭方式不触发回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'subWindowClose',即子窗口关闭事件。
callback Callback<void> 是 回调函数。当点击子窗口右上角关闭按钮事件发生时的回调。该回调函数不返回任何参数。回调函数内部逻辑需要有boolean类型的返回值,该返回值决定当前子窗是否继续关闭,true表示不关闭子窗,false表示关闭子窗。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.
1300004 Unauthorized operation.

示例:

const callback = () => {
  // ...
  return true;
}
try {
  windowClass.on('subWindowClose', callback);
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]off('subWindowClose')12+

off(type: 'subWindowClose', callback?: Callback<void>): void

关闭子窗口关闭事件的监听。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'subWindowClose',即子窗口关闭事件。
callback Callback<void> 否 回调函数。当点击子窗口右上角关闭按钮事件发生时的回调。该回调函数不返回任何参数。回调函数内部逻辑需要有boolean类型的返回值,该返回值决定当前子窗是否继续关闭,true表示不关闭子窗,false表示关闭子窗。如果传入参数,则关闭该监听。如果未传入参数,则关闭所有子窗口关闭的监听。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.
1300004 Unauthorized operation.

示例:

const callback = () => {
  // ...
  return true;
}
try {
  windowClass.on('subWindowClose', callback);
  windowClass.off('subWindowClose', callback);
  // 如果通过on开启多个callback进行监听,同时关闭所有监听:
  windowClass.off('subWindowClose');
} catch (exception) {
  console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]isWindowSupportWideGamut9+

isWindowSupportWideGamut(callback: AsyncCallback<boolean>): void

判断当前窗口是否支持广色域模式,使用callback异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示当前窗口支持广色域模式,返回false表示当前窗口不支持广色域模式。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.isWindowSupportWideGamut((err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data));
});

[h2]isWindowSupportWideGamut9+

isWindowSupportWideGamut(): Promise<boolean>

判断当前窗口是否支持广色域模式,使用Promise异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<boolean> Promise对象。返回true表示当前窗口支持广色域模式,返回false表示当前窗口不支持广色域模式。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.isWindowSupportWideGamut();
promise.then((data) => {
  console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setWindowColorSpace9+

setWindowColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void

设置当前窗口为广色域模式或默认色域模式,使用callback异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
colorSpace ColorSpace 是 设置色域模式。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

try {
  windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in setting window colorspace.');
  });
} catch (exception) {
  console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]setWindowColorSpace9+

setWindowColorSpace(colorSpace:ColorSpace): Promise<void>

设置当前窗口为广色域模式或默认色域模式,使用Promise异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
colorSpace ColorSpace 是 设置色域模式。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let promise = windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT);
  promise.then(() => {
    console.info('Succeeded in setting window colorspace.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]getWindowColorSpace9+

getWindowColorSpace(): ColorSpace

获取当前窗口色域模式。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
ColorSpace 当前色域模式。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

let colorSpace = windowClass.getWindowColorSpace();

[h2]setWindowBackgroundColor9+

setWindowBackgroundColor(color: string): void

设置窗口的背景色。Stage模型下,该接口需要在loadContent()或setUIContent()调用生效后使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
color string 是 需要设置的背景色,为十六进制RGB或ARGB颜色,不区分大小写,例如'#00FF00'或'#FF00FF00'。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

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 color: string = '#00ff33';
  try {
    windowClass?.setWindowBackgroundColor(color);
  } catch (exception) {
    console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`);
  };
});

[h2]setWindowBrightness9+

setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void

允许应用主窗口设置屏幕亮度值,使用callback异步回调。

当前屏幕亮度规格:窗口设置屏幕亮度生效时,控制中心不可以调整系统屏幕亮度,窗口恢复默认系统亮度之后,控制中心可以调整系统屏幕亮度。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
brightness number 是 屏幕亮度值。该参数为浮点数,取值范围为[0.0, 1.0]或-1.0。1.0表示最亮,-1.0表示默认亮度。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 brightness: number = 1;
      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}`);
      }
    });
  }
}

[h2]setWindowBrightness9+

setWindowBrightness(brightness: number): Promise<void>

允许应用主窗口设置屏幕亮度值,使用Promise异步回调。

当前屏幕亮度规格:窗口设置屏幕亮度生效时,控制中心不可以调整系统屏幕亮度,窗口恢复默认系统亮度之后,控制中心可以调整系统屏幕亮度。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
brightness number 是 屏幕亮度值。该参数为浮点数,取值范围为[0.0, 1.0]或-1.0。1.0表示最亮,-1.0表示默认亮度。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 brightness: number = 1;
      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}`);
      }
    });
  }
}

[h2]setWindowFocusable9+

setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void

设置使用点击或其他方式使该窗口获焦的场景时,该窗口是否支持窗口焦点从点击前的获焦窗口切换到该窗口,使用callback异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isFocusable boolean 是 点击时是否支持切换焦点窗口。true表示支持;false表示不支持。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]setWindowFocusable9+

setWindowFocusable(isFocusable: boolean): Promise<void>

设置使用点击或其他方式使该窗口获焦的场景时,该窗口是否支持窗口焦点从点击前的获焦窗口切换到该窗口,使用Promise异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isFocusable boolean 是 点击时是否支持切换焦点窗口。true表示支持;false表示不支持。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]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> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]setWindowKeepScreenOn9+

setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void>

设置屏幕是否为常亮状态,使用Promise异步回调。

规范使用该接口:仅在必要场景(导航、视频播放、绘画、游戏等场景)下,设置该属性为true;退出上述场景后,应当重置该属性为false;其他场景(无屏幕互动、音频播放等)下,不使用该接口;系统检测到非规范使用该接口时,可能会恢复自动灭屏功能。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
isKeepScreenOn boolean 是 设置屏幕是否为常亮状态。true表示常亮;false表示不常亮。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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.info(`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}`);
}

[h2]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> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.

示例:

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}`);
}

[h2]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对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
201 Permission verification failed. The application does not have the permission required to call the API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.

示例:

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}`);
}

[h2]setWindowTouchable9+

setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void

设置窗口是否为可触状态,使用callback异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isTouchable boolean 是 窗口是否为可触状态。true表示可触;false表示不可触。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]setWindowTouchable9+

setWindowTouchable(isTouchable: boolean): Promise<void>

设置窗口是否为可触状态,使用Promise异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isTouchable boolean 是 窗口是否为可触状态。true表示可触;false表示不可触。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

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}`);
}

[h2]snapshot9+

snapshot(callback: AsyncCallback<image.PixelMap>): void

获取窗口截图,使用callback异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<image.PixelMap> 是 回调函数。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

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使用完后及时释放内存
});

[h2]snapshot9+

snapshot(): Promise<image.PixelMap>

获取窗口截图,使用Promise异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<image.PixelMap> Promise对象。返回当前窗口截图。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

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}`);
});

[h2]setAspectRatio10+

setAspectRatio(ratio: number): Promise<void>

设置窗口内容布局的比例,使用Promise异步回调。

通过其他接口如resize、resizeAsync设置窗口大小时,不受ratio约束。

仅主窗可设置,且仅在自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)下生效,比例参数将持久化保存,关闭应用或重启设备设置的比例仍然生效。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ratio number 是 除边框装饰之外的窗口内容布局的宽高比。该参数为浮点数,受窗口最大最小尺寸限制,比例值下限为最小宽度/最大高度,上限为最大宽度/最小高度。窗口最大最小尺寸由WindowLimits和系统限制的交集决定,系统限制优先级高于WindowLimits。ratio的有效范围会随WindowLimits变化而变化。如果先设置了WindowLimits,后设置的ratio与其冲突,会返回错误码;如果先设置了ratio,后设置的WindowLimits与其冲突,窗口的宽高比可能会不跟随设置的宽高比(ratio)。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {

  // ...
  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口
    if (!windowClass) {
      console.info('windowClass is null');
    }
    try {
      let ratio = 1.0;
      let promise = windowClass.setAspectRatio(ratio);
      promise.then(() => {
        console.info('Succeeded in setting aspect ratio of window.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

[h2]setAspectRatio10+

setAspectRatio(ratio: number, callback: AsyncCallback<void>): void

设置窗口内容布局的比例,使用callback异步回调。

通过其他接口如resize、resizeAsync设置窗口大小时,不受ratio约束。

仅主窗可设置,且仅在自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)下生效,比例参数将持久化保存,关闭应用或重启设备设置的比例仍然生效。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
ratio number 是 除边框装饰之外的窗口内容布局的宽高比。该参数为浮点数,受窗口最大最小尺寸限制,比例值下限为最小宽度/最大高度,上限为最大宽度/最小高度。窗口最大最小尺寸由WindowLimits和系统限制的交集决定,系统限制优先级高于WindowLimits。ratio的有效范围会随WindowLimits变化而变化。如果先设置了WindowLimits,后设置的ratio与其冲突,会返回错误码;如果先设置了ratio,后设置的WindowLimits与其冲突,窗口的宽高比可能会不跟随设置的宽高比(ratio)。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {

  // ...
  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口
    if (!windowClass) {
      console.info('Failed to load the content. Cause: windowClass is null');
    }
    try {
      let ratio = 1.0;
      windowClass.setAspectRatio(ratio, (err: BusinessError) => {
        const errCode: number = err.code;
        if (errCode) {
          console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        console.info('Succeeded in setting the aspect ratio of window.');
      });
    } catch (exception) {
      console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

[h2]resetAspectRatio10+

resetAspectRatio(): Promise<void>

取消设置窗口内容布局的比例,使用Promise异步回调。

仅主窗可设置,且仅在自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)下生效,调用后将清除持久化储存的比例信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {

  // ...
  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口
    if (!windowClass) {
      console.info('Failed to load the content. Cause: windowClass is null');
    }
    try {
      let promise = windowClass.resetAspectRatio();
      promise.then(() => {
        console.info('Succeeded in resetting aspect ratio of window.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

[h2]resetAspectRatio10+

resetAspectRatio(callback: AsyncCallback<void>): void

取消设置窗口内容布局的比例,使用callback异步回调。

仅主窗可设置,且仅在自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)下生效,调用后将清除持久化储存的比例信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {

  // ...
  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口
    if (!windowClass) {
      console.info('Failed to load the content. Cause: windowClass is null');
    }
    try {
      windowClass.resetAspectRatio((err: BusinessError) => {
        const errCode: number = err.code;
        if (errCode) {
          console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        console.info('Succeeded in resetting aspect ratio of window.');
      });
    } catch (exception) {
      console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

[h2]minimize11+

minimize(callback: AsyncCallback<void>): void

此接口根据调用对象不同,实现不同的功能:

使用callback异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
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.

示例:

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.');
});

[h2]minimize11+

minimize(): Promise<void>

此接口根据调用对象不同,实现不同的功能:

使用Promise异步回调。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
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.

示例:

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}`);
});

[h2]maximize12+

maximize(presentation?: MaximizePresentation): Promise<void>

主窗口调用,实现最大化功能,使用Promise异步回调。

此接口仅可在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
presentation MaximizePresentation 否 主窗口最大化时候的布局枚举。默认值window.MaximizePresentation.ENTER_IMMERSIVE,即默认最大化时进入沉浸式布局。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
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.
1300004 Unauthorized operation.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
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}`);
      });
    });
  }
};

[h2]recover11+

recover(): Promise<void>

将主窗口从全屏、最大化、分屏模式下还原为浮动窗口,并恢复到进入该模式之前的大小和位置,已经是浮动窗口模式不可再还原。使用Promise异步回调。此接口仅在多窗层叠布局效果下生效。

此接口仅可在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300001 Repeated operation.
1300002 This window state is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 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}`);
      });
    });
  }
}

[h2]getWindowLimits11+

getWindowLimits(): WindowLimits

获取当前应用窗口的尺寸限制。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
WindowLimits 当前窗口尺寸限制。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.

示例:

try {
  let windowLimits = windowClass.getWindowLimits();
} catch (exception) {
  console.error(`Failed to obtain the window limits of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]setWindowLimits11+

setWindowLimits(windowLimits: WindowLimits): Promise<WindowLimits>

设置当前应用窗口的尺寸限制,使用Promise异步回调。

默认存在一个系统尺寸限制,系统尺寸限制由产品配置决定,不可修改。未调用setWindowLimits配置过WindowLimits时,使用getWindowLimits可获取系统限制。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
windowLimits WindowLimits 是 目标窗口的尺寸限制,单位为px。

返回值:

类型 说明
Promise<WindowLimits> Promise对象。返回设置后的尺寸限制,为入参与系统尺寸限制的交集。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
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.
1300004 Unauthorized operation.

示例:

import { BusinessError } from '@kit.BasicServicesKit';
try {
  let windowLimits: window.WindowLimits = {
    maxWidth: 1500,
    maxHeight: 1000,
    minWidth: 500,
    minHeight: 400
  };
  let promise = windowClass.setWindowLimits(windowLimits);
    promise.then((data) => {
    console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]setWindowMask12+

setWindowMask(windowMask: Array<Array<number>>): Promise<void>;

设置异形窗口的掩码,使用Promise异步回调。异形窗口为非常规形状的窗口,掩码用于描述异形窗口的形状。此接口仅限子窗和全局悬浮窗可用。

当异形窗口大小发生变化时,实际的显示内容为掩码大小和窗口大小的交集部分。

此接口仅可在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
windowMask Array<Array<number>> 是 异形窗口的掩码,该参数仅支持宽高为窗口宽高、取值为整数0和整数1的二维数组输入,整数0代表所在像素透明,整数1代表所在像素不透明,宽高不符合的二维数组或二维数组取值不为整数0和整数1的二维数组为非法参数。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

import { BusinessError } from '@kit.BasicServicesKit';
try {
  let windowMask: Array<Array<number>> = [
      [0, 0, 0, 1, 0, 0, 0],
      [0, 0, 1, 1, 1, 0, 0],
      [0, 1, 1, 0, 1, 1, 0],
      [1, 1, 0, 0, 0, 1, 1]
    ];
  let promise = windowClass.setWindowMask(windowMask);
    promise.then(() => {
    console.info('Succeeded in setting the window mask.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set the window mask. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set the window mask. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]keepKeyboardOnFocus11+

keepKeyboardOnFocus(keepKeyboardFlag: boolean): void

窗口获焦时保留由其他窗口创建的软键盘,仅支持系统窗口与应用子窗口。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
keepKeyboardFlag boolean 是 是否保留其他窗口创建的软键盘。true表示保留;false表示不保留。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

try {
  windowClass.keepKeyboardOnFocus(true);
} catch (exception) {
  console.error(`Failed to keep keyboard onFocus. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]setWindowDecorVisible11+

setWindowDecorVisible(isVisible: boolean): void

设置窗口标题栏是否可见,对存在标题栏和三键区的窗口形态生效。Stage模型下,该接口需要在loadContent()或setUIContent()调用生效后使用。

设置窗口标题栏不可见后,当主窗口进入全屏沉浸状态时,此时鼠标Hover到上方窗口标题栏热区上会显示悬浮标题栏。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
isVisible boolean 是 设置标题栏是否可见,true为可见,false为隐藏。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

import { BusinessError } from '@kit.BasicServicesKit';
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 isVisible = false;
  // 调用setWindowDecorVisible接口
  try {
      windowClass?.setWindowDecorVisible(isVisible);
  } catch (exception) {
      console.error(`Failed to set the visibility of window decor. Cause code: ${exception.code}, message: ${exception.message}`);
  }
});

[h2]setSubWindowModal12+

setSubWindowModal(isModal: boolean): Promise<void>

设置子窗的模态属性是否启用,使用Promise异步回调。

子窗口调用该接口时,设置子窗口模态属性是否启用。启用子窗口模态属性后,其父级窗口不能响应用户操作,直到子窗口关闭或者子窗口的模态属性被禁用。

子窗口之外的窗口调用该接口时,会报错。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
isModal boolean 是 设置子窗口模态属性是否启用,true为启用,false为不启用。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    // 创建子窗
    try {
      let subWindow = windowStage.createSubWindow("testSubWindow");
      subWindow.then((data) => {
        if (data == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        windowClass = data;
        let promise = windowClass.setSubWindowModal(true);
        promise.then(() => {
          console.info('Succeeded in setting subwindow modal');
        }).catch((err: BusinessError) => {
          console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`);
        });
      });
    } catch (exception) {
      console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

[h2]setWindowDecorHeight11+

setWindowDecorHeight(height: number): void

设置窗口的标题栏高度,仅在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下,对存在标题栏和三键区的窗口形态生效。如果使用Stage模型,该接口需要在loadContent()或setUIContent()调用生效后使用。

当主窗口进入全屏沉浸状态时,此时鼠标Hover到窗口标题栏热区时,会显示悬浮标题栏,悬浮标题栏高度固定为37vp。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
height number 是 设置的窗口标题栏高度,仅支持具有窗口标题栏的窗口。该参数为整数,浮点数输入将向下取整,取值范围为[37,112],范围外为非法参数,单位为vp。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.

示例:

windowClass.setUIContent('pages/WindowPage').then(() => {
  let height: number = 50;
  try {
    windowClass?.setWindowDecorHeight(height);
    console.info(`Succeeded in setting the height of window decor: ${height}`);
  } catch (exception) {
    console.error(`Failed to set the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`);
  }
})

[h2]getWindowDecorHeight11+

getWindowDecorHeight(): number

获取窗口的标题栏高度,仅在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下,对存在标题栏和三键区的窗口形态生效。如果使用Stage模型,该接口需要在loadContent()或setUIContent()调用生效后使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
number 返回的窗口标题栏高度。该参数为整数,取值范围为[37,112],单位为vp。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.

示例:

windowClass.setUIContent('pages/WindowPage').then(() => {
  try {
    let height = windowClass?.getWindowDecorHeight();
    console.info(`Succeeded in getting the height of window decor: ${height}`);
  } catch (exception) {
    console.error(`Failed to get the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`);
  }
})

[h2]getTitleButtonRect11+

getTitleButtonRect(): TitleButtonRect

获取主窗口或启用装饰的子窗口的标题栏上的最小化、最大化、关闭按钮矩形区域。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
TitleButtonRect 标题栏上的最小化、最大化、关闭按钮矩形区域,该区域位置坐标相对窗口右上角。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 titleButtonArea = windowClass.getTitleButtonRect();
        console.info('Succeeded in obtaining the area of title buttons. Data: ' + JSON.stringify(titleButtonArea));
      } catch (exception) {
        console.error(`Failed to get the area of title buttons. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

[h2]getWindowStatus12+

getWindowStatus(): WindowStatusType

获取当前应用窗口的模式。

在2in1设备上调用本接口时,在窗口最大化状态时返回值对应为WindowStatusType::FULL_SCREEN。

若想在2in1设备上区分当前窗口状态为最大化还是全屏,可在窗口状态为WindowStatusType::FULL_SCREEN的情况下,再调用getImmersiveModeEnabledState() 接口进行进一步判断,到底是最大化状态还是全屏状态。若接口返回true则表示当前窗口为全屏状态,若接口返回false则表示当前窗口为最大化状态。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
WindowStatusType 当前窗口模式。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.

示例:

try {
  let windowStatusType = windowClass.getWindowStatus();
} catch (exception) {
  console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]isFocused12+

isFocused(): boolean

判断当前窗口是否已获焦。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

返回值:

类型 说明
boolean 当前窗口是否已获焦。true表示当前窗口已获焦,false则表示当前窗口未获焦。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.

示例:

try {
  let focus = windowClass.isFocused();
  console.info('Succeeded in checking whether the window is focused. Data: ' + JSON.stringify(focus));
} catch (exception) {
  console.error(`Failed to check whether the window is focused. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]createSubWindowWithOptions12+

createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window>

创建主窗口或子窗口下的子窗口,使用Promise异步回调。

此接口仅可在2in1设备或平板设备的自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 子窗口的名字。
options SubWindowOptions 是 子窗口参数。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前Window下创建的子窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 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.
1300004 Unauthorized operation.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

try {
  let options : window.SubWindowOptions = {
    title: 'title',
    decorEnabled: true,
    isModal: true
  };
  let promise = windowClass.createSubWindowWithOptions('mySubWindow', options);
  promise.then((data) => {
    console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
}

[h2]enableLandscapeMultiWindow12+

enableLandscapeMultiWindow(): Promise<void>

应用部分界面支持横向布局时,在进入该界面时使能,使能后可支持进入横向多窗。不建议竖向布局界面使用。

此接口只对应用主窗口生效,且需要在module.json5配置文件中abilities标签中配置preferMultiWindowOrientation属性为"landscape_auto"。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例:

// 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 promise = windowClass.enableLandscapeMultiWindow();
      promise.then(() => {
        console.info('Succeeded in making multi-window become landscape.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to make multi-window become landscape. Cause code: ${err.code}, message: ${err.message}`);
      });
    });
  }
}

[h2]disableLandscapeMultiWindow12+

disableLandscapeMultiWindow(): Promise<void>

应用部分界面支持横向布局时,在退出该界面时去使能,去使能后不支持进入横向多窗。

此接口只对应用主窗口生效,且需要在module.json5配置文件中abilities标签中配置preferMultiWindowOrientation属性为"landscape_auto"。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例:

// 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 promise = windowClass.disableLandscapeMultiWindow();
      promise.then(() => {
        console.info('Succeeded in making multi-window become not landscape.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to make multi-window become not landscape. Cause code: ${err.code}, message: ${err.message}`);
      });
    });
  }
}

[h2]setDialogBackGestureEnabled12+

setDialogBackGestureEnabled(enabled: boolean): Promise<void>

设置模态窗口是否响应手势返回事件,非模态窗口调用返回错误码。

系统能力:SystemCapability.Window.SessionManager

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
enabled boolean 是

是否响应手势返回事件。

true表示响应手势返回事件,触发onBackPress回调;false表示不响应手势返回事件,不触发onBackPress回调。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300004 Unauthorized operation.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    let config: window.Configuration = {
      name: "test",
      windowType: window.WindowType.TYPE_DIALOG,
      ctx: this.context
    };
    try {
      window.createWindow(config, (err: BusinessError, data) => {
        const errCode: number = err.code;
        if (errCode) {
          console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        windowClass = data;
        windowClass.setUIContent("pages/Index");
        let enabled = true;
        let promise = windowClass.setDialogBackGestureEnabled(enabled);
        promise.then(() => {
          console.info('Succeeded in setting dialog window to respond back gesture.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to set dialog window to respond back gesture. Cause code: ${err.code}, message: ${err.message}`);
        });
      });
    } catch (exception) {
      console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}
// ets/pages/Index.ets
@Entry
@Component
struct Index {
  @State message: string = 'Hello World'
  build() {
    RelativeContainer() {
      Text(this.message)
        .id('HelloWorld')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
    }
    .height('100%')
    .width('100%')
  }

  onBackPress(): boolean | void {
    console.info('Succeeded in setting dialog window to respond back gesture.');
    return true;
  }
}

[h2]setWindowSystemBarProperties(deprecated)

setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void

设置主窗口三键导航栏、状态栏的属性,使用callback异步回调,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

子窗口调用后不生效。

从API version 9开始支持,从API version 12开始废弃,推荐使用Promise方式的setWindowSystemBarProperties。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
systemBarProperties SystemBarProperties 是 三键导航栏、状态栏的属性。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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}`);
      }
    });
  }
}

[h2]setWindowSystemBarEnable(deprecated)

setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void

设置主窗口三键导航栏、状态栏、底部导航条的可见模式,状态栏与底部导航条通过status控制、三键导航栏通过navigation控制,使用callback异步回调。从API version 12开始,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

调用生效后返回并不表示三键导航栏、状态栏和底部导航条的显示或隐藏已完成。子窗口调用后不生效。

从API version 9开始支持,从API version 12开始废弃,推荐使用Promise方式的setWindowSystemBarEnable。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
names Array<'status'|'navigation'> 是

设置窗口全屏模式时状态栏、三键导航栏和底部导航条是否显示。

例如,需全部显示,该参数设置为['status', 'navigation'];不设置,则默认不显示。

callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// 此处以不显示三键导航栏、状态栏、底部导航条为例
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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}`);
      }
    });
  }
}

[h2]setWindowLayoutFullScreen(deprecated)

setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void

设置主窗口或子窗口的布局是否为沉浸式布局,使用callback异步回调。

沉浸式布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。

非沉浸式布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。

从API version 9开始支持,从API version 12开始废弃,推荐使用Promise方式的setWindowLayoutFullScreen。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 12开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
isLayoutFullScreen boolean 是 窗口的布局是否为沉浸式布局(该沉浸式布局状态栏、导航栏仍然显示)。true表示沉浸式布局;false表示非沉浸式布局。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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}`);
      }
    });
  }
}

[h2]show(deprecated)

show(callback: AsyncCallback<void>): void

显示当前窗口,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用showWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.show((err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in showing the window.');
});

[h2]show(deprecated)

show(): Promise<void>

显示当前窗口,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用showWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.show();
promise.then(() => {
  console.info('Succeeded in showing the window.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]destroy(deprecated)

destroy(callback: AsyncCallback<void>): void

销毁当前窗口,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用destroyWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.destroy((err: BusinessError) => {
  const errCode: number = err.code;
  if (err.code) {
    console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in destroying the window.');
});

[h2]destroy(deprecated)

destroy(): Promise<void>

销毁当前窗口,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用destroyWindow()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.destroy();
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}`);
});

[h2]moveTo(deprecated)

moveTo(x: number, y: number, callback: AsyncCallback<void>): void

移动窗口位置,使用callback异步回调。

全屏模式窗口不支持该操作。

从 API version 7开始支持,从API version 9开始废弃,推荐使用moveWindowTo()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
x number 是 窗口在x轴方向移动到的坐标位置,单位为px,值为正表示位置在x轴右侧;值为负表示位置在x轴左侧;值为0表示位置在x轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。
y number 是 窗口在y轴方向移动到的坐标位置,单位为px,值为正表示位置在y轴下侧;值为负表示位置在y轴上侧;值为0表示位置在x轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.moveTo(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.');
});

[h2]moveTo(deprecated)

moveTo(x: number, y: number): Promise<void>

移动窗口位置,使用Promise异步回调。

全屏模式窗口不支持该操作。

从 API version 7开始支持,从API version 9开始废弃,推荐使用moveWindowTo()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
x number 是 窗口在x轴方向移动到的坐标位置,单位为px,值为正表示位置在x轴右侧;值为负表示位置在x轴左侧;值为0表示位置在x轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。
y number 是 窗口在y轴方向移动到的坐标位置,单位为px,值为正表示位置在y轴下侧;值为负表示位置在y轴上侧;值为0表示位置在y轴坐标原点。该参数仅支持整数输入,浮点数输入将向下取整。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.moveTo(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}`);
});

[h2]resetSize(deprecated)

resetSize(width: number, height: number, callback: AsyncCallback<void>): void

改变当前窗口大小,使用callback异步回调。

应用主窗口与子窗口存在大小限制,默认宽度范围:[320, 1920],默认高度范围:[240, 1920],单位为vp。

应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置,配置后的最小宽度与最小高度以产品段配置值为准,具体尺寸限制范围可以通过getWindowLimits接口进行查询。

系统窗口存在大小限制,宽度范围:(0, 1920],高度范围:(0, 1920],单位为vp。

设置的宽度与高度受到此约束限制,规则:

若所设置的窗口宽/高尺寸小于窗口最小宽/高限值,则窗口最小宽/高限值生效;

若所设置的窗口宽/高尺寸大于窗口最大宽/高限值,则窗口最大宽/高限值生效。

全屏模式窗口不支持该操作。

从 API version 7开始支持,从API version 9开始废弃,推荐使用resize()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
width number 是 目标窗口的宽度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。
height number 是 目标窗口的高度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.resetSize(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.');
});

[h2]resetSize(deprecated)

resetSize(width: number, height: number): Promise<void>

改变当前窗口大小,使用Promise异步回调。

应用主窗口与子窗口存在大小限制,默认宽度范围:[320, 1920],默认高度范围:[240, 1920],单位为vp。

应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置,配置后的最小宽度与最小高度以产品段配置值为准,具体尺寸限制范围可以通过getWindowLimits接口进行查询。

系统窗口存在大小限制,宽度范围:(0, 1920],高度范围:(0, 1920],单位为vp。

设置的宽度与高度受到此约束限制,规则:

若所设置的窗口宽/高尺寸小于窗口最小宽/高限值,则窗口最小宽/高限值生效;

若所设置的窗口宽/高尺寸大于窗口最大宽/高限值,则窗口最大宽/高限值生效。

全屏模式窗口不支持该操作。

从 API version 7开始支持,从API version 9开始废弃,推荐使用resize()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
width number 是 目标窗口的宽度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。
height number 是 目标窗口的高度,单位为px,该参数仅支持整数输入,浮点数输入将向下取整,负值为非法参数。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.resetSize(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}`);
});

[h2]getProperties(deprecated)

getProperties(callback: AsyncCallback<WindowProperties>): void

获取当前窗口的属性,使用callback异步回调,返回WindowProperties。

从 API version 6开始支持,从API version 9开始废弃,推荐使用getWindowProperties()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<WindowProperties> 是 回调函数。返回当前窗口属性。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.getProperties((err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data));
});

[h2]getProperties(deprecated)

getProperties(): Promise<WindowProperties>

获取当前窗口的属性,使用Promise异步回调,返回WindowProperties。

从 API version 6开始支持,从API version 9开始废弃,推荐使用getWindowProperties()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<WindowProperties> Promise对象。返回当前窗口属性。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.getProperties();
promise.then((data) => {
  console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]getAvoidArea(deprecated)

getAvoidArea(type: AvoidAreaType, callback: AsyncCallback<AvoidArea>): void

获取当前窗口内容规避的区域;如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。

从 API version 7开始支持,从API version 9开始废弃,推荐使用getWindowAvoidArea()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type AvoidAreaType 是 表示规避区类型。
callback AsyncCallback<AvoidArea> 是 回调函数。返回窗口内容规避区域。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let type = window.AvoidAreaType.TYPE_SYSTEM;
windowClass.getAvoidArea(type, (err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data));
});

[h2]getAvoidArea(deprecated)

getAvoidArea(type: AvoidAreaType): Promise<AvoidArea>

获取当前窗口内容规避的区域;如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。

从 API version 7开始支持,从API version 9开始废弃,推荐使用getWindowAvoidArea()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type AvoidAreaType 是 表示规避区类型。

返回值:

类型 说明
Promise<AvoidArea> Promise对象。返回窗口内容规避区域。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let type = window.AvoidAreaType.TYPE_SYSTEM;
let promise = windowClass.getAvoidArea(type);
promise.then((data) => {
  console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setFullScreen(deprecated)

setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void

设置主窗口或子窗口的布局是否为全屏布局,使用callback异步回调。

全屏布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。

非全屏布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。

从 API version 6开始支持,从API version 9开始废弃,推荐联合使用setWindowSystemBarEnable()和setWindowLayoutFullScreen()实现全屏。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isFullScreen boolean 是 是否设为全屏布局(该全屏布局影响状态栏导航栏显示)。true表示全屏;false表示非全屏。
callback AsyncCallback<void> 是 回调函数。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 isFullScreen: boolean = true;
      windowClass.setFullScreen(isFullScreen, (err: BusinessError) => {
        const errCode: number = err.code;
        if (errCode) {
          console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        console.info('Succeeded in enabling the full-screen mode.');
      });
    });
  }
}

[h2]setFullScreen(deprecated)

setFullScreen(isFullScreen: boolean): Promise<void>

设置主窗口或子窗口的布局是否为全屏布局,使用Promise异步回调。

全屏布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。

非全屏布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。

从 API version 6开始支持,从API version 9开始废弃,推荐联合使用setWindowSystemBarEnable()和setWindowLayoutFullScreen()实现全屏。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isFullScreen boolean 是 是否设为全屏布局(该全屏布局影响状态栏导航栏显示)。true表示全屏;false表示非全屏。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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 isFullScreen: boolean = true;
      let promise = windowClass.setFullScreen(isFullScreen);
      promise.then(() => {
        console.info('Succeeded in enabling the full-screen mode.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
      });
    });
  }
}

[h2]setLayoutFullScreen(deprecated)

setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void

设置主窗口或子窗口的布局是否为沉浸式布局,使用callback异步回调。

沉浸式布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。

非沉浸式布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowLayoutFullScreen()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isLayoutFullScreen boolean 是 窗口的布局是否为沉浸式布局(该沉浸式布局不影响状态栏、导航栏显示)。true表示沉浸式布局;false表示非沉浸式布局。
callback AsyncCallback<void> 是 回调函数。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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: boolean = true;
      windowClass.setLayoutFullScreen(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.');
      });
    });
  }
}

[h2]setLayoutFullScreen(deprecated)

setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>

设置主窗口或子窗口的布局是否为沉浸式布局,使用Promise异步回调。

沉浸式布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。

非沉浸式布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowLayoutFullScreen()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isLayoutFullScreen boolean 是 窗口的布局是否为沉浸式布局(该沉浸式布局不影响状态栏、导航栏显示)。true表示沉浸式布局;false表示非沉浸式布局。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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: boolean = true;
      let promise = windowClass.setLayoutFullScreen(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}`);
      });
    });
  }
}

[h2]setSystemBarEnable(deprecated)

setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void

设置主窗口三键导航栏、状态栏、底部导航条的可见模式,状态栏与底部导航条通过status控制、三键导航栏通过navigation控制,使用callback异步回调。从API version 12开始,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

调用生效后返回并不表示三键导航栏、状态栏和底部导航条的显示或隐藏已完成。子窗口调用后不生效。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowSystemBarEnable()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
names Array<'status'|'navigation'> 是

设置窗口全屏模式时状态栏、三键导航栏和底部导航条是否显示。

例如,需全部显示,该参数设置为['status', 'navigation'];不设置,则默认不显示。

callback AsyncCallback<void> 是 回调函数。

示例:

// 此处以不显示三键导航栏、状态栏、底部导航条为例
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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'> = [];
      windowClass.setSystemBarEnable(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.');
      });
    });
  }
}

[h2]setSystemBarEnable(deprecated)

setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void>

设置主窗口三键导航栏、状态栏、底部导航条的可见模式,状态栏与底部导航条通过status控制、三键导航栏通过navigation控制,使用Promise异步回调。从API version 12开始,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

调用生效后返回并不表示三键导航栏、状态栏和底部导航条的显示或隐藏已完成。子窗口调用后不生效。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowSystemBarEnable()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
names Array<'status'|'navigation'> 是

设置窗口全屏模式时状态栏、三键导航栏、底部导航条是否显示。

例如,需全部显示,该参数设置为['status', 'navigation'];不设置,则默认不显示。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

// 此处以不显示三键导航栏、状态栏、底部导航条为例
// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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'> = [];
      let promise = windowClass.setSystemBarEnable(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}`);
      });
    });
  }
}

[h2]setSystemBarProperties(deprecated)

setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void

设置主窗口三键导航栏、状态栏的属性,使用callback异步回调,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

子窗口调用后不生效。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowSystemBarProperties()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
systemBarProperties SystemBarProperties 是 三键导航栏、状态栏的属性。
callback AsyncCallback<void> 是 回调函数。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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'
      };
      windowClass.setSystemBarProperties(SystemBarProperties, (err) => {
        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.');
      });
    });
  }
}

[h2]setSystemBarProperties(deprecated)

setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void>

设置主窗口三键导航栏、状态栏的属性,使用Promise异步回调,

该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。

子窗口调用后不生效。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowSystemBarProperties()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
systemBarProperties SystemBarProperties 是 三键导航栏、状态栏的属性。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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'
      };
      let promise = windowClass.setSystemBarProperties(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}`);
      });
    });
  }
}

[h2]loadContent(deprecated)

loadContent(path: string, callback: AsyncCallback<void>): void

为当前窗口加载具体页面内容,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setUIContent()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,Stage模型下该路径需添加到工程的main_pages.json文件中,FA模型下该路径需添加到工程的config.json文件中。
callback AsyncCallback<void> 是 回调函数。

示例:

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.');
});

[h2]loadContent(deprecated)

loadContent(path: string): Promise<void>

为当前窗口加载具体页面内容,使用Promise异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setUIContent()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,Stage模型下该路径需添加到工程的main_pages.json文件中,FA模型下该路径需添加到工程的config.json文件中。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

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}`);
});

[h2]isShowing(deprecated)

isShowing(callback: AsyncCallback<boolean>): void

判断当前窗口是否已显示,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用isWindowShowing()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示当前窗口已显示,返回false表示当前窗口未显示。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.isShowing((err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data));
});

[h2]isShowing(deprecated)

isShowing(): Promise<boolean>

判断当前窗口是否已显示,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用isWindowShowing()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<boolean> Promise对象。返回true表示当前窗口已显示,返回false表示当前窗口未显示。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.isShowing();
promise.then((data) => {
  console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]on('systemAvoidAreaChange')(deprecated)

on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void

开启当前窗口系统规避区变化的监听。

从 API version 7开始支持,从API version 9开始废弃,推荐使用on('avoidAreaChange')。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'systemAvoidAreaChange',即系统规避区变化事件。
callback Callback<AvoidArea> 是 回调函数。返回当前规避区。

示例:

windowClass.on('systemAvoidAreaChange', (data) => {
  console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data));
});

[h2]off('systemAvoidAreaChange')(deprecated)

off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void

关闭当前窗口系统规避区变化的监听。

从 API version 7开始支持,从API version 9开始废弃,推荐使用off('avoidAreaChange')。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
type string 是 监听事件,固定为'systemAvoidAreaChange',即系统规避区变化事件。
callback Callback<AvoidArea> 否 回调函数。返回当前规避区。若传入参数,则关闭该监听。若未传入参数,则关闭所有系统规避区变化的监听。

示例:

const callback = (avoidArea: window.AvoidArea) => {
  // ...
}
windowClass.on('systemAvoidAreaChange', callback);
windowClass.off('systemAvoidAreaChange', callback);
// 如果通过on开启多个callback进行监听,同时关闭所有监听:
windowClass.off('systemAvoidAreaChange');

[h2]isSupportWideGamut(deprecated)

isSupportWideGamut(callback: AsyncCallback<boolean>): void

判断当前窗口是否支持广色域模式,使用callback异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用isWindowSupportWideGamut()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示当前窗口支持广色域模式,返回false表示当前窗口不支持广色域模式。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.isSupportWideGamut((err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data));
});

[h2]isSupportWideGamut(deprecated)

isSupportWideGamut(): Promise<boolean>

判断当前窗口是否支持广色域模式,使用Promise异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用isWindowSupportWideGamut()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<boolean> Promise对象。返回true表示当前窗口支持广色域模式,返回false表示当前窗口不支持广色域模式。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.isSupportWideGamut();
promise.then((data) => {
  console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setColorSpace(deprecated)

setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void

设置当前窗口为广色域模式或默认色域模式,使用callback异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用setWindowColorSpace()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
colorSpace ColorSpace 是 设置色域模式。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in setting window colorspace.');
});

[h2]setColorSpace(deprecated)

setColorSpace(colorSpace:ColorSpace): Promise<void>

设置当前窗口为广色域模式或默认色域模式,使用Promise异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用setWindowColorSpace()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
colorSpace ColorSpace 是 设置色域模式。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT);
promise.then(() => {
  console.info('Succeeded in setting window colorspace.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]getColorSpace(deprecated)

getColorSpace(callback: AsyncCallback<ColorSpace>): void

获取当前窗口色域模式,使用callback异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用getWindowColorSpace()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<ColorSpace> 是 回调函数。当获取成功,err为undefined,data为当前色域模式。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.getColorSpace((err: BusinessError, data) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data));
});

[h2]getColorSpace(deprecated)

getColorSpace(): Promise<ColorSpace>

获取当前窗口色域模式,使用Promise异步回调。

从 API version 8开始支持,从API version 9开始废弃,推荐使用getWindowColorSpace()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

返回值:

类型 说明
Promise<ColorSpace> Promise对象。返回当前色域模式。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.getColorSpace();
promise.then((data) => {
  console.info('Succeeded in getting window color space. Cause:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setBackgroundColor(deprecated)

setBackgroundColor(color: string, callback: AsyncCallback<void>): void

设置窗口的背景色,使用callback异步回调。Stage模型下,该接口需要在loadContent()或setUIContent()调用生效后使用。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowBackgroundColor()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
color string 是 需要设置的背景色,为十六进制RGB或ARGB颜色,不区分大小写,例如'#00FF00'或'#FF00FF00'。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let color: string = '#00ff33';
windowClass.setBackgroundColor(color, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the background color.');
});

[h2]setBackgroundColor(deprecated)

setBackgroundColor(color: string): Promise<void>

设置窗口的背景色,使用Promise异步回调。Stage模型下,该接口需要在loadContent()或setUIContent()调用生效后使用。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowBackgroundColor()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
color string 是 需要设置的背景色,为十六进制RGB或ARGB颜色,不区分大小写,例如'#00FF00'或'#FF00FF00'。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let color: string = '#00ff33';
let promise = windowClass.setBackgroundColor(color);
promise.then(() => {
  console.info('Succeeded in setting the background color.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setBrightness(deprecated)

setBrightness(brightness: number, callback: AsyncCallback<void>): void

允许应用窗口设置屏幕亮度值,使用callback异步回调。

当前屏幕亮度规格:窗口设置屏幕亮度生效时,控制中心不可以调整系统屏幕亮度,窗口恢复默认系统亮度之后,控制中心可以调整系统屏幕亮度。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowBrightness()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
brightness number 是 屏幕亮度值。该参数为浮点数,取值范围为[0.0, 1.0]或-1.0。1.0表示最亮,-1.0表示默认亮度。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let brightness: number = 1;
windowClass.setBrightness(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.');
});

[h2]setBrightness(deprecated)

setBrightness(brightness: number): Promise<void>

允许应用窗口设置屏幕亮度值,使用Promise异步回调。

当前屏幕亮度规格:窗口设置屏幕亮度生效时,控制中心不可以调整系统屏幕亮度,窗口恢复默认系统亮度之后,控制中心可以调整系统屏幕亮度。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowBrightness()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
brightness number 是 屏幕亮度值。该参数为浮点数,取值范围为[0.0, 1.0]或-1.0。1.0表示最亮,-1.0表示默认亮度。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let brightness: number = 1;
let promise = windowClass.setBrightness(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}`);
});

[h2]setDimBehind(deprecated)

setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void

窗口叠加时,设备有子窗口的情况下设置靠后的窗口的暗度值,使用callback异步回调。

该接口不支持使用。从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
dimBehindValue number 是 表示靠后的窗口的暗度值,取值范围为[0.0, 1.0],取1.0时表示最暗。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.setDimBehind(0.5, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the dimness.');
});

[h2]setDimBehind(deprecated)

setDimBehind(dimBehindValue: number): Promise<void>

窗口叠加时,设备有子窗口的情况下设置靠后的窗口的暗度值,使用Promise异步回调。

该接口不支持使用。从 API version 7开始支持,从API version 9开始废弃。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
dimBehindValue number 是 表示靠后的窗口的暗度值,取值范围为0-1,1表示最暗。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.setDimBehind(0.5);
promise.then(() => {
  console.info('Succeeded in setting the dimness.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setFocusable(deprecated)

setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void

设置使用点击或其他方式使该窗口获焦的场景时,该窗口是否支持窗口焦点从操作前的获焦窗口切换到该窗口,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowFocusable()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isFocusable boolean 是 点击时是否支持切换焦点窗口。true表示支持;false表示不支持。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isFocusable: boolean = true;
windowClass.setFocusable(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.');
});

[h2]setFocusable(deprecated)

setFocusable(isFocusable: boolean): Promise<void>

设置使用点击或其他方式使该窗口获焦的场景时,该窗口是否支持窗口焦点从点击前的获焦窗口切换到该窗口,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowFocusable()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isFocusable boolean 是 点击时是否支持切换焦点窗口。true表示支持;false表示不支持。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isFocusable: boolean = true;
let promise = windowClass.setFocusable(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}`);
});

[h2]setKeepScreenOn(deprecated)

setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void

设置屏幕是否为常亮状态,使用callback异步回调。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowKeepScreenOn()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isKeepScreenOn boolean 是 设置屏幕是否为常亮状态。true表示常亮;false表示不常亮。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isKeepScreenOn: boolean = true;
windowClass.setKeepScreenOn(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.');
});

[h2]setKeepScreenOn(deprecated)

setKeepScreenOn(isKeepScreenOn: boolean): Promise<void>

设置屏幕是否为常亮状态,使用Promise异步回调。

从 API version 6开始支持,从API version 9开始废弃,推荐使用setWindowKeepScreenOn()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isKeepScreenOn boolean 是 设置屏幕是否为常亮状态。true表示常亮;false表示不常亮。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isKeepScreenOn: boolean = true;
let promise = windowClass.setKeepScreenOn(isKeepScreenOn);
promise.then(() => {
  console.info('Succeeded in setting the screen to be always on.');
}).catch((err: BusinessError) => {
  console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setOutsideTouchable(deprecated)

setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): void

设置是否允许可点击子窗口之外的区域,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃。

从 API version 9开始,系统默认允许点击子窗口之外的区域,此接口不再支持使用,也不再提供替代接口。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
touchable boolean 是 设置是否可点击。true表示可点击;false表示不可点击。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

windowClass.setOutsideTouchable(true, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the area to be touchable.');
});

[h2]setOutsideTouchable(deprecated)

setOutsideTouchable(touchable: boolean): Promise<void>

设置是否允许可点击子窗口之外的区域,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃。

从 API version 9开始,系统默认允许点击子窗口之外的区域,此接口不再支持使用,也不再提供替代接口。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
touchable boolean 是 设置是否可点击。true表示可点击;false表示不可点击。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let promise = windowClass.setOutsideTouchable(true);
promise.then(() => {
  console.info('Succeeded in setting the area to be touchable.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`);
});

[h2]setPrivacyMode(deprecated)

setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void

设置窗口是否为隐私模式,使用callback异步回调。设置为隐私模式的窗口,窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowPrivacyMode()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isPrivacyMode boolean 是 窗口是否为隐私模式。true表示模式开启;false表示模式关闭。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isPrivacyMode: boolean = true;
windowClass.setPrivacyMode(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.');
});

[h2]setPrivacyMode(deprecated)

setPrivacyMode(isPrivacyMode: boolean): Promise<void>

设置窗口是否为隐私模式,使用Promise异步回调。设置为隐私模式的窗口,窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowPrivacyMode()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isPrivacyMode boolean 是 窗口是否为隐私模式。true表示模式开启;false表示模式关闭。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isPrivacyMode: boolean = true;
let promise = windowClass.setPrivacyMode(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}`);
});

[h2]setTouchable(deprecated)

setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void

设置窗口是否为可触状态,使用callback异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowTouchable()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isTouchable boolean 是 窗口是否为可触状态。true表示可触;false表示不可触。
callback AsyncCallback<void> 是 回调函数。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isTouchable = true;
windowClass.setTouchable(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.');
});

[h2]setTouchable(deprecated)

setTouchable(isTouchable: boolean): Promise<void>

设置窗口是否为可触状态,使用Promise异步回调。

从 API version 7开始支持,从API version 9开始废弃,推荐使用setWindowTouchable()。

系统能力: SystemCapability.WindowManager.WindowManager.Core

参数:

参数名 类型 必填 说明
isTouchable boolean 是 窗口是否为可触状态。true表示可触;false表示不可触。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

let isTouchable = true;
let promise = windowClass.setTouchable(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}`);
});

WindowStageEventType9+

WindowStage生命周期。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

名称 值 说明
SHOWN 1 切到前台,例如点击应用图标启动,无论是首次启动还是从后台启动均会触发。
ACTIVE 2 获焦状态,例如应用窗口处理点击事件后的状态、应用启动后的状态。
INACTIVE 3 失焦状态,例如打开新应用或点击其他窗口后,原获焦窗口的状态。
HIDDEN 4 切到后台,例如应用上滑退出、应用窗口关闭。
RESUMED11+ 5 前台可交互状态,例如应用打开后,可以与用户交互的状态。
PAUSED11+ 6 前台不可交互状态,例如从屏幕底部上划,应用进入到多任务界面后的状态。

SubWindowOptions11+

子窗口创建参数。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

名称 类型 只读 可选 说明
title string 否 否 子窗口标题。标题显示区域最右端不超过系统三键区域最左端,超过部分以省略号表示。
decorEnabled boolean 否 否 子窗口是否显示装饰。true表示子窗口显示装饰,false表示子窗口不显示装饰。
isModal12+ boolean 否 是 子窗口是否启用模态属性。true表示子窗口启用模态属性,其父级窗口不能响应用户操作,false表示子窗口禁用模态属性,其父级窗口能响应用户操作。不设置,则默认为false。

WindowStage9+

窗口管理器。管理各个基本窗口单元,即Window实例。

下列API示例中都需在onWindowStageCreate()函数中使用WindowStage的实例调用对应方法。

[h2]getMainWindow9+

getMainWindow(callback: AsyncCallback<Window>): void

获取该WindowStage实例下的主窗口,使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
callback AsyncCallback<Window> 是 回调函数。返回当前WindowStage下的主窗口对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('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;
      console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
    });
  }
};

[h2]getMainWindow9+

getMainWindow(): Promise<Window>

获取该WindowStage实例下的主窗口,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前WindowStage下的主窗口对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    let promise = windowStage.getMainWindow();
    promise.then((data) => {
      windowClass = data;
      console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
    }).catch((err: BusinessError) => {
      console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
    });
  }
};

[h2]getMainWindowSync9+

getMainWindowSync(): Window

获取该WindowStage实例下的主窗口。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
Window 返回当前WindowStage下的主窗口对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    try {
      let windowClass = windowStage.getMainWindowSync();
    } catch (exception) {
      console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

[h2]createSubWindow9+

createSubWindow(name: string, callback: AsyncCallback<Window>): void

创建该WindowStage实例下的子窗口,使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 子窗口的名字。
callback AsyncCallback<Window> 是 回调函数。返回当前WindowStage下的子窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: Incorrect parameter types.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    try {
      windowStage.createSubWindow('mySubWindow', (err: BusinessError, data) => {
        const errCode: number = err.code;
        if (errCode) {
          console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        windowClass = data;
        console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
        if (!windowClass) {
          console.info('Failed to load the content. Cause: windowClass is null');
        }
        else {
          (windowClass as window.Window).resize(500, 1000);
        }
      });
    } catch (exception) {
      console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

[h2]createSubWindow9+

createSubWindow(name: string): Promise<Window>

创建该WindowStage实例下的子窗口,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 子窗口的名字。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前WindowStage下的子窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: Incorrect parameter types.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    try {
      let promise = windowStage.createSubWindow('mySubWindow');
      promise.then((data) => {
        windowClass = data;
        console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
      }).catch((err: BusinessError) => {
        console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

[h2]createSubWindowWithOptions11+

createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window>

创建该WindowStage实例下的子窗口,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
name string 是 子窗口的名字。
options SubWindowOptions 是 子窗口参数。

返回值:

类型 说明
Promise<Window> Promise对象。返回当前WindowStage下创建的子窗口对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: Incorrect parameter types.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    let windowClass: window.Window | undefined = undefined;
    try {
      let options : window.SubWindowOptions = {
        title: 'title',
        decorEnabled: true
      };
      let promise = windowStage.createSubWindowWithOptions('mySubWindow', options);
      promise.then((data) => {
        windowClass = data;
        console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
      }).catch((err: BusinessError) => {
        console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

[h2]getSubWindow9+

getSubWindow(callback: AsyncCallback<Array<Window>>): void

获取该WindowStage实例下的所有子窗口,使用callback异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
callback AsyncCallback<Array<Window>> 是 回调函数。返回当前WindowStage下的所有子窗口对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    let windowClass: window.Window[] = [];
    windowStage.getSubWindow((err: BusinessError, data) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      windowClass = data;
      console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data));
    });
  }
};

[h2]getSubWindow9+

getSubWindow(): Promise<Array<Window>>

获取该WindowStage实例下的所有子窗口,使用Promise异步回调。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

返回值:

类型 说明
Promise<Array<Window>> Promise对象。返回当前WindowStage下的所有子窗口对象。

错误码:

以下错误码的详细介绍请参见窗口错误码。

错误码ID 错误信息
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    let windowClass: window.Window[] = [];
    let promise = windowStage.getSubWindow();
    promise.then((data) => {
      windowClass = data;
      console.info('Succeeded in obtaining the subwindow. Data: ' + JSON.stringify(data));
    }).catch((err: BusinessError) => {
      console.error(`Failed to obtain the subwindow. Cause code: ${err.code}, message: ${err.message}`);
    });
  }
};

[h2]loadContent9+

loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void

为当前WindowStage的主窗口加载具体页面内容,通过LocalStorage传递状态属性给加载的页面,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,该路径需添加到工程的main_pages.json文件中。
storage LocalStorage 是 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  storage: LocalStorage = new LocalStorage();

  onWindowStageCreate(windowStage: window.WindowStage) {
    this.storage.setOrCreate('storageSimpleProp', 121);
    console.log('onWindowStageCreate');
    try {
      windowStage.loadContent('pages/page2', this.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.');
      });
    } catch (exception) {
      console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

[h2]loadContent9+

loadContent(path: string, storage?: LocalStorage): Promise<void>

为当前WindowStage的主窗口加载具体页面内容,通过LocalStorage传递状态属性给加载的页面,使用Promise异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,该路径需添加到工程的main_pages.json文件中。
storage LocalStorage 否 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  storage: LocalStorage = new LocalStorage();

  onWindowStageCreate(windowStage: window.WindowStage) {
    this.storage.setOrCreate('storageSimpleProp', 121);
    console.log('onWindowStageCreate');
    try {
      let promise = windowStage.loadContent('pages/page2', this.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}`);
      });
    } catch (exception) {
      console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
    }
    ;
  }
};

[h2]loadContent9+

loadContent(path: string, callback: AsyncCallback<void>): void

为当前WindowStage的主窗口加载具体页面内容,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
path string 是 要加载到窗口中的页面内容的路径,该路径需添加到工程的main_pages.json文件中。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    try {
      windowStage.loadContent('pages/page2', (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}`);
    }
  }
};

[h2]loadContentByName11+

loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void

为当前WindowStage加载命名路由页面,通过LocalStorage传递状态属性给加载的页面,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 命名路由页面的名称。
storage LocalStorage 是 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // 导入命名路由页面

export default class EntryAbility extends UIAbility {
  // ...

  storage: LocalStorage = new LocalStorage();

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    this.storage.setOrCreate('storageSimpleProp', 121);
    try {
      windowStage.loadContentByName(Index.entryName, this.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.');
      });
    } catch (exception) {
      console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

[h2]loadContentByName11+

loadContentByName(name: string, callback: AsyncCallback<void>): void

为当前WindowStage加载命名路由页面,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 命名路由页面的名称。
callback AsyncCallback<void> 是 回调函数。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // 导入命名路由页面

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    try {
      windowStage.loadContentByName(Index.entryName, (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}`);
    }
  }
};
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName})
@Component
export struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

[h2]loadContentByName11+

loadContentByName(name: string, storage?: LocalStorage): Promise<void>;

为当前WindowStage加载命名路由页面,通过LocalStorage传递状态属性给加载的页面,使用promise异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
name string 是 命名路由页面的名称。
storage LocalStorage 否 页面级UI状态存储单元,这里用于为加载到窗口的页面内容传递状态属性。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import * as Index from '../pages/Index'; // 导入命名路由页面

export default class EntryAbility extends UIAbility {
  // ...

  storage: LocalStorage = new LocalStorage();

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    this.storage.setOrCreate('storageSimpleProp', 121);
    try {
      let promise = windowStage.loadContentByName(Index.entryName, this.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}`);
      });
    } catch (exception) {
      console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};
// ets/pages/Index.ets
export const entryName : string = 'Index';
@Entry({routeName: entryName, storage : LocalStorage.getShared()})
@Component
export struct Index {
  @State message: string = 'Hello World'
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
      }
      .width('100%')
    }
    .height('100%')
  }
}

[h2]on('windowStageEvent')9+

on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void

开启WindowStage生命周期变化的监听。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
eventType string 是 监听事件,固定为'windowStageEvent',即WindowStage生命周期变化事件。
callback Callback<WindowStageEventType> 是 回调函数。返回当前的WindowStage生命周期状态。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    try {
      windowStage.on('windowStageEvent', (data) => {
        console.info('Succeeded in enabling the listener for window stage event changes. Data: ' +
        JSON.stringify(data));
      });
    } catch (exception) {
      console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

[h2]off('windowStageEvent')9+

off(eventType: 'windowStageEvent', callback?: Callback<WindowStageEventType>): void

关闭WindowStage生命周期变化的监听。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.WindowManager.WindowManager.Core

元服务API: 从API version 11开始,该接口支持在元服务中使用。

参数:

参数名 类型 必填 说明
eventType string 是 监听事件,固定为'windowStageEvent',即WindowStage生命周期变化事件。
callback Callback<WindowStageEventType> 否 回调函数。返回当前的WindowStage生命周期状态。若传入参数,则关闭该监听。若未传入参数,则关闭所有WindowStage生命周期变化的监听。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码ID 错误信息
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    const callback = (windowStageEventType: window.WindowStageEventType) => {
      // ...
    }
    try {
      windowStage.on('windowStageEvent', callback);
    } catch (exception) {
      console.error(`Failed to enable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`);
    }
    try {
      windowStage.off('windowStageEvent', callback);
      // 如果通过on开启多个callback进行监听,同时关闭所有监听:
      windowStage.off('windowStageEvent');
    } catch (exception) {
      console.error(`Failed to disable the listener for window stage event changes. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

[h2]setDefaultDensityEnabled12+

setDefaultDensityEnabled(enabled: boolean): void

设置应用是否使用系统默认Density。

不调用此接口进行设置,则表示不使用系统默认Density,即窗口会跟随系统显示大小变化重新布局。

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

系统能力: SystemCapability.Window.SessionManager

参数:

参数名 类型 必填 说明
enabled boolean 是 是否设置应用使用系统默认Density。true表示使用系统默认Density,窗口不跟随系统显示大小变化重新布局;false表示不使用系统默认Density,窗口跟随系统显示大小变化重新布局。

错误码:

以下错误码的详细介绍请参见通用错误码和窗口错误码。

错误码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.
1300005 This window stage is abnormal.

示例:

// EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  // ...

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('onWindowStageCreate');
    try {
      windowStage.setDefaultDensityEnabled(true);
    } catch (exception) {
      console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};