1# Interface (Window) 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @waterwin--> 5<!--Designer: @nyankomiya--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9> **说明：** 10> 11> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12 13当前窗口实例，窗口管理器管理的基本单元。 14 15下列API示例中都需先使用[getLastWindow()](arkts-apis-window-f.md#windowgetlastwindow9)、[createWindow()](arkts-apis-window-f.md#windowcreatewindow9)、[findWindow()](arkts-apis-window-f.md#windowfindwindow9)中的任一方法获取到Window实例（windowClass），再通过此实例调用对应方法。 16 17## 导入模块 18 19```ts 20import { window } from '@kit.ArkUI'; 21``` 22 23## showWindow<sup>9+</sup> 24 25showWindow(callback: AsyncCallback<void>): void 26 27显示当前窗口，使用callback异步回调，仅支持系统窗口与应用子窗口，或将已显示的应用主窗口层级提升至顶部。 28 29**系统能力：** SystemCapability.WindowManager.WindowManager.Core 30 31**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 32 33**参数：** 34 35| 参数名 | 类型 | 必填 | 说明 | 36| -------- | ------------------------- | -- | --------- | 37| callback | AsyncCallback<void> | 是 | 回调函数。 | 38 39**错误码：** 40 41以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 42 43| 错误码ID | 错误信息 | 44| ------- | ------------------------------ | 45| 1300002 | This window state is abnormal. | 46 47**示例：** 48 49```ts 50import { BusinessError } from '@kit.BasicServicesKit'; 51 52windowClass.showWindow((err: BusinessError) => { 53 const errCode: number = err.code; 54 if (errCode) { 55 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 56 return; 57 } 58 console.info('Succeeded in showing the window.'); 59}); 60``` 61 62## showWindow<sup>9+</sup> 63 64showWindow(): Promise<void> 65 66显示当前窗口，使用Promise异步回调，仅支持系统窗口与应用子窗口，或将已显示的应用主窗口层级提升至顶部。 67 68**系统能力：** SystemCapability.WindowManager.WindowManager.Core 69 70**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 71 72**返回值：** 73 74| 类型 | 说明 | 75| ------------------- | ----------------------- | 76| Promise<void> | 无返回结果的Promise对象。 | 77 78**错误码：** 79 80以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 81 82| 错误码ID | 错误信息 | 83| ------- | ------------------------------ | 84| 1300002 | This window state is abnormal. | 85 86**示例：** 87 88```ts 89import { BusinessError } from '@kit.BasicServicesKit'; 90 91let promise = windowClass.showWindow(); 92promise.then(() => { 93 console.info('Succeeded in showing the window.'); 94}).catch((err: BusinessError) => { 95 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 96}); 97``` 98 99## showWindow<sup>20+</sup> 100 101showWindow(options: ShowWindowOptions): Promise<void> 102 103显示当前窗口，使用Promise异步回调，仅支持系统窗口及应用子窗口，或将已显示的应用主窗口的层级提升至顶部。支持传入参数来控制窗口显示的行为。 104 105**系统能力：** SystemCapability.Window.SessionManager 106 107**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 108 109**参数：** 110 111| 参数名 | 类型 | 必填 | 说明 | 112| -------- | ------------------------- | -- | --------- | 113| options | [ShowWindowOptions](arkts-apis-window-i.md#showwindowoptions20) | 是 | 显示子窗口或系统窗口时的参数。 | 114 115**返回值：** 116 117| 类型 | 说明 | 118| ------------------- | ----------------------- | 119| Promise<void> | 无返回结果的Promise对象。 | 120 121**错误码：** 122 123以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 124 125| 错误码ID | 错误信息 | 126| ------- | ------------------------------ | 127| 801 | Capability not supported. Function showWindow can not work correctly due to limited device capabilities. | 128| 1300002 | This window state is abnormal. | 129| 1300004 | Unauthorized operation. | 130| 1300016 | Parameter validation error. Possible cause: 1. The value of the parameter is out of the allowed range; 2. The length of the parameter exceeds the allowed length; 3. The parameter format is incorrect. | 131 132**示例：** 133 134```ts 135// EntryAbility.ets 136import { window } from '@kit.ArkUI'; 137import { UIAbility } from '@kit.AbilityKit'; 138import { BusinessError } from '@kit.BasicServicesKit'; 139 140export default class EntryAbility extends UIAbility { 141 onWindowStageCreate(windowStage: window.WindowStage): void { 142 console.info('onWindowStageCreate'); 143 // 创建子窗 144 try { 145 windowStage.createSubWindow('subWindow').then((data) => { 146 if (data == null) { 147 console.error('Failed to create the sub window. Cause: The data is empty'); 148 return; 149 } 150 let options: window.ShowWindowOptions = { 151 focusOnShow: false 152 }; 153 try { 154 data.showWindow(options).then(() => { 155 console.info('Succeeded in showing window'); 156 }).catch((err: BusinessError) => { 157 console.error(`Failed to show window. Cause code: ${err.code}, message: ${err.message}`); 158 }); 159 } catch (exception) { 160 console.error(`Failed to show window. Cause code: ${exception.code}, message: ${exception.message}`); 161 } 162 }); 163 } catch (exception) { 164 console.error(`Failed to create the sub window. Cause code: ${exception.code}, message: ${exception.message}`); 165 } 166 } 167} 168``` 169 170## destroyWindow<sup>9+</sup> 171 172destroyWindow(callback: AsyncCallback<void>): void 173 174销毁当前窗口，使用callback异步回调，仅支持系统窗口及应用子窗口。 175 176**系统能力：** SystemCapability.WindowManager.WindowManager.Core 177 178**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| -------- | ------------------------- | -- | --------- | 184| callback | AsyncCallback<void> | 是 | 回调函数。 | 185 186**错误码：** 187 188以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 189 190| 错误码ID | 错误信息 | 191| ------- | -------------------------------------------- | 192| 1300002 | This window state is abnormal. | 193 194**示例：** 195 196```ts 197import { BusinessError } from '@kit.BasicServicesKit'; 198 199windowClass.destroyWindow((err) => { 200 const errCode: number = err.code; 201 if (errCode) { 202 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 203 return; 204 } 205 console.info('Succeeded in destroying the window.'); 206}); 207``` 208 209## destroyWindow<sup>9+</sup> 210 211destroyWindow(): Promise<void> 212 213销毁当前窗口，使用Promise异步回调，仅支持系统窗口及应用子窗口。 214 215**系统能力：** SystemCapability.WindowManager.WindowManager.Core 216 217**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 218 219**返回值：** 220 221| 类型 | 说明 | 222| ------------------- | ------------------------ | 223| Promise<void> | 无返回结果的Promise对象。 | 224 225**错误码：** 226 227以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 228 229| 错误码ID | 错误信息 | 230| ------- | -------------------------------------------- | 231| 1300002 | This window state is abnormal. | 232 233**示例：** 234 235```ts 236import { BusinessError } from '@kit.BasicServicesKit'; 237 238let promise = windowClass.destroyWindow(); 239promise.then(() => { 240 console.info('Succeeded in destroying the window.'); 241}).catch((err: BusinessError) => { 242 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 243}); 244``` 245 246## moveWindowTo<sup>9+</sup> 247 248moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void 249 250移动窗口位置，使用callback异步回调。调用成功即返回，但返回后无法立即获取最终生效结果。如需立即获取，请使用[moveWindowToAsync()](#movewindowtoasync12)。 251 252> **说明：** 253> 254> - 不建议在除自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）外的其他窗口模式下使用。 255> 256> - 在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，窗口相对于屏幕移动；在非自由窗口状态下，窗口相对于父窗口移动。 257> 258> - 若需在非自由窗口状态下实现相对于屏幕的移动，请使用[moveWindowToGlobal()](#movewindowtoglobal15)。 259> 260> - 该方法对非自由窗口状态下的主窗口无效。 261 262**系统能力：** SystemCapability.WindowManager.WindowManager.Core 263 264**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| -------- | ------------------------- | -- | --------------------------------------------- | 270| x | number | 是 | 窗口在x轴方向移动到的坐标位置，单位为px，值为正表示位置在x轴右侧；值为负表示位置在x轴左侧；值为0表示位置在x轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 271| y | number | 是 | 窗口在y轴方向移动到的坐标位置，单位为px，值为正表示位置在y轴下侧；值为负表示位置在y轴上侧；值为0表示位置在y轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 272| callback | AsyncCallback<void> | 是 | 回调函数。 | 273 274**错误码：** 275 276以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 277 278| 错误码ID | 错误信息 | 279| ------- | -------------------------------------------- | 280| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 281| 1300002 | This window state is abnormal. | 282| 1300003 | This window manager service works abnormally. | 283 284**示例：** 285 286```ts 287import { BusinessError } from '@kit.BasicServicesKit'; 288 289try { 290 windowClass.moveWindowTo(300, 300, (err: BusinessError) => { 291 const errCode: number = err.code; 292 if (errCode) { 293 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 294 return; 295 } 296 console.info('Succeeded in moving the window.'); 297 }); 298} catch (exception) { 299 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 300} 301``` 302 303## moveWindowTo<sup>9+</sup> 304 305moveWindowTo(x: number, y: number): Promise<void> 306 307移动窗口位置，使用Promise异步回调。调用成功即返回，但返回后无法立即获取最终生效结果。如需立即获取，请使用[moveWindowToAsync()](#movewindowtoasync12)。 308 309> **说明：** 310> 311> - 不建议在除自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）外的其他窗口模式下使用。 312> 313> - 在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，窗口相对于屏幕移动；在非自由窗口状态下，窗口相对于父窗口移动。 314> 315> - 若需在非自由窗口状态下实现相对于屏幕的移动，请使用[moveWindowToGlobal()](#movewindowtoglobal15)。 316> 317> - 该方法对非自由窗口状态下的主窗口无效。 318 319**系统能力：** SystemCapability.WindowManager.WindowManager.Core 320 321**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 322 323**参数：** 324 325| 参数名 | 类型 | 必填 | 说明 | 326| -- | ----- | -- | --------------------------------------------- | 327| x | number | 是 | 窗口在x轴方向移动到的坐标位置，单位为px，值为正表示位置在x轴右侧；值为负表示位置在x轴左侧；值为0表示位置在x轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 328| y | number | 是 | 窗口在y轴方向移动到的坐标位置，单位为px，值为正表示位置在y轴下侧；值为负表示位置在y轴上侧；值为0表示位置在y轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 329 330**返回值：** 331 332| 类型 | 说明 | 333| ------------------- | ------------------------ | 334| Promise<void> | 无返回结果的Promise对象。 | 335 336**错误码：** 337 338以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 339 340| 错误码ID | 错误信息 | 341| ------- | -------------------------------------------- | 342| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 343| 1300002 | This window state is abnormal. | 344| 1300003 | This window manager service works abnormally. | 345 346**示例：** 347 348```ts 349import { BusinessError } from '@kit.BasicServicesKit'; 350 351try { 352 let promise = windowClass.moveWindowTo(300, 300); 353 promise.then(() => { 354 console.info('Succeeded in moving the window.'); 355 }).catch((err: BusinessError) => { 356 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 357 }); 358} catch (exception) { 359 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 360} 361``` 362 363## moveWindowToAsync<sup>12+</sup> 364 365moveWindowToAsync(x: number, y: number): Promise<void> 366 367移动窗口位置，使用Promise异步回调。调用生效后返回，回调中可使用[getWindowProperties()](#getwindowproperties9)（见示例）立即获取最终生效结果。 368 369> **说明：** 370> 371> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 372> 373> - 在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，窗口相对于屏幕移动；在非自由窗口状态下，窗口相对于父窗口移动。 374> 375> - 该方法对非自由窗口状态下的主窗口无效。 376 377**系统能力：** SystemCapability.Window.SessionManager 378 379**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 380 381**参数：** 382 383| 参数名 | 类型 | 必填 | 说明 | 384| -- | ----- | -- | --------------------------------------------- | 385| x | number | 是 | 窗口在x轴方向移动到的坐标位置，单位为px，值为正表示位置在x轴右侧；值为负表示位置在x轴左侧；值为0表示位置在x轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 386| y | number | 是 | 窗口在y轴方向移动到的坐标位置，单位为px，值为正表示位置在y轴下侧；值为负表示位置在y轴上侧；值为0表示位置在y轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 387 388**返回值：** 389 390| 类型 | 说明 | 391| ------------------- | ------------------------ | 392| Promise<void> | 无返回结果的Promise对象。 | 393 394**错误码：** 395 396以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 397 398| 错误码ID | 错误信息 | 399| ------- | -------------------------------------------- | 400| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 401| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 402| 1300002 | This window state is abnormal. | 403| 1300003 | This window manager service works abnormally. | 404| 1300010 | The operation in the current window status is invalid. | 405 406**示例：** 407 408```ts 409import { BusinessError } from '@kit.BasicServicesKit'; 410 411try { 412 let promise = windowClass.moveWindowToAsync(300, 300); 413 promise.then(() => { 414 console.info('Succeeded in moving the window.'); 415 let rect = windowClass?.getWindowProperties().windowRect; 416 console.info(`Get window rect: ` + JSON.stringify(rect)); 417 }).catch((err: BusinessError) => { 418 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 419 }); 420} catch (exception) { 421 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 422} 423``` 424 425## moveWindowToAsync<sup>15+</sup> 426 427moveWindowToAsync(x: number, y: number, moveConfiguration?: MoveConfiguration): Promise<void> 428 429移动窗口位置，使用Promise异步回调。调用生效后返回，回调中可使用[getWindowProperties()](#getwindowproperties9)（见示例）立即获取最终生效结果。 430 431> **说明：** 432> 433> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 434> 435> - 在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，窗口相对于屏幕移动；在非自由窗口状态下，窗口相对于父窗口移动。 436> 437> - 该方法对非自由窗口状态下的主窗口无效。 438 439**系统能力：** SystemCapability.Window.SessionManager 440 441**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 442 443**参数：** 444 445| 参数名 | 类型 | 必填 | 说明 | 446| -- | ----- | -- | --------------------------------------------- | 447| x | number | 是 | 窗口在x轴方向移动的值，值为正表示右移，单位为px，该参数应该为整数，非整数输入将向下取整。 | 448| y | number | 是 | 窗口在y轴方向移动的值，值为正表示下移，单位为px，该参数应该为整数，非整数输入将向下取整。 | 449| moveConfiguration | [MoveConfiguration](arkts-apis-window-i.md#moveconfiguration15) | 否 | 窗口移动选项，未设置将默认保持为当前屏幕。 | 450 451**返回值：** 452 453| 类型 | 说明 | 454| ------------------- | ------------------------ | 455| Promise<void> | 无返回结果的Promise对象。 | 456 457**错误码：** 458 459以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 460 461| 错误码ID | 错误信息 | 462| ------- | -------------------------------------------- | 463| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 464| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 465| 1300002 | This window state is abnormal. | 466| 1300003 | This window manager service works abnormally. | 467| 1300010 | The operation in the current window status is invalid. | 468 469**示例：** 470 471```ts 472import { window } from '@kit.ArkUI'; 473import { BusinessError } from '@kit.BasicServicesKit'; 474 475try { 476 let moveConfiguration: window.MoveConfiguration = { 477 displayId: 0 478 }; 479 let promise = windowClass.moveWindowToAsync(300, 300, moveConfiguration); 480 promise.then(() => { 481 console.info('Succeeded in moving the window.'); 482 let rect = windowClass?.getWindowProperties().windowRect; 483 console.info(`Get window rect: ` + JSON.stringify(rect)); 484 }).catch((err: BusinessError) => { 485 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 486 }); 487} catch (exception) { 488 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 489} 490``` 491 492## moveWindowToGlobal<sup>13+</sup> 493 494moveWindowToGlobal(x: number, y: number): Promise<void> 495 496基于屏幕坐标移动窗口位置，使用Promise异步回调。调用生效后返回，回调中可使用[getWindowProperties()](#getwindowproperties9)（见示例）立即获取最终生效结果。 497 498> **说明：** 499> 500> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 501> 502> - 该方法对非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下的主窗口无效。 503 504 505**系统能力：** SystemCapability.Window.SessionManager 506 507**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 508 509**参数：** 510 511| 参数名 | 类型 | 必填 | 说明 | 512| -- | ----- | -- | --------------------------------------------- | 513| x | number | 是 | 表示以屏幕左上角为起点，窗口在x轴方向移动的值，单位为px。值为正表示右移，值为负表示左移。该参数仅支持整数输入，浮点数输入将向下取整。 | 514| y | number | 是 | 表示以屏幕左上角为起点，窗口在y轴方向移动的值，单位为px。值为正表示下移，值为负表示上移。该参数仅支持整数输入，浮点数输入将向下取整。 | 515 516**返回值：** 517 518| 类型 | 说明 | 519| ------------------- | ------------------------ | 520| Promise<void> | 无返回结果的Promise对象。 | 521 522**错误码：** 523 524以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 525 526| 错误码ID | 错误信息 | 527| ------- | -------------------------------------------- | 528| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 529| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 530| 1300002 | This window state is abnormal. | 531| 1300003 | This window manager service works abnormally. | 532| 1300010 | The operation in the current window status is invalid. | 533 534**示例：** 535 536```ts 537import { BusinessError } from '@kit.BasicServicesKit'; 538 539try { 540 let promise = windowClass.moveWindowToGlobal(300, 300); 541 promise.then(() => { 542 console.info('Succeeded in moving the window.'); 543 let rect = windowClass?.getWindowProperties().windowRect; 544 console.info(`Get window rect: ` + JSON.stringify(rect)); 545 }).catch((err: BusinessError) => { 546 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 547 }); 548} catch (exception) { 549 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 550} 551``` 552 553## moveWindowToGlobal<sup>15+</sup> 554 555moveWindowToGlobal(x: number, y: number, moveConfiguration?: MoveConfiguration): Promise<void> 556 557基于屏幕坐标移动窗口位置，使用Promise异步回调。调用生效后返回，回调中可使用[getWindowProperties()](#getwindowproperties9)（见示例）立即获取最终生效结果。 558 559> **说明：** 560> 561> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 562> 563> - 该方法对非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下的主窗口无效。 564 565**系统能力：** SystemCapability.Window.SessionManager 566 567**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 568 569**参数：** 570 571| 参数名 | 类型 | 必填 | 说明 | 572| -- | ----- | -- | --------------------------------------------- | 573| x | number | 是 | 表示以目标屏幕左上角为起点，窗口在x轴方向移动的值，单位为px。值为正表示右移，值为负表示左移。该参数应该为整数，非整数输入将向下取整。 | 574| y | number | 是 | 表示以目标屏幕左上角为起点，窗口在y轴方向移动的值，单位为px。值为正表示下移，值为负表示上移。该参数应该为整数，非整数输入将向下取整。 | 575| moveConfiguration | [MoveConfiguration](arkts-apis-window-i.md#moveconfiguration15) | 否 | 窗口移动选项，未设置将默认保持为当前屏幕。 | 576 577**返回值：** 578 579| 类型 | 说明 | 580| ------------------- | ------------------------ | 581| Promise<void> | 无返回结果的Promise对象。 | 582 583**错误码：** 584 585以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 586 587| 错误码ID | 错误信息 | 588| ------- | -------------------------------------------- | 589| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 590| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 591| 1300002 | This window state is abnormal. | 592| 1300003 | This window manager service works abnormally. | 593| 1300010 | The operation in the current window status is invalid. | 594 595**示例：** 596 597```ts 598import { window } from '@kit.ArkUI'; 599import { BusinessError } from '@kit.BasicServicesKit'; 600 601try { 602 let moveConfiguration: window.MoveConfiguration = { 603 displayId: 0 604 }; 605 let promise = windowClass.moveWindowToGlobal(300, 300, moveConfiguration); 606 promise.then(() => { 607 console.info('Succeeded in moving the window.'); 608 let rect = windowClass?.getWindowProperties().windowRect; 609 console.info(`Get window rect: ` + JSON.stringify(rect)); 610 }).catch((err: BusinessError) => { 611 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 612 }); 613} catch (exception) { 614 console.error(`Failed to move the window. Cause code: ${exception.code}, message: ${exception.message}`); 615} 616``` 617 618## moveWindowToGlobalDisplay<sup>20+</sup> 619 620moveWindowToGlobalDisplay(x: number, y: number): Promise<void> 621 622基于全局坐标系（扩展屏场景下，以主屏幕左上角为原点）移动窗口位置，使用Promise异步回调。 623 624> **说明：** 625> 626> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 627> 628> - 该方法对非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下的主窗口无效。 629 630**系统能力：** SystemCapability.Window.SessionManager 631 632**参数：** 633 634| 参数名 | 类型 | 必填 | 说明 | 635| -- | ----- | -- | --------------------------------------------- | 636| x | number | 是 | 表示以主屏幕左上角为起点，窗口在x轴方向移动的值，单位为px。值为正表示右移，值为负表示左移。该参数应该为整数，非整数输入将向下取整。 | 637| y | number | 是 | 表示以主屏幕左上角为起点，窗口在y轴方向移动的值，单位为px。值为正表示下移，值为负表示上移。该参数应该为整数，非整数输入将向下取整。 | 638 639**返回值：** 640 641| 类型 | 说明 | 642| ------------------- | ------------------------ | 643| Promise<void> | 无返回结果的Promise对象。 | 644 645**错误码：** 646 647以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 648 649| 错误码ID | 错误信息 | 650| ------- | -------------------------------------------- | 651| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 652| 1300002 | This window state is abnormal. | 653| 1300003 | This window manager service works abnormally. | 654| 1300010 | The operation in the current window status is invalid. | 655| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range. | 656 657**示例：** 658 659```ts 660import { BusinessError } from '@kit.BasicServicesKit'; 661 662try { 663 let promise = windowClass.moveWindowToGlobalDisplay(300, 300); 664 promise.then(() => { 665 console.info('Succeeded in moving the window in global display.'); 666 }).catch((err: BusinessError) => { 667 console.error(`Failed to move the window in global display. Cause code: ${err.code}, message: ${err.message}`); 668 }); 669} catch (exception) { 670 console.error(`Failed to move the window in global display. Cause code: ${exception.code}, message: ${exception.message}`); 671} 672``` 673 674## clientToGlobalDisplay<sup>20+</sup> 675 676clientToGlobalDisplay(winX: number, winY: number): Position 677 678将相对于当前窗口左上角的坐标转换为相对于主屏幕左上角的全局坐标。 679 680不支持在经过显示缩放的窗口中调用，例如手机或平板设备在非自由多窗模式下的悬浮窗场景。 681 682**系统能力：** SystemCapability.Window.SessionManager 683 684**参数：** 685 686| 参数名 | 类型 | 必填 | 说明 | 687| -- | ----- | -- | --------------------------------------------- | 688| winX | number | 是 | 表示以当前窗口左上角为起点，组件在x轴方向移动的值，单位为px。值为正表示右移，值为负表示左移。该参数应该为整数，非整数输入将向下取整。 | 689| winY | number | 是 | 表示以当前窗口左上角为起点，组件在y轴方向移动的值，单位为px。值为正表示下移，值为负表示上移。该参数应该为整数，非整数输入将向下取整。 | 690 691**返回值：** 692 693| 类型 | 说明 | 694| ------------------- | ------------------------ | 695| [Position](arkts-apis-window-i.md#position20) | 返回转换后的坐标。 | 696 697**错误码：** 698 699以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 700 701| 错误码ID | 错误信息 | 702| ------- | -------------------------------------------- | 703| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 704| 1300002 | This window state is abnormal. | 705| 1300010 | The operation in the current window status is invalid. | 706| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range. | 707 708**示例：** 709 710```ts 711try { 712 let position = windowClass.clientToGlobalDisplay(100, 100); 713 console.info(`Succeeded in converting the position in the current window to the position in global display. Position: ` + JSON.stringify(position)); 714} catch (exception) { 715 console.error(`Failed to convert the position. Cause code: ${exception.code}, message: ${exception.message}`); 716} 717``` 718 719## globalDisplayToClient<sup>20+</sup> 720 721globalDisplayToClient(globalDisplayX: number, globalDisplayY: number): Position 722 723将相对于主屏幕左上角的全局坐标转换为相对于当前窗口左上角的坐标。 724 725不支持在经过显示缩放的窗口中调用，例如手机或平板设备在非自由多窗模式下的悬浮窗场景。 726 727**系统能力：** SystemCapability.Window.SessionManager 728 729**参数：** 730 731| 参数名 | 类型 | 必填 | 说明 | 732| -- | ----- | -- | --------------------------------------------- | 733| globalDisplayX | number | 是 | 表示以主屏幕左上角为起点，组件在x轴方向移动的值，单位为px。值为正表示右移，值为负表示左移。该参数应该为整数，非整数输入将向下取整。 | 734| globalDisplayY | number | 是 | 表示以主屏幕左上角为起点，组件在y轴方向移动的值，单位为px。值为正表示下移，值为负表示上移。该参数应该为整数，非整数输入将向下取整。 | 735 736**返回值：** 737 738| 类型 | 说明 | 739| ------------------- | ------------------------ | 740| [Position](arkts-apis-window-i.md#position20) | 返回转换后的坐标。 | 741 742**错误码：** 743 744以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 745 746| 错误码ID | 错误信息 | 747| ------- | -------------------------------------------- | 748| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 749| 1300002 | This window state is abnormal. | 750| 1300010 | The operation in the current window status is invalid. | 751| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range. | 752 753**示例：** 754 755```ts 756try { 757 let position = windowClass.globalDisplayToClient(100, 100); 758 console.info(`Succeeded in converting in the position in global display to the position in the current window. Position: ` + JSON.stringify(position)); 759} catch (exception) { 760 console.error(`Failed to convert the position. Cause code: ${exception.code}, message: ${exception.message}`); 761} 762``` 763 764## resize<sup>9+</sup> 765 766resize(width: number, height: number, callback: AsyncCallback<void>): void 767 768改变当前窗口大小，使用callback异步回调。 769 770窗口存在大小限制[WindowLimits](arkts-apis-window-i.md#windowlimits11)，具体尺寸限制范围可以通过[getWindowLimits](#getwindowlimits11)接口进行查询。 771 772调用该接口设置的宽度与高度受到此约束限制，规则： 773若所设置的窗口宽/高尺寸小于窗口最小宽/高限值，则窗口最小宽/高限值生效； 774若所设置的窗口宽/高尺寸大于窗口最大宽/高限值，则窗口最大宽/高限值生效。 775 776> **说明：** 777> 778> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 779> 780> - 该方法对非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下的主窗口无效。 781 782**系统能力：** SystemCapability.WindowManager.WindowManager.Core 783 784**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 785 786**参数：** 787 788| 参数名 | 类型 | 必填 | 说明 | 789| -------- | ------------------------- | -- | ------------------------ | 790| width | number | 是 | 目标窗口的宽度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 791| height | number | 是 | 目标窗口的高度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 792| callback | AsyncCallback<void> | 是 | 回调函数。 | 793 794**错误码：** 795 796以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 797 798| 错误码ID | 错误信息 | 799| ------- | -------------------------------------------- | 800| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 801| 1300002 | This window state is abnormal. | 802| 1300003 | This window manager service works abnormally. | 803 804**示例：** 805 806```ts 807import { BusinessError } from '@kit.BasicServicesKit'; 808 809try { 810 windowClass.resize(500, 1000, (err: BusinessError) => { 811 const errCode: number = err.code; 812 if (errCode) { 813 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 814 return; 815 } 816 console.info('Succeeded in changing the window size.'); 817 }); 818} catch (exception) { 819 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 820} 821``` 822 823## resize<sup>9+</sup> 824 825resize(width: number, height: number): Promise<void> 826 827改变当前窗口大小，使用Promise异步回调。调用成功即返回，该接口返回后无法立即获取最终生效结果，如需立即获取，建议使用接口[resizeAsync()](#resizeasync12)。 828 829窗口存在大小限制[WindowLimits](arkts-apis-window-i.md#windowlimits11)，具体尺寸限制范围可以通过[getWindowLimits](#getwindowlimits11)接口进行查询。 830 831调用该接口设置的宽度与高度受到此约束限制，规则： 832若所设置的窗口宽/高尺寸小于窗口最小宽/高限值，则窗口最小宽/高限值生效； 833若所设置的窗口宽/高尺寸大于窗口最大宽/高限值，则窗口最大宽/高限值生效。 834 835> **说明：** 836> 837> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 838> 839> - 该方法对非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下的主窗口无效。 840 841**系统能力：** SystemCapability.WindowManager.WindowManager.Core 842 843**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 844 845**参数：** 846 847| 参数名 | 类型 | 必填 | 说明 | 848| ------ | ------ | -- | ------------------------ | 849| width | number | 是 | 目标窗口的宽度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 850| height | number | 是 | 目标窗口的高度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 851 852**返回值：** 853 854| 类型 | 说明 | 855| ------------------- | ------------------------ | 856| Promise<void> | 无返回结果的Promise对象。 | 857 858**错误码：** 859 860以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 861 862| 错误码ID | 错误信息 | 863| ------- | -------------------------------------------- | 864| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 865| 1300002 | This window state is abnormal. | 866| 1300003 | This window manager service works abnormally. | 867 868**示例：** 869 870```ts 871import { BusinessError } from '@kit.BasicServicesKit'; 872 873try { 874 let promise = windowClass.resize(500, 1000); 875 promise.then(() => { 876 console.info('Succeeded in changing the window size.'); 877 }).catch((err: BusinessError) => { 878 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 879 }); 880} catch (exception) { 881 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 882} 883``` 884 885## resizeAsync<sup>12+</sup> 886 887resizeAsync(width: number, height: number): Promise<void> 888 889改变当前窗口大小，使用Promise异步回调。调用生效后返回，回调中可使用[getWindowProperties()](#getwindowproperties9)（见示例）立即获取最终生效结果。 890 891窗口存在大小限制[WindowLimits](arkts-apis-window-i.md#windowlimits11)，具体尺寸限制范围可以通过[getWindowLimits](#getwindowlimits11)接口进行查询。 892 893调用该接口设置的宽度与高度受到此约束限制，规则： 894若所设置的窗口宽/高尺寸小于窗口最小宽/高限值，则窗口最小宽/高限值生效； 895若所设置的窗口宽/高尺寸大于窗口最大宽/高限值，则窗口最大宽/高限值生效。 896 897> **说明：** 898> 899> - 仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING，WindowStatusType可通过[getWindowStatus()](#getwindowstatus12)获取）下支持该操作。 900> 901> - 该方法对非[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下的主窗口无效。 902 903**系统能力：** SystemCapability.Window.SessionManager 904 905**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 906 907**参数：** 908 909| 参数名 | 类型 | 必填 | 说明 | 910| ------ | ------ | -- | ------------------------ | 911| width | number | 是 | 目标窗口的宽度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 912| height | number | 是 | 目标窗口的高度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 913 914**返回值：** 915 916| 类型 | 说明 | 917| ------------------- | ------------------------ | 918| Promise<void> | 无返回结果的Promise对象。 | 919 920**错误码：** 921 922以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 923 924| 错误码ID | 错误信息 | 925| ------- | -------------------------------------------- | 926| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 927| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 928| 1300002 | This window state is abnormal. | 929| 1300003 | This window manager service works abnormally. | 930| 1300010 | The operation in the current window status is invalid. | 931 932**示例：** 933 934```ts 935import { BusinessError } from '@kit.BasicServicesKit'; 936 937try { 938 let promise = windowClass.resizeAsync(500, 1000); 939 promise.then(() => { 940 console.info('Succeeded in changing the window size.'); 941 let rect = windowClass?.getWindowProperties().windowRect; 942 console.info(`Get window rect: ` + JSON.stringify(rect)); 943 }).catch((err: BusinessError) => { 944 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 945 }); 946} catch (exception) { 947 console.error(`Failed to change the window size. Cause code: ${exception.code}, message: ${exception.message}`); 948} 949``` 950 951## getWindowProperties<sup>9+</sup> 952 953getWindowProperties(): WindowProperties 954 955获取当前窗口的属性，返回WindowProperties。 956 957**系统能力：** SystemCapability.WindowManager.WindowManager.Core 958 959**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 960 961**返回值：** 962 963| 类型 | 说明 | 964| ------------------------------------- | ------------- | 965| [WindowProperties](arkts-apis-window-i.md#windowproperties) | 当前窗口属性。 | 966 967**错误码：** 968 969以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 970 971| 错误码ID | 错误信息 | 972| ------- | ------------------------------ | 973| 1300002 | This window state is abnormal. | 974 975**示例：** 976 977```ts 978try { 979 let properties = windowClass.getWindowProperties(); 980} catch (exception) { 981 console.error(`Failed to obtain the window properties. Cause code: ${exception.code}, message: ${exception.message}`); 982} 983``` 984 985## getWindowDensityInfo<sup>15+</sup> 986 987getWindowDensityInfo(): WindowDensityInfo 988 989获取当前窗口所在屏幕的系统显示大小缩放系数、系统默认显示大小缩放系数和自定义显示大小缩放系数信息。 990 991**系统能力：** SystemCapability.Window.SessionManager 992 993**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 994 995**返回值：** 996 997| 类型 | 说明 | 998| ------------------------------------- | ------------- | 999| [WindowDensityInfo](arkts-apis-window-i.md#windowdensityinfo15) | 当前窗口的显示大小缩放系数信息。当返回值为[-1, -1, -1]时，表示当前设备不支持使用该接口。 | 1000 1001**错误码：** 1002 1003以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1004 1005| 错误码ID | 错误信息 | 1006| ------- | ------------------------------ | 1007| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1008| 1300002 | This window state is abnormal. | 1009 1010**示例：** 1011 1012```ts 1013try { 1014 let densityInfo = windowClass.getWindowDensityInfo(); 1015} catch (exception) { 1016 console.error(`Failed to obtain the window densityInfo. Cause code: ${exception.code}, message: ${exception.message}`); 1017} 1018``` 1019 1020## setWindowContainerColor<sup>20+</sup> 1021 1022setWindowContainerColor(activeColor: string, inactiveColor: string): void 1023 1024设置主窗口容器在焦点态和非焦点态时的背景色。在Stage模型下，该接口需在调用[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)后使用。 1025 1026窗口容器背景色覆盖整个窗口区域，包括标题栏和内容区域。当同时使用该接口和[setWindowBackgroundColor()](#setwindowbackgroundcolor9)设置背景色时，内容区域显示窗口背景色，标题栏显示窗口容器背景色。 1027 1028**系统能力：** SystemCapability.Window.SessionManager 1029 1030**设备行为差异：** 该接口在2in1设备中可正常调用，在其他设备中返回801错误码。 1031 1032**需要权限：** ohos.permission.SET_WINDOW_TRANSPARENT 1033 1034**参数：** 1035 1036| 参数名 | 类型 | 必填 | 说明 | 1037| ----- | ------ | -- | ----------------------------------------------------------------------- | 1038| activeColor | string | 是 | 窗口容器处于焦点态时的背景色，为十六进制RGB或ARGB颜色，不区分大小写，例如`'#00FF00'`或`'#FF00FF00'`。| 1039| inactiveColor | string | 是 | 窗口容器处于非焦点态时的背景色，为十六进制RGB颜色或ARGB颜色（透明度固定为`'FF'`），不区分大小写，例如`'#00FF00'`或`'#FF00FF00'`。| 1040 1041**错误码：** 1042 1043以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1044 1045| 错误码ID | 错误信息 | 1046| ------- | ------------------------------ | 1047| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1048| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1049| 1300002 | This window state is abnormal. | 1050| 1300004 | Unauthorized operation. | 1051 1052**示例：** 1053 1054```ts 1055// EntryAbility.ets 1056import { UIAbility } from '@kit.AbilityKit'; 1057import { BusinessError } from '@kit.BasicServicesKit'; 1058 1059export default class EntryAbility extends UIAbility { 1060 onWindowStageCreate(windowStage: window.WindowStage) { 1061 windowStage.loadContent("pages/page2", (err: BusinessError) => { 1062 let errCode: number = err.code; 1063 if (errCode) { 1064 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 1065 return; 1066 } 1067 console.info('Succeeded in loading the content.'); 1068 // 获取应用主窗口。 1069 let windowClass: window.Window | undefined = undefined; 1070 windowStage.getMainWindow((err: BusinessError, data) => { 1071 let errCode: number = err.code; 1072 if (errCode) { 1073 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1074 return; 1075 } 1076 windowClass = data; 1077 let activeColor: string = '#00000000'; 1078 let inactiveColor: string = '#FF000000'; 1079 try { 1080 windowClass.setWindowContainerColor(activeColor, inactiveColor); 1081 console.info('Succeeded in setting window container color.'); 1082 } catch (exception) { 1083 console.error(`Failed to set the window container color. Cause code: ${exception.code}, message: ${exception.message}`); 1084 }; 1085 }); 1086 }); 1087 } 1088} 1089``` 1090 1091## getGlobalRect<sup>13+</sup> 1092 1093getGlobalRect(): Rect 1094 1095获取窗口在屏幕上的真实显示区域，同步接口。 1096 1097在某些设备上，窗口显示时可能经过了缩放，此接口可以获取缩放后窗口在屏幕上的真实位置和大小。 1098 1099**系统能力：** SystemCapability.Window.SessionManager 1100 1101**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 1102 1103**返回值：** 1104 1105| 类型 | 说明 | 1106| ------------------- | ------------------------ | 1107| [Rect](arkts-apis-window-i.md#rect7) | 四元组分别表示距离屏幕左上角的x坐标、距离屏幕左上角的y坐标、缩放后的窗口宽度和缩放后的窗口高度。 | 1108 1109**错误码：** 1110 1111以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1112 1113| 错误码ID | 错误信息 | 1114| ------- | -------------------------------------------- | 1115| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1116| 1300002 | This window state is abnormal. | 1117| 1300003 | This window manager service works abnormally. | 1118 1119**示例：** 1120 1121```ts 1122try { 1123 let rect = windowClass.getGlobalRect(); 1124 console.info(`Succeeded in getting window rect: ` + JSON.stringify(rect)); 1125} catch (exception) { 1126 console.error(`Failed to get window rect. Cause code: ${exception.code}, message: ${exception.message}`); 1127} 1128``` 1129 1130## getWindowAvoidArea<sup>9+</sup> 1131 1132getWindowAvoidArea(type: AvoidAreaType): AvoidArea 1133 1134获取当前应用窗口避让区。避让区指系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时，需要窗口内容避让的区域。 1135 1136[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，当前窗口调用该接口获取到空的避让区。 1137 1138非自由窗口状态下，仅当子窗口的位置和大小与主窗口一致时，子窗口调用该接口才能计算避让区并返回，否则直接返回空的避让区。 1139 1140该接口一般适用于三种场景：1、在onWindowStageCreate方法中，获取应用启动时的初始布局避让区域时可调用该接口；2、当应用内子窗需要临时显示，对显示内容做布局避让时可调用该接口；3、创建悬浮窗、模态窗或WindowType窗口类型为系统窗口时，调用[setSystemAvoidAreaEnabled](#setsystemavoidareaenabled18)方法使能后，该接口对此类窗口亦生效。 1141 1142**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1143 1144**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1145 1146**参数：** 1147 1148| 参数名 | 类型 | 必填 | 说明 | 1149| ---- |----------------------------------| -- | ------------------------------------------------------------ | 1150| type | [AvoidAreaType](arkts-apis-window-e.md#avoidareatype7) | 是 | 表示规避区类型。 | 1151 1152**返回值：** 1153 1154| 类型 | 说明 | 1155|--------------------------| ----------------- | 1156| [AvoidArea](arkts-apis-window-i.md#avoidarea7) | 窗口内容规避区域。 | 1157 1158**错误码：** 1159 1160以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1161 1162| 错误码ID | 错误信息 | 1163| ------- | ------------------------------ | 1164| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1165| 1300002 | This window state is abnormal. | 1166 1167**示例：** 1168 1169```ts 1170let type = window.AvoidAreaType.TYPE_SYSTEM; 1171try { 1172 let avoidArea = windowClass.getWindowAvoidArea(type); 1173} catch (exception) { 1174 console.error(`Failed to obtain the area. Cause code: ${exception.code}, message: ${exception.message}`); 1175} 1176``` 1177 1178## setSystemAvoidAreaEnabled<sup>18+</sup> 1179 1180setSystemAvoidAreaEnabled(enabled: boolean): Promise<void> 1181 1182创建悬浮窗、模态窗或WindowType窗口类型为系统窗口时，可以调用该接口使能窗口获取避让区[AvoidArea](arkts-apis-window-i.md#avoidarea7)。 1183 1184该接口一般适用于此场景：应用于创建上述类型窗口并希望获取避让区信息时，需要在创建窗口后调用该接口设置使能该窗口，再调用[getWindowAvoidArea()](#getwindowavoidarea9)或[on('avoidAreaChange')](#onavoidareachange9)获取或监听避让区。 1185 1186**系统能力：** SystemCapability.Window.SessionManager 1187 1188**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1189 1190**参数：** 1191 1192| 参数名 | 类型 | 必填 | 说明 | 1193| ---- |----------------------------------| -- | ------------------------------------------------------------ | 1194| enabled | boolean | 是 | 是否可以获取到避让区。<br> true表示可以获取避让区；false表示不可以获取避让区。默认值是false。 | 1195 1196**返回值：** 1197 1198| 类型 | 说明 | 1199| ------------------- | ----------------------- | 1200| Promise<void> | 无返回结果的Promise对象。 | 1201 1202**错误码：** 1203 1204以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1205 1206| 错误码ID | 错误信息 | 1207| ------- | ------------------------------ | 1208| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1209| 1300002 | This window state is abnormal. | 1210| 1300003 | This window manager service works abnormally. | 1211| 1300004 | Unauthorized operation. | 1212 1213**示例：** 1214 1215```ts 1216import { BusinessError } from '@kit.BasicServicesKit'; 1217 1218let windowClass: window.Window | undefined = undefined; 1219let config: window.Configuration = { 1220 name: "test", 1221 windowType: window.WindowType.TYPE_DIALOG, 1222 decorEnabled: true, 1223 ctx: this.context 1224}; 1225try { 1226 window.createWindow(config, (err: BusinessError, data) => { 1227 const errCode: number = err.code; 1228 if (errCode) { 1229 console.error(`Failed to create the system window. Cause code: ${err.code}, message: ${err.message}`); 1230 return; 1231 } 1232 windowClass = data; 1233 windowClass.setUIContent("pages/Test"); 1234 let enabled = true; 1235 let promise = windowClass.setSystemAvoidAreaEnabled(enabled); 1236 promise.then(() => { 1237 let type = window.AvoidAreaType.TYPE_SYSTEM; 1238 let avoidArea = windowClass?.getWindowAvoidArea(type); 1239 }).catch((err: BusinessError) => { 1240 console.error(`Failed to obtain the system window avoid area. Cause code: ${err.code}, message: ${err.message}`); 1241 }); 1242 }); 1243} catch (exception) { 1244 console.error(`Failed to create the system window. Cause code: ${exception.code}, message: ${exception.message}`); 1245} 1246``` 1247 1248## isSystemAvoidAreaEnabled<sup>18+</sup> 1249 1250isSystemAvoidAreaEnabled(): boolean 1251 1252获取悬浮窗、模态窗或WindowType为系统类型的窗口是否可以获取窗口内容的避让区[AvoidArea](arkts-apis-window-i.md#avoidarea7)。 1253 1254**系统能力：** SystemCapability.Window.SessionManager 1255 1256**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1257 1258**返回值：** 1259 1260| 类型 | 说明 | 1261| ------------------------------------- | ------------- | 1262| boolean | 是否可以获取窗口内容的避让区。<br> true表示可以获取避让区；false表示不可以获取避让区。 | 1263 1264**错误码：** 1265 1266以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1267 1268| 错误码ID | 错误信息 | 1269| ------- | ------------------------------ | 1270| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1271| 1300002 | This window state is abnormal. | 1272| 1300003 | This window manager service works abnormally. | 1273| 1300004 | Unauthorized operation. | 1274 1275**示例：** 1276 1277```ts 1278import { BusinessError } from '@kit.BasicServicesKit'; 1279 1280let windowClass: window.Window | undefined = undefined; 1281let config: window.Configuration = { 1282 name: "test", 1283 windowType: window.WindowType.TYPE_DIALOG, 1284 decorEnabled: true, 1285 ctx: this.context 1286}; 1287try { 1288 window.createWindow(config, (err: BusinessError, data) => { 1289 const errCode: number = err.code; 1290 if (errCode) { 1291 console.error(`Failed to create the system window. Cause code: ${err.code}, message: ${err.message}`); 1292 return; 1293 } 1294 windowClass = data; 1295 windowClass.setUIContent("pages/Test"); 1296 let enabled = true; 1297 let promise = windowClass.setSystemAvoidAreaEnabled(enabled); 1298 promise.then(() => { 1299 let enable = windowClass?.isSystemAvoidAreaEnabled(); 1300 }).catch((err: BusinessError) => { 1301 console.error(`Failed to obtain whether the system window can get avoid area. Cause code: ${err.code}, message: ${err.message}`); 1302 }); 1303 }); 1304} catch (exception) { 1305 console.error(`Failed to create the system window. Cause code: ${exception.code}, message: ${exception.message}`); 1306} 1307``` 1308 1309## setTitleAndDockHoverShown<sup>14+</sup> 1310 1311setTitleAndDockHoverShown(isTitleHoverShown?: boolean, isDockHoverShown?: boolean): Promise<void> 1312 1313该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于设置主窗口进入全屏模式时鼠标Hover到热区上是否显示窗口标题栏和dock栏，使用Promise异步回调。 1314 1315**系统能力**：SystemCapability.Window.SessionManager 1316 1317**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 1318 1319**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1320 1321**参数：** 1322 1323| 参数名 | 类型 | 必填 | 说明 | 1324| ---------- | ------- | ---- | ------------------------------------------------------------ | 1325| isTitleHoverShown | boolean | 否 | 是否显示窗口标题栏。<br>true表示显示窗口标题栏；false表示不显示窗口标题栏。默认值是true。</br> | 1326| isDockHoverShown | boolean | 否 | 是否显示dock栏。<br>true表示显示dock栏；false表示不显示dock栏。默认值是true。</br> | 1327 1328**返回值：** 1329 1330| 类型 | 说明 | 1331| ------------------- | ------------------------- | 1332| Promise<void> | 无返回结果的Promise对象。 | 1333 1334**错误码：** 1335 1336以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1337 1338| 错误码ID | 错误信息 | 1339| ------- | -------------------------------------------- | 1340| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1341| 1300002 | This window state is abnormal. | 1342| 1300004 | Unauthorized operation. | 1343 1344**示例：** 1345 1346```ts 1347// EntryAbility.ets 1348import { UIAbility } from '@kit.AbilityKit'; 1349import { BusinessError } from '@kit.BasicServicesKit'; 1350import { window } from '@kit.ArkUI'; 1351 1352export default class EntryAbility extends UIAbility { 1353 // ... 1354 onWindowStageCreate(windowStage: window.WindowStage): void { 1355 // 加载主窗口对应的页面。 1356 windowStage.loadContent('pages/Index', (err) => { 1357 let mainWindow: window.Window | undefined = undefined; 1358 // 获取应用主窗口。 1359 windowStage.getMainWindow().then( 1360 data => { 1361 if (!data) { 1362 console.error('Failed to get main window. Cause: The data is undefined.'); 1363 return; 1364 } 1365 mainWindow = data; 1366 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 1367 // 调用maximize接口，设置窗口进入全屏模式。 1368 mainWindow.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 1369 // 调用setTitleAndDockHoverShown接口，隐藏标题栏和dock栏。 1370 mainWindow.setTitleAndDockHoverShown(false, false); 1371 } 1372 ).catch((err: BusinessError) => { 1373 if(err.code){ 1374 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1375 } 1376 }); 1377 }); 1378 } 1379} 1380``` 1381 1382## setWindowLayoutFullScreen<sup>9+</sup> 1383 1384setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 1385 1386设置主窗口或子窗口的布局是否为沉浸式布局，使用Promise异步回调。系统窗口调用不生效。 1387沉浸式布局生效时，布局不避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件可能产生与其重叠的情况。 1388非沉浸式布局生效时，布局避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件不会与其重叠。 1389 1390**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1391 1392**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1393 1394**设备行为差异：** API version 14之前，该接口在所有设备中可正常调用。从API version 14开始，该接口在2in1设备、Tablet设备的[自由多窗模式](../../windowmanager/window-terminology.md#自由多窗模式)下调用不生效也不报错，在其他设备中可正常调用。 1395 1396**参数：** 1397 1398| 参数名 | 类型 | 必填 | 说明 | 1399| ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ | 1400| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局（该沉浸式布局状态栏、<!--RP15-->三键导航栏<!--RP15End-->仍然显示）。true表示沉浸式布局；false表示非沉浸式布局。 | 1401 1402**返回值：** 1403 1404| 类型 | 说明 | 1405| ------------------- | ------------------------ | 1406| Promise<void> | 无返回结果的Promise对象。 | 1407 1408**错误码：** 1409 1410以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1411 1412| 错误码ID | 错误信息 | 1413| ------- | -------------------------------------------- | 1414| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1415| 1300002 | This window state is abnormal. | 1416| 1300003 | This window manager service works abnormally. | 1417 1418**示例：** 1419 1420```ts 1421// EntryAbility.ets 1422import { UIAbility } from '@kit.AbilityKit'; 1423import { BusinessError } from '@kit.BasicServicesKit'; 1424 1425export default class EntryAbility extends UIAbility { 1426 // ... 1427 onWindowStageCreate(windowStage: window.WindowStage): void { 1428 console.info('onWindowStageCreate'); 1429 let windowClass: window.Window | undefined = undefined; 1430 windowStage.getMainWindow((err: BusinessError, data) => { 1431 const errCode: number = err.code; 1432 if (errCode) { 1433 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1434 return; 1435 } 1436 windowClass = data; 1437 let isLayoutFullScreen = true; 1438 try { 1439 let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen); 1440 promise.then(() => { 1441 console.info('Succeeded in setting the window layout to full-screen mode.'); 1442 }).catch((err: BusinessError) => { 1443 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 1444 }); 1445 } catch (exception) { 1446 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 1447 } 1448 }); 1449 } 1450} 1451``` 1452 1453## setImmersiveModeEnabledState<sup>12+</sup> 1454 1455setImmersiveModeEnabledState(enabled: boolean): void 1456 1457设置当前窗口是否开启沉浸式布局，该调用不会改变窗口模式和窗口大小。仅主窗口和子窗口可调用。 1458 1459**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1460 1461**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1462 1463**设备行为差异：** API version 14之前，该接口在所有设备中可正常调用。从API version 14开始，该接口在2in1设备、Tablet设备的[自由多窗模式](../../windowmanager/window-terminology.md#自由多窗模式)下调用不生效也不报错，在其他设备中可正常调用。 1464 1465**参数：** 1466 1467| 参数名 | 类型 | 必填 | 说明 | 1468| ---------- | ------- | ---- | ------------------------------------------------------------ | 1469| enabled | boolean | 是 | 是否开启沉浸式布局。<br>true表示开启，false表示关闭。</br> | 1470 1471**错误码：** 1472 1473以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1474 1475| 错误码ID | 错误信息 | 1476| ------- | -------------------------------------------- | 1477| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1478| 1300002 | This window state is abnormal. | 1479| 1300003 | This window manager service works abnormally. | 1480| 1300004 | Unauthorized operation. | 1481 1482**示例：** 1483 1484```ts 1485try { 1486 let enabled = false; 1487 windowClass.setImmersiveModeEnabledState(enabled); 1488} catch (exception) { 1489 console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 1490} 1491``` 1492 1493## getImmersiveModeEnabledState<sup>12+</sup> 1494 1495getImmersiveModeEnabledState(): boolean 1496 1497查询当前窗口是否开启沉浸式布局。 1498 1499返回值与[setImmersiveModeEnabledState()](#setimmersivemodeenabledstate12)以及[setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9)设置结果一致，若未调用上述两个接口则默认返回false。 1500 1501**系统能力**：SystemCapability.WindowManager.WindowManager.Core 1502 1503**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1504 1505**返回值：** 1506| 类型 | 说明 | 1507| ------- | ------------------------------------------------------------------------------------ | 1508| boolean | 是否设置开启沉浸式布局。</br>true表示开启沉浸式布局，false表示关闭沉浸式布局。| 1509 1510**错误码：** 1511 1512以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1513 1514| 错误码ID | 错误信息 | 1515| -------- | -------------------------------------------- | 1516| 1300002 | This window state is abnormal. | 1517| 1300003 | This window manager service works abnormally. | 1518| 1300004 | Unauthorized operation. | 1519 1520**示例：** 1521 1522```ts 1523try { 1524 let isEnabled = windowClass.getImmersiveModeEnabledState(); 1525} catch (exception) { 1526 console.error(`Failed to get the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 1527} 1528``` 1529 1530## isImmersiveLayout<sup>20+</sup> 1531 1532isImmersiveLayout(): boolean 1533 1534查询当前窗口是否处于沉浸式布局状态。 1535 1536**系统能力**：SystemCapability.Window.SessionManager 1537 1538**返回值：** 1539| 类型 | 说明 | 1540| ------- | ------------------------------------------------------------------------------------ | 1541| boolean | 是否处于沉浸式布局状态。true表示处于沉浸式布局状态，false表示不处于沉浸式布局状态。| 1542 1543**错误码：** 1544 1545以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1546 1547| 错误码ID | 错误信息 | 1548| -------- | -------------------------------------------- | 1549| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1550| 1300002 | This window state is abnormal. | 1551 1552**示例：** 1553 1554```ts 1555try { 1556 let isEnabled = windowClass.isImmersiveLayout(); 1557} catch (exception) { 1558 console.error(`Failed to check if the window layout is in immersive mode. Cause code: ${exception.code}, message: ${exception.message}`); 1559} 1560``` 1561 1562## setWindowDelayRaiseOnDrag<sup>19+</sup> 1563 1564setWindowDelayRaiseOnDrag(isEnabled: boolean): void 1565 1566该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于设置窗口是否使能延迟抬升，仅主窗和子窗可设置。<br> 1567不调用此接口或传入false，主窗和子窗在鼠标左键按下时，默认立即抬升。<br> 1568调用此接口使能延迟抬升后，在跨窗拖拽场景，可拖拽组件所在窗口在鼠标左键按下时不会立即抬升，直到鼠标左键抬起。 1569 1570**系统能力**：SystemCapability.Window.SessionManager 1571 1572**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1573 1574**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 1575 1576**参数：** 1577 1578| 参数名 | 类型 | 必填 | 说明 | 1579| ---------- | ------- | ---- | ------------------------------------------------------------ | 1580| isEnabled | boolean | 是 | 是否使能延迟抬升。<br>true表示使能窗口延迟抬升；false表示不使能窗口延迟抬升。 | 1581 1582**错误码：** 1583 1584以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1585 1586| 错误码ID | 错误信息 | 1587| ------- | -------------------------------------------- | 1588| 801 | Capability not supported.function setWindowDelayRaiseOnDrag can not work correctly due to limited device capabilities. | 1589| 1300002 | This window state is abnormal. | 1590 1591**示例：** 1592 1593```ts 1594try { 1595 windowClass.setWindowDelayRaiseOnDrag(true); 1596} catch (exception) { 1597 console.error(`Failed to set window delay raise. Cause code: ${exception.code}, message: ${exception.message}`); 1598} 1599``` 1600 1601## setDragKeyFramePolicy<sup>20+</sup> 1602 1603setDragKeyFramePolicy(keyFramePolicy: KeyFramePolicy): Promise<KeyFramePolicy> 1604 1605设置主窗口拖拽的关键帧策略，并使用Promise处理异步回调。 1606 1607非主窗口调用时，返回1300004错误码。 1608 1609**系统能力：** SystemCapability.Window.SessionManager 1610 1611**设备行为差异：** 该接口在2in1设备可正常调用，在其他设备中返回801错误码。 1612 1613**参数：** 1614 1615| 参数名 | 类型 | 必填 | 说明 | 1616| ----- | ---------------------------- | -- | --------------------------------- | 1617| keyFramePolicy | [KeyFramePolicy](arkts-apis-window-i.md#keyframepolicy20) | 是 | 用于设置拖拽的关键帧策略。 | 1618 1619**返回值：** 1620 1621| 类型 | 说明 | 1622| ------------------------------------- | ------------------------- | 1623| Promise<[KeyFramePolicy](arkts-apis-window-i.md#keyframepolicy20)> | Promise对象，返回实际生效的关键帧策略。 | 1624 1625**错误码：** 1626 1627以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1628 1629| 错误码ID | 错误信息 | 1630| ------- | --------------------------------------------- | 1631| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1632| 1300002 | This window state is abnormal. | 1633| 1300003 | This window manager service works abnormally. | 1634| 1300004 | Unauthorized operation. | 1635| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range; 2. The parameter format is incorrect.| 1636 1637**示例：** 1638 1639```ts 1640// EntryAbility.ets 1641import { UIAbility } from '@kit.AbilityKit'; 1642import { BusinessError } from '@kit.BasicServicesKit'; 1643 1644export default class EntryAbility extends UIAbility { 1645 // ... 1646 onWindowStageCreate(windowStage: window.WindowStage): void { 1647 console.info('onWindowStageCreate'); 1648 let windowClass: window.Window | undefined = undefined; 1649 windowStage.getMainWindow((err: BusinessError, data) => { 1650 const errCode: number = err.code; 1651 if (errCode) { 1652 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1653 return; 1654 } 1655 windowClass = data; 1656 let keyFramePolicy: window.KeyFramePolicy = { 1657 enable: true 1658 } 1659 try { 1660 let promise = windowClass.setDragKeyFramePolicy(keyFramePolicy); 1661 promise.then((ret: window.KeyFramePolicy) => { 1662 console.info(`Succeeded in setting key frame: ${JSON.stringify(ret)}`); 1663 }).catch((err: BusinessError) => { 1664 console.error(`Failed to set key frame. Cause code: ${err.code}, message: ${err.message}`); 1665 }); 1666 } catch (exception) { 1667 console.error(`Failed to set key frame. Cause code: ${exception.code}, message: ${exception.message}`); 1668 } 1669 }); 1670 } 1671} 1672``` 1673 1674## setWindowSystemBarEnable<sup>9+</sup> 1675 1676setWindowSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 1677 1678<!--RP14-->设置主窗口状态栏、三键导航栏的可见模式，状态栏通过status控制、三键导航栏通过navigation控制<!--RP14End-->，使用Promise异步回调。<br>从API version 12开始，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 1679 1680调用生效后返回并不表示状态栏和<!--RP15-->三键导航栏<!--RP15End-->的显示或隐藏已完成。子窗口调用后不生效。非全屏模式（悬浮窗、分屏等场景）下配置不生效。 1681 1682**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1683 1684**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1685 1686**参数：** 1687 1688| 参数名 | 类型 | 必填 | 说明 | 1689| ----- | ---------------------------- | -- | --------------------------------- | 1690| names | Array<'status'\|'navigation'> | 是 | 设置窗口全屏模式时状态栏、<!--RP15-->三键导航栏<!--RP15End-->是否显示。<br>例如，需全部显示，该参数设置为['status', 'navigation']；设置为[]，则不显示。 | 1691 1692**返回值：** 1693 1694| 类型 | 说明 | 1695| ------------------- | ------------------------ | 1696| Promise<void> | 无返回结果的Promise对象。 | 1697 1698**错误码：** 1699 1700以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1701 1702| 错误码ID | 错误信息 | 1703| ------- | -------------------------------------------- | 1704| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1705| 1300002 | This window state is abnormal. | 1706| 1300003 | This window manager service works abnormally. | 1707 1708**示例：** 1709 1710```ts 1711// 此处以状态栏等均不显示为例 1712// EntryAbility.ets 1713import { UIAbility } from '@kit.AbilityKit'; 1714import { BusinessError } from '@kit.BasicServicesKit'; 1715 1716export default class EntryAbility extends UIAbility { 1717 // ... 1718 onWindowStageCreate(windowStage: window.WindowStage): void { 1719 console.info('onWindowStageCreate'); 1720 let windowClass: window.Window | undefined = undefined; 1721 windowStage.getMainWindow((err: BusinessError, data) => { 1722 const errCode: number = err.code; 1723 if (errCode) { 1724 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1725 return; 1726 } 1727 windowClass = data; 1728 let names: Array<'status' | 'navigation'> = []; 1729 try { 1730 let promise = windowClass.setWindowSystemBarEnable(names); 1731 promise.then(() => { 1732 console.info('Succeeded in setting the system bar to be invisible.'); 1733 }).catch((err: BusinessError) => { 1734 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 1735 }); 1736 } catch (exception) { 1737 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 1738 } 1739 }); 1740 } 1741} 1742``` 1743 1744## setSpecificSystemBarEnabled<sup>11+</sup> 1745 1746setSpecificSystemBarEnabled(name: SpecificSystemBar, enable: boolean, enableAnimation?: boolean): Promise<void> 1747 1748设置主窗口状态栏、<!--RP15-->三键导航栏<!--RP15End-->的显示和隐藏，使用Promise异步回调。<br>从API version 12开始，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 1749 1750调用生效后返回并不表示状态栏和<!--RP15-->三键导航栏<!--RP15End-->的显示或隐藏已完成。子窗口调用后不生效。非全屏模式（悬浮窗、分屏等场景）下配置不生效。 1751 1752**系统能力：** SystemCapability.Window.SessionManager 1753 1754**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1755 1756**参数：** 1757 1758| 参数名 | 类型 | 必填 | 说明 | 1759| ----- | ---------------------------- | -- | --------------------------------- | 1760| name | [SpecificSystemBar](arkts-apis-window-t.md#specificsystembar11) | 是 | 设置窗口全屏模式时，显示或隐藏的系统栏类型。 | 1761| enable | boolean | 是 | 设置窗口全屏模式时状态栏或<!--RP15-->三键导航栏<!--RP15End-->是否显示，true表示显示， false表示隐藏。| 1762| enableAnimation<sup>12+</sup> | boolean | 否 | 设置状态栏或<!--RP15-->三键导航栏<!--RP15End-->显示状态变化时是否使用动画，true表示使用， false表示不使用，默认值为false。| 1763 1764**返回值：** 1765 1766| 类型 | 说明 | 1767| ------------------- | ------------------------ | 1768| Promise<void> | 无返回结果的Promise对象。 | 1769 1770**错误码：** 1771 1772以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1773 1774| 错误码ID | 错误信息 | 1775| ------- | -------------------------------------------- | 1776| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1777| 1300002 | This window state is abnormal. | 1778| 1300003 | This window manager service works abnormally. | 1779 1780**示例：** 1781 1782```ts 1783// 此处以隐藏状态栏为例 1784// EntryAbility.ets 1785import { UIAbility } from '@kit.AbilityKit'; 1786import { BusinessError } from '@kit.BasicServicesKit'; 1787 1788export default class EntryAbility extends UIAbility { 1789 // ... 1790 onWindowStageCreate(windowStage: window.WindowStage): void { 1791 console.info('onWindowStageCreate'); 1792 let windowClass: window.Window | undefined = undefined; 1793 windowStage.getMainWindow((err: BusinessError, data) => { 1794 const errCode: number = err.code; 1795 if (errCode) { 1796 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1797 return; 1798 } 1799 windowClass = data; 1800 try { 1801 let promise = windowClass.setSpecificSystemBarEnabled('status', false); 1802 promise.then(() => { 1803 console.info('Succeeded in setting the system bar to be invisible.'); 1804 }).catch((err: BusinessError) => { 1805 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 1806 }); 1807 } catch (exception) { 1808 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 1809 } 1810 }); 1811 } 1812} 1813``` 1814 1815## setWindowSystemBarProperties<sup>9+</sup> 1816 1817setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 1818 1819设置主窗口<!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性，使用Promise异步回调，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 1820 1821子窗口调用后不生效。 1822 1823**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1824 1825**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1826 1827**参数：** 1828 1829| 参数名 | 类型 | 必填 | 说明 | 1830| ------------------- | ------------------------------------------- | ---- | ---------------------- | 1831| systemBarProperties | [SystemBarProperties](arkts-apis-window-i.md#systembarproperties) | 是 | <!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性。 | 1832 1833**返回值：** 1834 1835| 类型 | 说明 | 1836| ------------------- | ------------------------- | 1837| Promise<void> | 无返回结果的Promise对象。 | 1838 1839**错误码：** 1840 1841以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1842 1843| 错误码ID | 错误信息 | 1844| ------- | -------------------------------------------- | 1845| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1846| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1847| 1300002 | This window state is abnormal. | 1848| 1300003 | This window manager service works abnormally. | 1849 1850**示例：** 1851 1852```ts 1853// EntryAbility.ets 1854import { UIAbility } from '@kit.AbilityKit'; 1855import { BusinessError } from '@kit.BasicServicesKit'; 1856 1857export default class EntryAbility extends UIAbility { 1858 // ... 1859 onWindowStageCreate(windowStage: window.WindowStage): void { 1860 console.info('onWindowStageCreate'); 1861 let windowClass: window.Window | undefined = undefined; 1862 windowStage.getMainWindow((err: BusinessError, data) => { 1863 const errCode: number = err.code; 1864 if (errCode) { 1865 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1866 return; 1867 } 1868 windowClass = data; 1869 let SystemBarProperties: window.SystemBarProperties = { 1870 statusBarColor: '#ff00ff', 1871 navigationBarColor: '#00ff00', 1872 //以下两个属性从API Version8开始支持 1873 statusBarContentColor: '#ffffff', 1874 navigationBarContentColor: '#00ffff' 1875 }; 1876 try { 1877 let promise = windowClass.setWindowSystemBarProperties(SystemBarProperties); 1878 promise.then(() => { 1879 console.info('Succeeded in setting the system bar properties.'); 1880 }).catch((err: BusinessError) => { 1881 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 1882 }); 1883 } catch (exception) { 1884 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 1885 } 1886 }); 1887 } 1888} 1889``` 1890 1891## getWindowSystemBarProperties<sup>12+</sup> 1892 1893getWindowSystemBarProperties(): SystemBarProperties 1894 1895主窗口获取<!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性。 1896 1897**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1898 1899**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1900 1901**返回值：** 1902 1903| 类型 | 说明 | 1904| ------------------------------------- | ------------- | 1905| [SystemBarProperties](arkts-apis-window-i.md#systembarproperties) | 当前<!--Del-->三键导航栏、<!--DelEnd-->状态栏属性。 | 1906 1907**错误码：** 1908 1909以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 1910 1911| 错误码ID | 错误信息 | 1912| ------- | ------------------------------ | 1913| 1300002 | This window state is abnormal. | 1914| 1300003 | This window manager service works abnormally. | 1915| 1300004 | Unauthorized operation. | 1916 1917 1918**示例：** 1919 1920```ts 1921// EntryAbility.ets 1922import { UIAbility } from '@kit.AbilityKit'; 1923import { BusinessError } from '@kit.BasicServicesKit'; 1924 1925export default class EntryAbility extends UIAbility { 1926 // ... 1927 1928 onWindowStageCreate(windowStage: window.WindowStage) { 1929 let windowClass: window.Window | undefined = undefined; 1930 windowStage.getMainWindow((err: BusinessError, data) => { 1931 const errCode: number = err.code; 1932 if (errCode) { 1933 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 1934 return; 1935 } 1936 windowClass = data; 1937 try { 1938 let systemBarProperty = windowClass.getWindowSystemBarProperties(); 1939 console.info('Success in obtaining system bar properties. Property: ' + JSON.stringify(systemBarProperty)); 1940 } catch (err) { 1941 console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`); 1942 } 1943 }); 1944 } 1945}; 1946``` 1947 1948## setStatusBarColor<sup>18+</sup> 1949 1950setStatusBarColor(color: ColorMetrics): Promise<void> 1951 1952设置主窗口状态栏的文字颜色，使用Promise异步回调。 1953 1954子窗口不支持设置状态栏文字颜色，调用无效果。该接口在2in1设备上调用不生效。 1955 1956**系统能力：** SystemCapability.Window.SessionManager 1957 1958**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1959 1960**参数：** 1961 1962| 参数名 | 类型 | 必填 | 说明 | 1963| ------------------- | ------------------------------------------- | ---- | ---------------------- | 1964| color | [ColorMetrics](js-apis-arkui-graphics.md#colormetrics12) | 是 | 要设置的状态栏颜色值。 | 1965 1966**返回值：** 1967 1968| 类型 | 说明 | 1969| ------------------- | ------------------------- | 1970| Promise<void> | 无返回结果的Promise对象。 | 1971 1972**错误码：** 1973 1974以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 1975 1976| 错误码ID | 错误信息 | 1977| ------- | -------------------------------------------- | 1978| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1979| 801 | Capability not supported on this device. | 1980| 1300002 | This window state is abnormal. | 1981| 1300003 | This window manager service works abnormally. | 1982 1983**示例：** 1984 1985```ts 1986// EntryAbility.ets 1987import { UIAbility } from '@kit.AbilityKit'; 1988import { BusinessError } from '@kit.BasicServicesKit'; 1989import { ColorMetrics, window } from '@kit.ArkUI'; 1990 1991export default class EntryAbility extends UIAbility { 1992 // ... 1993 onWindowStageCreate(windowStage: window.WindowStage): void { 1994 console.info('onWindowStageCreate'); 1995 let windowClass: window.Window | undefined = undefined; 1996 windowStage.getMainWindow((err: BusinessError, data) => { 1997 const errCode: number = err.code; 1998 if (errCode) { 1999 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2000 return; 2001 } 2002 windowClass = data; 2003 try { 2004 let promise = windowClass.setStatusBarColor(ColorMetrics.numeric(0x112233)); 2005 promise.then(() => { 2006 console.info('Succeeded in setting the status bar color.'); 2007 }).catch((err: BusinessError) => { 2008 console.error(`Set the status bar color failed. Cause code: ${err.code}, message: ${err.message}`); 2009 }); 2010 } catch (exception) { 2011 console.error(`Failed to set the status bar color. Cause code: ${exception.code}, message: ${exception.message}`); 2012 } 2013 }); 2014 } 2015} 2016``` 2017 2018## getStatusBarProperty<sup>18+</sup> 2019 2020getStatusBarProperty(): StatusBarProperty 2021 2022获取主窗口状态栏的属性，如状态栏文字颜色。 2023 2024子窗口不支持查询，调用会返回错误码1300002。 2025 2026**系统能力：** SystemCapability.Window.SessionManager 2027 2028**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2029 2030**返回值：** 2031 2032| 类型 | 说明 | 2033| ------------------------------------- | ------------- | 2034| [StatusBarProperty](arkts-apis-window-i.md#statusbarproperty18) | 当前状态栏属性，如状态栏颜色。 | 2035 2036**错误码：** 2037 2038以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2039 2040| 错误码ID | 错误信息 | 2041| ------- | ------------------------------ | 2042| 801 | Capability not supported on this device. | 2043| 1300002 | This window state is abnormal. | 2044 2045**示例：** 2046 2047```ts 2048// EntryAbility.ets 2049import { UIAbility } from '@kit.AbilityKit'; 2050import { BusinessError } from '@kit.BasicServicesKit'; 2051import { window } from '@kit.ArkUI'; 2052 2053export default class EntryAbility extends UIAbility { 2054 // ... 2055 onWindowStageCreate(windowStage: window.WindowStage) { 2056 let windowClass: window.Window | undefined = undefined; 2057 windowStage.getMainWindow((err: BusinessError, data) => { 2058 const errCode: number = err.code; 2059 if (errCode) { 2060 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2061 return; 2062 } 2063 windowClass = data; 2064 try { 2065 let statusBarProperty = windowClass.getStatusBarProperty(); 2066 console.info('Succeeded in obtaining system bar properties. Property: ' + JSON.stringify(statusBarProperty)); 2067 } catch (err) { 2068 console.error(`Failed to get system bar properties. Code: ${err.code}, message: ${err.message}`); 2069 } 2070 }); 2071 } 2072}; 2073``` 2074 2075## setPreferredOrientation<sup>9+</sup> 2076 2077setPreferredOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 2078 2079设置主窗口的显示方向属性，使用callback异步回调。相关横竖屏开发实践查询[横竖屏切换](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-landscape-and-portrait-development)。<!--RP9-->仅在支持跟随sensor旋转的设备上生效，2in1设备上调用不生效，子窗口调用后不生效。<!--RP9End--> 2080 2081**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2082 2083**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2084 2085**参数：** 2086 2087| 参数名 | 类型 | 必填 | 说明 | 2088| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2089| orientation | [Orientation](arkts-apis-window-e.md#orientation9) | 是 | 窗口显示方向的属性。 | 2090| callback | AsyncCallback<void> | 是 | 回调函数。该回调函数返回调用结果是否成功，非应用旋转动效结束。 | 2091 2092**错误码：** 2093 2094以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2095 2096| 错误码ID | 错误信息 | 2097| ------- | ------------------------------ | 2098| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2099| 1300002 | This window state is abnormal. | 2100 2101**示例：** 2102 2103```ts 2104// EntryAbility.ets 2105import { UIAbility } from '@kit.AbilityKit'; 2106import { BusinessError } from '@kit.BasicServicesKit'; 2107 2108export default class EntryAbility extends UIAbility { 2109 // ... 2110 onWindowStageCreate(windowStage: window.WindowStage): void { 2111 console.info('onWindowStageCreate'); 2112 let windowClass: window.Window | undefined = undefined; 2113 windowStage.getMainWindow((err: BusinessError, data) => { 2114 const errCode: number = err.code; 2115 if (errCode) { 2116 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2117 return; 2118 } 2119 windowClass = data; 2120 let orientation = window.Orientation.AUTO_ROTATION; 2121 try { 2122 windowClass.setPreferredOrientation(orientation, (err: BusinessError) => { 2123 const errCode: number = err.code; 2124 if (errCode) { 2125 console.error(`Failed to set window orientation. Cause code: ${err.code}, message: ${err.message}`); 2126 return; 2127 } 2128 console.info('Succeeded in setting window orientation.'); 2129 }); 2130 } catch (exception) { 2131 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2132 } 2133 }); 2134 } 2135} 2136``` 2137 2138## setPreferredOrientation<sup>9+</sup> 2139 2140setPreferredOrientation(orientation: Orientation): Promise<void> 2141 2142设置主窗口的显示方向属性，使用Promise异步回调。<!--RP9-->仅在支持跟随sensor旋转的设备上生效，2in1设备上调用不生效，子窗口调用后不生效。<!--RP9End--> 2143 2144**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2145 2146**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2147 2148**参数：** 2149 2150| 参数名 | 类型 | 必填 | 说明 | 2151| ------------------- | ------------------------------------------- | ---- | ---------------------- | 2152| orientation | [Orientation](arkts-apis-window-e.md#orientation9) | 是 | 窗口显示方向的属性。 | 2153 2154**返回值：** 2155 2156| 类型 | 说明 | 2157| ------------------- | ------------------------- | 2158| Promise<void> | 无返回结果的Promise对象。 | 2159 2160**错误码：** 2161 2162以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2163 2164| 错误码ID | 错误信息 | 2165| ------- | ------------------------------ | 2166| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2167| 1300002 | This window state is abnormal. | 2168 2169**示例：** 2170 2171```ts 2172// EntryAbility.ets 2173import { UIAbility } from '@kit.AbilityKit'; 2174import { BusinessError } from '@kit.BasicServicesKit'; 2175 2176export default class EntryAbility extends UIAbility { 2177 // ... 2178 onWindowStageCreate(windowStage: window.WindowStage): void { 2179 console.info('onWindowStageCreate'); 2180 let windowClass: window.Window | undefined = undefined; 2181 windowStage.getMainWindow((err: BusinessError, data) => { 2182 const errCode: number = err.code; 2183 if (errCode) { 2184 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2185 return; 2186 } 2187 windowClass = data; 2188 let orientation = window.Orientation.AUTO_ROTATION; 2189 try { 2190 let promise = windowClass.setPreferredOrientation(orientation); 2191 promise.then(() => { 2192 console.info('Succeeded in setting the window orientation.'); 2193 }).catch((err: BusinessError) => { 2194 console.error(`Failed to set the window orientation. Cause code: ${err.code}, message: ${err.message}`); 2195 }); 2196 } catch (exception) { 2197 console.error(`Failed to set window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2198 } 2199 }); 2200 } 2201} 2202``` 2203 2204## getPreferredOrientation<sup>12+</sup> 2205 2206getPreferredOrientation(): Orientation 2207 2208主窗口调用，获取窗口的显示方向属性。 2209 2210**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2211 2212**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2213 2214**返回值：** 2215 2216| 类型 | 说明 | 2217|------------------------------| ------------------ | 2218| [Orientation](arkts-apis-window-e.md#orientation9) | 窗口显示方向的属性。 | 2219 2220**错误码：** 2221 2222以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 2223 2224| 错误码ID | 错误信息 | 2225| ------- | ------------------------------ | 2226| 1300002 | This window state is abnormal. | 2227 2228**示例：** 2229 2230```ts 2231// EntryAbility.ets 2232import { UIAbility } from '@kit.AbilityKit'; 2233import { BusinessError } from '@kit.BasicServicesKit'; 2234export default class EntryAbility extends UIAbility { 2235 // ... 2236 2237 onWindowStageCreate(windowStage: window.WindowStage) { 2238 console.info('onWindowStageCreate'); 2239 let windowClass: window.Window | undefined = undefined; 2240 windowStage.getMainWindow((err: BusinessError, data) => { 2241 const errCode: number = err.code; 2242 if (errCode) { 2243 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2244 return; 2245 } 2246 windowClass = data; 2247 try { 2248 let orientation = windowClass.getPreferredOrientation(); 2249 } catch (exception) { 2250 console.error(`Failed to get window orientation. Cause code: ${exception.code}, message: ${exception.message}`); 2251 } 2252 }); 2253 } 2254}; 2255``` 2256 2257## getUIContext<sup>10+</sup> 2258 2259getUIContext(): UIContext 2260 2261获取UIContext实例。 2262 2263**模型约束：** 此接口仅可在Stage模型下使用。 2264 2265**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2266 2267**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2268 2269**返回值：** 2270 2271| 类型 | 说明 | 2272| ---------- | ---------------------- | 2273| [UIContext](arkts-apis-uicontext-uicontext.md) | 返回UIContext实例对象。 | 2274 2275**错误码：** 2276 2277以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 2278 2279| 错误码ID | 错误信息 | 2280| ------- | ------------------------------ | 2281| 1300002 | This window state is abnormal. | 2282 2283**示例：** 2284 2285```ts 2286// EntryAbility.ets 2287import { UIAbility } from '@kit.AbilityKit'; 2288import { window, UIContext } from '@kit.ArkUI'; 2289import { BusinessError } from '@kit.BasicServicesKit'; 2290 2291export default class EntryAbility extends UIAbility { 2292 onWindowStageCreate(windowStage: window.WindowStage) { 2293 // 为主窗口加载对应的目标页面。 2294 windowStage.loadContent("pages/page2", (err: BusinessError) => { 2295 let errCode: number = err.code; 2296 if (errCode) { 2297 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2298 return; 2299 } 2300 console.info('Succeeded in loading the content.'); 2301 // 获取应用主窗口。 2302 let windowClass: window.Window | undefined = undefined; 2303 windowStage.getMainWindow((err: BusinessError, data) => { 2304 let errCode: number = err.code; 2305 if (errCode) { 2306 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 2307 return; 2308 } 2309 windowClass = data; 2310 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 2311 // 获取UIContext实例。 2312 let uiContext: UIContext | null = null; 2313 uiContext = windowClass.getUIContext(); 2314 }); 2315 }); 2316 } 2317}; 2318``` 2319 2320## setUIContent<sup>9+</sup> 2321 2322setUIContent(path: string, callback: AsyncCallback<void>): void 2323 2324根据当前工程中指定的某个页面路径为窗口加载具体页面内容，使用callback异步回调。 2325 2326**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2327 2328**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2329 2330**参数：** 2331 2332| 参数名 | 类型 | 必填 | 说明 | 2333| -------- | ------------------------- | -- | -------------------- | 2334| path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。 | 2335| callback | AsyncCallback<void> | 是 | 回调函数。 | 2336 2337**错误码：** 2338 2339以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2340 2341| 错误码ID | 错误信息 | 2342| ------- | -------------------------------------------- | 2343| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2344| 1300002 | This window state is abnormal. | 2345 2346**示例：** 2347 2348```ts 2349import { BusinessError } from '@kit.BasicServicesKit'; 2350 2351try { 2352 windowClass.setUIContent('pages/page2/page3', (err: BusinessError) => { 2353 const errCode: number = err.code; 2354 if (errCode) { 2355 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2356 return; 2357 } 2358 console.info('Succeeded in loading the content.'); 2359 }); 2360} catch (exception) { 2361 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2362} 2363``` 2364 2365## setUIContent<sup>9+</sup> 2366 2367setUIContent(path: string): Promise<void> 2368 2369根据当前工程中指定的某个页面路径为窗口加载具体页面内容，使用Promise异步回调。 2370 2371**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2372 2373**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2374 2375**参数：** 2376 2377| 参数名 | 类型 | 必填 | 说明 | 2378| ---- | ------ | -- | ------------------ | 2379| path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。 | 2380 2381**返回值：** 2382 2383| 类型 | 说明 | 2384| ------------------- | ------------------------ | 2385| Promise<void> | 无返回结果的Promise对象。 | 2386 2387**错误码：** 2388 2389以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2390 2391| 错误码ID | 错误信息 | 2392| ------- | -------------------------------------------- | 2393| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2394| 1300002 | This window state is abnormal. | 2395 2396**示例：** 2397 2398```ts 2399import { BusinessError } from '@kit.BasicServicesKit'; 2400 2401try { 2402 let promise = windowClass.setUIContent('pages/page2/page3'); 2403 promise.then(() => { 2404 console.info('Succeeded in loading the content.'); 2405 }).catch((err: BusinessError) => { 2406 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2407 }); 2408} catch (exception) { 2409 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2410} 2411``` 2412 2413## loadContent<sup>9+</sup> 2414 2415loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void 2416 2417根据当前工程中指定的页面路径为窗口加载具体页面内容，通过LocalStorage传递状态属性给加载的页面，使用callback异步回调。建议在UIAbility启动过程中使用该接口，重复调用将先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。当前UI的执行上下文可能不明确，所以不建议在回调函数中做UI相关的操作。 2418 2419**模型约束：** 此接口仅可在Stage模型下使用。 2420 2421**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2422 2423**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2424 2425**参数：** 2426 2427| 参数名 | 类型 | 必填 | 说明 | 2428| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 2429| path | string | 是 | 要加载到窗口中的页面内容的路径，该路径需添加到工程的main_pages.json文件中。 | 2430| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 是 | 页面级UI状态存储单元，这里用于为加载到窗口的页面内容传递状态属性。 | 2431| callback | AsyncCallback<void> | 是 | 回调函数。 | 2432 2433**错误码：** 2434 2435以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2436 2437| 错误码ID | 错误信息 | 2438| ------- | -------------------------------------------- | 2439| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter.| 2440| 1300002 | This window state is abnormal. | 2441 2442**示例：** 2443 2444```ts 2445import { BusinessError } from '@kit.BasicServicesKit'; 2446 2447let storage: LocalStorage = new LocalStorage(); 2448storage.setOrCreate('storageSimpleProp', 121); 2449windowClass.loadContent('pages/page2', storage, (err: BusinessError) => { 2450 const errCode: number = err.code; 2451 if (errCode) { 2452 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2453 return; 2454 } 2455 console.info('Succeeded in loading the content.'); 2456}); 2457``` 2458 2459## loadContent<sup>9+</sup> 2460 2461loadContent(path: string, storage: LocalStorage): Promise<void> 2462 2463根据当前工程中指定的页面路径为窗口加载具体页面内容，通过LocalStorage传递状态属性给加载的页面，使用Promise异步回调。建议在UIAbility启动过程中使用该接口，重复调用将先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。当前UI的执行上下文可能不明确，所以不建议在回调函数中做UI相关的操作。 2464 2465**模型约束：** 此接口仅可在Stage模型下使用。 2466 2467**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2468 2469**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2470 2471**参数：** 2472 2473| 参数名 | 类型 | 必填 | 说明 | 2474| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 2475| path | string | 是 | 要加载到窗口中的页面内容的路径，该路径需添加到工程的main_pages.json文件中。 | 2476| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 是 | 页面级UI状态存储单元，这里用于为加载到窗口的页面内容传递状态属性。 | 2477 2478**返回值：** 2479 2480| 类型 | 说明 | 2481| ------------------- | ------------------------- | 2482| Promise<void> | 无返回结果的Promise对象。 | 2483 2484**错误码：** 2485 2486以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2487 2488| 错误码ID | 错误信息 | 2489| ------- | -------------------------------------------- | 2490| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Invalid path parameter.| 2491| 1300002 | This window state is abnormal. | 2492 2493**示例：** 2494 2495```ts 2496import { BusinessError } from '@kit.BasicServicesKit'; 2497 2498let storage: LocalStorage = new LocalStorage(); 2499storage.setOrCreate('storageSimpleProp', 121); 2500let promise = windowClass.loadContent('pages/page2', storage); 2501promise.then(() => { 2502 console.info('Succeeded in loading the content.'); 2503}).catch((err: BusinessError) => { 2504 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2505}); 2506``` 2507 2508## loadContentByName<sup>11+</sup> 2509 2510loadContentByName(name: string, storage: LocalStorage, callback: AsyncCallback<void>): void 2511 2512根据指定路由页面名称为当前窗口加载[命名路由](../../ui/arkts-routing.md#命名路由)页面，通过LocalStorage传递状态属性至加载页面，使用callback异步回调。建议在UIAbility启动过程中使用该接口，重复调用该接口将先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。当前UI的执行上下文可能不明确，所以不建议在回调函数中做UI相关的操作。 2513 2514**模型约束：** 此接口仅可在Stage模型下使用。 2515 2516**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2517 2518**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2519 2520**参数：** 2521 2522| 参数名 | 类型 | 必填 | 说明 | 2523| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 2524| name | string | 是 | 命名路由页面的名称。 | 2525| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 是 | 页面级UI状态存储单元，这里用于为加载到窗口的页面内容传递状态属性。 | 2526| callback | AsyncCallback<void> | 是 | 回调函数。 | 2527 2528**错误码：** 2529 2530以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2531 2532| 错误码ID | 错误信息 | 2533| -------- | ------------------------------------------------------------ | 2534| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2535| 1300002 | This window state is abnormal. | 2536| 1300003 | This window manager service works abnormally. | 2537 2538**示例：** 2539<!--code_no_check--> 2540```ts 2541import { UIAbility } from '@kit.AbilityKit'; 2542import { BusinessError } from '@kit.BasicServicesKit'; 2543import * as Index from '../pages/Index'; // 导入命名路由页面 2544 2545export default class EntryAbility extends UIAbility { 2546 onWindowStageCreate(windowStage: window.WindowStage) { 2547 console.info('onWindowStageCreate'); 2548 let storage: LocalStorage = new LocalStorage(); 2549 let newValue: Number = 121; 2550 storage.setOrCreate('storageSimpleProp', newValue); 2551 try { 2552 let windowClass: window.Window = windowStage.getMainWindowSync(); 2553 if (!windowClass) { 2554 console.error('Failed to get main window.'); 2555 return; 2556 } 2557 windowClass.loadContentByName(Index.entryName, storage, (err: BusinessError) => { 2558 const errCode: number = err?.code; 2559 if (errCode) { 2560 console.error(`Failed to load the content. Cause code: ${err?.code}, message: ${err?.message}`); 2561 return; 2562 } 2563 console.info('Succeeded in loading the content.'); 2564 }); 2565 } catch (exception) { 2566 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2567 } 2568 } 2569} 2570``` 2571<!--code_no_check--> 2572```ts 2573// ets/pages/Index.ets 2574export const entryName : string = 'Index'; 2575@Entry({routeName: entryName, useSharedStorage: true}) 2576@Component 2577export struct Index { 2578 @State message: string = 'Hello World' 2579 @LocalStorageLink('storageSimpleProp') storageSimpleProp: number = 1; 2580 build() { 2581 Row() { 2582 Column() { 2583 Text(this.message) 2584 .fontSize(50) 2585 .fontWeight(FontWeight.Bold) 2586 } 2587 .width('100%') 2588 } 2589 .height('100%') 2590 } 2591} 2592``` 2593 2594## loadContentByName<sup>11+</sup> 2595 2596loadContentByName(name: string, callback: AsyncCallback<void>): void 2597 2598根据指定路由页面名称为当前窗口加载[命名路由](../../ui/arkts-routing.md#命名路由)页面，使用callback异步回调。建议在UIAbility启动过程中使用该接口，重复调用该接口将先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。当前UI的执行上下文可能不明确，所以不建议在回调函数中做UI相关的操作。 2599 2600**模型约束：** 此接口仅可在Stage模型下使用。 2601 2602**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2603 2604**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2605 2606**参数：** 2607 2608| 参数名 | 类型 | 必填 | 说明 | 2609| -------- | ------------------------- | ---- | ---------------- | 2610| name | string | 是 | 命名路由页面的名称。 | 2611| callback | AsyncCallback<void> | 是 | 回调函数。 | 2612 2613**错误码：** 2614 2615以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2616 2617| 错误码ID | 错误信息 | 2618| -------- | ------------------------------------------------------------ | 2619| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2620| 1300002 | This window state is abnormal. | 2621| 1300003 | This window manager service works abnormally. | 2622 2623**示例：** 2624<!--code_no_check--> 2625```ts 2626import { BusinessError } from '@kit.BasicServicesKit'; 2627import * as Index from '../pages/Index'; // 导入命名路由页面 2628 2629try { 2630 (windowClass as window.Window).loadContentByName(Index.entryName, (err: BusinessError) => { 2631 const errCode: number = err.code; 2632 if (errCode) { 2633 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2634 return; 2635 } 2636 console.info('Succeeded in loading the content.'); 2637 }); 2638} catch (exception) { 2639 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2640} 2641``` 2642<!--code_no_check--> 2643```ts 2644// ets/pages/Index.ets 2645export const entryName : string = 'Index'; 2646@Entry({routeName: entryName}) 2647@Component 2648export struct Index { 2649 @State message: string = 'Hello World' 2650 build() { 2651 Row() { 2652 Column() { 2653 Text(this.message) 2654 .fontSize(50) 2655 .fontWeight(FontWeight.Bold) 2656 } 2657 .width('100%') 2658 } 2659 .height('100%') 2660 } 2661} 2662``` 2663 2664## loadContentByName<sup>11+</sup> 2665 2666loadContentByName(name: string, storage?: LocalStorage): Promise<void> 2667 2668根据指定路由页面名称为当前窗口加载[命名路由](../../ui/arkts-routing.md#命名路由)页面，通过LocalStorage传递状态属性至加载页面，使用Promise异步回调。建议在UIAbility启动过程中使用该接口，重复调用该接口将先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。当前UI的执行上下文可能不明确，所以不建议在回调函数中做UI相关的操作。 2669 2670**模型约束：** 此接口仅可在Stage模型下使用。 2671 2672**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2673 2674**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2675 2676**参数：** 2677 2678| 参数名 | 类型 | 必填 | 说明 | 2679| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 2680| name | string | 是 | 命名路由页面的名称。 | 2681| storage | [LocalStorage](../../ui/state-management/arkts-localstorage.md) | 否 | 页面级UI状态存储单元，这里用于为加载到窗口的页面内容传递状态属性。 | 2682 2683**返回值：** 2684 2685| 类型 | 说明 | 2686| ------------------- | ------------------------- | 2687| Promise<void> | 无返回结果的Promise对象。 | 2688 2689**错误码：** 2690 2691以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 2692 2693| 错误码ID | 错误信息 | 2694| -------- | ------------------------------------------------------------ | 2695| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2696| 1300002 | This window state is abnormal. | 2697| 1300003 | This window manager service works abnormally. | 2698 2699**示例：** 2700<!--code_no_check--> 2701```ts 2702import { BusinessError } from '@kit.BasicServicesKit'; 2703import * as Index from '../pages/Index'; // 导入命名路由页面 2704 2705let storage: LocalStorage = new LocalStorage(); 2706storage.setOrCreate('storageSimpleProp', 121); 2707try { 2708 let promise = (windowClass as window.Window).loadContentByName(Index.entryName, storage); 2709 promise.then(() => { 2710 console.info('Succeeded in loading the content.'); 2711 }).catch((err: BusinessError) => { 2712 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 2713 }); 2714} catch (exception) { 2715 console.error(`Failed to load the content. Cause code: ${exception.code}, message: ${exception.message}`); 2716} 2717``` 2718<!--code_no_check--> 2719```ts 2720// ets/pages/Index.ets 2721export const entryName : string = 'Index'; 2722@Entry({routeName: entryName, useSharedStorage: true}) 2723@Component 2724export struct Index { 2725 @State message: string = 'Hello World' 2726 @LocalStorageLink('storageSimpleProp') storageSimpleProp: number = 1; 2727 build() { 2728 Row() { 2729 Column() { 2730 Text(this.message) 2731 .fontSize(50) 2732 .fontWeight(FontWeight.Bold) 2733 } 2734 .width('100%') 2735 } 2736 .height('100%') 2737 } 2738} 2739``` 2740 2741## isWindowShowing<sup>9+</sup> 2742 2743isWindowShowing(): boolean 2744 2745判断当前窗口是否已显示。 2746 2747**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2748 2749**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2750 2751**返回值：** 2752 2753| 类型 | 说明 | 2754| ------- | ------------------------------------------------------------------ | 2755| boolean | 当前窗口是否已显示。true表示当前窗口已显示，false则表示当前窗口未显示。 | 2756 2757**错误码：** 2758 2759以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 2760 2761| 错误码ID | 错误信息 | 2762| ------- | ------------------------------ | 2763| 1300002 | This window state is abnormal. | 2764 2765**示例：** 2766 2767```ts 2768try { 2769 let data = windowClass.isWindowShowing(); 2770 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 2771} catch (exception) { 2772 console.error(`Failed to check whether the window is showing. Cause code: ${exception.code}, message: ${exception.message}`); 2773} 2774``` 2775 2776## on('windowSizeChange')<sup>7+</sup> 2777 2778on(type: 'windowSizeChange', callback: Callback<Size>): void 2779 2780开启窗口尺寸变化的监听。 2781 2782**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2783 2784**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2785 2786**参数：** 2787 2788| 参数名 | 类型 | 必填 | 说明 | 2789| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 2790| type | string | 是 | 监听事件，固定为'windowSizeChange'，即窗口尺寸变化事件。 | 2791| callback | Callback<[Size](arkts-apis-window-i.md#size7)> | 是 | 回调函数。返回当前的窗口尺寸。 | 2792 2793**错误码：** 2794 2795以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2796 2797| 错误码ID | 错误信息 | 2798| ------- | -------------------------------------------- | 2799| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2800 2801**示例：** 2802 2803```ts 2804try { 2805 windowClass.on('windowSizeChange', (data) => { 2806 console.info('Succeeded in enabling the listener for window size changes. Data: ' + JSON.stringify(data)); 2807 }); 2808} catch (exception) { 2809 console.error(`Failed to enable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 2810} 2811``` 2812 2813## off('windowSizeChange')<sup>7+</sup> 2814 2815off(type: 'windowSizeChange', callback?: Callback<Size>): void 2816 2817关闭窗口尺寸变化的监听。 2818 2819**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2820 2821**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2822 2823**参数：** 2824 2825| 参数名 | 类型 | 必填 | 说明 | 2826| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 2827| type | string | 是 | 监听事件，固定为'windowSizeChange'，即窗口尺寸变化事件。 | 2828| callback | Callback<[Size](arkts-apis-window-i.md#size7)> | 否 | 回调函数。返回当前的窗口尺寸。如果传入参数，则关闭该监听。如果未传入参数，则关闭窗口尺寸变化的监听。 | 2829 2830**错误码：** 2831 2832以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2833 2834| 错误码ID | 错误信息 | 2835| ------- | -------------------------------------------- | 2836| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 2837 2838**示例：** 2839 2840```ts 2841const callback = (size: window.Size) => { 2842 // ... 2843} 2844try { 2845 // 通过on接口开启监听 2846 windowClass.on('windowSizeChange', callback); 2847 // 关闭指定callback的监听 2848 windowClass.off('windowSizeChange', callback); 2849 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 2850 windowClass.off('windowSizeChange'); 2851} catch (exception) { 2852 console.error(`Failed to disable the listener for window size changes. Cause code: ${exception.code}, message: ${exception.message}`); 2853} 2854``` 2855 2856## on('avoidAreaChange')<sup>9+</sup> 2857 2858on(type: 'avoidAreaChange', callback: Callback<AvoidAreaOptions>): void 2859 2860开启当前应用窗口系统规避区变化的监听。 2861 2862[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，触发避让区回调时，该接口直接回调空的避让区。 2863 2864非自由窗口状态下，触发避让区回调时，仅当子窗口的位置和大小与主窗口一致时，子窗口调用该接口才能计算避让区并返回，否则直接返回空的避让区。 2865<!--RP7-->常见的触发避让区回调的场景如下：应用窗口在全屏模式、悬浮模式、分屏模式之间的切换；应用窗口旋转；多折叠设备在屏幕折叠态和展开态之间的切换；应用窗口在多设备之间的流转。<!--RP7End--> 2866 2867**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2868 2869**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2870 2871**参数：** 2872 2873| 参数名 | 类型 | 必填 | 说明 | 2874| -------- |----------------------------------| ---- |--------------------------------------| 2875| type | string | 是 | 监听事件，固定为'avoidAreaChange'，即系统规避区变化事件。 | 2876| callback | Callback<[AvoidAreaOptions](arkts-apis-window-i.md#avoidareaoptions12)> | 是 | 回调函数。返回当前规避区以及规避区类型。| 2877 2878**错误码：** 2879 2880以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2881 2882| 错误码ID | 错误信息 | 2883| ------- | -------------------------------------------- | 2884| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2885 2886**示例：** 2887 2888```ts 2889try { 2890 windowClass.on('avoidAreaChange', (data) => { 2891 console.info('Succeeded in enabling the listener for system avoid area changes. type:' + 2892 JSON.stringify(data.type) + ', area: ' + JSON.stringify(data.area)); 2893 }); 2894} catch (exception) { 2895 console.error(`Failed to enable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 2896} 2897``` 2898 2899## off('avoidAreaChange')<sup>9+</sup> 2900 2901off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaOptions>): void 2902 2903关闭当前窗口系统规避区变化的监听。 2904 2905**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2906 2907**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2908 2909**参数：** 2910 2911| 参数名 | 类型 | 必填 | 说明 | 2912| -------- |----------------------------------|------|------------------------------------| 2913| type | string | 是 | 监听事件，固定为'avoidAreaChange'，即系统规避区变化事件。 | 2914| callback | Callback<[AvoidAreaOptions](arkts-apis-window-i.md#avoidareaoptions12)> | 否 | 回调函数。返回当前规避区以及规避区类型。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有系统规避区变化的监听。| 2915 2916**错误码：** 2917 2918以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2919 2920| 错误码ID | 错误信息 | 2921| ------- | -------------------------------------------- | 2922| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed. | 2923 2924**示例：** 2925 2926```ts 2927interface Param { 2928 type: window.AvoidAreaType, 2929 area: window.AvoidArea 2930} 2931const callback = (data: Param) => { 2932 // ... 2933} 2934try { 2935 windowClass.on('avoidAreaChange', callback); 2936 2937 windowClass.off('avoidAreaChange', callback); 2938 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 2939 windowClass.off('avoidAreaChange'); 2940} catch (exception) { 2941 console.error(`Failed to enable or disable the listener for system avoid area changes. Cause code: ${exception.code}, message: ${exception.message}`); 2942} 2943``` 2944 2945## on('keyboardHeightChange')<sup>7+</sup> 2946 2947on(type: 'keyboardHeightChange', callback: Callback<number>): void 2948 2949开启固定态软键盘高度变化的监听。当软键盘从本窗口唤出且与窗口有重叠区域时，通知键盘高度变化。从API version 10开始，有关将软键盘设置为固定态或悬浮态的方法，请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 2950 2951**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2952 2953**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2954 2955**参数：** 2956 2957| 参数名 | 类型 | 必填 | 说明 | 2958| -------- | ------------------- | ---- |-------------------------------------------| 2959| type | string | 是 | 监听事件，固定为'keyboardHeightChange'，即键盘高度变化事件。 | 2960| callback | Callback<number> | 是 | 回调函数。返回当前的键盘高度。返回值为整数，单位为px。 | 2961 2962**错误码：** 2963 2964以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2965 2966| 错误码ID | 错误信息 | 2967| ------- | -------------------------------------------- | 2968| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2969 2970**示例：** 2971 2972```ts 2973import { BusinessError } from '@kit.BasicServicesKit'; 2974 2975try { 2976 windowClass.on('keyboardHeightChange', (data) => { 2977 console.info('Succeeded in enabling the listener for keyboard height changes. Data: ' + JSON.stringify(data)); 2978 }); 2979} catch (exception) { 2980 console.error(`Failed to enable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 2981} 2982``` 2983 2984## off('keyboardHeightChange')<sup>7+</sup> 2985 2986off(type: 'keyboardHeightChange', callback?: Callback<number>): void 2987 2988关闭固定态软键盘高度变化的监听，使应用程序不再接收键盘高度变化的通知。从API version 10开始，有关将软键盘设置为固定态或悬浮态的方法，请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 2989 2990**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2991 2992**系统能力：** SystemCapability.WindowManager.WindowManager.Core 2993 2994**参数：** 2995 2996| 参数名 | 类型 | 必填 | 说明 | 2997| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 2998| type | string | 是 | 监听事件，固定为'keyboardHeightChange'，即键盘高度变化事件。 | 2999| callback | Callback<number> | 否 | 回调函数。返回当前的键盘高度，返回值为整数，单位为px。若传入参数，则关闭该监听；未传入参数，则关闭所有固定态软键盘高度变化的监听。 | 3000 3001**错误码：** 3002 3003以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3004 3005| 错误码ID | 错误信息 | 3006| ------- | -------------------------------------------- | 3007| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3008 3009**示例：** 3010 3011```ts 3012import { BusinessError } from '@kit.BasicServicesKit'; 3013 3014const callback = (height: number) => { 3015 // ... 3016} 3017try { 3018 windowClass.on('keyboardHeightChange', callback); 3019 3020 windowClass.off('keyboardHeightChange', callback); 3021 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3022 windowClass.off('keyboardHeightChange'); 3023} catch (exception) { 3024 console.error(`Failed to disable the listener for keyboard height changes. Cause code: ${exception.code}, message: ${exception.message}`); 3025} 3026``` 3027 3028## on('keyboardWillShow')<sup>20+</sup> 3029 3030on(type: 'keyboardWillShow', callback: Callback<KeyboardInfo>): void 3031 3032开启固定态软键盘即将开始显示的监听。此监听在固定态软键盘即将开始显示或软键盘由悬浮态切换为固定态时触发。 3033 3034改变软键盘为固定态或者悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3035 3036**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3037 3038**系统能力：** SystemCapability.Window.SessionManager 3039 3040**参数：** 3041 3042| 参数名 | 类型 | 必填 | 说明 | 3043| -------- | ------------------- | ---- |-------------------------------------------| 3044| type | string | 是 | 监听事件，固定为'keyboardWillShow'，即固定态软键盘即将开始显示的事件。 | 3045| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 是 | 回调函数。返回软键盘窗口信息。 | 3046 3047**错误码：** 3048 3049以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3050 3051| 错误码ID | 错误信息 | 3052| ------- | -------------------------------------------- | 3053| 801 | Capability not supported. Function keyboardWillShow can not work correctly due to limited device capabilities. | 3054| 1300002 | This window state is abnormal. | 3055 3056**示例：** 3057 3058```ts 3059import { BusinessError } from '@kit.BasicServicesKit'; 3060 3061const callback = (keyboardInfo: window.KeyboardInfo) => { 3062 console.info(`Keyboard will show animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 3063} 3064try { 3065 windowClass.on('keyboardWillShow', callback); 3066 console.info(`Register keyboard will show animation success`); 3067} catch (exception) { 3068 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3069} 3070``` 3071 3072## off('keyboardWillShow')<sup>20+</sup> 3073 3074off(type: 'keyboardWillShow', callback?: Callback<KeyboardInfo>): void 3075 3076关闭固定态软键盘即将开始显示的监听。改变输入法窗口为固定态或者悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3077 3078**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3079 3080**系统能力：** SystemCapability.Window.SessionManager 3081 3082**参数：** 3083 3084| 参数名 | 类型 | 必填 | 说明 | 3085| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3086| type | string | 是 | 监听事件，固定为'keyboardWillShow'，即固定态软键盘即将开始显示的事件。 | 3087| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 否 | 回调函数。返回软键盘窗口信息。若传入参数，则关闭该监听。如果未传入参数，则关闭所有固定态软键盘即将开始显示的监听。 | 3088 3089**错误码：** 3090 3091以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3092 3093| 错误码ID | 错误信息 | 3094| ------- | -------------------------------------------- | 3095| 801 | Capability not supported. Function keyboardWillShow can not work correctly due to limited device capabilities. | 3096| 1300002 | This window state is abnormal. | 3097 3098**示例：** 3099 3100```ts 3101import { BusinessError } from '@kit.BasicServicesKit'; 3102 3103const callback = (keyboardInfo: window.KeyboardInfo) => { 3104 console.info(`Keyboard will show animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 3105} 3106try { 3107 windowClass.on('keyboardWillShow', callback); 3108 windowClass.off('keyboardWillShow', callback); 3109 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3110 windowClass.off('keyboardWillShow'); 3111 console.info(`Unregister keyboard will show animation success`); 3112} catch (exception) { 3113 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3114} 3115``` 3116 3117## on('keyboardWillHide')<sup>20+</sup> 3118 3119on(type: 'keyboardWillHide', callback: Callback<KeyboardInfo>): void 3120 3121开启固定态软键盘即将开始隐藏的监听。此监听在固定态软键盘即将开始隐藏或软键盘由固定态切换为悬浮态时触发。 3122 3123改变软键盘为固定态或者悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3124 3125**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3126 3127**系统能力：** SystemCapability.Window.SessionManager 3128 3129**参数：** 3130 3131| 参数名 | 类型 | 必填 | 说明 | 3132| -------- | ------------------- | ---- |-------------------------------------------| 3133| type | string | 是 | 监听事件，固定为'keyboardWillHide'，即固定态软键盘即将开始隐藏的事件。 | 3134| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 是 | 回调函数。返回软键盘窗口信息。 | 3135 3136**错误码：** 3137 3138以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3139 3140| 错误码ID | 错误信息 | 3141| ------- | -------------------------------------------- | 3142| 801 | Capability not supported. Function keyboardWillHide can not work correctly due to limited device capabilities. | 3143| 1300002 | This window state is abnormal. | 3144 3145**示例：** 3146 3147```ts 3148import { BusinessError } from '@kit.BasicServicesKit'; 3149 3150const callback = (keyboardInfo: window.KeyboardInfo) => { 3151 console.info(`Keyboard will hide animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 3152} 3153try { 3154 windowClass.on('keyboardWillHide', callback); 3155 console.info(`Register keyboard will hide animation success`); 3156} catch (exception) { 3157 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3158} 3159``` 3160 3161## off('keyboardWillHide')<sup>20+</sup> 3162 3163off(type: 'keyboardWillHide', callback?: Callback<KeyboardInfo>): void 3164 3165关闭固定态软键盘即将开始隐藏的监听。改变输入法窗口为固定态切换至悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3166 3167**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3168 3169**系统能力：** SystemCapability.Window.SessionManager 3170 3171**参数：** 3172 3173| 参数名 | 类型 | 必填 | 说明 | 3174| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3175| type | string | 是 | 监听事件，固定为'keyboardWillHide'，即固定态软键盘即将开始隐藏的事件。 | 3176| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 否 | 回调函数。返回软键盘窗口信息。若传入参数，则关闭该监听。如果未传入参数，则关闭所有固定态软键盘即将开始隐藏的监听。 | 3177 3178**错误码：** 3179 3180以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3181 3182| 错误码ID | 错误信息 | 3183| ------- | -------------------------------------------- | 3184| 801 | Capability not supported. Function keyboardWillHide can not work correctly due to limited device capabilities. | 3185| 1300002 | This window state is abnormal. | 3186 3187**示例：** 3188 3189```ts 3190import { BusinessError } from '@kit.BasicServicesKit'; 3191 3192const callback = (keyboardInfo: window.KeyboardInfo) => { 3193 console.info(`Keyboard will hide animation. keyboardInfo: ` + JSON.stringify(keyboardInfo)); 3194} 3195try { 3196 windowClass.on('keyboardWillHide', callback); 3197 windowClass.off('keyboardWillHide', callback); 3198 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3199 windowClass.off('keyboardWillHide'); 3200 console.info(`Unregister keyboard will hide animation success`); 3201} catch (exception) { 3202 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3203} 3204``` 3205 3206## on('keyboardDidShow')<sup>18+</sup> 3207 3208on(type: 'keyboardDidShow', callback: Callback<KeyboardInfo>): void 3209 3210开启固定态软键盘显示动画完成的监听。此监听在固定态软键盘显示动画完成或软键盘由悬浮态切换至固定态时触发。 3211 3212改变软键盘为固定态或者悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3213 3214**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3215 3216**系统能力：** SystemCapability.Window.SessionManager 3217 3218**参数：** 3219 3220| 参数名 | 类型 | 必填 | 说明 | 3221| -------- | ------------------- | ---- |-------------------------------------------| 3222| type | string | 是 | 监听事件，固定为'keyboardDidShow'，即固定态软键盘显示动画完成事件。 | 3223| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 是 | 回调函数。返回软键盘窗口信息。 | 3224 3225**错误码：** 3226 3227以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3228 3229| 错误码ID | 错误信息 | 3230| ------- | -------------------------------------------- | 3231| 801 | Capability not supported. Function keyboardDidShow can not work correctly due to limited device capabilities. | 3232| 1300002 | This window state is abnormal. | 3233 3234**示例：** 3235 3236```ts 3237import { BusinessError } from '@kit.BasicServicesKit'; 3238 3239try { 3240 windowClass.on('keyboardDidShow', (keyboardInfo) => { 3241 console.info('keyboard show animation completion. keyboardInfo: ' + JSON.stringify(keyboardInfo)); 3242 }); 3243} catch (exception) { 3244 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3245} 3246``` 3247 3248## off('keyboardDidShow')<sup>18+</sup> 3249 3250off(type: 'keyboardDidShow', callback?: Callback<KeyboardInfo>): void 3251 3252关闭固定态软键盘显示动画完成的监听。改变输入法窗口为固定态或者悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3253 3254**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3255 3256**系统能力：** SystemCapability.Window.SessionManager 3257 3258**参数：** 3259 3260| 参数名 | 类型 | 必填 | 说明 | 3261| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3262| type | string | 是 | 监听事件，固定为'keyboardDidShow'，即固定态软键盘显示动画完成事件。 | 3263| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 否 | 回调函数。返回软键盘窗口信息。若传入参数，则关闭该监听。如果未传入参数，则关闭所有固定态软键盘显示动画完成的监听。 | 3264 3265**错误码：** 3266 3267以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3268 3269| 错误码ID | 错误信息 | 3270| ------- | -------------------------------------------- | 3271| 801 | Capability not supported. Function keyboardDidShow can not work correctly due to limited device capabilities. | 3272| 1300002 | This window state is abnormal. | 3273 3274**示例：** 3275 3276```ts 3277import { BusinessError } from '@kit.BasicServicesKit'; 3278 3279const callback = (keyboardInfo: window.KeyboardInfo) => { 3280 // ... 3281} 3282try { 3283 windowClass.on('keyboardDidShow', callback); 3284 windowClass.off('keyboardDidShow', callback); 3285 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3286 windowClass.off('keyboardDidShow'); 3287} catch (exception) { 3288 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3289} 3290``` 3291 3292## on('keyboardDidHide')<sup>18+</sup> 3293 3294on(type: 'keyboardDidHide', callback: Callback<KeyboardInfo>): void 3295 3296开启固定态软键盘隐藏动画完成的监听。此监听在固定态软键盘隐藏动画完成或软键盘由固定态切换至悬浮态时触发。 3297 3298改变软键盘为固定态或者悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3299 3300**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3301 3302**系统能力：** SystemCapability.Window.SessionManager 3303 3304**参数：** 3305 3306| 参数名 | 类型 | 必填 | 说明 | 3307| -------- | ------------------- | ---- |-------------------------------------------| 3308| type | string | 是 | 监听事件，固定为'keyboardDidHide'，即固定态软键盘隐藏动画完成事件。 | 3309| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 是 | 回调函数。返回软键盘窗口信息。 | 3310 3311**错误码：** 3312 3313以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3314 3315| 错误码ID | 错误信息 | 3316| ------- | -------------------------------------------- | 3317| 801 | Capability not supported. Function keyboardDidHide can not work correctly due to limited device capabilities. | 3318| 1300002 | This window state is abnormal. | 3319 3320**示例：** 3321 3322```ts 3323import { BusinessError } from '@kit.BasicServicesKit'; 3324 3325try { 3326 windowClass.on('keyboardDidHide', (keyboardInfo) => { 3327 console.info('keyboard hide animation completion. keyboardInfo: ' + JSON.stringify(keyboardInfo)); 3328 }); 3329} catch (exception) { 3330 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3331} 3332``` 3333 3334## off('keyboardDidHide')<sup>18+</sup> 3335 3336off(type: 'keyboardDidHide', callback?: Callback<KeyboardInfo>): void 3337 3338关闭固定态软键盘隐藏动画完成的监听。改变输入法窗口为固定态切换至悬浮态方法详细介绍请参见[输入法服务](../apis-ime-kit/js-apis-inputmethodengine.md#changeflag10)。 3339 3340**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3341 3342**系统能力：** SystemCapability.Window.SessionManager 3343 3344**参数：** 3345 3346| 参数名 | 类型 | 必填 | 说明 | 3347| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3348| type | string | 是 | 监听事件，固定为'keyboardDidHide'，即固定态软键盘隐藏动画完成事件。 | 3349| callback | Callback<[KeyboardInfo](arkts-apis-window-i.md#keyboardinfo18)> | 否 | 回调函数。返回软键盘窗口信息。若传入参数，则关闭该监听。如果未传入参数，则关闭所有固定态软键盘隐藏动画完成的监听。 | 3350 3351**错误码：** 3352 3353以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3354 3355| 错误码ID | 错误信息 | 3356| ------- | -------------------------------------------- | 3357| 801 | Capability not supported. Function keyboardDidHide can not work correctly due to limited device capabilities. | 3358| 1300002 | This window state is abnormal. | 3359 3360**示例：** 3361 3362```ts 3363import { BusinessError } from '@kit.BasicServicesKit'; 3364 3365const callback = (keyboardInfo: window.KeyboardInfo) => { 3366 // ... 3367} 3368try { 3369 windowClass.on('keyboardDidHide', callback); 3370 windowClass.off('keyboardDidHide', callback); 3371 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3372 windowClass.off('keyboardDidHide'); 3373} catch (exception) { 3374 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3375} 3376``` 3377 3378## on('touchOutside')<sup>11+</sup> 3379 3380on(type: 'touchOutside', callback: Callback<void>): void 3381 3382开启本窗口区域范围外的点击事件的监听。 3383 3384**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3385 3386**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3387 3388**参数：** 3389 3390| 参数名 | 类型 | 必填 | 说明 | 3391| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3392| type | string | 是 | 监听事件，固定为'touchOutside'，即本窗口范围外的点击事件。 | 3393| callback | Callback<void> | 是 | 回调函数。当点击事件发生在本窗口范围之外的回调。 | 3394 3395**错误码：** 3396 3397以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3398 3399| 错误码ID | 错误信息 | 3400| ------- | -------------------------------------------- | 3401| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3402 3403**示例：** 3404 3405```ts 3406try { 3407 windowClass.on('touchOutside', () => { 3408 console.info('touch outside'); 3409 }); 3410} catch (exception) { 3411 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3412} 3413``` 3414 3415## off('touchOutside')<sup>11+</sup> 3416 3417off(type: 'touchOutside', callback?: Callback<void>): void 3418 3419关闭本窗口区域范围外的点击事件的监听。 3420 3421**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3422 3423**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3424 3425**参数：** 3426 3427| 参数名 | 类型 | 必填 | 说明 | 3428| -------- |----------------------| ---- |--------------------------------------| 3429| type | string | 是 | 监听事件，固定为'touchOutside'，即本窗口范围外的点击事件。 | 3430| callback | Callback<void> | 否 | 回调函数。当点击事件发生在本窗口范围之外的回调。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有本窗口区域范围外的点击事件的监听。 | 3431 3432**错误码：** 3433 3434以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3435 3436| 错误码ID | 错误信息 | 3437| ------- | -------------------------------------------- | 3438| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3439 3440**示例：** 3441 3442```ts 3443const callback = () => { 3444 // ... 3445} 3446try { 3447 windowClass.on('touchOutside', callback); 3448 windowClass.off('touchOutside', callback); 3449 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3450 windowClass.off('touchOutside'); 3451} catch (exception) { 3452 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3453} 3454``` 3455 3456## on('screenshot')<sup>9+</sup> 3457 3458on(type: 'screenshot', callback: Callback<void>): void 3459 3460开启截屏事件的监听。 3461 3462**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3463 3464**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3465 3466**参数：** 3467 3468| 参数名 | 类型 | 必填 | 说明 | 3469| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3470| type | string | 是 | 监听事件，固定为'screenshot'，即截屏事件，对控制中心截屏、hdc命令截屏、整屏截屏接口生效。 | 3471| callback | Callback<void> | 是 | 回调函数。发生截屏事件时的回调。 | 3472 3473**错误码：** 3474 3475以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3476 3477| 错误码ID | 错误信息 | 3478| ------- | -------------------------------------------- | 3479| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3480 3481**示例：** 3482 3483```ts 3484try { 3485 windowClass.on('screenshot', () => { 3486 console.info('screenshot happened'); 3487 }); 3488} catch (exception) { 3489 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3490} 3491``` 3492 3493## off('screenshot')<sup>9+</sup> 3494 3495off(type: 'screenshot', callback?: Callback<void>): void 3496 3497关闭截屏事件的监听。 3498 3499**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3500 3501**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3502 3503**参数：** 3504 3505| 参数名 | 类型 | 必填 | 说明 | 3506| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3507| type | string | 是 | 监听事件，固定为'screenshot'，即截屏事件。 | 3508| callback | Callback<void> | 否 | 回调函数。发生截屏事件时的回调。若传入参数，则关闭该监听。若未传入参数，则关闭所有截屏事件的监听。 | 3509 3510**错误码：** 3511 3512以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3513 3514| 错误码ID | 错误信息 | 3515| ------- | -------------------------------------------- | 3516| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3517 3518**示例：** 3519 3520```ts 3521let callback = () => { 3522 console.info('screenshot happened'); 3523}; 3524try { 3525 windowClass.on('screenshot', callback); 3526 windowClass.off('screenshot', callback); 3527 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3528 windowClass.off('screenshot'); 3529} catch (exception) { 3530 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3531} 3532``` 3533 3534## on('screenshotAppEvent')<sup>20+</sup> 3535 3536on(type: 'screenshotAppEvent', callback: Callback<ScreenshotEventType>): void 3537 3538开启屏幕截屏事件类型的监听。 3539 3540**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3541 3542**参数：** 3543 3544| 参数名 | 类型 | 必填 | 说明 | 3545| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3546| type | string | 是 | 监听事件，固定为'screenshotAppEvent'，即屏幕截屏的事件类型，对控制中心截屏、快捷键截屏以及滚动截屏生效。 | 3547| callback | Callback<[ScreenshotEventType](arkts-apis-window-e.md#screenshoteventtype20)> | 是 | 回调函数。返回触发的截屏事件类型。 | 3548 3549**错误码：** 3550 3551以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 3552 3553| 错误码ID | 错误信息 | 3554| ------- | ------------------------------ | 3555| 1300002 | This window state is abnormal. | 3556| 1300003 | This window manager service works abnormally. | 3557 3558**示例：** 3559 3560```ts 3561const callback = (eventType: window.ScreenshotEventType) => { 3562 console.info(`screenshotAppEvent happened. Event: ${eventType}`); 3563} 3564try { 3565 windowClass.on('screenshotAppEvent', callback); 3566} catch (exception) { 3567 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3568} 3569``` 3570 3571## off('screenshotAppEvent')<sup>20+</sup> 3572 3573off(type: 'screenshotAppEvent', callback?: Callback<ScreenshotEventType>): void 3574 3575关闭屏幕截屏事件类型的监听。 3576 3577**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3578 3579**参数：** 3580 3581| 参数名 | 类型 | 必填 | 说明 | 3582| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3583| type | string | 是 | 监听事件，固定为'screenshotAppEvent'，即屏幕截屏的事件类型。 | 3584| callback | Callback<[ScreenshotEventType](arkts-apis-window-e.md#screenshoteventtype20)> | 否 | 回调函数。返回触发的截屏事件类型。若传入参数，则关闭该监听。若未传入参数，则关闭所有窗口截图事件的监听。 | 3585 3586**错误码：** 3587 3588以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 3589 3590| 错误码ID | 错误信息 | 3591| ------- | ------------------------------ | 3592| 1300002 | This window state is abnormal. | 3593| 1300003 | This window manager service works abnormally. | 3594 3595**示例：** 3596 3597```ts 3598const callback = (eventType: window.ScreenshotEventType) => { 3599 // ... 3600} 3601try { 3602 // 通过on接口开启监听 3603 windowClass.on('screenshotAppEvent', callback); 3604 // 关闭指定callback的监听 3605 windowClass.off('screenshotAppEvent', callback); 3606 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3607 windowClass.off('screenshotAppEvent'); 3608} catch (exception) { 3609 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3610} 3611``` 3612 3613## on('dialogTargetTouch')<sup>10+</sup> 3614 3615on(type: 'dialogTargetTouch', callback: Callback<void>): void 3616 3617开启模态窗口所遮盖窗口的点击或触摸事件的监听，除模态窗口以外其他窗口调用此接口不生效。 3618 3619**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3620 3621**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3622 3623**参数：** 3624 3625| 参数名 | 类型 | 必填 | 说明 | 3626| -------- | ------------------- | ---- | ------------------------------------------------------------ | 3627| type | string | 是 | 监听事件，固定为'dialogTargetTouch'，即模态窗口所遮盖窗口的点击或触摸事件。 | 3628| callback | Callback<void>| 是 | 回调函数。当点击或触摸事件发生在模态窗口所遮盖窗口的回调。 | 3629 3630**错误码：** 3631 3632以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3633 3634| 错误码ID | 错误信息 | 3635| ------- | -------------------------------------------- | 3636| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3637 3638**示例：** 3639 3640```ts 3641try { 3642 windowClass.on('dialogTargetTouch', () => { 3643 console.info('touch dialog target'); 3644 }); 3645} catch (exception) { 3646 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3647} 3648``` 3649 3650## off('dialogTargetTouch')<sup>10+</sup> 3651 3652off(type: 'dialogTargetTouch', callback?: Callback<void>): void 3653 3654关闭模态窗口目标窗口的点击事件的监听。 3655 3656**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3657 3658**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3659 3660**参数：** 3661 3662| 参数名 | 类型 | 必填 | 说明 | 3663| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 3664| type | string | 是 | 监听事件，固定为'dialogTargetTouch'，即模态窗口目标窗口的点击事件。 | 3665| callback | Callback<void> | 否 | 回调函数。当点击事件发生在模态窗口目标窗口的回调。若传入参数，则关闭该监听。若未传入参数，则关闭所有模态窗口目标窗口的点击事件的监听。 | 3666 3667**错误码：** 3668 3669以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3670 3671| 错误码ID | 错误信息 | 3672| ------- | -------------------------------------------- | 3673| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3674 3675**示例：** 3676 3677```ts 3678const callback = () => { 3679 // ... 3680} 3681try { 3682 windowClass.on('dialogTargetTouch', callback); 3683 windowClass.off('dialogTargetTouch', callback); 3684 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3685 windowClass.off('dialogTargetTouch'); 3686} catch (exception) { 3687 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3688} 3689``` 3690 3691## on('windowEvent')<sup>10+</sup> 3692 3693on(type: 'windowEvent', callback: Callback<WindowEventType>): void 3694 3695开启窗口生命周期变化的监听。 3696 3697**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3698 3699**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3700 3701**参数：** 3702 3703| 参数名 | 类型 | 必填 | 说明 | 3704| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3705| type | string | 是 | 监听事件，固定为'windowEvent'，即窗口生命周期变化事件。 | 3706| callback | Callback<[WindowEventType](arkts-apis-window-e.md#windoweventtype10)> | 是 | 回调函数。返回当前的窗口生命周期状态。 | 3707 3708**错误码：** 3709 3710以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3711 3712| 错误码ID | 错误信息 | 3713| ------- | -------------------------------------------- | 3714| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3715 3716**示例：** 3717 3718```ts 3719try { 3720 windowClass.on('windowEvent', (data) => { 3721 console.info('Window event happened. Event:' + JSON.stringify(data)); 3722 }); 3723} catch (exception) { 3724 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3725} 3726``` 3727 3728## off('windowEvent')<sup>10+</sup> 3729 3730off(type: 'windowEvent', callback?: Callback<WindowEventType>): void 3731 3732关闭窗口生命周期变化的监听。 3733 3734**系统能力：** SystemCapability.WindowManager.WindowManager.Core 3735 3736**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3737 3738**参数：** 3739 3740| 参数名 | 类型 | 必填 | 说明 | 3741| -------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ | 3742| type | string | 是 | 监听事件，固定为'windowEvent'，即窗口生命周期变化事件。 | 3743| callback | Callback<[WindowEventType](arkts-apis-window-e.md#windoweventtype10)> | 否 | 回调函数。返回当前的窗口生命周期状态。若传入参数，则关闭该监听。若未传入参数，则关闭所有窗口生命周期变化的监听。 | 3744 3745**错误码：** 3746 3747以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3748 3749| 错误码ID | 错误信息 | 3750| ------- | -------------------------------------------- | 3751| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3752 3753**示例：** 3754 3755```ts 3756const callback = (windowEventType: window.WindowEventType) => { 3757 // ... 3758} 3759try { 3760 // 通过on接口开启监听 3761 windowClass.on('windowEvent', callback); 3762 // 关闭指定callback的监听 3763 windowClass.off('windowEvent', callback); 3764 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3765 windowClass.off('windowEvent'); 3766} catch (exception) { 3767 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3768} 3769``` 3770 3771## on('displayIdChange')<sup>14+</sup> 3772 3773on(type: 'displayIdChange', callback: Callback<number>): void 3774 3775开启本窗口所处屏幕变化事件的监听。比如，当前窗口移动到其他屏幕时，可以从此接口监听到这个行为。 3776 3777**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 3778 3779**系统能力：** SystemCapability.Window.SessionManager 3780 3781**参数：** 3782 3783| 参数名 | 类型 | 必填 | 说明 | 3784| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3785| type | string | 是 | 监听事件，固定为'displayIdChange'，即本窗口所处屏幕变化的事件。 | 3786| callback | Callback<number> | 是 | 回调函数。当本窗口所处屏幕发生变化后的回调。回调函数返回number类型参数，表示窗口所处屏幕的displayId。 | 3787 3788**错误码：** 3789 3790以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3791 3792| 错误码ID | 错误信息 | 3793| ------- | ------------------------------ | 3794| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3795| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3796| 1300002 | This window state is abnormal. | 3797 3798**示例：** 3799 3800```ts 3801try { 3802 windowClass.on('displayIdChange', (data) => { 3803 console.info('Window displayId changed, displayId=' + JSON.stringify(data)); 3804 }); 3805} catch (exception) { 3806 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3807} 3808``` 3809## off('displayIdChange')<sup>14+</sup> 3810 3811off(type: 'displayIdChange', callback?: Callback<number>): void 3812 3813关闭本窗口所处屏幕变化事件的监听。 3814 3815**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 3816 3817**系统能力：** SystemCapability.Window.SessionManager 3818 3819**参数：** 3820 3821| 参数名 | 类型 | 必填 | 说明 | 3822| -------- |----------------------------| ---- |--------------------------------------| 3823| type | string | 是 | 监听事件，固定为'displayIdChange'，即本窗口所处屏幕变化的事件。 | 3824| callback | Callback<number> | 否 | 回调函数。当本窗口所处屏幕发生变化时的回调。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有本窗口所处屏幕变化事件的回调。 | 3825 3826**错误码：** 3827 3828以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3829 3830| 错误码ID | 错误信息 | 3831| ------- | ------------------------------ | 3832| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3833| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3834| 1300002 | This window state is abnormal. | 3835 3836**示例：** 3837 3838```ts 3839const callback = (displayId: number) => { 3840 // ... 3841} 3842try { 3843 // 通过on接口开启监听 3844 windowClass.on('displayIdChange', callback); 3845 // 关闭指定callback的监听 3846 windowClass.off('displayIdChange', callback); 3847 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3848 windowClass.off('displayIdChange'); 3849} catch (exception) { 3850 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3851} 3852``` 3853 3854## on('windowVisibilityChange')<sup>11+</sup> 3855 3856on(type: 'windowVisibilityChange', callback: Callback<boolean>): void 3857 3858开启本窗口可见状态变化事件的监听。 3859 3860**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3861 3862**系统能力：** SystemCapability.Window.SessionManager 3863 3864**参数：** 3865 3866| 参数名 | 类型 | 必填 | 说明 | 3867| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3868| type | string | 是 | 监听事件，固定为'windowVisibilityChange'，即本窗口可见状态变化的事件。 | 3869| callback | Callback<boolean> | 是 | 回调函数。当本窗口可见状态发生变化后的回调。回调函数返回boolean类型参数，当返回参数为true时表示窗口可见，否则表示窗口不可见。 | 3870 3871**错误码：** 3872 3873以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3874 3875| 错误码ID | 错误信息 | 3876| ------- | ------------------------------ | 3877| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3878| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3879| 1300002 | This window state is abnormal. | 3880| 1300003 | This window manager service works abnormally. | 3881 3882**示例：** 3883 3884```ts 3885try { 3886 windowClass.on('windowVisibilityChange', (boolean) => { 3887 console.info('Window visibility changed, isVisible=' + boolean); 3888 }); 3889} catch (exception) { 3890 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3891} 3892``` 3893 3894## off('windowVisibilityChange')<sup>11+</sup> 3895 3896off(type: 'windowVisibilityChange', callback?: Callback<boolean>): void 3897 3898关闭本窗口可见状态变化事件的监听。 3899 3900**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3901 3902**系统能力：** SystemCapability.Window.SessionManager 3903 3904**参数：** 3905 3906| 参数名 | 类型 | 必填 | 说明 | 3907| -------- |----------------------------| ---- |--------------------------------------| 3908| type | string | 是 | 监听事件，固定为'windowVisibilityChange'，即本窗口可见状态变化的事件。 | 3909| callback | Callback<boolean> | 否 | 回调函数。当本窗口可见状态发生变化时的回调。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有本窗口可见状态变化事件的回调。 | 3910 3911**错误码：** 3912 3913以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3914 3915| 错误码ID | 错误信息 | 3916| ------- | ------------------------------ | 3917| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 3918| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3919| 1300002 | This window state is abnormal. | 3920| 1300003 | This window manager service works abnormally. | 3921 3922**示例：** 3923 3924```ts 3925const callback = (bool: boolean) => { 3926 // ... 3927} 3928try { 3929 // 通过on接口开启监听 3930 windowClass.on('windowVisibilityChange', callback); 3931 // 关闭指定callback的监听 3932 windowClass.off('windowVisibilityChange', callback); 3933 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 3934 windowClass.off('windowVisibilityChange'); 3935} catch (exception) { 3936 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 3937} 3938``` 3939 3940## on('systemDensityChange')<sup>15+</sup> 3941 3942on(type: 'systemDensityChange', callback: Callback<number>): void 3943 3944开启本窗口所处屏幕的系统显示大小缩放系数变化事件的监听。比如，当调整窗口所处屏幕的显示大小缩放系数时，可以从此接口监听到这个行为。 3945 3946**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 3947 3948**系统能力：** SystemCapability.Window.SessionManager 3949 3950**参数：** 3951 3952| 参数名 | 类型 | 必填 | 说明 | 3953| -------- | --------------------------| ---- | ------------------------------------------------------------ | 3954| type | string | 是 | 监听事件，固定为'systemDensityChange'，即本窗口所处屏幕的系统显示大小缩放系数变化的事件。 | 3955| callback | Callback<number> | 是 | 回调函数。当本窗口所处屏幕的系统显示大小缩放系数发生变化后的回调。回调函数返回number类型参数，表示当前窗口所处屏幕的系统显示大小缩放系数。 | 3956 3957**错误码：** 3958 3959 3960以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 3961 3962| 错误码ID | 错误信息 | 3963| ------- | ------------------------------ | 3964| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 3965| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 3966| 1300002 | This window state is abnormal. | 3967 3968**示例：** 3969 3970```ts 3971const callback = (density: number) => { 3972 console.info('System density changed, density=' + JSON.stringify(density)); 3973} 3974try { 3975 windowClass.on('systemDensityChange', callback); 3976} catch (exception) { 3977 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 3978} 3979``` 3980## off('systemDensityChange')<sup>15+</sup> 3981 3982off(type: 'systemDensityChange', callback?: Callback<number>): void 3983 3984关闭本窗口所处屏幕的系统显示大小缩放系数变化事件的监听。 3985 3986**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 3987 3988**系统能力：** SystemCapability.Window.SessionManager 3989 3990**参数：** 3991 3992| 参数名 | 类型 | 必填 | 说明 | 3993| -------- |----------------------------| ---- |--------------------------------------| 3994| type | string | 是 | 监听事件，固定为'systemDensityChange'，即本窗口所处屏幕的系统显示大小缩放系数变化的事件。 | 3995| callback | Callback<number> | 否 | 回调函数。当本窗口所处屏幕的系统显示大小缩放系数发生变化后的回调。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有本窗口所处屏幕的系统显示大小缩放系数变化事件的回调。 | 3996 3997**错误码：** 3998 3999以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4000 4001| 错误码ID | 错误信息 | 4002| ------- | ------------------------------ | 4003| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4004| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4005| 1300002 | This window state is abnormal. | 4006 4007**示例：** 4008 4009```ts 4010const callback = (density: number) => { 4011 // ... 4012} 4013try { 4014 // 通过on接口开启监听 4015 windowClass.on('systemDensityChange', callback); 4016 // 关闭指定callback的监听 4017 windowClass.off('systemDensityChange', callback); 4018 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4019 windowClass.off('systemDensityChange'); 4020} catch (exception) { 4021 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4022} 4023``` 4024 4025## on('noInteractionDetected')<sup>12+</sup> 4026 4027on(type: 'noInteractionDetected', timeout: number, callback: Callback<void>): void 4028 4029开启本窗口在指定超时时间内无交互事件的监听，交互事件支持物理键盘输入事件和屏幕触控点击事件，不支持软键盘输入事件。 4030 4031**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4032 4033**系统能力：** SystemCapability.Window.SessionManager 4034 4035**参数：** 4036 4037| 参数名 | 类型 | 必填 | 说明 | 4038| -------- | --------------------------| ---- | ------------------------------------------------------------ | 4039| type | string | 是 | 监听事件，固定为'noInteractionDetected'，即本窗口在指定超时时间内无交互的事件。 | 4040| timeout | number | 是 | 指定本窗口在多长时间内无交互即回调，单位为秒(s)。该参数仅支持整数输入，负数和小数为非法参数。 | 4041| callback | Callback<void> | 是 | 回调函数。当本窗口在指定超时时间内无交互事件时的回调。 | 4042 4043**错误码：** 4044 4045以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4046 4047| 错误码ID | 错误信息 | 4048| ------- | ------------------------------ | 4049| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4050| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4051| 1300002 | This window state is abnormal. | 4052| 1300003 | This window manager service works abnormally. | 4053 4054**示例：** 4055 4056```ts 4057try { 4058 windowClass.on('noInteractionDetected', 60, () => { 4059 console.info('no interaction in 60s'); 4060 }); 4061} catch (exception) { 4062 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4063} 4064``` 4065 4066## off('noInteractionDetected')<sup>12+</sup> 4067 4068off(type: 'noInteractionDetected', callback?: Callback<void>): void 4069 4070关闭本窗口在指定超时时间内无交互事件的监听，交互事件支持物理键盘输入事件和屏幕触控点击事件，不支持软键盘输入事件。 4071 4072**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4073 4074**系统能力：** SystemCapability.Window.SessionManager 4075 4076**参数：** 4077 4078| 参数名 | 类型 | 必填 | 说明 | 4079| -------- |----------------------------| ---- |--------------------------------------| 4080| type | string | 是 | 监听事件，固定为'noInteractionDetected'，即本窗口在指定超时时间内无交互的事件。 | 4081| callback | Callback<void> | 否 | 回调函数，当本窗口在指定超时时间内无交互事件时的回调。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有本窗口在指定超时时间内无交互事件的监听。 | 4082 4083**错误码：** 4084 4085以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4086 4087| 错误码ID | 错误信息 | 4088| ------- | ------------------------------ | 4089| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4090| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4091| 1300002 | This window state is abnormal. | 4092| 1300003 | This window manager service works abnormally. | 4093 4094**示例：** 4095 4096```ts 4097const callback = () => { 4098 // ... 4099} 4100try { 4101 windowClass.on('noInteractionDetected', 60, callback); 4102 windowClass.off('noInteractionDetected', callback); 4103 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4104 windowClass.off('noInteractionDetected'); 4105} catch (exception) { 4106 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4107} 4108``` 4109 4110## on('windowStatusChange')<sup>11+</sup> 4111 4112on(type: 'windowStatusChange', callback: Callback<WindowStatusType>): void 4113 4114开启窗口模式变化的监听，当窗口windowStatus发生变化时进行通知（此时窗口属性可能还没有更新）。 4115 4116**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4117 4118**系统能力：** SystemCapability.Window.SessionManager 4119 4120**参数：** 4121 4122| 参数名 | 类型 | 必填 | 说明 | 4123| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4124| type | string | 是 | 监听事件，固定为'windowStatusChange'，即窗口模式变化事件。 | 4125| callback | Callback<[WindowStatusType](arkts-apis-window-e.md#windowstatustype11)> | 是 | 回调函数。返回当前的窗口模式。 | 4126 4127**错误码：** 4128 4129以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4130 4131| 错误码ID | 错误信息 | 4132| ------- | ------------------------------ | 4133| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4134| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4135 4136**示例：** 4137 4138```ts 4139try { 4140 windowClass.on('windowStatusChange', (WindowStatusType) => { 4141 console.info('Succeeded in enabling the listener for window status changes. Data: ' + JSON.stringify(WindowStatusType)); 4142 }); 4143} catch (exception) { 4144 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4145} 4146``` 4147 4148## off('windowStatusChange')<sup>11+</sup> 4149 4150off(type: 'windowStatusChange', callback?: Callback<WindowStatusType>): void 4151 4152关闭窗口模式变化的监听。 4153 4154**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4155 4156**系统能力：** SystemCapability.Window.SessionManager 4157 4158**参数：** 4159 4160| 参数名 | 类型 | 必填 | 说明 | 4161| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 4162| type | string | 是 | 监听事件，固定为'windowStatusChange'，即窗口模式变化事件。 | 4163| callback | Callback<[WindowStatusType](arkts-apis-window-e.md#windowstatustype11)> | 否 | 回调函数。返回当前的窗口模式。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有窗口模式变化的监听。 | 4164 4165**错误码：** 4166 4167以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4168 4169| 错误码ID | 错误信息 | 4170| ------- | ------------------------------ | 4171| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4172| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4173 4174**示例：** 4175 4176```ts 4177const callback = (windowStatusType: window.WindowStatusType) => { 4178 // ... 4179} 4180try { 4181 windowClass.on('windowStatusChange', callback); 4182 windowClass.off('windowStatusChange', callback); 4183 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4184 windowClass.off('windowStatusChange'); 4185} catch (exception) { 4186 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4187} 4188``` 4189 4190## on('windowStatusDidChange')<sup>20+</sup> 4191 4192on(type: 'windowStatusDidChange', callback: Callback<WindowStatusType>): void 4193 4194开启窗口模式变化的监听，当窗口windowStatus发生变化后进行通知（此时窗口[Rect](arkts-apis-window-i.md#rect7)属性已经完成更新）。 4195 4196**系统能力：** SystemCapability.Window.SessionManager 4197 4198**参数：** 4199 4200| 参数名 | 类型 | 必填 | 说明 | 4201| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4202| type | string | 是 | 监听事件，固定为'windowStatusDidChange'，即窗口模式变化完成事件。 | 4203| callback | Callback<[WindowStatusType](arkts-apis-window-e.md#windowstatustype11)> | 是 | 回调函数。返回当前的窗口模式。 | 4204 4205**错误码：** 4206 4207以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4208 4209| 错误码ID | 错误信息 | 4210| ------- | ------------------------------ | 4211| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4212| 1300002 | This window state is abnormal. | 4213 4214**示例：** 4215 4216```ts 4217try { 4218 windowClass.on('windowStatusDidChange', (WindowStatusType) => { 4219 console.info(`Succeeded in enabling the listener for window status changes. Data: ${JSON.stringify(WindowStatusType)}`); 4220 }); 4221} catch (exception) { 4222 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4223} 4224``` 4225 4226## off('windowStatusDidChange')<sup>20+</sup> 4227 4228off(type: 'windowStatusDidChange', callback?: Callback<WindowStatusType>): void 4229 4230关闭窗口模式变化的监听。 4231 4232**系统能力：** SystemCapability.Window.SessionManager 4233 4234**参数：** 4235 4236| 参数名 | 类型 | 必填 | 说明 | 4237| -------- | ----------------------------- | ---- | -------------------------------------------------------- | 4238| type | string | 是 | 监听事件，固定为'windowStatusDidChange'，即窗口模式变化完成事件。 | 4239| callback | Callback<[WindowStatusType](arkts-apis-window-e.md#windowstatustype11)> | 否 | 回调函数。返回当前的窗口模式。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有窗口模式变化的监听。 | 4240 4241**错误码：** 4242 4243以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4244 4245| 错误码ID | 错误信息 | 4246| ------- | ------------------------------ | 4247| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4248| 1300002 | This window state is abnormal. | 4249 4250**示例：** 4251 4252```ts 4253const callback = (windowStatusType: window.WindowStatusType) => { 4254 // ... 4255} 4256try { 4257 windowClass.on('windowStatusDidChange', callback); 4258 windowClass.off('windowStatusDidChange', callback); 4259 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4260 windowClass.off('windowStatusDidChange'); 4261} catch (exception) { 4262 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4263} 4264``` 4265 4266## setWindowGrayScale<sup>12+</sup> 4267 4268setWindowGrayScale(grayScale: number): Promise<void> 4269 4270设置窗口灰阶，使用Promise异步回调。该接口需要在调用[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)使窗口加载页面内容后调用。 4271 4272**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4273 4274**系统能力：** SystemCapability.Window.SessionManager 4275 4276**参数：** 4277 4278| 参数名 | 类型 | 必填 | 说明 | 4279| --------- | ------ | -- | ---------------------------------------- | 4280| grayScale | number | 是 | 窗口灰阶。该参数为浮点数，取值范围为[0.0, 1.0]。0.0表示窗口图像无变化，1.0表示窗口图像完全转为灰度图像，0.0至1.0之间时效果呈线性变化。 | 4281 4282**返回值：** 4283 4284| 类型 | 说明 | 4285| ------------------- | ------------------------ | 4286| Promise<void> | 无返回结果的Promise对象。 | 4287 4288**错误码：** 4289 4290以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4291 4292| 错误码ID | 错误信息 | 4293| ------- | --------------------------------------------- | 4294| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4295| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4296| 1300002 | This window state is abnormal. | 4297| 1300003 | This window manager service works abnormally. | 4298 4299**示例：** 4300 4301```ts 4302import { BusinessError } from '@kit.BasicServicesKit'; 4303 4304windowClass?.setUIContent('pages/Index', (error: BusinessError) => { 4305 if (error.code) { 4306 console.error(`Failed to set the content. Cause code: ${error.code}`); 4307 return; 4308 } 4309 console.info('Succeeded in setting the content.'); 4310 let grayScale: number = 0.5; 4311 try { 4312 if (canIUse("SystemCapability.Window.SessionManager")) { 4313 let promise = windowClass?.setWindowGrayScale(grayScale); 4314 promise?.then(() => { 4315 console.info('Succeeded in setting the grayScale.'); 4316 }).catch((err: BusinessError) => { 4317 console.error(`Failed to set the grayScale. Cause code: ${err.code}, message: ${err.message}`); 4318 }); 4319 } 4320 } catch (exception) { 4321 console.error(`Failed to set the grayScale. Cause code: ${exception.code}, message: ${exception.message}`); 4322 } 4323}); 4324``` 4325 4326## on('windowTitleButtonRectChange')<sup>11+</sup> 4327 4328on(type: 'windowTitleButtonRectChange', callback: Callback<TitleButtonRect>): void 4329 4330开启窗口标题栏上的最小化、最大化、关闭按钮矩形区域变化的监听，对存在标题栏和三键区的窗口形态生效。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 4331 4332**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4333 4334**系统能力：** SystemCapability.Window.SessionManager 4335 4336**参数：** 4337 4338| 参数名 | 类型 | 必填 | 说明 | 4339| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 4340| type | string | 是 | 监听事件，固定为'windowTitleButtonRectChange'，即标题栏上的最小化、最大化、关闭按钮矩形区域变化事件。 | 4341| callback | Callback<[TitleButtonRect](arkts-apis-window-i.md#titlebuttonrect11)> | 是 | 回调函数。返回当前标题栏上的最小化、最大化、关闭按钮矩形区域。 | 4342 4343**错误码：** 4344 4345以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4346 4347| 错误码ID | 错误信息 | 4348| -------- | ------------------------------ | 4349| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4350| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4351| 1300002 | This window state is abnormal. | 4352 4353**示例：** 4354 4355```ts 4356windowClass.setUIContent('pages/WindowPage').then(() => { 4357 try { 4358 windowClass?.on('windowTitleButtonRectChange', (titleButtonRect) => { 4359 console.info('Succeeded in enabling the listener for window title buttons area changes. Data: ' + JSON.stringify(titleButtonRect)); 4360 }); 4361 } catch (exception) { 4362 console.error(`Failed to enable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4363 } 4364}) 4365``` 4366 4367## off('windowTitleButtonRectChange')<sup>11+</sup> 4368 4369off(type: 'windowTitleButtonRectChange', callback?: Callback<TitleButtonRect>): void 4370 4371关闭窗口标题栏上的最小化、最大化、关闭按钮矩形区域变化的监听，对存在标题栏和三键区的窗口形态生效。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 4372 4373**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4374 4375**系统能力：** SystemCapability.Window.SessionManager 4376 4377**参数：** 4378 4379| 参数名 | 类型 | 必填 | 说明 | 4380| -------- | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 4381| type | string | 是 | 监听事件，固定为'windowTitleButtonRectChange'，即标题栏上的最小化、最大化、关闭按钮矩形区域变化事件。 | 4382| callback | Callback<[TitleButtonRect](arkts-apis-window-i.md#titlebuttonrect11)> | 否 | 回调函数。返回当前标题栏上的最小化、最大化、关闭按钮矩形区域。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有标题栏上的最小化、最大化、关闭按钮矩形区域变化的监听。 | 4383 4384**错误码：** 4385 4386以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4387 4388| 错误码ID | 错误信息 | 4389| -------- | ------------------------------ | 4390| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4391| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4392| 1300002 | This window state is abnormal. | 4393 4394**示例：** 4395 4396```ts 4397windowClass.setUIContent('pages/WindowPage').then(() => { 4398 const callback = (titleButtonRect: window.TitleButtonRect) => { 4399 // ... 4400 } 4401 try { 4402 // 通过on接口开启监听 4403 windowClass?.on('windowTitleButtonRectChange', callback); 4404 // 关闭指定callback的监听 4405 windowClass?.off('windowTitleButtonRectChange', callback); 4406 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4407 windowClass?.off('windowTitleButtonRectChange'); 4408 } catch (exception) { 4409 console.error(`Failed to disable the listener for window title buttons area changes. Cause code: ${exception.code}, message: ${exception.message}`); 4410 } 4411}) 4412``` 4413 4414## on('windowRectChange')<sup>12+</sup> 4415 4416on(type: 'windowRectChange', callback: Callback<RectChangeOptions>): void 4417 4418开启窗口矩形（窗口位置及窗口大小）变化的监听。 4419 4420**系统能力：** SystemCapability.Window.SessionManager 4421 4422**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4423 4424**参数：** 4425 4426| 参数名 | 类型 | 必填 | 说明 | 4427| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4428| type | string | 是 | 监听事件，固定为'windowRectChange'，即窗口矩形变化事件。 | 4429| callback | Callback<[RectChangeOptions](arkts-apis-window-i.md#rectchangeoptions12)> | 是 | 回调函数。返回当前窗口矩形变化值及变化原因。 | 4430 4431**错误码：** 4432 4433以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4434 4435| 错误码ID | 错误信息 | 4436| ------- | -------------------------------------------- | 4437| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4438| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4439| 1300002 | This window state is abnormal. | 4440| 1300003 | This window manager service works abnormally. | 4441 4442**示例：** 4443 4444```ts 4445try { 4446 windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 4447 console.info(`Succeeded in enabling the listener for window rect changes. Data: ` + JSON.stringify(data)); 4448 }); 4449} catch (exception) { 4450 console.error(`Failed to disable the listener for window rect changes. Cause code: ${exception.code}, message: ${exception.message}`); 4451} 4452``` 4453 4454## off('windowRectChange')<sup>12+</sup> 4455 4456off(type: 'windowRectChange', callback?: Callback<RectChangeOptions>): void 4457 4458关闭窗口矩形（窗口位置及窗口大小）变化的监听。 4459 4460**系统能力：** SystemCapability.Window.SessionManager 4461 4462**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4463 4464**参数：** 4465 4466| 参数名 | 类型 | 必填 | 说明 | 4467| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4468| type | string | 是 | 监听事件，固定为'windowRectChange'，即窗口矩形变化事件。 | 4469| callback | Callback<[RectChangeOptions](arkts-apis-window-i.md#rectchangeoptions12)> | 否 | 回调函数。返回当前的窗口矩形及变化原因。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有窗口矩形变化的监听。 | 4470 4471**错误码：** 4472 4473以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4474 4475| 错误码ID | 错误信息 | 4476| ------- | -------------------------------------------- | 4477| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4478| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4479| 1300002 | This window state is abnormal. | 4480| 1300003 | This window manager service works abnormally. | 4481 4482**示例：** 4483 4484```ts 4485const callback = (rectChangeOptions: window.RectChangeOptions) => { 4486 // ... 4487} 4488 4489try { 4490 windowClass.on('windowRectChange', callback); 4491 windowClass.off('windowRectChange', callback); 4492 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4493 windowClass.off('windowRectChange'); 4494} catch (exception) { 4495 console.error(`Failed to disable the listener for window rect changes. Cause code: ${exception.code}, message: ${exception.message}`); 4496} 4497``` 4498 4499## on('rectChangeInGlobalDisplay')<sup>20+</sup> 4500 4501on(type: 'rectChangeInGlobalDisplay', callback: Callback<RectChangeOptions>): void 4502 4503开启全局坐标系（扩展屏场景下，以主屏左上角为原点）下窗口矩形（窗口位置及窗口大小）变化的监听事件。 4504 4505**系统能力：** SystemCapability.Window.SessionManager 4506 4507**参数：** 4508 4509| 参数名 | 类型 | 必填 | 说明 | 4510| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4511| type | string | 是 | 监听事件，固定为'rectChangeInGlobalDisplay'，即全局坐标系下窗口矩形变化事件。 | 4512| callback | Callback<[RectChangeOptions](arkts-apis-window-i.md#rectchangeoptions12)> | 是 | 回调函数。返回当前窗口矩形变化值及变化原因。 | 4513 4514**错误码：** 4515 4516以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4517 4518| 错误码ID | 错误信息 | 4519| ------- | -------------------------------------------- | 4520| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4521| 1300002 | This window state is abnormal. | 4522| 1300003 | This window manager service works abnormally. | 4523 4524**示例：** 4525 4526```ts 4527const callback = (rectChangeOptions: window.RectChangeOptions) => { 4528 console.info(`Succeeded in enabling the listener for window rect changes in global display. Data: ` + JSON.stringify(rectChangeOptions)); 4529} 4530 4531try { 4532 windowClass.on('rectChangeInGlobalDisplay', callback); 4533} catch (exception) { 4534 console.error(`Failed to enable the listener for window rect changes in global display. Cause code: ${exception.code}, message: ${exception.message}`); 4535} 4536``` 4537 4538## off('rectChangeInGlobalDisplay')<sup>20+</sup> 4539 4540off(type: 'rectChangeInGlobalDisplay', callback?: Callback<RectChangeOptions>): void 4541 4542关闭全局坐标系（扩展屏场景下，以主屏左上角为原点）下窗口矩形（窗口位置及窗口大小）变化的监听事件。 4543 4544**系统能力：** SystemCapability.Window.SessionManager 4545 4546**参数：** 4547 4548| 参数名 | 类型 | 必填 | 说明 | 4549| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4550| type | string | 是 | 监听事件，固定为'rectChangeInGlobalDisplay'，即全局坐标系下窗口矩形变化事件。 | 4551| callback | Callback<[RectChangeOptions](arkts-apis-window-i.md#rectchangeoptions12)> | 否 | 回调函数。返回当前的窗口矩形及变化原因。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有全局坐标系下窗口矩形变化的监听。 | 4552 4553**错误码：** 4554 4555以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4556 4557| 错误码ID | 错误信息 | 4558| ------- | -------------------------------------------- | 4559| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4560| 1300002 | This window state is abnormal. | 4561| 1300003 | This window manager service works abnormally. | 4562 4563**示例：** 4564 4565```ts 4566const callback = (rectChangeOptions: window.RectChangeOptions) => { 4567 // ... 4568} 4569 4570try { 4571 windowClass.on('rectChangeInGlobalDisplay', callback); 4572 windowClass.off('rectChangeInGlobalDisplay', callback); 4573 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4574 windowClass.off('rectChangeInGlobalDisplay'); 4575} catch (exception) { 4576 console.error(`Failed to disable the listener for window rect changes in global display. Cause code: ${exception.code}, message: ${exception.message}`); 4577} 4578``` 4579 4580## on('subWindowClose')<sup>12+</sup> 4581 4582on(type: 'subWindowClose', callback: Callback<void>): void 4583 4584开启子窗口关闭事件的监听。此监听仅在点击系统提供的右上角关闭按钮关闭子窗时触发，其余关闭方式不触发回调。 4585 4586当重复注册窗口关闭事件的监听时，最后一次注册成功的监听事件生效。 4587 4588该接口触发的窗口关闭事件监听回调函数是同步执行，子窗口的异步关闭事件监听参考[on('windowWillClose')](#onwindowwillclose15)方法。 4589 4590如果存在[on('windowWillClose')](#onwindowwillclose15)监听事件，只响应[on('windowWillClose')](#onwindowwillclose15)接口。 4591 4592**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4593 4594**系统能力：** SystemCapability.Window.SessionManager 4595 4596**参数：** 4597 4598| 参数名 | 类型 | 必填 | 说明 | 4599| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4600| type | string | 是 | 监听事件，固定为'subWindowClose'，即子窗口关闭事件。 | 4601| callback | Callback<void> | 是 | 回调函数。当点击子窗口右上角关闭按钮事件发生时的回调。该回调函数不返回任何参数。回调函数内部逻辑的返回值决定当前子窗是否继续关闭，如果返回boolean类型的true表示不关闭子窗，返回false或者其他非boolean类型表示关闭子窗。 | 4602 4603**错误码：** 4604 4605以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4606 4607| 错误码ID | 错误信息 | 4608| ------- | -------------------------------------------- | 4609| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4610| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4611| 1300002 | This window state is abnormal. | 4612| 1300004 | Unauthorized operation. | 4613 4614**示例：** 4615 4616```ts 4617const callback = () => { 4618 // ... 4619 return true; 4620} 4621try { 4622 windowClass.on('subWindowClose', callback); 4623} catch (exception) { 4624 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4625} 4626``` 4627 4628## off('subWindowClose')<sup>12+</sup> 4629 4630off(type: 'subWindowClose', callback?: Callback<void>): void 4631 4632关闭子窗口关闭事件的监听。 4633 4634**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4635 4636**系统能力：** SystemCapability.Window.SessionManager 4637 4638**参数：** 4639 4640| 参数名 | 类型 | 必填 | 说明 | 4641| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4642| type | string | 是 | 监听事件，固定为'subWindowClose'，即子窗口关闭事件。 | 4643| callback | Callback<void> | 否 | 回调函数。当点击子窗口右上角关闭按钮事件发生时的回调。该回调函数不返回任何参数。回调函数内部逻辑的返回值决定当前子窗是否继续关闭，如果返回boolean类型的true表示不关闭子窗，返回false或者其他非boolean类型表示关闭子窗。如果传入参数，则关闭该监听。如果未传入参数，则关闭所有子窗口关闭的监听。 | 4644 4645**错误码：** 4646 4647以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4648 4649| 错误码ID | 错误信息 | 4650| ------- | -------------------------------------------- | 4651| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4652| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4653| 1300002 | This window state is abnormal. | 4654| 1300004 | Unauthorized operation. | 4655 4656**示例：** 4657 4658```ts 4659const callback = () => { 4660 // ... 4661 return true; 4662} 4663try { 4664 windowClass.on('subWindowClose', callback); 4665 windowClass.off('subWindowClose', callback); 4666 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4667 windowClass.off('subWindowClose'); 4668} catch (exception) { 4669 console.error(`Failed to register or unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4670} 4671``` 4672 4673## on('windowWillClose')<sup>15+</sup> 4674 4675on(type: 'windowWillClose', callback: Callback<void, Promise<boolean>>): void 4676 4677该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于开启主窗口或子窗口关闭事件的监听。此监听仅能通过系统提供的窗口标题栏关闭按键触发，其余关闭窗口的方式不触发回调。 4678 4679该接口触发的回调函数是异步执行。子窗口的同步关闭事件监听参考[on('subWindowClose')](#onsubwindowclose12)方法。主窗口的同步关闭事件监听参考[on('windowStageClose')](arkts-apis-window-WindowStage.md#onwindowstageclose14)方法。 4680 4681**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 4682 4683**系统能力：** SystemCapability.Window.SessionManager 4684 4685**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 4686 4687**参数：** 4688 4689| 参数名 | 类型 | 必填 | 说明 | 4690| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4691| type | string | 是 | 监听事件，固定为'windowWillClose'，即窗口关闭事件。 | 4692| callback | Callback<void, Promise<boolean>> | 是 | 回调函数。当点击窗口系统提供的右上角关闭按钮事件发生时的回调。该回调函数不返回任何参数。回调函数内部逻辑需要有Promise<boolean>类型的返回值。在返回的Promise函数里，执行resolve(true) 方法表示不关闭当前窗口，执行resolve(false) 方法或者reject方法均表示关闭当前窗口。| 4693 4694**错误码：** 4695 4696以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4697 4698| 错误码ID | 错误信息 | 4699| ------- | -------------------------------------------- | 4700| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4701| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4702| 1300002 | This window state is abnormal. | 4703| 1300004 | Unauthorized operation. | 4704 4705**示例：** 4706 4707```ts 4708// EntryAbility.ets 4709import { UIAbility } from '@kit.AbilityKit'; 4710import { window } from '@kit.ArkUI'; 4711 4712export default class EntryAbility extends UIAbility { 4713 4714 onWindowStageCreate(windowStage: window.WindowStage) { 4715 console.info('onWindowStageCreate'); 4716 const callback = () => { 4717 // ... 4718 return new Promise<boolean>((resolve, reject) => { 4719 // 是否关闭该窗口 4720 let result: boolean = true; 4721 resolve(result); 4722 }); 4723 } 4724 try { 4725 let windowClass = windowStage.getMainWindowSync(); 4726 windowClass.on('windowWillClose', callback); 4727 } catch (exception) { 4728 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4729 } 4730 } 4731} 4732``` 4733 4734## off('windowWillClose')<sup>15+</sup> 4735 4736off(type: 'windowWillClose', callback?: Callback<void, Promise<boolean>>): void 4737 4738该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于关闭主窗口或子窗口关闭事件的监听。 4739 4740**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 4741 4742**系统能力：** SystemCapability.Window.SessionManager 4743 4744**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中不生效也不报错。 4745 4746**参数：** 4747 4748| 参数名 | 类型 | 必填 | 说明 | 4749| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4750| type | string | 是 | 监听事件，固定为'windowWillClose'，即窗口关闭事件。 | 4751| callback | Callback<void, Promise<boolean>> | 否 | 回调函数。当点击窗口系统提供的右上角关闭按钮事件发生时的回调。该回调函数不返回任何参数。回调函数内部逻辑需要有Promise<boolean>类型的返回值。在返回的Promise函数里，执行resolve(true) 方法表示不关闭当前窗口，执行resolve(false) 方法或者reject方法均表示关闭当前窗口。| 4752 4753**错误码：** 4754 4755以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4756 4757| 错误码ID | 错误信息 | 4758| ------- | -------------------------------------------- | 4759| 401 | Parameter error. Possible cause: 1. Incorrect parameter types; 2. Parameter verification failed. | 4760| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4761| 1300002 | This window state is abnormal. | 4762| 1300004 | Unauthorized operation. | 4763 4764**示例：** 4765 4766```ts 4767// EntryAbility.ets 4768import { UIAbility } from '@kit.AbilityKit'; 4769import { window } from '@kit.ArkUI'; 4770 4771export default class EntryAbility extends UIAbility { 4772 4773 onWindowStageCreate(windowStage: window.WindowStage) { 4774 console.info('onWindowStageCreate'); 4775 try { 4776 const callback = () => { 4777 // ... 4778 return new Promise<boolean>((resolve, reject) => { 4779 // 是否关闭该窗口 4780 let result: boolean = true; 4781 resolve(result); 4782 }); 4783 } 4784 let windowClass = windowStage.getMainWindowSync(); 4785 windowClass.on('windowWillClose', callback); 4786 windowClass.off('windowWillClose', callback); 4787 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4788 windowClass.off('windowWillClose'); 4789 } catch (exception) { 4790 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4791 } 4792 } 4793} 4794``` 4795 4796## on('windowHighlightChange')<sup>15+</sup> 4797 4798on(type: 'windowHighlightChange', callback: Callback<boolean>): void 4799 4800开启窗口激活态变化事件的监听。 4801 4802**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 4803 4804**系统能力：** SystemCapability.Window.SessionManager 4805 4806**参数：** 4807 4808| 参数名 | 类型 | 必填 | 说明 | 4809| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4810| type | string | 是 | 监听事件，固定为'windowHighlightChange'，即窗口激活态变化事件。 | 4811| callback | Callback<boolean> | 是 | 回调函数。当本窗口的激活态发生变化时的回调。回调函数返回boolean类型参数。当返回参数为true表示激活态；false表示非激活态。 | 4812 4813**错误码：** 4814 4815以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4816 4817| 错误码ID | 错误信息 | 4818| ------- | -------------------------------------------- | 4819| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4820| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4821| 1300002 | This window state is abnormal. | 4822| 1300003 | This window manager service works abnormally. | 4823 4824**示例：** 4825 4826```ts 4827try { 4828 windowClass.on('windowHighlightChange', (data: boolean) => { 4829 console.info(`Window highlight Change: ${data}`); 4830 }); 4831} catch (exception) { 4832 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4833} 4834``` 4835 4836## off('windowHighlightChange')<sup>15+</sup> 4837 4838off(type: 'windowHighlightChange', callback?: Callback<boolean>): void 4839 4840关闭窗口激活态变化事件的监听。 4841 4842**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 4843 4844**系统能力：** SystemCapability.Window.SessionManager 4845 4846**参数：** 4847 4848| 参数名 | 类型 | 必填 | 说明 | 4849| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4850| type | string | 是 | 监听事件，固定为'windowHighlightChange'，即窗口激活态变化事件。 | 4851| callback | Callback<boolean> | 否 | 回调函数。当本窗口的激活态发生变化时的回调。若传入参数，则关闭该监听。若未传入参数，则关闭所有窗口激活态变化的监听。 | 4852 4853**错误码：** 4854 4855以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4856 4857| 错误码ID | 错误信息 | 4858| ------- | -------------------------------------------- | 4859| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 4860| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4861| 1300002 | This window state is abnormal. | 4862| 1300003 | This window manager service works abnormally. | 4863 4864**示例：** 4865 4866```ts 4867const callback = (data: boolean) => { 4868 // ... 4869} 4870try { 4871 // 通过on接口开启监听 4872 windowClass.on('windowHighlightChange', callback); 4873 // 关闭指定callback的监听 4874 windowClass.off('windowHighlightChange', callback); 4875 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 4876 windowClass.off('windowHighlightChange'); 4877} catch (exception) { 4878 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4879} 4880``` 4881 4882## on('rotationChange')<sup>19+</sup> 4883 4884on(type: 'rotationChange', callback: RotationChangeCallback<RotationChangeInfo, RotationChangeResult | void>): void 4885 4886开启窗口旋转变化的监听。[RotationChangeInfo](arkts-apis-window-i.md#rotationchangeinfo19)中窗口旋转事件类型为窗口即将旋转时，必须返回[RotationChangeResult](arkts-apis-window-i.md#rotationchangeresult19)。窗口旋转事件类型为窗口旋转结束时返回[RotationChangeResult](arkts-apis-window-i.md#rotationchangeresult19)不生效。 4887 4888该函数只允许在主线程注册。同一个窗口多次注册同类型回调函数，只生效最新注册的同类型回调函数返回值。系统提供了超时保护机制，若20ms内窗口未返回[RotationChangeResult](arkts-apis-window-i.md#rotationchangeresult19)，系统不处理该返回值。 4889 4890<!--RP10-->此接口在2in1设备上调用不生效。<!--RP10End--> 4891 4892**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 4893 4894**系统能力：** SystemCapability.Window.SessionManager 4895 4896**参数：** 4897 4898| 参数名 | 类型 | 必填 | 说明 | 4899| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 4900| type | string | 是 | 监听事件，固定为'rotationChange'，即窗口旋转变化事件。 | 4901| callback | RotationChangeCallback<[RotationChangeInfo](arkts-apis-window-i.md#rotationchangeinfo19), [RotationChangeResult](arkts-apis-window-i.md#rotationchangeresult19) \| void> | 是 | 回调函数。返回窗口旋转信息[RotationChangeInfo](arkts-apis-window-i.md#rotationchangeinfo19)，应用返回当前窗口变化结果[RotationChangeResult](arkts-apis-window-i.md#rotationchangeresult19)。 | 4902 4903**错误码：** 4904 4905以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4906 4907| 错误码ID | 错误信息 | 4908| ------- | -------------------------------------------- | 4909| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4910| 1300002 | This window state is abnormal. | 4911| 1300003 | This window manager service works abnormally. | 4912 4913**示例：** 4914 4915```ts 4916function calculateRect(info: window.RotationChangeInfo): window.Rect { 4917 // calculate result with info 4918 let rect : window.Rect = { 4919 left: 0, 4920 top: 0, 4921 width: 500, 4922 height: 600, 4923 } 4924 return rect; 4925} 4926 4927const callback = (info: window.RotationChangeInfo): window.RotationChangeResult | void => { 4928 let result: window.RotationChangeResult = { 4929 rectType: window.RectType.RELATIVE_TO_SCREEN, 4930 windowRect: { 4931 left: 0, 4932 top: 0, 4933 width: 0, 4934 height: 0, 4935 } 4936 }; 4937 if (info.type === window.RotationChangeType.WINDOW_WILL_ROTATE) { 4938 result.rectType = window.RectType.RELATIVE_TO_SCREEN; 4939 result.windowRect = calculateRect(info); 4940 return result; 4941 } else { 4942 // do something after rotate 4943 return; 4944 } 4945} 4946 4947try { 4948 windowClass.on('rotationChange', callback); 4949} catch (exception) { 4950 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 4951} 4952``` 4953 4954## off('rotationChange')<sup>19+</sup> 4955 4956off(type: 'rotationChange', callback?: RotationChangeCallback<RotationChangeInfo, RotationChangeResult | void>): void 4957 4958关闭窗口旋转变化的监听。 4959 4960<!--RP10-->此接口在2in1设备上调用不生效。<!--RP10End--> 4961 4962**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 4963 4964**系统能力：** SystemCapability.Window.SessionManager 4965 4966**参数：** 4967 4968| 参数名 | 类型 | 必填 | 说明 | 4969| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 4970| type | string | 是 | 监听事件，固定为'rotationChange'，即窗口旋转变化事件。 | 4971| callback | RotationChangeCallback<[RotationChangeInfo](arkts-apis-window-i.md#rotationchangeinfo19), [RotationChangeResult](arkts-apis-window-i.md#rotationchangeresult19) \| void> | 否 | 回调函数。如果传入参数，则关闭该监听。如果未传入参数，则关闭该窗口的所有监听。 | 4972 4973**错误码：** 4974 4975以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 4976 4977| 错误码ID | 错误信息 | 4978| ------- | -------------------------------------------- | 4979| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 4980| 1300002 | This window state is abnormal. | 4981| 1300003 | This window manager service works abnormally. | 4982 4983**示例：** 4984 4985```ts 4986const callback = (info: window.RotationChangeInfo): window.RotationChangeResult | void => { 4987 // ... 4988 return; 4989} 4990try { 4991 windowClass.off('rotationChange', callback); 4992 // 如果通过on开启多个callback进行监听，同时关闭所有监听。 4993 windowClass.off('rotationChange'); 4994} catch (exception) { 4995 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 4996} 4997``` 4998 4999## on('uiExtensionSecureLimitChange')<sup>20+</sup> 5000 5001on(eventType: 'uiExtensionSecureLimitChange', callback: Callback<boolean>): void 5002 5003开启窗口内uiExtension安全限制变化事件的监听, 建议在窗口创建后立即监听。 5004 5005**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 5006 5007**系统能力：** SystemCapability.Window.SessionManager 5008 5009**参数：** 5010 5011| 参数名 | 类型 | 必填 | 说明 | 5012| -------- | ------------------------------ | ---- | -------------------------------------------------------- | 5013| eventType | string | 是 | 监听事件，固定为'uiExtensionSecureLimitChange'，即窗口内uiExtension安全限制变化事件。 | 5014| callback | Callback<boolean> | 是 | 回调函数。当窗口内uiExtension安全限制变化时触发回调。当返回参数为true表示窗口内uiExtension开启了隐藏不安全窗口；当返回参数为false表示窗口内uiExtension关闭了隐藏不安全窗口。若窗口内存在多个uiExtension，当返回参数为true表示窗口内至少一个uiExtension开启了隐藏不安全窗口；当返回参数为false表示窗口内所有uiExtension关闭了隐藏不安全窗口。 | 5015 5016**错误码：** 5017 5018以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5019 5020| 错误码ID | 错误信息 | 5021| ------- | -------------------------------------------- | 5022| 801 | Capability not supported.Function on('uiExtensionSecureLimitChange') can not work correctly due to limited device capabilities. | 5023| 1300002 | This window state is abnormal. | 5024| 1300003 | This window manager service works abnormally. | 5025 5026**示例：** 5027 5028```ts 5029try { 5030 windowClass.on('uiExtensionSecureLimitChange', (data: boolean) => { 5031 console.info(`Window secure limit Change: ${data}`); 5032 }); 5033} catch (exception) { 5034 console.error(`Failed to register callback. Cause code: ${exception.code}, message: ${exception.message}`); 5035} 5036``` 5037 5038## off('uiExtensionSecureLimitChange')<sup>20+</sup> 5039 5040off(eventType: 'uiExtensionSecureLimitChange', callback?: Callback<boolean>): void 5041 5042关闭窗口内uiextension安全限制变化事件的监听。 5043 5044**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 5045 5046**系统能力：** SystemCapability.Window.SessionManager 5047 5048**参数：** 5049 5050| 参数名 | 类型 | 必填 | 说明 | 5051| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | 5052| eventType | string | 是 | 监听事件，固定为'uiExtensionSecureLimitChange'，即窗口内uiExtension安全限制变化事件。 | 5053| callback | Callback<boolean> | 否 | 回调函数。若传入参数，则关闭该监听。若未传入参数，则关闭所有窗口安全限制变化的监听。 | 5054 5055**错误码：** 5056 5057以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5058 5059| 错误码ID | 错误信息 | 5060| ------- | -------------------------------------------- | 5061| 801 | Capability not supported.Function off('uiExtensionSecureLimitChange') can not work correctly due to limited device capabilities. | 5062| 1300002 | This window state is abnormal. | 5063| 1300003 | This window manager service works abnormally. | 5064 5065**示例：** 5066 5067```ts 5068const callback = (data: boolean) => { 5069 // ... 5070} 5071try { 5072 // 通过on接口开启监听 5073 windowClass.on('uiExtensionSecureLimitChange', callback); 5074 // 关闭指定callback的监听 5075 windowClass.off('uiExtensionSecureLimitChange', callback); 5076 // 如果通过on开启多个callback进行监听，同时关闭所有监听： 5077 windowClass.off('uiExtensionSecureLimitChange'); 5078} catch (exception) { 5079 console.error(`Failed to unregister callback. Cause code: ${exception.code}, message: ${exception.message}`); 5080} 5081``` 5082 5083## isWindowSupportWideGamut<sup>9+</sup> 5084 5085isWindowSupportWideGamut(callback: AsyncCallback<boolean>): void 5086 5087判断当前窗口是否支持广色域模式，使用callback异步回调。 5088 5089**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5090 5091**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5092 5093**参数：** 5094 5095| 参数名 | 类型 | 必填 | 说明 | 5096| -------- | ---------------------------- | -- | -------------------------------------------------------------------------------- | 5097| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前窗口支持广色域模式，返回false表示当前窗口不支持广色域模式。 | 5098 5099**错误码：** 5100 5101以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 5102 5103| 错误码ID | 错误信息 | 5104| ------- | ------------------------------ | 5105| 1300002 | This window state is abnormal. | 5106 5107**示例：** 5108 5109```ts 5110import { BusinessError } from '@kit.BasicServicesKit'; 5111 5112windowClass.isWindowSupportWideGamut((err: BusinessError, data) => { 5113 const errCode: number = err.code; 5114 if (errCode) { 5115 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 5116 return; 5117 } 5118 console.info(`Succeeded in checking whether the window support WideGamut Data: ${data}`); 5119}); 5120``` 5121 5122## isWindowSupportWideGamut<sup>9+</sup> 5123 5124isWindowSupportWideGamut(): Promise<boolean> 5125 5126判断当前窗口是否支持广色域模式，使用Promise异步回调。 5127 5128**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5129 5130**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5131 5132**返回值：** 5133 5134| 类型 | 说明 | 5135| ---------------------- | ------------------------------------------------------------------------------------ | 5136| Promise<boolean> | Promise对象。返回true表示当前窗口支持广色域模式，返回false表示当前窗口不支持广色域模式。 | 5137 5138**错误码：** 5139 5140以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 5141 5142| 错误码ID | 错误信息 | 5143| ------- | ------------------------------ | 5144| 1300002 | This window state is abnormal. | 5145 5146**示例：** 5147 5148```ts 5149import { BusinessError } from '@kit.BasicServicesKit'; 5150 5151let promise = windowClass.isWindowSupportWideGamut(); 5152promise.then((data) => { 5153 console.info(`Succeeded in checking whether the window support WideGamut. Data: ${data}`); 5154}).catch((err: BusinessError) => { 5155 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 5156}); 5157``` 5158 5159## setWindowColorSpace<sup>9+</sup> 5160 5161setWindowColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 5162 5163设置当前窗口为广色域模式或默认色域模式，使用callback异步回调。 5164 5165**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5166 5167**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5168 5169**参数：** 5170 5171| 参数名 | 类型 | 必填 | 说明 | 5172| ---------- | ------------------------- | -- | ----------- | 5173| colorSpace | [ColorSpace](arkts-apis-window-e.md#colorspace8) | 是 | 设置色域模式。 | 5174| callback | AsyncCallback<void> | 是 | 回调函数。 | 5175 5176**错误码：** 5177 5178以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5179 5180| 错误码ID | 错误信息 | 5181| ------- | ------------------------------ | 5182| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5183| 1300002 | This window state is abnormal. | 5184 5185**示例：** 5186 5187```ts 5188import { BusinessError } from '@kit.BasicServicesKit'; 5189 5190try { 5191 windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 5192 const errCode: number = err.code; 5193 if (errCode) { 5194 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 5195 return; 5196 } 5197 console.info('Succeeded in setting window colorspace.'); 5198 }); 5199} catch (exception) { 5200 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 5201} 5202``` 5203 5204## setWindowColorSpace<sup>9+</sup> 5205 5206setWindowColorSpace(colorSpace:ColorSpace): Promise<void> 5207 5208设置当前窗口为广色域模式或默认色域模式，使用Promise异步回调。 5209 5210**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5211 5212**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5213 5214**参数：** 5215 5216| 参数名 | 类型 | 必填 | 说明 | 5217| ---------- | ------------------------- | -- | ------------- | 5218| colorSpace | [ColorSpace](arkts-apis-window-e.md#colorspace8) | 是 | 设置色域模式。 | 5219 5220**返回值：** 5221 5222| 类型 | 说明 | 5223| ------------------- | ------------------------ | 5224| Promise<void> | 无返回结果的Promise对象。 | 5225 5226**错误码：** 5227 5228以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5229 5230| 错误码ID | 错误信息 | 5231| ------- | ------------------------------ | 5232| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 5233| 1300002 | This window state is abnormal. | 5234 5235**示例：** 5236 5237```ts 5238import { BusinessError } from '@kit.BasicServicesKit'; 5239 5240try { 5241 let promise = windowClass.setWindowColorSpace(window.ColorSpace.WIDE_GAMUT); 5242 promise.then(() => { 5243 console.info('Succeeded in setting window colorspace.'); 5244 }).catch((err: BusinessError) => { 5245 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 5246 }); 5247} catch (exception) { 5248 console.error(`Failed to set window colorspace. Cause code: ${exception.code}, message: ${exception.message}`); 5249} 5250``` 5251 5252## getWindowColorSpace<sup>9+</sup> 5253 5254getWindowColorSpace(): ColorSpace 5255 5256获取当前窗口色域模式。 5257 5258**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5259 5260**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5261 5262**返回值：** 5263 5264| 类型 | 说明 | 5265| ------------------------- | ------------- | 5266| [ColorSpace](arkts-apis-window-e.md#colorspace8) | 当前色域模式。 | 5267 5268**错误码：** 5269 5270以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 5271 5272| 错误码ID | 错误信息 | 5273| ------- | ------------------------------ | 5274| 1300002 | This window state is abnormal. | 5275 5276**示例：** 5277 5278```ts 5279import { BusinessError } from '@kit.BasicServicesKit'; 5280 5281try { 5282 let colorSpace = windowClass.getWindowColorSpace(); 5283 console.info(`Succeeded in getting the window color space. ColorSpace: ${colorSpace}`); 5284} catch (exception) { 5285 console.error(`Failed to get the window color space. Cause code: ${exception.code}, message: ${exception.message}`); 5286} 5287``` 5288 5289## setWindowBackgroundColor<sup>9+</sup> 5290 5291setWindowBackgroundColor(color: string | ColorMetrics): void 5292 5293设置窗口的背景色。Stage模型下，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 5294 5295**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5296 5297**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5298 5299**参数：** 5300 5301| 参数名 | 类型 | 必填 | 说明 | 5302| ----- | ------ | -- | ----------------------------------------------------------------------- | 5303| color | string \| [ColorMetrics](js-apis-arkui-graphics.md#colormetrics12)<sup>18+</sup> | 是 | 需要设置的背景色，为十六进制RGB或ARGB颜色，不区分大小写，例如`'#00FF00'`或`'#FF00FF00'`。<br>从API version 18开始，此参数支持ColorMetrics类型。| 5304 5305**错误码：** 5306 5307以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5308 5309| 错误码ID | 错误信息 | 5310| ------- | ------------------------------ | 5311| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5312| 1300002 | This window state is abnormal. | 5313 5314**示例：** 5315 5316```ts 5317import { BusinessError } from '@kit.BasicServicesKit'; 5318import { ColorMetrics } from '@kit.ArkUI'; 5319 5320let storage: LocalStorage = new LocalStorage(); 5321storage.setOrCreate('storageSimpleProp', 121); 5322windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 5323 let errCode: number = err.code; 5324 if (errCode) { 5325 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 5326 return; 5327 } 5328 console.info('Succeeded in loading the content.'); 5329 let color1: string = '#00ff33'; 5330 let color2: ColorMetrics = ColorMetrics.numeric(0xff112233); 5331 try { 5332 windowClass?.setWindowBackgroundColor(color1); 5333 windowClass?.setWindowBackgroundColor(color2); 5334 } catch (exception) { 5335 console.error(`Failed to set the background color. Cause code: ${exception.code}, message: ${exception.message}`); 5336 }; 5337}); 5338``` 5339 5340## setWindowShadowEnabled<sup>20+</sup> 5341 5342setWindowShadowEnabled(enable: boolean): Promise<void> 5343 5344设置主窗口是否显示阴影，使用Promise异步回调。未调用该接口时，主窗口默认显示阴影。 5345 5346**系统能力：** SystemCapability.Window.SessionManager 5347 5348**设备行为差异：** 该接口在2in1设备中可正常调用，在其他设备中返回801错误码。 5349 5350**需要权限：** ohos.permission.SET_WINDOW_TRANSPARENT 5351 5352**参数：** 5353 5354| 参数名 | 类型 | 必填 | 说明 | 5355| ----- | ------ | -- | ----------------------------------------------------------------------- | 5356| enable | boolean | 是 | 设置主窗口是否显示阴影。true表示显示阴影，false表示不显示阴影。 | 5357 5358**返回值：** 5359 5360| 类型 | 说明 | 5361| ------------------- | ------------------------ | 5362| Promise<void> | 无返回结果的Promise对象。 | 5363 5364**错误码：** 5365 5366以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5367 5368| 错误码ID | 错误信息 | 5369| ------- | ------------------------------ | 5370| 201 | Permission verification failed. The application does not have the permission required to call the API. | 5371| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 5372| 1300002 | This window state is abnormal. | 5373| 1300003 | This window manager service works abnormally. | 5374| 1300004 | Unauthorized operation. | 5375 5376**示例：** 5377 5378```ts 5379// EntryAbility.ets 5380import { UIAbility } from '@kit.AbilityKit'; 5381import { BusinessError } from '@kit.BasicServicesKit'; 5382 5383export default class EntryAbility extends UIAbility { 5384 onWindowStageCreate(windowStage: window.WindowStage) { 5385 windowStage.loadContent("pages/page2", (err: BusinessError) => { 5386 let errCode: number = err.code; 5387 if (errCode) { 5388 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 5389 return; 5390 } 5391 console.info('Succeeded in loading the content.'); 5392 // 获取应用主窗口。 5393 let windowClass: window.Window | undefined = undefined; 5394 windowStage.getMainWindow((err: BusinessError, data) => { 5395 let errCode: number = err.code; 5396 if (errCode) { 5397 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5398 return; 5399 } 5400 windowClass = data; 5401 let enable = true; 5402 let promise = windowClass.setWindowShadowEnabled(enable); 5403 promise.then(() => { 5404 console.info('Succeeded in setting window shadow.'); 5405 }).catch((err: BusinessError) => { 5406 console.error(`Failed to set the window shadow. Cause code: ${err.code}, message: ${err.message}`); 5407 }); 5408 }); 5409 }); 5410 } 5411} 5412``` 5413 5414## setWindowBrightness<sup>9+</sup> 5415 5416setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void 5417 5418允许应用主窗口设置当前窗口亮度值，使用callback异步回调。 5419 5420当窗口退至后台的过程中，不建议同时调用此接口，否则会有时序问题。 5421 5422> **说明：** 5423>- 针对非2in1设备，窗口设置当前窗口亮度生效时，控制中心不可以调整系统屏幕亮度。当接口入参为-1或当前窗口退至后台时，窗口亮度恢复为系统屏幕亮度，控制中心可以调整系统屏幕亮度。 5424>- 针对2in1设备，在API version 14之前，窗口设置屏幕亮度生效时，控制中心和快捷键不可以调整系统屏幕亮度。当接口入参为-1或当前窗口退至后台时，窗口亮度恢复为系统屏幕亮度，控制中心和快捷键可以调整系统屏幕亮度。从API version 14开始，窗口亮度与系统屏幕亮度保持一致，可以通过本接口、控制中心或者快捷键设置系统屏幕亮度。 5425 5426**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5427 5428**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5429 5430**参数：** 5431 5432| 参数名 | 类型 | 必填 | 说明 | 5433| ---------- | ------------------------- | -- |-------------------------------------------| 5434| brightness | number | 是 | 屏幕亮度值。该参数为浮点数，取值范围为[0.0, 1.0]或-1.0。1.0表示最亮，-1.0表示恢复成设置窗口亮度前的系统控制中心亮度。 | 5435| callback | AsyncCallback<void> | 是 | 回调函数。 | 5436 5437**错误码：** 5438 5439以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5440 5441| 错误码ID | 错误信息 | 5442| ------- | -------------------------------------------- | 5443| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5444| 1300002 | This window state is abnormal. | 5445| 1300003 | This window manager service works abnormally. | 5446 5447**示例：** 5448 5449```ts 5450// EntryAbility.ets 5451import { UIAbility } from '@kit.AbilityKit'; 5452import { BusinessError } from '@kit.BasicServicesKit'; 5453 5454export default class EntryAbility extends UIAbility { 5455 // ... 5456 onWindowStageCreate(windowStage: window.WindowStage): void { 5457 console.info('onWindowStageCreate'); 5458 let windowClass: window.Window | undefined = undefined; 5459 windowStage.getMainWindow((err: BusinessError, data) => { 5460 const errCode: number = err.code; 5461 if (errCode) { 5462 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5463 return; 5464 } 5465 windowClass = data; 5466 let brightness: number = 1.0; 5467 try { 5468 windowClass.setWindowBrightness(brightness, (err: BusinessError) => { 5469 const errCode: number = err.code; 5470 if (errCode) { 5471 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 5472 return; 5473 } 5474 console.info('Succeeded in setting the brightness.'); 5475 }); 5476 } catch (exception) { 5477 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 5478 } 5479 }); 5480 } 5481} 5482``` 5483 5484## setWindowBrightness<sup>9+</sup> 5485 5486setWindowBrightness(brightness: number): Promise<void> 5487 5488允许应用主窗口设置当前窗口亮度值，使用Promise异步回调。 5489 5490当窗口退至后台的过程中，不建议同时调用此接口，否则会有时序问题。 5491 5492> **说明：** 5493>- 针对非2in1设备，窗口设置当前窗口亮度生效时，控制中心不可以调整系统屏幕亮度。当接口入参为-1或当前窗口退至后台时，窗口亮度恢复为系统屏幕亮度，控制中心可以调整系统屏幕亮度。 5494>- 针对2in1设备，在API version 14之前，窗口设置屏幕亮度生效时，控制中心和快捷键不可以调整系统屏幕亮度。当接口入参为-1或当前窗口退至后台时，窗口亮度恢复为系统屏幕亮度，控制中心和快捷键可以调整系统屏幕亮度。从API version 14开始，窗口亮度与系统屏幕亮度保持一致，可以通过本接口、控制中心或者快捷键设置系统屏幕亮度。 5495 5496**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5497 5498**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5499 5500**参数：** 5501 5502| 参数名 | 类型 | 必填 | 说明 | 5503| ---------- | ------ | -- |----------------------------------------| 5504| brightness | number | 是 | 屏幕亮度值。该参数为浮点数，取值范围为[0.0, 1.0]或-1.0。1.0表示最亮，-1.0表示恢复成设置窗口亮度前的系统控制中心亮度。 | 5505 5506**返回值：** 5507 5508| 类型 | 说明 | 5509| ------------------- | ------------------------ | 5510| Promise<void> | 无返回结果的Promise对象。 | 5511 5512**错误码：** 5513 5514以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5515 5516| 错误码ID | 错误信息 | 5517| ------- | -------------------------------------------- | 5518| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5519| 1300002 | This window state is abnormal. | 5520| 1300003 | This window manager service works abnormally. | 5521 5522**示例：** 5523 5524```ts 5525// EntryAbility.ets 5526import { UIAbility } from '@kit.AbilityKit'; 5527import { BusinessError } from '@kit.BasicServicesKit'; 5528 5529export default class EntryAbility extends UIAbility { 5530 // ... 5531 onWindowStageCreate(windowStage: window.WindowStage): void { 5532 console.info('onWindowStageCreate'); 5533 let windowClass: window.Window | undefined = undefined; 5534 windowStage.getMainWindow((err: BusinessError, data) => { 5535 const errCode: number = err.code; 5536 if (errCode) { 5537 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 5538 return; 5539 } 5540 windowClass = data; 5541 let brightness: number = 1.0; 5542 try { 5543 let promise = windowClass.setWindowBrightness(brightness); 5544 promise.then(() => { 5545 console.info('Succeeded in setting the brightness.'); 5546 }).catch((err: BusinessError) => { 5547 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 5548 }); 5549 } catch (exception) { 5550 console.error(`Failed to set the brightness. Cause code: ${exception.code}, message: ${exception.message}`); 5551 } 5552 }); 5553 } 5554} 5555``` 5556 5557## setWindowFocusable<sup>9+</sup> 5558 5559setWindowFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 5560 5561设置窗口是否具有获得焦点的能力，使用callback异步回调。 5562 5563**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5564 5565**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5566 5567**参数：** 5568 5569| 参数名 | 类型 | 必填 | 说明 | 5570| ----------- | ------------------------- | -- | ------------------------------------------------------- | 5571| isFocusable | boolean | 是 | 窗口是否可获焦。true表示支持；false表示不支持。 | 5572| callback | AsyncCallback<void> | 是 | 回调函数。 | 5573 5574**错误码：** 5575 5576以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5577 5578| 错误码ID | 错误信息 | 5579| ------- | -------------------------------------------- | 5580| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5581| 1300002 | This window state is abnormal. | 5582| 1300003 | This window manager service works abnormally. | 5583 5584**示例：** 5585 5586```ts 5587import { BusinessError } from '@kit.BasicServicesKit'; 5588 5589let isFocusable: boolean = true; 5590try { 5591 windowClass.setWindowFocusable(isFocusable, (err: BusinessError) => { 5592 const errCode: number = err.code; 5593 if (errCode) { 5594 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 5595 return; 5596 } 5597 console.info('Succeeded in setting the window to be focusable.'); 5598 }); 5599} catch (exception) { 5600 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 5601} 5602``` 5603 5604## setWindowFocusable<sup>9+</sup> 5605 5606setWindowFocusable(isFocusable: boolean): Promise<void> 5607 5608设置窗口是否具有获得焦点的能力，使用Promise异步回调。 5609 5610**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5611 5612**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5613 5614**参数：** 5615 5616| 参数名 | 类型 | 必填 | 说明 | 5617| ----------- | ------- | -- | -------------------------------------------------------- | 5618| isFocusable | boolean | 是 | 窗口是否可获焦。true表示支持；false表示不支持。 | 5619 5620**返回值：** 5621 5622| 类型 | 说明 | 5623| ------------------- | ------------------------ | 5624| Promise<void> | 无返回结果的Promise对象。 | 5625 5626**错误码：** 5627 5628以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5629 5630| 错误码ID | 错误信息 | 5631| ------- | -------------------------------------------- | 5632| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5633| 1300002 | This window state is abnormal. | 5634| 1300003 | This window manager service works abnormally. | 5635 5636**示例：** 5637 5638```ts 5639import { BusinessError } from '@kit.BasicServicesKit'; 5640 5641let isFocusable: boolean = true; 5642try { 5643 let promise = windowClass.setWindowFocusable(isFocusable); 5644 promise.then(() => { 5645 console.info('Succeeded in setting the window to be focusable.'); 5646 }).catch((err: BusinessError) => { 5647 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 5648 }); 5649} catch (exception) { 5650 console.error(`Failed to set the window to be focusable. Cause code: ${exception.code}, message: ${exception.message}`); 5651} 5652``` 5653 5654## setWindowKeepScreenOn<sup>9+</sup> 5655 5656setWindowKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 5657 5658设置屏幕是否为常亮状态，使用callback异步回调。 5659 5660规范使用该接口：仅在必要场景（导航、视频播放、绘画、游戏等场景）下，设置该属性为true；退出上述场景后，应当重置该属性为false；其他场景（无屏幕互动、音频播放等）下，不使用该接口；系统检测到非规范使用该接口时，可能会恢复自动灭屏功能。 5661 5662**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5663 5664**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5665 5666**参数：** 5667 5668| 参数名 | 类型 | 必填 | 说明 | 5669| -------------- | ------------------------- | -- | ---------------------------------------------------- | 5670| isKeepScreenOn | boolean | 是 | 设置屏幕是否为常亮状态。true表示常亮；false表示不常亮。 | 5671| callback | AsyncCallback<void> | 是 | 回调函数。 | 5672 5673**错误码：** 5674 5675以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5676 5677| 错误码ID | 错误信息 | 5678| ------- | -------------------------------------------- | 5679| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5680| 1300002 | This window state is abnormal. | 5681| 1300003 | This window manager service works abnormally. | 5682 5683**示例：** 5684 5685```ts 5686import { BusinessError } from '@kit.BasicServicesKit'; 5687 5688let isKeepScreenOn: boolean = true; 5689try { 5690 windowClass.setWindowKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 5691 const errCode: number = err.code; 5692 if (errCode) { 5693 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 5694 return; 5695 } 5696 console.info('Succeeded in setting the screen to be always on.'); 5697 }); 5698} catch (exception) { 5699 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 5700} 5701``` 5702 5703## setWindowKeepScreenOn<sup>9+</sup> 5704 5705setWindowKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 5706 5707设置屏幕是否为常亮状态，使用Promise异步回调。 5708 5709规范使用该接口：仅在必要场景（导航、视频播放、绘画、游戏等场景）下，设置该属性为true；退出上述场景后，应当重置该属性为false；其他场景（无屏幕互动、音频播放等）下，不使用该接口；系统检测到非规范使用该接口时，可能会恢复自动灭屏功能。 5710 5711**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5712 5713**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5714 5715**参数：** 5716 5717| 参数名 | 类型 | 必填 | 说明 | 5718| -------------- | ------- | -- | --------------------------------------------------- | 5719| isKeepScreenOn | boolean | 是 | 设置屏幕是否为常亮状态。true表示常亮；false表示不常亮。 | 5720 5721**返回值：** 5722 5723| 类型 | 说明 | 5724| ------------------- | ------------------------ | 5725| Promise<void> | 无返回结果的Promise对象。 | 5726 5727**错误码：** 5728 5729以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5730 5731| 错误码ID | 错误信息 | 5732| ------- | -------------------------------------------- | 5733| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5734| 1300002 | This window state is abnormal. | 5735| 1300003 | This window manager service works abnormally. | 5736 5737**示例：** 5738 5739```ts 5740import { BusinessError } from '@kit.BasicServicesKit'; 5741 5742let isKeepScreenOn: boolean = true; 5743try { 5744 let promise = windowClass.setWindowKeepScreenOn(isKeepScreenOn); 5745 promise.then(() => { 5746 console.info('Succeeded in setting the screen to be always on.'); 5747 }).catch((err: BusinessError) => { 5748 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 5749 }); 5750} catch (exception) { 5751 console.error(`Failed to set the screen to be always on. Cause code: ${exception.code}, message: ${exception.message}`); 5752} 5753``` 5754 5755## setWindowPrivacyMode<sup>9+</sup> 5756 5757setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 5758 5759设置窗口是否为隐私模式，使用callback异步回调。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。 5760 5761**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5762 5763**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5764 5765**需要权限：** ohos.permission.PRIVACY_WINDOW 5766 5767**参数：** 5768 5769| 参数名 | 类型 | 必填 | 说明 | 5770| ------------- | ------------------------- | -- | ------------------------------------------------------ | 5771| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 5772| callback | AsyncCallback<void> | 是 | 回调函数。 | 5773 5774**错误码：** 5775 5776以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5777 5778| 错误码ID | 错误信息 | 5779| ------- | ------------------------------ | 5780| 201 | Permission verification failed. The application does not have the permission required to call the API. | 5781| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5782| 1300002 | This window state is abnormal. | 5783 5784**示例：** 5785 5786```ts 5787import { BusinessError } from '@kit.BasicServicesKit'; 5788 5789let isPrivacyMode: boolean = true; 5790try { 5791 windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => { 5792 const errCode: number = err.code; 5793 if (errCode) { 5794 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 5795 return; 5796 } 5797 console.info('Succeeded in setting the window to privacy mode.'); 5798 }); 5799} catch (exception) { 5800 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 5801} 5802``` 5803 5804## setWindowPrivacyMode<sup>9+</sup> 5805 5806setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 5807 5808设置窗口是否为隐私模式，使用Promise异步回调。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。 5809 5810**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5811 5812**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5813 5814**需要权限：** ohos.permission.PRIVACY_WINDOW 5815 5816**参数：** 5817 5818| 参数名 | 类型 | 必填 | 说明 | 5819| ------------- | ------- | -- | ----------------------------------------------------- | 5820| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 5821 5822**返回值：** 5823 5824| 类型 | 说明 | 5825| ------------------- | ------------------------ | 5826| Promise<void> | 无返回结果的Promise对象。 | 5827 5828**错误码：** 5829 5830以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5831 5832| 错误码ID | 错误信息 | 5833| ------- | ------------------------------ | 5834| 201 | Permission verification failed. The application does not have the permission required to call the API. | 5835| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5836| 1300002 | This window state is abnormal. | 5837 5838**示例：** 5839 5840```ts 5841import { BusinessError } from '@kit.BasicServicesKit'; 5842 5843let isPrivacyMode: boolean = true; 5844try { 5845 let promise = windowClass.setWindowPrivacyMode(isPrivacyMode); 5846 promise.then(() => { 5847 console.info('Succeeded in setting the window to privacy mode.'); 5848 }).catch((err: BusinessError) => { 5849 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 5850 }); 5851} catch (exception) { 5852 console.error(`Failed to set the window to privacy mode. Cause code: ${exception.code}, message: ${exception.message}`); 5853} 5854``` 5855 5856## setWindowTouchable<sup>9+</sup> 5857 5858setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 5859 5860设置窗口是否为可触状态，使用callback异步回调。 5861 5862**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5863 5864**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5865 5866**参数：** 5867 5868| 参数名 | 类型 | 必填 | 说明 | 5869| ----------- | ------------------------- | -- | ----------------------------------------------- | 5870| isTouchable | boolean | 是 | 窗口是否为可触状态。true表示可触；false表示不可触。 | 5871| callback | AsyncCallback<void> | 是 | 回调函数。 | 5872 5873**错误码：** 5874 5875以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5876 5877| 错误码ID | 错误信息 | 5878| ------- | -------------------------------------------- | 5879| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5880| 1300002 | This window state is abnormal. | 5881| 1300003 | This window manager service works abnormally. | 5882 5883**示例：** 5884 5885```ts 5886import { BusinessError } from '@kit.BasicServicesKit'; 5887 5888let isTouchable = true; 5889try { 5890 windowClass.setWindowTouchable(isTouchable, (err: BusinessError) => { 5891 const errCode: number = err.code; 5892 if (errCode) { 5893 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 5894 return; 5895 } 5896 console.info('Succeeded in setting the window to be touchable.'); 5897 }); 5898} catch (exception) { 5899 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 5900} 5901``` 5902 5903## setWindowTouchable<sup>9+</sup> 5904 5905setWindowTouchable(isTouchable: boolean): Promise<void> 5906 5907设置窗口是否为可触状态，使用Promise异步回调。 5908 5909**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5910 5911**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5912 5913**参数：** 5914 5915| 参数名 | 类型 | 必填 | 说明 | 5916| ----------- | ------- | -- | ----------------------------------------------- | 5917| isTouchable | boolean | 是 | 窗口是否为可触状态。true表示可触；false表示不可触。 | 5918 5919**返回值：** 5920 5921| 类型 | 说明 | 5922| ------------------- | ------------------------- | 5923| Promise<void> | 无返回结果的Promise对象。 | 5924 5925**错误码：** 5926 5927以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 5928 5929| 错误码ID | 错误信息 | 5930| ------- | -------------------------------------------- | 5931| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 5932| 1300002 | This window state is abnormal. | 5933| 1300003 | This window manager service works abnormally. | 5934 5935**示例：** 5936 5937```ts 5938import { BusinessError } from '@kit.BasicServicesKit'; 5939 5940let isTouchable: boolean = true; 5941try { 5942 let promise = windowClass.setWindowTouchable(isTouchable); 5943 promise.then(() => { 5944 console.info('Succeeded in setting the window to be touchable.'); 5945 }).catch((err: BusinessError) => { 5946 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 5947 }); 5948} catch (exception) { 5949 console.error(`Failed to set the window to be touchable. Cause code: ${exception.code}, message: ${exception.message}`); 5950} 5951``` 5952 5953## snapshot<sup>9+</sup> 5954 5955snapshot(callback: AsyncCallback<image.PixelMap>): void 5956 5957获取窗口截图，使用callback异步回调。若当前窗口设置为隐私模式（可通过[setWindowPrivacyMode](#setwindowprivacymode9)接口设置），截图结果为白屏。 5958 5959**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 5960 5961**系统能力：** SystemCapability.WindowManager.WindowManager.Core 5962 5963**参数：** 5964 5965| 参数名 | 类型 | 必填 | 说明 | 5966| ----------- | ------------------------- | ---- | -------------------- | 5967| callback | AsyncCallback<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | 回调函数。 | 5968 5969**错误码：** 5970 5971以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 5972 5973| 错误码ID | 错误信息 | 5974| ------- | ------------------------------ | 5975| 1300002 | This window state is abnormal. | 5976 5977**示例：** 5978 5979```ts 5980import { BusinessError } from '@kit.BasicServicesKit'; 5981import { image } from '@kit.ImageKit'; 5982 5983windowClass.snapshot((err: BusinessError, pixelMap: image.PixelMap) => { 5984 const errCode: number = err.code; 5985 if (errCode) { 5986 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 5987 return; 5988 } 5989 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 5990 pixelMap.release(); // PixelMap使用完后及时释放内存 5991}); 5992``` 5993 5994## snapshot<sup>9+</sup> 5995 5996snapshot(): Promise<image.PixelMap> 5997 5998获取当前窗口截图。若当前窗口设置为隐私模式（可通过[setWindowPrivacyMode](#setwindowprivacymode9)接口设置），截图结果为白屏。 5999 6000**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6001 6002**系统能力：** SystemCapability.WindowManager.WindowManager.Core 6003 6004**返回值：** 6005 6006| 类型 | 说明 | 6007| ------------------- | ------------------------- | 6008| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象。返回当前窗口截图。 | 6009 6010**错误码：** 6011 6012以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 6013 6014| 错误码ID | 错误信息 | 6015| ------- | ------------------------------ | 6016| 1300002 | This window state is abnormal. | 6017 6018**示例：** 6019 6020```ts 6021import { BusinessError } from '@kit.BasicServicesKit'; 6022import { image } from '@kit.ImageKit'; 6023 6024let promise = windowClass.snapshot(); 6025promise.then((pixelMap: image.PixelMap) => { 6026 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 6027 pixelMap.release(); // PixelMap使用完后及时释放内存 6028}).catch((err: BusinessError) => { 6029 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 6030}); 6031``` 6032 6033## snapshotSync<sup>20+</sup> 6034 6035snapshotSync(): image.PixelMap 6036 6037获取当前窗口截图，此接口为同步接口。若当前窗口设置为隐私模式（[setWindowPrivacyMode](#setwindowprivacymode9)接口设置），截图结果为白屏。 6038 6039Stage模型下，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 6040 6041**系统能力：** SystemCapability.Window.SessionManager 6042 6043**返回值：** 6044 6045| 类型 | 说明 | 6046| ------------------- | ------------------------- | 6047| [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | 返回当前窗口截图。 | 6048 6049**错误码：** 6050 6051以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6052 6053| 错误码ID | 错误信息 | 6054| ------- | ------------------------------ | 6055| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6056| 1300002 | This window state is abnormal. | 6057| 1300018 | Timeout. | 6058 6059**示例：** 6060 6061```ts 6062import { BusinessError } from '@kit.BasicServicesKit'; 6063import { image } from '@kit.ImageKit'; 6064 6065try { 6066 let pixelMap = windowClass.snapshotSync(); 6067 console.info(`Succeeded in snapshotting window`); 6068 pixelMap.release(); // PixelMap使用完后及时释放内存 6069} catch (exception) { 6070 console.error(`Failed to snapshot window. Cause code: ${exception.code}, message: ${exception.message}`); 6071} 6072``` 6073 6074## snapshotIgnorePrivacy<sup>18+</sup> 6075 6076snapshotIgnorePrivacy(): Promise<image.PixelMap> 6077 6078获取当前窗口截图。即使当前窗口设置为隐私模式（可通过[setWindowPrivacyMode](#setwindowprivacymode9)接口设置），仍可调用本接口返回当前窗口截图。 6079 6080**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 6081 6082**系统能力：** SystemCapability.Window.SessionManager 6083 6084**返回值：** 6085 6086| 类型 | 说明 | 6087| ------------------- | ------------------------- | 6088| Promise<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象。返回当前窗口截图。 | 6089 6090**错误码：** 6091 6092以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6093 6094| 错误码ID | 错误信息 | 6095| ------- | ------------------------------ | 6096| 801 | Capability not supported. Function snapshotIgnorePrivacy can not work correctly due to limited device capabilities. | 6097| 1300002 | This window state is abnormal. | 6098 6099**示例：** 6100 6101```ts 6102import { BusinessError } from '@kit.BasicServicesKit'; 6103import { image } from '@kit.ImageKit'; 6104 6105let promise = windowClass.snapshotIgnorePrivacy(); 6106promise.then((pixelMap: image.PixelMap) => { 6107 console.info('Succeeded in snapshotting window. Pixel bytes number: ' + pixelMap.getPixelBytesNumber()); 6108 pixelMap.release(); // PixelMap使用完后及时释放内存 6109}).catch((err: BusinessError) => { 6110 console.error(`Failed to snapshot window. Cause code: ${err.code}, message: ${err.message}`); 6111}); 6112``` 6113 6114## setAspectRatio<sup>10+</sup> 6115 6116setAspectRatio(ratio: number): Promise<void> 6117 6118设置窗口内容布局的比例，使用Promise异步回调。 6119 6120通过其他接口如[resize](#resize9)、[resizeAsync](#resizeasync12)设置窗口大小时，不受ratio约束。 6121 6122仅主窗可设置，且仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING）下生效，比例参数将持久化保存，关闭应用或重启设备设置的比例仍然生效。 6123 6124**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6125 6126**系统能力：** SystemCapability.WindowManager.WindowManager.Core 6127 6128**参数：** 6129 6130| 参数名 | 类型 | 必填 | 说明 | 6131| ------------------ | ------- | ---- |-------------------------------------------| 6132| ratio | number | 是 | 除边框装饰之外的窗口内容布局的宽高比。该参数为浮点数，受窗口最大最小尺寸限制，比例值下限为最小宽度/最大高度，上限为最大宽度/最小高度。窗口最大最小尺寸由[WindowLimits](arkts-apis-window-i.md#windowlimits11)和系统限制的交集决定，系统限制优先级高于[WindowLimits](arkts-apis-window-i.md#windowlimits11)。ratio的有效范围会随[WindowLimits](arkts-apis-window-i.md#windowlimits11)变化而变化。如果先设置了[WindowLimits](arkts-apis-window-i.md#windowlimits11)，后设置的ratio与其冲突，会返回错误码；如果先设置了ratio，后设置的[WindowLimits](arkts-apis-window-i.md#windowlimits11)与其冲突，窗口的宽高比可能会不跟随设置的宽高比（ratio）。 | 6133 6134**返回值：** 6135 6136| 类型 | 说明 | 6137| ------------------- | ------------------------- | 6138| Promise<void> | 无返回结果的Promise对象。 | 6139 6140**错误码：** 6141 6142以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6143 6144| 错误码ID | 错误信息 | 6145| ------- | -------------------------------------------- | 6146| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6147| 1300002 | This window state is abnormal. | 6148| 1300004 | Unauthorized operation. | 6149 6150**示例：** 6151<!--code_no_check--> 6152```ts 6153// EntryAbility.ets 6154import { UIAbility } from '@kit.AbilityKit'; 6155import { BusinessError } from '@kit.BasicServicesKit'; 6156 6157export default class EntryAbility extends UIAbility { 6158 6159 // ... 6160 onWindowStageCreate(windowStage: window.WindowStage) { 6161 console.info('onWindowStageCreate'); 6162 let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口 6163 if (!windowClass) { 6164 console.info('windowClass is null'); 6165 } 6166 try { 6167 let ratio = 1.0; 6168 let promise = windowClass.setAspectRatio(ratio); 6169 promise.then(() => { 6170 console.info('Succeeded in setting aspect ratio of window.'); 6171 }).catch((err: BusinessError) => { 6172 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 6173 }); 6174 } catch (exception) { 6175 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 6176 } 6177 } 6178} 6179``` 6180 6181## setAspectRatio<sup>10+</sup> 6182 6183setAspectRatio(ratio: number, callback: AsyncCallback<void>): void 6184 6185设置窗口内容布局的比例，使用callback异步回调。 6186 6187通过其他接口如[resize](#resize9)、[resizeAsync](#resizeasync12)设置窗口大小时，不受ratio约束。 6188 6189仅主窗可设置，且仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING）下生效，比例参数将持久化保存，关闭应用或重启设备设置的比例仍然生效。 6190 6191**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6192 6193**系统能力：** SystemCapability.WindowManager.WindowManager.Core 6194 6195**参数：** 6196 6197| 参数名 | 类型 | 必填 | 说明 | 6198| ------------------ | ------- | ---- |--------------------------------------------| 6199| ratio | number | 是 | 除边框装饰之外的窗口内容布局的宽高比。该参数为浮点数，受窗口最大最小尺寸限制，比例值下限为最小宽度/最大高度，上限为最大宽度/最小高度。窗口最大最小尺寸由[WindowLimits](arkts-apis-window-i.md#windowlimits11)和系统限制的交集决定，系统限制优先级高于[WindowLimits](arkts-apis-window-i.md#windowlimits11)。ratio的有效范围会随[WindowLimits](arkts-apis-window-i.md#windowlimits11)变化而变化。如果先设置了[WindowLimits](arkts-apis-window-i.md#windowlimits11)，后设置的ratio与其冲突，会返回错误码；如果先设置了ratio，后设置的[WindowLimits](arkts-apis-window-i.md#windowlimits11)与其冲突，窗口的宽高比可能会不跟随设置的宽高比（ratio）。 | 6200| callback | AsyncCallback<void> | 是 | 回调函数。 | 6201 6202**错误码：** 6203 6204以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6205 6206| 错误码ID | 错误信息 | 6207| ------- | -------------------------------------------- | 6208| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6209| 1300002 | This window state is abnormal. | 6210| 1300004 | Unauthorized operation. | 6211 6212**示例：** 6213<!--code_no_check--> 6214```ts 6215// EntryAbility.ets 6216import { UIAbility } from '@kit.AbilityKit'; 6217import { BusinessError } from '@kit.BasicServicesKit'; 6218 6219export default class EntryAbility extends UIAbility { 6220 6221 // ... 6222 onWindowStageCreate(windowStage: window.WindowStage) { 6223 console.info('onWindowStageCreate'); 6224 let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口 6225 if (!windowClass) { 6226 console.info('Failed to load the content. Cause: windowClass is null'); 6227 } 6228 try { 6229 let ratio = 1.0; 6230 windowClass.setAspectRatio(ratio, (err: BusinessError) => { 6231 const errCode: number = err.code; 6232 if (errCode) { 6233 console.error(`Failed to set the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 6234 return; 6235 } 6236 console.info('Succeeded in setting the aspect ratio of window.'); 6237 }); 6238 } catch (exception) { 6239 console.error(`Failed to set the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 6240 } 6241 } 6242} 6243 6244``` 6245 6246## resetAspectRatio<sup>10+</sup> 6247 6248resetAspectRatio(): Promise<void> 6249 6250取消设置窗口内容布局的比例，使用Promise异步回调。 6251 6252仅主窗可设置，且仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING）下生效，调用后将清除持久化储存的比例信息。 6253 6254**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6255 6256**系统能力：** SystemCapability.WindowManager.WindowManager.Core 6257 6258**返回值：** 6259 6260| 类型 | 说明 | 6261| ------------------- | ------------------------- | 6262| Promise<void> | 无返回结果的Promise对象。 | 6263 6264**错误码：** 6265 6266以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 6267 6268| 错误码ID | 错误信息 | 6269| ------- | -------------------------------------------- | 6270| 1300002 | This window state is abnormal. | 6271| 1300004 | Unauthorized operation. | 6272 6273**示例：** 6274<!--code_no_check--> 6275```ts 6276// EntryAbility.ets 6277import { UIAbility } from '@kit.AbilityKit'; 6278import { BusinessError } from '@kit.BasicServicesKit'; 6279 6280export default class EntryAbility extends UIAbility { 6281 6282 // ... 6283 onWindowStageCreate(windowStage: window.WindowStage) { 6284 console.info('onWindowStageCreate'); 6285 let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口 6286 if (!windowClass) { 6287 console.info('Failed to load the content. Cause: windowClass is null'); 6288 } 6289 try { 6290 let promise = windowClass.resetAspectRatio(); 6291 promise.then(() => { 6292 console.info('Succeeded in resetting aspect ratio of window.'); 6293 }).catch((err: BusinessError) => { 6294 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 6295 }); 6296 } catch (exception) { 6297 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 6298 } 6299 } 6300} 6301``` 6302 6303## resetAspectRatio<sup>10+</sup> 6304 6305resetAspectRatio(callback: AsyncCallback<void>): void 6306 6307取消设置窗口内容布局的比例，使用callback异步回调。 6308 6309仅主窗可设置，且仅在自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING）下生效，调用后将清除持久化储存的比例信息。 6310 6311**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6312 6313**系统能力：** SystemCapability.WindowManager.WindowManager.Core 6314 6315**参数：** 6316 6317| 参数名 | 类型 | 必填 | 说明 | 6318| ------------------ | ------- | ---- | ------------------------------------------------------------ | 6319| callback | AsyncCallback<void> | 是 | 回调函数。 | 6320 6321**错误码：** 6322 6323以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 6324 6325| 错误码ID | 错误信息 | 6326| ------- | -------------------------------------------- | 6327| 1300002 | This window state is abnormal. | 6328| 1300004 | Unauthorized operation. | 6329 6330**示例：** 6331<!--code_no_check--> 6332```ts 6333// EntryAbility.ets 6334import { UIAbility } from '@kit.AbilityKit'; 6335import { BusinessError } from '@kit.BasicServicesKit'; 6336 6337export default class EntryAbility extends UIAbility { 6338 6339 // ... 6340 onWindowStageCreate(windowStage: window.WindowStage) { 6341 console.info('onWindowStageCreate'); 6342 let windowClass: window.Window = windowStage.getMainWindowSync(); // 获取应用主窗口 6343 if (!windowClass) { 6344 console.info('Failed to load the content. Cause: windowClass is null'); 6345 } 6346 try { 6347 windowClass.resetAspectRatio((err: BusinessError) => { 6348 const errCode: number = err.code; 6349 if (errCode) { 6350 console.error(`Failed to reset the aspect ratio of window. Cause code: ${err.code}, message: ${err.message}`); 6351 return; 6352 } 6353 console.info('Succeeded in resetting aspect ratio of window.'); 6354 }); 6355 } catch (exception) { 6356 console.error(`Failed to reset the aspect ratio of window. Cause code: ${exception.code}, message: ${exception.message}`); 6357 } 6358 } 6359} 6360``` 6361 6362## minimize<sup>11+</sup> 6363 6364minimize(callback: AsyncCallback<void>): void 6365 6366此接口根据调用对象不同，实现不同的功能： 6367 6368- 当调用对象为主窗口时，实现最小化功能，可在Dock栏中还原，2in1 设备上可以使用[restore()](#restore14)进行还原。 6369 6370- 当调用对象为子窗口或悬浮窗时，实现隐藏功能，不可在Dock栏中还原，可以使用[showWindow()](#showwindow9)进行还原。 6371 6372使用callback异步回调。 6373 6374**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6375 6376**系统能力：** SystemCapability.Window.SessionManager 6377 6378**参数：** 6379 6380| 参数名 | 类型 | 必填 | 说明 | 6381| -------- | ------------------------- | ---- | ---------- | 6382| callback | AsyncCallback<void> | 是 | 回调函数。 | 6383 6384**错误码：** 6385 6386以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6387 6388| 错误码ID | 错误信息 | 6389| ------- | ------------------------------ | 6390| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6391| 1300002 | This window state is abnormal. | 6392| 1300003 | This window manager service works abnormally. | 6393 6394**示例：** 6395 6396```ts 6397import { BusinessError } from '@kit.BasicServicesKit'; 6398 6399windowClass.minimize((err: BusinessError) => { 6400 const errCode: number = err.code; 6401 if (errCode) { 6402 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 6403 return; 6404 } 6405 console.info('Succeeded in minimizing the window.'); 6406}); 6407``` 6408 6409## minimize<sup>11+</sup> 6410 6411minimize(): Promise<void> 6412 6413此接口根据调用对象不同，实现不同的功能： 6414 6415- 当调用对象为主窗口时，实现最小化功能，可在Dock栏中还原，2in1 设备上可以使用[restore()](#restore14)进行还原。 6416 6417- 当调用对象为子窗口或悬浮窗时，实现隐藏功能，不可在Dock栏中还原，可以使用[showWindow()](#showwindow9)进行还原。 6418 6419使用Promise异步回调。 6420 6421**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6422 6423**系统能力：** SystemCapability.Window.SessionManager 6424 6425**返回值：** 6426 6427| 类型 | 说明 | 6428| ------------------- | ------------------------- | 6429| Promise<void> | 无返回结果的Promise对象。 | 6430 6431**错误码：** 6432 6433以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6434 6435| 错误码ID | 错误信息 | 6436| ------- | ------------------------------ | 6437| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6438| 1300002 | This window state is abnormal. | 6439| 1300003 | This window manager service works abnormally. | 6440 6441**示例：** 6442 6443```ts 6444import { BusinessError } from '@kit.BasicServicesKit'; 6445 6446let promise = windowClass.minimize(); 6447promise.then(() => { 6448 console.info('Succeeded in minimizing the window.'); 6449}).catch((err: BusinessError) => { 6450 console.error(`Failed to minimize the window. Cause code: ${err.code}, message: ${err.message}`); 6451}); 6452``` 6453 6454## maximize<sup>12+</sup> 6455maximize(presentation?: MaximizePresentation): Promise<void> 6456 6457该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于实现最大化功能。主窗口可调用此接口实现最大化功能；子窗口需在创建时设置子窗口参数maximizeSupported为true，再调用此接口可实现最大化功能。使用Promise异步回调。 6458 6459**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6460 6461**系统能力：** SystemCapability.Window.SessionManager 6462 6463**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 6464 6465**参数：** 6466 6467| 参数名 | 类型 | 必填 | 说明 | 6468| ----- | ---------------------------- | -- | --------------------------------- | 6469| presentation | [MaximizePresentation](arkts-apis-window-e.md#maximizepresentation12) | 否 | 主窗口或子窗口最大化时的布局枚举。默认值window.MaximizePresentation.ENTER_IMMERSIVE，即默认最大化时进入全屏模式。 | 6470 6471**返回值：** 6472 6473| 类型 | 说明 | 6474| ------------------- | ------------------------- | 6475| Promise<void> | 无返回结果的Promise对象。 | 6476 6477**错误码：** 6478 6479以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6480 6481| 错误码ID | 错误信息 | 6482| ------- | ------------------------------ | 6483| 801 | Capability not supported. Function maximize can not work correctly due to limited device capabilities. | 6484| 1300002 | This window state is abnormal. | 6485| 1300003 | This window manager service works abnormally. | 6486| 1300004 | Unauthorized operation. | 6487 6488**示例：** 6489 6490```ts 6491// EntryAbility.ets 6492import { UIAbility } from '@kit.AbilityKit'; 6493import { BusinessError } from '@kit.BasicServicesKit'; 6494export default class EntryAbility extends UIAbility { 6495 // ... 6496 6497 onWindowStageCreate(windowStage: window.WindowStage) { 6498 console.info('onWindowStageCreate'); 6499 let windowClass: window.Window | undefined = undefined; 6500 windowStage.getMainWindow((err: BusinessError, data) => { 6501 const errCode: number = err.code; 6502 if (errCode) { 6503 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 6504 return; 6505 } 6506 windowClass = data; 6507 let promise = windowClass.maximize(); 6508 // let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE); 6509 promise.then(() => { 6510 console.info('Succeeded in maximizing the window.'); 6511 }).catch((err: BusinessError) => { 6512 console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`); 6513 }); 6514 }); 6515 } 6516}; 6517``` 6518 6519## setResizeByDragEnabled<sup>14+</sup> 6520setResizeByDragEnabled(enable: boolean, callback: AsyncCallback<void>): void 6521 6522禁止/使能通过拖拽方式缩放主窗口或启用装饰的子窗口的功能。使用callback异步回调。 6523 6524**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 6525 6526**系统能力：** SystemCapability.Window.SessionManager 6527 6528**参数：** 6529 6530| 参数名 | 类型 | 必填 | 说明 | 6531| ----- | ---------------------------- | -- | --------------------------------- | 6532| enable | boolean | 是 | 设置窗口是否使能通过拖拽进行缩放，true表示使能，false表示禁止。 | 6533| callback | AsyncCallback<void> | 是 | 回调函数。 | 6534 6535**错误码：** 6536 6537以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6538 6539| 错误码ID | 错误信息 | 6540| ------- | ------------------------------ | 6541| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6542| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6543| 1300002 | This window state is abnormal. | 6544| 1300003 | This window manager service works abnormally. | 6545 6546**示例：** 6547 6548```ts 6549try { 6550 let enabled = false; 6551 windowClass.setResizeByDragEnabled(enabled, (err) => { 6552 if (err.code) { 6553 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 6554 return; 6555 } 6556 console.info(`Succeeded in setting the function of disabling the resize by drag window.`); 6557 }); 6558} catch (exception) { 6559 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${exception.code}, message: ${exception.message}`); 6560} 6561``` 6562 6563## setResizeByDragEnabled<sup>14+</sup> 6564setResizeByDragEnabled(enable: boolean): Promise<void> 6565 6566禁止/使能通过拖拽方式缩放主窗口或启用装饰的子窗口的功能。使用Promise异步回调。 6567 6568**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 6569 6570**系统能力：** SystemCapability.Window.SessionManager 6571 6572**参数：** 6573 6574| 参数名 | 类型 | 必填 | 说明 | 6575| ----- | ---------------------------- | -- | --------------------------------- | 6576| enable | boolean | 是 | 设置窗口是否使能通过拖拽进行缩放，true表示使能，false表示禁止。 | 6577 6578**返回值：** 6579 6580| 类型 | 说明 | 6581| ------------------- | ------------------------ | 6582| Promise<void> | 无返回结果的Promise对象。 | 6583 6584**错误码：** 6585 6586以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6587 6588| 错误码ID | 错误信息 | 6589| ------- | ------------------------------ | 6590| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6591| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6592| 1300002 | This window state is abnormal. | 6593| 1300003 | This window manager service works abnormally. | 6594 6595**示例：** 6596 6597```ts 6598import { BusinessError } from '@kit.BasicServicesKit'; 6599 6600try { 6601 let enabled = false; 6602 let promise = windowClass.setResizeByDragEnabled(enabled); 6603 promise.then(() => { 6604 console.info(`Succeeded in setting the function of disabling the resize by drag window.`); 6605 }).catch((err: BusinessError) => { 6606 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${err.code}, message: ${err.message}`); 6607 }); 6608} catch (exception) { 6609 console.error(`Failed to set the function of disabling the resize by drag window. Cause code: ${exception.code}, message: ${exception.message}`); 6610} 6611``` 6612 6613## recover<sup>11+</sup> 6614 6615recover(): Promise<void> 6616 6617该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于将主窗口从全屏、最大化、分屏模式下还原为自由悬浮窗口模式（即窗口模式为window.WindowStatusType.FLOATING），并恢复到进入该模式之前的大小和位置，已经是自由悬浮窗口模式不可再还原。使用Promise异步回调。 6618 6619**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6620 6621**系统能力：** SystemCapability.Window.SessionManager 6622 6623**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 6624 6625**返回值：** 6626 6627| 类型 | 说明 | 6628| ------------------- | ------------------------- | 6629| Promise<void> | 无返回结果的Promise对象。 | 6630 6631**错误码：** 6632 6633以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6634 6635| 错误码ID | 错误信息 | 6636| ------- | ------------------------------ | 6637| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6638| 1300001 | Repeated operation. | 6639| 1300002 | This window state is abnormal. | 6640 6641**示例：** 6642 6643```ts 6644// EntryAbility.ets 6645import { UIAbility } from '@kit.AbilityKit'; 6646import { BusinessError } from '@kit.BasicServicesKit'; 6647 6648export default class EntryAbility extends UIAbility { 6649 // ... 6650 onWindowStageCreate(windowStage: window.WindowStage): void { 6651 console.info('onWindowStageCreate'); 6652 try { 6653 let windowClass = windowStage.getMainWindowSync(); 6654 if (!windowClass) { 6655 console.error('Failed to get main window.'); 6656 return; 6657 } 6658 let promise = windowClass.recover(); 6659 promise.then(() => { 6660 console.info('Succeeded in recovering the window.'); 6661 }).catch((err: BusinessError) => { 6662 console.error(`Failed to recover the window. Cause code: ${err.code}, message: ${err.message}`); 6663 }); 6664 } catch (exception) { 6665 console.error(`Failed to recover the window. Cause code: ${exception.code}, message: ${exception.message}`); 6666 } 6667 } 6668} 6669``` 6670 6671## restore<sup>14+</sup> 6672 6673restore(): Promise<void> 6674 6675主窗口为最小化状态且UIAbility生命周期为onForeground时，将主窗口从最小化状态，恢复到前台显示，并恢复到进入最小化状态之前的大小和位置。使用Promise异步回调。 6676 6677**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 6678 6679**系统能力：** SystemCapability.Window.SessionManager 6680 6681**设备行为差异：** 该接口在2in1设备中可正常调用，在其他设备中返回801错误码。 6682 6683**返回值：** 6684 6685| 类型 | 说明 | 6686| ------------------- | ------------------------- | 6687| Promise<void> | 无返回结果的Promise对象。 | 6688 6689**错误码：** 6690 6691以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6692 6693| **错误码ID** | **错误信息** | 6694| ------------ | ------------------------------------------------------------ | 6695| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6696| 1300002 | This window state is abnormal. | 6697| 1300003 | This window manager service works abnormally. | 6698| 1300004 | Unauthorized operation. | 6699 6700**示例** 6701 6702```ts 6703// EntryAbility.ets 6704import { UIAbility } from '@kit.AbilityKit'; 6705import { BusinessError } from '@kit.BasicServicesKit'; 6706 6707export default class EntryAbility extends UIAbility { 6708 onWindowStageCreate(windowStage: window.WindowStage): void { 6709 try { 6710 let windowClass = windowStage.getMainWindowSync(); 6711 // 调用minimize, 使主窗最小化 6712 windowClass.minimize(); 6713 //设置延时函数延时5秒钟后对主窗进行恢复。 6714 setTimeout(()=>{ 6715 //调用restore()函数对主窗进行恢复。 6716 let promise = windowClass.restore(); 6717 promise.then(() => { 6718 console.info('Succeeded in restoring the window.'); 6719 }).catch((err: BusinessError) => { 6720 console.error(`Failed to restore the window. Cause code: ${err.code}, message: ${err.message}`); 6721 }); 6722 }, 5000); 6723 } catch (exception) { 6724 console.error(`Failed to restore the window. Cause code: ${exception.code}, message: ${exception.message}`); 6725 } 6726 } 6727} 6728``` 6729 6730## getWindowLimits<sup>11+</sup> 6731 6732getWindowLimits(): WindowLimits 6733 6734获取当前应用窗口的尺寸限制。 6735 6736**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6737 6738**系统能力：** SystemCapability.Window.SessionManager 6739 6740**返回值：** 6741 6742| 类型 | 说明 | 6743| ----------------------------- | ------------------ | 6744| [WindowLimits](arkts-apis-window-i.md#windowlimits11) | 当前窗口尺寸限制。 | 6745 6746**错误码：** 6747 6748以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6749 6750| 错误码ID | 错误信息 | 6751| :------- | :----------------------------- | 6752| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6753| 1300002 | This window state is abnormal. | 6754 6755**示例：** 6756 6757```ts 6758try { 6759 let windowLimits = windowClass.getWindowLimits(); 6760} catch (exception) { 6761 console.error(`Failed to obtain the window limits of window. Cause code: ${exception.code}, message: ${exception.message}`); 6762} 6763``` 6764 6765## setWindowLimits<sup>11+</sup> 6766 6767setWindowLimits(windowLimits: WindowLimits): Promise<WindowLimits> 6768 6769设置当前应用窗口的尺寸限制，使用Promise异步回调。 6770默认存在一个系统尺寸限制，系统尺寸限制由产品配置决定，不可修改。未调用setWindowLimits配置过WindowLimits时，使用[getWindowLimits](#getwindowlimits11)可获取系统限制。 6771 6772**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6773 6774**系统能力：** SystemCapability.Window.SessionManager 6775 6776**参数：** 6777 6778| 参数名 | 类型 | 必填 | 说明 | 6779| :----------- | :---------------------------- | :--- | :----------------------------- | 6780| windowLimits | [WindowLimits](arkts-apis-window-i.md#windowlimits11) | 是 | 目标窗口的尺寸限制，单位为px。 | 6781 6782**返回值：** 6783 6784| 类型 | 说明 | 6785| :------------------------------------------- | :---------------------------------- | 6786| Promise<[WindowLimits](arkts-apis-window-i.md#windowlimits11)> | Promise对象。返回设置后的尺寸限制，为入参与系统尺寸限制的交集。 | 6787 6788**错误码：** 6789 6790以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6791 6792| 错误码ID | 错误信息 | 6793| :------- | :-------------------------------------------- | 6794| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6795| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6796| 1300002 | This window state is abnormal. | 6797| 1300003 | This window manager service works abnormally. | 6798| 1300004 | Unauthorized operation. | 6799 6800**示例：** 6801 6802```ts 6803import { BusinessError } from '@kit.BasicServicesKit'; 6804try { 6805 let windowLimits: window.WindowLimits = { 6806 maxWidth: 1500, 6807 maxHeight: 1000, 6808 minWidth: 500, 6809 minHeight: 400 6810 }; 6811 let promise = windowClass.setWindowLimits(windowLimits); 6812 promise.then((data) => { 6813 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 6814 }).catch((err: BusinessError) => { 6815 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 6816 }); 6817} catch (exception) { 6818 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 6819} 6820``` 6821 6822## setWindowLimits<sup>15+</sup> 6823 6824setWindowLimits(windowLimits: WindowLimits, isForcible: boolean): Promise<WindowLimits> 6825 6826该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于设置当前应用窗口的尺寸限制，使用Promise异步回调。 6827 6828默认存在一个系统尺寸限制，系统尺寸限制由产品配置决定，不可修改。未调用setWindowLimits配置过WindowLimits时，使用[getWindowLimits](#getwindowlimits11)可获取系统限制。 6829 6830**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 6831 6832**系统能力：** SystemCapability.Window.SessionManager 6833 6834**设备行为差异：** API version 19之前，该接口在2in1设备中可正常调用，在其他设备中返回801错误码。从API version 19开始，该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 6835 6836**参数：** 6837 6838| 参数名 | 类型 | 必填 | 说明 | 6839| :----------- | :---------------------------- | :--- | :----------------------------- | 6840| windowLimits | [WindowLimits](arkts-apis-window-i.md#windowlimits11) | 是 | 目标窗口的尺寸限制，单位为px。 | 6841| isForcible | boolean | 是 | 是否强制设置窗口的尺寸限制。<br>设置为true，表示窗口宽高最小值以系统限制值和40vp两者中的低数值为准，窗口宽高的最大值仍取决于系统限制。<br>设置为false，表示窗口宽高的最小值和最大值都取决于系统限制。| 6842 6843**返回值：** 6844 6845| 类型 | 说明 | 6846| :------------------------------------------- | :---------------------------------- | 6847| Promise<[WindowLimits](arkts-apis-window-i.md#windowlimits11)> | Promise对象。返回设置后的窗口尺寸限制。根据isForcible判断为入参与系统默认窗口尺寸限制的交集。 | 6848 6849**错误码：** 6850 6851以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6852 6853| 错误码ID | 错误信息 | 6854| :------- | :-------------------------------------------- | 6855| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 6856| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6857| 1300002 | This window state is abnormal. | 6858| 1300003 | This window manager service works abnormally. | 6859| 1300004 | Unauthorized operation. | 6860 6861**示例：** 6862 6863```ts 6864import { BusinessError } from '@kit.BasicServicesKit'; 6865try { 6866 let windowLimits: window.WindowLimits = { 6867 maxWidth: 1500, 6868 maxHeight: 1000, 6869 minWidth: 100, 6870 minHeight: 100 6871 }; 6872 let promise = windowClass.setWindowLimits(windowLimits, true); 6873 promise.then((data) => { 6874 console.info('Succeeded in changing the window limits. Cause:' + JSON.stringify(data)); 6875 }).catch((err: BusinessError) => { 6876 console.error(`Failed to change the window limits. Cause code: ${err.code}, message: ${err.message}`); 6877 }); 6878} catch (exception) { 6879 console.error(`Failed to change the window limits. Cause code: ${exception.code}, message: ${exception.message}`); 6880} 6881``` 6882 6883## setWindowMask<sup>12+</sup> 6884 6885setWindowMask(windowMask: Array<Array<number>>): Promise<void>; 6886 6887设置异形窗口的掩码，使用Promise异步回调。异形窗口为非常规形状的窗口，掩码用于描述异形窗口的形状。此接口仅限子窗和全局悬浮窗可用。 6888当异形窗口大小发生变化时，实际的显示内容为掩码大小和窗口大小的交集部分。 6889 6890该接口只在多个线程操作同一个窗口时可能返回错误码1300002。窗口被销毁场景下错误码返回401。 6891 6892 6893**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6894 6895**系统能力：** SystemCapability.Window.SessionManager 6896 6897**参数：** 6898 6899| 参数名 | 类型 | 必填 | 说明 | 6900| :----------- | :---------------------------- | :--- | :----------------------------- | 6901| windowMask | Array<Array<number>> | 是 | 异形窗口的掩码，该参数仅支持宽高为窗口宽高、取值为整数0和整数1的二维数组输入，整数0代表所在像素透明，整数1代表所在像素不透明，宽高不符合的二维数组或二维数组取值不为整数0和整数1的二维数组为非法参数。 | 6902 6903**返回值：** 6904 6905| 类型 | 说明 | 6906| :------------------------------------------- | :---------------------------------- | 6907| Promise<void> | 无返回结果的Promise对象。 | 6908 6909**错误码：** 6910 6911以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6912 6913| 错误码ID | 错误信息 | 6914| :------- | :-------------------------------------------- | 6915| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6916| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6917| 1300002 | This window state is abnormal. | 6918| 1300003 | This window manager service works abnormally. | 6919| 1300004 | Unauthorized operation. | 6920 6921**示例：** 6922 6923```ts 6924import { BusinessError } from '@kit.BasicServicesKit'; 6925try { 6926 let windowMask: Array<Array<number>> = [ 6927 [0, 0, 0, 1, 0, 0, 0], 6928 [0, 0, 1, 1, 1, 0, 0], 6929 [0, 1, 1, 0, 1, 1, 0], 6930 [1, 1, 0, 0, 0, 1, 1] 6931 ]; 6932 let promise = windowClass.setWindowMask(windowMask); 6933 promise.then(() => { 6934 console.info('Succeeded in setting the window mask.'); 6935 }).catch((err: BusinessError) => { 6936 console.error(`Failed to set the window mask. Cause code: ${err.code}, message: ${err.message}`); 6937 }); 6938} catch (exception) { 6939 console.error(`Failed to set the window mask. Cause code: ${exception.code}, message: ${exception.message}`); 6940} 6941``` 6942 6943## keepKeyboardOnFocus<sup>11+</sup> 6944 6945keepKeyboardOnFocus(keepKeyboardFlag: boolean): void 6946 6947窗口获焦时保留由其他窗口创建的软键盘，仅支持系统窗口与应用子窗口。 6948 6949**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6950 6951**系统能力：** SystemCapability.Window.SessionManager 6952 6953**参数：** 6954 6955| 参数名 | 类型 | 必填 | 说明 | 6956| ---------------- | ------- | ---- | ------------------------------------------------------------ | 6957| keepKeyboardFlag | boolean | 是 | 是否保留其他窗口创建的软键盘。true表示保留；false表示不保留。| 6958 6959**错误码：** 6960 6961以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 6962 6963| 错误码ID | 错误信息 | 6964| ------- | ---------------------------------------- | 6965| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 6966| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 6967| 1300002 | This window state is abnormal. | 6968| 1300004 | Unauthorized operation. | 6969 6970**示例：** 6971 6972```ts 6973try { 6974 windowClass.keepKeyboardOnFocus(true); 6975} catch (exception) { 6976 console.error(`Failed to keep keyboard onFocus. Cause code: ${exception.code}, message: ${exception.message}`); 6977} 6978``` 6979 6980## setWindowDecorVisible<sup>11+</sup> 6981 6982setWindowDecorVisible(isVisible: boolean): void 6983 6984设置窗口标题栏是否可见，对存在标题栏和三键区的窗口形态生效。Stage模型下，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 6985 6986设置窗口标题栏不可见后，当主窗口进入全屏沉浸状态时，此时鼠标Hover到上方窗口标题栏热区上会显示悬浮标题栏。若想禁用悬浮标题栏显示，请使用[setTitleAndDockHoverShown()](#settitleanddockhovershown14)接口。 6987 6988**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 6989 6990**系统能力：** SystemCapability.Window.SessionManager 6991 6992**参数：** 6993 6994| 参数名 | 类型 | 必填 | 说明 | 6995| --------- | ------- | ---- | --------------------------------------------- | 6996| isVisible | boolean | 是 | 设置标题栏是否可见，true为可见，false为隐藏。 | 6997 6998**错误码：** 6999 7000以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7001 7002| 错误码ID | 错误信息 | 7003| -------- | ------------------------------ | 7004| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7005| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7006| 1300002 | This window state is abnormal. | 7007 7008**示例：** 7009 7010```ts 7011import { BusinessError } from '@kit.BasicServicesKit'; 7012let storage: LocalStorage = new LocalStorage(); 7013storage.setOrCreate('storageSimpleProp', 121); 7014windowClass.loadContent("pages/page2", storage, (err: BusinessError) => { 7015 let errCode: number = err.code; 7016 if (errCode) { 7017 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 7018 return; 7019 } 7020 console.info('Succeeded in loading the content.'); 7021 let isVisible = false; 7022 // 调用setWindowDecorVisible接口 7023 try { 7024 windowClass?.setWindowDecorVisible(isVisible); 7025 } catch (exception) { 7026 console.error(`Failed to set the visibility of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 7027 } 7028}); 7029``` 7030 7031## getWindowDecorVisible<sup>18+</sup> 7032 7033getWindowDecorVisible(): boolean 7034 7035该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于查询窗口标题栏是否可见。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 7036 7037**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 7038 7039**系统能力：** SystemCapability.Window.SessionManager 7040 7041**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 7042 7043**返回值：** 7044 7045| 类型 | 说明 | 7046| ------ | ------------------------------------------------------------ | 7047| boolean | 返回当前窗口标题栏是否可见，true表示可见，false表示不可见。| 7048 7049**错误码：** 7050 7051以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7052 7053| 错误码ID | 错误信息 | 7054| -------- | ------------------------------ | 7055| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7056| 1300002 | This window state is abnormal. | 7057 7058**示例：** 7059 7060```ts 7061let isVisible: boolean | undefined = undefined; 7062windowClass.setUIContent('pages/WindowPage').then(() => { 7063 try { 7064 isVisible = windowClass?.getWindowDecorVisible(); 7065 } catch (exception) { 7066 console.error(`Failed to get the window decor visibility. Cause code: ${exception.code}, message: ${exception.message}`); 7067 } 7068}) 7069``` 7070 7071## setWindowTitle<sup>15+</sup> 7072 7073setWindowTitle(titleName: string): Promise<void> 7074 7075设置窗口标题，存在标题栏的窗口形态生效，若不存在标题栏则返回1300002错误码，使用Promise异步回调。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 7076 7077**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 7078 7079**系统能力：** SystemCapability.Window.SessionManager 7080 7081**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 7082 7083**参数：** 7084 7085| 参数名 | 类型 | 必填 | 说明 | 7086| --------- | ------- | ---- | --------------------------------------------- | 7087| titleName | string | 是 | 窗口标题。标题显示区域最右端不超过系统三键区域最左端，超过部分以省略号表示。 | 7088 7089**返回值：** 7090 7091| 类型 | 说明 | 7092| ------------------- | ------------------------ | 7093| Promise<void> | 无返回结果的Promise对象。 | 7094 7095**错误码：** 7096 7097以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7098 7099| 错误码ID | 错误信息 | 7100| -------- | ------------------------------ | 7101| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7102| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7103| 1300002 | This window state is abnormal. | 7104 7105**示例：** 7106 7107```ts 7108import { BusinessError } from '@kit.BasicServicesKit'; 7109 7110try { 7111 let title = "title"; 7112 windowClass.setWindowTitle(title).then(() => { 7113 console.info('Succeeded in setting the window title.'); 7114 }).catch((err: BusinessError) => { 7115 console.error(`Failed to set the window title. Cause code: ${err.code}, message: ${err.message}`); 7116 }); 7117} catch (exception) { 7118 console.error(`Failed to set the window title. Cause code: ${exception.code}, message: ${exception.message}`); 7119} 7120``` 7121 7122## setWindowTitleMoveEnabled<sup>14+</sup> 7123 7124setWindowTitleMoveEnabled(enabled: boolean): void 7125 7126该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于禁止/使能主窗或子窗标题栏默认移动窗口和双击最大化的功能，当禁用标题栏默认移动窗口和双击最大化的功能时，可使用[startMoving()](#startmoving14)在应用热区中发起拖拽移动，使用[maximize()](#maximize12)实现最大化功能。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 7127 7128**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 7129 7130**系统能力：** SystemCapability.Window.SessionManager 7131 7132**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 7133 7134**参数：** 7135 7136| 参数名 | 类型 | 必填 | 说明 | 7137| --------- | ------- | ---- | --------------------------------------------- | 7138| enabled | boolean | 是 | 是否使能标题栏默认移动窗口和双击最大化功能，true表示使能，false表示不使能。| 7139 7140**错误码：** 7141 7142以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7143 7144| 错误码ID | 错误信息 | 7145| -------- | ------------------------------ | 7146| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7147| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7148| 1300002 | This window state is abnormal. | 7149| 1300004 | Unauthorized operation. | 7150 7151**示例：** 7152 7153```ts 7154// EntryAbility.ets 7155import { UIAbility } from '@kit.AbilityKit'; 7156 7157export default class EntryAbility extends UIAbility { 7158 onWindowStageCreate(windowStage: window.WindowStage): void { 7159 try { 7160 windowStage.loadContent("pages/Index").then(() =>{ 7161 let windowClass = windowStage.getMainWindowSync(); 7162 let enabled = false; 7163 windowClass.setWindowTitleMoveEnabled(enabled); 7164 console.info(`Succeeded in setting the the window title move enabled: ${enabled}`); 7165 }); 7166 } catch (exception) { 7167 console.error(`Failed to set the window title move enabled. Cause code: ${exception.code}, message: ${exception.message}`); 7168 } 7169 } 7170} 7171``` 7172 7173## setSubWindowModal<sup>12+</sup> 7174 7175setSubWindowModal(isModal: boolean): Promise<void> 7176 7177设置子窗的模态属性是否启用，使用Promise异步回调。 7178 7179子窗口调用该接口时，设置子窗口模态属性是否启用。启用子窗口模态属性后，其父级窗口不能响应用户操作，直到子窗口关闭或者子窗口的模态属性被禁用。 7180 7181子窗口之外的窗口调用该接口时，会报错。 7182 7183**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7184 7185**系统能力：** SystemCapability.Window.SessionManager 7186 7187**参数：** 7188 7189| 参数名 | 类型 | 必填 | 说明 | 7190| --------- | ------- | ---- | --------------------------------------------- | 7191| isModal | boolean | 是 | 设置子窗口模态属性是否启用，true为启用，false为不启用。 | 7192 7193 7194**返回值：** 7195 7196| 类型 | 说明 | 7197| ------------------- | ------------------------ | 7198| Promise<void> | 无返回结果的Promise对象。 | 7199 7200**错误码：** 7201 7202以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7203 7204| 错误码ID | 错误信息 | 7205| -------- | ------------------------------ | 7206| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7207| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7208| 1300002 | This window state is abnormal. | 7209| 1300003 | This window manager service works abnormally. | 7210| 1300004 | Unauthorized operation. | 7211 7212**示例：** 7213 7214```ts 7215// EntryAbility.ets 7216import { UIAbility } from '@kit.AbilityKit'; 7217import { BusinessError } from '@kit.BasicServicesKit'; 7218 7219export default class EntryAbility extends UIAbility { 7220 // ... 7221 onWindowStageCreate(windowStage: window.WindowStage): void { 7222 console.info('onWindowStageCreate'); 7223 let windowClass: window.Window | undefined = undefined; 7224 // 创建子窗 7225 try { 7226 let subWindow = windowStage.createSubWindow("testSubWindow"); 7227 subWindow.then((data) => { 7228 if (data == null) { 7229 console.error("Failed to create the subWindow. Cause: The data is empty"); 7230 return; 7231 } 7232 windowClass = data; 7233 let promise = windowClass.setSubWindowModal(true); 7234 promise.then(() => { 7235 console.info('Succeeded in setting subwindow modal'); 7236 }).catch((err: BusinessError) => { 7237 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 7238 }); 7239 }); 7240 } catch (exception) { 7241 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 7242 } 7243 } 7244} 7245``` 7246 7247## setSubWindowModal<sup>14+</sup> 7248 7249setSubWindowModal(isModal: boolean, modalityType: ModalityType): Promise<void> 7250 7251设置子窗的模态类型，使用Promise异步回调。 7252 7253当子窗口模态类型为模窗口子窗时，其父级窗口不能响应用户操作，直到子窗口关闭或者子窗口的模态类型被禁用。 7254 7255当子窗口模态类型为模应用子窗时，其父级窗口与该应用其他实例的窗口不能响应用户操作，直到子窗口关闭或者子窗口的模态类型被禁用。 7256 7257此接口仅支持设置子窗口模态类型，当需要禁用子窗口模态属性时，建议使用[setSubWindowModal<sup>12+</sup>](#setsubwindowmodal12)。 7258 7259子窗口之外的窗口调用该接口时，会报错。 7260 7261**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 7262 7263**系统能力：** SystemCapability.Window.SessionManager 7264 7265**参数：** 7266 7267| 参数名 | 类型 | 必填 | 说明 | 7268| --------- | ------- | ---- | --------------------------------------------- | 7269| isModal | boolean | 是 | 设置子窗口模态属性是否启用，true为启用，false为不启用。当前仅支持设置为true。 | 7270| modalityType | [ModalityType](arkts-apis-window-e.md#modalitytype14) | 是 | 子窗口模态类型。 | 7271 7272**返回值：** 7273 7274| 类型 | 说明 | 7275| ------------------- | ------------------------ | 7276| Promise<void> | 无返回结果的Promise对象。 | 7277 7278**错误码：** 7279 7280以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7281 7282| 错误码ID | 错误信息 | 7283| -------- | ------------------------------ | 7284| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7285| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7286| 1300002 | This window state is abnormal. | 7287| 1300003 | This window manager service works abnormally. | 7288| 1300004 | Unauthorized operation. | 7289 7290**示例：** 7291 7292```ts 7293// EntryAbility.ets 7294import { UIAbility } from '@kit.AbilityKit'; 7295import { BusinessError } from '@kit.BasicServicesKit'; 7296import { window } from '@kit.ArkUI'; 7297 7298export default class EntryAbility extends UIAbility { 7299 // ... 7300 onWindowStageCreate(windowStage: window.WindowStage): void { 7301 console.info('onWindowStageCreate'); 7302 let windowClass: window.Window | undefined = undefined; 7303 // 创建子窗 7304 try { 7305 let subWindow = windowStage.createSubWindow("testSubWindow"); 7306 subWindow.then((data) => { 7307 if (!data) { 7308 console.error("Failed to create the subWindow. Cause: The data is empty"); 7309 return; 7310 } 7311 windowClass = data; 7312 let promise = windowClass.setSubWindowModal(true, window.ModalityType.WINDOW_MODALITY); 7313 promise.then(() => { 7314 console.info('Succeeded in setting subwindow modal'); 7315 }).catch((err: BusinessError) => { 7316 console.error(`Failed to set subwindow modal. Cause code: ${err.code}, message: ${err.message}`); 7317 }); 7318 }); 7319 } catch (exception) { 7320 console.error(`Failed to create the subWindow. Cause code: ${exception.code}, message: ${exception.message}`); 7321 } 7322 } 7323} 7324``` 7325 7326## setWindowDecorHeight<sup>11+</sup> 7327 7328setWindowDecorHeight(height: number): void 7329 7330<!--RP1--> 7331设置窗口的标题栏高度，仅在2in1设备中，对存在标题栏和三键区的窗口形态生效。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 7332<!--RP1End--> 7333 7334当主窗口进入全屏沉浸状态时，此时鼠标Hover到窗口标题栏热区时，会显示悬浮标题栏，悬浮标题栏高度固定为37vp。 7335 7336**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7337 7338**系统能力：** SystemCapability.Window.SessionManager 7339 7340**参数：** 7341 7342| 参数名 | 类型 | 必填 | 说明 | 7343| ------ | ------ | ---- | ------------------------------------------------------------ | 7344| height | number | 是 |设置的窗口标题栏高度，仅支持具有窗口标题栏的窗口。该参数为整数，浮点数输入将向下取整，取值范围为[37,112]，范围外为非法参数，单位为vp。 | 7345 7346**错误码：** 7347 7348以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7349 7350| 错误码ID | 错误信息 | 7351| -------- | ------------------------------ | 7352| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 7353| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7354| 1300002 | This window state is abnormal. | 7355 7356**示例：** 7357 7358```ts 7359windowClass.setUIContent('pages/WindowPage').then(() => { 7360 let height: number = 50; 7361 try { 7362 windowClass?.setWindowDecorHeight(height); 7363 console.info(`Succeeded in setting the height of window decor: ${height}`); 7364 } catch (exception) { 7365 console.error(`Failed to set the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 7366 } 7367}) 7368``` 7369 7370## setDecorButtonStyle<sup>14+</sup> 7371 7372setDecorButtonStyle(dectorStyle: DecorButtonStyle): void 7373 7374该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于设置装饰栏按钮样式，仅对主窗和子窗生效。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 7375 7376**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 7377 7378**系统能力：** SystemCapability.Window.SessionManager 7379 7380**设备行为差异：** API version 18之前，该接口在2in1设备中可正常调用，在其他设备中返回801错误码。从API version 18开始，该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 7381 7382**参数：** 7383 7384| 参数名 | 类型 | 必填 | 说明 | 7385| --------- | ------- | ---- | --------------------------------------------- | 7386| dectorStyle | [DecorButtonStyle](arkts-apis-window-i.md#decorbuttonstyle14) | 是 | 要设置的装饰栏按钮样式。 | 7387 7388**错误码：** 7389 7390以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7391 7392| 错误码ID | 错误信息 | 7393| -------- | ------------------------------ | 7394| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7395| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7396| 1300002 | This window state is abnormal. | 7397| 1300004 | Unauthorized operation. | 7398 7399**示例：** 7400 7401```ts 7402// EntryAbility.ets 7403import { UIAbility } from '@kit.AbilityKit'; 7404import { ConfigurationConstant } from '@kit.AbilityKit'; 7405 7406export default class EntryAbility extends UIAbility { 7407 onWindowStageCreate(windowStage: window.WindowStage): void { 7408 try { 7409 windowStage.loadContent("pages/Index").then(() =>{ 7410 let windowClass = windowStage.getMainWindowSync(); 7411 let colorMode : ConfigurationConstant.ColorMode = ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT; 7412 let style: window.DecorButtonStyle = { 7413 colorMode: colorMode, 7414 buttonBackgroundSize: 28, 7415 spacingBetweenButtons: 12, 7416 closeButtonRightMargin: 20, 7417 buttonIconSize: 20, 7418 buttonBackgroundCornerRadius: 4 7419 }; 7420 windowClass.setDecorButtonStyle(style); 7421 console.info('Succeeded in setting the style of button. Data: ' + JSON.stringify(style)); 7422 }); 7423 } catch (exception) { 7424 console.error(`Failed to set the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 7425 } 7426 } 7427} 7428``` 7429 7430## getDecorButtonStyle<sup>14+</sup> 7431 7432getDecorButtonStyle(): DecorButtonStyle 7433 7434该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于获取装饰栏按钮样式，仅对主窗和子窗生效。 7435 7436**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 7437 7438**系统能力：** SystemCapability.Window.SessionManager 7439 7440**设备行为差异：** API version 18之前，该接口在2in1设备中可正常调用，在其他设备中返回801错误码。从API version 18开始，该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 7441 7442**返回值：** 7443 7444| 类型 | 说明 | 7445| ------------------------------------- | ------------------------------------------------------------ | 7446| [DecorButtonStyle](arkts-apis-window-i.md#decorbuttonstyle14) | 返回当前窗口装饰栏上的按钮样式，窗口装饰按钮区域位于窗口的右上角。 | 7447 7448**错误码：** 7449 7450以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7451 7452| 错误码ID | 错误信息 | 7453| -------- | ------------------------------ | 7454| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7455| 1300002 | This window state is abnormal. | 7456| 1300003 | This window manager service works abnormally. | 7457| 1300004 | Unauthorized operation. | 7458 7459**示例：** 7460 7461```ts 7462try { 7463 let decorButtonStyle = windowClass.getDecorButtonStyle(); 7464 console.info('Succeeded in getting the style of button. Data: ' + JSON.stringify(decorButtonStyle)); 7465} catch (exception) { 7466 console.error(`Failed to get the style of button. Cause code: ${exception.code}, message: ${exception.message}`); 7467} 7468``` 7469 7470## getWindowDecorHeight<sup>11+</sup> 7471 7472getWindowDecorHeight(): number 7473 7474<!--RP2--> 7475获取窗口的标题栏高度，仅在2in1设备中，对存在标题栏和三键区的窗口形态生效。如果使用Stage模型，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 7476<!--RP2End--> 7477 7478**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7479 7480**系统能力：** SystemCapability.Window.SessionManager 7481 7482**返回值：** 7483 7484| 类型 | 说明 | 7485| ------ | ------------------------------------------------------------ | 7486| number | 返回的窗口标题栏高度。该参数为整数，取值范围为[37,112]，单位为vp。 | 7487 7488**错误码：** 7489 7490以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7491 7492| 错误码ID | 错误信息 | 7493| -------- | ------------------------------ | 7494| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7495| 1300002 | This window state is abnormal. | 7496 7497**示例：** 7498 7499```ts 7500windowClass.setUIContent('pages/WindowPage').then(() => { 7501 try { 7502 let height = windowClass?.getWindowDecorHeight(); 7503 console.info(`Succeeded in getting the height of window decor: ${height}`); 7504 } catch (exception) { 7505 console.error(`Failed to get the height of window decor. Cause code: ${exception.code}, message: ${exception.message}`); 7506 } 7507}) 7508``` 7509 7510## getTitleButtonRect<sup>11+</sup> 7511 7512getTitleButtonRect(): TitleButtonRect 7513 7514获取主窗口或启用装饰的子窗口的标题栏上的最小化、最大化、关闭按钮矩形区域。 7515 7516**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7517 7518**系统能力：** SystemCapability.Window.SessionManager 7519 7520**返回值：** 7521 7522| 类型 | 说明 | 7523| ------------------------------------- | ------------------------------------------------------------ | 7524| [TitleButtonRect](arkts-apis-window-i.md#titlebuttonrect11) | 标题栏上的最小化、最大化、关闭按钮矩形区域，该区域位置坐标相对窗口右上角。 | 7525 7526**错误码：** 7527 7528以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7529 7530| 错误码ID | 错误信息 | 7531| -------- | ------------------------------ | 7532| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7533| 1300002 | This window state is abnormal. | 7534 7535**示例：** 7536 7537```ts 7538// EntryAbility.ets 7539import { UIAbility } from '@kit.AbilityKit'; 7540import { BusinessError } from '@kit.BasicServicesKit'; 7541 7542export default class EntryAbility extends UIAbility { 7543 // ... 7544 onWindowStageCreate(windowStage: window.WindowStage): void { 7545 console.info('onWindowStageCreate'); 7546 let windowClass: window.Window | undefined = undefined; 7547 windowStage.getMainWindow((err: BusinessError, data) => { 7548 const errCode: number = err.code; 7549 if (errCode) { 7550 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7551 return; 7552 } 7553 windowClass = data; 7554 try { 7555 let titleButtonArea = windowClass.getTitleButtonRect(); 7556 console.info('Succeeded in obtaining the area of title buttons. Data: ' + JSON.stringify(titleButtonArea)); 7557 } catch (exception) { 7558 console.error(`Failed to get the area of title buttons. Cause code: ${exception.code}, message: ${exception.message}`); 7559 } 7560 }); 7561 } 7562} 7563``` 7564 7565## getWindowStatus<sup>12+</sup> 7566 7567getWindowStatus(): WindowStatusType 7568 7569获取当前应用窗口的模式。 7570 7571**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7572 7573**系统能力：** SystemCapability.Window.SessionManager 7574 7575**返回值：** 7576 7577| 类型 | 说明 | 7578| ------------------------------ | ----------------------------------------| 7579| [WindowStatusType](arkts-apis-window-e.md#windowstatustype11) | 当前窗口模式。 | 7580 7581**错误码：** 7582 7583以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7584 7585| 错误码ID | 错误信息 | 7586| ------- | ------------------------------ | 7587| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7588| 1300002 | This window state is abnormal. | 7589 7590**示例：** 7591 7592```ts 7593try { 7594 let windowStatusType = windowClass.getWindowStatus(); 7595} catch (exception) { 7596 console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); 7597} 7598``` 7599 7600## isFocused<sup>12+</sup> 7601 7602isFocused(): boolean 7603 7604判断当前窗口是否已获焦。 7605 7606**系统能力：** SystemCapability.WindowManager.WindowManager.Core 7607 7608**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7609 7610**返回值：** 7611 7612| 类型 | 说明 | 7613| ------- | ------------------------------------------------------------------ | 7614| boolean | 当前窗口是否已获焦。true表示当前窗口已获焦，false则表示当前窗口未获焦。 | 7615 7616**错误码：** 7617 7618以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 7619 7620| 错误码ID | 错误信息 | 7621| ------- | ------------------------------ | 7622| 1300002 | This window state is abnormal. | 7623 7624**示例：** 7625 7626```ts 7627try { 7628 let focus = windowClass.isFocused(); 7629 console.info('Succeeded in checking whether the window is focused. Data: ' + JSON.stringify(focus)); 7630} catch (exception) { 7631 console.error(`Failed to check whether the window is focused. Cause code: ${exception.code}, message: ${exception.message}`); 7632} 7633``` 7634 7635## createSubWindowWithOptions<sup>12+</sup> 7636 7637createSubWindowWithOptions(name: string, options: SubWindowOptions): Promise<Window> 7638 7639该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于创建主窗口、子窗口或悬浮窗下的子窗口，使用Promise异步回调。 7640 7641**模型约束：** 此接口仅可在Stage模型下使用。 7642 7643**系统能力：** SystemCapability.Window.SessionManager 7644 7645**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7646 7647**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备类型中返回undefined。 7648 7649**参数：** 7650 7651| 参数名 | 类型 | 必填 | 说明 | 7652| ------ | ------ | ---- | -------------- | 7653| name | string | 是 | 子窗口的名字。 | 7654| options | [SubWindowOptions](arkts-apis-window-i.md#subwindowoptions11) | 是 | 子窗口参数。decorEnabled为true时，子窗口为非[沉浸式布局](../../windowmanager/window-terminology.md#沉浸式布局)；decorEnabled为false时，子窗口为沉浸式布局。| 7655 7656**返回值：** 7657 7658| 类型 | 说明 | 7659| -------------------------------- | ------------------------------------------------ | 7660| Promise<[Window](arkts-apis-window-Window.md)> | Promise对象。返回当前Window下创建的子窗口对象。 | 7661 7662**错误码：** 7663 7664以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7665 7666| 错误码ID | 错误信息 | 7667| ------- | ------------------------------ | 7668| 401 | Parameter error. Possible cause: Incorrect parameter types. | 7669| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7670| 1300002 | This window state is abnormal. | 7671| 1300003 | This window manager service works abnormally. | 7672| 1300004 | Unauthorized operation. | 7673 7674**示例：** 7675 7676```ts 7677import { BusinessError } from '@kit.BasicServicesKit'; 7678 7679try { 7680 let options : window.SubWindowOptions = { 7681 title: 'title', 7682 decorEnabled: true, 7683 isModal: true 7684 }; 7685 let promise = windowClass.createSubWindowWithOptions('mySubWindow', options); 7686 promise.then((data) => { 7687 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 7688 }).catch((err: BusinessError) => { 7689 console.error(`Failed to create the subwindow. Cause code: ${err.code}, message: ${err.message}`); 7690 }); 7691} catch (exception) { 7692 console.error(`Failed to create the subwindow. Cause code: ${exception.code}, message: ${exception.message}`); 7693} 7694``` 7695 7696## setParentWindow<sup>19+</sup> 7697 7698setParentWindow(windowId: number): Promise<void> 7699 7700更改子窗口的父窗口，该父窗口仅支持主窗口、子窗口或悬浮窗，使用Promise异步回调。 7701 7702如果该子窗口处于获焦状态，且新的父窗口处于前台，则会抬升父窗口的层级。 7703 7704如果该子窗口处于获焦状态，且新的父窗口的子窗口存在层级更高的模态子窗口，则焦点会转移给该模态子窗口。 7705 7706**系统能力：** SystemCapability.Window.SessionManager 7707 7708**设备行为差异：** 该接口在2in1设备中可正常调用，在其他设备中返回801错误码。 7709 7710**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 7711 7712**参数：** 7713 7714| 参数名 | 类型 | 必填 | 说明 | 7715| ------ | ------ | ---- | -------------- | 7716| windowId | number | 是 | 父窗口id，该参数应为整数。推荐使用[getWindowProperties()](#getwindowproperties9)方法获取父窗口id属性。| 7717 7718**返回值：** 7719 7720| 类型 | 说明 | 7721| ------------------- | ------------------------| 7722| Promise<void> | 无返回结果的Promise对象。 | 7723 7724**错误码：** 7725 7726以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7727 7728| 错误码ID | 错误信息 | 7729| ------- | ------------------------------ | 7730| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7731| 1300002 | This window state is abnormal. | 7732| 1300003 | This window manager service works abnormally. | 7733| 1300004 | Unauthorized operation. | 7734| 1300009 | The parent window is invaild. | 7735 7736**示例：** 7737 7738```ts 7739import { BusinessError } from '@kit.BasicServicesKit'; 7740 7741try { 7742 let windowClass: window.Window = window.findWindow("subWindow"); 7743 let newParentWindow: window.Window = window.findWindow("newParentWindow"); 7744 let newParentWindowId: number = newParentWindow.getWindowProperties().id; 7745 let promise = windowClass.setParentWindow(newParentWindowId); 7746 promise.then(() => { 7747 console.info('Succeeded in setting the new parent window.'); 7748 }).catch((err: BusinessError) => { 7749 console.error(`Failed to set the new parent window. Cause code: ${err.code}, message: ${err.message}`); 7750 }); 7751} catch (exception) { 7752 console.error(`Failed to set the new parent window. Cause code: ${exception.code}, message: ${exception.message}`); 7753} 7754``` 7755 7756## getParentWindow<sup>19+</sup> 7757 7758getParentWindow(): Window 7759 7760获取子窗口的父窗口。 7761 7762**系统能力：** SystemCapability.Window.SessionManager 7763 7764**设备行为差异：** 该接口在2in1设备中可正常调用，在其他设备中返回801错误码。 7765 7766**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 7767 7768**返回值：** 7769 7770| 类型 | 说明 | 7771| ----------------- | ------------------- | 7772| [Window](arkts-apis-window-Window.md) | 子窗口的父窗口对象。 | 7773 7774**错误码：** 7775 7776以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7777 7778| 错误码ID | 错误信息 | 7779| ------- | ------------------------------ | 7780| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7781| 1300002 | This window state is abnormal. | 7782| 1300004 | Unauthorized operation. | 7783| 1300009 | The parent window is invaild. | 7784 7785**示例：** 7786 7787```ts 7788try { 7789 let windowClass: window.Window = window.findWindow("subWindow"); 7790 let parentWindow: window.Window = windowClass.getParentWindow(); 7791 let properties = parentWindow.getWindowProperties(); 7792 console.info('Succeeded in obtaining parent window properties. Property: ' + JSON.stringify(properties)); 7793} catch (exception) { 7794 console.error(`Failed to get the parent window. Cause code: ${exception.code}, message: ${exception.message}`); 7795} 7796``` 7797 7798## setWindowTitleButtonVisible<sup>14+</sup> 7799 7800setWindowTitleButtonVisible(isMaximizeButtonVisible: boolean, isMinimizeButtonVisible: boolean, isCloseButtonVisible?: boolean): void 7801 7802该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于设置主窗标题栏上的最大化、最小化、关闭按钮是否可见。 7803 7804**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 7805 7806**系统能力：** SystemCapability.Window.SessionManager 7807 7808**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 7809 7810**参数：** 7811 7812| 参数名 | 类型 | 必填 | 说明 | 7813| --------- | ------- | ---- | --------------------------------------------- | 7814| isMaximizeButtonVisible | boolean | 是 | 设置最大化按钮是否可见，true为可见，false为隐藏。如果最大化按钮隐藏，那么在最大化场景下，也隐藏对应的还原按钮。 | 7815| isMinimizeButtonVisible | boolean | 是 | 设置最小化按钮是否可见，true为可见，false为隐藏。 | 7816| isCloseButtonVisible | boolean | 否 | 设置关闭按钮是否可见，true为可见，false为隐藏，默认值true。 | 7817 7818**错误码：** 7819 7820以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7821 7822| 错误码ID | 错误信息 | 7823| -------- | ------------------------------ | 7824| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7825| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7826| 1300002 | This window state is abnormal. | 7827| 1300004 | Unauthorized operation. | 7828 7829**示例：** 7830 7831```ts 7832// EntryAbility.ets 7833import { UIAbility } from '@kit.AbilityKit'; 7834import { BusinessError } from '@kit.BasicServicesKit'; 7835import { window } from '@kit.ArkUI'; 7836 7837export default class EntryAbility extends UIAbility { 7838 onWindowStageCreate(windowStage: window.WindowStage): void { 7839 // 加载主窗口对应的页面 7840 windowStage.loadContent('pages/Index', (err) => { 7841 let mainWindow: window.Window | undefined = undefined; 7842 // 获取应用主窗口。 7843 windowStage.getMainWindow().then( 7844 data => { 7845 if (!data) { 7846 console.error('Failed to get main window. Cause: The data is undefined.'); 7847 return; 7848 } 7849 mainWindow = data; 7850 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 7851 // 调用setWindowTitleButtonVisible接口，隐藏主窗标题栏最大化、最小化、关闭按钮。 7852 mainWindow.setWindowTitleButtonVisible(false, false, false); 7853 } 7854 ).catch((err: BusinessError) => { 7855 if(err.code){ 7856 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 7857 } 7858 }); 7859 }); 7860 } 7861} 7862``` 7863 7864## setWindowTopmost<sup>14+</sup> 7865 7866setWindowTopmost(isWindowTopmost: boolean): Promise<void> 7867 7868该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，应用主窗口调用，用于实现将窗口置于其他应用窗口之上不被遮挡，使用Promise异步回调。 7869 7870应用可通过自定义快捷键实现主窗口的置顶和取消置顶。 7871 7872**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 7873 7874**系统能力：** SystemCapability.Window.SessionManager 7875 7876**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 7877 7878**需要权限：** ohos.permission.WINDOW_TOPMOST 7879 7880**参数：** 7881 7882| 参数名 | 类型 | 必填 | 说明 | 7883| --------- | ------- | ---- | --------------------------------------------- | 7884| isWindowTopmost | boolean | 是 | 设置主窗口置顶，true为置顶，false为取消置顶。 | 7885 7886**返回值：** 7887 7888| 类型 | 说明 | 7889| ------------------- | ------------------------- | 7890| Promise<void> | 无返回结果的Promise对象。 | 7891 7892**错误码：** 7893 7894以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7895 7896| 错误码ID | 错误信息 | 7897| -------- | ------------------------------ | 7898| 201 | Permission verification failed. The application does not have the permission required to call the API. | 7899| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7900| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 7901| 1300002 | This window state is abnormal. | 7902| 1300004 | Unauthorized operation. | 7903 7904**示例：** 7905 7906```ts 7907// ets/pages/Index.ets 7908import { window } from '@kit.ArkUI'; 7909import { common } from '@kit.AbilityKit'; 7910import { BusinessError } from '@kit.BasicServicesKit'; 7911 7912let windowClass: window.Window | undefined; 7913let keyUpEventAry: string[] = []; 7914 7915@Entry 7916@Component 7917struct Index { 7918 private context = (this.getUIContext()?.getHostContext() as common.UIAbilityContext); 7919 private windowStage = this.context.windowStage; 7920 7921 build() { 7922 RelativeContainer() { 7923 Button("窗口置顶") 7924 .onClick(() => { 7925 try { 7926 windowClass = this.windowStage.getMainWindowSync(); 7927 // true:窗口置顶，false:取消窗口置顶 7928 let isWindowTopmost: boolean = true; 7929 let promiseTopmost = windowClass.setWindowTopmost(isWindowTopmost); 7930 promiseTopmost.then(() => { 7931 console.info('Succeeded in setting the main window to be topmost.'); 7932 }).catch((err: BusinessError) => { 7933 console.error(`Failed to set the main window to be topmost. Cause code: ${err.code}, message: ${err.message}`); 7934 }); 7935 } catch (exception) { 7936 console.error(`Failed to obtain the top window. Cause code: ${exception.code}, message: ${exception.message}`) 7937 } 7938 }) 7939 } 7940 .height('100%') 7941 .width('100%') 7942 .onKeyEvent((event) => { 7943 if(event) { 7944 if(event.type === KeyType.Down) { 7945 keyUpEventAry = []; 7946 } 7947 if(event.type === KeyType.Up) { 7948 keyUpEventAry.push(event.keyText); 7949 // 自定义快捷键 ctrl+T 执行主窗口置顶、取消置顶的操作 7950 if(windowClass && keyUpEventAry.includes('KEYCODE_CTRL_LEFT') && keyUpEventAry.includes('KEYCODE_T')) { 7951 let isWindowTopmost: boolean = false; 7952 windowClass.setWindowTopmost(isWindowTopmost); 7953 } 7954 } 7955 } 7956 }) 7957 } 7958} 7959``` 7960 7961## raiseToAppTop<sup>14+</sup> 7962 7963raiseToAppTop(): Promise<void> 7964 7965应用子窗口调用，提升应用子窗口到顶层，只在当前应用同一个父窗口下的相同类型子窗范围内生效，对于自定义了zLevel属性的子窗口，只在当前应用同一个父窗口下相同zLevel值的子窗范围内生效。使用Promise异步回调。 7966 7967使用该接口需要先创建子窗口，并确保该子窗口调用[showWindow()](#showwindow9)并执行完毕。 7968 7969**系统能力：** SystemCapability.WindowManager.WindowManager.Core 7970 7971**返回值：** 7972 7973| 类型 | 说明 | 7974| ------------------- | ------------------------- | 7975| Promise<void> | 无返回结果的Promise对象。 | 7976 7977**错误码：** 7978 7979以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 7980 7981| 错误码ID | 错误信息 | 7982| ------- | ------------------------------ | 7983| 1300002 | This window state is abnormal. | 7984| 1300003 | This window manager service works abnormally. | 7985| 1300004 | Unauthorized operation. | 7986| 1300009 | The parent window is invalid. | 7987 7988**示例：** 7989 7990```ts 7991// EntryAbility.ets 7992import { window } from '@kit.ArkUI'; 7993import { UIAbility } from '@kit.AbilityKit'; 7994import { BusinessError } from '@kit.BasicServicesKit'; 7995 7996export default class EntryAbility extends UIAbility { 7997 // ... 7998 onWindowStageCreate(windowStage: window.WindowStage): void { 7999 console.info('onWindowStageCreate'); 8000 // 创建子窗 8001 windowStage.createSubWindow('testSubWindow').then((subWindow) => { 8002 if (subWindow == null) { 8003 console.error('Failed to create the subWindow. Cause: The data is empty'); 8004 return; 8005 } 8006 subWindow.showWindow().then(() => { 8007 subWindow.raiseToAppTop().then(() => { 8008 console.info('Succeeded in raising window to app top'); 8009 }).catch((err: BusinessError)=>{ 8010 console.error(`Failed to raise window to app top. Cause code: ${err.code}, message: ${err.message}`); 8011 }); 8012 }); 8013 }); 8014 } 8015} 8016``` 8017 8018## setRaiseByClickEnabled<sup>14+</sup> 8019 8020setRaiseByClickEnabled(enable: boolean): Promise<void> 8021 8022禁止/使能子窗点击抬升功能。使用Promise异步回调。 8023 8024通常来说，点击一个子窗口，会将该子窗口显示抬升到应用内同一个父窗口下同类型子窗口的最上方，如果设置为false，那么点击子窗口的时候，不会将该子窗口进行抬升，而是保持不变。 8025 8026使用该接口需要先创建子窗口，并确保该子窗口调用[showWindow()](#showwindow9)并执行完毕。 8027 8028**系统能力：** SystemCapability.Window.SessionManager 8029 8030**参数：** 8031 8032| 参数名 | 类型 | 必填 | 说明 | 8033| -------- | ------------------------- | ---- | ---------- | 8034| enable | boolean | 是 | 设置子窗口点击抬升功能是否使能，true表示使能，false表示禁止。 | 8035 8036**返回值：** 8037 8038| 类型 | 说明 | 8039| ------------------- | ------------------------- | 8040| Promise<void> | 无返回结果的Promise对象。 | 8041 8042**错误码：** 8043 8044以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8045 8046| 错误码ID | 错误信息 | 8047| ------- | ------------------------------ | 8048| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8049| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8050| 1300002 | This window state is abnormal. | 8051| 1300003 | This window manager service works abnormally. | 8052| 1300004 | Unauthorized operation. | 8053| 1300009 | The parent window is invalid. | 8054 8055**示例：** 8056 8057```ts 8058// EntryAbility.ets 8059import { window } from '@kit.ArkUI'; 8060import { UIAbility } from '@kit.AbilityKit'; 8061import { BusinessError } from '@kit.BasicServicesKit'; 8062 8063export default class EntryAbility extends UIAbility { 8064 // ... 8065 onWindowStageCreate(windowStage: window.WindowStage): void { 8066 console.info('onWindowStageCreate'); 8067 // 创建子窗 8068 windowStage.createSubWindow("testSubWindow").then((subWindow) => { 8069 if (subWindow == null) { 8070 console.error('Failed to create the subWindow. Cause: The data is empty'); 8071 return; 8072 } 8073 subWindow.showWindow().then(() => { 8074 try { 8075 let enabled = false; 8076 subWindow.setRaiseByClickEnabled(enabled).then(() => { 8077 console.info('Succeeded in disabling the raise-by-click function.'); 8078 }).catch((err: BusinessError) => { 8079 console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`); 8080 }); 8081 } catch (err) { 8082 console.error(`Failed to disable the raise-by-click function. Cause code: ${err.code}, message: ${err.message}`); 8083 } 8084 }); 8085 }); 8086 } 8087} 8088``` 8089 8090## enableLandscapeMultiWindow<sup>12+</sup> 8091 8092enableLandscapeMultiWindow(): Promise<void> 8093 8094应用部分界面支持横向布局时，在进入该界面时使能，使能后可支持进入横向多窗。不建议竖向布局界面使用。 8095 8096此接口只对应用主窗口生效，且需要在module.json5配置文件中[abilities](../../quick-start/module-configuration-file.md#abilities标签)标签中配置preferMultiWindowOrientation属性为"landscape_auto"。 8097 8098**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 8099 8100**系统能力：** SystemCapability.Window.SessionManager 8101 8102**返回值：** 8103 8104| 类型 | 说明 | 8105| ------------------- | ------------------------- | 8106| Promise<void> | 无返回结果的Promise对象。 | 8107 8108**错误码：** 8109 8110以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 8111 8112| 错误码ID | 错误信息 | 8113| ------- | -------------------------------------------- | 8114| 1300002 | This window state is abnormal. | 8115| 1300003 | This window manager service works abnormally. | 8116 8117**示例：** 8118 8119```ts 8120// EntryAbility.ets 8121import { UIAbility } from '@kit.AbilityKit'; 8122import { BusinessError } from '@kit.BasicServicesKit'; 8123import { window } from '@kit.ArkUI'; 8124 8125export default class EntryAbility extends UIAbility { 8126 // ... 8127 onWindowStageCreate(windowStage: window.WindowStage): void { 8128 console.info('onWindowStageCreate'); 8129 let windowClass: window.Window | undefined = undefined; 8130 windowStage.getMainWindow((err: BusinessError, data) => { 8131 const errCode: number = err.code; 8132 if (errCode) { 8133 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8134 return; 8135 } 8136 windowClass = data; 8137 let promise = windowClass.enableLandscapeMultiWindow(); 8138 promise.then(() => { 8139 console.info('Succeeded in making multi-window become landscape.'); 8140 }).catch((err: BusinessError) => { 8141 console.error(`Failed to make multi-window become landscape. Cause code: ${err.code}, message: ${err.message}`); 8142 }); 8143 }); 8144 } 8145} 8146``` 8147 8148## disableLandscapeMultiWindow<sup>12+</sup> 8149 8150disableLandscapeMultiWindow(): Promise<void> 8151 8152应用部分界面支持横向布局时，在退出该界面时去使能，去使能后不支持进入横向多窗。 8153 8154此接口只对应用主窗口生效，且需要在module.json5配置文件中[abilities](../../quick-start/module-configuration-file.md#abilities标签)标签中配置preferMultiWindowOrientation属性为"landscape_auto"。 8155 8156**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 8157 8158**系统能力：** SystemCapability.Window.SessionManager 8159 8160**返回值：** 8161 8162| 类型 | 说明 | 8163| ------------------- | ------------------------- | 8164| Promise<void> | 无返回结果的Promise对象。 | 8165 8166**错误码：** 8167 8168以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。 8169 8170| 错误码ID | 错误信息 | 8171| ------- | -------------------------------------------- | 8172| 1300002 | This window state is abnormal. | 8173| 1300003 | This window manager service works abnormally. | 8174 8175**示例：** 8176 8177```ts 8178// EntryAbility.ets 8179import { UIAbility } from '@kit.AbilityKit'; 8180import { BusinessError } from '@kit.BasicServicesKit'; 8181import { window } from '@kit.ArkUI'; 8182 8183export default class EntryAbility extends UIAbility { 8184 // ... 8185 onWindowStageCreate(windowStage: window.WindowStage): void { 8186 console.info('onWindowStageCreate'); 8187 let windowClass: window.Window | undefined = undefined; 8188 windowStage.getMainWindow((err: BusinessError, data) => { 8189 const errCode: number = err.code; 8190 if (errCode) { 8191 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8192 return; 8193 } 8194 windowClass = data; 8195 let promise = windowClass.disableLandscapeMultiWindow(); 8196 promise.then(() => { 8197 console.info('Succeeded in making multi-window become not landscape.'); 8198 }).catch((err: BusinessError) => { 8199 console.error(`Failed to make multi-window become not landscape. Cause code: ${err.code}, message: ${err.message}`); 8200 }); 8201 }); 8202 } 8203} 8204``` 8205 8206## setDialogBackGestureEnabled<sup>12+</sup> 8207 8208setDialogBackGestureEnabled(enabled: boolean): Promise<void> 8209 8210设置模态窗口是否响应手势返回事件，非模态窗口调用返回错误码。 8211 8212**系统能力**：SystemCapability.Window.SessionManager 8213 8214**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 8215 8216**参数：** 8217 8218| 参数名 | 类型 | 必填 | 说明 | 8219| ---------- | ------- | ---- | ------------------------------------------------------------ | 8220| enabled | boolean | 是 | 是否响应手势返回事件。<br>true表示响应手势返回事件，触发onBackPress回调；false表示不响应手势返回事件，不触发onBackPress回调。</br> | 8221 8222**返回值：** 8223 8224| 类型 | 说明 | 8225| ------------------- | ------------------------- | 8226| Promise<void> | 无返回结果的Promise对象。 | 8227 8228**错误码：** 8229 8230以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8231 8232| 错误码ID | 错误信息 | 8233| ------- | -------------------------------------------- | 8234| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8235| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8236| 1300002 | This window state is abnormal. | 8237| 1300003 | This window manager service works abnormally. | 8238| 1300004 | Unauthorized operation. | 8239 8240**示例：** 8241 8242```ts 8243// EntryAbility.ets 8244import { UIAbility } from '@kit.AbilityKit'; 8245import { BusinessError } from '@kit.BasicServicesKit'; 8246 8247export default class EntryAbility extends UIAbility { 8248 onWindowStageCreate(windowStage: window.WindowStage): void { 8249 console.info('onWindowStageCreate'); 8250 let windowClass: window.Window | undefined = undefined; 8251 let config: window.Configuration = { 8252 name: "test", 8253 windowType: window.WindowType.TYPE_DIALOG, 8254 ctx: this.context 8255 }; 8256 try { 8257 window.createWindow(config, (err: BusinessError, data) => { 8258 const errCode: number = err.code; 8259 if (errCode) { 8260 console.error(`Failed to create the window. Cause code: ${err.code}, message: ${err.message}`); 8261 return; 8262 } 8263 windowClass = data; 8264 windowClass.setUIContent("pages/Index"); 8265 let enabled = true; 8266 let promise = windowClass.setDialogBackGestureEnabled(enabled); 8267 promise.then(() => { 8268 console.info('Succeeded in setting dialog window to respond back gesture.'); 8269 }).catch((err: BusinessError) => { 8270 console.error(`Failed to set dialog window to respond back gesture. Cause code: ${err.code}, message: ${err.message}`); 8271 }); 8272 }); 8273 } catch (exception) { 8274 console.error(`Failed to create the window. Cause code: ${exception.code}, message: ${exception.message}`); 8275 } 8276 } 8277} 8278``` 8279 8280```ts 8281// ets/pages/Index.ets 8282@Entry 8283@Component 8284struct Index { 8285 @State message: string = 'Hello World' 8286 build() { 8287 RelativeContainer() { 8288 Text(this.message) 8289 .id('HelloWorld') 8290 .fontSize(50) 8291 .fontWeight(FontWeight.Bold) 8292 } 8293 .height('100%') 8294 .width('100%') 8295 } 8296 8297 onBackPress(): boolean | void { 8298 console.info('Succeeded in setting dialog window to respond back gesture.'); 8299 return true; 8300 } 8301} 8302``` 8303 8304## enableDrag<sup>20+</sup> 8305 8306enableDrag(enable: boolean): Promise<void> 8307 8308使能/禁止拖拽窗口。使用Promise异步回调。 8309 8310使能后，将允许通过鼠标操作或触摸对窗口进行拉伸操作。 8311 8312仅对手机、平板和2in1设备上的子窗及系统窗口生效，其他设备类型和其他窗口类型调用此接口会报错。 8313 8314**系统能力：** SystemCapability.Window.SessionManager 8315 8316**参数：** 8317 8318| 参数名 | 类型 | 必填 | 说明 | 8319| -------- | ---------------------------- | -- | --------- | 8320| enable| boolean | 是 | 是否允许拖拽。<br>true表示允许，false表示不允许。</br> | 8321 8322**返回值：** 8323 8324| 类型 | 说明 | 8325| ------------------- | ------------------------- | 8326| Promise<void> | 无返回结果的Promise对象。 | 8327 8328**错误码：** 8329 8330以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8331 8332| 错误码ID | 错误信息 | 8333| -------- | -------------------------------------------- | 8334| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8335| 1300002 | This window state is abnormal. | 8336| 1300003 | This window manager service works abnormally. | 8337| 1300004 | Unauthorized operation. | 8338 8339**示例：** 8340 8341```ts 8342import { BusinessError } from '@kit.BasicServicesKit'; 8343 8344try { 8345 windowClass.enableDrag(true).then(() => { 8346 console.info('succeeded in setting window draggable'); 8347 }).catch((err: BusinessError) => { 8348 console.error(`Failed to set window draggable. Cause code: ${err.code}, message: ${err.message}`); 8349 }); 8350} catch (exception) { 8351 console.error(`Failed to set window draggable. Cause code: ${exception.code}, message: ${exception.message}`); 8352} 8353``` 8354 8355## startMoving<sup>14+</sup> 8356 8357startMoving(): Promise<void> 8358 8359开始移动窗口，使用Promise异步回调。 8360 8361仅在[onTouch](./arkui-ts/ts-universal-events-touch.md#touchevent对象说明)事件（其中，事件类型必须为TouchType.Down）的回调方法中调用此接口才会有移动效果，成功调用此接口后，窗口将跟随鼠标或触摸点移动。 8362 8363在点击拖拽场景下，若不期望在按下时触发拖拽事件，则可以在事件类型为[TouchType.Move](./arkui-ts/ts-appendix-enums.md#touchtype)（需要保证当前行为已经触发TouchType.Down事件）时调用此接口，触发移动效果。 8364 8365手机设备上对子窗、系统窗口生效。 8366 8367平板设备非自由多窗模式上对子窗、系统窗口生效；平板设备自由多窗模式上对主窗、子窗和系统窗口生效。 8368 83692in1设备上对主窗、子窗及系统窗口生效。 8370 8371其他设备类型和其它窗口类型调用此接口会报错。 8372 8373**系统能力：** SystemCapability.Window.SessionManager 8374 8375**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 8376 8377**返回值：** 8378 8379| 类型 | 说明 | 8380| ------------------- | ------------------------- | 8381| Promise<void> | 无返回结果的Promise对象。 | 8382 8383**错误码：** 8384 8385以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8386 8387| 错误码ID | 错误信息 | 8388| -------- | -------------------------------------------- | 8389| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8390| 1300001 | Repeated operation. | 8391| 1300002 | This window state is abnormal. | 8392| 1300003 | This window manager service works abnormally. | 8393| 1300004 | Unauthorized operation. | 8394 8395**示例：** 8396 8397```ts 8398// ets/pages/Index.ets 8399import { BusinessError } from '@kit.BasicServicesKit'; 8400 8401@Entry 8402@Component 8403struct Index { 8404 private isTouchDown: boolean = false; 8405 build() { 8406 Row() { 8407 Column() { 8408 Blank('160') 8409 .color(Color.Blue) 8410 .onTouch((event: TouchEvent) => { 8411 if (event.type === TouchType.Down) { 8412 try { 8413 let windowClass: window.Window = window.findWindow("subWindow"); 8414 if (!windowClass) { 8415 console.error('Failed to find window.'); 8416 return; 8417 } 8418 windowClass.startMoving().then(() => { 8419 console.info('Succeeded in starting moving window.') 8420 }).catch((err: BusinessError) => { 8421 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 8422 }); 8423 } catch (exception) { 8424 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 8425 } 8426 } 8427 }) 8428 Blank('160') 8429 .color(Color.Red) 8430 .onTouch((event: TouchEvent) => { 8431 if(event.type == TouchType.Down){ 8432 this.isTouchDown = true; 8433 } else if (event.type === TouchType.Move && this.isTouchDown) { 8434 try { 8435 let context = this.getUIContext()?.getHostContext(); 8436 if (!context) { 8437 console.error('Failed to get host context.'); 8438 return; 8439 } 8440 window.getLastWindow(context).then((data)=>{ 8441 if (!data) { 8442 console.error('Failed to get last window.'); 8443 return; 8444 } 8445 let windowClass: window.Window = data; 8446 windowClass.startMoving().then(() => { 8447 console.info('Succeeded in starting moving window.') 8448 }).catch((err: BusinessError) => { 8449 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 8450 }); 8451 }); 8452 } catch (exception) { 8453 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 8454 } 8455 } else { 8456 this.isTouchDown = false; 8457 } 8458 }) 8459 }.width('100%') 8460 }.height('100%').width('100%') 8461 } 8462} 8463``` 8464 8465## startMoving<sup>15+</sup> 8466 8467startMoving(offsetX: number, offsetY: number): Promise<void> 8468 8469该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于指定鼠标在窗口内的位置并移动窗口，使用Promise异步回调。 8470 8471在同应用内窗口分合后，且鼠标保持按下状态直接移动新窗口，如果此时鼠标快速移动，窗口移动时鼠标可能会在窗口外。可以使用本接口指定窗口移动时鼠标在窗口内的位置，先移动窗口到鼠标位置，再开始移动窗口。 8472 8473仅在[onTouch](./arkui-ts/ts-universal-events-touch.md#touchevent对象说明)事件（其中，事件类型必须为TouchType.Down）的回调方法中调用此接口才会有移动效果，成功调用此接口后，窗口将跟随鼠标移动。 8474 8475在点击拖拽场景下，若不期望在按下时触发拖拽事件，则可以在事件类型为[TouchType.Move](./arkui-ts/ts-appendix-enums.md#touchtype)（需要保证当前行为已经触发TouchType.Down事件）时调用此接口，触发移动效果。 8476 8477**系统能力：** SystemCapability.Window.SessionManager 8478 8479**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 8480 8481**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 8482 8483**参数：** 8484 8485| 参数名 | 类型 | 必填 | 说明 | 8486| --------- | --------- | ------- |----------------------------------------------------| 8487| offsetX | number | 是 | 窗口移动时预期鼠标位置相对窗口左上角的x轴偏移量，单位为px，该参数仅支持整数输入，浮点数向下取整。负值为非法参数，大于窗口宽度为非法参数，窗口宽度可以在窗口属性[WindowProperties](arkts-apis-window-i.md#windowproperties)中获取。 | 8488| offsetY | number | 是 | 窗口移动时预期鼠标位置相对窗口左上角的y轴偏移量，单位为px，该参数仅支持整数输入，浮点数向下取整。负值为非法参数，大于窗口高度为非法参数，窗口高度可以在窗口属性[WindowProperties](arkts-apis-window-i.md#windowproperties)中获取。 | 8489 8490**返回值：** 8491 8492| 类型 | 说明 | 8493| ------------------- |----------------------------| 8494| Promise<void> | 无返回结果的Promise对象。 | 8495 8496**错误码：** 8497 8498以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8499 8500| 错误码ID | 错误信息 | 8501| ---- | -------------------------------------------- | 8502| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8503| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8504| 1300001 | Repeated operation. | 8505| 1300002 | This window state is abnormal. | 8506| 1300003 | This window manager service works abnormally. | 8507| 1300004 | Unauthorized operation. | 8508 8509**示例：** 8510 8511```ts 8512// ets/pages/Index.ets 8513import { BusinessError } from '@kit.BasicServicesKit'; 8514 8515@Entry 8516@Component 8517struct Index { 8518 private isTouchDown: boolean = false; 8519 build() { 8520 Row() { 8521 Column() { 8522 Blank('160') 8523 .color(Color.Blue) 8524 .onTouch((event: TouchEvent) => { 8525 if (event.type === TouchType.Down) { 8526 try { 8527 let windowClass: window.Window = window.findWindow("subWindow"); 8528 if (!windowClass) { 8529 console.error('Failed to find window.'); 8530 return; 8531 } 8532 windowClass.startMoving(100, 50).then(() => { 8533 console.info('Succeeded in starting moving window.') 8534 }).catch((err: BusinessError) => { 8535 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 8536 }); 8537 } catch (exception) { 8538 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 8539 } 8540 } 8541 }) 8542 Blank('160') 8543 .color(Color.Red) 8544 .onTouch((event: TouchEvent) => { 8545 if(event.type == TouchType.Down){ 8546 this.isTouchDown = true; 8547 } else if (event.type === TouchType.Move && this.isTouchDown) { 8548 try { 8549 let context = this.getUIContext()?.getHostContext(); 8550 if (!context) { 8551 console.error('Failed to get host context.'); 8552 return; 8553 } 8554 window.getLastWindow(context).then((data)=>{ 8555 let windowClass: window.Window = data; 8556 windowClass.startMoving(100, 50).then(() => { 8557 console.info('Succeeded in starting moving window.') 8558 }).catch((err: BusinessError) => { 8559 console.error(`Failed to start moving. Cause code: ${err.code}, message: ${err.message}`); 8560 }); 8561 }); 8562 } catch (exception) { 8563 console.error(`Failed to start moving window. Cause code: ${exception.code}, message: ${exception.message}`); 8564 } 8565 } else { 8566 this.isTouchDown = false; 8567 } 8568 }) 8569 }.width('100%') 8570 }.height('100%').width('100%') 8571 } 8572} 8573``` 8574 8575## stopMoving<sup>15+</sup> 8576 8577stopMoving(): Promise<void> 8578 8579该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于在窗口拖拽移动过程中，通过此接口来停止窗口移动，使用Promise异步回调。 8580 8581**系统能力：** SystemCapability.Window.SessionManager 8582 8583**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 8584 8585**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 8586 8587**返回值：** 8588 8589| 类型 | 说明 | 8590| ------------------- | -------------------------| 8591| Promise<void> | 无返回结果的Promise对象。 | 8592 8593**错误码：** 8594 8595以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8596 8597| 错误码ID | 错误信息 | 8598| -------- | -------------------------------------------- | 8599| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8600| 1300002 | This window state is abnormal. | 8601| 1300003 | This window manager service works abnormally. | 8602| 1300004 | Unauthorized operation. | 8603 8604**示例：** 8605 8606```ts 8607// EntryAbility.ets 8608import { UIAbility } from '@kit.AbilityKit'; 8609import { window } from '@kit.ArkUI'; 8610import { BusinessError } from '@kit.BasicServicesKit'; 8611 8612export default class EntryAbility extends UIAbility { 8613 8614 onWindowStageCreate(windowStage: window.WindowStage) { 8615 try { 8616 let windowClass = windowStage.getMainWindowSync(); 8617 windowClass.on('windowRectChange', (data: window.RectChangeOptions) => { 8618 if (data.reason === window.RectChangeReason.MOVE) { 8619 windowClass.stopMoving().then(() => { 8620 console.info('Succeeded in stopping moving window.') 8621 }).catch((err: BusinessError) => { 8622 console.error(`Failed to stop moving. Cause code: ${err.code}, message: ${err.message}`); 8623 }); 8624 } 8625 }); 8626 } catch (exception) { 8627 console.error(`Failed to stop moving window. Cause code: ${exception.code}, message: ${exception.message}`); 8628 } 8629 } 8630} 8631``` 8632 8633## setGestureBackEnabled<sup>13+<sup> 8634 8635setGestureBackEnabled(enabled: boolean): Promise<void> 8636 8637设置当前窗口是否禁用返回手势功能，仅主窗全屏模式下生效，2in1设备下不生效。 8638禁用返回手势功能后，当前应用会禁用手势热区，侧滑返回功能失效；切换到其他应用或者回到桌面后，手势热区恢复，侧滑返回功能正常。 8639开启返回手势功能后，当前应用会恢复手势热区，侧滑返回功能正常。 8640 8641**系统能力：** SystemCapability.Window.SessionManager 8642 8643**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 8644 8645**参数：** 8646 8647| 参数名 | 类型 | 必填 | 说明 | 8648| ---------- | --------- | -------- | --------------------------------------------- | 8649| enabled | boolean | 是 | true时开启返回手势功能，false时禁用返回手势功能。 | 8650 8651**返回值：** 8652 8653| 类型 | 说明 | 8654| ------------------- | ------------------------- | 8655| Promise<void> | 无返回结果的Promise对象。 | 8656 8657**错误码：** 8658 8659以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8660 8661| 错误码ID | 错误信息 | 8662| -------- | ------------------------------------------------------------------------------------------------------------ | 8663| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 8664| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8665| 1300002 | This window state is abnormal. | 8666| 1300003 | This window manager service works abnormally. | 8667| 1300004 | Unauthorized operation. | 8668 8669**示例：** 8670 8671```ts 8672// EntryAbility.ets 8673import { UIAbility } from '@kit.AbilityKit'; 8674import { BusinessError } from '@kit.BasicServicesKit'; 8675import { window } from '@kit.ArkUI'; 8676 8677export default class EntryAbility extends UIAbility { 8678 // ... 8679 onWindowStageCreate(windowStage: window.WindowStage): void { 8680 console.info('onWindowStageCreate'); 8681 let windowClass: window.Window | undefined = undefined; 8682 windowStage.getMainWindow((err: BusinessError, data) => { 8683 const errCode: number = err.code; 8684 if (errCode) { 8685 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8686 return; 8687 } 8688 windowClass = data; 8689 8690 // 设置当前窗口禁用返回手势功能 8691 try { 8692 let gestureBackEnabled: boolean = false; 8693 let promise = windowClass.setGestureBackEnabled(gestureBackEnabled); 8694 promise.then(() => { 8695 console.info(`Succeeded in setting gesture back disabled`); 8696 }).catch((err: BusinessError) => { 8697 console.error(`Failed to set gesture back disabled, Cause code: ${err.code}, message: ${err.message}`); 8698 }); 8699 } catch(exception) { 8700 console.error(`Failed to set gesture back disabled, Cause code: ${exception.code}, message: ${exception.message}`); 8701 } 8702 }); 8703 } 8704} 8705``` 8706 8707## isGestureBackEnabled<sup>13+<sup> 8708 8709isGestureBackEnabled(): boolean 8710 8711获取当前窗口是否禁用返回手势功能，仅主窗全屏模式下生效，2in1设备不生效。 8712 8713**系统能力：** SystemCapability.Window.SessionManager 8714 8715**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 8716 8717**返回值：** 8718 8719| 类型 | 说明 | 8720| ------------------- | --------------------------------------------- | 8721| boolean | 是否已经禁用返回手势。true表示未禁用返回手势功能，false表示已禁用返回手势功能。 | 8722 8723**错误码：** 8724 8725以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8726 8727| 错误码ID | 错误信息 | 8728| -------- | ------------------------------------------------------------------------------------------------------------ | 8729| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8730| 1300002 | This window state is abnormal. | 8731| 1300003 | This window manager service works abnormally. | 8732| 1300004 | Unauthorized operation. | 8733 8734**示例：** 8735 8736```ts 8737// EntryAbility.ets 8738import { UIAbility } from '@kit.AbilityKit'; 8739import { BusinessError } from '@kit.BasicServicesKit'; 8740import { window } from '@kit.ArkUI'; 8741 8742export default class EntryAbility extends UIAbility { 8743 // ... 8744 onWindowStageCreate(windowStage: window.WindowStage): void { 8745 console.info('onWindowStageCreate'); 8746 let windowClass: window.Window | undefined = undefined; 8747 windowStage.getMainWindow((err: BusinessError, data) => { 8748 const errCode: number = err.code; 8749 if (errCode) { 8750 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 8751 return; 8752 } 8753 windowClass = data; 8754 8755 // 获取当前窗口是否禁用返回手势功能 8756 try { 8757 let gestureBackEnabled: boolean = windowClass.isGestureBackEnabled(); 8758 console.info(`Succeeded in obtaining gesture back enabled status: ${gestureBackEnabled}`); 8759 } catch (exception) { 8760 console.error(`Failed to get gesture back enabled status. Cause code: ${exception.code}, message: ${exception.message}`); 8761 } 8762 }); 8763 } 8764} 8765``` 8766 8767## setWindowShadowRadius<sup>17+</sup> 8768 8769setWindowShadowRadius(radius: number): void 8770 8771设置子窗或悬浮窗窗口边缘阴影的模糊半径。 8772 8773**系统能力：** SystemCapability.Window.SessionManager 8774 8775**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 8776 8777**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 8778 8779**参数：** 8780 8781| 参数名 | 类型 | 必填 | 说明 | 8782| ------- | ------ | ---- |-------------------------------------------------------------| 8783| radius | number | 是 | 表示窗口边缘阴影的模糊半径。该参数为浮点数，单位为px，取值范围为[0.0, +∞)，取值为0.0时表示关闭窗口边缘阴影。 | 8784 8785**错误码：** 8786 8787以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8788 8789| 错误码ID | 错误信息 | 8790| ------- | ------------------------------ | 8791| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 8792| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8793| 1300002 | This window state is abnormal. | 8794| 1300004 | Unauthorized operation. | 8795 8796**示例：** 8797 8798```ts 8799try { 8800 windowClass.setWindowShadowRadius(4.0); 8801} catch (exception) { 8802 console.error(`Failed to set shadow. Cause code: ${exception.code}, message: ${exception.message}`); 8803} 8804``` 8805 8806## setWindowCornerRadius<sup>17+</sup> 8807 8808setWindowCornerRadius(cornerRadius: number): Promise<void> 8809 8810设置子窗或悬浮窗的圆角半径值，使用Promise异步回调。 8811 8812圆角半径值过大将会导致三键（最大化、最小化、关闭按钮）位置被裁切，且会导致热区不易识别，请根据窗口大小设置合适的圆角半径值。 8813 8814在调用此接口之前调用[getWindowCornerRadius()](#getwindowcornerradius17)接口可以获得窗口默认圆角半径值。 8815 8816> **说明：** 8817> 8818> - 在API version 20之前，<!--RP6-->此接口仅可在2in1设备下使用。<!--RP6End--> 8819> - 从API version 20开始，此接口支持在手机设备、2in1设备和平板设备下使用。 8820 8821**系统能力**：SystemCapability.Window.SessionManager 8822 8823**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 8824 8825**参数：** 8826 8827| 参数名 | 类型 | 必填 | 说明 | 8828| ----------- | ------- | ---- |----------------------------------------------------| 8829| cornerRadius | number | 是 | 表示窗口圆角的半径值。该参数为浮点数，单位为vp，取值范围为[0.0, +∞)，取值为0.0时表示没有窗口圆角。 | 8830 8831**返回值：** 8832 8833| 类型 | 说明 | 8834| ---------------------- | ------------------------------------------------------------------------------------ | 8835| Promise<void> | 无返回结果的Promise对象。 | 8836 8837**错误码：** 8838 8839以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8840 8841| 错误码ID | 错误信息 | 8842| ------- | ------------------------------ | 8843| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 8844| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8845| 1300002 | This window state is abnormal. | 8846| 1300003 | This window manager service works abnormally. | 8847| 1300004 | Unauthorized operation. | 8848 8849**示例：** 8850 8851```ts 8852import { BusinessError } from '@kit.BasicServicesKit'; 8853 8854try{ 8855 let promise = windowClass.setWindowCornerRadius(1.0); 8856 promise.then(() => { 8857 console.info('Succeeded in setting window corner radius.'); 8858 }).catch((err: BusinessError) => { 8859 console.error(`Failed to set window corner radius. Cause code: ${err.code}, message: ${err.message}`); 8860 }); 8861} catch (exception) { 8862 console.error(`Failed to set corner radius. Cause code: ${exception.code}, message: ${exception.message}`); 8863} 8864 8865``` 8866 8867## getWindowCornerRadius<sup>17+</sup> 8868 8869getWindowCornerRadius(): number 8870 8871该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于获取子窗或悬浮窗的圆角半径值，在未调用[setWindowCornerRadius()](#setwindowcornerradius17)接口设置窗口圆角半径值时，调用此接口可获取窗口默认圆角半径值。 8872 8873**系统能力**：SystemCapability.Window.SessionManager 8874 8875**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 8876 8877**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 8878 8879**返回值：** 8880 8881| 类型 | 说明 | 8882| ---------------------- | ------------------------------------------------------------------------------------ | 8883| number | 当前子窗或悬浮窗的圆角半径值，单位为vp。 | 8884 8885**错误码：** 8886 8887以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8888 8889| 错误码ID | 错误信息 | 8890| ------- | ------------------------------ | 8891| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8892| 1300002 | This window state is abnormal. | 8893| 1300004 | Unauthorized operation. | 8894 8895**示例：** 8896 8897```ts 8898try { 8899 let cornerRadius = windowClass.getWindowCornerRadius(); 8900} catch (exception) { 8901 console.error(`Failed to get corner radius. Cause code: ${exception.code}, message: ${exception.message}`); 8902} 8903``` 8904 8905## setExclusivelyHighlighted<sup>15+<sup> 8906 8907setExclusivelyHighlighted(exclusivelyHighlighted: boolean): Promise<void> 8908 8909设置窗口独占激活态属性。独占激活态表示窗口获焦时，会导致当前父子窗口链中处于激活态的其他窗口失去激活态。使用Promise异步回调。 8910 8911此接口对主窗、模态窗、dialog窗口不生效。 8912 8913**系统能力：** SystemCapability.Window.SessionManager 8914 8915**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 8916 8917**参数：** 8918 8919| 参数名 | 类型 | 必填 | 说明 | 8920| ----------- | ------- | -- | -------------------------------------------------------- | 8921| exclusivelyHighlighted | boolean | 是 | 窗口是否独占激活态。true表示独占激活态；false表示不独占激活态。 | 8922 8923**返回值：** 8924 8925| 类型 | 说明 | 8926| ---------------------- | ------------------------------------------------------------------------------------ | 8927| Promise<void> | 无返回结果的Promise对象。 | 8928 8929**错误码：** 8930 8931以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8932 8933| 错误码ID | 错误信息 | 8934| -------- | ------------------------------------------------------------------------------------------------------------ | 8935| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 8936| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8937| 1300002 | This window state is abnormal. | 8938| 1300003 | This window manager service works abnormally. | 8939| 1300004 | Unauthorized operation. | 8940 8941**示例：** 8942 8943```ts 8944import { BusinessError } from '@kit.BasicServicesKit'; 8945 8946let exclusivelyHighlighted: boolean = true; 8947try { 8948 let promise = windowClass.setExclusivelyHighlighted(exclusivelyHighlighted); 8949 promise.then(() => { 8950 console.info('Succeeded in setting the window to be exclusively highlight.'); 8951 }).catch((err: BusinessError) => { 8952 console.error(`Failed to set the window to be exclusively highlight. Cause code: ${err.code}, message: ${err.message}`); 8953 }); 8954} catch (exception) { 8955 console.error(`Failed to set the window to be exclusively highlight. Cause code: ${exception.code}, message: ${exception.message}`); 8956} 8957``` 8958 8959## isWindowHighlighted<sup>18+<sup> 8960 8961isWindowHighlighted(): boolean 8962 8963获取当前窗口是否为激活态。为准确获取激活态，需要在[WindowEventType](arkts-apis-window-e.md#windoweventtype10)生命周期处于WINDOW_ACTIVE之后调用。 8964 8965可使用[on('windowHighlightChange')](#onwindowhighlightchange15)监听对应状态变更，再执行对应具体业务。 8966 8967**系统能力：** SystemCapability.Window.SessionManager 8968 8969**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8970 8971**返回值：** 8972 8973| 类型 | 说明 | 8974| ------------------- | --------------------------------------------- | 8975| boolean | 当前窗口是否为激活态。true表示当前窗口为激活态，false表示当前窗口非激活态。 | 8976 8977**错误码：** 8978 8979以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 8980 8981| 错误码ID | 错误信息 | 8982| -------- | ------------------------------------------------------------------------------------------------------------ | 8983| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 8984| 1300002 | This window state is abnormal. | 8985 8986**示例：** 8987 8988```ts 8989import { BusinessError } from '@kit.BasicServicesKit'; 8990 8991try { 8992 let isHighlighted = windowClass.isWindowHighlighted(); 8993 console.info(`Succeeded in getting the window highlight status: ${isHighlighted}`); 8994} catch (exception) { 8995 console.error(`Failed to get the window highlight status.. Cause code: ${exception.code}, message: ${exception.message}`); 8996} 8997``` 8998 8999## setFollowParentMultiScreenPolicy<sup>17+<sup> 9000 9001setFollowParentMultiScreenPolicy(enabled: boolean): Promise<void> 9002 9003该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于设置子窗口在其父窗口处于拖拽移动或拖拽缩放过程时，该子窗口是否支持跨多个屏幕同时显示。使用Promise异步回调。 9004 9005通过监听父窗口大小位置变化，对子窗口调用[moveWindowTo()](#movewindowto9)等接口实现子窗口跟随父窗口布局时，此时子窗口默认不支持跨多个屏幕同时显示。 9006 9007对子窗口调用此接口后可以使能子窗口在跟随父窗口布局过程中跨多个屏幕同时显示。 9008 9009**系统能力：** SystemCapability.Window.SessionManager 9010 9011**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常使用，在其他设备中返回801错误码。 9012 9013**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 9014 9015**参数：** 9016 9017| 参数名 | 类型 | 必填 | 说明 | 9018| ----------- | ------- | -- | -------------------------------------------------------- | 9019| enabled | boolean | 是 | 设置子窗口在其父窗口处于拖拽移动或拖拽缩放过程时，该子窗口是否支持跨多个屏幕同时显示。true表示支持；false表示不支持。 | 9020 9021**返回值：** 9022 9023| 类型 | 说明 | 9024| ---------------------- | ------------------------------------------------------------------------------------ | 9025| Promise<void> | 无返回结果的Promise对象。 | 9026 9027**错误码：** 9028 9029以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9030 9031| 错误码ID | 错误信息 | 9032| -------- | ------------------------------------------------------------------------------------------------------------ | 9033| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9034| 801 | Capability not supported.Function setFollowParentMultiScreenPolicy can not work correctly due to limited device capabilities.| 9035| 1300002 | This window state is abnormal. | 9036| 1300003 | This window manager service works abnormally. | 9037| 1300004 | Unauthorized operation. | 9038 9039**示例：** 9040 9041```ts 9042import { BusinessError } from '@kit.BasicServicesKit'; 9043 9044try { 9045 let windowClass: window.Window = window.findWindow("subWindow"); 9046 let enabled: boolean = true; 9047 let promise = windowClass?.setFollowParentMultiScreenPolicy(enabled); 9048 promise.then(() => { 9049 console.info('Succeeded in setting the sub window supports multi-screen simultaneous display') 9050 }).catch((err: BusinessError) => { 9051 console.error(`Failed to set the sub window supports multi-screen simultaneous display. Cause code: ${err.code}, message: ${err.message}`); 9052 }); 9053} catch (exception) { 9054 console.error(`Failed to set the sub window supports multi-screen simultaneous display. Cause code: ${exception.code}, message: ${exception.message}`); 9055} 9056``` 9057 9058## setFollowParentWindowLayoutEnabled<sup>17+</sup> 9059 9060setFollowParentWindowLayoutEnabled(enabled: boolean): Promise<void> 9061 9062设置子窗或模态窗口（即WindowType为TYPE_DIALOG的窗口）的布局信息（position和size）是否跟随主窗，使用Promise异步回调。 9063 90641、只支持主窗的一级子窗或模态窗口使用该接口。 9065 90662、当子窗或模态窗口调用该接口后，立即使其布局信息与主窗完全一致并保持，除非传入false再次调用该接口，否则效果将持续。 9067 90683、当子窗或模态窗口调用该接口后，再调用moveTo、resize等修改布局信息的接口将不生效。 9069 90704、当子窗或模态窗口不再使用该功能后，不保证子窗或模态窗口的布局信息（position和size）为确定的值，需要应用重新进行设置。 9071 9072该接口调用生效后，[setRelativePositionToParentWindowEnabled()](#setrelativepositiontoparentwindowenabled20)接口调用不生效。 9073 9074**模型约束：** 此接口仅可在Stage模型下使用。 9075 9076**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 9077 9078**系统能力：** SystemCapability.Window.SessionManager 9079 9080**参数：** 9081 9082| 参数名 | 类型 | 必填 | 说明 | 9083| --- | --- | --- | --- | 9084| enabled | boolean | 是 | 设置是否启用跟随主窗布局。true表示启用，false表示不启用。| 9085 9086**返回值：** 9087 9088| 类型 | 说明 | 9089| --- | --- | 9090| Promise<void> | 无返回结果的Promise对象。 | 9091 9092**错误码：** 9093 9094以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9095 9096| 错误码ID | 错误信息 | 9097| --- | --- | 9098| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9099| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9100| 1300002 | This window state is abnormal. | 9101| 1300003 | This window manager service works abnormally. | 9102| 1300004 | Unauthorized operation. | 9103 9104**示例：** 9105 9106```ts 9107// EntryAbility.ets 9108import { window } from '@kit.ArkUI'; 9109import { BusinessError } from '@kit.BasicServicesKit'; 9110import { UIAbility } from '@kit.AbilityKit'; 9111 9112export default class EntryAbility extends UIAbility { 9113 onWindowStageCreate(windowStage: window.WindowStage): void { 9114 windowStage.loadContent('pages/Index', (loadError) => { 9115 if (loadError.code) { 9116 console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`); 9117 return; 9118 } 9119 console.info("Succeeded in loading the content."); 9120 windowStage.createSubWindow("subWindow").then((subWindow: window.Window) => { 9121 if (subWindow == null) { 9122 console.error("Failed to create the subWindow. Cause: The data is empty"); 9123 return; 9124 } 9125 subWindow.setFollowParentWindowLayoutEnabled(true).then(() => { 9126 console.info("after set follow parent window layout") 9127 }).catch((error: BusinessError) => { 9128 console.error(`setFollowParentWindowLayoutEnabled failed. ${error.code} ${error.message}`); 9129 }) 9130 }).catch((error: BusinessError) => { 9131 console.error(`createSubWindow failed. ${error.code} ${error.message}`); 9132 }) 9133 }); 9134 } 9135} 9136``` 9137 9138## setRelativePositionToParentWindowEnabled<sup>20+<sup> 9139 9140setRelativePositionToParentWindowEnabled(enabled: boolean, anchor?: WindowAnchor, offsetX?: number, offsetY?: number): Promise<void> 9141 9142该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下生效，用于设置一级子窗是否支持与主窗保持相对位置不变。使用Promise异步回调。 9143 9144该相对位置通过一级子窗与主窗之间锚点的偏移量表示，子窗和主窗使用的窗口锚点相同。 9145 91461、只支持非最大化一级子窗使用该接口。 9147 91482、当子窗调用该接口后，立即使其显示位置跟随主窗并保持相对位置不变，除非传入false再次调用该接口，否则效果将持续。 9149 91503、当子窗调用该接口后，再调用[moveWindowTo()](#movewindowto9)、[maximize()](#maximize12)修改窗口位置或大小的接口将不生效。 9151 9152该接口调用生效后，[setFollowParentWindowLayoutEnabled()](#setfollowparentwindowlayoutenabled17)接口调用不生效。 9153 9154**系统能力：** SystemCapability.Window.SessionManager 9155 9156**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中返回801错误码。 9157 9158**参数：** 9159 9160| 参数名 | 类型 | 必填 | 说明 | 9161| ----------- | ------- | -- | -------------------------------------------------------- | 9162| enabled | boolean | 是 | 一级子窗是否支持与主窗保持相对位置不变。true表示支持；false表示不支持。 | 9163| anchor | [WindowAnchor](arkts-apis-window-e.md#windowanchor20) | 否 | 一级子窗与主窗保持相对位置不变时的窗口锚点枚举。该参数仅在enabled为true时生效，默认值为window.WindowAnchor.TopStart，即默认锚点为窗口左上角。 | 9164| offsetX | number | 否 | 一级子窗锚点与主窗锚点位置的x轴偏移量，单位为px。该参数仅在enabled为true时生效，仅支持整数输入，浮点数向下取整，默认值为0。 | 9165| offsetY | number | 否 | 一级子窗锚点与主窗锚点位置的y轴偏移量，单位为px。该参数仅在enabled为true时生效，仅支持整数输入，浮点数向下取整，默认值为0。 | 9166 9167**返回值：** 9168 9169| 类型 | 说明 | 9170| ---------------------- | ------------------------------------------------ | 9171| Promise<void> | 无返回结果的Promise对象。 | 9172 9173**错误码：** 9174 9175以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9176 9177| 错误码ID | 错误信息 | 9178| -------- | ------------------------------------------------------------------------------------------------------------ | 9179| 801 | Capability not supported.Function setRelativePositionToParentWindowEnabled can not work correctly due to limited device capabilities.| 9180| 1300002 | This window state is abnormal. | 9181| 1300003 | This window manager service works abnormally. | 9182| 1300004 | Unauthorized operation. | 9183| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range. | 9184 9185**示例：** 9186 9187```ts 9188import { window } from '@kit.ArkUI'; 9189import { BusinessError } from '@kit.BasicServicesKit'; 9190import { UIAbility } from '@kit.AbilityKit'; 9191 9192export default class EntryAbility extends UIAbility { 9193 onWindowStageCreate(windowStage: window.WindowStage): void { 9194 windowStage.loadContent('pages/Index', (loadError: BusinessError) => { 9195 if (loadError.code) { 9196 console.error(`Failed to load the content. Cause code: ${loadError.code}, message: ${loadError.message}`); 9197 return; 9198 } 9199 console.info("Succeeded in loading the content."); 9200 windowStage.createSubWindow("subWindow").then((subWindow: window.Window) => { 9201 if (subWindow == null) { 9202 console.error("Failed to create the subWindow. Cause: The data is empty"); 9203 return; 9204 } 9205 subWindow.setRelativePositionToParentWindowEnabled(true).then(() => { 9206 console.info("after set relative position to parent window enabled"); 9207 }).catch((error: BusinessError) => { 9208 console.error(`setRelativePositionToParentWindowEnabled failed. ${error.code} ${error.message}`); 9209 }) 9210 }).catch((error: BusinessError) => { 9211 console.error(`createSubWindow failed. ${error.code} ${error.message}`); 9212 }) 9213 }); 9214 } 9215} 9216``` 9217 9218## setWindowTransitionAnimation<sup>20+</sup> 9219 9220setWindowTransitionAnimation(transitionType: WindowTransitionType, animation: TransitionAnimation): Promise<void> 9221 9222该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)模式下生效，用于给特定场景下的窗口增加转场动画。 9223 9224当前只支持在应用主窗下使用。 9225 9226**模型约束：** 此接口仅可在Stage模型下使用。 9227 9228**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 9229 9230**系统能力：** SystemCapability.Window.SessionManager 9231 9232**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备类型中返回801错误码。 9233 9234**参数：** 9235 9236| 参数名 | 类型 | 必填 | 说明 | 9237| -------------- | ----------------------------------------------- | ---- | -------------------------------------- | 9238| transitionType | [WindowTransitionType](arkts-apis-window-e.md#windowtransitiontype20) | 是 | 本次转场动画场景。当前只支持销毁场景。 | 9239| animation | [TransitionAnimation](arkts-apis-window-i.md#transitionanimation20) | 是 | 本次转场动画配置。 | 9240 9241**返回值：** 9242 9243| 类型 | 说明 | 9244| ------------------- | ------------------------- | 9245| Promise<void> | 无返回结果的Promise对象。 | 9246 9247**错误码：** 9248 9249以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9250 9251| 错误码ID | 错误信息 | 9252| -------- | ------------------------------------------------------------ | 9253| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9254| 1300002 | This window state is abnormal. | 9255| 1300003 | This window manager service works abnormally. | 9256| 1300004 | Unauthorized operation. | 9257| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range; 2. Invalid parameter length. | 9258 9259**示例：** 9260 9261```typescript 9262// EntryAbility.ets 9263import { BusinessError } from '@kit.BasicServicesKit'; 9264import { UIAbility } from '@kit.AbilityKit'; 9265import { window } from '@kit.ArkUI'; 9266 9267export default class EntryAbility extends UIAbility { 9268 // ... 9269 onWindowStageCreate(windowStage: window.WindowStage): void { 9270 console.info('onWindowStageCreate'); 9271 let windowClass: window.Window | undefined = undefined; 9272 windowStage.getMainWindow((err: BusinessError, data) => { 9273 const errCode: number = err.code; 9274 if (errCode) { 9275 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9276 return; 9277 } 9278 windowClass = data; 9279 try { 9280 const animationConfig: window.WindowAnimationConfig = { 9281 duration: 1000, 9282 curve: window.WindowAnimationCurve.LINEAR, 9283 }; 9284 const transitionAnimation: window.TransitionAnimation = { 9285 opacity: 0.5, 9286 config: animationConfig 9287 }; 9288 let promise = windowClass.setWindowTransitionAnimation(window.WindowTransitionType.DESTROY, transitionAnimation); 9289 promise.then((data) => { 9290 console.info('Succeeded in setting window transition animation. Cause:' + JSON.stringify(data)); 9291 }).catch((err: BusinessError) => { 9292 console.error(`Failed to set window transition animation. Cause code: ${err.code}, message: ${err.message}`); 9293 }); 9294 } catch (exception) { 9295 console.error(`Failed to obtain the window status of window. Cause code: ${exception.code}, message: ${exception.message}`); 9296 } 9297 }) 9298 } 9299} 9300``` 9301 9302## getWindowTransitionAnimation<sup>20+</sup> 9303 9304getWindowTransitionAnimation(transitionType: WindowTransitionType): TransitionAnimation | undefined 9305 9306该接口仅在[自由窗口](../../windowmanager/window-terminology.md#自由窗口)模式下生效，用于获取特定场景下的窗口转场动画配置。 9307 9308当前只支持在应用主窗下使用。 9309 9310**模型约束：** 此接口仅可在Stage模型下使用。 9311 9312**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 9313 9314**系统能力：** SystemCapability.Window.SessionManager 9315 9316**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备类型中返回801错误码。 9317 9318**参数：** 9319 9320| 参数名 | 类型 | 必填 | 说明 | 9321| -------------- | ----------------------------------------------- | ---- | -------------------------------------- | 9322| transitionType | [WindowTransitionType](arkts-apis-window-e.md#windowtransitiontype20) | 是 | 本次转场动画场景。当前只支持销毁场景。 | 9323 9324**返回值：** 9325 9326| 类型 | 说明 | 9327| --------------------------------------------- | -------------------------- | 9328| [TransitionAnimation](arkts-apis-window-i.md#transitionanimation20) \| undefined | 对应场景下的转场动画配置。当未使用过[setWindowTransitionAnimation](#setwindowtransitionanimation20)接口时，返回undefined。| 9329 9330**错误码：** 9331 9332以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9333 9334| 错误码ID | 错误信息 | 9335| -------- | ------------------------------------------------------------ | 9336| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9337| 1300002 | This window state is abnormal. | 9338| 1300003 | This window manager service works abnormally. | 9339| 1300004 | Unauthorized operation. | 9340| 1300016 | Parameter error. Possible cause: 1. Invalid parameter range. | 9341 9342**示例：** 9343 9344```typescript 9345// EntryAbility.ets 9346import { BusinessError } from '@kit.BasicServicesKit'; 9347import { UIAbility } from '@kit.AbilityKit'; 9348import { window } from '@kit.ArkUI'; 9349 9350export default class EntryAbility extends UIAbility { 9351 // ... 9352 onWindowStageCreate(windowStage: window.WindowStage): void { 9353 console.info('onWindowStageCreate'); 9354 let windowClass: window.Window | undefined = undefined; 9355 windowStage.getMainWindow((err: BusinessError, data) => { 9356 const errCode: number = err.code; 9357 if (errCode) { 9358 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9359 return; 9360 } 9361 windowClass = data; 9362 try { 9363 let transitionAnimationResult = windowClass.getWindowTransitionAnimation(window.WindowTransitionType.DESTROY); 9364 console.info('Succeeded in getting window transition animation: ' + JSON.stringify(transitionAnimationResult)); 9365 } catch (exception) { 9366 console.error(`Failed to obtain the window transition animation. Cause code: ${exception.code}, message: ${exception.message}`); 9367 } 9368 }) 9369 } 9370} 9371``` 9372 9373## setSubWindowZLevel<sup>18+</sup> 9374 9375setSubWindowZLevel(zLevel: number): Promise<void> 9376 9377设置当前子窗口层级级别，设置了模态属性的子窗不支持。使用Promise异步回调。 9378 9379通过该接口改变子窗口的显示层级时，不会发生焦点切换。推荐使用[shiftAppWindowFocus()](arkts-apis-window-f.md#windowshiftappwindowfocus11)进行焦点切换。 9380 9381**系统能力：** SystemCapability.Window.SessionManager 9382 9383**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 9384 9385**参数：** 9386 9387| 参数名 | 类型 | 必填 | 说明 | 9388| :----------- | :---------------------------- | :--- | :----------------------------- | 9389| zLevel | number | 是 | 子窗口层级级别。默认值为0，取值范围为[-10000, 10000]，该参数仅支持整数输入，浮点数输入将向下取整。 | 9390 9391**返回值：** 9392 9393| 类型 | 说明 | 9394| ------------------- | ------------------------- | 9395| Promise<void> | 无返回结果的Promise对象。 | 9396 9397**错误码：** 9398 9399以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9400 9401| 错误码ID | 错误信息 | 9402| ------- | --------------------------------------------- | 9403| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 9404| 801 | Capability not supported. Function setSubWindowZLevel can not work correctly due to limited device capabilities. | 9405| 1300002 | This window state is abnormal. | 9406| 1300003 | This window manager service works abnormally. | 9407| 1300004 | Unauthorized operation. | 9408| 1300009 | The parent window is invalid. | 9409 9410**示例：** 9411 9412```ts 9413// EntryAbility.ets 9414import { window } from '@kit.ArkUI'; 9415import { UIAbility } from '@kit.AbilityKit'; 9416import { BusinessError } from '@kit.BasicServicesKit'; 9417 9418export default class EntryAbility extends UIAbility { 9419 // ... 9420 onWindowStageCreate(windowStage: window.WindowStage): void { 9421 console.info('onWindowStageCreate'); 9422 let zLevel: number = 1; 9423 // 创建子窗 9424 try { 9425 windowStage.createSubWindow('testSubWindow').then((subWindow) => { 9426 if (subWindow == null) { 9427 console.error('Failed to create the sub window. Cause: The sub window is null'); 9428 return; 9429 } 9430 subWindow.setSubWindowZLevel(zLevel).then(() => { 9431 console.info('Succeeded in setting sub window zLevel.'); 9432 }).catch((err: BusinessError) => { 9433 console.error(`Failed to set sub window zLevel. Cause code: ${err.code}, message: ${err.message}`); 9434 }); 9435 }); 9436 } catch (err) { 9437 console.error(`Failed to create the sub window or set zLevel. Cause code: ${err.code}, message: ${err.message}`); 9438 } 9439 } 9440} 9441``` 9442 9443## getSubWindowZLevel<sup>18+</sup> 9444 9445getSubWindowZLevel(): number 9446 9447获取当前子窗口层级级别。不支持主窗、系统窗调用。 9448 9449**系统能力：** SystemCapability.Window.SessionManager 9450 9451**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 9452 9453**返回值：** 9454 9455| 类型 | 说明 | 9456| ------------------- | --------------------------------------------- | 9457| number | 当前子窗口层级级别。 | 9458 9459**错误码：** 9460 9461以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9462 9463| 错误码ID | 错误信息 | 9464| -------- | ------------------------------------------------------------------------------------------------------------ | 9465| 801 | Capability not supported. Function getSubWindowZLevel can not work correctly due to limited device capabilities. | 9466| 1300002 | This window state is abnormal. | 9467| 1300004 | Unauthorized operation. | 9468 9469**示例：** 9470 9471```ts 9472// EntryAbility.ets 9473import { window } from '@kit.ArkUI'; 9474import { UIAbility } from '@kit.AbilityKit'; 9475 9476export default class EntryAbility extends UIAbility { 9477 // ... 9478 onWindowStageCreate(windowStage: window.WindowStage): void { 9479 console.info('onWindowStageCreate'); 9480 let subWindowZLevel = -1; 9481 // 创建子窗 9482 windowStage.createSubWindow('testSubWindow').then((subWindow) => { 9483 if (subWindow == null) { 9484 console.error('Failed to create the sub window. Cause: The sub window is null'); 9485 return; 9486 } 9487 try { 9488 subWindowZLevel = subWindow.getSubWindowZLevel(); 9489 console.info(`Succeeded in obtaining sub window zLevel: ${subWindowZLevel}`); 9490 } catch (err) { 9491 console.error(`Failed to obtain the sub window zLevel. Cause code: ${err.code}, message: ${err.message}`); 9492 } 9493 }); 9494 } 9495} 9496``` 9497 9498 9499## setWindowSystemBarProperties<sup>(deprecated)</sup> 9500 9501setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 9502 9503设置主窗口<!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性，使用callback异步回调，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 9504 9505子窗口调用后不生效。 9506 9507> **说明：** 9508> 9509> 从API version 9开始支持，从API version 12开始废弃，推荐使用Promise方式的[setWindowSystemBarProperties](#setwindowsystembarproperties9)。 9510 9511**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9512 9513**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 9514 9515**参数：** 9516 9517| 参数名 | 类型 | 必填 | 说明 | 9518| ------------------- | ------------------------------------------- | ---- | ---------------------- | 9519| systemBarProperties | [SystemBarProperties](arkts-apis-window-i.md#systembarproperties) | 是 | <!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性。 | 9520| callback | AsyncCallback<void> | 是 | 回调函数。 | 9521 9522**错误码：** 9523 9524以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9525 9526| 错误码ID | 错误信息 | 9527| -------- | ------------------------------------------------------------------------------------------------------------ | 9528| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9529| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 9530| 1300002 | This window state is abnormal. | 9531| 1300003 | This window manager service works abnormally. | 9532 9533**示例：** 9534 9535```ts 9536// EntryAbility.ets 9537import { UIAbility } from '@kit.AbilityKit'; 9538import { BusinessError } from '@kit.BasicServicesKit'; 9539 9540export default class EntryAbility extends UIAbility { 9541 // ... 9542 onWindowStageCreate(windowStage: window.WindowStage): void { 9543 console.info('onWindowStageCreate'); 9544 let windowClass: window.Window | undefined = undefined; 9545 windowStage.getMainWindow((err: BusinessError, data) => { 9546 const errCode: number = err.code; 9547 if (errCode) { 9548 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9549 return; 9550 } 9551 windowClass = data; 9552 let SystemBarProperties: window.SystemBarProperties = { 9553 statusBarColor: '#ff00ff', 9554 navigationBarColor: '#00ff00', 9555 //以下两个属性从API Version8开始支持 9556 statusBarContentColor: '#ffffff', 9557 navigationBarContentColor: '#00ffff' 9558 }; 9559 try { 9560 windowClass.setWindowSystemBarProperties(SystemBarProperties, (err: BusinessError) => { 9561 const errCode: number = err.code; 9562 if (errCode) { 9563 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 9564 return; 9565 } 9566 console.info('Succeeded in setting the system bar properties.'); 9567 }); 9568 } catch (exception) { 9569 console.error(`Failed to set the system bar properties. Cause code: ${exception.code}, message: ${exception.message}`); 9570 } 9571 }); 9572 } 9573} 9574``` 9575 9576## setWindowSystemBarEnable<sup>(deprecated)</sup> 9577 9578setWindowSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 9579 9580<!--RP14-->设置主窗口状态栏、三键导航栏的可见模式，状态栏通过status控制、三键导航栏通过navigation控制<!--RP14End-->，使用callback异步回调。<br>从API version 12开始，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 9581 9582调用生效后返回并不表示状态栏和<!--RP15-->三键导航栏<!--RP15End-->的显示或隐藏已完成。子窗口调用后不生效。非全屏模式（悬浮窗、分屏等场景）下配置不生效。 9583 9584> **说明：** 9585> 9586> 从API version 9开始支持，从API version 12开始废弃，推荐使用Promise方式的[setWindowSystemBarEnable](#setwindowsystembarenable9)。 9587 9588**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 9589 9590**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9591 9592**参数：** 9593 9594| 参数名 | 类型 | 必填 | 说明 | 9595| -------- | ----------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------- | 9596| names | Array<'status'\|'navigation'> | 是 | 设置窗口全屏模式时状态栏和<!--RP15-->三键导航栏<!--RP15End-->是否显示。<br>例如，需全部显示，该参数设置为['status', 'navigation']；设置为[]，则不显示。 | 9597| callback | AsyncCallback<void> | 是 | 回调函数。 | 9598 9599**错误码：** 9600 9601以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9602 9603| 错误码ID | 错误信息 | 9604| -------- | ------------------------------------------------------------------------------------------------------------ | 9605| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9606| 1300002 | This window state is abnormal. | 9607| 1300003 | This window manager service works abnormally. | 9608 9609**示例：** 9610 9611```ts 9612// 此处以状态栏等均不显示为例 9613// EntryAbility.ets 9614import { UIAbility } from '@kit.AbilityKit'; 9615import { BusinessError } from '@kit.BasicServicesKit'; 9616 9617export default class EntryAbility extends UIAbility { 9618 // ... 9619 onWindowStageCreate(windowStage: window.WindowStage): void { 9620 console.info('onWindowStageCreate'); 9621 let windowClass: window.Window | undefined = undefined; 9622 windowStage.getMainWindow((err: BusinessError, data) => { 9623 const errCode: number = err.code; 9624 if (errCode) { 9625 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9626 return; 9627 } 9628 windowClass = data; 9629 let names: Array<'status' | 'navigation'> = []; 9630 try { 9631 windowClass.setWindowSystemBarEnable(names, (err: BusinessError) => { 9632 const errCode: number = err.code; 9633 if (errCode) { 9634 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 9635 return; 9636 } 9637 console.info('Succeeded in setting the system bar to be invisible.'); 9638 }); 9639 } catch (exception) { 9640 console.error(`Failed to set the system bar to be invisible. Cause code: ${exception.code}, message: ${exception.message}`); 9641 } 9642 }); 9643 } 9644} 9645``` 9646 9647## setWindowLayoutFullScreen<sup>(deprecated)</sup> 9648 9649setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 9650 9651设置主窗口或子窗口的布局是否为沉浸式布局，使用callback异步回调。系统窗口调用不生效。 9652沉浸式布局生效时，布局不避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件可能产生与其重叠的情况。 9653非沉浸式布局生效时，布局避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件不会与其重叠。 9654 9655> **说明：** 9656> 9657> 从API version 9开始支持，从API version 12开始废弃，推荐使用Promise方式的[setWindowLayoutFullScreen](#setwindowlayoutfullscreen9)。 9658 9659**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9660 9661**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 9662 9663**设备行为差异：** API version 14之前，该接口在所有设备中可正常调用。从API version 14开始，该接口在2in1设备、Tablet设备的[自由多窗模式](../../windowmanager/window-terminology.md#自由多窗模式)下调用不生效也不报错，在其他设备中可正常调用。 9664 9665**参数：** 9666 9667| 参数名 | 类型 | 必填 | 说明 | 9668| ------------------ | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------- | 9669| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局（该沉浸式布局状态栏、<!--RP15-->三键导航栏<!--RP15End-->仍然显示）。true表示沉浸式布局；false表示非沉浸式布局。 | 9670| callback | AsyncCallback<void> | 是 | 回调函数。 | 9671 9672**错误码：** 9673 9674以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[窗口错误码](errorcode-window.md)。 9675 9676| 错误码ID | 错误信息 | 9677| -------- | ------------------------------------------------------------------------------------------------------------ | 9678| 401 | Parameter error. Possible cause: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 9679| 1300002 | This window state is abnormal. | 9680| 1300003 | This window manager service works abnormally. | 9681 9682**示例：** 9683 9684```ts 9685// EntryAbility.ets 9686import { UIAbility } from '@kit.AbilityKit'; 9687import { BusinessError } from '@kit.BasicServicesKit'; 9688 9689export default class EntryAbility extends UIAbility { 9690 // ... 9691 onWindowStageCreate(windowStage: window.WindowStage): void { 9692 console.info('onWindowStageCreate'); 9693 let windowClass: window.Window | undefined = undefined; 9694 windowStage.getMainWindow((err: BusinessError, data) => { 9695 const errCode: number = err.code; 9696 if (errCode) { 9697 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 9698 return; 9699 } 9700 windowClass = data; 9701 let isLayoutFullScreen = true; 9702 try { 9703 windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 9704 const errCode: number = err.code; 9705 if (errCode) { 9706 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 9707 return; 9708 } 9709 console.info('Succeeded in setting the window layout to full-screen mode.'); 9710 }); 9711 } catch (exception) { 9712 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`); 9713 } 9714 }); 9715 } 9716} 9717``` 9718 9719## show<sup>(deprecated)</sup> 9720 9721show(callback: AsyncCallback<void>): void 9722 9723显示当前窗口，使用callback异步回调。 9724 9725> **说明：** 9726> 9727> 从API version 7开始支持，从API version 9开始废弃，推荐使用[showWindow()](#showwindow9)。 9728 9729**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9730 9731**参数：** 9732 9733| 参数名 | 类型 | 必填 | 说明 | 9734| -------- | ------------------------- | ---- | ---------- | 9735| callback | AsyncCallback<void> | 是 | 回调函数。 | 9736 9737**示例：** 9738 9739```ts 9740import { BusinessError } from '@kit.BasicServicesKit'; 9741 9742windowClass.show((err: BusinessError) => { 9743 const errCode: number = err.code; 9744 if (errCode) { 9745 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 9746 return; 9747 } 9748 console.info('Succeeded in showing the window.'); 9749}); 9750``` 9751 9752## show<sup>(deprecated)</sup> 9753 9754show(): Promise<void> 9755 9756显示当前窗口，使用Promise异步回调。 9757 9758> **说明：** 9759> 9760> 从API version 7开始支持，从API version 9开始废弃，推荐使用[showWindow()](#showwindow9-1)。 9761 9762**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9763 9764**返回值：** 9765 9766| 类型 | 说明 | 9767| ------------------- | ------------------------- | 9768| Promise<void> | 无返回结果的Promise对象。 | 9769 9770**示例：** 9771 9772```ts 9773import { BusinessError } from '@kit.BasicServicesKit'; 9774 9775let promise = windowClass.show(); 9776promise.then(() => { 9777 console.info('Succeeded in showing the window.'); 9778}).catch((err: BusinessError) => { 9779 console.error(`Failed to show the window. Cause code: ${err.code}, message: ${err.message}`); 9780}); 9781``` 9782 9783## destroy<sup>(deprecated)</sup> 9784 9785destroy(callback: AsyncCallback<void>): void 9786 9787销毁当前窗口，使用callback异步回调。 9788 9789> **说明：** 9790> 9791> 从API version 7开始支持，从API version 9开始废弃，推荐使用[destroyWindow()](#destroywindow9)。 9792 9793**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9794 9795**参数：** 9796 9797| 参数名 | 类型 | 必填 | 说明 | 9798| -------- | ------------------------- | ---- | ---------- | 9799| callback | AsyncCallback<void> | 是 | 回调函数。 | 9800 9801**示例：** 9802 9803```ts 9804import { BusinessError } from '@kit.BasicServicesKit'; 9805 9806windowClass.destroy((err: BusinessError) => { 9807 const errCode: number = err.code; 9808 if (err.code) { 9809 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 9810 return; 9811 } 9812 console.info('Succeeded in destroying the window.'); 9813}); 9814``` 9815 9816## destroy<sup>(deprecated)</sup> 9817 9818destroy(): Promise<void> 9819 9820销毁当前窗口，使用Promise异步回调。 9821 9822> **说明：** 9823> 9824> 从API version 7开始支持，从API version 9开始废弃，推荐使用[destroyWindow()](#destroywindow9-1)。 9825 9826**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9827 9828**返回值：** 9829 9830| 类型 | 说明 | 9831| ------------------- | ------------------------- | 9832| Promise<void> | 无返回结果的Promise对象。 | 9833 9834**示例：** 9835 9836```ts 9837import { BusinessError } from '@kit.BasicServicesKit'; 9838 9839let promise = windowClass.destroy(); 9840promise.then(() => { 9841 console.info('Succeeded in destroying the window.'); 9842}).catch((err: BusinessError) => { 9843 console.error(`Failed to destroy the window. Cause code: ${err.code}, message: ${err.message}`); 9844}); 9845``` 9846 9847## moveTo<sup>(deprecated)</sup> 9848 9849moveTo(x: number, y: number, callback: AsyncCallback<void>): void 9850 9851移动窗口位置，使用callback异步回调。 9852 9853全屏模式窗口不支持该操作。 9854 9855> **说明：** 9856> 9857> 从API version 7开始支持，从API version 9开始废弃，推荐使用[moveWindowTo()](#movewindowto9)。 9858 9859**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9860 9861**参数：** 9862 9863| 参数名 | 类型 | 必填 | 说明 | 9864| -------- | ------------------------- | ---- | ------------------------------------------------- | 9865| x | number | 是 | 窗口在x轴方向移动到的坐标位置，单位为px，值为正表示位置在x轴右侧；值为负表示位置在x轴左侧；值为0表示位置在x轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 9866| y | number | 是 | 窗口在y轴方向移动到的坐标位置，单位为px，值为正表示位置在y轴下侧；值为负表示位置在y轴上侧；值为0表示位置在x轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 9867| callback | AsyncCallback<void> | 是 | 回调函数。 | 9868 9869**示例：** 9870 9871```ts 9872import { BusinessError } from '@kit.BasicServicesKit'; 9873 9874windowClass.moveTo(300, 300, (err: BusinessError) => { 9875 const errCode: number = err.code; 9876 if (errCode) { 9877 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 9878 return; 9879 } 9880 console.info('Succeeded in moving the window.'); 9881}); 9882``` 9883 9884## moveTo<sup>(deprecated)</sup> 9885 9886moveTo(x: number, y: number): Promise<void> 9887 9888移动窗口位置，使用Promise异步回调。 9889 9890全屏模式窗口不支持该操作。 9891 9892> **说明：** 9893> 9894> 从API version 7开始支持，从API version 9开始废弃，推荐使用[moveWindowTo()](#movewindowto9-1)。 9895 9896**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9897 9898**参数：** 9899 9900| 参数名 | 类型 | 必填 | 说明 | 9901| ------ | ------ | ---- | ------------------------------------------------- | 9902| x | number | 是 | 窗口在x轴方向移动到的坐标位置，单位为px，值为正表示位置在x轴右侧；值为负表示位置在x轴左侧；值为0表示位置在x轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 9903| y | number | 是 | 窗口在y轴方向移动到的坐标位置，单位为px，值为正表示位置在y轴下侧；值为负表示位置在y轴上侧；值为0表示位置在y轴坐标原点。该参数仅支持整数输入，浮点数输入将向下取整。 | 9904 9905**返回值：** 9906 9907| 类型 | 说明 | 9908| ------------------- | ------------------------- | 9909| Promise<void> | 无返回结果的Promise对象。 | 9910 9911**示例：** 9912 9913```ts 9914import { BusinessError } from '@kit.BasicServicesKit'; 9915 9916let promise = windowClass.moveTo(300, 300); 9917promise.then(() => { 9918 console.info('Succeeded in moving the window.'); 9919}).catch((err: BusinessError) => { 9920 console.error(`Failed to move the window. Cause code: ${err.code}, message: ${err.message}`); 9921}); 9922``` 9923 9924## resetSize<sup>(deprecated)</sup> 9925 9926resetSize(width: number, height: number, callback: AsyncCallback<void>): void 9927 9928改变当前窗口大小，使用callback异步回调。 9929 9930应用主窗口与子窗口存在大小限制，默认宽度范围：[320, 1920]，默认高度范围：[240, 1920]，单位为vp。 9931应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置，配置后的最小宽度与最小高度以产品段配置值为准，具体尺寸限制范围可以通过[getWindowLimits](#getwindowlimits11)接口进行查询。 9932 9933系统窗口存在大小限制，宽度范围：(0, 1920]，高度范围：(0, 1920]，单位为vp。 9934 9935设置的宽度与高度受到此约束限制，规则： 9936若所设置的窗口宽/高尺寸小于窗口最小宽/高限值，则窗口最小宽/高限值生效； 9937若所设置的窗口宽/高尺寸大于窗口最大宽/高限值，则窗口最大宽/高限值生效。 9938 9939全屏模式窗口不支持该操作。 9940 9941> **说明：** 9942> 9943> 从API version 7开始支持，从API version 9开始废弃，推荐使用[resize()](#resize9)。 9944 9945**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9946 9947**参数：** 9948 9949| 参数名 | 类型 | 必填 | 说明 | 9950| -------- | ------------------------- | ---- | -------------------------- | 9951| width | number | 是 | 目标窗口的宽度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 9952| height | number | 是 | 目标窗口的高度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 9953| callback | AsyncCallback<void> | 是 | 回调函数。 | 9954 9955**示例：** 9956 9957```ts 9958import { BusinessError } from '@kit.BasicServicesKit'; 9959 9960windowClass.resetSize(500, 1000, (err: BusinessError) => { 9961 const errCode: number = err.code; 9962 if (errCode) { 9963 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 9964 return; 9965 } 9966 console.info('Succeeded in changing the window size.'); 9967}); 9968``` 9969 9970## resetSize<sup>(deprecated)</sup> 9971 9972resetSize(width: number, height: number): Promise<void> 9973 9974改变当前窗口大小，使用Promise异步回调。 9975 9976应用主窗口与子窗口存在大小限制，默认宽度范围：[320, 1920]，默认高度范围：[240, 1920]，单位为vp。 9977应用主窗口与子窗口的最小宽度与最小高度可由产品端进行配置，配置后的最小宽度与最小高度以产品段配置值为准，具体尺寸限制范围可以通过[getWindowLimits](#getwindowlimits11)接口进行查询。 9978 9979系统窗口存在大小限制，宽度范围：(0, 1920]，高度范围：(0, 1920]，单位为vp。 9980 9981设置的宽度与高度受到此约束限制，规则： 9982若所设置的窗口宽/高尺寸小于窗口最小宽/高限值，则窗口最小宽/高限值生效； 9983若所设置的窗口宽/高尺寸大于窗口最大宽/高限值，则窗口最大宽/高限值生效。 9984 9985全屏模式窗口不支持该操作。 9986 9987> **说明：** 9988> 9989> 从API version 7开始支持，从API version 9开始废弃，推荐使用[resize()](#resize9-1)。 9990 9991**系统能力：** SystemCapability.WindowManager.WindowManager.Core 9992 9993**参数：** 9994 9995| 参数名 | 类型 | 必填 | 说明 | 9996| ------ | ------ | ---- | -------------------------- | 9997| width | number | 是 | 目标窗口的宽度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 9998| height | number | 是 | 目标窗口的高度，单位为px，该参数仅支持整数输入，浮点数输入将向下取整，负值为非法参数。 | 9999 10000**返回值：** 10001 10002| 类型 | 说明 | 10003| ------------------- | ------------------------- | 10004| Promise<void> | 无返回结果的Promise对象。 | 10005 10006**示例：** 10007 10008```ts 10009import { BusinessError } from '@kit.BasicServicesKit'; 10010 10011let promise = windowClass.resetSize(500, 1000); 10012promise.then(() => { 10013 console.info('Succeeded in changing the window size.'); 10014}).catch((err: BusinessError) => { 10015 console.error(`Failed to change the window size. Cause code: ${err.code}, message: ${err.message}`); 10016}); 10017``` 10018 10019## getProperties<sup>(deprecated)</sup> 10020 10021getProperties(callback: AsyncCallback<WindowProperties>): void 10022 10023获取当前窗口的属性，使用callback异步回调，返回WindowProperties。 10024 10025> **说明：** 10026> 10027> 从API version 6开始支持，从API version 9开始废弃，推荐使用[getWindowProperties()](#getwindowproperties9)。 10028 10029**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10030 10031**参数：** 10032 10033| 参数名 | 类型 | 必填 | 说明 | 10034| -------- | ---------------------------------------------------------- | ---- | ---------------------------- | 10035| callback | AsyncCallback<[WindowProperties](arkts-apis-window-i.md#windowproperties)> | 是 | 回调函数。返回当前窗口属性。 | 10036 10037**示例：** 10038 10039```ts 10040import { BusinessError } from '@kit.BasicServicesKit'; 10041 10042windowClass.getProperties((err: BusinessError, data) => { 10043 const errCode: number = err.code; 10044 if (errCode) { 10045 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 10046 return; 10047 } 10048 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 10049}); 10050``` 10051 10052## getProperties<sup>(deprecated)</sup> 10053 10054getProperties(): Promise<WindowProperties> 10055 10056获取当前窗口的属性，使用Promise异步回调，返回WindowProperties。 10057 10058> **说明：** 10059> 10060> 从API version 6开始支持，从API version 9开始废弃，推荐使用[getWindowProperties()](#getwindowproperties9)。 10061 10062**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10063 10064**返回值：** 10065 10066| 类型 | 说明 | 10067| ---------------------------------------------------- | ------------------------------- | 10068| Promise<[WindowProperties](arkts-apis-window-i.md#windowproperties)> | Promise对象。返回当前窗口属性。 | 10069 10070**示例：** 10071 10072```ts 10073import { BusinessError } from '@kit.BasicServicesKit'; 10074 10075let promise = windowClass.getProperties(); 10076promise.then((data) => { 10077 console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); 10078}).catch((err: BusinessError) => { 10079 console.error(`Failed to obtain the window properties. Cause code: ${err.code}, message: ${err.message}`); 10080}); 10081``` 10082 10083## getAvoidArea<sup>(deprecated)</sup> 10084 10085getAvoidArea(type: [AvoidAreaType](arkts-apis-window-e.md#avoidareatype7), callback: AsyncCallback<[AvoidArea](arkts-apis-window-i.md#avoidarea7)>): void 10086 10087获取当前窗口内容规避的区域；如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时，需要窗口内容避让的区域。 10088 10089[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，当前窗口调用该接口获取到空的避让区。 10090 10091非自由窗口状态下，仅当子窗口的位置和大小与主窗口一致时，子窗口调用该接口才能计算避让区并返回，否则直接返回空的避让区。 10092 10093> **说明：** 10094> 10095> 从API version 7开始支持，从API version 9开始废弃，推荐使用[getWindowAvoidArea()](#getwindowavoidarea9)。 10096 10097**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10098 10099**参数：** 10100 10101| 参数名 | 类型 | 必填 | 说明 | 10102| -------- |-----------------------------------------------| ---- | ------------------------------------------------------------ | 10103| type | [AvoidAreaType](arkts-apis-window-e.md#avoidareatype7) | 是 | 表示规避区类型。| 10104| callback | AsyncCallback<[AvoidArea](arkts-apis-window-i.md#avoidarea7)> | 是 | 回调函数。返回窗口内容规避区域。 | 10105 10106**示例：** 10107 10108```ts 10109import { BusinessError } from '@kit.BasicServicesKit'; 10110 10111let type = window.AvoidAreaType.TYPE_SYSTEM; 10112windowClass.getAvoidArea(type, (err: BusinessError, data) => { 10113 const errCode: number = err.code; 10114 if (errCode) { 10115 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 10116 return; 10117 } 10118 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 10119}); 10120``` 10121 10122## getAvoidArea<sup>(deprecated)</sup> 10123 10124getAvoidArea(type: [AvoidAreaType](arkts-apis-window-e.md#avoidareatype7)): Promise<[AvoidArea](arkts-apis-window-i.md#avoidarea7)> 10125 10126获取当前窗口内容规避的区域；如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时，需要窗口内容避让的区域。 10127 10128[自由窗口](../../windowmanager/window-terminology.md#自由窗口)状态下，当前窗口调用该接口获取到空的避让区。 10129 10130非自由窗口状态下，仅当子窗口的位置和大小与主窗口一致时，子窗口调用该接口才能计算避让区并返回，否则直接返回空的避让区。 10131 10132> **说明：** 10133> 10134> 从API version 7开始支持，从API version 9开始废弃，推荐使用[getWindowAvoidArea()](#getwindowavoidarea9)。 10135 10136**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10137 10138**参数：** 10139 10140| 参数名 | 类型 | 必填 | 说明 | 10141| ------ |----------------------------------| ---- | ------------------------------------------------------------ | 10142| type | [AvoidAreaType](arkts-apis-window-e.md#avoidareatype7) | 是 | 表示规避区类型。 | 10143 10144**返回值：** 10145 10146| 类型 | 说明 | 10147|-----------------------------------------| ----------------------------------- | 10148| Promise<[AvoidArea](arkts-apis-window-i.md#avoidarea7)> | Promise对象。返回窗口内容规避区域。 | 10149 10150**示例：** 10151 10152```ts 10153import { BusinessError } from '@kit.BasicServicesKit'; 10154 10155let type = window.AvoidAreaType.TYPE_SYSTEM; 10156let promise = windowClass.getAvoidArea(type); 10157promise.then((data) => { 10158 console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); 10159}).catch((err: BusinessError) => { 10160 console.error(`Failed to obtain the area. Cause code: ${err.code}, message: ${err.message}`); 10161}); 10162``` 10163 10164## setFullScreen<sup>(deprecated)</sup> 10165 10166setFullScreen(isFullScreen: boolean, callback: AsyncCallback<void>): void 10167 10168设置主窗口或子窗口的布局是否为全屏布局，使用callback异步回调。 10169全屏布局生效时，布局不避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件可能产生与其重叠的情况。 10170非全屏布局生效时，布局避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件不会与其重叠。 10171 10172> **说明：** 10173> 10174> 从API version 6开始支持，从API version 9开始废弃，推荐联合使用[setWindowSystemBarEnable()](#setwindowsystembarenable9)和[setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9)实现全屏。 10175 10176**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10177 10178**参数：** 10179 10180| 参数名 | 类型 | 必填 | 说明 | 10181| ------------ | ------------------------- | ---- | ---------------------------------------------- | 10182| isFullScreen | boolean | 是 | 是否设为全屏布局（该全屏布局影响状态栏、<!--RP15-->三键导航栏<!--RP15End-->显示）。true表示全屏；false表示非全屏。 | 10183| callback | AsyncCallback<void> | 是 | 回调函数。 | 10184 10185**示例：** 10186 10187```ts 10188// EntryAbility.ets 10189import { UIAbility } from '@kit.AbilityKit'; 10190import { BusinessError } from '@kit.BasicServicesKit'; 10191 10192export default class EntryAbility extends UIAbility { 10193 // ... 10194 onWindowStageCreate(windowStage: window.WindowStage): void { 10195 console.info('onWindowStageCreate'); 10196 let windowClass: window.Window | undefined = undefined; 10197 windowStage.getMainWindow((err: BusinessError, data) => { 10198 const errCode: number = err.code; 10199 if (errCode) { 10200 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10201 return; 10202 } 10203 windowClass = data; 10204 let isFullScreen: boolean = true; 10205 windowClass.setFullScreen(isFullScreen, (err: BusinessError) => { 10206 const errCode: number = err.code; 10207 if (errCode) { 10208 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 10209 return; 10210 } 10211 console.info('Succeeded in enabling the full-screen mode.'); 10212 }); 10213 }); 10214 } 10215} 10216``` 10217 10218## setFullScreen<sup>(deprecated)</sup> 10219 10220setFullScreen(isFullScreen: boolean): Promise<void> 10221 10222设置主窗口或子窗口的布局是否为全屏布局，使用Promise异步回调。 10223全屏布局生效时，布局不避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件可能产生与其重叠的情况。 10224非全屏布局生效时，布局避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件不会与其重叠。 10225 10226> **说明：** 10227> 10228> 从API version 6开始支持，从API version 9开始废弃，推荐联合使用[setWindowSystemBarEnable()](#setwindowsystembarenable9)和[setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9)实现全屏。 10229 10230**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10231 10232**参数：** 10233 10234| 参数名 | 类型 | 必填 | 说明 | 10235| ------------ | ------- | ---- | ---------------------------------------------- | 10236| isFullScreen | boolean | 是 | 是否设为全屏布局（该全屏布局影响状态栏、<!--RP15-->三键导航栏<!--RP15End-->显示）。true表示全屏；false表示非全屏。 | 10237 10238**返回值：** 10239 10240| 类型 | 说明 | 10241| ------------------- | ------------------------- | 10242| Promise<void> | 无返回结果的Promise对象。 | 10243 10244**示例：** 10245 10246```ts 10247// EntryAbility.ets 10248import { UIAbility } from '@kit.AbilityKit'; 10249import { BusinessError } from '@kit.BasicServicesKit'; 10250 10251export default class EntryAbility extends UIAbility { 10252 // ... 10253 onWindowStageCreate(windowStage: window.WindowStage): void { 10254 console.info('onWindowStageCreate'); 10255 let windowClass: window.Window | undefined = undefined; 10256 windowStage.getMainWindow((err: BusinessError, data) => { 10257 const errCode: number = err.code; 10258 if (errCode) { 10259 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10260 return; 10261 } 10262 windowClass = data; 10263 let isFullScreen: boolean = true; 10264 let promise = windowClass.setFullScreen(isFullScreen); 10265 promise.then(() => { 10266 console.info('Succeeded in enabling the full-screen mode.'); 10267 }).catch((err: BusinessError) => { 10268 console.error(`Failed to enable the full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 10269 }); 10270 }); 10271 } 10272} 10273``` 10274 10275## setLayoutFullScreen<sup>(deprecated)</sup> 10276 10277setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void 10278 10279设置主窗口或子窗口的布局是否为沉浸式布局，使用callback异步回调。 10280沉浸式布局生效时，布局不避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件可能产生与其重叠的情况。 10281非沉浸式布局生效时，布局避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件不会与其重叠。 10282 10283> **说明：** 10284> 10285> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9)。 10286 10287**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10288 10289**参数：** 10290 10291| 参数名 | 类型 | 必填 | 说明 | 10292| ------------------ | ------------------------- | ---- | ------------------------------------------------------------ | 10293| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局（该沉浸式布局不影响状态栏、<!--RP15-->三键导航栏<!--RP15End-->显示）。true表示沉浸式布局；false表示非沉浸式布局。 | 10294| callback | AsyncCallback<void> | 是 | 回调函数。 | 10295 10296**示例：** 10297 10298```ts 10299// EntryAbility.ets 10300import { UIAbility } from '@kit.AbilityKit'; 10301import { BusinessError } from '@kit.BasicServicesKit'; 10302 10303export default class EntryAbility extends UIAbility { 10304 // ... 10305 onWindowStageCreate(windowStage: window.WindowStage): void { 10306 console.info('onWindowStageCreate'); 10307 let windowClass: window.Window | undefined = undefined; 10308 windowStage.getMainWindow((err: BusinessError, data) => { 10309 const errCode: number = err.code; 10310 if (errCode) { 10311 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10312 return; 10313 } 10314 windowClass = data; 10315 let isLayoutFullScreen: boolean = true; 10316 windowClass.setLayoutFullScreen(isLayoutFullScreen, (err: BusinessError) => { 10317 const errCode: number = err.code; 10318 if (errCode) { 10319 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 10320 return; 10321 } 10322 console.info('Succeeded in setting the window layout to full-screen mode.'); 10323 }); 10324 }); 10325 } 10326} 10327``` 10328 10329## setLayoutFullScreen<sup>(deprecated)</sup> 10330 10331setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> 10332 10333设置主窗口或子窗口的布局是否为沉浸式布局，使用Promise异步回调。 10334沉浸式布局生效时，布局不避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件可能产生与其重叠的情况。 10335非沉浸式布局生效时，布局避让状态栏与<!--RP15-->三键导航栏<!--RP15End-->，组件不会与其重叠。 10336 10337> **说明：** 10338> 10339> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowLayoutFullScreen()](#setwindowlayoutfullscreen9)。 10340 10341**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10342 10343**参数：** 10344 10345| 参数名 | 类型 | 必填 | 说明 | 10346| ------------------ | ------- | ---- | ------------------------------------------------------------ | 10347| isLayoutFullScreen | boolean | 是 | 窗口的布局是否为沉浸式布局（该沉浸式布局不影响状态栏、<!--RP15-->三键导航栏<!--RP15End-->显示）。true表示沉浸式布局；false表示非沉浸式布局。 | 10348 10349**返回值：** 10350 10351| 类型 | 说明 | 10352| ------------------- | ------------------------- | 10353| Promise<void> | 无返回结果的Promise对象。 | 10354 10355**示例：** 10356 10357```ts 10358// EntryAbility.ets 10359import { UIAbility } from '@kit.AbilityKit'; 10360import { BusinessError } from '@kit.BasicServicesKit'; 10361 10362export default class EntryAbility extends UIAbility { 10363 // ... 10364 onWindowStageCreate(windowStage: window.WindowStage): void { 10365 console.info('onWindowStageCreate'); 10366 let windowClass: window.Window | undefined = undefined; 10367 windowStage.getMainWindow((err: BusinessError, data) => { 10368 const errCode: number = err.code; 10369 if (errCode) { 10370 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10371 return; 10372 } 10373 windowClass = data; 10374 let isLayoutFullScreen: boolean = true; 10375 let promise = windowClass.setLayoutFullScreen(isLayoutFullScreen); 10376 promise.then(() => { 10377 console.info('Succeeded in setting the window layout to full-screen mode.'); 10378 }).catch((err: BusinessError) => { 10379 console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`); 10380 }); 10381 }); 10382 } 10383} 10384``` 10385 10386## setSystemBarEnable<sup>(deprecated)</sup> 10387 10388setSystemBarEnable(names: Array<'status' | 'navigation'>, callback: AsyncCallback<void>): void 10389 10390<!--RP14-->设置主窗口状态栏、三键导航栏的可见模式，状态栏通过status控制、三键导航栏通过navigation控制<!--RP14End-->，使用callback异步回调。<br>从API version 12开始，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 10391 10392调用生效后返回并不表示状态栏和<!--RP15-->三键导航栏<!--RP15End-->的显示或隐藏已完成。子窗口调用后不生效。非全屏模式（悬浮窗、分屏等场景）下配置不生效。 10393 10394> **说明：** 10395> 10396> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowSystemBarEnable()](#setwindowsystembarenable9)。 10397 10398**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10399 10400**参数：** 10401 10402| 参数名 | 类型 | 必填 | 说明 | 10403| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 10404| names | Array<'status'\|'navigation'> | 是 | 设置窗口全屏模式时状态栏和<!--RP15-->三键导航栏<!--RP15End-->是否显示。<br>例如，需全部显示，该参数设置为['status', 'navigation']；设置为[]，则不显示。 | 10405| callback | AsyncCallback<void> | 是 | 回调函数。 | 10406 10407 10408**示例：** 10409 10410```ts 10411// 此处以状态栏等均不显示为例 10412// EntryAbility.ets 10413import { UIAbility } from '@kit.AbilityKit'; 10414import { BusinessError } from '@kit.BasicServicesKit'; 10415 10416export default class EntryAbility extends UIAbility { 10417 // ... 10418 onWindowStageCreate(windowStage: window.WindowStage): void { 10419 console.info('onWindowStageCreate'); 10420 let windowClass: window.Window | undefined = undefined; 10421 windowStage.getMainWindow((err: BusinessError, data) => { 10422 const errCode: number = err.code; 10423 if (errCode) { 10424 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10425 return; 10426 } 10427 windowClass = data; 10428 let names: Array<'status' | 'navigation'> = []; 10429 windowClass.setSystemBarEnable(names, (err: BusinessError) => { 10430 const errCode: number = err.code; 10431 if (errCode) { 10432 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 10433 return; 10434 } 10435 console.info('Succeeded in setting the system bar to be invisible.'); 10436 }); 10437 }); 10438 } 10439} 10440``` 10441 10442## setSystemBarEnable<sup>(deprecated)</sup> 10443 10444setSystemBarEnable(names: Array<'status' | 'navigation'>): Promise<void> 10445 10446<!--RP14-->设置主窗口状态栏、三键导航栏的可见模式，状态栏通过status控制、三键导航栏通过navigation控制<!--RP14End-->，使用Promise异步回调。<br>从API version 12开始，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 10447 10448调用生效后返回并不表示状态栏和<!--RP15-->三键导航栏<!--RP15End-->的显示或隐藏已完成。子窗口调用后不生效。非全屏模式（悬浮窗、分屏等场景）下配置不生效。 10449 10450> **说明：** 10451> 10452> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowSystemBarEnable()](#setwindowsystembarenable9)。 10453 10454**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10455 10456**参数：** 10457 10458| 参数名 | 类型 | 必填 | 说明 | 10459| ------ | ---------------------------- | ---- | ------------------------ | 10460| names | Array<'status'\|'navigation'> | 是 | 设置窗口全屏模式时状态栏和<!--RP15-->三键导航栏<!--RP15End-->是否显示。<br>例如，需全部显示，该参数设置为['status', 'navigation']；设置为[]，则不显示。 | 10461 10462**返回值：** 10463 10464| 类型 | 说明 | 10465| ------------------- | ------------------------- | 10466| Promise<void> | 无返回结果的Promise对象。 | 10467 10468 10469**示例：** 10470 10471```ts 10472// 此处以状态栏等均不显示为例 10473// EntryAbility.ets 10474import { UIAbility } from '@kit.AbilityKit'; 10475import { BusinessError } from '@kit.BasicServicesKit'; 10476 10477export default class EntryAbility extends UIAbility { 10478 // ... 10479 onWindowStageCreate(windowStage: window.WindowStage): void { 10480 console.info('onWindowStageCreate'); 10481 let windowClass: window.Window | undefined = undefined; 10482 windowStage.getMainWindow((err: BusinessError, data) => { 10483 const errCode: number = err.code; 10484 if (errCode) { 10485 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10486 return; 10487 } 10488 windowClass = data; 10489 let names: Array<'status' | 'navigation'> = []; 10490 let promise = windowClass.setSystemBarEnable(names); 10491 promise.then(() => { 10492 console.info('Succeeded in setting the system bar to be invisible.'); 10493 }).catch((err: BusinessError) => { 10494 console.error(`Failed to set the system bar to be invisible. Cause code: ${err.code}, message: ${err.message}`); 10495 }); 10496 }); 10497 } 10498} 10499``` 10500 10501## setSystemBarProperties<sup>(deprecated)</sup> 10502 10503setSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void 10504 10505设置主窗口<!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性，使用callback异步回调，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 10506 10507子窗口调用后不生效。非全屏模式（悬浮窗、分屏等场景）下配置不生效。 10508 10509> **说明：** 10510> 10511> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowSystemBarProperties()](#setwindowsystembarproperties9)。 10512 10513**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10514 10515**参数：** 10516 10517| 参数名 | 类型 | 必填 | 说明 | 10518| ------------------- | ------------------------------------------- | ---- | ---------------------- | 10519| systemBarProperties | [SystemBarProperties](arkts-apis-window-i.md#systembarproperties) | 是 | <!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性。 | 10520| callback | AsyncCallback<void> | 是 | 回调函数。 | 10521 10522**示例：** 10523 10524```ts 10525// EntryAbility.ets 10526import { UIAbility } from '@kit.AbilityKit'; 10527import { BusinessError } from '@kit.BasicServicesKit'; 10528 10529export default class EntryAbility extends UIAbility { 10530 // ... 10531 onWindowStageCreate(windowStage: window.WindowStage): void { 10532 console.info('onWindowStageCreate'); 10533 let windowClass: window.Window | undefined = undefined; 10534 windowStage.getMainWindow((err: BusinessError, data) => { 10535 const errCode: number = err.code; 10536 if (errCode) { 10537 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10538 return; 10539 } 10540 windowClass = data; 10541 let SystemBarProperties: window.SystemBarProperties = { 10542 statusBarColor: '#ff00ff', 10543 navigationBarColor: '#00ff00', 10544 //以下两个属性从API Version8开始支持 10545 statusBarContentColor: '#ffffff', 10546 navigationBarContentColor: '#00ffff' 10547 }; 10548 windowClass.setSystemBarProperties(SystemBarProperties, (err) => { 10549 const errCode: number = err.code; 10550 if (errCode) { 10551 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 10552 return; 10553 } 10554 console.info('Succeeded in setting the system bar properties.'); 10555 }); 10556 }); 10557 } 10558} 10559``` 10560 10561## setSystemBarProperties<sup>(deprecated)</sup> 10562 10563setSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> 10564 10565设置主窗口<!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性，使用Promise异步回调，<!--RP5-->该接口在2in1设备上调用不生效。<!--RP5End--> 10566 10567子窗口调用后不生效。 10568 10569> **说明：** 10570> 10571> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowSystemBarProperties()](#setwindowsystembarproperties9)。 10572 10573**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10574 10575**参数：** 10576 10577| 参数名 | 类型 | 必填 | 说明 | 10578| ------------------- | ------------------------------------------- | ---- | ---------------------- | 10579| systemBarProperties | [SystemBarProperties](arkts-apis-window-i.md#systembarproperties) | 是 | <!--Del-->三键导航栏、<!--DelEnd-->状态栏的属性。 | 10580 10581**返回值：** 10582 10583| 类型 | 说明 | 10584| ------------------- | ------------------------- | 10585| Promise<void> | 无返回结果的Promise对象。 | 10586 10587**示例：** 10588 10589```ts 10590// EntryAbility.ets 10591import { UIAbility } from '@kit.AbilityKit'; 10592import { BusinessError } from '@kit.BasicServicesKit'; 10593 10594export default class EntryAbility extends UIAbility { 10595 // ... 10596 onWindowStageCreate(windowStage: window.WindowStage): void { 10597 console.info('onWindowStageCreate'); 10598 let windowClass: window.Window | undefined = undefined; 10599 windowStage.getMainWindow((err: BusinessError, data) => { 10600 const errCode: number = err.code; 10601 if (errCode) { 10602 console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`); 10603 return; 10604 } 10605 windowClass = data; 10606 let SystemBarProperties: window.SystemBarProperties = { 10607 statusBarColor: '#ff00ff', 10608 navigationBarColor: '#00ff00', 10609 //以下两个属性从API Version8开始支持 10610 statusBarContentColor: '#ffffff', 10611 navigationBarContentColor: '#00ffff' 10612 }; 10613 let promise = windowClass.setSystemBarProperties(SystemBarProperties); 10614 promise.then(() => { 10615 console.info('Succeeded in setting the system bar properties.'); 10616 }).catch((err: BusinessError) => { 10617 console.error(`Failed to set the system bar properties. Cause code: ${err.code}, message: ${err.message}`); 10618 }); 10619 }); 10620 } 10621} 10622``` 10623 10624## loadContent<sup>(deprecated)</sup> 10625 10626loadContent(path: string, callback: AsyncCallback<void>): void 10627 10628为当前窗口加载具体页面内容，使用callback异步回调。建议在UIAbility启动过程中使用该接口，多次调用该接口会先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。当前UI的执行上下文可能不明确，所以不建议在回调函数中做UI相关的操作。 10629 10630> **说明：** 10631> 10632> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setUIContent()](#setuicontent9)。 10633 10634**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10635 10636**参数：** 10637 10638| 参数名 | 类型 | 必填 | 说明 | 10639| -------- | ------------------------- | ---- | -------------------- | 10640| path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。 | 10641| callback | AsyncCallback<void> | 是 | 回调函数。 | 10642 10643**示例：** 10644 10645```ts 10646import { BusinessError } from '@kit.BasicServicesKit'; 10647 10648windowClass.loadContent('pages/page2/page3', (err: BusinessError) => { 10649 const errCode: number = err.code; 10650 if (errCode) { 10651 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10652 return; 10653 } 10654 console.info('Succeeded in loading the content.'); 10655}); 10656``` 10657 10658## loadContent<sup>(deprecated)</sup> 10659 10660loadContent(path: string): Promise<void> 10661 10662为当前窗口加载具体页面内容，使用Promise异步回调。建议在UIAbility启动过程中使用该接口，多次调用该接口会先销毁旧的页面内容（即UIContent）再加载新的页面内容，请谨慎使用。当前UI的执行上下文可能不明确，所以不建议在回调函数中做UI相关的操作。 10663 10664> **说明：** 10665> 10666> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setUIContent()](#setuicontent9-1)。 10667 10668**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10669 10670**参数：** 10671 10672| 参数名 | 类型 | 必填 | 说明 | 10673| ------ | ------ | ---- | -------------------- | 10674| path | string | 是 | 要加载到窗口中的页面内容的路径，Stage模型下该路径需添加到工程的main_pages.json文件中，FA模型下该路径需添加到工程的config.json文件中。 | 10675 10676**返回值：** 10677 10678| 类型 | 说明 | 10679| ------------------- | ------------------------- | 10680| Promise<void> | 无返回结果的Promise对象。 | 10681 10682**示例：** 10683 10684```ts 10685import { BusinessError } from '@kit.BasicServicesKit'; 10686 10687let promise = windowClass.loadContent('pages/page2/page3'); 10688promise.then(() => { 10689 console.info('Succeeded in loading the content.'); 10690}).catch((err: BusinessError) => { 10691 console.error(`Failed to load the content. Cause code: ${err.code}, message: ${err.message}`); 10692}); 10693``` 10694 10695## isShowing<sup>(deprecated)</sup> 10696 10697isShowing(callback: AsyncCallback<boolean>): void 10698 10699判断当前窗口是否已显示，使用callback异步回调。 10700 10701> **说明：** 10702> 10703> 从API version 7开始支持，从API version 9开始废弃，推荐使用[isWindowShowing()](#iswindowshowing9)。 10704 10705**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10706 10707**参数：** 10708 10709| 参数名 | 类型 | 必填 | 说明 | 10710| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 10711| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前窗口已显示，返回false表示当前窗口未显示。 | 10712 10713**示例：** 10714 10715```ts 10716import { BusinessError } from '@kit.BasicServicesKit'; 10717 10718windowClass.isShowing((err: BusinessError, data) => { 10719 const errCode: number = err.code; 10720 if (errCode) { 10721 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 10722 return; 10723 } 10724 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 10725}); 10726``` 10727 10728## isShowing<sup>(deprecated)</sup> 10729 10730isShowing(): Promise<boolean> 10731 10732判断当前窗口是否已显示，使用Promise异步回调。 10733 10734> **说明：** 10735> 10736> 从API version 7开始支持，从API version 9开始废弃，推荐使用[isWindowShowing()](#iswindowshowing9)。 10737 10738**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10739 10740**返回值：** 10741 10742| 类型 | 说明 | 10743| ---------------------- | ------------------------------------------------------------ | 10744| Promise<boolean> | Promise对象。返回true表示当前窗口已显示，返回false表示当前窗口未显示。 | 10745 10746**示例：** 10747 10748```ts 10749import { BusinessError } from '@kit.BasicServicesKit'; 10750 10751let promise = windowClass.isShowing(); 10752promise.then((data) => { 10753 console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); 10754}).catch((err: BusinessError) => { 10755 console.error(`Failed to check whether the window is showing. Cause code: ${err.code}, message: ${err.message}`); 10756}); 10757``` 10758 10759## on('systemAvoidAreaChange')<sup>(deprecated)</sup> 10760 10761on(type: 'systemAvoidAreaChange', callback: Callback<AvoidArea>): void 10762 10763开启当前窗口系统规避区变化的监听。 10764 10765> **说明：** 10766> 10767> 从API version 7开始支持，从API version 9开始废弃，推荐使用[on('avoidAreaChange')](#onavoidareachange9)。 10768 10769**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10770 10771**参数：** 10772 10773| 参数名 | 类型 | 必填 | 说明 | 10774| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 10775| type | string | 是 | 监听事件，固定为'systemAvoidAreaChange'，即系统规避区变化事件。 | 10776| callback | Callback<[AvoidArea](arkts-apis-window-i.md#avoidarea7)> | 是 | 回调函数。返回当前规避区。 | 10777 10778 10779**示例：** 10780 10781```ts 10782windowClass.on('systemAvoidAreaChange', (data) => { 10783 console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data)); 10784}); 10785``` 10786 10787## off('systemAvoidAreaChange')<sup>(deprecated)</sup> 10788 10789off(type: 'systemAvoidAreaChange', callback?: Callback<AvoidArea>): void 10790 10791关闭当前窗口系统规避区变化的监听。 10792 10793> **说明：** 10794> 10795> 从API version 7开始支持，从API version 9开始废弃，推荐使用[off('avoidAreaChange')](#offavoidareachange9)。 10796 10797**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10798 10799**参数：** 10800 10801| 参数名 | 类型 | 必填 | 说明 | 10802| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 10803| type | string | 是 | 监听事件，固定为'systemAvoidAreaChange'，即系统规避区变化事件。 | 10804| callback | Callback<[AvoidArea](arkts-apis-window-i.md#avoidarea7)> | 否 | 回调函数。返回当前规避区。若传入参数，则关闭该监听。若未传入参数，则关闭所有系统规避区变化的监听。 | 10805 10806**示例：** 10807 10808```ts 10809const callback = (avoidArea: window.AvoidArea) => { 10810 // ... 10811} 10812windowClass.on('systemAvoidAreaChange', callback); 10813windowClass.off('systemAvoidAreaChange', callback); 10814// 如果通过on开启多个callback进行监听，同时关闭所有监听： 10815windowClass.off('systemAvoidAreaChange'); 10816``` 10817 10818## isSupportWideGamut<sup>(deprecated)</sup> 10819 10820isSupportWideGamut(callback: AsyncCallback<boolean>): void 10821 10822判断当前窗口是否支持广色域模式，使用callback异步回调。 10823 10824> **说明：** 10825> 10826> 从API version 8开始支持，从API version 9开始废弃，推荐使用[isWindowSupportWideGamut()](#iswindowsupportwidegamut9)。 10827 10828**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10829 10830**参数：** 10831 10832| 参数名 | 类型 | 必填 | 说明 | 10833| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 10834| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前窗口支持广色域模式，返回false表示当前窗口不支持广色域模式。 | 10835 10836**示例：** 10837 10838```ts 10839import { BusinessError } from '@kit.BasicServicesKit'; 10840 10841windowClass.isSupportWideGamut((err: BusinessError, data) => { 10842 const errCode: number = err.code; 10843 if (errCode) { 10844 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 10845 return; 10846 } 10847 console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); 10848}); 10849``` 10850 10851## isSupportWideGamut<sup>(deprecated)</sup> 10852 10853isSupportWideGamut(): Promise<boolean> 10854 10855判断当前窗口是否支持广色域模式，使用Promise异步回调。 10856 10857> **说明：** 10858> 10859> 从API version 8开始支持，从API version 9开始废弃，推荐使用[isWindowSupportWideGamut()](#iswindowsupportwidegamut9-1)。 10860 10861**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10862 10863**返回值：** 10864 10865| 类型 | 说明 | 10866| ---------------------- | ------------------------------------------------------------ | 10867| Promise<boolean> | Promise对象。返回true表示当前窗口支持广色域模式，返回false表示当前窗口不支持广色域模式。 | 10868 10869**示例：** 10870 10871```ts 10872import { BusinessError } from '@kit.BasicServicesKit'; 10873 10874let promise = windowClass.isSupportWideGamut(); 10875promise.then((data) => { 10876 console.info('Succeeded in checking whether the window support WideGamut. Data: ' + JSON.stringify(data)); 10877}).catch((err: BusinessError) => { 10878 console.error(`Failed to check whether the window support WideGamut. Cause code: ${err.code}, message: ${err.message}`); 10879}); 10880``` 10881 10882## setColorSpace<sup>(deprecated)</sup> 10883 10884setColorSpace(colorSpace:ColorSpace, callback: AsyncCallback<void>): void 10885 10886设置当前窗口为广色域模式或默认色域模式，使用callback异步回调。 10887 10888> **说明：** 10889> 10890> 从API version 8开始支持，从API version 9开始废弃，推荐使用[setWindowColorSpace()](#setwindowcolorspace9)。 10891 10892**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10893 10894**参数：** 10895 10896| 参数名 | 类型 | 必填 | 说明 | 10897| ---------- | ------------------------- | ---- | ------------ | 10898| colorSpace | [ColorSpace](arkts-apis-window-e.md#colorspace8) | 是 | 设置色域模式。 | 10899| callback | AsyncCallback<void> | 是 | 回调函数。 | 10900 10901 10902**示例：** 10903 10904```ts 10905import { BusinessError } from '@kit.BasicServicesKit'; 10906 10907windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err: BusinessError) => { 10908 const errCode: number = err.code; 10909 if (errCode) { 10910 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 10911 return; 10912 } 10913 console.info('Succeeded in setting window colorspace.'); 10914}); 10915``` 10916 10917## setColorSpace<sup>(deprecated)</sup> 10918 10919setColorSpace(colorSpace:ColorSpace): Promise<void> 10920 10921设置当前窗口为广色域模式或默认色域模式，使用Promise异步回调。 10922 10923> **说明：** 10924> 10925> 从API version 8开始支持，从API version 9开始废弃，推荐使用[setWindowColorSpace()](#setwindowcolorspace9-1)。 10926 10927**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10928 10929**参数：** 10930 10931| 参数名 | 类型 | 必填 | 说明 | 10932| ---------- | ------------------------- | ---- | -------------- | 10933| colorSpace | [ColorSpace](arkts-apis-window-e.md#colorspace8) | 是 | 设置色域模式。 | 10934 10935**返回值：** 10936 10937| 类型 | 说明 | 10938| ------------------- | ------------------------- | 10939| Promise<void> | 无返回结果的Promise对象。 | 10940 10941 10942**示例：** 10943 10944```ts 10945import { BusinessError } from '@kit.BasicServicesKit'; 10946 10947let promise = windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT); 10948promise.then(() => { 10949 console.info('Succeeded in setting window colorspace.'); 10950}).catch((err: BusinessError) => { 10951 console.error(`Failed to set window colorspace. Cause code: ${err.code}, message: ${err.message}`); 10952}); 10953``` 10954 10955## getColorSpace<sup>(deprecated)</sup> 10956 10957getColorSpace(callback: AsyncCallback<ColorSpace>): void 10958 10959获取当前窗口色域模式，使用callback异步回调。 10960 10961> **说明：** 10962> 10963> 从API version 8开始支持，从API version 9开始废弃，推荐使用[getWindowColorSpace()](#getwindowcolorspace9)。 10964 10965**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10966 10967**参数：** 10968 10969| 参数名 | 类型 | 必填 | 说明 | 10970| -------- | ---------------------------------------------- | ---- | ---------------------------------------------------------- | 10971| callback | AsyncCallback<[ColorSpace](arkts-apis-window-e.md#colorspace8)> | 是 | 回调函数。当获取成功，err为undefined，data为当前色域模式。 | 10972 10973**示例：** 10974 10975```ts 10976import { BusinessError } from '@kit.BasicServicesKit'; 10977 10978windowClass.getColorSpace((err: BusinessError, data) => { 10979 const errCode: number = err.code; 10980 if (errCode) { 10981 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 10982 return; 10983 } 10984 console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data)); 10985}); 10986``` 10987 10988## getColorSpace<sup>(deprecated)</sup> 10989 10990getColorSpace(): Promise<ColorSpace> 10991 10992获取当前窗口色域模式，使用Promise异步回调。 10993 10994> **说明：** 10995> 10996> 从API version 8开始支持，从API version 9开始废弃，推荐使用[getWindowColorSpace()](#getwindowcolorspace9)。 10997 10998**系统能力：** SystemCapability.WindowManager.WindowManager.Core 10999 11000**返回值：** 11001 11002| 类型 | 说明 | 11003| ---------------------------------------- | ------------------------------- | 11004| Promise<[ColorSpace](arkts-apis-window-e.md#colorspace8)> | Promise对象。返回当前色域模式。 | 11005 11006**示例：** 11007 11008```ts 11009import { BusinessError } from '@kit.BasicServicesKit'; 11010 11011let promise = windowClass.getColorSpace(); 11012promise.then((data) => { 11013 console.info('Succeeded in getting window color space. Cause:' + JSON.stringify(data)); 11014}).catch((err: BusinessError) => { 11015 console.error(`Failed to get window colorspace. Cause code: ${err.code}, message: ${err.message}`); 11016}); 11017``` 11018 11019## setBackgroundColor<sup>(deprecated)</sup> 11020 11021setBackgroundColor(color: string, callback: AsyncCallback<void>): void 11022 11023设置窗口的背景色，使用callback异步回调。Stage模型下，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 11024 11025> **说明：** 11026> 11027> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowBackgroundColor()](#setwindowbackgroundcolor9)。 11028 11029**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11030 11031**参数：** 11032 11033| 参数名 | 类型 | 必填 | 说明 | 11034| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 11035| color | string | 是 | 需要设置的背景色，为十六进制RGB或ARGB颜色，不区分大小写，例如`'#00FF00'`或`'#FF00FF00'`。 | 11036| callback | AsyncCallback<void> | 是 | 回调函数。 | 11037 11038 11039**示例：** 11040 11041```ts 11042import { BusinessError } from '@kit.BasicServicesKit'; 11043 11044let color: string = '#00ff33'; 11045windowClass.setBackgroundColor(color, (err: BusinessError) => { 11046 const errCode: number = err.code; 11047 if (errCode) { 11048 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 11049 return; 11050 } 11051 console.info('Succeeded in setting the background color.'); 11052}); 11053``` 11054 11055## setBackgroundColor<sup>(deprecated)</sup> 11056 11057setBackgroundColor(color: string): Promise<void> 11058 11059设置窗口的背景色，使用Promise异步回调。Stage模型下，该接口需要在[loadContent()](#loadcontent9)或[setUIContent()](#setuicontent9)调用生效后使用。 11060 11061> **说明：** 11062> 11063> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowBackgroundColor()](#setwindowbackgroundcolor9)。 11064 11065**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11066 11067**参数：** 11068 11069| 参数名 | 类型 | 必填 | 说明 | 11070| ------ | ------ | ---- | ------------------------------------------------------------ | 11071| color | string | 是 | 需要设置的背景色，为十六进制RGB或ARGB颜色，不区分大小写，例如`'#00FF00'`或`'#FF00FF00'`。 | 11072 11073**返回值：** 11074 11075| 类型 | 说明 | 11076| ------------------- | ------------------------- | 11077| Promise<void> | 无返回结果的Promise对象。 | 11078 11079 11080**示例：** 11081 11082```ts 11083import { BusinessError } from '@kit.BasicServicesKit'; 11084 11085let color: string = '#00ff33'; 11086let promise = windowClass.setBackgroundColor(color); 11087promise.then(() => { 11088 console.info('Succeeded in setting the background color.'); 11089}).catch((err: BusinessError) => { 11090 console.error(`Failed to set the background color. Cause code: ${err.code}, message: ${err.message}`); 11091}); 11092``` 11093 11094## setBrightness<sup>(deprecated)</sup> 11095 11096setBrightness(brightness: number, callback: AsyncCallback<void>): void 11097 11098允许应用窗口设置屏幕亮度值，使用callback异步回调。 11099 11100当前屏幕亮度规格：窗口设置屏幕亮度生效时，控制中心不可以调整系统屏幕亮度，窗口恢复默认系统亮度之后，控制中心可以调整系统屏幕亮度。 11101 11102> **说明：** 11103> 11104> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowBrightness()](#setwindowbrightness9)。 11105 11106**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11107 11108**参数：** 11109 11110| 参数名 | 类型 | 必填 | 说明 | 11111| ---------- | ------------------------- | ---- |---------------------------------------| 11112| brightness | number | 是 | 屏幕亮度值。该参数为浮点数，取值范围为[0.0, 1.0]或-1.0。1.0表示最亮，-1.0表示恢复成设置窗口亮度前的系统控制中心亮度。。 | 11113| callback | AsyncCallback<void> | 是 | 回调函数。 | 11114 11115 11116**示例：** 11117 11118```ts 11119import { BusinessError } from '@kit.BasicServicesKit'; 11120 11121let brightness: number = 1; 11122windowClass.setBrightness(brightness, (err: BusinessError) => { 11123 const errCode: number = err.code; 11124 if (errCode) { 11125 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 11126 return; 11127 } 11128 console.info('Succeeded in setting the brightness.'); 11129}); 11130``` 11131 11132## setBrightness<sup>(deprecated)</sup> 11133 11134setBrightness(brightness: number): Promise<void> 11135 11136允许应用窗口设置屏幕亮度值，使用Promise异步回调。 11137 11138当前屏幕亮度规格：窗口设置屏幕亮度生效时，控制中心不可以调整系统屏幕亮度，窗口恢复默认系统亮度之后，控制中心可以调整系统屏幕亮度。 11139 11140> **说明：** 11141> 11142> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowBrightness()](#setwindowbrightness9-1)。 11143 11144**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11145 11146**参数：** 11147 11148| 参数名 | 类型 | 必填 | 说明 | 11149| ---------- | ------ | ---- |------------------------------------------| 11150| brightness | number | 是 | 屏幕亮度值。该参数为浮点数，取值范围为[0.0, 1.0]或-1.0。1.0表示最亮，-1.0表示恢复成设置窗口亮度前的系统控制中心亮度。 | 11151 11152**返回值：** 11153 11154| 类型 | 说明 | 11155| ------------------- | ------------------------- | 11156| Promise<void> | 无返回结果的Promise对象。 | 11157 11158 11159**示例：** 11160 11161```ts 11162import { BusinessError } from '@kit.BasicServicesKit'; 11163 11164let brightness: number = 1; 11165let promise = windowClass.setBrightness(brightness); 11166promise.then(() => { 11167 console.info('Succeeded in setting the brightness.'); 11168}).catch((err: BusinessError) => { 11169 console.error(`Failed to set the brightness. Cause code: ${err.code}, message: ${err.message}`); 11170}); 11171``` 11172 11173## setDimBehind<sup>(deprecated)</sup> 11174 11175setDimBehind(dimBehindValue: number, callback: AsyncCallback<void>): void 11176 11177窗口叠加时，设备有子窗口的情况下设置靠后的窗口的暗度值，使用callback异步回调。 11178 11179> **说明：** 11180> 11181> 该接口不支持使用。从API version 7开始支持，从API version 9开始废弃。 11182 11183**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11184 11185**参数：** 11186 11187| 参数名 | 类型 | 必填 | 说明 | 11188| -------------- | ------------------------- | ---- |----------------------------------------| 11189| dimBehindValue | number | 是 | 表示靠后的窗口的暗度值，取值范围为[0.0, 1.0]，取1.0时表示最暗。 | 11190| callback | AsyncCallback<void> | 是 | 回调函数。 | 11191 11192**示例：** 11193 11194```ts 11195import { BusinessError } from '@kit.BasicServicesKit'; 11196 11197windowClass.setDimBehind(0.5, (err: BusinessError) => { 11198 const errCode: number = err.code; 11199 if (errCode) { 11200 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 11201 return; 11202 } 11203 console.info('Succeeded in setting the dimness.'); 11204}); 11205``` 11206 11207## setDimBehind<sup>(deprecated)</sup> 11208 11209setDimBehind(dimBehindValue: number): Promise<void> 11210 11211窗口叠加时，设备有子窗口的情况下设置靠后的窗口的暗度值，使用Promise异步回调。 11212 11213> **说明：** 11214> 11215> 该接口不支持使用。从API version 7开始支持，从API version 9开始废弃。 11216 11217**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11218 11219**参数：** 11220 11221| 参数名 | 类型 | 必填 | 说明 | 11222| -------------- | ------ | ---- | -------------------------------------------------- | 11223| dimBehindValue | number | 是 | 表示靠后的窗口的暗度值，取值范围为0-1，1表示最暗。 | 11224 11225**返回值：** 11226 11227| 类型 | 说明 | 11228| ------------------- | ------------------------- | 11229| Promise<void> | 无返回结果的Promise对象。 | 11230 11231**示例：** 11232 11233```ts 11234import { BusinessError } from '@kit.BasicServicesKit'; 11235 11236let promise = windowClass.setDimBehind(0.5); 11237promise.then(() => { 11238 console.info('Succeeded in setting the dimness.'); 11239}).catch((err: BusinessError) => { 11240 console.error(`Failed to set the dimness. Cause code: ${err.code}, message: ${err.message}`); 11241}); 11242``` 11243 11244## setFocusable<sup>(deprecated)</sup> 11245 11246setFocusable(isFocusable: boolean, callback: AsyncCallback<void>): void 11247 11248设置使用点击或其他方式使该窗口获焦的场景时，该窗口是否支持窗口焦点从操作前的获焦窗口切换到该窗口，使用callback异步回调。 11249 11250> **说明：** 11251> 11252> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowFocusable()](#setwindowfocusable9)。 11253 11254**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11255 11256**参数：** 11257 11258| 参数名 | 类型 | 必填 | 说明 | 11259| ----------- | ------------------------- | ---- | ---------------------------- | 11260| isFocusable | boolean | 是 | 点击时是否支持切换焦点窗口。true表示支持；false表示不支持。 | 11261| callback | AsyncCallback<void> | 是 | 回调函数。 | 11262 11263 11264**示例：** 11265 11266```ts 11267import { BusinessError } from '@kit.BasicServicesKit'; 11268 11269let isFocusable: boolean = true; 11270windowClass.setFocusable(isFocusable, (err: BusinessError) => { 11271 const errCode: number = err.code; 11272 if (errCode) { 11273 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 11274 return; 11275 } 11276 console.info('Succeeded in setting the window to be focusable.'); 11277}); 11278``` 11279 11280## setFocusable<sup>(deprecated)</sup> 11281 11282setFocusable(isFocusable: boolean): Promise<void> 11283 11284设置使用点击或其他方式使该窗口获焦的场景时，该窗口是否支持窗口焦点从点击前的获焦窗口切换到该窗口，使用Promise异步回调。 11285 11286> **说明：** 11287> 11288> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowFocusable()](#setwindowfocusable9-1)。 11289 11290**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11291 11292**参数：** 11293 11294| 参数名 | 类型 | 必填 | 说明 | 11295| ----------- | ------- | ---- | ---------------------------- | 11296| isFocusable | boolean | 是 | 点击时是否支持切换焦点窗口。true表示支持；false表示不支持。 | 11297 11298**返回值：** 11299 11300| 类型 | 说明 | 11301| ------------------- | ------------------------- | 11302| Promise<void> | 无返回结果的Promise对象。 | 11303 11304 11305**示例：** 11306 11307```ts 11308import { BusinessError } from '@kit.BasicServicesKit'; 11309 11310let isFocusable: boolean = true; 11311let promise = windowClass.setFocusable(isFocusable); 11312promise.then(() => { 11313 console.info('Succeeded in setting the window to be focusable.'); 11314}).catch((err: BusinessError) => { 11315 console.error(`Failed to set the window to be focusable. Cause code: ${err.code}, message: ${err.message}`); 11316}); 11317``` 11318 11319## setKeepScreenOn<sup>(deprecated)</sup> 11320 11321setKeepScreenOn(isKeepScreenOn: boolean, callback: AsyncCallback<void>): void 11322 11323设置屏幕是否为常亮状态，使用callback异步回调。 11324 11325> **说明：** 11326> 11327> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowKeepScreenOn()](#setwindowkeepscreenon9)。 11328 11329**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11330 11331**参数：** 11332 11333| 参数名 | 类型 | 必填 | 说明 | 11334| -------------- | ------------------------- | ---- | ------------------------ | 11335| isKeepScreenOn | boolean | 是 | 设置屏幕是否为常亮状态。true表示常亮；false表示不常亮。 | 11336| callback | AsyncCallback<void> | 是 | 回调函数。 | 11337 11338 11339**示例：** 11340 11341```ts 11342import { BusinessError } from '@kit.BasicServicesKit'; 11343 11344let isKeepScreenOn: boolean = true; 11345windowClass.setKeepScreenOn(isKeepScreenOn, (err: BusinessError) => { 11346 const errCode: number = err.code; 11347 if (errCode) { 11348 console.error(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 11349 return; 11350 } 11351 console.info('Succeeded in setting the screen to be always on.'); 11352}); 11353``` 11354 11355## setKeepScreenOn<sup>(deprecated)</sup> 11356 11357setKeepScreenOn(isKeepScreenOn: boolean): Promise<void> 11358 11359设置屏幕是否为常亮状态，使用Promise异步回调。 11360 11361> **说明：** 11362> 11363> 从API version 6开始支持，从API version 9开始废弃，推荐使用[setWindowKeepScreenOn()](#setwindowkeepscreenon9-1)。 11364 11365**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11366 11367**参数：** 11368 11369| 参数名 | 类型 | 必填 | 说明 | 11370| -------------- | ------- | ---- | ------------------------ | 11371| isKeepScreenOn | boolean | 是 | 设置屏幕是否为常亮状态。true表示常亮；false表示不常亮。 | 11372 11373**返回值：** 11374 11375| 类型 | 说明 | 11376| ------------------- | ------------------------- | 11377| Promise<void> | 无返回结果的Promise对象。 | 11378 11379**示例：** 11380 11381```ts 11382import { BusinessError } from '@kit.BasicServicesKit'; 11383 11384let isKeepScreenOn: boolean = true; 11385let promise = windowClass.setKeepScreenOn(isKeepScreenOn); 11386promise.then(() => { 11387 console.info('Succeeded in setting the screen to be always on.'); 11388}).catch((err: BusinessError) => { 11389 console.info(`Failed to set the screen to be always on. Cause code: ${err.code}, message: ${err.message}`); 11390}); 11391``` 11392 11393## setOutsideTouchable<sup>(deprecated)</sup> 11394 11395setOutsideTouchable(touchable: boolean, callback: AsyncCallback<void>): void 11396 11397设置是否允许可点击子窗口之外的区域，使用callback异步回调。 11398 11399> **说明：** 11400> 11401> 从API version 7开始支持，从API version 9开始废弃。 11402> 11403> 从API version 9开始，系统默认允许点击子窗口之外的区域，此接口不再支持使用，也不再提供替代接口。 11404 11405**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11406 11407**参数：** 11408 11409| 参数名 | 类型 | 必填 | 说明 | 11410| --------- | ------------------------- | ---- | ---------------- | 11411| touchable | boolean | 是 | 设置是否可点击。true表示可点击；false表示不可点击。 | 11412| callback | AsyncCallback<void> | 是 | 回调函数。 | 11413 11414**示例：** 11415 11416```ts 11417import { BusinessError } from '@kit.BasicServicesKit'; 11418 11419windowClass.setOutsideTouchable(true, (err: BusinessError) => { 11420 const errCode: number = err.code; 11421 if (errCode) { 11422 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 11423 return; 11424 } 11425 console.info('Succeeded in setting the area to be touchable.'); 11426}); 11427``` 11428 11429## setOutsideTouchable<sup>(deprecated)</sup> 11430 11431setOutsideTouchable(touchable: boolean): Promise<void> 11432 11433设置是否允许可点击子窗口之外的区域，使用Promise异步回调。 11434 11435> **说明：** 11436> 11437> 从API version 7开始支持，从API version 9开始废弃。 11438> 11439> 从API version 9开始，系统默认允许点击子窗口之外的区域，此接口不再支持使用，也不再提供替代接口。 11440 11441**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11442 11443**参数：** 11444 11445| 参数名 | 类型 | 必填 | 说明 | 11446| --------- | ------- | ---- | ---------------- | 11447| touchable | boolean | 是 | 设置是否可点击。true表示可点击；false表示不可点击。 | 11448 11449**返回值：** 11450 11451| 类型 | 说明 | 11452| ------------------- | ------------------------- | 11453| Promise<void> | 无返回结果的Promise对象。 | 11454 11455**示例：** 11456 11457```ts 11458import { BusinessError } from '@kit.BasicServicesKit'; 11459 11460let promise = windowClass.setOutsideTouchable(true); 11461promise.then(() => { 11462 console.info('Succeeded in setting the area to be touchable.'); 11463}).catch((err: BusinessError) => { 11464 console.error(`Failed to set the area to be touchable. Cause code: ${err.code}, message: ${err.message}`); 11465}); 11466``` 11467 11468## setPrivacyMode<sup>(deprecated)</sup> 11469 11470setPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 11471 11472设置窗口是否为隐私模式，使用callback异步回调。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。 11473 11474> **说明：** 11475> 11476> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowPrivacyMode()](#setwindowprivacymode9)。 11477 11478**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11479 11480**参数：** 11481 11482| 参数名 | 类型 | 必填 | 说明 | 11483| ------------- | ------------------------- | ---- | -------------------- | 11484| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 11485| callback | AsyncCallback<void> | 是 | 回调函数。 | 11486 11487**示例：** 11488 11489```ts 11490import { BusinessError } from '@kit.BasicServicesKit'; 11491 11492let isPrivacyMode: boolean = true; 11493windowClass.setPrivacyMode(isPrivacyMode, (err: BusinessError) => { 11494 const errCode: number = err.code; 11495 if (errCode) { 11496 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 11497 return; 11498 } 11499 console.info('Succeeded in setting the window to privacy mode.'); 11500}); 11501``` 11502 11503## setPrivacyMode<sup>(deprecated)</sup> 11504 11505setPrivacyMode(isPrivacyMode: boolean): Promise<void> 11506 11507设置窗口是否为隐私模式，使用Promise异步回调。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。 11508 11509> **说明：** 11510> 11511> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowPrivacyMode()](#setwindowprivacymode9-1)。 11512 11513**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11514 11515**参数：** 11516 11517| 参数名 | 类型 | 必填 | 说明 | 11518| ------------- | ------- | ---- | -------------------- | 11519| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 11520 11521**返回值：** 11522 11523| 类型 | 说明 | 11524| ------------------- | ------------------------- | 11525| Promise<void> | 无返回结果的Promise对象。 | 11526 11527**示例：** 11528 11529```ts 11530import { BusinessError } from '@kit.BasicServicesKit'; 11531 11532let isPrivacyMode: boolean = true; 11533let promise = windowClass.setPrivacyMode(isPrivacyMode); 11534promise.then(() => { 11535 console.info('Succeeded in setting the window to privacy mode.'); 11536}).catch((err: BusinessError) => { 11537 console.error(`Failed to set the window to privacy mode. Cause code: ${err.code}, message: ${err.message}`); 11538}); 11539``` 11540 11541## setTouchable<sup>(deprecated)</sup> 11542 11543setTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void 11544 11545设置窗口是否为可触状态，使用callback异步回调。 11546 11547> **说明：** 11548> 11549> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowTouchable()](#setwindowtouchable9)。 11550 11551**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11552 11553**参数：** 11554 11555| 参数名 | 类型 | 必填 | 说明 | 11556| ----------- | ------------------------- | ---- | -------------------- | 11557| isTouchable | boolean | 是 | 窗口是否为可触状态。true表示可触；false表示不可触。 | 11558| callback | AsyncCallback<void> | 是 | 回调函数。 | 11559 11560 11561**示例：** 11562 11563```ts 11564import { BusinessError } from '@kit.BasicServicesKit'; 11565 11566let isTouchable = true; 11567windowClass.setTouchable(isTouchable, (err: BusinessError) => { 11568 const errCode: number = err.code; 11569 if (errCode) { 11570 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 11571 return; 11572 } 11573 console.info('Succeeded in setting the window to be touchable.'); 11574}); 11575``` 11576 11577## setTouchable<sup>(deprecated)</sup> 11578 11579setTouchable(isTouchable: boolean): Promise<void> 11580 11581设置窗口是否为可触状态，使用Promise异步回调。 11582 11583> **说明：** 11584> 11585> 从API version 7开始支持，从API version 9开始废弃，推荐使用[setWindowTouchable()](#setwindowtouchable9-1)。 11586 11587**系统能力：** SystemCapability.WindowManager.WindowManager.Core 11588 11589**参数：** 11590 11591| 参数名 | 类型 | 必填 | 说明 | 11592| ----------- | ------- | ---- | -------------------- | 11593| isTouchable | boolean | 是 | 窗口是否为可触状态。true表示可触；false表示不可触。 | 11594 11595**返回值：** 11596 11597| 类型 | 说明 | 11598| ------------------- | ------------------------- | 11599| Promise<void> | 无返回结果的Promise对象。 | 11600 11601 11602**示例：** 11603 11604```ts 11605import { BusinessError } from '@kit.BasicServicesKit'; 11606 11607let isTouchable = true; 11608let promise = windowClass.setTouchable(isTouchable); 11609promise.then(() => { 11610 console.info('Succeeded in setting the window to be touchable.'); 11611}).catch((err: BusinessError) => { 11612 console.error(`Failed to set the window to be touchable. Cause code: ${err.code}, message: ${err.message}`); 11613}); 11614```