1# @ohos.display (屏幕属性) 2 3屏幕属性提供管理显示设备的一些基础能力，包括获取默认显示设备的信息，获取所有显示设备的信息以及监听显示设备的插拔行为。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 12import display from '@ohos.display'; 13``` 14 15## DisplayState 16 17显示设备的状态枚举。 18 19**系统能力：** SystemCapability.WindowManager.WindowManager.Core 20 21| 名称 | 值 | 说明 | 22| -------- | -------- | -------- | 23| STATE_UNKNOWN | 0 | 表示显示设备状态未知。| 24| STATE_OFF | 1 | 表示显示设备状态为关闭。 | 25| STATE_ON | 2 | 表示显示设备状态为开启。| 26| STATE_DOZE | 3 | 表示显示设备为低电耗模式。| 27| STATE_DOZE_SUSPEND | 4 | 表示显示设备为睡眠模式，CPU为挂起状态。 | 28| STATE_VR | 5 | 表示显示设备为VR模式。| 29| STATE_ON_SUSPEND | 6 | 表示显示设备为开启状态，CPU为挂起状态。 | 30 31## Rect<sup>9+</sup> 32 33矩形区域。 34 35**系统能力：** SystemCapability.WindowManager.WindowManager.Core 36 37| 名称 | 类型 | 可读 | 可写 | 说明 | 38| ------ | -------- | ---- | ---- | ------------------ | 39| left | number | 是 | 是 | 矩形区域的左边界，单位为像素。 | 40| top | number | 是 | 是 | 矩形区域的上边界，单位为像素。 | 41| width | number | 是 | 是 | 矩形区域的宽度，单位为像素。 | 42| height | number | 是 | 是 | 矩形区域的高度，单位为像素。 | 43 44## WaterfallDisplayAreaRects<sup>9+</sup> 45 46瀑布屏曲面部分显示区域。 47 48**系统能力：** SystemCapability.WindowManager.WindowManager.Core 49 50| 名称 | 类型 | 可读 | 可写 | 说明 | 51| ------ | ------------- | ---- | ---- | ------------------ | 52| left | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的左侧矩形区域。 | 53| top | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的顶部矩形区域。 | 54| right | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的右侧矩形区域。 | 55| bottom | [Rect](#rect9) | 是 | 否 | 瀑布曲面区域的底部矩形区域。 | 56 57## CutoutInfo<sup>9+</sup> 58 59挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。 60 61**系统能力：** SystemCapability.WindowManager.WindowManager.Core 62 63| 名称 | 类型 | 可读 | 可写 | 说明 | 64| --------------------------- | ------------- | ---- | ---- | ------------------ | 65| boundingRects | Array\<[Rect](#rect9)> | 是 | 否 | 挖孔、刘海等区域的边界矩形。 | 66| waterfallDisplayAreaRects | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | 是 | 否 | 瀑布屏曲面部分显示区域。 | 67 68## display.getDefaultDisplaySync<sup>9+</sup> 69 70getDefaultDisplaySync(): Display 71 72获取当前默认的display对象。 73 74**系统能力：** SystemCapability.WindowManager.WindowManager.Core 75 76**返回值：** 77 78| 类型 | 说明 | 79| ------------------------------| ----------------------------------------------| 80| [Display](#display) | 返回默认的display对象。 | 81 82**错误码：** 83 84以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 85 86| 错误码ID | 错误信息 | 87| ------- | ----------------------- | 88| 1400001 | Invalid display or screen. | 89 90**示例：** 91 92```js 93let displayClass = null; 94try { 95 displayClass = display.getDefaultDisplaySync(); 96} catch (exception) { 97 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 98} 99``` 100 101## display.getAllDisplays<sup>9+</sup> 102 103getAllDisplays(callback: AsyncCallback<Array<Display>>): void 104 105获取当前所有的display对象，使用callback异步回调。 106 107**系统能力：** SystemCapability.WindowManager.WindowManager.Core 108 109**参数：** 110 111| 参数名 | 类型 | 必填 | 说明 | 112| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 113| callback | AsyncCallback<Array<[Display](#display)>> | 是 | 回调函数。返回当前所有的display对象。 | 114 115**错误码：** 116 117以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 118 119| 错误码ID | 错误信息 | 120| ------- | ----------------------- | 121| 1400001 | Invalid display or screen. | 122 123**示例：** 124 125```js 126let displayClass = null; 127display.getAllDisplays((err, data) => { 128 displayClass = data; 129 if (err.code) { 130 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 131 return; 132 } 133 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 134}); 135``` 136 137## display.getAllDisplays<sup>9+</sup> 138 139getAllDisplays(): Promise<Array<Display>> 140 141获取当前所有的display对象，使用Promise异步回调。 142 143**系统能力：** SystemCapability.WindowManager.WindowManager.Core 144 145**返回值：** 146 147| 类型 | 说明 | 148| ----------------------------------------------- | ------------------------------------------------------- | 149| Promise<Array<[Display](#display)>> | Promise对象。返回当前所有的display对象。 | 150 151**错误码：** 152 153以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 154 155| 错误码ID | 错误信息 | 156| ------- | ----------------------- | 157| 1400001 | Invalid display or screen. | 158 159**示例：** 160 161```js 162let displayClass = null; 163let promise = display.getAllDisplays(); 164promise.then((data) => { 165 displayClass = data; 166 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 167}).catch((err) => { 168 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 169}); 170``` 171 172## display.hasPrivateWindow<sup>9+</sup> 173 174hasPrivateWindow(displayId: number): boolean 175 176查询指定display对象上是否有可见的隐私窗口。可通过[setWindowPrivacyMode()](js-apis-window.md#setwindowprivacymode9)接口设置隐私窗口。隐私窗口内容将无法被截屏或录屏。 177 178**系统接口：** 此接口为系统接口。 179 180**系统能力：** SystemCapability.WindowManager.WindowManager.Core 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| ------ | ------------------------- | ---- |----------| 186| id | number | 是 | 显示设备的id。 | 187 188**返回值：** 189 190| 类型 | 说明 | 191| -------------------------------- |-----------------------------------------------------------------------| 192|boolean | 查询的display对象上是否有可见的隐私窗口。<br>true表示此display对象上有可见的隐私窗口，false表示此display对象上没有可见的隐私窗口。</br> | 193 194**错误码：** 195 196以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 197 198| 错误码ID | 错误信息 | 199| ------- | -------------------------------------------- | 200| 1400003 | This display manager service works abnormally. | 201 202**示例：** 203 204```js 205let displayClass = null; 206try { 207 displayClass = display.getDefaultDisplaySync(); 208 209 let ret = undefined; 210 try { 211 ret = display.hasPrivateWindow(displayClass.id); 212 } catch (exception) { 213 console.error('Failed to check has privateWindow or not. Code: ' + JSON.stringify(exception)); 214 } 215 if (ret == undefined) { 216 console.log("Failed to check has privateWindow or not."); 217 } 218 if (ret) { 219 console.log("There has privateWindow."); 220 } else if (!ret) { 221 console.log("There has no privateWindow."); 222 } 223} catch (exception) { 224 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 225} 226``` 227 228## display.on('add'|'remove'|'change') 229 230on(type: 'add'|'remove'|'change', callback: Callback<number>): void 231 232开启显示设备变化的监听。 233 234**系统能力：** SystemCapability.WindowManager.WindowManager.Core 235 236**参数：** 237 238| 参数名 | 类型 | 必填 | 说明 | 239| -------- | -------- | -------- | -------- | 240| type | string | 是 | 监听事件。<br/>- type为"add"，表示增加显示设备事件。例如：插入显示器。<br/>- type为"remove"，表示移除显示设备事件。例如：移除显示器。<br/>- type为"change"，表示改变显示设备事件。例如：显示器方向改变。 | 241| callback | Callback<number> | 是 | 回调函数。返回监听到的显示设备的id。 | 242 243**示例：** 244 245```js 246let callback = (data) => { 247 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 248}; 249try { 250 display.on("add", callback); 251} catch (exception) { 252 console.error('Failed to register callback. Code: ' + JSON.stringify(exception)); 253} 254``` 255 256## display.off('add'|'remove'|'change') 257 258off(type: 'add'|'remove'|'change', callback?: Callback<number>): void 259 260关闭显示设备变化的监听。 261 262**系统能力：** SystemCapability.WindowManager.WindowManager.Core 263 264**参数：** 265 266| 参数名 | 类型 | 必填 | 说明 | 267| -------- | -------- | -------- | -------- | 268| type | string | 是 | 监听事件。<br/>- type为"add"，表示增加显示设备事件。例如：插入显示器。<br/>- type为"remove"，表示移除显示设备事件。例如：移除显示器。<br/>- type为"change"，表示改变显示设备事件。例如：显示器方向改变。 | 269| callback | Callback<number> | 否 | 回调函数。返回监听到的显示设备的id。 | 270 271**示例：** 272 273```js 274try { 275 display.off("remove"); 276} catch (exception) { 277 console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception)); 278} 279``` 280 281## display.getDefaultDisplay<sup>(deprecated)</sup> 282 283getDefaultDisplay(callback: AsyncCallback<Display>): void 284 285获取当前默认的display对象，使用callback异步回调。 286 287> **说明：** 288> 289> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。 290 291**系统能力：** SystemCapability.WindowManager.WindowManager.Core 292 293**参数：** 294 295| 参数名 | 类型 | 必填 | 说明 | 296| -------- | -------- | -------- | -------- | 297| callback | AsyncCallback<[Display](#display)> | 是 | 回调函数。返回当前默认的display对象。 | 298 299**示例：** 300 301```js 302let displayClass = null; 303display.getDefaultDisplay((err, data) => { 304 if (err.code) { 305 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(err)); 306 return; 307 } 308 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 309 displayClass = data; 310}); 311``` 312 313## display.getDefaultDisplay<sup>(deprecated)</sup> 314 315getDefaultDisplay(): Promise<Display> 316 317获取当前默认的display对象，使用Promise异步回调。 318 319> **说明：** 320> 321> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。 322 323**系统能力：** SystemCapability.WindowManager.WindowManager.Core 324 325**返回值：** 326 327| 类型 | 说明 | 328| ---------------------------------- | ---------------------------------------------- | 329| Promise<[Display](#display)> | Promise对象。返回当前默认的display对象。 | 330 331**示例：** 332 333```js 334let displayClass = null; 335let promise = display.getDefaultDisplay(); 336promise.then((data) => { 337 displayClass = data; 338 console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data)); 339}).catch((err) => { 340 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(err)); 341}); 342``` 343 344## display.getAllDisplay<sup>(deprecated)</sup> 345 346getAllDisplay(callback: AsyncCallback<Array<Display>>): void 347 348获取当前所有的display对象，使用callback异步回调。 349 350> **说明：** 351> 352> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9)。 353 354**系统能力：** SystemCapability.WindowManager.WindowManager.Core 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| -------- | ---------------------------------------------------- | ---- | ------------------------------- | 360| callback | AsyncCallback<Array<[Display](#display)>> | 是 | 回调函数。返回当前所有的display对象。 | 361 362**示例：** 363 364```js 365display.getAllDisplay((err, data) => { 366 if (err.code) { 367 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 368 return; 369 } 370 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 371}); 372``` 373 374## display.getAllDisplay<sup>(deprecated)</sup> 375 376getAllDisplay(): Promise<Array<Display>> 377 378获取当前所有的display对象，使用Promise异步回调。 379 380> **说明：** 381> 382> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9-1)。 383 384**系统能力：** SystemCapability.WindowManager.WindowManager.Core 385 386**返回值：** 387 388| 类型 | 说明 | 389| ----------------------------------------------- | ------------------------------------------------------- | 390| Promise<Array<[Display](#display)>> | Promise对象。返回当前所有的display对象。 | 391 392**示例：** 393 394```js 395let promise = display.getAllDisplay(); 396promise.then((data) => { 397 console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data)); 398}).catch((err) => { 399 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 400}); 401``` 402 403## Display 404屏幕实例。描述display对象的属性和方法。 405 406下列API示例中都需先使用[getAllDisplays()](#displaygetalldisplays9)、[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)中的任一方法获取到Display实例，再通过此实例调用对应方法。 407 408### 属性 409 410**系统能力：** SystemCapability.WindowManager.WindowManager.Core 411 412| 名称 | 类型 | 可读 | 可写 | 说明 | 413| -------- | -------- | -------- | -------- | -------- | 414| id | number | 是 | 否 | 显示设备的id号。| 415| name | string | 是 | 否 | 显示设备的名称。| 416| alive | boolean | 是 | 否 | 显示设备是否启用。| 417| state | [DisplayState](#displaystate) | 是 | 否 | 显示设备的状态。| 418| refreshRate | number | 是 | 否 | 显示设备的刷新率。| 419| rotation | number | 是 | 否 | 显示设备的屏幕旋转角度。<br>值为0时，表示显示设备屏幕旋转为0°；<br>值为1时，表示显示设备屏幕旋转为90°；<br>值为2时，表示显示设备屏幕旋转为180°；<br>值为3时，表示显示设备屏幕旋转为270°。| 420| width | number | 是 | 否 | 显示设备的宽度，单位为像素。| 421| height | number | 是 | 否 | 显示设备的高度，单位为像素。| 422| densityDPI | number | 是 | 否 | 显示设备的屏幕密度，表示每英寸点数。一般取值160，480等。 | 423| densityPixels | number | 是 | 否 | 显示设备的逻辑密度，是像素单位无关的缩放系数。一般取值1，3等。 | 424| scaledDensity | number | 是 | 否 | 显示设备的显示字体的缩放因子。通常与densityPixels相同。 | 425| xDPI | number | 是 | 否 | x方向中每英寸屏幕的确切物理像素值。 | 426| yDPI | number | 是 | 否 | y方向中每英寸屏幕的确切物理像素值。| 427 428### getCutoutInfo<sup>9+</sup> 429getCutoutInfo(callback: AsyncCallback<CutoutInfo>): void 430 431获取挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。使用callback异步回调。建议应用布局规避该区域。 432 433**系统能力：** SystemCapability.WindowManager.WindowManager.Core 434 435**参数：** 436 437| 参数名 | 类型 | 必填 | 说明 | 438| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 439| callback | AsyncCallback<[CutoutInfo](#cutoutinfo9)> | 是 | 回调函数。返回描述不可用屏幕区域的CutoutInfo对象。。 | 440 441**错误码：** 442 443以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 444 445| 错误码ID | 错误信息 | 446| ------- | ----------------------- | 447| 1400001 | Invalid display or screen. | 448 449**示例：** 450 451```js 452let displayClass = null; 453try { 454 displayClass = display.getDefaultDisplaySync(); 455 456 displayClass.getCutoutInfo((err, data) => { 457 if (err.code) { 458 console.error('Failed to get cutoutInfo. Code: ' + JSON.stringify(err)); 459 return; 460 } 461 console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data)); 462 }); 463} catch (exception) { 464 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 465} 466``` 467### getCutoutInfo<sup>9+</sup> 468getCutoutInfo(): Promise<CutoutInfo> 469 470获取挖孔屏、刘海屏、瀑布屏等不可用屏幕区域信息。使用Promise异步回调。建议应用布局规避该区域。 471 472**系统能力：** SystemCapability.WindowManager.WindowManager.Core 473 474**返回值：** 475 476| 类型 | 说明 | 477| ------------------- | ------------------------- | 478| Promise<[CutoutInfo](#cutoutinfo9)> | Promise对象。返回描述不可用屏幕区域的CutoutInfo对象。 | 479 480**错误码：** 481 482以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。 483 484| 错误码ID | 错误信息 | 485| ------- | ----------------------- | 486| 1400001 | Invalid display or screen. | 487 488**示例：** 489 490```js 491let displayClass = null; 492try { 493 displayClass = display.getDefaultDisplaySync(); 494 495 let promise = displayClass.getCutoutInfo(); 496 promise.then((data) => { 497 console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data)); 498 }).catch((err) => { 499 console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err)); 500 }); 501} catch (exception) { 502 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 503} 504``` 505