1# @ohos.display (屏幕属性) 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @oh_wangxk; @logn--> 5<!--Designer: @hejunfei1991--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9屏幕属性提供管理显示设备的一些基础能力，包括获取默认显示设备的信息，获取所有显示设备的信息以及监听显示设备的插拔行为。 10 11> **说明：** 12> 13> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { display } from '@kit.ArkUI'; 19``` 20 21## DisplayState 22 23显示设备的状态枚举。 24 25**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.WindowManager.WindowManager.Core 28 29| 名称 | 值 | 说明 | 30| -------- | -------- | -------- | 31| STATE_UNKNOWN | 0 | 表示显示设备状态未知。| 32| STATE_OFF | 1 | 表示显示设备状态为关闭。 | 33| STATE_ON | 2 | 表示显示设备状态为开启。| 34| STATE_DOZE | 3 | 表示显示设备为低电耗模式。| 35| STATE_DOZE_SUSPEND | 4 | 表示显示设备为睡眠模式，CPU为挂起状态。 | 36| STATE_VR | 5 | 表示显示设备为VR模式。| 37| STATE_ON_SUSPEND | 6 | 表示显示设备为开启状态，CPU为挂起状态。 | 38 39## Orientation<sup>10+</sup> 40 41显示设备当前显示的方向枚举。 42 43**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.WindowManager.WindowManager.Core 46 47| 名称 | 值 | 说明 | 48| -------- | -------- | -------- | 49| PORTRAIT | 0 | 表示设备当前以竖屏方式显示。| 50| LANDSCAPE | 1 | 表示设备当前以横屏方式显示。 | 51| PORTRAIT_INVERTED | 2 | 表示设备当前以反向竖屏方式显示。| 52| LANDSCAPE_INVERTED | 3 | 表示设备当前以反向横屏方式显示。| 53 54## DisplaySourceMode<sup>19+</sup> 55 56屏幕显示内容的显示模式枚举。 57 58**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 59 60**系统能力：** SystemCapability.Window.SessionManager 61 62| 名称 | 值 | 说明 | 63| -------- | -------- | -------- | 64| NONE | 0 | 表示设备当前未使用。| 65| MAIN | 1 | 表示设备当前为主屏。 | 66| MIRROR | 2 | 表示设备当前为镜像显示模式。| 67| EXTEND | 3 | 表示设备当前为扩展显示模式。| 68| ALONE | 4 | 表示设备当前为异源显示模式。| 69 70## FoldStatus<sup>10+</sup> 71 72当前可折叠设备的折叠状态枚举。如果是双折轴设备，则在充电口朝下的状态下，从右到左分别是折轴一和折轴二。 73 74**系统能力：** SystemCapability.Window.SessionManager 75 76| 名称 | 值 | 说明 | 77| -------- | -------- | -------- | 78| FOLD_STATUS_UNKNOWN | 0 | 表示设备当前折叠状态未知。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 79| FOLD_STATUS_EXPANDED | 1 | 表示设备当前折叠状态为完全展开。如果是双折轴设备，则表示折轴一折叠状态为完全展开，折轴二折叠状态为折叠。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 80| FOLD_STATUS_FOLDED | 2 | 表示设备当前折叠状态为折叠。如果是双折轴设备，则表示折轴一折叠状态为折叠，折轴二折叠状态为折叠。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 81| FOLD_STATUS_HALF_FOLDED | 3 | 表示设备当前折叠状态为半折叠。半折叠指完全展开和折叠之间的状态。如果是双折轴设备，则表示折轴一折叠状态为半折叠，折轴二折叠状态为折叠。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 82| FOLD_STATUS_EXPANDED_WITH_SECOND_EXPANDED<sup>15+</sup> | 11 | 表示双折轴设备折轴一折叠状态为完全展开，折轴二折叠状态为完全展开。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 83| FOLD_STATUS_EXPANDED_WITH_SECOND_HALF_FOLDED<sup>15+</sup> | 21 | 表示双折轴设备折轴一折叠状态为完全展开，折轴二折叠状态为半折叠。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 84| FOLD_STATUS_FOLDED_WITH_SECOND_EXPANDED<sup>15+</sup> | 12 | 表示双折轴设备折轴一折叠状态为折叠，折轴二折叠状态为完全展开。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 85| FOLD_STATUS_FOLDED_WITH_SECOND_HALF_FOLDED<sup>15+</sup> | 22 | 表示双折轴设备折轴一折叠状态为折叠，折轴二折叠状态为半折叠。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 86| FOLD_STATUS_HALF_FOLDED_WITH_SECOND_EXPANDED<sup>15+</sup> | 13 | 表示双折轴设备折轴一折叠状态为半折叠，折轴二折叠状态为完全展开。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 87| FOLD_STATUS_HALF_FOLDED_WITH_SECOND_HALF_FOLDED<sup>15+</sup> | 23 | 表示双折轴设备折轴一折叠状态为半折叠，折轴二折叠状态为半折叠。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 88 89>**说明：**<br> 90> 只有一个折轴的产品包含FOLD_STATUS_EXPANDED、FOLD_STATUS_FOLDED、FOLD_STATUS_HALF_FOLDED三种折叠状态。 91> 具有两个折轴的产品包含上表所示九种折叠状态。<br> 92> FOLD_STATUS_UNKNOWN是一种不可用的折叠状态。 93 94## FoldDisplayMode<sup>10+</sup> 95 96可折叠设备的显示模式枚举。 97 98**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 99 100**系统能力：** SystemCapability.Window.SessionManager 101 102| 名称 | 值 | 说明 | 103| -------- | -------- | -------- | 104| FOLD_DISPLAY_MODE_UNKNOWN | 0 | 表示设备当前折叠显示模式未知。| 105| FOLD_DISPLAY_MODE_FULL | 1 | 表示设备当前全屏显示。 | 106| FOLD_DISPLAY_MODE_MAIN | 2 | 表示设备当前主屏幕显示。| 107| FOLD_DISPLAY_MODE_SUB | 3 | 表示设备当前子屏幕显示。| 108| FOLD_DISPLAY_MODE_COORDINATION | 4 | 表示设备当前双屏协同显示。| 109 110>**说明：**<br> 111>• 对于内外屏均可作为主屏幕使用的折叠产品，例如大折叠、阔折叠，内屏显示状态为FOLD_DISPLAY_MODE_FULL，外屏显示状态为FOLD_DISPLAY_MODE_MAIN。<br> 112>• 对于外屏只有简单的辅助显示作用的折叠产品，例如小折叠，内屏显示状态为FOLD_DISPLAY_MODE_MAIN，外屏显示状态为FOLD_DISPLAY_MODE_SUB。 113 114## FoldCreaseRegion<sup>10+</sup> 115 116折叠折痕区域。 117 118**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 119 120**系统能力：** SystemCapability.Window.SessionManager 121 122| 名称 | 类型 | 只读 | 可选 | 说明 | 123| ------ | -------- | ---- | ---- | ------------------ | 124| displayId | number | 是 | 否 | 屏幕id，用于识别折痕所在的屏幕。 | 125| creaseRects | Array\<[Rect](#rect9)> | 是 | 否 | 折痕区域。 | 126 127## Rect<sup>9+</sup> 128 129矩形区域。 130 131**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 132 133**系统能力：** SystemCapability.WindowManager.WindowManager.Core 134 135| 名称 | 类型 | 只读 | 可选 | 说明 | 136| ------ | -------- | ---- | ---- | ------------------ | 137| left | number | 否 | 否 | 矩形区域的左边界，单位为px，该参数为整数。 | 138| top | number | 否 | 否 | 矩形区域的上边界，单位为px，该参数为整数。 | 139| width | number | 否 | 否 | 矩形区域的宽度，单位为px，该参数为整数。 | 140| height | number | 否 | 否 | 矩形区域的高度，单位为px，该参数为整数。 | 141 142## WaterfallDisplayAreaRects<sup>9+</sup> 143 144瀑布屏曲面部分显示区域。 145 146**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 147 148**系统能力：** SystemCapability.WindowManager.WindowManager.Core 149 150| 名称 | 类型 | 只读 | 可选 | 说明 | 151| ------ | ------------- | ---- | ---- | ------------------ | 152| left | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的左侧矩形区域。 | 153| top | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的顶部矩形区域。 | 154| right | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的右侧矩形区域。 | 155| bottom | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的底部矩形区域。 | 156 157## CutoutInfo<sup>9+</sup> 158 159挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。 160 161**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 162 163**系统能力：** SystemCapability.WindowManager.WindowManager.Core 164 165| 名称 | 类型 | 只读 | 可选 | 说明 | 166| --------------------------- | ------------- | ---- | ---- | ------------------ | 167| boundingRects | Array\<[Rect](#rect9)> | 是 | 否 | 挖孔、刘海等区域的边界矩形。如果没有挖孔、刘海等区域，数组返回为空。 | 168| waterfallDisplayAreaRects | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | 是 | 否 | 瀑布屏曲面部分显示区域。 | 169 170## DisplayPhysicalResolution<sup>12+</sup> 171设备的显示模式以及对应的物理屏幕分辨率信息。 172 173**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 174 175**系统能力：** SystemCapability.WindowManager.WindowManager.Core 176 177| 名称 | 类型 | 只读 | 可选 | 说明 | 178| --------------------------- | ------------- | ---- | ---- | ------------------ | 179| foldDisplayMode | [FoldDisplayMode](#folddisplaymode10) | 是 | 否 | 设备的显示模式，非折叠设备时值为0。 | 180| physicalWidth | number | 是 | 否 | 设备的宽度，单位为px，该参数为大于0的整数。| 181| physicalHeight | number | 是 | 否 | 设备的高度，单位为px，该参数为大于0的整数。| 182 183## ScreenShape<sup>18+</sup> 184 185显示设备的屏幕形状枚举。 186 187**系统能力：** SystemCapability.WindowManager.WindowManager.Core 188 189| 名称 | 值 | 说明 | 190| -------- | -------- | -------- | 191| RECTANGLE | 0 | 表示设备屏幕形状为矩形。| 192| ROUND | 1 | 表示设备屏幕形状为圆形。| 193 194## VirtualScreenConfig<sup>16+</sup> 195 196创建虚拟屏幕的参数。 197 198**系统能力：** SystemCapability.Window.SessionManager 199 200| 名称 | 类型 | 只读 | 可选 | 说明 | 201| --------- | -------- | ---- | ---- |--------------------------| 202| name | string | 否 | 否 | 指定虚拟屏幕的名称，用户可自行定义。 | 203| width | number | 否 | 否 | 指定虚拟屏幕的宽度，单位为px，该参数应为正整数。 | 204| height | number | 否 | 否 | 指定虚拟屏幕的高度，单位为px，该参数应为正整数。 | 205| density | number | 否 | 否 | 指定虚拟屏幕的密度，单位为px，该参数为浮点数。 | 206| surfaceId | string | 否 | 否 | 指定虚拟屏幕的surfaceId，用户可自行定义，该参数最大长度为4096个字节，超出最大长度时则取前4096个字节。 | 207 208## Position<sup>20+</sup> 209 210坐标位置：在全局坐标系中，以主屏左上角为原点。在相对坐标系中，以指定屏幕左上角为原点。 211 212**系统能力：** SystemCapability.Window.SessionManager 213 214| 名称 | 类型 | 只读 | 可选 | 说明 | 215| --------- | -------- | ---- | ---- |--------------------------| 216| x | number | 否 | 否 | 相对原点的横坐标，单位为px，该参数应为32位有符号整数，输入浮点数时向下取整。 | 217| y | number | 否 | 否 | 相对原点的纵坐标，单位为px，该参数应为32位有符号整数，输入浮点数时向下取整。 | 218 219## RelativePosition<sup>20+</sup> 220 221相对坐标系下的坐标位置，以displayId对应的屏幕左上角为原点。 222 223**系统能力：** SystemCapability.Window.SessionManager 224 225| 名称 | 类型 | 只读 | 可选 | 说明 | 226| --------- | -------- | ---- | ---- |--------------------------| 227| displayId | number | 否 | 否 | 相对坐标所对应的屏幕ID，仅支持整数输入，且需大于等于0。 | 228| position | [Position](#position20) | 否 | 否 | 以displayId所指定屏幕左上角为原点的坐标值。 | 229 230## display.getDisplayByIdSync<sup>12+</sup> 231 232getDisplayByIdSync(displayId: number): Display 233 234根据displayId获取对应的Display对象。 235 236**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 237 238**系统能力：** SystemCapability.WindowManager.WindowManager.Core 239 240**参数：** 241 242| 参数名 | 类型 | 必填 | 说明 | 243| ------ | ------------------------- | ---- |----------| 244| displayId | number | 是 | 屏幕id。该参数仅支持整数输入，该参数大于等于0。需要确保displayId准确才能成功获取到对应结果。可以通过[WindowProperties](arkts-apis-window-i.md#windowproperties)的displayId属性获取到准确的displayId作为入参。 | 245 246**返回值：** 247 248| 类型 | 说明 | 249| ------------------------------| ----------------------------------------------| 250| [Display](#display) | 返回displayId对应的Display对象。 | 251 252**错误码：** 253 254以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 255 256| 错误码ID | 错误信息 | 257| ------- | ----------------------- | 258| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2. Incorrect parameter types. 3. Parameter verification failed.| 259| 1400003 | This display manager service works abnormally. | 260 261**示例：** 262 263```ts 264import { display } from '@kit.ArkUI'; 265 266let displayClass: display.Display | null = null; 267 268try { 269 // 可以通过WindowProperties的displayId属性获取到准确的displayId作为入参 270 let displayId = 0; 271 displayClass = display.getDisplayByIdSync(displayId); 272} catch (exception) { 273 console.error(`Failed to get display. Code: ${exception.code}, message: ${exception.message}`); 274} 275``` 276 277## display.getAllDisplayPhysicalResolution<sup>12+</sup> 278 279getAllDisplayPhysicalResolution(): Promise<Array<DisplayPhysicalResolution>> 280 281获取当前设备支持的所有显示模式及其对应的物理屏幕分辨率信息对象。使用Promise异步回调。 282 283**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 284 285**系统能力：** SystemCapability.WindowManager.WindowManager.Core 286 287**返回值：** 288 289| 类型 | 说明 | 290| ----------------------------------------------- | ------------------------------------------------------- | 291| Promise<Array<[DisplayPhysicalResolution](#displayphysicalresolution12)>> | Promise对象。返回当前所有的DisplayPhysicalResolution对象。 | 292 293**错误码：** 294 295以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 296 297| 错误码ID | 错误信息 | 298| ------- | ----------------------- | 299| 1400003 | This display manager service works abnormally. | 300 301**示例：** 302 303```ts 304import { BusinessError } from '@kit.BasicServicesKit'; 305import { display } from '@kit.ArkUI'; 306 307let promise = display.getAllDisplayPhysicalResolution(); 308promise.then((resolutionObjects) => { 309 console.info('Obtaining physical resolution length: ' + resolutionObjects.length); 310 for (let i = 0; i < resolutionObjects.length; i++) { 311 console.info(`resolutionObjects[${i}].foldDisplayMode: ${resolutionObjects[i].foldDisplayMode}`); 312 console.info(`resolutionObjects[${i}].physicalWidth: ${resolutionObjects[i].physicalWidth}`); 313 console.info(`resolutionObjects[${i}].physicalHeight: ${resolutionObjects[i].physicalHeight}`); 314 } 315}).catch((err: BusinessError) => { 316 console.error(`Failed to obtain physical resolution. Code: ${err.code}, message: ${err.message}`); 317}); 318``` 319 320## display.getDefaultDisplaySync<sup>9+</sup> 321 322getDefaultDisplaySync(): Display 323 324获取当前默认的Display对象。 325 326**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 327 328**系统能力：** SystemCapability.WindowManager.WindowManager.Core 329 330**返回值：** 331 332| 类型 | 说明 | 333| ------------------------------| ----------------------------------------------| 334| [Display](#display) | 返回默认的Display对象。 | 335 336**错误码：** 337 338以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 339 340| 错误码ID | 错误信息 | 341| ------- | ----------------------- | 342| 1400001 | Invalid display or screen. | 343 344**示例：** 345 346```ts 347import { display } from '@kit.ArkUI'; 348 349let displayClass: display.Display | null = null; 350try { 351 displayClass = display.getDefaultDisplaySync(); 352} catch (exception) { 353 console.error(`Failed to get default display. Code: ${exception.code}, message: ${exception.message}`); 354} 355``` 356 357## display.getPrimaryDisplaySync<sup>14+</sup> 358 359getPrimaryDisplaySync(): Display 360 361获取主屏信息。除2in1之外的设备获取的是设备自带屏幕的Display对象；2in1设备外接屏幕时获取的是当前主屏幕的Display对象；2in1设备没有外接屏幕时获取的是自带屏幕的Display对象。 362 363**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 364 365**系统能力：** SystemCapability.WindowManager.WindowManager.Core 366 367**返回值：** 368 369| 类型 | 说明 | 370| ------------------------------| ----------------------------------------------| 371| [Display](#display) | 当前设备主屏幕的Display对象。 | 372 373**错误码：** 374 375以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 376 377| 错误码ID | 错误信息 | 378| ------- | ----------------------- | 379| 1400001 | Invalid display or screen. | 380 381**示例：** 382 383```ts 384import { display } from '@kit.ArkUI'; 385 386let displayClass: display.Display | null = null; 387 388displayClass = display.getPrimaryDisplaySync(); 389``` 390 391## display.getAllDisplays<sup>9+</sup> 392 393getAllDisplays(callback: AsyncCallback<Array<Display>>): void 394 395获取当前所有的Display对象，使用callback异步回调。 396 397**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 398 399**系统能力：** SystemCapability.WindowManager.WindowManager.Core 400 401**参数：** 402 403| 参数名 | 类型 | 必填 | 说明 | 404| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 405| callback | AsyncCallback<Array<[Display](#display)>> | 是 | 回调函数。返回当前所有的Display对象。 | 406 407**错误码：** 408 409以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 410 411| 错误码ID | 错误信息 | 412| ------- | ----------------------- | 413| 1400001 | Invalid display or screen. | 414 415**示例：** 416 417```ts 418import { BusinessError } from '@kit.BasicServicesKit'; 419import { display } from '@kit.ArkUI'; 420 421let displayClass: Array<display.Display> = []; 422display.getAllDisplays((err: BusinessError, data: Array<display.Display>) => { 423 displayClass = data; 424 const errCode: number = err.code; 425 if (errCode) { 426 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 427 return; 428 } 429 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 430}); 431``` 432 433## display.getAllDisplays<sup>9+</sup> 434 435getAllDisplays(): Promise<Array<Display>> 436 437获取当前所有的Display对象，使用Promise异步回调。 438 439**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 440 441**系统能力：** SystemCapability.WindowManager.WindowManager.Core 442 443**返回值：** 444 445| 类型 | 说明 | 446| ----------------------------------------------- | ------------------------------------------------------- | 447| Promise<Array<[Display](#display)>> | Promise对象。返回当前所有的Display对象。 | 448 449**错误码：** 450 451以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 452 453| 错误码ID | 错误信息 | 454| ------- | ----------------------- | 455| 1400001 | Invalid display or screen. | 456 457**示例：** 458 459```ts 460import { BusinessError } from '@kit.BasicServicesKit'; 461import { display } from '@kit.ArkUI'; 462 463let displayClass: Array<display.Display> =[]; 464let promise: Promise<Array<display.Display>> = display.getAllDisplays(); 465promise.then((data: Array<display.Display>) => { 466 displayClass = data; 467 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 468}).catch((err: BusinessError) => { 469 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 470}); 471``` 472 473## display.on('add'|'remove'|'change') 474 475on(type: 'add'|'remove'|'change', callback: Callback<number>): void 476 477开启显示设备变化的监听。 478 479**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 480 481**系统能力：** SystemCapability.WindowManager.WindowManager.Core 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------------------------| 487| type | string | 是 | 监听事件。<br/>- type为"add"，表示增加显示设备事件。例如：插入显示器。<br/>- type为"remove"，表示移除显示设备事件。例如：移除显示器。<br/>- type为"change"，表示改变显示设备事件。例如：显示器方向改变。 | 488| callback | Callback<number> | 是 | 回调函数。返回监听到的屏幕id，该参数为整数。 | 489 490**错误码：** 491 492以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 493 494| 错误码ID | 错误信息 | 495| ------- | ----------------------- | 496| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 497 498**示例：** 499 500```ts 501import { Callback } from '@kit.BasicServicesKit'; 502 503let callback: Callback<number> = (data: number) => { 504 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 505}; 506 507display.on("add", callback); 508``` 509 510## display.off('add'|'remove'|'change') 511 512off(type: 'add'|'remove'|'change', callback?: Callback<number>): void 513 514关闭显示设备变化的监听。 515 516**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 517 518**系统能力：** SystemCapability.WindowManager.WindowManager.Core 519 520**参数：** 521 522| 参数名 | 类型 | 必填 | 说明 | 523| -------- | -------- | -------- | -------- | 524| type | string | 是 | 监听事件。<br/>- type为"add"，表示增加显示设备事件。例如：插入显示器。<br/>- type为"remove"，表示移除显示设备事件。例如：移除显示器。<br/>- type为"change"，表示改变显示设备事件。例如：显示器方向改变。 | 525| callback | Callback<number> | 否 | 需要取消注册的回调函数。返回监听到的屏幕id，该参数为整数。若无此参数，则取消注册当前type类型事件监听的所有回调函数。 | 526 527**错误码：** 528 529以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 530 531| 错误码ID | 错误信息 | 532| ------- | ----------------------- | 533| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 534 535**示例：** 536 537```ts 538 539// 如果通过on注册多个callback，同时关闭所有callback监听 540display.off("remove"); 541 542let callback: Callback<number> = (data: number) => { 543 console.info('Succeeded in unregistering the callback for display remove. Data: ' + JSON.stringify(data)) 544}; 545// 关闭传入的callback监听 546display.off('remove', callback); 547``` 548 549## display.isFoldable<sup>10+</sup> 550isFoldable(): boolean 551 552检查设备是否可折叠。 553 554**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 555 556**系统能力：** SystemCapability.Window.SessionManager 557 558**返回值：** 559 560| 类型 | 说明 | 561| ----------------------------------------------- | ------------------------------------------------------- | 562| boolean | boolean对象，返回当前设备是否可折叠的结果。false表示不可折叠，true表示可折叠。对于外屏只有简单辅助显示作用的小折叠设备，应用无法自定义外屏界面，故其返回值为false。其他可折叠设备的返回值均为true。| 563 564**错误码：** 565 566以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 567 568| 错误码ID | 错误信息 | 569| ------- | ----------------------- | 570| 1400003 | This display manager service works abnormally. | 571 572**示例：** 573 574```ts 575import { display } from '@kit.ArkUI'; 576 577let ret: boolean = false; 578ret = display.isFoldable(); 579``` 580 581## display.getFoldStatus<sup>10+</sup> 582getFoldStatus(): FoldStatus 583 584获取可折叠设备的当前折叠状态。 585 586**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 587 588**系统能力：** SystemCapability.Window.SessionManager 589 590**返回值：** 591 592| 类型 | 说明 | 593| ----------------------------------------------- | ------------------------------------------------------- | 594| [FoldStatus](#foldstatus10) | FoldStatus对象，返回当前可折叠设备的折叠状态。 | 595 596**错误码：** 597 598以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 599 600| 错误码ID | 错误信息 | 601| ------- | ----------------------- | 602| 1400003 | This display manager service works abnormally. | 603 604**示例：** 605 606```ts 607import { display } from '@kit.ArkUI'; 608 609let data: display.FoldStatus = display.getFoldStatus(); 610console.info('Succeeded in obtaining fold status. Data: ' + JSON.stringify(data)); 611``` 612 613## display.getFoldDisplayMode<sup>10+</sup> 614getFoldDisplayMode(): FoldDisplayMode 615 616获取可折叠设备的显示模式。 617 618**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 619 620**系统能力：** SystemCapability.Window.SessionManager 621 622**设备行为差异：** 该接口在2in1设备、非折叠设备中返回0，在其他设备中可正常调用。 623 624**返回值：** 625 626| 类型 | 说明 | 627| ----------------------------------------------- | ------------------------------------------------------- | 628| [FoldDisplayMode](#folddisplaymode10) | FoldDisplayMode对象，返回当前可折叠设备的显示模式。 | 629 630**错误码：** 631 632以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 633 634| 错误码ID | 错误信息 | 635| ------- | ----------------------- | 636| 1400003 | This display manager service works abnormally. | 637 638**示例：** 639 640```ts 641import { display } from '@kit.ArkUI'; 642 643let data: display.FoldDisplayMode = display.getFoldDisplayMode(); 644console.info('Succeeded in obtaining fold display mode. Data: ' + JSON.stringify(data)); 645``` 646 647## display.getCurrentFoldCreaseRegion<sup>10+</sup> 648getCurrentFoldCreaseRegion(): FoldCreaseRegion 649 650在当前显示模式下获取折叠折痕区域。 651 652**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 653 654**系统能力：** SystemCapability.Window.SessionManager 655 656**设备行为差异：** 该接口在折叠设备中可正常调用，在其他设备中返回undefined。 657 658**返回值：** 659 660| 类型 | 说明 | 661| ----------------------------------------------- | ------------------------------------------------------- | 662| [FoldCreaseRegion](#foldcreaseregion10) | FoldCreaseRegion对象，返回设备在当前显示模式下的折叠折痕区域。 | 663 664**错误码：** 665 666以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 667 668| 错误码ID | 错误信息 | 669| ------- | ----------------------- | 670| 1400003 | This display manager service works abnormally. | 671 672**示例：** 673 674```ts 675import { display } from '@kit.ArkUI'; 676 677let data: display.FoldCreaseRegion = display.getCurrentFoldCreaseRegion(); 678console.info('Succeeded in obtaining current fold crease region. Data: ' + JSON.stringify(data)); 679``` 680 681## display.on('foldStatusChange')<sup>10+</sup> 682 683on(type: 'foldStatusChange', callback: Callback<FoldStatus>): void 684 685开启折叠设备折叠状态变化的监听。 686 687本接口监听设备物理折叠状态的变化，如果要监听屏幕显示模式的变化，需要使用[display.on('foldDisplayModeChange')](#displayonfolddisplaymodechange10)接口。 688 689两者存在差异，时序上物理折叠状态变化在前，底层会根据物理折叠状态匹配屏幕显示模式状态。 690 691若需监听当前显示内容是显示在折叠设备的内屏还是外屏，请使用[display.on('foldDisplayModeChange')](#displayonfolddisplaymodechange10)。 692 693**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 694 695**系统能力：** SystemCapability.Window.SessionManager 696 697**参数：** 698 699| 参数名 | 类型 | 必填 | 说明 | 700| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 701| type | string | 是 | 监听事件，固定为'foldStatusChange'，表示折叠设备折叠状态发生变化。 | 702| callback | Callback<[FoldStatus](#foldstatus10)> | 是 | 回调函数。表示折叠设备折叠状态。 | 703 704**错误码：** 705 706以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 707 708| 错误码ID | 错误信息 | 709| ------- | ----------------------- | 710| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 711| 1400003 | This display manager service works abnormally. | 712 713**示例：** 714 715```ts 716import { Callback } from '@kit.BasicServicesKit'; 717 718/** 719 * 注册监听的callback参数要采用对象传递. 720 * 若使用匿名函数注册，每次调用会创建一个新的底层对象，引起内存泄漏问题。 721*/ 722let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 723 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 724}; 725display.on('foldStatusChange', callback); 726``` 727 728## display.off('foldStatusChange')<sup>10+</sup> 729 730off(type: 'foldStatusChange', callback?: Callback<FoldStatus>): void 731 732关闭折叠设备折叠状态变化的监听。 733 734**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 735 736**系统能力：** SystemCapability.Window.SessionManager 737 738**参数：** 739 740| 参数名 | 类型 | 必填 | 说明 | 741| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 742| type | string | 是 | 监听事件，固定为'foldStatusChange'，表示折叠设备折叠状态发生变化。 | 743| callback | Callback<[FoldStatus](#foldstatus10)> | 否 | 需要取消注册的回调函数。表示折叠设备折叠状态。若无此参数，则取消注册折叠状态变化监听的所有回调函数。 | 744 745**错误码：** 746 747以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 748 749| 错误码ID | 错误信息 | 750| ------- | ----------------------- | 751| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 752| 1400003 | This display manager service works abnormally. | 753 754**示例：** 755 756```ts 757 758// 如果通过on注册多个callback，同时关闭所有callback监听 759display.off('foldStatusChange'); 760 761let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => { 762 console.info('unregistering FoldStatus changes callback. Data: ' + JSON.stringify(data)); 763}; 764// 关闭传入的callback监听 765display.off('foldStatusChange', callback); 766``` 767 768## display.on('foldAngleChange')<sup>12+</sup> 769 770on(type: 'foldAngleChange', callback: Callback<Array<number>>): void 771 772开启折叠设备折叠角度变化的监听。如果是双折轴设备，则有两个角度值；在充电口朝下的状态下，从右到左分别是折轴一和折轴二。 773 774**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 775 776**系统能力：** SystemCapability.Window.SessionManager 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 782| type | string | 是 | 监听事件，固定为'foldAngleChange'，表示折叠设备折叠角度发生变化。| 783| callback | Callback<Array<number>> | 是 | 回调函数。表示折叠设备屏幕折叠角度值（0度~180度）。如果是双折轴设备，则数组返回两个角度值，第一个值是折轴一的折叠角度值，第二个值是折轴二的折叠角度值。| 784 785**错误码：** 786 787以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 788 789| 错误码ID | 错误信息 | 790| ------- | ----------------------- | 791| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 792| 1400003 | This display manager service works abnormally. | 793 794**示例：** 795 796```ts 797import { Callback } from '@kit.BasicServicesKit'; 798 799let callback: Callback<Array<number>> = (angles: Array<number>) => { 800 console.info('Listening fold angles length: ' + angles.length); 801}; 802display.on('foldAngleChange', callback); 803``` 804 805## display.off('foldAngleChange')<sup>12+</sup> 806 807off(type: 'foldAngleChange', callback?: Callback<Array<number>>): void 808 809关闭折叠设备折叠角度变化的监听。 810 811**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 812 813**系统能力：** SystemCapability.Window.SessionManager 814 815**参数：** 816 817| 参数名 | 类型 | 必填 | 说明 | 818| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 819| type | string | 是 | 监听事件，固定为'foldAngleChange'表示折叠设备折叠角度发生变化。| 820| callback | Callback<Array<number>> | 否 | 需要取消注册的回调函数。表示折叠设备屏幕折叠角度值（0度~180度）。若无此参数，则取消注册折叠角度变化监听的所有回调函数。| 821 822**错误码：** 823 824以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 825 826| 错误码ID | 错误信息 | 827| ------- | ----------------------- | 828| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 829| 1400003 | This display manager service works abnormally. | 830 831**示例：** 832 833```ts 834 835// 如果通过on注册多个callback，同时关闭所有callback监听 836display.off('foldAngleChange'); 837 838let callback: Callback<Array<number>> = (angles: Array<number>) => { 839 console.info('Listening fold angles length: ' + angles.length); 840}; 841// 关闭传入的callback监听 842display.off('foldAngleChange', callback); 843``` 844 845## display.on('captureStatusChange')<sup>12+</sup> 846 847on(type: 'captureStatusChange', callback: Callback<boolean>): void 848 849开启屏幕截屏、投屏、录屏状态变化的监听。 850 851**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 852 853**系统能力：** SystemCapability.Window.SessionManager 854 855**参数：** 856 857| 参数名 | 类型 | 必填 | 说明 | 858| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 859| type | string | 是 | 监听事件，固定为'captureStatusChange'表示设备截屏、投屏或者录屏状态发生变化。| 860| callback | Callback<boolean> | 是 | 回调函数。表示设备截屏、投屏或录屏时状态发生变化。true表示设备开始投屏或者录屏，false表示结束投屏或者录屏；截屏仅返回一次true。| 861 862**错误码：** 863 864以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 865 866| 错误码ID | 错误信息 | 867| ------- | ----------------------- | 868| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 869| 1400003 | This display manager service works abnormally. | 870 871**示例：** 872 873```ts 874import { Callback } from '@kit.BasicServicesKit'; 875 876let callback: Callback<boolean> = (captureStatus: boolean) => { 877 console.info('Listening capture status: ' + captureStatus); 878}; 879display.on('captureStatusChange', callback); 880``` 881 882## display.off('captureStatusChange')<sup>12+</sup> 883 884off(type: 'captureStatusChange', callback?: Callback<boolean>): void 885 886关闭屏幕截屏、投屏、录屏状态变化的监听。 887 888**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 889 890**系统能力：** SystemCapability.Window.SessionManager 891 892**参数：** 893 894| 参数名 | 类型 | 必填 | 说明 | 895| -------- |-------------------------------------------| ---- | ------------------------------------------------------- | 896| type | string | 是 | 监听事件，固定为'captureStatusChange'表示设备截屏、投屏、录屏状态发生变化。| 897| callback | Callback<boolean> | 否 | 需要取消注册的回调函数。表示设备截屏、投屏或录屏状态发生变化。true表示设备开始投屏或者录屏，false表示结束投屏或者录屏；截屏仅返回一次true。若无此参数，则取消注册截屏、投屏、录屏状态变化监听的所有回调函数。| 898 899**错误码：** 900 901以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 902 903| 错误码ID | 错误信息 | 904| ------- | ----------------------- | 905| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 906| 1400003 | This display manager service works abnormally. | 907 908**示例：** 909 910```ts 911 912// 如果通过on注册多个callback，同时关闭所有callback监听 913display.off('captureStatusChange'); 914 915let callback: Callback<boolean> = (captureStatus: boolean) => { 916 console.info('Listening capture status: ' + captureStatus); 917}; 918// 关闭传入的callback监听 919display.off('captureStatusChange', callback); 920``` 921 922## display.isCaptured<sup>12+</sup> 923isCaptured(): boolean 924 925检查设备是否正在截屏、投屏、录屏。 926 927**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 928 929**系统能力：** SystemCapability.Window.SessionManager 930 931**返回值：** 932 933| 类型 | 说明 | 934| ----------------------------------------------- | ------------------------------------------------------- | 935| boolean | boolean值，返回当前设备是否有截屏、投屏或者录屏。true表示有截屏、投屏、录屏，否则返回false。| 936 937**错误码：** 938 939以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 940 941| 错误码ID | 错误信息 | 942| ------- | ----------------------- | 943| 1400003 | This display manager service works abnormally. | 944 945**示例：** 946 947```ts 948import { display } from '@kit.ArkUI'; 949 950let ret: boolean = false; 951ret = display.isCaptured(); 952``` 953 954## display.on('foldDisplayModeChange')<sup>10+</sup> 955 956on(type: 'foldDisplayModeChange', callback: Callback<FoldDisplayMode>): void 957 958开启折叠设备屏幕显示模式变化的监听。 959 960本接口监听设备屏幕显示模式的变化，如果要监听设备物理折叠状态的变化，需要使用[display.on('foldStatusChange')](#displayonfoldstatuschange10)接口。 961 962两者存在差异，时序上物理折叠状态变化在前，底层会根据物理折叠状态匹配屏幕显示模式状态。 963 964**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 965 966**系统能力：** SystemCapability.Window.SessionManager 967 968**设备行为差异：** 该接口在2in1设备、非折叠设备中不生效也不报错，在其他设备中可正常调用。 969 970**参数：** 971 972| 参数名 | 类型 | 必填 | 说明 | 973| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 974| type | string | 是 | 监听事件，固定为'foldDisplayModeChange'，表示折叠设备屏幕显示模式发生变化。 | 975| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | 是 | 回调函数。表示折叠设备屏幕显示模式。 | 976 977**错误码：** 978 979以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 980 981| 错误码ID | 错误信息 | 982| ------- | ----------------------- | 983| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 984| 1400003 | This display manager service works abnormally. | 985 986**示例：** 987 988```ts 989import { Callback } from '@kit.BasicServicesKit'; 990 991/** 992 * 注册监听的callback参数要采用对象传递. 993 * 若使用匿名函数注册，每次调用会创建一个新的底层对象，引起内存泄漏问题。 994*/ 995let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 996 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 997}; 998display.on('foldDisplayModeChange', callback); 999``` 1000 1001## display.off('foldDisplayModeChange')<sup>10+</sup> 1002 1003off(type: 'foldDisplayModeChange', callback?: Callback<FoldDisplayMode>): void 1004 1005关闭折叠设备屏幕显示模式变化的监听。 1006 1007**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1008 1009**系统能力：** SystemCapability.Window.SessionManager 1010 1011**设备行为差异：** 该接口在2in1设备、非折叠设备中不生效也不报错，在其他设备中可正常调用。 1012 1013**参数：** 1014 1015| 参数名 | 类型 | 必填 | 说明 | 1016| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1017| type | string | 是 | 监听事件，固定为'foldDisplayModeChange'，表示折叠设备屏幕显示模式发生变化。 | 1018| callback | Callback<[FoldDisplayMode](#folddisplaymode10)> | 否 | 需要取消注册的回调函数。表示折叠设备屏幕显示模式。若无此参数，则取消注册屏幕显示模式变化监听的所有回调函数。 | 1019 1020**错误码：** 1021 1022以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1023 1024| 错误码ID | 错误信息 | 1025| ------- | ----------------------- | 1026| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1027| 1400003 | This display manager service works abnormally. | 1028 1029**示例：** 1030 1031```ts 1032 1033// 如果通过on注册多个callback，同时关闭所有callback监听 1034display.off('foldDisplayModeChange'); 1035 1036let callback: Callback<display.FoldDisplayMode> = (data: display.FoldDisplayMode) => { 1037 console.info('unregistering FoldDisplayMode changes callback. Data: ' + JSON.stringify(data)); 1038}; 1039// 关闭传入的callback监听 1040display.off('foldDisplayModeChange', callback); 1041``` 1042 1043## display.createVirtualScreen<sup>16+</sup> 1044 1045createVirtualScreen(config:VirtualScreenConfig): Promise<number> 1046 1047创建虚拟屏幕，使用Promise异步回调。 1048 1049**系统能力：** SystemCapability.Window.SessionManager 1050 1051**需要权限**：ohos.permission.ACCESS_VIRTUAL_SCREEN 1052 1053**参数：** 1054 1055| 参数名 | 类型 | 必填 | 说明 | 1056| ------- | ------------------------------------------- | ---- | ------------------------ | 1057| config | [VirtualScreenConfig](#virtualscreenconfig16) | 是 | 用于创建虚拟屏幕的参数。| 1058 1059**返回值：** 1060 1061| 类型 | 说明 | 1062| -------------------------------- | ------------------------------------- | 1063| Promise<number> | Promise对象。返回创建的虚拟屏幕的ScreenId。 | 1064 1065**错误码：** 1066 1067以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1068 1069| 错误码ID | 错误信息 | 1070| ------- | ----------------------- | 1071| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1072| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1073| 801 | Capability not supported.function createVirtualScreen can not work correctly due to limited device capabilities. | 1074| 1400001 | Invalid display or screen. | 1075 1076**示例：** 1077 1078```ts 1079import { BusinessError } from '@kit.BasicServicesKit'; 1080 1081class VirtualScreenConfig { 1082 name : string = ''; 1083 width : number = 0; 1084 height : number = 0; 1085 density : number = 0; 1086 surfaceId : string = ''; 1087} 1088 1089let config : VirtualScreenConfig = { 1090 name: 'screen01', 1091 width: 1080, 1092 height: 2340, 1093 density: 2, 1094 surfaceId: '' 1095}; 1096 1097display.createVirtualScreen(config).then((screenId: number) => { 1098 console.info('Succeeded in creating the virtual screen. Data: ' + JSON.stringify(screenId)); 1099}).catch((err: BusinessError) => { 1100 console.error(`Failed to create the virtual screen. Code:${err.code},message is ${err.message}`); 1101}); 1102``` 1103 1104## display.destroyVirtualScreen<sup>16+</sup> 1105 1106destroyVirtualScreen(screenId:number): Promise<void> 1107 1108销毁虚拟屏幕，使用Promise异步回调。 1109 1110**系统能力：** SystemCapability.Window.SessionManager 1111 1112**需要权限**：ohos.permission.ACCESS_VIRTUAL_SCREEN 1113 1114**参数：** 1115 1116| 参数名 | 类型 | 必填 | 说明 | 1117| -------- | ------ | ---- | ---------- | 1118| screenId | number | 是 | 屏幕id，与创建的虚拟屏幕id保持一致，即使用[createVirtualScreen()](#displaycreatevirtualscreen16)接口成功创建对应虚拟屏幕时的返回值，该参数仅支持整数输入。 | 1119 1120**返回值：** 1121 1122| 类型 | 说明 | 1123| ------------------- | ------------------------- | 1124| Promise<void> | 无返回结果的Promise对象。 | 1125 1126**错误码：** 1127 1128以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1129 1130| 错误码ID | 错误信息 | 1131| ------- | ----------------------- | 1132| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1133| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1134| 801 | Capability not supported.function destroyVirtualScreen can not work correctly due to limited device capabilities. | 1135| 1400001 | Invalid display or screen. | 1136| 1400003 | This display manager service works abnormally. | 1137 1138**示例：** 1139 1140```ts 1141import { BusinessError } from '@kit.BasicServicesKit'; 1142 1143let screenId: number = 1; 1144display.destroyVirtualScreen(screenId).then(() => { 1145 console.info('Succeeded in destroying the virtual screen.'); 1146}).catch((err: BusinessError) => { 1147 console.error(`Failed to destroy the virtual screen.Code:${err.code},message is ${err.message}`); 1148}); 1149``` 1150 1151## display.setVirtualScreenSurface<sup>16+</sup> 1152 1153setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 1154 1155设置虚拟屏幕的surfaceId，使用Promise异步回调。 1156 1157**系统能力：** SystemCapability.Window.SessionManager 1158 1159**需要权限**：ohos.permission.ACCESS_VIRTUAL_SCREEN 1160 1161**参数：** 1162 1163| 参数名 | 类型 | 必填 | 说明 | 1164| --------- | ------ | ---- | ------------- | 1165| screenId | number | 是 | 屏幕id，与创建的虚拟屏幕id保持一致，即使用[createVirtualScreen()](#displaycreatevirtualscreen16)接口成功创建对应虚拟屏幕时的返回值，该参数仅支持整数输入。 | 1166| surfaceId | string | 是 | 代表虚拟屏幕的surfaceId，用户可自行定义，该参数最大长度为4096个字节，超出最大长度时则取前4096个字节。 | 1167 1168**返回值：** 1169 1170| 类型 | 说明 | 1171| ------------------- | ------------------------- | 1172| Promise<void> | 无返回结果的Promise对象。 | 1173 1174**错误码：** 1175 1176以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1177 1178| 错误码ID | 错误信息 | 1179| ------- | ----------------------- | 1180| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1181| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1182| 801 | Capability not supported.function setVirtualScreenSurface can not work correctly due to limited device capabilities. | 1183| 1400001 | Invalid display or screen. | 1184| 1400003 | This display manager service works abnormally. | 1185 1186**示例：** 1187 1188```ts 1189import { BusinessError } from '@kit.BasicServicesKit'; 1190 1191let screenId: number = 1; 1192let surfaceId: string = '2048'; 1193display.setVirtualScreenSurface(screenId, surfaceId).then(() => { 1194 console.info('Succeeded in setting the surface for the virtual screen.'); 1195}).catch((err: BusinessError) => { 1196 console.error(`Failed to set the surface for the virtual screen. Code:${err.code},message is ${err.message}`); 1197}); 1198``` 1199 1200## display.makeUnique<sup>16+</sup> 1201 1202makeUnique(screenId:number): Promise<void> 1203 1204将屏幕设置为异源模式，使用Promise异步回调。 1205 1206**系统能力：** SystemCapability.Window.SessionManager 1207 1208**需要权限**：ohos.permission.ACCESS_VIRTUAL_SCREEN 1209 1210**参数：** 1211 1212| 参数名 | 类型 | 必填 | 说明 | 1213| --------- | ------ | ---- | ------------- | 1214| screenId | number | 是 | 要设置成异源模式的屏幕id。其中id应为大于0的整数，否则返回401错误码。 | 1215 1216**返回值：** 1217 1218| 类型 | 说明 | 1219| ------------------- | ------------------------- | 1220| Promise<void> | 无返回结果的Promise对象。 | 1221 1222**错误码：** 1223 1224以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1225 1226| 错误码ID | 错误信息 | 1227| ------- | ----------------------- | 1228| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1229| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.| 1230| 801 | Capability not supported.function makeUnique can not work correctly due to limited device capabilities. | 1231| 1400001 | Invalid display or screen. | 1232| 1400003 | This display manager service works abnormally. | 1233 1234**示例：** 1235 1236```ts 1237import { BusinessError } from '@kit.BasicServicesKit'; 1238 1239let screenId: number = 0; 1240display.makeUnique(screenId).then(() => { 1241 console.info('Succeeded in making unique screens.'); 1242}).catch((err: BusinessError) => { 1243 console.error(`Failed to make unique screens. Code:${err.code},message is ${err.message}`); 1244}); 1245``` 1246 1247## display.convertRelativeToGlobalCoordinate<sup>20+</sup> 1248 1249convertRelativeToGlobalCoordinate(relativePosition: RelativePosition): Position 1250 1251将指定屏幕左上角为原点的相对坐标转换成主屏左上角为原点的全局坐标，仅支持主屏和扩展屏的坐标转换。 1252 1253**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1254 1255**系统能力：** SystemCapability.Window.SessionManager 1256 1257**参数：** 1258 1259| 参数名 | 类型 | 必填 | 说明 | 1260| --------- | ------ | ---- | ------------- | 1261| relativePosition | [RelativePosition](#relativeposition20) | 是 | 需要转化为全局坐标的相对坐标。 | 1262 1263**返回值：** 1264 1265| 类型 | 说明 | 1266| ------------------- | ------------------------- | 1267| [Position](#position20) | 返回相对于主屏左上角的全局坐标。 | 1268 1269**错误码：** 1270 1271以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)、[屏幕错误码](errorcode-display.md)。 1272 1273| 错误码ID | 错误信息 | 1274| ------- | ----------------------- | 1275| 801 | Capability not supported. | 1276| 1400003 | This display manager service works abnormally. | 1277| 1400004 | Parameter error. Possible cause: 1.Invalid parameter range. | 1278 1279**示例：** 1280 1281```ts 1282import { display } from '@kit.ArkUI'; 1283 1284let relativePosition: display.RelativePosition = { 1285 displayId: 0, 1286 position: { 1287 x: 100, 1288 y: 200 1289 } 1290}; 1291 1292try { 1293 let position: display.Position = display.convertRelativeToGlobalCoordinate(relativePosition); 1294 console.info(`The global coordinate is ${position.x}, ${position.y}`) 1295} catch (exception) { 1296 console.error(`Failed to convert the relative coordinate to the global coordinate. Code: ${exception.code}, message: ${exception.message}`); 1297} 1298``` 1299 1300## display.convertGlobalToRelativeCoordinate<sup>20+</sup> 1301 1302convertGlobalToRelativeCoordinate(position: Position, displayId?: number): RelativePosition 1303 1304将主屏左上角为原点的全局坐标转换成displayId指定屏幕左上角为原点的相对坐标。若未传入displayId，默认转换为全局坐标所在屏幕的相对坐标系。若全局坐标不在任何屏幕上，默认转换成主屏的相对坐标。 1305 1306**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1307 1308**系统能力：** SystemCapability.Window.SessionManager 1309 1310**参数：** 1311 1312| 参数名 | 类型 | 必填 | 说明 | 1313| --------- | ------ | ---- | ------------- | 1314| position | [Position](#position20) | 是 | 需要转化为相对坐标的全局坐标。 | 1315| displayId | number | 否 | 相对坐标系原点所在的屏幕ID，传递该参数表示以指定屏幕左上角为原点转换相对坐标。不指定则不传参，默认转换成全局坐标所在屏幕的相对坐标，若全局坐标不在任何屏幕上，则默认转换成主屏的相对坐标。 | 1316 1317**返回值：** 1318 1319| 类型 | 说明 | 1320| ------------------- | ------------------------- | 1321| [RelativePosition](#relativeposition20) | 返回对应屏幕的相对坐标。 | 1322 1323**错误码：** 1324 1325以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)、[屏幕错误码](errorcode-display.md)。 1326 1327| 错误码ID | 错误信息 | 1328| ------- | ----------------------- | 1329| 801 | Capability not supported. | 1330| 1400003 | This display manager service works abnormally. | 1331| 1400004 | Parameter error. Possible cause: 1.Invalid parameter range. | 1332 1333**示例：** 1334 1335```ts 1336import { display } from '@kit.ArkUI'; 1337 1338let position: display.Position = { 1339 x: 100, 1340 y: 200 1341}; 1342 1343try { 1344 let relPos: display.RelativePosition = display.convertGlobalToRelativeCoordinate(position, 0); 1345 console.info(`The relative coordinate is ${relPos.displayId}, ${relPos.position.x}, ${relPos.position.y}`) 1346} catch (exception) { 1347 console.error(`Failed to convert the global coordinate to the relative coordinate. Code: ${exception.code}, message: ${exception.message}`); 1348} 1349``` 1350 1351## display.getDefaultDisplay<sup>(deprecated)</sup> 1352 1353getDefaultDisplay(callback: AsyncCallback<Display>): void 1354 1355获取当前默认的Display对象，使用callback异步回调。 1356 1357> **说明：** 1358> 1359> 从API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。 1360 1361**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1362 1363**参数：** 1364 1365| 参数名 | 类型 | 必填 | 说明 | 1366| -------- | -------- | -------- | -------- | 1367| callback | AsyncCallback<[Display](#display)> | 是 | 回调函数。返回当前默认的Display对象。 | 1368 1369**示例：** 1370 1371```ts 1372import { BusinessError } from '@kit.BasicServicesKit'; 1373 1374let displayClass: display.Display | null = null; 1375display.getDefaultDisplay((err: BusinessError, data: display.Display) => { 1376 const errCode: number = err.code; 1377 if (errCode) { 1378 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 1379 return; 1380 } 1381 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 1382 displayClass = data; 1383}); 1384``` 1385 1386## display.getDefaultDisplay<sup>(deprecated)</sup> 1387 1388getDefaultDisplay(): Promise<Display> 1389 1390获取当前默认的Display对象，使用Promise异步回调。 1391 1392> **说明：** 1393> 1394> 从API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。 1395 1396**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1397 1398**返回值：** 1399 1400| 类型 | 说明 | 1401| ---------------------------------- | ---------------------------------------------- | 1402| Promise<[Display](#display)> | Promise对象。返回当前默认的Display对象。 | 1403 1404**示例：** 1405 1406```ts 1407import { BusinessError } from '@kit.BasicServicesKit'; 1408 1409let displayClass: display.Display | null = null; 1410let promise: Promise<display.Display> = display.getDefaultDisplay(); 1411promise.then((data: display.Display) => { 1412 displayClass = data; 1413 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 1414}).catch((err: BusinessError) => { 1415 console.error(`Failed to obtain the default display object. Code: ${err.code}, message: ${err.message}`); 1416}); 1417``` 1418 1419## display.getAllDisplay<sup>(deprecated)</sup> 1420 1421getAllDisplay(callback: AsyncCallback<Array<Display>>): void 1422 1423获取当前所有的Display对象，使用callback异步回调。 1424 1425> **说明：** 1426> 1427> 从API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9)。 1428 1429**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1430 1431**参数：** 1432 1433| 参数名 | 类型 | 必填 | 说明 | 1434| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 1435| callback | AsyncCallback<Array<[Display](#display)>> | 是 | 回调函数。返回当前所有的Display对象。 | 1436 1437**示例：** 1438 1439```ts 1440import { BusinessError } from '@kit.BasicServicesKit'; 1441 1442display.getAllDisplay((err: BusinessError, data: Array<display.Display>) => { 1443 const errCode: number = err.code; 1444 if (errCode) { 1445 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1446 return; 1447 } 1448 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1449}); 1450``` 1451 1452## display.getAllDisplay<sup>(deprecated)</sup> 1453 1454getAllDisplay(): Promise<Array<Display>> 1455 1456获取当前所有的Display对象，使用Promise异步回调。 1457 1458> **说明：** 1459> 1460> 从API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9-1)。 1461 1462**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1463 1464**返回值：** 1465 1466| 类型 | 说明 | 1467| ----------------------------------------------- | ------------------------------------------------------- | 1468| Promise<Array<[Display](#display)>> | Promise对象。返回当前所有的Display对象。 | 1469 1470**示例：** 1471 1472```ts 1473import { BusinessError } from '@kit.BasicServicesKit'; 1474 1475let promise: Promise<Array<display.Display>> = display.getAllDisplay(); 1476promise.then((data: Array<display.Display>) => { 1477 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 1478}).catch((err: BusinessError) => { 1479 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1480}); 1481``` 1482 1483## Display 1484屏幕实例。描述Display对象的属性和方法。 1485 1486下列API示例中都需先使用[getAllDisplays()](#displaygetalldisplays9)、[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)中的任一方法获取到Display实例，再通过此实例调用对应方法。 1487 1488### 属性 1489 1490| 名称 | 类型 | 只读 | 可选 | 说明 | 1491| -------- | -------- | -------- | -------- |---------------------------------------------------------------------------------------------------------------| 1492| id | number | 是 | 否 | 屏幕id，该参数为大于等于0的整数。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1493| name | string | 是 | 否 | 显示设备的名称。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1494| alive | boolean | 是 | 否 | 显示设备是否启用。true表示设备启用，false表示设备未启用。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1495| state | [DisplayState](#displaystate) | 是 | 否 | 显示设备的状态。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1496| refreshRate | number | 是 | 否 | 显示设备当前采用的刷新率，该参数为整数，单位为Hz。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1497| rotation | number | 是 | 否 | 显示设备的屏幕顺时针旋转角度。<br>值为0时，表示显示设备屏幕顺时针旋转为0°；<br>值为1时，表示显示设备屏幕顺时针旋转为90°；<br>值为2时，表示显示设备屏幕顺时针旋转为180°；<br>值为3时，表示显示设备屏幕顺时针旋转为270°。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1498| width | number | 是 | 否 | 显示设备的屏幕宽度，单位为px，该参数为整数。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1499| height | number | 是 | 否 | 显示设备的屏幕高度，单位为px，该参数为整数。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1500| densityDPI | number | 是 | 否 | 显示设备屏幕的物理像素密度，表示每英寸上的像素点数。该参数为浮点数，单位为px。一般取值160.0、480.0等，实际能取到的值取决于不同设备设置里提供的可选值。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1501| orientation<sup>10+</sup> | [Orientation](#orientation10) | 是 | 否 | 表示屏幕当前显示的方向。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1502| densityPixels | number | 是 | 否 | 显示设备逻辑像素的密度，代表物理像素与逻辑像素的缩放系数，计算方式为：<br>该参数为浮点数，受densityDPI范围限制，取值范围在[0.5，4.0]。一般取值1.0、3.0等，实际取值取决于不同设备提供的densityDPI。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1503| scaledDensity | number | 是 | 否 | 显示设备的显示字体的缩放因子。该参数为浮点数，通常与densityPixels相同。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1504| xDPI | number | 是 | 否 | x方向中每英寸屏幕的确切物理像素值，该参数为浮点数。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1505| yDPI | number | 是 | 否 | y方向中每英寸屏幕的确切物理像素值，该参数为浮点数。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1506| colorSpaces<sup>11+</sup> | Array<[colorSpaceManager.ColorSpace](../apis-arkgraphics2d/js-apis-colorSpaceManager.md)> | 是 | 否 | 显示设备支持的所有色域类型。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1507| hdrFormats<sup>11+</sup> | Array<[hdrCapability.HDRFormat](../apis-arkgraphics2d/js-apis-hdrCapability.md)> | 是 | 否 | 显示设备支持的所有HDR格式。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1508| availableWidth<sup>12+</sup> | number | 是 | 否 | 2in1设备上屏幕的可用区域宽度，单位为px，该参数为大于0的整数。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1509| availableHeight<sup>12+</sup> | number | 是 | 否 | 2in1设备上屏幕的可用区域高度，单位为px，该参数为大于0的整数。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1510| screenShape<sup>18+</sup> | [ScreenShape](#screenshape18) | 是 | 是 | 显示设备的屏幕形状，默认值为RECTANGLE。<br/>**系统能力：** SystemCapability.WindowManager.WindowManager.Core<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 1511| sourceMode<sup>19+</sup> | [DisplaySourceMode](#displaysourcemode19) | 是 | 是 | 屏幕显示内容的显示模式枚举，默认值为DisplaySourceMode.NONE。<br/>**系统能力：** SystemCapability.Window.SessionManager <br>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 1512| x<sup>19+</sup> | number | 是 | 是 | 屏幕左上角相对于原点的x轴坐标，原点为主屏左上角，单位为px，该参数为整数，默认值为0。仅DisplaySourceMode为MAIN和EXTEND时返回。<br/>**系统能力：** SystemCapability.Window.SessionManager<br>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 1513| y<sup>19+</sup> | number | 是 | 是 | 屏幕左上角相对于原点的y轴坐标，原点为主屏左上角，单位为px，该参数为整数，默认值为0。仅DisplaySourceMode为MAIN和EXTEND时返回。<br/>**系统能力：** SystemCapability.Window.SessionManager<br>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 1514| supportedRefreshRates<sup>20+</sup> | Array<number> | 是 | 是 | 显示设备支持的所有刷新率，从小到大排序。刷新率值为正整数，单位为Hz。默认为空。<br/>**系统能力：** SystemCapability.Window.SessionManager<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 1515 1516 1517### getCutoutInfo<sup>9+</sup> 1518getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void 1519 1520获取挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。使用callback异步回调。建议应用布局规避该区域。 1521 1522**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1523 1524**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1525 1526**参数：** 1527 1528| 参数名 | 类型 | 必填 | 说明 | 1529| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 1530| callback | AsyncCallback<[CutoutInfo](#cutoutinfo9)> | 是 | 回调函数。返回描述不可用屏幕区域的CutoutInfo对象。 | 1531 1532**错误码：** 1533 1534以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 1535 1536| 错误码ID | 错误信息 | 1537| ------- | ----------------------- | 1538| 1400001 | Invalid display or screen. | 1539 1540**示例：** 1541 1542```ts 1543import { BusinessError } from '@kit.BasicServicesKit'; 1544 1545let displayClass: display.Display | null = null; 1546displayClass = display.getDefaultDisplaySync(); 1547 1548displayClass.getCutoutInfo((err: BusinessError, data: display.CutoutInfo) => { 1549 const errCode: number = err.code; 1550 if (errCode) { 1551 console.error(`Failed to get cutoutInfo. Code: ${err.code}, message: ${err.message}`); 1552 return; 1553 } 1554 console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data)); 1555}); 1556``` 1557### getCutoutInfo<sup>9+</sup> 1558getCutoutInfo(): Promise<CutoutInfo> 1559 1560获取挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。使用Promise异步回调。建议应用布局规避该区域。 1561 1562**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1563 1564**系统能力：** SystemCapability.WindowManager.WindowManager.Core 1565 1566**返回值：** 1567 1568| 类型 | 说明 | 1569| ------------------- | ------------------------- | 1570| Promise<[CutoutInfo](#cutoutinfo9)> | Promise对象。返回描述不可用屏幕区域的CutoutInfo对象。 | 1571 1572**错误码：** 1573 1574以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 1575 1576| 错误码ID | 错误信息 | 1577| ------- | ----------------------- | 1578| 1400001 | Invalid display or screen. | 1579 1580**示例：** 1581 1582```ts 1583import { BusinessError } from '@kit.BasicServicesKit'; 1584 1585let displayClass: display.Display | null = null; 1586displayClass = display.getDefaultDisplaySync(); 1587let promise: Promise<display.CutoutInfo> = displayClass.getCutoutInfo(); 1588promise.then((data: display.CutoutInfo) => { 1589 console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data)); 1590}).catch((err: BusinessError) => { 1591 console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`); 1592}); 1593``` 1594 1595### getAvailableArea<sup>12+</sup> 1596getAvailableArea(): Promise<Rect> 1597 1598获取当前设备屏幕的可用区域，使用Promise异步回调。 1599 1600**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1601 1602**系统能力：** SystemCapability.Window.SessionManager 1603 1604**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用；在其他设备中不可用，请通过[Display属性](#属性)中的width、height属性获取当前设备屏幕的可用区域。 1605 1606**返回值：** 1607 1608| 类型 | 说明 | 1609| ------------------- | ------------------------- | 1610| Promise<[Rect](#rect9)> | Promise对象。返回当前屏幕可用矩形区域。 | 1611 1612**错误码：** 1613 1614以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1615 1616| 错误码ID | 错误信息 | 1617| ------- | ----------------------- | 1618| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1619| 1400001 | Invalid display or screen. | 1620 1621**示例：** 1622 1623```ts 1624import { BusinessError } from '@kit.BasicServicesKit'; 1625import { display } from '@kit.ArkUI'; 1626 1627let displayClass: display.Display | null = null; 1628try { 1629 displayClass = display.getDefaultDisplaySync(); 1630 let promise = displayClass.getAvailableArea(); 1631 promise.then((data) => { 1632 console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(data)); 1633 }).catch((err: BusinessError) => { 1634 console.error(`Failed to get the available area in this display. Code: ${err.code}, message: ${err.message}`); 1635 }) 1636} catch (exception) { 1637 console.error(`Failed to obtain the default display object. Code: ${exception.code}, message: ${exception.message}`); 1638} 1639``` 1640 1641### on('availableAreaChange')<sup>12+</sup> 1642on(type: 'availableAreaChange', callback: Callback<Rect>): void 1643 1644开启当前设备屏幕的可用区域监听。当前设备屏幕有可用区域变化时，触发回调函数，返回可用区域。 1645 1646**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1647 1648**系统能力：** SystemCapability.Window.SessionManager 1649 1650**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中不生效也不报错。 1651 1652**参数：** 1653 1654| 参数名 | 类型 | 必填 | 说明 | 1655| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1656| type | string | 是 | 监听事件。固定为'availableAreaChange'，表示屏幕可用区域变更。 | 1657| callback | Callback<[Rect](#rect9)> | 是 | 回调函数。返回改变后的可用区域。 | 1658 1659**错误码：** 1660 1661以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1662 1663| 错误码ID | 错误信息 | 1664| ------- | ----------------------- | 1665| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1666| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1667| 1400003 | This display manager service works abnormally. | 1668 1669**示例：** 1670 1671```ts 1672import { Callback } from '@kit.BasicServicesKit'; 1673import { display } from '@kit.ArkUI'; 1674 1675let callback: Callback<display.Rect> = (data: display.Rect) => { 1676 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1677}; 1678let displayClass: display.Display | null = null; 1679try { 1680 displayClass = display.getDefaultDisplaySync(); 1681 displayClass.on("availableAreaChange", callback); 1682} catch (exception) { 1683 console.error(`Failed to register callback. Code: ${exception.code}, message: ${exception.message}`); 1684} 1685``` 1686 1687### off('availableAreaChange')<sup>12+</sup> 1688 1689off(type: 'availableAreaChange', callback?: Callback<Rect>): void 1690 1691关闭当前设备屏幕可用区域变化的监听。 1692 1693**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1694 1695**系统能力：** SystemCapability.Window.SessionManager 1696 1697**设备行为差异：** 该接口在2in1设备、Tablet设备中可正常调用，在其他设备中不生效也不报错。 1698 1699**参数：** 1700 1701| 参数名 | 类型 | 必填 | 说明 | 1702| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 1703| type | string | 是 | 监听事件，固定为'availableAreaChange'，表示屏幕可用区域变更。 | 1704| callback | Callback<[Rect](#rect9)> | 否 | 需要取消注册的回调函数。返回改变后的可用区域。若无此参数，则取消注册屏幕可用区域变化监听的所有回调函数。 | 1705 1706**错误码：** 1707 1708以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1709 1710| 错误码ID | 错误信息 | 1711| ------- | ----------------------- | 1712| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.| 1713| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1714| 1400003 | This display manager service works abnormally. | 1715 1716**示例：** 1717 1718```ts 1719import { Callback } from '@kit.BasicServicesKit'; 1720import { display } from '@kit.ArkUI'; 1721 1722let callback: Callback<display.Rect> = (data: display.Rect) => { 1723 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 1724}; 1725let displayClass: display.Display | null = null; 1726try { 1727 displayClass = display.getDefaultDisplaySync(); 1728 displayClass.off("availableAreaChange", callback); 1729} catch (exception) { 1730 console.error(`Failed to unregister callback. Code: ${exception.code}, message: ${exception.message}`); 1731} 1732``` 1733 1734### getLiveCreaseRegion<sup>20+</sup> 1735getLiveCreaseRegion(): FoldCreaseRegion 1736 1737获取当前显示模式下的实时折痕区域。 1738 1739**系统能力：** SystemCapability.Window.SessionManager 1740 1741**返回值：** 1742 1743| 类型 | 说明 | 1744| ------------------- | ------------------------- | 1745| [FoldCreaseRegion](#foldcreaseregion10) | 返回设备在当前显示模式下的折叠折痕区域。 | 1746 1747**错误码：** 1748 1749以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[屏幕错误码](errorcode-display.md)。 1750 1751| 错误码ID | 错误信息 | 1752| ------- | ----------------------- | 1753| 801 | Capability not supported. Failed to call the API due to limited device capabilities. | 1754| 1400003 | This display manager service works abnormally. | 1755 1756**示例：** 1757 1758```ts 1759import { display } from '@kit.ArkUI'; 1760 1761let displayClass: display.Display | null = null; 1762try { 1763 displayClass = display.getDefaultDisplaySync(); 1764 let data: display.FoldCreaseRegion = displayClass.getLiveCreaseRegion(); 1765 console.info('Succeeded in getting the live crease region. Data: ' + JSON.stringify(data)); 1766} catch (exception) { 1767 console.error(`Failed to get the live crease region. Code: ${exception.code}, message: ${exception.message}`); 1768} 1769```
