0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
ge-yafangge-yafangupdate docs
aa0a67ae创建于 3 天前历史提交

@ohos.window (窗口)(系统接口)

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

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

  • Window：当前窗口实例，窗口管理器管理的基本单元。
  • WindowStage：窗口管理器。管理各个基本窗口单元。

说明：

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

  • 当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.window (窗口)。

  • 针对系统能力SystemCapability.Window.SessionManager，请先使用canIUse()接口判断当前设备是否支持此syscap及对应接口。

导入模块

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

WindowType7+

窗口类型枚举。

名称 值 说明
TYPE_INPUT_METHOD(deprecated) 2 表示输入法窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
说明： 从API version 9开始支持，从API version 13开始废弃，无替代窗口类型，输入法相关控制都请调用输入法框架侧接口执行。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_STATUS_BAR9+ 3 表示状态栏窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_PANEL9+ 4 表示通知栏。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_KEYGUARD9+ 5 表示锁屏。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_VOLUME_OVERLAY9+ 6 表示音量条。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_NAVIGATION_BAR9+ 7 表示导航栏窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_WALLPAPER9+ 9 表示壁纸。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_DESKTOP9+ 10 表示桌面。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_LAUNCHER_RECENT9+ 11 表示多任务中心。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_LAUNCHER_DOCK9+ 12 表示桌面Dock栏。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_VOICE_INTERACTION9+ 13 表示智慧语音。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_POINTER9+ 14 表示鼠标。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_FLOAT_CAMERA9+ 15 表示相机类型悬浮窗。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_SCREENSHOT9+ 17 表示截屏窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_SYSTEM_TOAST11+ 18 表示顶层提示窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_DIVIDER11+ 19 表示分屏条。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_GLOBAL_SEARCH11+ 20 表示全局搜索窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.WindowManager.WindowManager.Core
TYPE_HANDWRITE12+ 21 表示手写笔窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.Window.SessionManager
TYPE_WALLET_SWIPE_CARD15+ 22 表示钱包刷卡窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.Window.SessionManager
TYPE_SCREEN_CONTROL15+ 23 表示锁定触控的顶层窗口，用于拦截屏幕触摸和点击事件。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.Window.SessionManager
TYPE_FLOAT_NAVIGATION17+ 24 表示悬浮的三键导航窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.Window.SessionManager
TYPE_DYNAMIC20+ 25 表示可设置窗口层级的系统窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.Window.SessionManager
TYPE_MUTISCREEN_COLLABORATION20+ 26 表示多屏协同窗口。
模型约束： 此接口仅可在Stage模型下使用。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.Window.SessionManager

Configuration9+

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

系统接口： 此接口为系统接口。

名称 类型 只读 可选 说明
zIndex20+ number 否 是 当前系统窗口的层级，仅在WindowType为TYPE_DYNAMIC时生效。
系统能力： SystemCapability.Window.SessionManager
defaultDensityEnabled20+ boolean 否 是 是否使用系统默认Density，使用系统默认Density之后，窗口不会跟随系统显示大小变化重新布局。
当创建的系统窗口设置此参数为true时，表示当前窗口使用系统默认Density，且不会受到setDefaultDensityEnabled()和setCustomDensity()设置的主窗口以及setDefaultDensityEnabled()设置的本窗口的相关影响。
当创建的系统窗口设置此参数为false时，表示当前窗口不使用系统默认Density，且会受到setDefaultDensityEnabled()和setCustomDensity()设置的主窗口以及setDefaultDensityEnabled()设置的本窗口的相关影响。
默认为false。
系统能力： SystemCapability.Window.SessionManager

WindowMode7+

窗口模式枚举。

系统接口： 此接口为系统接口。

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

名称 值 说明
UNDEFINED 1 表示APP未定义窗口模式。
FULLSCREEN 2 表示APP全屏模式。
PRIMARY 3 表示APP分屏多窗口主要模式。上下分屏时，上分屏为主要模式。左右分屏时，左分屏为主要模式。
SECONDARY 4 表示APP分屏多窗口次要模式。上下分屏时，下分屏为次要模式。左右分屏时，右分屏为次要模式。
FLOATING 5 表示APP自由悬浮形式窗口模式。

BlurStyle9+

窗口模糊类型枚举。

系统接口： 此接口为系统接口。

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

名称 值 说明
OFF 0 表示关闭模糊。
THIN 1 表示较薄的模糊类型。
REGULAR 2 表示适中的模糊类型。
THICK 3 表示较厚的模糊类型。

AnimationType20+

窗口动画类型枚举。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

名称 值 说明
FADE_IN 1 表示窗口动画类型为淡入。淡入动画在窗口显示过程中生效。

SystemBarRegionTint8+

单个导航栏或状态栏回调信息。

系统接口： 此接口为系统接口。

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

名称 类型 只读 可选 说明
type WindowType 否 否 当前属性改变的系统栏类型，仅支持类型为导航栏、状态栏的系统栏。
isEnable boolean 否 是 当前系统栏是否显示。true表示显示；false表示不显示。默认值为true。
region Rect 否 是 当前系统栏的位置及大小。默认值为{0,0,0,0}。
backgroundColor string 否 是 系统栏背景颜色，为十六进制RGB或ARGB颜色，不区分大小写，例如'#00FF00'或'#FF00FF00'。 默认值为'0x66000000'。
contentColor string 否 是 系统栏文字颜色。 默认值为'0xE5FFFFFF'。

SystemBarTintState8+

当前系统栏回调信息集合。

系统接口： 此接口为系统接口。

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

名称 类型 只读 可选 说明
displayId number 否 否 当前窗口所在屏幕id，该参数应为整数。
regionTint Array<SystemBarRegionTint> 否 否 当前已改变的所有系统栏信息。

ScaleOptions9+

缩放参数。

系统接口： 此接口为系统接口。

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

名称 类型 只读 可选 说明
x number 否 是 X轴的缩放参数。该参数为浮点数，默认值为1.0。
y number 否 是 Y轴的缩放参数。该参数为浮点数，默认值为1.0。
pivotX number 否 是 缩放中心点X轴坐标。该参数为浮点数，默认值为0.5， 取值范围[0.0, 1.0]。
pivotY number 否 是 缩放中心点Y轴坐标。该参数为浮点数，默认值为0.5， 取值范围[0.0, 1.0]。

RotateOptions9+

旋转参数。

系统接口： 此接口为系统接口。

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

名称 类型 只读 可选 说明
x number 否 是 绕X轴的旋转角度。该参数为浮点数，默认值为0.0。
y number 否 是 绕Y轴的旋转角度。该参数为浮点数，默认值为0.0。
z number 否 是 绕Z轴的旋转角度。该参数为浮点数，默认值为0.0。
pivotX number 否 是 旋转中心点X轴坐标。该参数为浮点数，默认值为0.5， 取值范围为[0.0, 1.0]。
pivotY number 否 是 旋转中心点Y轴坐标。该参数为浮点数，默认值为0.5， 取值范围为[0.0, 1.0]。

TranslateOptions9+

平移参数。

系统接口： 此接口为系统接口。

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

名称 类型 只读 可选 说明
x number 否 是 X轴的平移参数。该参数为浮点数，默认值为0.0，单位为px。
y number 否 是 Y轴的平移参数。该参数为浮点数，默认值为0.0，单位为px。
z number 否 是 Z轴的平移参数。该参数为浮点数，默认值为0.0，单位为px。

StartAnimationSystemParams20+

启动动画配置，仅对全屏应用生效。

不同应用间跳转场景不生效，仍保持系统默认动效。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在Phone设备、非自由多窗模式的Tablet设备中可正常调用，在其他设备中不生效也不报错。

名称 类型 只读 可选 说明
type AnimationType 否 否 窗口动画类型。
animationConfig WindowAnimationConfig 否 是 窗口动画参数配置。默认动画曲线为WindowAnimationCurve.LINEAR，duration为0。

WindowCreateParams20+

应用启动时的窗口参数配置。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

名称 类型 只读 可选 说明
systemAnimationParams StartAnimationSystemParams 否 是 启动动画参数配置。默认值为undefined，若不配置将保持系统默认动效。
isWindowLimitsForcible boolean 否 是 应用主窗窗口尺寸限制是否可突破系统默认限制。仅当被启动应用为系统应用时生效，否则不生效也不报错。
- true: 允许突破系统默认限制。在窗口尺寸限制计算过程中，将忽略系统默认限制，最终生效结果仍按各来源取交集计算，且优先级保持不变。 详细说明可参考WindowLimits。
- false: 不允许突破系统默认限制，窗口尺寸限制按照默认规则计算（包含系统默认限制）。
默认值为false。
起始版本： 26.0.0
模型约束： 此接口仅可在Stage模型下使用。

WindowAnchorInfo24+

一级子窗与主窗保持相对位置的窗口锚点参数信息。

系统接口： 此接口为系统接口。

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

系统能力： SystemCapability.Window.SessionManager

名称 类型 只读 可选 说明
anchorType WindowAnchor 否 否 一级子窗与主窗保持相对位置不变时的窗口锚点枚举。
offsetX number 否 是 一级子窗锚点与主窗锚点位置的X轴偏移量，单位为px。仅支持整数输入，浮点数向下取整，默认值为0。
offsetY number 否 是 一级子窗锚点与主窗锚点位置的Y轴偏移量，单位为px。仅支持整数输入，浮点数向下取整，默认值为0。

SubWindowAttachOptions24+

子窗与主窗保持相对位置不变时的参数。

系统接口： 此接口为系统接口。

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

系统能力： SystemCapability.Window.SessionManager

名称 类型 只读 可选 说明
currentLayoutMode string 否 是 子窗当前布局模式，用于控制应用定制的UI效果。若不传，则默认为空字符串。
parentWindowSizeChangeCallback Callback<Size> 否 是 父窗大小变化的回调。绑定后立即回调一次，后续父窗大小变化时通知。默认不传，无法收到父窗大小变化通知。
parentWindowStatusChangeCallback Callback<WindowStatusType> 否 是 父窗模式变化的回调。绑定后立即回调一次，后续父窗模式变化时通知。默认不传，无法收到父窗模式变化通知。
isIntersectedWidthLimit boolean 否 是 子窗与绑定主窗的宽度是否互相限制。
true表示子窗与绑定主窗的宽度不能超过两个窗口宽度限制的交集；若两者宽度限制无交集，则不互相限制。当多个子窗同时设置此参数为true时，所有参与互限的窗口（包括主窗）的宽度受全部窗口宽度限制的交集约束。
false表示子窗与绑定主窗的宽度不会互相限制。
默认为false。
起始版本： 26.0.0
isIntersectedHeightLimit boolean 否 是 子窗与绑定主窗的高度是否互相限制。
true表示子窗与绑定主窗的高度不能超过两个窗口高度限制的交集；若两者高度限制无交集，则不互相限制。当多个子窗同时设置此参数为true时，所有参与互限的窗口（包括主窗）的高度受全部窗口高度限制的交集约束。
false表示子窗与绑定主窗的高度不会互相限制。
默认为false。
起始版本： 26.0.0

WindowLayoutMode(deprecated)

窗口布局模式枚举。

说明：

从API version 9开始支持，从API version 26.0.0开始废弃，无替代接口。

系统接口： 此接口为系统接口。

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

名称 值 说明
WINDOW_LAYOUT_MODE_CASCADE(deprecated) 0 表示使用层叠布局模式。层叠布局下，多个自由窗口层叠放置，以Z轴次序区分。
说明： 从API version 9开始支持，从API version 26.0.0开始废弃，无替代枚举。
WINDOW_LAYOUT_MODE_TILE(deprecated) 1 表示使用平铺布局模式。平铺布局下，新打开的应用窗口出现在最右侧。
说明： 从API version 9开始支持，从API version 26.0.0开始废弃，无替代枚举。

window.minimizeAll9+

minimizeAll(id: number, callback: AsyncCallback<void>): void

最小化指定ID的屏幕中的所有主窗口。

系统接口： 此接口为系统接口。

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

设备行为差异： 该接口在Phone设备中可正常调用，在其他设备中返回801错误码。

参数：

参数名 类型 必填 说明
id number 是 显示设备Display的ID号，该参数仅支持整数输入。
callback AsyncCallback<void> 是 回调信息。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.
1300003 This window manager service works abnormally.

示例：

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

let displayClass: display.Display | null = null;
displayClass = display.getDefaultDisplaySync();

try {
  if (!displayClass) {
    console.error('displayClass is null');
  } else {
    window.minimizeAll(displayClass.id, (err: BusinessError) => {
      const errCode: number = err?.code;
      if (errCode) {
        console.error(`Failed to minimize all windows. Cause code: ${err?.code}, message: ${err?.message}`);
        return;
      }
      console.info('Succeeded in minimizing all windows.');
    });
  }
} catch (exception) {
  console.error(`Failed to minimize all windows. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.minimizeAll9+

minimizeAll(id: number): Promise<void>

最小化指定ID的屏幕中的所有主窗口，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

设备行为差异： 该接口在Phone设备中可正常调用，在其他设备中返回801错误码。

参数：

参数名 类型 必填 说明
id number 是 显示设备Display的ID号，该参数仅支持整数输入。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.
1300003 This window manager service works abnormally.

示例：

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

let displayClass: display.Display | null = null;
displayClass = display.getDefaultDisplaySync();

try {
  let promise = window.minimizeAll(displayClass.id);
  promise.then(() => {
    console.info('Succeeded in minimizing all windows.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to minimize all windows. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to minimize all windows. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.minimizeAllWithExclusion23+

minimizeAllWithExclusion(displayId: number, excludeWindowId: number): Promise<void>

最小化指定ID的屏幕中除指定窗口之外的所有主窗口，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

设备行为差异： 该接口在Phone设备中可正常调用，在其他设备中返回801错误码。

参数：

参数名 类型 必填 说明
displayId number 是 屏幕ID，该参数仅支持整数输入，输入浮点数会向下取整。
excludeWindowId number 是 窗口ID。可通过getWindowProperties接口获取到相关窗口属性，其中属性id即对应为窗口ID。窗口ID小于等于0，或窗口ID为null或者undefined时，会抛出401错误码；窗口ID大于0但是不存在会抛出1300002错误码；窗口ID大于0且窗口存在但是不在该屏幕，最小化指定屏幕上的所有主窗口。该参数仅支持整数输入，输入浮点数会向下取整。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal. Possible cause: 1.Window is nullptr; 2. Failed to find specified window by id.
1300003 This window manager service works abnormally.

示例：

import { display, window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let displayClass: display.Display | null = null;
displayClass = display.getDefaultDisplaySync();
let excludeWindowId = 1;

try {
  let promise = window.minimizeAllWithExclusion(displayClass.id, excludeWindowId);
  promise.then(() => {
    console.info('Succeeded in minimizing all windows.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to minimize all windows. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to minimize all windows. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.toggleShownStateForAllAppWindows9+

toggleShownStateForAllAppWindows(callback: AsyncCallback<void>): void

多窗口快速切换时隐藏或者恢复应用窗口。

系统接口： 此接口为系统接口。

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

参数：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300003 This window manager service works abnormally.

示例：

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

window.toggleShownStateForAllAppWindows((err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to toggle shown state for all app windows. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in toggling shown state for all app windows.');
});

window.toggleShownStateForAllAppWindows9+

toggleShownStateForAllAppWindows(): Promise<void>

多窗口快速切换时隐藏或者恢复应用窗口，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300003 This window manager service works abnormally.

示例：

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

let promise = window.toggleShownStateForAllAppWindows();
promise.then(() => {
  console.info('Succeeded in toggling shown state for all app windows.');
}).catch((err: BusinessError) => {
  console.error(`Failed to toggle shown state for all app windows. Cause code: ${err.code}, message: ${err.message}`);
});

window.on('systemBarTintChange')8+

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

开启状态栏、导航栏属性变化的监听。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'systemBarTintChange'，即导航栏、状态栏属性变化事件。
callback Callback<SystemBarTintState> 是 回调函数。返回当前的状态栏、导航栏信息集合。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例：

try {
  window.on('systemBarTintChange', (data) => {
    console.info('Succeeded in enabling the listener for systemBarTint changes. Data: ' + JSON.stringify(data));
  });
} catch (exception) {
  console.error(`Failed to enable the listener for systemBarTint changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.off('systemBarTintChange')8+

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

关闭状态栏、导航栏属性变化的监听。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'systemBarTintChange'，即导航栏、状态栏属性变化事件。
callback Callback<SystemBarTintState> 否 回调函数。返回当前的状态栏、导航栏信息集合。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有状态栏、导航栏属性变化的监听。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.

示例：

const callback = (systemBarTintState: window.SystemBarTintState) => {
  // ...
}
try {
  window.on('systemBarTintChange', callback);

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

window.on('gestureNavigationEnabledChange')10+

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

添加手势导航启用状态变化的监听。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'gestureNavigationEnabledChange'，即手势导航启用状态变化事件。
callback Callback<boolean> 是 回调函数。返回当前手势导航的启用状态。true表示手势导航状态变化为启用；false表示手势导航状态变化为禁用。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

try {
  window.on('gestureNavigationEnabledChange', (data) => {
    console.info(`Succeeded in enabling the listener for gesture navigation status changes. Data: ${data}`);
  });
} catch (exception) {
  console.error(`Failed to enable the listener for gesture navigation status changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.off('gestureNavigationEnabledChange')10+

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

移除手势导航启用状态变化的监听。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'gestureNavigationEnabledChange'，即手势导航启用状态变化事件。
callback Callback<boolean> 否 已注册的回调函数。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有手势导航启用状态变化的监听。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

const callback = (bool: boolean) => {
  // ...
}
try {
  window.on('gestureNavigationEnabledChange', callback);
  window.off('gestureNavigationEnabledChange', callback);
  // 如果通过on开启多个callback进行监听，同时关闭所有监听：
  window.off('gestureNavigationEnabledChange');
} catch (exception) {
  console.error(`Failed to enable or disable the listener for gesture navigation status changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.on('waterMarkFlagChange')10+

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

添加水印启用状态变化的监听。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'waterMarkFlagChange'，即水印启用状态变化事件。
callback Callback<boolean> 是 回调函数。返回当前水印的启用状态。true表示当前已启用水印；false表示当前未启用水印。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible causes: 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.

示例：

try {
  window.on('waterMarkFlagChange', (data) => {
    console.info(`Succeeded in enabling the listener for watermark flag changes. Data: ${data}`);
  });
} catch (exception) {
  console.error(`Failed to enable the listener for watermark flag changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.off('waterMarkFlagChange')10+

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

移除水印启用状态变化的监听。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'waterMarkFlagChange'，即水印启用状态变化事件。
callback Callback<boolean> 否 已注册的回调函数。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有水印启用状态变化的监听。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

const callback = (bool: boolean) => {
  // ...
}
try {
  window.on('waterMarkFlagChange', callback);
  window.off('waterMarkFlagChange', callback);
  // 如果通过on开启多个callback进行监听，同时关闭所有监听：
  window.off('waterMarkFlagChange');
} catch (exception) {
  console.error(`Failed to enable or disable the listener for watermark flag changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setGestureNavigationEnabled10+

setGestureNavigationEnabled(enable: boolean, callback: AsyncCallback<void>): void

设置手势导航启用状态。使用callback异步回调。系统出于安全的考虑，不会干预手势的禁用和恢复。应用调用本接口禁用手势后异常退出的情况下，如果想要恢复手势，需自行实现自动拉起机制并再次调用本接口恢复手势。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
enable boolean 是 设置手势导航启用状态。true表示启用手势导航；false表示禁用手势导航。当前仅禁用从屏幕下拉的手势，其他手势未禁用。
callback AsyncCallback<void> 是 回调信息。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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 {
  window.setGestureNavigationEnabled(true, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set gesture navigation enabled. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in setting gesture navigation enabled.');
  });
} catch (exception) {
  console.error(`Failed to set gesture navigation enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setGestureNavigationEnabled10+

setGestureNavigationEnabled(enable: boolean): Promise<void>

设置手势导航启用状态。使用Promise异步回调。系统出于安全的考虑，不会干预手势的禁用和恢复。应用调用本接口禁用手势后异常退出的情况下，如果想要恢复手势，需自行实现自动拉起机制并再次调用本接口恢复手势。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
enable boolean 是 设置手势导航启用状态。true表示启用手势导航；false表示禁用手势导航。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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 = window.setGestureNavigationEnabled(true);
  promise.then(() => {
    console.info('Succeeded in setting gesture navigation enabled.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set gesture navigation enabled. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set gesture navigation enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setWaterMarkImage10+

setWaterMarkImage(pixelMap: image.PixelMap, enable: boolean, callback: AsyncCallback<void>): void

设置屏幕水印图片显示状态。使用callback异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
pixelMap image.PixelMap 是 水印图片。可通过createPixelMap接口获取。
enable boolean 是 设置是否显示水印图片。true显示水印图片；false表示不显示水印图片。设置显示水印后需主动设置为false才能关闭水印图片显示。
callback AsyncCallback<void> 是 回调信息。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300003 This window manager service works abnormally.

示例：

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

let enable: boolean = true;
let color: ArrayBuffer = new ArrayBuffer(40000);
let initializationOptions: image.InitializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions).then((pixelMap: image.PixelMap) => {
  console.info('Succeeded in creating pixelmap.');
  try {
    window.setWaterMarkImage(pixelMap, enable, (err: BusinessError) => {
      const errCode: number = err.code;
      if (errCode) {
        console.error(`Failed to show watermark image. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info('Succeeded in showing watermark image.');
    });
  } catch (exception) {
    console.error(`Failed to show watermark image. Cause code: ${exception.code}, message: ${exception.message}`);
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to create PixelMap. Cause code: ${err.code}, message: ${err.message}`);
});

window.setWaterMarkImage10+

setWaterMarkImage(pixelMap: image.PixelMap, enable: boolean): Promise<void>

设置屏幕水印图片显示状态。使用Promise异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
pixelMap image.PixelMap 是 水印图片。可通过createPixelMap接口获取。
enable boolean 是 设置是否显示水印图片。true显示水印图片；false表示不显示水印图片。设置显示水印后需主动设置为false才能关闭水印图片显示。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300003 This window manager service works abnormally.

示例：

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

let enable: boolean = true;
let color: ArrayBuffer = new ArrayBuffer(40000);
let initializationOptions: image.InitializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions).then((pixelMap: image.PixelMap) => {
  console.info('Succeeded in creating pixelmap.');
  try {
    let promise = window.setWaterMarkImage(pixelMap, enable);
    promise.then(() => {
      console.info('Succeeded in showing watermark image.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to show watermark image. Cause code: ${err.code}, message: ${err.message}`);
    });
  } catch (exception) {
    console.error(`Failed to show watermark image. Cause code: ${exception.code}, message: ${exception.message}`);
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to create PixelMap. Cause code: ${err.code}, message: ${err.message}`);
});

window.setWaterMarkImage

setWaterMarkImage(pixelMap: image.PixelMap, enable: boolean, priority: number): Promise<void>

设置屏幕水印图片的显示状态，并设定水印的优先级。使用Promise异步回调。当priority等于0时，当前接口与setWaterMarkImage等价。

起始版本： 26.0.0

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

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
pixelMap image.PixelMap 是 水印图片。可通过createPixelMap接口获取。
enable boolean 是 设置是否显示水印图片。true表示显示水印图片；false表示不显示水印图片。设置显示水印后需主动设置为false才能关闭水印图片显示。
priority number 是 水印设置优先级。数值越小表示优先级越高，需大于等于0，小于0时返回1300016错误码。设置水印时，如果传入的优先级比上一次设置的低，则本次设置不会生效。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300003 This window manager service works abnormally.
1300016 Parameter error. Possible cause: Invalid parameter range.

示例：

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

let enable: boolean = true;
let color: ArrayBuffer = new ArrayBuffer(40000);
let initializationOptions: image.InitializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions).then((pixelMap: image.PixelMap) => {
  console.info('Succeeded in creating pixelmap.');
  try {
    window.setWaterMarkImage(pixelMap, enable, 0).then(() => {
      console.info('Succeeded in showing watermark image.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to show watermark image. Cause code: ${err.code}, message: ${err.message}`);
    });
  } catch (exception) {
    console.error(`Failed to show watermark image. Cause code: ${exception.code}, message: ${exception.message}`);
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to create PixelMap. Cause code: ${err.code}, message: ${err.message}`);
});

window.getSnapshot12+

getSnapshot(windowId: number): Promise<image.PixelMap>

获取指定窗口相同尺寸截图，使用Promise异步回调。若当前窗口设置为隐私模式（可通过setWindowPrivacyMode接口设置），截图结果为白屏。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
windowId number 是 窗口Id。可通过getWindowProperties接口获取到相关窗口属性，其中属性id即对应为窗口ID。

返回值：

类型 说明
Promise<image.PixelMap> Promise对象。返回指定窗口截图。

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
1300002 This window state is abnormal. Possible cause: Internal task error.
1300003 This window manager service works abnormally.

示例：

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

try {
  // 此处仅示意，请使用getWindowProperties获取对应窗口ID再进行使用
  let windowId: number = 40;
  let promise = window.getSnapshot(windowId);
  promise.then((pixelMap: image.PixelMap) => {
    console.info('Succeeded in getting snapshot window. Pixel bytes number:' + pixelMap.getPixelBytesNumber());
    pixelMap.release();
  }).catch((err: BusinessError) =>{
    console.error(`Failed to get snapshot. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to get snapshot. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.notifyScreenshotEvent20+

notifyScreenshotEvent(eventType: ScreenshotEventType): Promise<void>

通知屏幕截屏的事件类型，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
eventType ScreenshotEventType 是 截屏事件类型。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300003 This window manager service works abnormally.
1300016 Parameter error. Possible cause: 1. Invalid parameter range.

示例：

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

try {
  let eventType: window.ScreenshotEventType = window.ScreenshotEventType.SYSTEM_SCREENSHOT;
  let promise = window.notifyScreenshotEvent(eventType);
  promise.then(() => {
    console.info(`Succeeded in notifying screenshot event type.`);
  }).catch((err: BusinessError) =>{
    console.error(`Failed to notify screenshot event type. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to notify screenshot event type. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.getTopNavDestinationName20+

getTopNavDestinationName(windowId: number): Promise<string>

获取指定的前台窗口当前栈顶Navigation中的NavDestination名称，使用Promise异步回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
windowId number 是 窗口Id，用于指定要查询的窗口。该参数应为大于0的整数，小于等于0时会返回错误码1300016，如果指定的窗口不存在或生命周期不在前台，返回错误码为1300002。

返回值：

类型 说明
Promise<string> Promise对象。返回获取到的NavDestination名称。
对于Navigation嵌套以及当前页面存在多个Navigation的场景，查询的是后创建的Navigation的信息。
如果页面没有Navigation或者Navigation中没有NavDestination，返回空字符串。

错误码：

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

错误码ID 错误信息
202 Permission verification failed, non-system application uses system API.
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.
1300016 Parameter error. Possible cause: 1. Invalid parameter range.

示例：

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

try {
  let windowId = 10;
  let promise = window.getTopNavDestinationName(windowId);
  promise.then((data) => {
    console.info(`Succeeded, data: ${data}`);
  }).catch((err: BusinessError) => {
    console.error(`Failed, cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed, exception code: ${exception.code}, message: ${exception.message}`);
}

window.setSpecificSystemWindowZIndex23+

setSpecificSystemWindowZIndex(windowType: WindowType, zIndex: number): Promise<void>

设置系统窗口的窗口层级。使用Promise异步回调。

将所有该类型系统窗口zIndex调整为所设置的值，调整前后，该类型窗口之间相对层级保持不变，焦点窗口不发生变化。当应用关闭之后该类型窗口层级恢复默认值。

推荐不同类型窗口设置不同的zIndex，如果已经存在相同zIndex的窗口，设置前后，窗口之间的相对层级保持不变。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
windowType WindowType 是 窗口类型。仅支持TYPE_WALLET_SWIPE_CARD、TYPE_VOICE_INTERACTION、TYPE_SCREENSHOT、TYPE_SCREEN_CONTROL、TYPE_FLOAT_NAVIGATION和TYPE_MUTISCREEN_COLLABORATION。
zIndex number 是 系统窗口的层级。该参数仅支持整数输入，浮点数输入将向下取整。0和负数会使窗口在桌面以下。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed, non-system application uses system API.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: Invalid window type. Possible cause: Invalid window type.

示例：

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
try {
  window.setSpecificSystemWindowZIndex(window.WindowType.TYPE_WALLET_SWIPE_CARD, 200).then(() => {
    console.info('Succeeded in setting zIndex');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set zIndex. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set zIndex. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.createSubWindowAndBindParent

createSubWindowAndBindParent(name: string, parentId: number, ctx: BaseContext, parentWindowEventListener: WindowEventListener): Promise<Window>

创建一个子窗，并绑定父窗。使用Promise异步回调。

仅支持主窗口作为绑定的父窗。

子窗跟随父窗显示/隐藏，但并不跟随父窗销毁，子窗通过回调函数监听父窗生命周期变化。

建议在父窗销毁后主动销毁创建的子窗。

起始版本： 26.0.0

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

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
name string 是 窗口名称。
parentId number 是 指定父窗口ID。推荐使用getWindowProperties()方法获取窗口ID属性。
ctx BaseContext 是 当前应用上下文信息。
parentWindowEventListener WindowEventListener 是 回调函数。返回绑定父窗的生命周期变化。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
801 Capability not supported. This can not work correctly due to limited device capabilities.
1300001 Repeated operation. Possible cause: The window has been created and can not be created again.
1300002 This window state is abnormal. Possible cause: 1. Internal task error. 2. The number of windows has reached the limit.
1300003 This window manager service works abnormally.
1300009 The parent window is invalid. Possible cause: 1. The parent window does not exist or has been destroyed. 2. Invalid window type. Only main windows are supported.

示例：

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    let windowClass: window.Window | undefined = undefined;
    const parentWindowEventListener = (windowId: number, event: window.WindowEventType) => {
      // ...
    }
    try {
      let promise = window.createSubWindowAndBindParent('test', 100, this.context, parentWindowEventListener);
      promise.then((data) => {
        console.info('Succeeded in creating the window. Data:' + JSON.stringify(data));
        windowClass = data;
      }).catch((err: BusinessError) => {
        console.error(`Failed to create the Window. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

window.moveMainWindowToTargetDisplay

moveMainWindowToTargetDisplay(displayId: number, windowId: number): Promise<void>

将指定的主窗口迁移到指定的屏幕上。使用Promise异步回调。

  • 对于主屏/扩展屏与虚拟屏之间以及虚拟屏与虚拟屏之间的窗口迁移，仅主窗及其子窗会一起被迁移到对应屏幕上且被抬升，如果存在子窗，最上层可获焦子窗会获取焦点，否则主窗口获焦。
  • 对于主屏与扩展屏之间的窗口迁移，只会将主窗口迁移到对应屏幕并抬升层级。

起始版本： 26.0.0

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

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
displayId number 是 目标屏幕的ID，用于指定要迁移到的屏幕。该参数应为非负整数，可通过getWindowProperties接口获取到properties后，再通过properties.displayId获取；也可通过获取Display对象的id属性获取此参数。
windowId number 是 目标主窗口的ID，用于指定要迁移的窗口。该参数应为大于0的整数，通过getWindowProperties接口获取到properties后，再通过properties.id获取。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed, non-system application uses system API.
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.
1300008 The display device is abnormal.

示例：

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

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    windowStage.loadContent('pages/Index', (err: BusinessError) => {
      if (err.code) {
        console.error(`Failed to load content for main window. Cause code: ${err.code}, message: ${err.message}`);
      }
      let displayClass: display.Display | null = null;
      displayClass = display.getDefaultDisplaySync();
      let mainWindow = windowStage.getMainWindowSync();
      try {
        window.moveMainWindowToTargetDisplay(displayClass.id, mainWindow.getWindowProperties().id).then(() => {
          console.info(`Succeeded in moving window id: ${mainWindow.getWindowProperties().id} to target display id: ${mainWindow.getWindowProperties().displayId}`);
        }).catch((err: BusinessError) => {
          console.error(`Failed to move window to target display. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to move window to target display. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

window.setWindowLayoutMode(deprecated)

setWindowLayoutMode(mode: WindowLayoutMode, callback: AsyncCallback<void>): void

设置窗口布局模式，使用callback异步回调。

说明：

从API version 9开始支持，从API version 26.0.0开始废弃，无替代接口。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
mode WindowLayoutMode 是 设置的窗口布局模式。
callback AsyncCallback<void> 是 回调信息。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300003 This window manager service works abnormally.

示例：

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

try {
  window.setWindowLayoutMode(window.WindowLayoutMode.WINDOW_LAYOUT_MODE_CASCADE, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set window layout mode. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in setting window layout mode.');
  });
} catch (exception) {
  console.error(`Failed to set window layout mode. Cause code: ${exception.code}, message: ${exception.message}`);
}

window.setWindowLayoutMode(deprecated)

setWindowLayoutMode(mode: WindowLayoutMode): Promise<void>

设置窗口布局模式，使用Promise异步回调。

说明：

从API version 9开始支持，从API version 26.0.0开始废弃，无替代接口。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
mode WindowLayoutMode 是 设置的窗口布局模式。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
1300003 This window manager service works abnormally.

示例：

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

try {
  let promise = window.setWindowLayoutMode(window.WindowLayoutMode.WINDOW_LAYOUT_MODE_CASCADE);
  promise.then(() => {
    console.info('Succeeded in setting window layout mode.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set window layout mode. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set window layout mode. Cause code: ${exception.code}, message: ${exception.message}`);
}

Window

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

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

hide7+

hide (callback: AsyncCallback<void>): void

隐藏当前窗口，使用callback异步回调，仅支持系统窗口与应用子窗口。

系统接口： 此接口为系统接口。

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

参数：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal.

示例：

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

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

hide7+

hide(): Promise<void>

隐藏当前窗口，使用Promise异步回调，仅支持系统窗口与应用子窗口。

系统接口： 此接口为系统接口。

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

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal.

示例：

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

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

hideWithAnimation9+

hideWithAnimation(callback: AsyncCallback<void>): void

隐藏当前窗口，过程中播放动画，使用callback异步回调。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

参数：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

示例：

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

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

hideWithAnimation9+

hideWithAnimation(): Promise<void>

隐藏当前窗口，过程中播放动画，使用Promise异步回调。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

示例：

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

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

showWithAnimation9+

showWithAnimation(callback: AsyncCallback<void>): void

显示当前窗口，过程中播放动画，使用callback异步回调。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

参数：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

示例：

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

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

showWithAnimation9+

showWithAnimation(): Promise<void>

显示当前窗口，过程中播放动画，使用Promise异步回调。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: Invalid window type. Only system windows are supported.

示例：

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

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

setWindowMode9+

setWindowMode(mode: WindowMode, callback: AsyncCallback<void>): void

设置主窗口模式，使用callback异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
mode WindowMode 是 窗口模式。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

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

setWindowMode9+

setWindowMode(mode: WindowMode): Promise<void>

设置主窗口模式，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
mode WindowMode 是 窗口模式。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

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

attachLayoutToParentWindow24+

attachLayoutToParentWindow(anchorInfo?: WindowAnchorInfo, attachOptions?: SubWindowAttachOptions): Promise<void>

设置一级子窗与主窗保持相对位置不变。使用Promise异步回调。

该相对位置通过子窗与主窗之间的锚点偏移量表示，子窗和主窗使用的窗口锚点相同。

非独立子窗支持调用。独立子窗调用此接口时，将返回1300004错误码。

说明：

  • 只支持一级子窗调用该接口，子窗需处于自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING）。

  • 当子窗调用该接口后，立即使其显示位置跟随主窗并保持相对位置不变，并且可以监听主窗大小及模式切换。除非调用detachLayoutToParentWindow()接口解绑，否则效果将持续。

  • 当子窗调用该接口后，再调用moveWindowTo()、maximize()、setFollowParentWindowLayoutEnabled()等修改窗口位置的接口，或通过鼠标/触摸操作对子窗进行拖拽移动、拖拽缩放时将不生效。

系统接口： 此接口为系统接口。

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

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在支持并处于自由窗口的设备上正常调用并生效；在支持但不处于自由窗口的设备上调用不生效不报错，设备切换到自由窗口状态生效；在不支持自由窗口的设备上调用不生效不报错。

参数：

参数名 类型 必填 说明
anchorInfo WindowAnchorInfo 否 一级子窗与主窗保持相对位置不变时的锚点参数。若不传，默认逻辑参考WindowAnchorInfo。
attachOptions SubWindowAttachOptions 否 设置子窗布局的附加参数。若不传，默认逻辑参考SubWindowAttachOptions。

返回值：

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

错误码：

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

错误码ID 错误信息
801 Capability not supported. Function attachLayoutToParentWindow can not work correctly due to limited device capabilities.
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: 1. Invalid window type. Only subwindows are supported; 2. The current window's parent window is not a main window; 3. Only level-1 subwindows are supported.
1300010 The operation in the current window status is invalid. Possible cause: 1. The subwindow is following its parent window's layout. 2. The subwindow is maximized.

示例：

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (loadError: BusinessError) => {
      if (loadError.code) {
        console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`);
        return;
      }
      console.info("Succeeded in loading the content.");
      windowStage.createSubWindow("subWindow").then((subWindow: window.Window) => {
        if (subWindow == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        let anchorInfo : window.WindowAnchorInfo = {
          anchorType: window.WindowAnchor.TOP_START,
          offsetX: 0,
          offsetY: 0
        };
        let attachOptions: window.SubWindowAttachOptions = {
          parentWindowSizeChangeCallback:(data: window.Size) => {
            console.info(`Successfully accepted parentWindow size change, width: ${data.width}, height: ${data.height}`);
          },
          parentWindowStatusChangeCallback:(type: window.WindowStatusType) => {
            console.info(`Successfully accepted parentWindow status change, statusType: ${type}`);
          },
          isIntersectedWidthLimit: true,
          isIntersectedHeightLimit: true
        }
        subWindow.attachLayoutToParentWindow(anchorInfo, attachOptions).then(() => {
          console.info("Succeeded in attaching to the main window");
        }).catch((error: BusinessError) => {
          console.error(`attachLayoutToParentWindow failed. ${error.code} ${error.message}`);
        })
      }).catch((error: BusinessError) => {
        console.error(`createSubWindow failed. ${error.code} ${error.message}`);
      })
    });
  }
}

detachLayoutToParentWindow24+

detachLayoutToParentWindow(): Promise<void>

解除一级子窗与主窗保持相对位置不变的协同关系。使用Promise异步回调。

非独立子窗支持调用。独立子窗调用此接口时，将返回1300004错误码。

说明：

  • 子窗调用接口时需保持子窗处于协同状态。

  • 调用接口解除协同后，子窗将保持协同时的位置，可对子窗进行拖拽以修改子窗大小和位置。

  • 解除协同后，调用moveWindowTo()、maximize()、setFollowParentWindowLayoutEnabled()修改窗口位置的接口，或通过鼠标/触摸操作对子窗进行拖拽移动、拖拽缩放时将生效。

系统接口： 此接口为系统接口。

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

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在支持并处于自由窗口的设备上正常调用并生效；在支持但不处于自由窗口的设备上调用不生效不报错，设备切换到自由窗口状态生效；在不支持自由窗口的设备上调用不生效不报错。

返回值：

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

错误码：

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

错误码ID 错误信息
801 Capability not supported. Function detachLayoutToParentWindow can not work correctly due to limited device capabilities.
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: 1. Invalid window type. Only subwindows are supported; 2. Only level-1 subwindows are supported.
1300010 The operation in the current window status is invalid. Possible cause: The subwindow is not attached to the main window.

示例：

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (loadError: BusinessError) => {
      if (loadError.code) {
        console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`);
        return;
      }
      console.info("Succeeded in loading the content.");
      windowStage.createSubWindow("subWindow").then((subWindow: window.Window) => {
        if (subWindow == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        subWindow.detachLayoutToParentWindow().then(() => {
          console.info("Succeeded in detaching to the main window");
        }).catch((error: BusinessError) => {
          console.error(`detachLayoutToParentWindow failed. ${error.code} ${error.message}`);
        })
      }).catch((error: BusinessError) => {
        console.error(`createSubWindow failed. ${error.code} ${error.message}`);
      })
    });
  }
}

bindDialogTarget9+

bindDialogTarget(token: rpc.RemoteObject, deathCallback: Callback<void>, callback: AsyncCallback<void>): void

绑定模态窗口与目标窗口，成功绑定后，目标窗口不能响应用户操作。同时添加目标窗口销毁监听，使用callback异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
token rpc.RemoteObject 是 目标窗口token值。
deathCallback Callback<void> 是 目标窗口销毁监听。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: Incorrect parameter types.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

import { rpc } from '@kit.IPCKit';
import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class Property {
  public value: Object

  constructor(value: Object) {
    this.value = value
  }
}

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    let config: window.Configuration = {
      name: "test",
      windowType: window.WindowType.TYPE_DIALOG,
      ctx: this.context
    };
    try {
      window.createWindow(config, (err: BusinessError, data) => {
        let errCode: number = err?.code;
        if (errCode) {
          console.error(`Failed to create the window. Cause code: ${err?.code}, message: ${err?.message}`);
          return;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let token = want.parameters?.['ohos.ability.params.request.token'] as Property;
        let value = token.value as rpc.RemoteObject;
        data.bindDialogTarget(value, () => {
          console.info('Dialog Window Need Destroy.');
          }, (err: BusinessError) => {
          let errCode: number = err?.code;
          if (errCode) {
            console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
            return;
          }
          console.info('Succeeded in binding dialog target.');
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

bindDialogTarget9+

bindDialogTarget(token: rpc.RemoteObject, deathCallback: Callback<void>): Promise<void>

绑定模态窗口与目标窗口，成功绑定后，目标窗口不能响应用户操作。同时添加目标窗口销毁监听，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
token rpc.RemoteObject 是 目标窗口token值。
deathCallback Callback<void> 是 目标窗口销毁监听。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: Incorrect parameter types.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

import { rpc } from '@kit.IPCKit';
import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class Property {
  public value: Object

  constructor(value: Object) {
    this.value = value
  }
}

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    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;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let token = want.parameters?.['ohos.ability.params.request.token'] as Property;
        let value = token.value as rpc.RemoteObject;
        let promise = data.bindDialogTarget(value, () => {
          console.info('Dialog Window Need Destroy.');
        });
        promise.then(() => {
          console.info('Succeeded in binding dialog target.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

bindDialogTarget9+

bindDialogTarget(requestInfo: dialogRequest.RequestInfo, deathCallback: Callback<void>, callback: AsyncCallback<void>): void

绑定模态窗口与目标窗口，成功绑定后，目标窗口不能响应用户操作。同时添加目标窗口销毁监听，使用callback异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
requestInfo dialogRequest.RequestInfo 是 目标窗口RequestInfo值。
deathCallback Callback<void> 是 目标窗口销毁监听。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: Incorrect parameter types.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    let config: window.Configuration = {
      name: "test", windowType: window.WindowType.TYPE_DIALOG, ctx: this.context
    };
    try {
      window.createWindow(config, (err: BusinessError, data) => {
        let errCode: number = err?.code;
        if (errCode) {
          console.error(`Failed to create the window. Cause code: ${err?.code}, message: ${err?.message}`);
          return;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let requestInfo = dialogRequest.getRequestInfo(want);
        data.bindDialogTarget(requestInfo, () => {
          console.info('Dialog Window Need Destroy.');
          }, (err: BusinessError) => {
          let errCode: number = err?.code;
          if (errCode) {
            console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
            return;
          }
          console.info('Succeeded in binding dialog target.');
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

bindDialogTarget9+

bindDialogTarget(requestInfo: dialogRequest.RequestInfo, deathCallback: Callback<void>): Promise<void>

绑定模态窗口与目标窗口，成功绑定后，目标窗口不能响应用户操作。同时添加目标窗口销毁监听，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
requestInfo dialogRequest.RequestInfo 是 目标窗口RequestInfo值。
deathCallback Callback<void> 是 目标窗口销毁监听。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: Incorrect parameter types.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

import { dialogRequest, Want, ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    console.info('onRequest');
    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;
        }
        if (!data) {
          console.error('data is null');
          return;
        }
        let requestInfo = dialogRequest.getRequestInfo(want);
        let promise = data.bindDialogTarget(requestInfo, () => {
          console.info('Dialog Window Need Destroy.');
        });
        promise.then(() => {
          console.info('Succeeded in binding dialog target.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`);
        });
      });
    } catch (err) {
      console.error(`Failed to bind dialog target. Cause code: ${err?.code}, message: ${err?.message}`)
    }
  }
}

setWakeUpScreen9+

setWakeUpScreen(wakeUp: boolean): void

唤醒屏幕。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
wakeUp boolean 是 是否设置唤醒屏幕。true表示唤醒；false表示不唤醒。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

let wakeUp: boolean = true;
try {
  windowClass.setWakeUpScreen(wakeUp);
} catch (exception) {
  console.error(`Failed to wake up the screen. Cause code: ${exception.code}, message: ${exception.message}`);
}

setSnapshotSkip9+

setSnapshotSkip(isSkip: boolean): void

截屏、录屏或投屏是否忽略当前窗口。此接口一般用于禁止截屏、录屏或投屏的场景。

若要实现窗口始终在前台忽略截屏、录屏或投屏，在窗口从后台回到前台时，需要通过on('windowEvent')监听窗口生命周期变化，在后台状态时设置为false，而在前台状态时设置为true。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
isSkip boolean 是 截屏、录屏或投屏是否忽略当前窗口，默认为false。
true表示忽略当前窗口，false表示不忽略当前窗口。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
1300002 This window state is abnormal.

示例：

let isSkip: boolean = true;
try {
  windowClass.setSnapshotSkip(isSkip);
} catch (exception) {
  console.error(`Failed to Skip. Cause code: ${exception.code}, message: ${exception.message}`);
}

opacity9+

opacity(opacity: number): void

设置窗口不透明度。仅支持在系统窗口、全局悬浮窗和模态窗口的自定义显示与隐藏动画中使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
opacity number 是 不透明度。该参数为浮点数，取值范围为[0.0, 1.0]。0.0表示完全透明，1.0表示完全不透明。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

try {
  windowClass.opacity(0.5);
} catch (exception) {
  console.error(`Failed to opacity. Cause code: ${exception.code}, message: ${exception.message}`);
}

scale9+

scale(scaleOptions: ScaleOptions): void

设置窗口缩放参数。仅支持在系统窗口、全局悬浮窗和模态窗口的自定义显示与隐藏动画中使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
scaleOptions ScaleOptions 是 缩放参数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

let obj: window.ScaleOptions = {
  x: 2.0,
  y: 1.0,
  pivotX: 0.5,
  pivotY: 0.5
};
try {
  windowClass.scale(obj);
} catch (exception) {
  console.error(`Failed to scale. Cause code: ${exception.code}, message: ${exception.message}`);
}

rotate9+

rotate(rotateOptions: RotateOptions): void

设置窗口旋转参数。仅支持在系统窗口、全局悬浮窗和模态窗口的自定义显示与隐藏动画中使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
rotateOptions RotateOptions 是 旋转参数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

let obj: window.RotateOptions = {
  x: 1.0,
  y: 1.0,
  z: 45.0,
  pivotX: 0.5,
  pivotY: 0.5
};
try {
  windowClass.rotate(obj);
} catch (exception) {
  console.error(`Failed to rotate. Cause code: ${exception.code}, message: ${exception.message}`);
}

translate9+

translate(translateOptions: TranslateOptions): void

设置窗口平移参数。仅支持在系统窗口、全局悬浮窗和模态窗口的自定义显示与隐藏动画中使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
translateOptions TranslateOptions 是 平移参数，单位为px。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

let obj: window.TranslateOptions = {
  x: 100.0,
  y: 0.0,
  z: 0.0
};
try {
  windowClass.translate(obj);
} catch (exception) {
  console.error(`Failed to translate. Cause code: ${exception.code}, message: ${exception.message}`);
}

getTransitionController9+

getTransitionController(): TransitionController

获取窗口属性转换控制器。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

返回值：

类型 说明
TransitionController 属性转换控制器。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal.
1300004 Unauthorized operation.

示例：

let controller = windowClass.getTransitionController(); // 获取属性转换控制器

setBlur9+

setBlur(radius: number): void

设置窗口模糊。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
radius number 是 表示窗口模糊的半径值。该参数为浮点数，单位为px，取值范围为[0, +∞)，取值为0.0时表示关闭窗口模糊。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

try {
  windowClass.setBlur(4.0);
} catch (exception) {
  console.error(`Failed to set blur. Cause code: ${exception.code}, message: ${exception.message}`);
}

setBackdropBlur9+

setBackdropBlur(radius: number): void

设置窗口背景模糊。仅支持系统窗口、全局悬浮窗和模态窗口使用。

窗口背景是指窗口覆盖的下层区域，与窗口大小相同。

需要通过setWindowBackgroundColor将窗口内容背景设置成透明，否则无法看到模糊效果。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
radius number 是 表示窗口背景模糊的半径值。该参数为浮点数，单位为px，取值范围为[0.0, +∞)，取值为0.0表示关闭窗口背景模糊。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

try {
  windowClass.setWindowBackgroundColor('#00FFFFFF');
  windowClass.setBackdropBlur(4.0);
} catch (exception) {
  console.error(`Failed to set backdrop blur. Cause code: ${exception.code}, message: ${exception.message}`);
}

setBackdropBlurStyle9+

setBackdropBlurStyle(blurStyle: BlurStyle): void

设置窗口背景模糊类型。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
blurStyle BlurStyle 是 表示窗口背景模糊类型。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

try {
  windowClass.setBackdropBlurStyle(window.BlurStyle.THIN);
} catch (exception) {
  console.error(`Failed to set backdrop blur style. Cause code: ${exception.code}, message: ${exception.message}`);
}

setShadow9+

setShadow(radius: number, color?: string, offsetX?: number, offsetY?: number): void

设置窗口边缘阴影。仅支持系统窗口、应用子窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
radius number 是 表示窗口边缘阴影的模糊半径。该参数为浮点数，单位为px，取值范围为[0.0, +∞)，取值为0.0时表示关闭窗口边缘阴影。
color string 否 表示窗口边缘阴影的颜色，为十六进制RGB或ARGB颜色，不区分大小写，例如#00FF00或#FF00FF00，默认值为'#000000'。
offsetX number 否 表示窗口边缘阴影的X轴的偏移量。该参数为浮点数，单位为px，默认值为0.0。
offsetY number 否 表示窗口边缘阴影的Y轴的偏移量。该参数为浮点数，单位为px，默认值为0.0。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

try {
  windowClass.setShadow(4.0, '#FF00FF00', 2, 3);
} catch (exception) {
  console.error(`Failed to set shadow. Cause code: ${exception.code}, message: ${exception.message}`);
}

setCornerRadius9+

setCornerRadius(cornerRadius: number): void

设置窗口圆角半径。仅支持系统窗口、全局悬浮窗和模态窗口使用。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
cornerRadius number 是 表示窗口圆角的半径值。该参数为浮点数，单位为px，取值范围为[0.0, +∞)，取值为0.0时表示没有窗口圆角。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.

示例：

try {
  windowClass.setCornerRadius(4.0);
} catch (exception) {
  console.error(`Failed to set corner radius. Cause code: ${exception.code}, message: ${exception.message}`);
}

raiseToAppTop10+

raiseToAppTop(callback: AsyncCallback<void>): void

提升应用子窗口到应用顶层。使用callback异步回调。

使用该接口需要先创建子窗口，并确保该子窗口调用showWindow()并执行完毕。

非独立子窗支持调用。独立子窗调用该接口不生效也不报错。

系统接口： 此接口为系统接口。

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

参数：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation.
1300009 The parent window is invalid.

示例：

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

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    // 创建子窗
    windowStage.createSubWindow('testSubWindow').then((subWindow) => {
      if (subWindow == null) {
        console.error('Failed to create the subWindow. Cause: The data is empty');
        return;
      }
      subWindow.showWindow().then(() => {
        subWindow.raiseToAppTop((err: BusinessError) => {
          const errCode: number = err.code;
          if (errCode) {
            console.error(`Failed to raise the window to app top. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in raising the window to app top.');
        });
      });
    });
  }
}

setWaterMarkFlag10+

setWaterMarkFlag(enable: boolean): Promise<void>

为当前窗口添加或删除安全水印标志，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
enable boolean 是 是否对窗口添加标志位。true表示添加，false表示删除。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300008 The display device is abnormal.

示例：

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

try {
  let enable = true;
  let promise = windowClass.setWaterMarkFlag(enable);
  promise.then(() => {
    console.info('Succeeded in setting water mark flag of window.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set water mark flag of window. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set water mark flag of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

setWaterMarkFlag10+

setWaterMarkFlag(enable: boolean, callback: AsyncCallback<void>): void

为当前窗口添加或删除安全水印标志，使用callback异步回调。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
enable boolean 是 是否对窗口添加标志位。true表示添加，false表示删除。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300008 The display device is abnormal.

示例：

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

try {
  let enable: boolean = true;
  windowClass.setWaterMarkFlag(enable, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set water mark flag of window. Cause code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in setting water mark flag of window.');
  });
} catch (exception) {
  console.error(`Failed to set water mark flag of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

setHandwritingFlag12+

setHandwritingFlag(enable: boolean): Promise<void>

为当前窗口添加或移除手写标志，添加该标志后窗口只响应手写笔事件，不响应触屏事件。使用Promise异步回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
enable boolean 是 是否对窗口添加标志位。true表示添加，false表示移除。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system 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.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

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

try {
  let enable = true;
  let promise = windowClass.setHandwritingFlag(enable);
  promise.then(() => {
    console.info('Succeeded in setting handwriting flag of window.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set handwriting flag of window. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to set handwriting flag of window. Cause code: ${exception.code}, message: ${exception.message}`);
}

raiseAboveTarget10+

raiseAboveTarget(windowId: number, callback: AsyncCallback<void>): void

将同一个主窗口下的子窗口抬升到目标子窗口之上。使用callback异步回调。

使用该接口需要确保要抬升的子窗口和目标子窗口都已创建完成，分别调用showWindow()并执行完毕。

非独立子窗支持调用。独立子窗调用该接口不生效也不报错。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
windowId number 是 目标子窗口的id，通过getWindowProperties接口获取到properties后，再通过properties.id获取。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: Mandatory parameters are left unspecified.
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.
1300009 The parent window is invalid.

示例：

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

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window;
    // 创建子窗
    try {
      windowStage.createSubWindow("testSubWindow").then((data) => {
        if (data == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        windowClass = data;
        windowClass.showWindow().then(() => {
          // windowClass的获取需放在targetWindow之上
          let targetWindow: window.Window = windowClass;
          let properties = targetWindow.getWindowProperties();
          let targetId = properties.id;
          windowClass.raiseAboveTarget(targetId, (err: BusinessError) => {
            if (err.code) {
              console.error(`Failed to raise the subWindow to target subWindow top. Cause code: ${err.code}, message: ${err.message}`);
              return;
            }
            console.info('Succeeded in raising the subWindow to target subWindow top.');
          });
        });
      });
    } catch (exception) {
      console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

raiseAboveTarget10+

raiseAboveTarget(windowId: number): Promise<void>

将同一个主窗下的子窗口提升到目标子窗口之上。使用Promise异步回调。

使用该接口需要确保要抬升的子窗口和目标子窗口都已创建完成，分别调用showWindow()并执行完毕。

非独立子窗支持调用。独立子窗调用该接口不生效也不报错。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
windowId number 是 目标子窗口的id，通过getWindowProperties接口获取到properties后，再通过properties.id获取。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: Mandatory parameters are left unspecified.
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.
1300009 The parent window is invalid.

示例：

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

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    let windowClass: window.Window;
    // 创建子窗
    try {
      windowStage.createSubWindow("testSubWindow").then((data) => {
        if (data == null) {
          console.error("Failed to create the subWindow. Cause: The data is empty");
          return;
        }
        windowClass = data;
        windowClass.showWindow().then(() => {
          // windowClass的获取需放在targetWindow之上
          let targetWindow: window.Window = windowClass;
          let properties = targetWindow.getWindowProperties();
          let targetId = properties.id;
          windowClass.raiseAboveTarget(targetId).then(()=> {
            console.info('Succeeded in raising the subWindow to target subWindow top.');
          }).catch((err: BusinessError)=>{
            console.error(`Failed to raise the subWindow to target subWindow top. Cause code: ${err.code}, message: ${err.message}`);
          });
        });
      });
    } catch (exception) {
      console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
}

raiseMainWindowAboveTarget20+

raiseMainWindowAboveTarget(windowId: number): Promise<void>

将主窗口的层级调整至同应用下的另一个主窗口之上，子窗口的层级会跟随所属主窗口变动。使用Promise异步回调。

仅支持系统应用主窗口调用。

传入目标主窗口的id，调用窗口和目标窗口需满足：同应用进程、显示在同一物理屏、层级低于锁屏、非置顶主窗、非模态主窗且无模应用子窗。

  • 应用主窗口或者它的子窗口如果是焦点窗口，此主窗口调用该接口降低层级后则自动失焦，由当前层级最高的应用窗口获焦。

  • 应用主窗口调用该接口调整层级后超过当前焦点窗口，则被抬升主窗口及其子窗口中，层级最高的窗口自动获焦；应用主窗口调用该接口调整层级后未超过当前焦点窗口，则焦点不做转移。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在支持并处于自由窗口状态的设备上可正常调用；在支持但不处于自由窗口状态的设备及不支持自由窗口状态的设备上调用返回801错误码。

参数：

参数名 类型 必填 说明
windowId number 是 目标主窗口的id，该参数为整数，通过getWindowProperties接口获取到properties后，再通过properties.id获取。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.
1300016 Parameter error. Possible cause: 1. Invalid Parameter range. 2. Invalid parameter length.

示例：

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

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}.`);
        return;
      }
      console.info('Succeeded in loading the content.');
      try {
        let want: Want = {
          abilityName: "RaiseMainWindowAbility",
          bundleName: "com.example.myapplication"
        };
        let options: StartOptions = {
          windowMode: AbilityConstant.WindowMode.WINDOW_MODE_FLOATING
        };
        this.context.startAbility(want, options);
      } catch (err) {
        console.error(`Failed to start the ability. Cause code: ${err.code}, message: ${err.message}.`);
      }
      setTimeout(async () => {
        let mainWindow: window.Window | null | undefined = windowStage.getMainWindowSync();
        let targetId: number | null | undefined = AppStorage.get('higher_window_id');
        mainWindow.raiseMainWindowAboveTarget(targetId).then(() => {
          console.info('Succeeded in raising main window above target.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to raise main window above target. Cause code: ${err.code}, message: ${err.message}.`)
        });
      }, 3000)
    });
  }
}

// 新建文件src/main/ets/raisemainwindowability/RaiseMainWindowAbility.ets
import { UIAbility } from '@kit.AbilityKit';

export default class RaiseMainWindowAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    AppStorage.setOrCreate('higher_window_id', windowStage.getMainWindowSync().getWindowProperties().id);
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}.`);
        return;
      }
      console.info('Succeeded in loading the content.');
    });
  }
}

// module.json5
{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      },
      {
        "name": "RaiseMainWindowAbility",
        "launchType": "multiton",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}

setRaiseByClickEnabled10+

setRaiseByClickEnabled(enable: boolean, callback: AsyncCallback<void>): void

禁止/使能子窗口点击抬升功能。使用callback异步回调。

通常来说，点击一个子窗口，会将该子窗口显示到最上方，如果设置为false，那么点击子窗口的时候，不会将该子窗口显示到最上方，而是保持不变。

使用该接口需要先创建子窗口，并确保该子窗口调用showWindow()并执行完毕。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
enable boolean 是 设置子窗口点击抬升功能是否使能，true表示使能，false表示禁止。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system 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.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation.
1300009 The parent window is invalid.

示例：

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

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.info('onWindowStageCreate');
    // 创建子窗
    windowStage.createSubWindow("testSubWindow").then((subWindow) => {
      if (subWindow == null) {
        console.error('Failed to create the subWindow. Cause: The data is empty');
        return;
      }
      subWindow.showWindow().then(() => {
        try {
          let enabled = false;
          subWindow.setRaiseByClickEnabled(enabled, (err) => {
          if (err.code) {
            console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in disabling the raise-by-click function.');
          });
        } catch (err) {
          console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`);
        }
      });
    });
  }
}

setMainWindowRaiseByClickEnabled23+

setMainWindowRaiseByClickEnabled(enable: boolean): Promise<void>

禁止/使能主窗口点击抬升功能。使用Promise异步回调。

点击主窗口时，默认会抬升主窗口及其子窗口。调用此接口禁止主窗口点击抬升后（即传入false），点击主窗口时不会将其及子窗口进行抬升，保持原有状态不变；点击子窗口时，主窗口会连同子窗口一起被抬升。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
enable boolean 是 设置主窗口点击抬升功能是否使能，true表示使能，false表示禁止。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.getMainWindow().then((window: window.Window) => {
      // 加载主窗口对应的页面
      windowStage.loadContent('pages/Index', (err) => {
        if (err.code) {
          console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
          return;
        }
        console.info('Succeeded in loading the content.');
        try {
          let raiseEnabled: boolean = false;
          let promise = window.setMainWindowRaiseByClickEnabled(raiseEnabled);
          promise.then(() => {
            console.info('Succeeded in disabling the raise-by-click function.');
          })
        } catch(err) {
          console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`);
        };
      });
    });
  }
}

hideNonSystemFloatingWindows11+

hideNonSystemFloatingWindows(shouldHide: boolean, callback: AsyncCallback<void>): void

设置是否隐藏非系统级悬浮窗口（windowType类型为TYPE_FLOAT），使用callback异步回调。

非系统级悬浮窗口是指非系统应用创建的悬浮窗口。默认情况下，一个系统应用主窗口可以与非系统级悬浮窗口共同显示，即该主窗口可以被上层的非系统级悬浮窗口遮挡，如果设置为true，则所有的非系统级悬浮窗口都会被隐藏，此时该主窗口就不会被上层的非系统级悬浮窗口遮挡。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在PC/2in1设备、其他设备的电脑模式中调用不生效也不报错，在其他设备和其他模式中可正常调用。

参数：

参数名 类型 必填 说明
shouldHide boolean 是 指示是否隐藏非系统级的悬浮窗口，true表示隐藏，false表示不隐藏。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system 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.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation.

示例：

// EntryAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // 加载主窗口对应的页面
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info('Succeeded in loading the content.');
    });

    // 获取应用主窗口。
    let mainWindow: window.Window | undefined = undefined;
    windowStage.getMainWindow((err, data) => {
      if (err.code) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      mainWindow = data;
      console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));

      let shouldHide = true;
      try {
        // 调用带callback参数的hideNonSystemFloatingWindows接口
        mainWindow.hideNonSystemFloatingWindows(shouldHide, (err) => {
          if (err.code) {
            console.error(`Failed to hide the non-system floating windows. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in hiding the non-system floating windows.');
        });
      } catch (exception) {
        console.error(`Failed to hide the non-system floating windows. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

hideNonSystemFloatingWindows11+

hideNonSystemFloatingWindows(shouldHide: boolean): Promise<void>

设置是否隐藏非系统级悬浮窗口（windowType类型为TYPE_FLOAT），使用Promise异步回调。

非系统级悬浮窗口是指非系统应用创建的悬浮窗口。默认情况下，一个系统应用主窗口可以与非系统级悬浮窗口共同显示，即该主窗口可以被上层的非系统级悬浮窗口遮挡，如果设置为true，则所有的非系统级悬浮窗口都会被隐藏，此时该主窗口就不会被上层的非系统级悬浮窗口遮挡。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在PC/2in1设备、其他设备的电脑模式中调用不生效也不报错，在其他设备和其他模式中可正常调用。

参数：

参数名 类型 必填 说明
shouldHide boolean 是 指示是否隐藏非系统级的悬浮窗口，true表示隐藏，false表示不隐藏。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system 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.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation.

示例：

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

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // 加载主窗口对应的页面
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      console.info('Succeeded in loading the content.');
    });

    // 获取应用主窗口。
    let mainWindow: window.Window | undefined = undefined;
    windowStage.getMainWindow((err, data) => {
      if (err.code) {
        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      mainWindow = data;
      console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));

      let shouldHide = true;
      try {
        // 调用hideNonSystemFloatingWindows接口，获取promise对象
        let promise = mainWindow.hideNonSystemFloatingWindows(shouldHide);
        promise.then(()=> {
          console.info('Succeeded in hiding the non-system floating windows.');
        }).catch((err: BusinessError)=>{
          console.error(`Failed to hide the non-system floating windows. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to hide the non-system floating windows. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

setDefaultDensityEnabled20+

setDefaultDensityEnabled(enabled: boolean): void

设置窗口是否使用所在屏幕的系统默认Density。Stage模型下，该接口需要在loadContent()或setUIContent()调用生效后使用。

不调用此接口进行设置，则表示不使用系统默认Density。

当存在同时使用该接口、setDefaultDensityEnabled()和setCustomDensity时，以最后调用的设置效果为准。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
enabled boolean 是 设置是否使用系统默认Density。true表示使用系统默认Density，窗口不跟随系统显示大小变化重新布局；false表示不使用系统默认Density，窗口跟随系统显示大小变化重新布局。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal. Possible cause: The window is not created or destroyed.

示例：

try {
  windowClass.setDefaultDensityEnabled(true);
  console.info(`Succeeded in setting default density enabled`);
} catch (exception) {
  console.error(`Failed to set default density enabled. Cause code: ${exception.code}, message: ${exception.message}`);
}

isMainWindowFullScreenAcrossDisplays20+

isMainWindowFullScreenAcrossDisplays(): Promise<boolean>

判断当前窗口的主窗口是否是跨多块屏幕使用全屏模式显示，使用Promise异步回调，仅支持主窗口与应用子窗口。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

返回值：

类型 说明
Promise<boolean> Promise对象。返回true表示当前窗口的主窗口跨多块屏幕使用全屏模式显示，返回false表示当前窗口的主窗口未跨多块屏幕使用全屏模式显示。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation.

示例：

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

try {
  let promise = windowClass.isMainWindowFullScreenAcrossDisplays();
  promise.then((data: boolean)=> {
      console.info(`Succeeded in using isMainWindowFullScreenAcrossDisplays function. Data: ${data}`);
  }).catch((err: BusinessError)=>{
      console.error(`Failed to use isMainWindowFullScreenAcrossDisplays function. code:${err.code}, message:${err.message}.`);
  });
} catch (exception) {
  console.error(`Failed to use isMainWindowFullScreenAcrossDisplays function. Cause code: ${exception.code}, message: ${exception.message}.`);
}

on('mainWindowFullScreenAcrossDisplaysChanged')20+

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

监听本窗口的主窗口跨多块屏幕使用全屏模式显示的状态变化事件。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'mainWindowFullScreenAcrossDisplaysChanged'，即本窗口的主窗口跨多块屏幕使用全屏模式显示的状态变化。
callback Callback<boolean> 是 回调函数。即本窗口的主窗口跨多块屏幕使用全屏模式显示的状态变化回调。true表示主窗口进入跨多块屏幕使用全屏模式显示状态，false表示主窗口退出跨多块屏幕使用全屏模式显示状态。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: Invalid window type. Only main windows and subwindows are supported.

示例：

const callback = (mainWindowFullScreenAcrossDisplaysChanged: boolean) => {
  console.info(`main window across displays changed. Data: ${mainWindowFullScreenAcrossDisplaysChanged}`);
}
try {
  windowClass.on('mainWindowFullScreenAcrossDisplaysChanged', callback);
} catch (exception) {
  console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`);
}

off('mainWindowFullScreenAcrossDisplaysChanged')20+

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

取消监听本窗口的主窗口跨多块屏幕使用全屏模式显示的状态变化事件。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'mainWindowFullScreenAcrossDisplaysChanged'，即本窗口的主窗口跨多块屏幕使用全屏模式显示的状态变化。
callback Callback<boolean> 否 回调函数。即本窗口的主窗口跨多块屏幕使用全屏模式显示的状态变化回调。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有本窗口的主窗口跨多块屏幕使用全屏模式显示的状态变化回调。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
801 Capability not supported. Failed to call the API due to limited device capabilities.
1300002 This window state is abnormal. Possible cause: 1. The window is not created or destroyed; 2. Internal task error.
1300003 This window manager service works abnormally.
1300004 Unauthorized operation. Possible cause: Invalid window type. Only main windows and subwindows are supported.

示例：

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

setTopmost12+

setTopmost(isTopmost: boolean): Promise<void>

系统应用主窗口调用，实现将窗口置于所有应用窗口之上不被遮挡，使用Promise异步回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异：

在OpenHarmony 6.1之前，该接口在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

从OpenHarmony 6.1开始，该接口在支持并处于自由窗口状态的设备上可正常调用；在支持但不处于自由窗口状态的设备及不支持自由窗口状态的设备上调用返回801错误码。

参数：

参数名 类型 必填 说明
isTopmost boolean 是 是否将系统应用主窗口置顶，true表示置顶，false表示取消置顶。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system 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.
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 {
    // ...
    windowStage.getMainWindow().then((mainWindow) => {
      let isTopmost: boolean = true;
      mainWindow.setTopmost(isTopmost).then(() => {
        console.info('Succeeded in setting the main window to be topmost.');
      }).catch((err: BusinessError) => {
        console.error(`Failed to set the main window to be topmost. Cause code: ${err.code}, message: ${err.message}`);
      });
    });
  }
}

setSingleFrameComposerEnabled11+

setSingleFrameComposerEnabled(enable: boolean): Promise<void>

禁止/使能单帧合成渲染节点的功能。使用Promise异步回调。

单帧合成渲染节点的功能主要用于跟手性要求较高的场景，使能该功能之后可以降低渲染节点的上屏延时。通过setSingleFrameComposerEnabled接口，如果enable设置为true，则使能单帧合成渲染节点的功能，否则禁止单帧合成渲染节点的功能。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
enable boolean 是 设置单帧合成渲染节点的功能是否使能，true表示使能，false表示禁止。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system 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.
1300002 This window state is abnormal.

示例：

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

let enable = true;
try {
  let promise = windowClass.setSingleFrameComposerEnabled(enable);
  promise.then(()=> {
      console.info('Succeeded in enabling the single-frame-composer function.');
  }).catch((err: BusinessError)=>{
      console.error(`Failed to enable the single-frame-composer function. code:${err.code}, message:${err.message}.`);
  });
} catch (exception) {
  console.error(`Failed to enable the single-frame-composer function. Cause code: ${exception.code}, message: ${exception.message}`);
}

setTitleButtonVisible12+

setTitleButtonVisible(isMaximizeVisible: boolean, isMinimizeVisible: boolean, isSplitVisible: boolean): void

设置标题栏上的最大化、最小化、分屏按钮是否可见。

仅支持主窗和独立子窗调用此接口，其他窗口调用时将返回1300004错误码。

仅对在当前场景下可见的标题栏按钮（最大化、最小化、分屏）生效。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在支持并处于自由窗口状态的设备上可正常调用；在支持但不处于自由窗口状态的设备及不支持自由窗口状态的设备上调用返回801错误码。

参数：

参数名 类型 必填 说明
isMaximizeVisible boolean 是 设置最大化按钮是否可见，true为可见，false为隐藏。
isMinimizeVisible boolean 是 设置最小化按钮是否可见，true为可见，false为隐藏。
isSplitVisible boolean 是 设置分屏按钮是否可见，true为可见，false为隐藏。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system 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.
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 {
    // 加载主窗口对应的页面
    windowStage.loadContent('pages/Index', (err) => {
      if (err?.code) {
        console.error(`Failed to load content. Cause code: ${err.code}, message: ${err.message}`);
        return;
      }
      let mainWindow: window.Window | undefined = undefined;
      // 获取应用主窗口。
      windowStage.getMainWindow().then(
        data => {
          if (!data) {
            console.error('Failed to get main window.');
            return;
          }
          mainWindow = data;
          console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
          // 调用setTitleButtonVisible接口，隐藏主窗标题栏最大化、最小化、分屏按钮。
          mainWindow.setTitleButtonVisible(false, false, false);
        }
      ).catch((err: BusinessError) => {
          if(err.code){
            console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
          }
      });
    });
  }
}

setRotationLocked22+

setRotationLocked(locked: boolean): Promise<void>

仅支持系统窗口设置旋转锁定，锁定后系统窗口显示方向不变，未锁定时系统窗口显示方向受主窗口显示方向、旋转锁定按钮、sensor旋转影响。非系统窗口调用返回1300029错误码。使用Promise异步回调。

说明：

  • 如果在锁定期间主窗口通过setPreferredOrientation()设置显示方向属性，则解除旋转锁定后该窗口在前台还原最后一次的方向请求。

  • 如果在锁定期间系统窗口通过setPreferredOrientation()设置显示方向属性，则解除旋转锁定后该窗口在前台且层级最高时还原最后一次的方向请求。低层级窗口通过setRotationLocked设置旋转锁定不会影响高层级系统窗口调用setPreferredOrientation()设置显示方向。

  • 如果在锁定期间sensor方向发生了变化，则解除旋转锁定后还原到最后一次的sensor方向。

  • 如果在锁定期间应用调用setOrientation()设置屏幕方向，忽略该次屏幕方向设置。

  • 解除锁定时，根据主窗口的显示方向属性setPreferredOrientation()、sensor方向等决定应用显示方向，具体见窗口旋转简介。

  • 不影响应用module.json5配置文件中的abilities标签orientation属性设置的启动方向。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在Phone设备、Tablet设备和2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

参数名 类型 必填 说明
locked boolean 是 设置是否锁定旋转，true表示锁定旋转，false表示解除锁定。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed, non-system application uses system API.
801 Capability not supported. Function setRotationLocked can not work correctly due to limited device capabilities.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300029 This window type is invalid.

示例：

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

let locked: boolean = true;
let promise = windowClass.setRotationLocked(locked);
promise.then(() => {
  console.info('set rotation locked success.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set rotation locked. Cause code: ${err.code}, message: ${err.message}`);
});

getRotationLocked22+

getRotationLocked(): boolean

仅支持系统窗口获取当前旋转锁定状态。非系统窗口调用返回1300029错误码。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在Phone设备、Tablet设备和2in1设备中可正常调用，在其他设备中返回801错误码。

返回值：

类型 说明
boolean 当前系统窗是否设置旋转锁定。true表示当前系统窗已锁定旋转；false表示当前系统窗未锁定旋转。

错误码：

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

错误码ID 错误信息
202 Permission verification failed, non-system application uses system API.
801 Capability not supported. Function setRotationLocked can not work correctly due to limited device capabilities.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.
1300029 This window type is invalid.

示例：

try {
  let locked = windowClass.getRotationLocked();
  console.info('Succeeded in getting rotation locked.');
} catch (exception) {
  console.error(`Failed to get rotation locked. Cause code: ${exception.code}, message: ${exception.message}`);
};

requestFocus13+

requestFocus(isFocused: boolean): Promise<void>

支持当前窗口主动请求获焦/失焦，使用Promise异步回调。调用成功即返回，该接口返回值不代表最终获焦/失焦生效结果。可使用on('windowEvent')监听窗口获焦/失焦状态。

获焦请求发送后，窗口获焦结果受到窗口可获焦属性及窗口可见状态的限制。获焦成功的窗口需满足以下约束：1.窗口支持获焦；2.窗口可见（窗口已显示，未销毁且未退至后台）。

失焦请求发送后，窗口无条件失焦。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
isFocused boolean 是 是否获取焦点，true表示请求获焦，false表示请求失焦。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed, non-system application uses system 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.
1300002 This window state is abnormal.
1300003 This window manager service works abnormally.

示例：

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

let isFocused: boolean = true;
let promise = windowClass.requestFocus(isFocused);
promise.then(() => {
  console.info('Succeeded in requesting focus.');
}).catch((err: BusinessError) => {
  console.error(`Failed to request focus. Cause code: ${err.code}, message: ${err.message}`);
});

setWindowType(deprecated)

setWindowType(type: WindowType, callback: AsyncCallback<void>): void

设置窗口类型，使用callback异步回调。

系统接口： 此接口为系统接口。

说明：

从API version 7开始支持，从API version 9开始废弃。

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

参数：

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

示例：

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

let type = window.WindowType.TYPE_SYSTEM_ALERT;
windowClass.setWindowType(type, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to set the window type. Cause code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the window type.');
});

setWindowType(deprecated)

setWindowType(type: WindowType): Promise<void>

设置窗口类型，使用Promise异步回调。

系统接口： 此接口为系统接口。

说明：

从API version 7开始支持，从API version 9开始废弃。

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

参数：

参数名 类型 必填 说明
type WindowType 是 窗口类型。

返回值：

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

示例：

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

let type = window.WindowType.TYPE_SYSTEM_ALERT;
let promise = windowClass.setWindowType(type);
promise.then(() => {
  console.info('Succeeded in setting the window type.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set the window type. Cause code: ${err.code}, message: ${err.message}`);
});

setForbidSplitMove(deprecated)

setForbidSplitMove(isForbidSplitMove: boolean, callback: AsyncCallback<void>): void

设置主窗口在分屏模式下是否被禁止移动，使用callback异步回调。

说明：

从API version 9开始支持，从API version 26.0.0开始废弃，无替代接口。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
isForbidSplitMove boolean 是 窗口在分屏模式下是否被禁止移动。true表示禁止；false表示不禁止。
callback AsyncCallback<void> 是 回调函数。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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 isForbidSplitMove: boolean = true;
      try {
        windowClass.setForbidSplitMove(isForbidSplitMove, (err: BusinessError) => {
          const errCode: number = err.code;
          if (errCode) {
            console.error(`Failed to forbid window moving in split screen mode. Cause code: ${err.code}, message: ${err.message}`);
            return;
          }
          console.info('Succeeded in forbidding window moving in split screen mode.');
        });
      } catch (exception) {
        console.error(`Failed to forbid window moving in split screen mode. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

setForbidSplitMove(deprecated)

setForbidSplitMove(isForbidSplitMove: boolean): Promise<void>

设置主窗口在分屏模式下是否被禁止移动，使用Promise异步回调。

说明：

从API version 9开始支持，从API version 26.0.0开始废弃，无替代接口。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
isForbidSplitMove boolean 是 窗口在分屏模式下是否被禁止移动。true表示禁止；false表示不禁止。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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 isForbidSplitMove: boolean = true;
      try {
        let promise = windowClass.setForbidSplitMove(isForbidSplitMove);
        promise.then(() => {
          console.info('Succeeded in forbidding window moving in split screen mode.');
        }).catch((err: BusinessError) => {
          console.error(`Failed to forbid window moving in split screen mode. Cause code: ${err.code}, message: ${err.message}`);
        });
      } catch (exception) {
        console.error(`Failed to forbid window moving in split screen mode. Cause code: ${exception.code}, message: ${exception.message}`);
      }
    });
  }
}

SubWindowOptions11+

子窗口创建参数。

名称 类型 只读 可选 说明
isTopmost12+ boolean 否 是 子窗口是否启用置顶属性。true表示子窗口置顶，false表示子窗口不置顶。不设置，则默认为false。
系统接口： 此接口为系统接口。
系统能力： SystemCapability.Window.SessionManager

WindowStage9+

窗口管理器。管理各个基本窗口单元，即Window实例。

下列API示例中都需在onWindowStageCreate()函数中使用WindowStage的实例调用对应方法。

disableWindowDecor9+

disableWindowDecor(): void

禁止窗口装饰。

禁止窗口装饰后，当主窗口进入全屏沉浸状态时，此时鼠标Hover到上方窗口标题栏热区上会显示悬浮标题栏。若想禁用悬浮标题栏显示，请使用setTitleAndDockHoverShown()接口。

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

系统接口： 此接口为系统接口。

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
1300002 This window state is abnormal.
1300005 This window stage is abnormal.

示例：

// EntryAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';

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

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('disableWindowDecor');
    windowStage.disableWindowDecor();
  }
};

setShowOnLockScreen9+

setShowOnLockScreen(showOnLockScreen: boolean): void

设置应用显示在锁屏之上。

系统接口： 此接口为系统接口。

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

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

参数：

参数名 类型 必填 说明
showOnLockScreen boolean 是 是否设置应用显示在锁屏之上。true表示显示在锁屏之上；false表示不显示在锁屏之上。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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';

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

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('onWindowStageCreate');
    try {
      windowStage.setShowOnLockScreen(true);
    } catch (exception) {
      console.error(`Failed to show on lockscreen. Cause code: ${exception.code}, message: ${exception.message}`);
    }
  }
};

setImageForRecent19+

setImageForRecent(imgResourceId: number, value: ImageFit): Promise<void>

设置应用在多任务中显示的图片，使用Promise异步回调。

系统接口： 此接口为系统接口。

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

系统能力：SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
imgResourceId number 是 应用自定义图片的资源id，图片资源需放在resources/base/media目录下，通过$r资源访问方式获取对应图片的资源id，这里以获取startIcon图片的资源id为例给出示意：$r("app.media.startIcon").id。
value ImageFit 是 应用自定义图片的填充方式。

返回值：

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

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
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.
1300016 Parameter error. Possible cause: 1. Invalid parameter range. 2. Invalid parameter length. 3. Incorrect parameter format.

示例：

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

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

  onWindowStageCreate(windowStage: window.WindowStage) {
    let imgResourceId = $r("app.media.startIcon").id
    try {
      let promise = windowStage.setImageForRecent(imgResourceId, ImageFit.Fill);
      promise.then(() => {
        console.info(`Succeeded in setting image for recent`);
      }).catch((err: BusinessError) => {
        console.error(`Failed to set image for recent. Cause code: ${err.code}, message: ${err.message}`);
      });
    } catch (exception) {
      console.error(`Failed to set image for recent.`);
    }
  }
};

TransitionContext9+

属性转换的上下文信息。

系统接口： 此接口为系统接口。

属性

系统接口： 此接口为系统接口。

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

名称 类型 只读 可选 说明
toWindow Window 否 否 动画的目标窗口。

completeTransition9+

completeTransition(isCompleted: boolean): void

设置属性转换的最终完成状态。该函数需要在动画函数animateTo()执行后设置。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
isCompleted boolean 是 窗口属性转换是否完成。true表示完成本次转换；false表示撤销本次转换。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

(context: window.TransitionContext) => {
  let toWindow: window.Window = context.toWindow;
  this.getUIContext()?.animateTo({
    duration: 1000, // 动画时长
    tempo: 0.5, // 播放速率
    curve: Curve.EaseInOut, // 动画曲线
    delay: 0, // 动画延迟
    iterations: 1, // 播放次数
    playMode: PlayMode.Normal, // 动画模式
  }, () => {
    let obj: window.TranslateOptions = {
      x: 100.0,
      y: 0.0,
      z: 0.0
    };
    toWindow?.translate(obj);
    console.info('toWindow translate end');
  }
  );
  try {
    context.completeTransition(true)
  } catch (exception) {
    console.error(`toWindow translate fail. Cause code: ${exception.code}, message: ${exception.message}`);
  }
  console.info('complete transition end');
};

TransitionController9+

属性转换控制器。使用其子接口之前得先创建系统窗口，参照示例代码。

系统接口： 此接口为系统接口。

示例：

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

let windowClass: window.Window | undefined = undefined;
let config: window.Configuration = {
  name: "systemTypeWindow",
  windowType: window.WindowType.TYPE_PANEL, // 根据需要自选系统窗口类型
  ctx: this.context
};
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}`);
});

animationForShown9+

animationForShown(context: TransitionContext): void

窗口显示时的自定义动画配置。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
context TransitionContext 是 属性转换时的上下文。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

// xxx.ts
export class AnimationConfig {
  private animationForShownCallFunc_: ((context : window.TransitionContext) => void) | undefined = undefined;
  ShowWindowWithCustomAnimation(windowClass: window.Window, callback: (context : window.TransitionContext) => void) {
    if (!windowClass) {
      console.error('windowClass is undefined');
      return false;
    }
    this.animationForShownCallFunc_ = callback;
    let controller: window.TransitionController = windowClass.getTransitionController();
    controller.animationForShown = (context : window.TransitionContext)=> {
      this.animationForShownCallFunc_(context);
    };
    windowClass.showWithAnimation(()=>{
      console.info('Show with animation success');
    });
  }
}

// xxx.ets
let animationConfig = new AnimationConfig();
let systemTypeWindow = window.findWindow("systemTypeWindow"); // 此处需要获取一个系统类型窗口。
try {
  animationConfig?.ShowWindowWithCustomAnimation(systemTypeWindow, (context : window.TransitionContext)=>{
    console.info('complete transition end');
    let toWindow = context.toWindow;
    this.getUIContext()?.animateTo({
      duration: 1000, // 动画时长
      tempo: 0.5, // 播放速率
      curve: Curve.EaseInOut, // 动画曲线
      delay: 0, // 动画延迟
      iterations: 1, // 播放次数
      playMode: PlayMode.Normal, // 动画模式
      onFinish: () => {
        console.info('onFinish in animation');
        context.completeTransition(true)
      }
    }, () => {
      let obj : window.TranslateOptions = {
        x : 100.0,
        y : 0.0,
        z : 0.0
      };
      toWindow?.translate(obj); // 设置动画过程中的属性转换
      console.info('toWindow translate end in animation');
    });
    console.info('complete transition end');
  });
} catch (error) {
  console.error(`ShowWindowWithCustomAnimation error code: ${error.code}, message: ${error.message}`);
}

animationForHidden9+

animationForHidden(context: TransitionContext): void

窗口隐藏时的自定义动画配置。

系统接口： 此接口为系统接口。

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

参数：

参数名 类型 必填 说明
context TransitionContext 是 属性转换时的上下文。

错误码：

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

错误码ID 错误信息
202 Permission verification failed. A non-system application calls a system API.
401 Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

示例：

// xxx.ts
export class AnimationConfig {
  private animationForHiddenCallFunc_: ((context : window.TransitionContext) => void) | undefined = undefined;
  HideWindowWithCustomAnimation(windowClass: window.Window, callback: (context : window.TransitionContext) => void) {
    if (!windowClass) {
      console.error('windowClass is undefined');
      return false;
    }
    this.animationForHiddenCallFunc_ = callback;
    let controller: window.TransitionController = windowClass.getTransitionController();
    controller.animationForHidden = (context : window.TransitionContext)=> {
      this.animationForHiddenCallFunc_(context);
    };
    windowClass.hideWithAnimation(()=>{
      console.info('hide with animation success');
    });
  }
}

// xxx.ets
let animationConfig = new AnimationConfig();
let systemTypeWindow = window.findWindow("systemTypeWindow"); // 此处需要获取一个系统类型窗口。
try {
  animationConfig?.HideWindowWithCustomAnimation(systemTypeWindow, (context : window.TransitionContext)=>{
    console.info('complete transition end');
    let toWindow = context.toWindow;
    this.getUIContext()?.animateTo({
      duration: 1000, // 动画时长
      tempo: 0.5, // 播放速率
      curve: Curve.EaseInOut, // 动画曲线
      delay: 0, // 动画延迟
      iterations: 1, // 播放次数
      playMode: PlayMode.Normal, // 动画模式
      onFinish: () => {
        console.info('onFinish in animation');
        context.completeTransition(true)
      }
    }, () => {
      let obj : window.TranslateOptions = {
        x : 100.0,
        y : 0.0,
        z : 0.0
      };
      toWindow?.translate(obj); // 设置动画过程中的属性转换
      console.info('toWindow translate end in animation');
    });
    console.info('complete transition end');
  });
} catch (error) {
  console.error(`HideWindowWithCustomAnimation error code: ${error.code}, message: ${error.message}` );
}

ExtensionWindowAttribute14+

扩展窗口的属性枚举。

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

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

名称 值 说明
SYSTEM_WINDOW 0 系统窗口。
SUB_WINDOW 1 子窗口。

SystemWindowOptions14+

系统窗口的创建参数。

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

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

名称 类型 只读 可选 说明
windowType WindowType 否 否 窗口类型。无默认类型，不配置会导致窗口创建失败。不支持TYPE_DIALOG类型。

ExtensionWindowConfig14+

创建扩展窗口时需要配置的参数。

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

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

名称 类型 只读 可选 说明
windowName string 否 否 窗口名。
windowAttribute ExtensionWindowAttribute 否 否 窗口的属性。用于配置创建的窗口是子窗口还是系统窗口。当windowAttribute配置为SUB_WINDOW时须配置subWindowOptions，当windowAttribute配置为SYSTEM_WINDOW时须配置systemWindowOptions，否则创建窗口失败。
windowRect Rect 否 否 窗口矩形区域。
subWindowOptions SubWindowOptions 否 是 创建子窗口的参数。无默认参数，当windowAttribute配置为SUB_WINDOW时必选，否则会导致窗口创建失败。
systemWindowOptions SystemWindowOptions 否 是 创建系统窗口的参数。无默认参数，当windowAttribute配置为SYSTEM_WINDOW时必选，否则会导致窗口创建失败。