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