1# @ohos.display (屏幕属性) 2 3屏幕属性提供管理显示设备的一些基础能力，包括获取默认显示设备的信息，获取所有显示设备的信息以及监听显示设备的插拔行为。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { display } from '@kit.ArkUI'; 13``` 14 15## DisplayState 16 17显示设备的状态枚举。 18 19**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 20 21**系统能力：** SystemCapability.WindowManager.WindowManager.Core 22 23| 名称 | 值 | 说明 | 24| -------- | -------- | -------- | 25| STATE_UNKNOWN | 0 | 表示显示设备状态未知。| 26| STATE_OFF | 1 | 表示显示设备状态为关闭。 | 27| STATE_ON | 2 | 表示显示设备状态为开启。| 28| STATE_DOZE | 3 | 表示显示设备为低电耗模式。| 29| STATE_DOZE_SUSPEND | 4 | 表示显示设备为睡眠模式，CPU为挂起状态。 | 30| STATE_VR | 5 | 表示显示设备为VR模式。| 31| STATE_ON_SUSPEND | 6 | 表示显示设备为开启状态，CPU为挂起状态。 | 32 33## Orientation<sup>10+</sup> 34 35显示设备当前显示的方向枚举。 36 37**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 38 39**系统能力：** SystemCapability.WindowManager.WindowManager.Core 40 41| 名称 | 值 | 说明 | 42| -------- | -------- | -------- | 43| PORTRAIT | 0 | 表示设备当前以竖屏方式显示。| 44| LANDSCAPE | 1 | 表示设备当前以横屏方式显示。 | 45| PORTRAIT_INVERTED | 2 | 表示设备当前以反向竖屏方式显示。| 46| LANDSCAPE_INVERTED | 3 | 表示设备当前以反向横屏方式显示。| 47 48## FoldStatus<sup>10+</sup> 49 50当前可折叠设备的折叠状态枚举。 51 52**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 53 54**系统能力：** SystemCapability.Window.SessionManager 55 56| 名称 | 值 | 说明 | 57| -------- | -------- | -------- | 58| FOLD_STATUS_UNKNOWN | 0 | 表示设备当前折叠状态未知。| 59| FOLD_STATUS_EXPANDED | 1 | 表示设备当前折叠状态为完全展开。| 60| FOLD_STATUS_FOLDED | 2 | 表示设备当前折叠状态为折叠。| 61| FOLD_STATUS_HALF_FOLDED | 3 | 表示设备当前折叠状态为半折叠。半折叠指完全展开和折叠之间的状态。| 62 63## FoldDisplayMode<sup>10+</sup> 64 65可折叠设备的显示模式枚举。 66 67**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 68 69**系统能力：** SystemCapability.Window.SessionManager 70 71| 名称 | 值 | 说明 | 72| -------- | -------- | -------- | 73| FOLD_DISPLAY_MODE_UNKNOWN | 0 | 表示设备当前折叠显示模式未知。| 74| FOLD_DISPLAY_MODE_FULL | 1 | 表示设备当前全屏显示。 | 75| FOLD_DISPLAY_MODE_MAIN | 2 | 表示设备当前主屏幕显示。| 76| FOLD_DISPLAY_MODE_SUB | 3 | 表示设备当前子屏幕显示。| 77| FOLD_DISPLAY_MODE_COORDINATION | 4 | 表示设备当前双屏协同显示。| 78 79>**说明：**<br> 80>• 对于大屏内折产品，内屏显示状态为FOLD_DISPLAY_MODE_FULL，外屏显示状态为FOLD_DISPLAY_MODE_MAIN。<br> 81>• 对于小屏内折产品，内屏显示状态为FOLD_DISPLAY_MODE_MAIN，外屏显示状态为FOLD_DISPLAY_MODE_SUB。 82 83## FoldCreaseRegion<sup>10+</sup> 84 85折叠折痕区域。 86 87**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 88 89**系统能力：** SystemCapability.Window.SessionManager 90 91| 名称 | 类型 | 可读 | 可写 | 说明 | 92| ------ | -------- | ---- | ---- | ------------------ | 93| displayId | number | 是 | 否 | 显示器ID，用于识别折痕所在的屏幕。 | 94| creaseRects | Array\<[Rect](#rect9)> | 是 | 否 | 折痕区域。 | 95 96## Rect<sup>9+</sup> 97 98矩形区域。 99 100**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 101 102**系统能力：** SystemCapability.WindowManager.WindowManager.Core 103 104| 名称 | 类型 | 可读 | 可写 | 说明 | 105| ------ | -------- | ---- | ---- | ------------------ | 106| left | number | 是 | 是 | 矩形区域的左边界，单位为px，该参数应为整数。 | 107| top | number | 是 | 是 | 矩形区域的上边界，单位为px，该参数应为整数。 | 108| width | number | 是 | 是 | 矩形区域的宽度，单位为px，该参数应为整数。 | 109| height | number | 是 | 是 | 矩形区域的高度，单位为px，该参数应为整数。 | 110 111## WaterfallDisplayAreaRects<sup>9+</sup> 112 113瀑布屏曲面部分显示区域。 114 115**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 116 117**系统能力：** SystemCapability.WindowManager.WindowManager.Core 118 119| 名称 | 类型 | 可读 | 可写 | 说明 | 120| ------ | ------------- | ---- | ---- | ------------------ | 121| left | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的左侧矩形区域。 | 122| top | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的顶部矩形区域。 | 123| right | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的右侧矩形区域。 | 124| bottom | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的底部矩形区域。 | 125 126## CutoutInfo<sup>9+</sup> 127 128挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。 129 130**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 131 132**系统能力：** SystemCapability.WindowManager.WindowManager.Core 133 134| 名称 | 类型 | 可读 | 可写 | 说明 | 135| --------------------------- | ------------- | ---- | ---- | ------------------ | 136| boundingRects | Array\<[Rect](#rect9)> | 是 | 否 | 挖孔、刘海等区域的边界矩形。 | 137| waterfallDisplayAreaRects | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | 是 | 否 | 瀑布屏曲面部分显示区域。 | 138 139## DisplayPhysicalResolution<sup>12+</sup> 140折叠设备的显示模式以及对应的物理屏幕分辨率信息。 141 142**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 143 144**系统能力：** SystemCapability.WindowManager.WindowManager.Core 145 146| 名称 | 类型 | 只读 | 可选 | 说明 | 147| --------------------------- | ------------- | ---- | ---- | ------------------ | 148| foldDisplayMode | [FoldDisplayMode](#folddisplaymode10) | 是 | 否 | 折叠设备的显示模式。 | 149| physicalWidth | number | 是 | 否 | 折叠设备的宽度，单位为px，该参数应为大于0的整数。| 150| physicalHeight | number | 是 | 否 | 折叠设备的高度，单位为px，该参数应为大于0的整数。| 151 152## display.getDisplayByIdSync<sup>12+</sup> 153 154getDisplayByIdSync(displayId: number): Display 155 156根据displayId获取对应的display对象。 157 158**系统能力：** SystemCapability.WindowManager.WindowManager.Core 159 160**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 161 162**参数：** 163 164| 参数名 | 类型 | 必填 | 说明 | 165| ------ | ------------------------- | ---- |----------| 166| displayId | number | 是 | 屏幕id。该参数仅支持整数输入，该参数大于等于0。需要确保displayId准确才能成功获取到对应结果。可以通过[WindowProperties](js-apis-window.md#windowproperties)的displayId属性获取到准确的displayId作为入参。 | 167 168**返回值：** 169 170| 类型 | 说明 | 171| ------------------------------| ----------------------------------------------| 172| [Display](#display) | 返回displayId对应的display对象。 | 173 174**错误码：** 175 176以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 177 178| 错误码ID | 错误信息 | 179| ------- | ----------------------- | 180| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types. 3. Parameter verification failed.| 181| 1400003 | This display manager service works abnormally. | 182 183**示例：** 184 185```ts 186import { display } from '@kit.ArkUI'; 187 188let displayClass: display.Display | null = null; 189 190try { 191 // 可以通过WindowProperties的displayId属性获取到准确的displayId作为入参 192 let displayId = 0; 193 displayClass = display.getDisplayByIdSync(displayId); 194} catch (exception) { 195 console.error(`Failed to get display. Code: ${exception.code}, message: ${exception.message}`); 196} 197``` 198 199## display.getAllDisplayPhysicalResolution<sup>12+</sup> 200 201getAllDisplayPhysicalResolution(): Promise<Array<DisplayPhysicalResolution>> 202 203获取当前折叠设备的显示模式以及对应的物理屏幕分辨率信息对象。 204 205**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 206 207**系统能力：** SystemCapability.WindowManager.WindowManager.Core 208 209**返回值：** 210 211| 类型 | 说明 | 212| ----------------------------------------------- | ------------------------------------------------------- | 213| Promise<Array<[DisplayPhysicalResolution](#displayphysicalresolution12)>> | Promise对象。返回当前所有的DisplayPhysicalResolution对象。 | 214 215**错误码：** 216 217以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 218 219| 错误码ID | 错误信息 | 220| ------- | ----------------------- | 221| 1400003 | This display manager service works abnormally. | 222 223**示例：** 224 225```ts 226import { BusinessError } from '@kit.BasicServicesKit'; 227import { display } from '@kit.ArkUI'; 228 229let promise = display.getAllDisplayPhysicalResolution(); 230promise.then((resolutionObjects) => { 231 console.info('Obtaining physical resolution length: ' + resolutionObjects.length); 232 for (let i = 0; i < resolutionObjects.length; i++) { 233 console.info(`resolutionObjects[${i}].foldDisplayMode: ${resolutionObjects[i].foldDisplayMode}`); 234 console.info(`resolutionObjects[${i}].physicalWidth: ${resolutionObjects[i].physicalWidth}`); 235 console.info(`resolutionObjects[${i}].physicalHeight: ${resolutionObjects[i].physicalHeight}`); 236 } 237}).catch((err: BusinessError) => { 238 console.error(`Failed to obtain physical resolution. Code: ${err.code}, message: ${err.message}`); 239}); 240``` 241 242## display.getDefaultDisplaySync<sup>9+</sup> 243 244getDefaultDisplaySync(): Display 245 246获取当前默认的display对象。 247 248**系统能力：** SystemCapability.WindowManager.WindowManager.Core 249 250**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 251 252**返回值：** 253 254| 类型 | 说明 | 255| ------------------------------| ----------------------------------------------| 256| [Display](#display) | 返回默认的display对象。 | 257 258**错误码：** 259 260以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 261 262| 错误码ID | 错误信息 | 263| ------- | ----------------------- | 264| 1400001 | Invalid display or screen. | 265 266**示例：** 267 268```ts 269import { display } from '@kit.ArkUI'; 270 271let displayClass: display.Display | null = null; 272 273displayClass = display.getDefaultDisplaySync(); 274``` 275 276## display.getPrimaryDisplaySync<sup>14+</sup> 277 278getPrimaryDisplaySync(): Display 279 280获取主屏信息。除2in1之外的设备获取的是设备自带屏幕的Display对象；2in1设备外接屏幕时获取的是当前主屏幕的Display对象；2in1设备没有外接屏幕时获取的是自带屏幕的Display对象。 281 282**系统能力：** SystemCapability.WindowManager.WindowManager.Core 283 284**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 285 286**返回值：** 287 288| 类型 | 说明 | 289| ------------------------------| ----------------------------------------------| 290| [Display](#display) | 当前设备主屏幕的Display对象。 | 291 292**错误码：** 293 294以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 295 296| 错误码ID | 错误信息 | 297| ------- | ----------------------- | 298| 1400001 | Invalid display or screen. | 299 300**示例：** 301 302```ts 303import { display } from '@kit.ArkUI'; 304 305let displayClass: display.Display | null = null; 306 307displayClass = display.getPrimaryDisplaySync(); 308``` 309 310## display.getAllDisplays<sup>9+</sup> 311 312getAllDisplays(callback: AsyncCallback<Array<Display>>): void 313 314获取当前所有的display对象，使用callback异步回调。 315 316**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 317 318**系统能力：** SystemCapability.WindowManager.WindowManager.Core 319 320**参数：** 321 322| 参数名 | 类型 | 必填 | 说明 | 323| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 324| callback | AsyncCallback<Array<[Display](#display)>> | 是 | 回调函数。返回当前所有的display对象。 | 325 326**错误码：** 327 328以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 329 330| 错误码ID | 错误信息 | 331| ------- | ----------------------- | 332| 1400001 | Invalid display or screen. | 333 334**示例：** 335 336```ts 337import { BusinessError } from '@kit.BasicServicesKit'; 338import { display } from '@kit.ArkUI'; 339 340let displayClass: Array<display.Display> = []; 341display.getAllDisplays((err: BusinessError, data: Array<display.Display>) => { 342 displayClass = data; 343 const errCode: number = err.code; 344 if (errCode) { 345 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 346 return; 347 } 348 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 349}); 350``` 351 352## display.getAllDisplays<sup>9+</sup> 353 354getAllDisplays(): Promise<Array<Display>> 355 356获取当前所有的display对象，使用Promise异步回调。 357 358**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 359 360**系统能力：** SystemCapability.WindowManager.WindowManager.Core 361 362**返回值：** 363 364| 类型 | 说明 | 365| ----------------------------------------------- | ------------------------------------------------------- | 366| Promise<Array<[Display](#display)>> | Promise对象。返回当前所有的display对象。 | 367 368**错误码：** 369 370以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 371 372| 错误码ID | 错误信息 | 373| ------- | ----------------------- | 374| 1400001 | Invalid display or screen. | 375 376**示例：** 377 378```ts 379import { BusinessError } from '@kit.BasicServicesKit'; 380import { display } from '@kit.ArkUI'; 381 382let displayClass: Array<display.Display> =[]; 383let promise: Promise<Array<display.Display>> = display.getAllDisplays(); 384promise.then((data: Array<display.Display>) => { 385 displayClass = data; 386 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 387}).catch((err: BusinessError) => { 388 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 389}); 390``` 391 392## display.on('add'|'remove'|'change') 393 394on(type: 'add'|'remove'|'change', callback: Callback<number>): void 395 396开启显示设备变化的监听。 397 398**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 399 400**系统能力：** SystemCapability.WindowManager.WindowManager.Core 401 402**参数：** 403 404| 参数名 | 类型 | 必填 | 说明 | 405| -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------------------------| 406| type | string | 是 | 监听事件。<br/>- type为"add"，表示增加显示设备事件。例如：插入显示器。<br/>- type为"remove"，表示移除显示设备事件。例如：移除显示器。<br/>- type为"change"，表示改变显示设备事件。例如：显示器方向改变。 | 407| callback | Callback<number> | 是 | 回调函数。返回监听到的显示设备的id，该参数应为整数。 | 408 409**错误码：** 410 411以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 412 413| 错误码ID | 错误信息 | 414| ------- | ----------------------- | 415| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 416 417**示例：** 418 419```ts 420import { Callback } from '@kit.BasicServicesKit'; 421 422let callback: Callback<number> = (data: number) => { 423 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 424}; 425 426display.on("add", callback); 427``` 428 429## display.off('add'|'remove'|'change') 430 431off(type: 'add'|'remove'|'change', callback?: Callback<number>): void 432 433关闭显示设备变化的监听。 434 435**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 436 437**系统能力：** SystemCapability.WindowManager.WindowManager.Core 438 439**参数：** 440 441| 参数名 | 类型 | 必填 | 说明 | 442| -------- | -------- | -------- | -------- | 443| type | string | 是 | 监听事件。<br/>- type为"add"，表示增加显示设备事件。例如：插入显示器。<br/>- type为"remove"，表示移除显示设备事件。例如：移除显示器。<br/>- type为"change"，表示改变显示设备事件。例如：显示器方向改变。 | 444| callback | Callback<number> | 否 | 需要取消注册的回调函数。若无此参数，则取消注册当前type类型事件监听的所有回调函数。 | 445 446**错误码：** 447 448以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 449 450| 错误码ID | 错误信息 | 451| ------- | ----------------------- | 452| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 453 454**示例：** 455 456```ts 457 458// 如果通过on注册多个callback，同时关闭所有callback监听 459display.off("remove"); 460 461let callback: Callback<number> = (data: number) => { 462 console.info('Succeeded in unregistering the callback for display remove. Data: ' + JSON.stringify(data)) 463}; 464// 关闭传入的callback监听 465display.off('remove', callback); 466``` 467 468## display.isFoldable<sup>10+</sup> 469isFoldable(): boolean 470 471检查设备是否可折叠。 472 473**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 474 475**系统能力：** SystemCapability.Window.SessionManager 476 477**返回值：** 478 479| 类型 | 说明 | 480| ----------------------------------------------- | ------------------------------------------------------- | 481| boolean | boolean对象，返回当前设备是否可折叠的结果。false表示不可折叠，true表示可折叠。| 482 483**错误码：** 484 485以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 486 487| 错误码ID | 错误信息 | 488| ------- | ----------------------- | 489| 1400003 | This display manager service works abnormally. | 490 491**示例：** 492 493```ts 494import { display } from '@kit.ArkUI'; 495 496let ret: boolean = false; 497ret = display.isFoldable(); 498``` 499 500## display.getFoldStatus<sup>10+</sup> 501getFoldStatus(): FoldStatus 502 503获取可折叠设备的当前折叠状态。 504 505**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 506 507**系统能力：** SystemCapability.Window.SessionManager 508 509**返回值：** 510 511| 类型 | 说明 | 512| ----------------------------------------------- | ------------------------------------------------------- | 513| [FoldStatus](#foldstatus10) | FoldStatus对象，返回当前可折叠设备的折叠状态。 | 514 515**错误码：** 516 517以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 518 519| 错误码ID | 错误信息 | 520| ------- | ----------------------- | 521| 1400003 | This display manager service works abnormally. | 522 523**示例：** 524 525```ts 526import { display } from '@kit.ArkUI'; 527 528let data: display.FoldStatus = display.getFoldStatus(); 529console.info('Succeeded in obtaining fold status. Data: ' + JSON.stringify(data)); 530``` 531 532## display.getFoldDisplayMode<sup>10+</sup> 533getFoldDisplayMode(): FoldDisplayMode 534 535获取可折叠设备的显示模式。 536 537**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 538 539**系统能力：** SystemCapability.Window.SessionManager 540 541**返回值：** 542 543| 类型 | 说明 | 544| ----------------------------------------------- | ------------------------------------------------------- | 545| [FoldDisplayMode](#folddisplaymode10) | FoldDisplayMode对象，返回当前可折叠设备的显示模式。 | 546 547**错误码：** 548 549以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 550 551| 错误码ID | 错误信息 | 552| ------- | ----------------------- | 553| 1400003 | This display manager service works abnormally. | 554 555**示例：** 556 557```ts 558import { display } from '@kit.ArkUI'; 559 560let data: display.FoldDisplayMode = display.getFoldDisplayMode(); 561console.info('Succeeded in obtaining fold display mode. Data: ' + JSON.stringify(data)); 562``` 563 564## display.getCurrentFoldCreaseRegion<sup>10+</sup> 565getCurrentFoldCreaseRegion(): FoldCreaseRegion 566 567在当前显示模式下获取折叠折痕区域。 568 569**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 570 571**系统能力：** SystemCapability.Window.SessionManager 572 573**返回值：** 574 575| 类型 | 说明 | 576| ----------------------------------------------- | ------------------------------------------------------- | 577| [FoldCreaseRegion](#foldcreaseregion10) | FoldCreaseRegion对象，返回设备在当前显示模式下的折叠折痕区域。 | 578 579**错误码：** 580 581以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 582 583| 错误码ID | 错误信息 | 584| ------- | ----------------------- | 585| 1400003 | This display manager service works abnormally. | 586 587**示例：** 588 589```ts 590import { display } from '@kit.ArkUI'; 591 592let data: display.FoldCreaseRegion = display.getCurrentFoldCreaseRegion(); 593console.info('Succeeded in obtaining current fold crease region. Data: ' + JSON.stringify(data)); 594``` 595 596## display.on('foldStatusChange')<sup>10+</sup> 597 598on(type: 'foldStatusChange', callback: Callback<FoldStatus>): void 599 600开启折叠设备折叠状态变化的监听。 601 602本接口监听设备物理折叠状态的变化，[display.on('foldDispla 603yModeChange')](#displayonfolddisplaymodechange10)则监听屏幕显示模式的变化。 604 605两者存在差异，时序上物理折叠状态变化在前，底层会根据物理折叠状态匹配屏幕显示模式状态。 606 607若需监听当前显示内容是显示在折叠设备的内屏还是外屏，请使用[display.on('foldDisplayModeChange')](#displayonfolddisplaymodechange10)。 608 609**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 610 611**系统能力：** SystemCapability.Window.SessionManager 612 613**参数：** 614 615| 参数名 | 类型 | 必填 | 说明 | 616| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 617| type | string | 是 | 监听事件，固定为'foldStatusChange'，表示折叠设备折叠状态发生变化。 | 618| callback | Callback<[FoldStatus](#foldstatus10)> | 是 | 回调函数。表示折叠设备折叠状态。 | 619 620**错误码：** 621 622以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 623 624| 错误码ID | 错误信息 | 625| ------- | ----------------------- | 626| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 627| 1400003 | This display manager service works abnormally. | 628 629**示例：** 630 631```ts 632import { Callback } from '@kit.BasicServicesKit'; 633 634/** 635 * 注册监听的callback参数要采用对象传递. 636 * 若使用匿名函数注册，每次调用会创建一个新的底层对象，引起内存泄漏问题。 637*/ 638let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 639 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 640}; 641display.on('foldStatusChange', callback); 642``` 643 644## display.off('foldStatusChange')<sup>10+</sup> 645 646off(type: 'foldStatusChange', callback?: Callback<FoldStatus>): void 647 648关闭折叠设备折叠状态变化的监听。 649 650**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 651 652**系统能力：** SystemCapability.Window.SessionManager 653 654**参数：** 655 656| 参数名 | 类型 | 必填 | 说明 | 657| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 658| type | string | 是 | 监听事件，固定为'foldStatusChange'，表示折叠设备折叠状态发生变化。 | 659| callback | Callback<[FoldStatus](#foldstatus10)> | 否 | 需要取消注册的回调函数。若无此参数，则取消注册折叠状态变化监听的所有回调函数。 | 660 661**错误码：** 662 663以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 664 665| 错误码ID | 错误信息 | 666| ------- | ----------------------- | 667| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 668| 1400003 | This display manager service works abnormally. | 669 670**示例：** 671 672```ts 673 674// 如果通过on注册多个callback，同时关闭所有callback监听 675display.off('foldStatusChange'); 676 677let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 678 console.info('unregistering FoldStatus changes callback. Data: ' + JSON.stringify(data)); 679}; 680// 关闭传入的callback监听 681display.off('foldStatusChange', callback); 682``` 683 684## display.on('foldAngleChange')<sup>12+</sup> 685 686on(type: 'foldAngleChange', callback: Callback<Array<number>>): void 687 688开启折叠设备折叠角度变化的监听。 689 690**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 691 692**系统能力：** SystemCapability.Window.SessionManager 693 694**参数：** 695 696| 参数名 | 类型 | 必填 | 说明 | 697| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 698| type | string | 是 | 监听事件，固定为'foldAngleChange'，表示折叠设备折叠角度发生变化。| 699| callback | Callback<Array<number>> | 是 | 回调函数。表示折叠设备屏幕折叠角度值（0度~180度）。| 700 701**错误码：** 702 703以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 704 705| 错误码ID | 错误信息 | 706| ------- | ----------------------- | 707| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 708| 1400003 | This display manager service works abnormally. | 709 710**示例：** 711 712```ts 713import { Callback } from '@kit.BasicServicesKit'; 714 715let callback: Callback<Array<number>> = (angles: Array<number>) => { 716 console.info('Listening fold angles length: ' + angles.length); 717}; 718display.on('foldAngleChange', callback); 719``` 720 721## display.off('foldAngleChange')<sup>12+</sup> 722 723off(type: 'foldAngleChange', callback?: Callback<Array<number>>): void 724 725关闭折叠设备折叠角度变化的监听。 726 727**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 728 729**系统能力：** SystemCapability.Window.SessionManager 730 731**参数：** 732 733| 参数名 | 类型 | 必填 | 说明 | 734| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 735| type | string | 是 | 监听事件，固定为'foldAngleChange'表示折叠设备折叠角度发生变化。| 736| callback | Callback<Array<number>> | 否 | 需要取消注册的回调函数。若无此参数，则取消注册折叠角度变化监听的所有回调函数。| 737 738**错误码：** 739 740以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 741 742| 错误码ID | 错误信息 | 743| ------- | ----------------------- | 744| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 745| 1400003 | This display manager service works abnormally. | 746 747**示例：** 748 749```ts 750display.off('foldAngleChange'); 751``` 752 753## display.on('captureStatusChange')<sup>12+</sup> 754 755on(type: 'captureStatusChange', callback: Callback<boolean>): void 756 757开启屏幕截屏、投屏、录屏状态变化的监听。 758 759**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 760 761**系统能力：** SystemCapability.Window.SessionManager 762 763**参数：** 764 765| 参数名 | 类型 | 必填 | 说明 | 766| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 767| type | string | 是 | 监听事件，固定为'captureStatusChange'表示设备截屏、投屏或者录屏状态发生变化。| 768| callback | Callback<boolean> | 是 | 回调函数。表示设备截屏、投屏、录屏状态发生变化。true表示设备开始截屏、投屏或者录屏，false表示结束截屏、投屏、录屏。| 769 770**错误码：** 771 772以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 773 774| 错误码ID | 错误信息 | 775| ------- | ----------------------- | 776| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 777| 1400003 | This display manager service works abnormally. | 778 779**示例：** 780 781```ts 782import { Callback } from '@kit.BasicServicesKit'; 783 784let callback: Callback<boolean> = (captureStatus: boolean) => { 785 console.info('Listening capture status: ' + captureStatus); 786}; 787display.on('captureStatusChange', callback); 788``` 789 790## display.off('captureStatusChange')<sup>12+</sup> 791 792off(type: 'captureStatusChange', callback?: Callback<boolean>): void 793 794关闭屏幕截屏、投屏、录屏状态变化的监听。 795 796**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 797 798**系统能力：** SystemCapability.Window.SessionManager 799 800**参数：** 801 802| 参数名 | 类型 | 必填 | 说明 | 803| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 804| type | string | 是 | 监听事件，固定为'captureStatusChange'表示设备截屏、投屏、录屏状态发生变化。| 805| callback | Callback<boolean> | 否 | 需要取消注册的回调函数。若无此参数，则取消注册截屏、投屏、录屏状态变化监听的所有回调函数。| 806 807**错误码：** 808 809以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 810 811| 错误码ID | 错误信息 | 812| ------- | ----------------------- | 813| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 814| 1400003 | This display manager service works abnormally. | 815 816**示例：** 817 818```ts 819display.off('captureStatusChange'); 820``` 821 822## display.isCaptured<sup>12+</sup> 823isCaptured(): boolean 824 825检查设备是否正在截屏、投屏、录屏。 826 827**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 828 829**系统能力：** SystemCapability.Window.SessionManager 830 831**返回值：** 832 833| 类型 | 说明 | 834| ----------------------------------------------- | ------------------------------------------------------- | 835| boolean | boolean值，返回当前设备是否有截屏、投屏或者录屏。true表示有截屏、投屏、录屏，否则返回false。| 836 837**错误码：** 838 839以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 840 841| 错误码ID | 错误信息 | 842| ------- | ----------------------- | 843| 1400003 | This display manager service works abnormally. | 844 845**示例：** 846 847```ts 848import { display } from '@kit.ArkUI'; 849 850let ret: boolean = false; 851ret = display.isCaptured(); 852``` 853 854## display.on('foldDisplayModeChange')<sup>10+</sup> 855 856on(type: 'foldDisplayModeChange', callback: Callback<FoldDisplayMode>): void 857 858开启折叠设备屏幕显示模式变化的监听。 859 860本接口监听设备屏幕显示模式的变化，[display.on('foldStatusChange')](#displayonfoldstatuschange10)则监听设备物理折叠状态的变化。 861 862两者存在差异，时序上物理折叠状态变化在前，底层会根据物理折叠状态匹配屏幕显示模式状态。 863 864**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 865 866**系统能力：** SystemCapability.Window.SessionManager 867 868**参数：** 869 870| 参数名 | 类型 | 必填 | 说明 | 871| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 872| type | string | 是 | 监听事件，固定为'foldDisplayModeChange'，表示折叠设备屏幕显示模式发生变化。 | 873| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | 是 | 回调函数。表示折叠设备屏幕显示模式。 | 874 875**错误码：** 876 877以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 878 879| 错误码ID | 错误信息 | 880| ------- | ----------------------- | 881| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 882| 1400003 | This display manager service works abnormally. | 883 884**示例：** 885 886```ts 887import { Callback } from '@kit.BasicServicesKit'; 888 889/** 890 * 注册监听的callback参数要采用对象传递. 891 * 若使用匿名函数注册，每次调用会创建一个新的底层对象，引起内存泄漏问题。 892*/ 893let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 894 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 895}; 896display.on('foldDisplayModeChange', callback); 897``` 898 899## display.off('foldDisplayModeChange')<sup>10+</sup> 900 901off(type: 'foldDisplayModeChange', callback?: Callback<FoldDisplayMode>): void 902 903关闭折叠设备屏幕显示模式变化的监听。 904 905**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 906 907**系统能力：** SystemCapability.Window.SessionManager 908 909**参数：** 910 911| 参数名 | 类型 | 必填 | 说明 | 912| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 913| type | string | 是 | 监听事件，固定为'foldDisplayModeChange'，表示折叠设备屏幕显示模式发生变化。 | 914| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | 否 | 需要取消注册的回调函数。若无此参数，则取消注册屏幕显示模式变化监听的所有回调函数。 | 915 916**错误码：** 917 918以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 919 920| 错误码ID | 错误信息 | 921| ------- | ----------------------- | 922| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 923| 1400003 | This display manager service works abnormally. | 924 925**示例：** 926 927```ts 928 929// 如果通过on注册多个callback，同时关闭所有callback监听 930display.off('foldDisplayModeChange'); 931 932let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 933 console.info('unregistering FoldDisplayMode changes callback. Data: ' + JSON.stringify(data)); 934}; 935// 关闭传入的callback监听 936display.off('foldDisplayModeChange', callback); 937``` 938 939 940## display.getDefaultDisplay<sup>(deprecated)</sup> 941 942getDefaultDisplay(callback: AsyncCallback<Display>): void 943 944获取当前默认的display对象，使用callback异步回调。 945 946> **说明：** 947> 948> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。 949 950**系统能力：** SystemCapability.WindowManager.WindowManager.Core 951 952**参数：** 953 954| 参数名 | 类型 | 必填 | 说明 | 955| -------- | -------- | -------- | -------- | 956| callback | AsyncCallback<[Display](#display)> | 是 | 回调函数。返回当前默认的display对象。 | 957 958**示例：** 959 960```ts 961import { BusinessError } from '@kit.BasicServicesKit'; 962 963let displayClass: display.Display | null = null; 964display.getDefaultDisplay((err: BusinessError, data: display.Display) => { 965 const errCode: number = err.code; 966 if (errCode) { 967 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 968 return; 969 } 970 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 971 displayClass = data; 972}); 973``` 974 975## display.getDefaultDisplay<sup>(deprecated)</sup> 976 977getDefaultDisplay(): Promise<Display> 978 979获取当前默认的display对象，使用Promise异步回调。 980 981> **说明：** 982> 983> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。 984 985**系统能力：** SystemCapability.WindowManager.WindowManager.Core 986 987**返回值：** 988 989| 类型 | 说明 | 990| ---------------------------------- | ---------------------------------------------- | 991| Promise<[Display](#display)> | Promise对象。返回当前默认的display对象。 | 992 993**示例：** 994 995```ts 996import { BusinessError } from '@kit.BasicServicesKit'; 997 998let displayClass: display.Display | null = null; 999let promise: Promise<display.Display> = display.getDefaultDisplay(); 1000promise.then((data: display.Display) => { 1001 displayClass = data; 1002 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 1003}).catch((err: BusinessError) => { 1004 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 1005}); 1006``` 1007 1008## display.getAllDisplay<sup>(deprecated)</sup> 1009 1010getAllDisplay(callback: AsyncCallback<Array<Display>>): void 1011 1012获取当前所有的display对象，使用callback异步回调。 1013 1014> **说明：** 1015> 1016> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9)。 1017 1018**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1019 1020**参数：** 1021 1022| 参数名 | 类型 | 必填 | 说明 | 1023| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 1024| callback | AsyncCallback<Array<[Display](#display)>> | 是 | 回调函数。返回当前所有的display对象。 | 1025 1026**示例：** 1027 1028```ts 1029import { BusinessError } from '@kit.BasicServicesKit'; 1030 1031display.getAllDisplay((err: BusinessError, data: Array<display.Display>) => { 1032 const errCode: number = err.code; 1033 if (errCode) { 1034 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1035 return; 1036 } 1037 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1038}); 1039``` 1040 1041## display.getAllDisplay<sup>(deprecated)</sup> 1042 1043getAllDisplay(): Promise<Array<Display>> 1044 1045获取当前所有的display对象，使用Promise异步回调。 1046 1047> **说明：** 1048> 1049> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9-1)。 1050 1051**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1052 1053**返回值：** 1054 1055| 类型 | 说明 | 1056| ----------------------------------------------- | ------------------------------------------------------- | 1057| Promise<Array<[Display](#display)>> | Promise对象。返回当前所有的display对象。 | 1058 1059**示例：** 1060 1061```ts 1062import { BusinessError } from '@kit.BasicServicesKit'; 1063 1064let promise: Promise<Array<display.Display>> = display.getAllDisplay(); 1065promise.then((data: Array<display.Display>) => { 1066 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1067}).catch((err: BusinessError) => { 1068 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1069}); 1070``` 1071 1072## Display 1073屏幕实例。描述display对象的属性和方法。 1074 1075下列API示例中都需先使用[getAllDisplays()](#displaygetalldisplays9)、[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)中的任一方法获取到Display实例，再通过此实例调用对应方法。 1076 1077### 属性 1078 1079**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1080 1081| 名称 | 类型 | 只读 | 可选 | 说明 | 1082| -------- | -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------| 1083| id | number | 是 | 否 | 显示设备的id号，该参数应为整数。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1084| name | string | 是 | 否 | 显示设备的名称。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1085| alive | boolean | 是 | 否 | 显示设备是否启用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1086| state | [DisplayState](#displaystate) | 是 | 否 | 显示设备的状态。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1087| refreshRate | number | 是 | 否 | 显示设备的刷新率，该参数应为整数，单位为hz。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1088| rotation | number | 是 | 否 | 显示设备的屏幕顺时针旋转角度。<br>值为0时，表示显示设备屏幕顺时针旋转为0°；<br>值为1时，表示显示设备屏幕顺时针旋转为90°；<br>值为2时，表示显示设备屏幕顺时针旋转为180°；<br>值为3时，表示显示设备屏幕顺时针旋转为270°。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1089| width | number | 是 | 否 | 显示设备的屏幕宽度，单位为px，该参数应为整数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1090| height | number | 是 | 否 | 显示设备的屏幕高度，单位为px，该参数应为整数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1091| densityDPI | number | 是 | 否 | 显示设备屏幕的物理像素密度，表示每英寸上的像素点数。该参数为浮点数，单位为px。一般取值160.0、480.0等，实际能取到的值取决于不同设备设置里提供的可选值。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1092| orientation<sup>10+</sup> | [Orientation](#orientation10) | 是 | 否 | 表示屏幕当前显示的方向。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1093| densityPixels | number | 是 | 否 | 显示设备逻辑像素的密度，代表物理像素与逻辑像素的缩放系数，计算方式为：<br>该参数为浮点数，受densityDPI范围限制，取值范围在[0.5，4.0]。一般取值1.0、3.0等，实际取值取决于不同设备提供的densityDPI。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1094| scaledDensity | number | 是 | 否 | 显示设备的显示字体的缩放因子。该参数为浮点数，通常与densityPixels相同。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1095| xDPI | number | 是 | 否 | x方向中每英寸屏幕的确切物理像素值，该参数为浮点数。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1096| yDPI | number | 是 | 否 | y方向中每英寸屏幕的确切物理像素值，该参数为浮点数。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1097| colorSpaces<sup>11+</sup> | Array<[colorSpaceManager.ColorSpace](../apis-arkgraphics2d/js-apis-colorSpaceManager.md)> | 是 | 否 | 显示设备支持的所有色域类型。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1098| hdrFormats<sup>11+</sup> | Array<[hdrCapability.HDRFormat](../apis-arkgraphics2d/js-apis-hdrCapability.md)> | 是 | 否 | 显示设备支持的所有HDR格式。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1099| availableWidth<sup>12+</sup> | number | 是 | 否 | 2in1设备上屏幕的可用区域宽度，单位为px，该参数为大于0的整数。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1100| availableHeight<sup>12+</sup> | number | 是 | 否 | 2in1设备上屏幕的可用区域高度，单位为px，该参数为大于0的整数。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1101 1102### getCutoutInfo<sup>9+</sup> 1103getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void 1104 1105获取挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。使用callback异步回调。建议应用布局规避该区域。 1106 1107**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1108 1109**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1110 1111**参数：** 1112 1113| 参数名 | 类型 | 必填 | 说明 | 1114| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1115| callback | AsyncCallback<[CutoutInfo](#cutoutinfo9)> | 是 | 回调函数。返回描述不可用屏幕区域的CutoutInfo对象。 | 1116 1117**错误码：** 1118 1119以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 1120 1121| 错误码ID | 错误信息 | 1122| ------- | ----------------------- | 1123| 1400001 | Invalid display or screen. | 1124 1125**示例：** 1126 1127```ts 1128import { BusinessError } from '@kit.BasicServicesKit'; 1129 1130let displayClass: display.Display | null = null; 1131displayClass = display.getDefaultDisplaySync(); 1132 1133displayClass.getCutoutInfo((err: BusinessError, data: display.CutoutInfo) => { 1134 const errCode: number = err.code; 1135 if (errCode) { 1136 console.error(`Failed to get cutoutInfo. Code: ${err.code}, message: ${err.message}`); 1137 return; 1138 } 1139 console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data)); 1140}); 1141``` 1142### getCutoutInfo<sup>9+</sup> 1143getCutoutInfo(): Promise<CutoutInfo> 1144 1145获取挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。使用Promise异步回调。建议应用布局规避该区域。 1146 1147**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1148 1149**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1150 1151**返回值：** 1152 1153| 类型 | 说明 | 1154| ------------------- | ------------------------- | 1155| Promise<[CutoutInfo](#cutoutinfo9)> | Promise对象。返回描述不可用屏幕区域的CutoutInfo对象。 | 1156 1157**错误码：** 1158 1159以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 1160 1161| 错误码ID | 错误信息 | 1162| ------- | ----------------------- | 1163| 1400001 | Invalid display or screen. | 1164 1165**示例：** 1166 1167```ts 1168import { BusinessError } from '@kit.BasicServicesKit'; 1169 1170let displayClass: display.Display | null = null; 1171displayClass = display.getDefaultDisplaySync(); 1172let promise: Promise<display.CutoutInfo> = displayClass.getCutoutInfo(); 1173promise.then((data: display.CutoutInfo) => { 1174 console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data)); 1175}).catch((err: BusinessError) => { 1176 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1177}); 1178``` 1179 1180### getAvailableArea<sup>12+</sup> 1181getAvailableArea(): Promise<Rect> 1182 1183获取当前设备屏幕的可用区域，使用Promise异步回调。 1184 1185**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1186 1187**系统能力：** SystemCapability.Window.SessionManager 1188 1189**返回值：** 1190 1191| 类型 | 说明 | 1192| ------------------- | ------------------------- | 1193| Promise<[Rect](#rect9)> | Promise对象。返回当前屏幕可用矩形区域。 | 1194 1195**错误码：** 1196 1197以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1198 1199| 错误码ID | 错误信息 | 1200| ------- | ----------------------- | 1201| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1202| 1400001 | Invalid display or screen. | 1203 1204**示例：** 1205 1206```ts 1207import { BusinessError } from '@kit.BasicServicesKit'; 1208import { display } from '@kit.ArkUI'; 1209 1210let displayClass: display.Display | null = null; 1211try { 1212 displayClass = display.getDefaultDisplaySync(); 1213 let promise = displayClass.getAvailableArea(); 1214 promise.then((data) => { 1215 console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(data)); 1216 }).catch((err: BusinessError) => { 1217 console.error(`Failed to get the available area in this display. Code: ${err.code}, message: ${err.message}`); 1218 }) 1219} catch (exception) { 1220 console.error(`Failed to obtain the default display object. Code: ${exception.code}, message: ${exception.message}`); 1221} 1222``` 1223 1224### on('availableAreaChange')<sup>12+</sup> 1225on(type: 'availableAreaChange', callback: Callback<Rect>): void 1226 1227开启当前设备屏幕的可用区域监听。当前设备屏幕有可用区域变化时，触发回调函数，返回可用区域。 1228 1229**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1230 1231**系统能力：** SystemCapability.Window.SessionManager 1232 1233**参数：** 1234 1235| 参数名 | 类型 | 必填 | 说明 | 1236| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1237| type | string | 是 | 监听事件，固定为'availableAreaChange'，表示屏幕可用区域变更。 | 1238| callback | Callback<[Rect](#rect9)> | 是 | 回调函数，返回改变后的可用区域。 | 1239 1240**错误码：** 1241 1242以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1243 1244| 错误码ID | 错误信息 | 1245| ------- | ----------------------- | 1246| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1247| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1248| 1400003 | This display manager service works abnormally. | 1249 1250**示例：** 1251 1252```ts 1253import { Callback } from '@kit.BasicServicesKit'; 1254import { display } from '@kit.ArkUI'; 1255 1256let callback: Callback<display.Rect> = (data: display.Rect) => { 1257 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1258}; 1259let displayClass: display.Display | null = null; 1260try { 1261 displayClass = display.getDefaultDisplaySync(); 1262 displayClass.on("availableAreaChange", callback); 1263} catch (exception) { 1264 console.error(`Failed to register callback. Code: ${exception.code}, message: ${exception.message}`); 1265} 1266``` 1267 1268### off('availableAreaChange')<sup>12+</sup> 1269 1270off(type: 'availableAreaChange', callback?: Callback<Rect>): void 1271 1272关闭当前设备屏幕可用区域变化的监听。 1273 1274**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1275 1276**系统能力：** SystemCapability.Window.SessionManager 1277 1278**参数：** 1279 1280| 参数名 | 类型 | 必填 | 说明 | 1281| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1282| type | string | 是 | 监听事件，固定为'availableAreaChange'，表示屏幕可用区域变更。 | 1283| callback | Callback<[Rect](#rect9)> | 否 | 回调函数，已经注册的回调函数，不填默认删除所有回调 | 1284 1285**错误码：** 1286 1287以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1288 1289| 错误码ID | 错误信息 | 1290| ------- | ----------------------- | 1291| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1292| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1293| 1400003 | This display manager service works abnormally. | 1294 1295**示例：** 1296 1297```ts 1298import { Callback } from '@kit.BasicServicesKit'; 1299import { display } from '@kit.ArkUI'; 1300 1301let callback: Callback<display.Rect> = (data: display.Rect) => { 1302 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1303}; 1304let displayClass: display.Display | null = null; 1305try { 1306 displayClass = display.getDefaultDisplaySync(); 1307 displayClass.off("availableAreaChange", callback); 1308} catch (exception) { 1309 console.error(`Failed to unregister callback. Code: ${exception.code}, message: ${exception.message}`); 1310} 1311```
