窗口提供管理窗口的一些基础能力,包括对当前窗口的创建、销毁、各属性设置,以及对各窗口间的管理调度。
该模块提供以下窗口相关的常用功能:
本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
窗口类型枚举。
系统能力: 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开始,该接口支持在元服务中使用。 |
创建子窗口或系统窗口时的参数。
元服务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 |
窗口内容需要规避区域的类型枚举。
系统能力: 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 | 表示导航条区域。 |
状态栏、导航栏的属性。在设置窗口级状态栏、导航栏属性时使用。
元服务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。 |
状态栏的属性。在设置页面级状态栏属性时使用。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.WindowManager.WindowManager.Core
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| statusBarContentColor | string | 是 | 是 | 状态栏文字颜色。默认值:'#E5FFFFFF'。 |
窗口显示方向类型枚举。
| 名称 | 值 | 说明 |
|---|---|---|
| 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。 |
窗口矩形区域。
系统能力: SystemCapability.WindowManager.WindowManager.Core
元服务API: 从API version 11开始,该接口支持在元服务中使用。
| 名称 | 类型 | 可读 | 可写 | 说明 |
|---|---|---|---|---|
| left | number | 是 | 是 | 矩形区域的左边界,单位为px,该参数为整数。 |
| top | number | 是 | 是 | 矩形区域的上边界,单位为px,该参数应为整数。 |
| width | number | 是 | 是 | 矩形区域的宽度,单位为px,该参数应为整数。 |
| height | number | 是 | 是 | 矩形区域的高度,单位为px,该参数应为整数。 |
窗口内容规避区域。如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。在规避区无法响应用户点击事件。
除此之外还需注意规避区域的如下约束,具体为:
底部手势区域中非导航条区域支持点击、长按事件透传,不支持拖入。
左右侧边手势区域支持点击、长按以及上下滑动事件透传,不支持拖入。
导航条区域支持长按、点击、拖入事件响应,不支持事件向下透传。
系统能力: SystemCapability.WindowManager.WindowManager.Core
元服务API: 从API version 11开始,该接口支持在元服务中使用。
窗口大小。
系统能力: SystemCapability.WindowManager.WindowManager.Core
元服务API: 从API version 11开始,该接口支持在元服务中使用。
| 名称 | 类型 | 可读 | 可写 | 说明 |
|---|---|---|---|---|
| width | number | 是 | 是 | 窗口宽度,单位为px,该参数应为整数。 |
| height | number | 是 | 是 | 窗口高度,单位为px,该参数应为整数。 |
窗口矩形(窗口位置及窗口大小)变化的原因。
系统能力: SystemCapability.Window.SessionManager
元服务API: 从API version 12开始,该接口支持在元服务中使用。
| 名称 | 值 | 说明 |
|---|---|---|
| UNDEFINED | 0 | 默认值。 |
| MAXIMIZE | 1 | 窗口最大化。 |
| RECOVER | 2 | 窗口恢复到上一次的状态。 |
| MOVE | 3 | 窗口拖拽移动。 |
| DRAG | 4 | 窗口拖拽缩放。 |
| DRAG_START | 5 | 窗口开始拖拽缩放。 |
| DRAG_END | 6 | 窗口结束拖拽缩放。 |
窗口矩形(窗口位置及窗口大小)变化返回的值及变化原因。
系统能力: SystemCapability.Window.SessionManager
元服务API: 从API version 12开始,该接口支持在元服务中使用。
| 名称 | 类型 | 可读 | 可写 | 说明 |
|---|---|---|---|---|
| rect | Rect | 是 | 是 | 窗口矩形变化后的值。 |
| reason | RectChangeReason | 是 | 是 | 窗口矩形变化的原因。 |
系统规避区变化后返回当前规避区域以及规避区域类型。
系统能力: SystemCapability.WindowManager.WindowManager.Core
元服务API: 从API version 12开始,该接口支持在元服务中使用。
| 名称 | 类型 | 可读 | 可写 | 说明 |
|---|---|---|---|---|
| type | AvoidAreaType | 是 | 是 | 系统规避区变化后返回的规避区域类型。 |
| area | AvoidArea | 是 | 是 | 系统规避区变化后返回的规避区域。 |
窗口属性。
系统能力: 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开始,该接口支持在元服务中使用。 |
色域模式。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.WindowManager.WindowManager.Core
| 名称 | 值 | 说明 |
|---|---|---|
| DEFAULT | 0 | 默认SRGB色域模式。 |
| WIDE_GAMUT | 1 | 广色域模式。 |
窗口生命周期。
元服务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。 |
窗口尺寸限制参数。可以通过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,上限值为系统限定的最小高度。 |
窗口模式枚举。
元服务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分屏模式。 |
标题栏上的最小化、最大化、关闭按钮矩形区域,该区域位置坐标相对窗口右上角。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Window.SessionManager
| 名称 | 类型 | 可读 | 可写 | 说明 |
|---|---|---|---|---|
| right | number | 是 | 是 | 矩形区域的右边界,单位为vp,该参数为整数。 |
| top | number | 是 | 是 | 矩形区域的上边界,单位为vp,该参数为整数。 |
| width | number | 是 | 是 | 矩形区域的宽度,单位为vp,该参数为整数。 |
| height | number | 是 | 是 | 矩形区域的高度,单位为vp,该参数为整数。 |
窗口最大化时的布局枚举。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Window.SessionManager
| 名称 | 值 | 说明 |
|---|---|---|
| FOLLOW_APP_IMMERSIVE_SETTING | 0 | 最大化时,跟随应用app当前设置的沉浸式布局。 |
| EXIT_IMMERSIVE | 1 | 最大化时,如果当前窗口设置了沉浸式布局会退出沉浸式布局。 |
| ENTER_IMMERSIVE | 2 | 最大化时,进入沉浸式布局。 |
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}`);
} 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}`);
} 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}`);
} 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}`);
}
}
} 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}`);
}
}
} 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}`);
}
}
} create(id: string, type: WindowType, callback: AsyncCallback<Window>): void
创建子窗口,使用callback异步回调。
模型约束: 此接口仅可在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));
}); create(id: string, type: WindowType): Promise<Window>
创建子窗口,使用Promise异步回调。
模型约束: 此接口仅可在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}`);
}); create(ctx: BaseContext, id: string, type: WindowType, callback: AsyncCallback<Window>): void
创建系统窗口,使用callback异步回调。
系统能力: 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);
}); create(ctx: BaseContext, id: string, type: WindowType): Promise<Window>
创建系统窗口,使用Promise异步回调。
系统能力: 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}`);
}); find(id: string, callback: AsyncCallback<Window>): void
查找id所对应的窗口,使用callback异步回调。
系统能力: 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));
}); find(id: string): Promise<Window>
查找id所对应的窗口,使用Promise异步回调。
系统能力: 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}`);
}); getTopWindow(callback: AsyncCallback<Window>): void
获取当前应用内最后显示的窗口,使用callback异步回调。
模型约束: 此接口仅可在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));
}); getTopWindow(): Promise<Window>
获取当前应用内最后显示的窗口,使用Promise异步回调。
模型约束: 此接口仅可在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}`);
}); getTopWindow(ctx: BaseContext, callback: AsyncCallback<Window>): void
获取当前应用内最后显示的窗口,使用callback异步回调。
系统能力: 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}`);
}
}
} getTopWindow(ctx: BaseContext): Promise<Window>
获取当前应用内最后显示的窗口,使用Promise异步回调。
系统能力: 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}`);
});
}
} type SpecificSystemBar = 'status' | 'navigation' | 'navigationIndicator'
当前支持显示或隐藏的系统栏类型。
系统能力: SystemCapability.Window.SessionManager
元服务API: 从API version 11开始,该接口支持在元服务中使用。
| 类型 | 说明 |
|---|---|
| 'status' | 状态栏。 |
| 'navigation' | 三键导航栏。 |
| 'navigationIndicator' | 底部导航条。 |
当前窗口实例,窗口管理器管理的基本单元。
下列API示例中都需先使用getLastWindow()、createWindow()、findWindow()中的任一方法获取到Window实例(windowClass),再通过此实例调用对应方法。
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.');
}); 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}`);
}); 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.');
}); 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}`);
}); 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
}
});
}
} 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}`);
} 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}`);
} 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}`);
}
});
}
} 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}`);
}
});
}
} 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}`);
}
});
}
} 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}`);
}
});
}
}; 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}`);
}
});
}
} 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}`);
}
});
}
} 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}`);
}
});
}
}; 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();
});
});
}
}; 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}`);
} 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}`);
} 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.');
}); 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}`);
}); 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%')
}
} 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%')
}
} 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%')
}
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
}
}); 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}`);
}
}) 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}`);
}
}) 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));
}); 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'); 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}`);
} 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}`);
} 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));
}); 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}`);
}); 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}`);
} 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}`);
} getWindowColorSpace(): ColorSpace
获取当前窗口色域模式。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.WindowManager.WindowManager.Core
返回值:
| 类型 | 说明 |
|---|---|
| ColorSpace | 当前色域模式。 |
错误码:
以下错误码的详细介绍请参见窗口错误码。
| 错误码ID | 错误信息 |
|---|---|
| 1300002 | This window state is abnormal. |
示例:
let colorSpace = windowClass.getWindowColorSpace();
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}`);
};
}); 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}`);
}
});
}
} 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}`);
}
});
}
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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使用完后及时释放内存
}); 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}`);
}); 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}`);
}
}
} 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}`);
}
}
} 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}`);
}
}
} 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}`);
}
}
} minimize(callback: AsyncCallback<void>): void
此接口根据调用对象不同,实现不同的功能:
当调用对象为主窗口时,实现最小化功能,可在Dock栏中还原。
当调用对象为子窗口时,实现隐藏功能,不可在Dock栏中还原,可以使用showWindow()进行还原。悬浮窗类型的窗口对象,调用此接口会报1300002错误码。
使用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.');
}); minimize(): Promise<void>
此接口根据调用对象不同,实现不同的功能:
当调用对象为主窗口时,实现最小化功能,可在Dock栏中还原。
当调用对象为子窗口时,实现隐藏功能,不可在Dock栏中还原,可以使用showWindow()进行还原。悬浮窗类型的窗口对象,调用此接口会报1300002错误码。
使用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}`);
}); 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}`);
});
});
}
}; 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}`);
});
});
}
} 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}`);
} 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}`);
} 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}`);
} 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}`);
} 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}`);
}
}); 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}`);
}
}
} 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}`);
}
}) 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}`);
}
}) 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}`);
}
});
}
} 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}`);
} 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}`);
} 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}`);
} 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}`);
});
});
}
} 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}`);
});
});
}
} 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;
}
} setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void
设置主窗口三键导航栏、状态栏的属性,使用callback异步回调,
该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。
子窗口调用后不生效。
系统能力: 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}`);
}
});
}
} setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void
设置主窗口三键导航栏、状态栏、底部导航条的可见模式,状态栏与底部导航条通过status控制、三键导航栏通过navigation控制,使用callback异步回调。从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'];不设置,则默认不显示。 |
| 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}`);
}
});
}
} setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void
设置主窗口或子窗口的布局是否为沉浸式布局,使用callback异步回调。
沉浸式布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。
非沉浸式布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。
系统能力: 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}`);
}
});
}
} show(callback: AsyncCallback<void>): void
显示当前窗口,使用callback异步回调。
系统能力: 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.');
}); show(): Promise<void>
显示当前窗口,使用Promise异步回调。
系统能力: 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}`);
}); destroy(callback: AsyncCallback<void>): void
销毁当前窗口,使用callback异步回调。
系统能力: 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.');
}); destroy(): Promise<void>
销毁当前窗口,使用Promise异步回调。
系统能力: 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}`);
}); moveTo(x: number, y: number, callback: AsyncCallback<void>): void
移动窗口位置,使用callback异步回调。
全屏模式窗口不支持该操作。
系统能力: 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.');
}); moveTo(x: number, y: number): Promise<void>
移动窗口位置,使用Promise异步回调。
全屏模式窗口不支持该操作。
系统能力: 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}`);
}); resetSize(width: number, height: number, callback: AsyncCallback<void>): void
改变当前窗口大小,使用callback异步回调。
应用主窗口与子窗口存在大小限制,默认宽度范围:[320, 1920],默认高度范围:[240, 1920],单位为vp。
应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置,配置后的最小宽度与最小高度以产品段配置值为准,具体尺寸限制范围可以通过getWindowLimits接口进行查询。
系统窗口存在大小限制,宽度范围:(0, 1920],高度范围:(0, 1920],单位为vp。
设置的宽度与高度受到此约束限制,规则:
若所设置的窗口宽/高尺寸小于窗口最小宽/高限值,则窗口最小宽/高限值生效;
若所设置的窗口宽/高尺寸大于窗口最大宽/高限值,则窗口最大宽/高限值生效。
全屏模式窗口不支持该操作。
系统能力: 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.');
}); resetSize(width: number, height: number): Promise<void>
改变当前窗口大小,使用Promise异步回调。
应用主窗口与子窗口存在大小限制,默认宽度范围:[320, 1920],默认高度范围:[240, 1920],单位为vp。
应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置,配置后的最小宽度与最小高度以产品段配置值为准,具体尺寸限制范围可以通过getWindowLimits接口进行查询。
系统窗口存在大小限制,宽度范围:(0, 1920],高度范围:(0, 1920],单位为vp。
设置的宽度与高度受到此约束限制,规则:
若所设置的窗口宽/高尺寸小于窗口最小宽/高限值,则窗口最小宽/高限值生效;
若所设置的窗口宽/高尺寸大于窗口最大宽/高限值,则窗口最大宽/高限值生效。
全屏模式窗口不支持该操作。
系统能力: 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}`);
}); getProperties(callback: AsyncCallback<WindowProperties>): void
获取当前窗口的属性,使用callback异步回调,返回WindowProperties。
系统能力: 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));
}); getProperties(): Promise<WindowProperties>
获取当前窗口的属性,使用Promise异步回调,返回WindowProperties。
系统能力: 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}`);
}); getAvoidArea(type: AvoidAreaType, callback: AsyncCallback<AvoidArea>): void
获取当前窗口内容规避的区域;如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。
系统能力: 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));
}); getAvoidArea(type: AvoidAreaType): Promise<AvoidArea>
获取当前窗口内容规避的区域;如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时,需要窗口内容避让的区域。
系统能力: 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}`);
}); 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.');
});
});
}
} 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}`);
});
});
}
} setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void
设置主窗口或子窗口的布局是否为沉浸式布局,使用callback异步回调。
沉浸式布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。
非沉浸式布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。
系统能力: 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.');
});
});
}
} setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void>
设置主窗口或子窗口的布局是否为沉浸式布局,使用Promise异步回调。
沉浸式布局生效时,布局不避让状态栏与导航栏,组件可能产生与其重叠的情况。
非沉浸式布局生效时,布局避让状态栏与导航栏,组件不会与其重叠。
系统能力: 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}`);
});
});
}
} setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void
设置主窗口三键导航栏、状态栏、底部导航条的可见模式,状态栏与底部导航条通过status控制、三键导航栏通过navigation控制,使用callback异步回调。从API version 12开始,
该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。
调用生效后返回并不表示三键导航栏、状态栏和底部导航条的显示或隐藏已完成。子窗口调用后不生效。
系统能力: 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.');
});
});
}
} setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void>
设置主窗口三键导航栏、状态栏、底部导航条的可见模式,状态栏与底部导航条通过status控制、三键导航栏通过navigation控制,使用Promise异步回调。从API version 12开始,
该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。
调用生效后返回并不表示三键导航栏、状态栏和底部导航条的显示或隐藏已完成。子窗口调用后不生效。
系统能力: 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}`);
});
});
}
} setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void
设置主窗口三键导航栏、状态栏的属性,使用callback异步回调,
该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。
子窗口调用后不生效。
系统能力: 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.');
});
});
}
} setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void>
设置主窗口三键导航栏、状态栏的属性,使用Promise异步回调,
该接口在2in1设备上调用不生效,其他设备在分屏模式(即窗口模式为window.WindowStatusType.SPLIT_SCREEN)、自由悬浮窗口模式(即窗口模式为window.WindowStatusType.FLOATING)、自由多窗模式(可点击设备控制中心中的自由多窗按钮开启)下调用不会立刻生效,只有进入全屏主窗口才会生效。
子窗口调用后不生效。
系统能力: 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}`);
});
});
}
} loadContent(path: string, callback: AsyncCallback<void>): void
为当前窗口加载具体页面内容,使用callback异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。
系统能力: 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.');
}); loadContent(path: string): Promise<void>
为当前窗口加载具体页面内容,使用Promise异步回调。建议在UIAbility启动过程中使用该接口,多次调用该接口会先销毁旧的页面内容(即UIContent)再加载新的页面内容,请谨慎使用。
系统能力: 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}`);
}); isShowing(callback: AsyncCallback<boolean>): void
判断当前窗口是否已显示,使用callback异步回调。
系统能力: 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));
}); isShowing(): Promise<boolean>
判断当前窗口是否已显示,使用Promise异步回调。
系统能力: 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}`);
}); on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void
开启当前窗口系统规避区变化的监听。
系统能力: 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));
}); off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void
关闭当前窗口系统规避区变化的监听。
系统能力: 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'); isSupportWideGamut(callback: AsyncCallback<boolean>): void
判断当前窗口是否支持广色域模式,使用callback异步回调。
系统能力: 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));
}); isSupportWideGamut(): Promise<boolean>
判断当前窗口是否支持广色域模式,使用Promise异步回调。
系统能力: 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}`);
}); setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void
设置当前窗口为广色域模式或默认色域模式,使用callback异步回调。
系统能力: 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.');
}); setColorSpace(colorSpace:ColorSpace): Promise<void>
设置当前窗口为广色域模式或默认色域模式,使用Promise异步回调。
系统能力: 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}`);
}); getColorSpace(callback: AsyncCallback<ColorSpace>): void
获取当前窗口色域模式,使用callback异步回调。
系统能力: 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));
}); getColorSpace(): Promise<ColorSpace>
获取当前窗口色域模式,使用Promise异步回调。
系统能力: 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}`);
}); setBackgroundColor(color: string, callback: AsyncCallback<void>): void
设置窗口的背景色,使用callback异步回调。Stage模型下,该接口需要在loadContent()或setUIContent()调用生效后使用。
系统能力: 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.');
}); setBackgroundColor(color: string): Promise<void>
设置窗口的背景色,使用Promise异步回调。Stage模型下,该接口需要在loadContent()或setUIContent()调用生效后使用。
系统能力: 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}`);
}); setBrightness(brightness: number, callback: AsyncCallback<void>): void
允许应用窗口设置屏幕亮度值,使用callback异步回调。
当前屏幕亮度规格:窗口设置屏幕亮度生效时,控制中心不可以调整系统屏幕亮度,窗口恢复默认系统亮度之后,控制中心可以调整系统屏幕亮度。
系统能力: 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.');
}); setBrightness(brightness: number): Promise<void>
允许应用窗口设置屏幕亮度值,使用Promise异步回调。
当前屏幕亮度规格:窗口设置屏幕亮度生效时,控制中心不可以调整系统屏幕亮度,窗口恢复默认系统亮度之后,控制中心可以调整系统屏幕亮度。
系统能力: 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}`);
}); 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.');
}); 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}`);
}); setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void
设置使用点击或其他方式使该窗口获焦的场景时,该窗口是否支持窗口焦点从操作前的获焦窗口切换到该窗口,使用callback异步回调。
系统能力: 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.');
}); setFocusable(isFocusable: boolean): Promise<void>
设置使用点击或其他方式使该窗口获焦的场景时,该窗口是否支持窗口焦点从点击前的获焦窗口切换到该窗口,使用Promise异步回调。
系统能力: 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}`);
}); setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void
设置屏幕是否为常亮状态,使用callback异步回调。
系统能力: 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.');
}); setKeepScreenOn(isKeepScreenOn: boolean): Promise<void>
设置屏幕是否为常亮状态,使用Promise异步回调。
系统能力: 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}`);
}); 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.');
}); 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}`);
}); setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void
设置窗口是否为隐私模式,使用callback异步回调。设置为隐私模式的窗口,窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。
系统能力: 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.');
}); setPrivacyMode(isPrivacyMode: boolean): Promise<void>
设置窗口是否为隐私模式,使用Promise异步回调。设置为隐私模式的窗口,窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。
系统能力: 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}`);
}); setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void
设置窗口是否为可触状态,使用callback异步回调。
系统能力: 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.');
}); setTouchable(isTouchable: boolean): Promise<void>
设置窗口是否为可触状态,使用Promise异步回调。
系统能力: 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}`);
}); WindowStage生命周期。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.WindowManager.WindowManager.Core
元服务API: 从API version 11开始,该接口支持在元服务中使用。
| 名称 | 值 | 说明 |
|---|---|---|
| SHOWN | 1 | 切到前台,例如点击应用图标启动,无论是首次启动还是从后台启动均会触发。 |
| ACTIVE | 2 | 获焦状态,例如应用窗口处理点击事件后的状态、应用启动后的状态。 |
| INACTIVE | 3 | 失焦状态,例如打开新应用或点击其他窗口后,原获焦窗口的状态。 |
| HIDDEN | 4 | 切到后台,例如应用上滑退出、应用窗口关闭。 |
| RESUMED11+ | 5 | 前台可交互状态,例如应用打开后,可以与用户交互的状态。 |
| PAUSED11+ | 6 | 前台不可交互状态,例如从屏幕底部上划,应用进入到多任务界面后的状态。 |
子窗口创建参数。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Window.SessionManager
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| title | string | 否 | 否 | 子窗口标题。标题显示区域最右端不超过系统三键区域最左端,超过部分以省略号表示。 |
| decorEnabled | boolean | 否 | 否 | 子窗口是否显示装饰。true表示子窗口显示装饰,false表示子窗口不显示装饰。 |
| isModal12+ | boolean | 否 | 是 | 子窗口是否启用模态属性。true表示子窗口启用模态属性,其父级窗口不能响应用户操作,false表示子窗口禁用模态属性,其父级窗口能响应用户操作。不设置,则默认为false。 |
窗口管理器。管理各个基本窗口单元,即Window实例。
下列API示例中都需在onWindowStageCreate()函数中使用WindowStage的实例调用对应方法。
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));
});
}
}; 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}`);
});
}
}; 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}`);
}
}
}; 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}`);
}
}
}; 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}`);
}
}
}; 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}`);
}
}
}; 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));
});
}
}; 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}`);
});
}
}; 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}`);
}
}
}; 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}`);
}
;
}
}; 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}`);
}
}
}; 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%')
}
} 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%')
}
} 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%')
}
} 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}`);
}
}
}; 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}`);
}
}
}; 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}`);
}
}
};