1# @ohos.display (屏幕属性)(系统接口) 2 3屏幕属性提供管理显示设备的一些基础能力，包括获取默认显示设备的信息，获取所有显示设备的信息以及监听显示设备的插拔行为。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohso.display (屏幕属性)](js-apis-display.md)。 10 11## 导入模块 12 13```ts 14import display from '@ohos.display'; 15``` 16 17## display.hasPrivateWindow<sup>9+</sup> 18 19hasPrivateWindow(displayId: number): boolean 20 21查询指定display对象上是否有可见的隐私窗口。可通过[setWindowPrivacyMode()](js-apis-window.md#setwindowprivacymode9)接口设置隐私窗口。隐私窗口内容将无法被截屏或录屏。 22 23**系统接口：** 此接口为系统接口。 24 25**系统能力：** SystemCapability.WindowManager.WindowManager.Core 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------ | ------------------------- | ---- |----------| 31| id | number | 是 | 显示设备的id，该参数仅支持整数输入。 | 32 33**返回值：** 34 35| 类型 | 说明 | 36| -------------------------------- |-----------------------------------------------------------------------| 37|boolean | 查询的display对象上是否有可见的隐私窗口。<br>true表示此display对象上有可见的隐私窗口，false表示此display对象上没有可见的隐私窗口。</br> | 38 39**错误码：** 40 41以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 42 43| 错误码ID | 错误信息 | 44| ------- | -------------------------------------------- | 45| 1400003 | This display manager service works abnormally. | 46 47**示例：** 48 49```ts 50import display from '@ohos.display'; 51 52let displayClass: display.Display | null = null; 53try { 54 displayClass = display.getDefaultDisplaySync(); 55 56 let ret: boolean = true; 57 try { 58 ret = display.hasPrivateWindow(displayClass.id); 59 } catch (exception) { 60 console.error('Failed to check has privateWindow or not. Code: ' + JSON.stringify(exception)); 61 } 62 if (ret == undefined) { 63 console.log("Failed to check has privateWindow or not."); 64 } 65 if (ret) { 66 console.log("There has privateWindow."); 67 } else if (!ret) { 68 console.log("There has no privateWindow."); 69 } 70} catch (exception) { 71 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 72} 73``` 74 75## display.on('privateModeChange')<sup>10+</sup> 76 77on(type: 'privateModeChange', callback: Callback<boolean>): void 78 79开启屏幕隐私模式变化的监听。当屏幕前台有隐私窗口，则屏幕处于隐私模式，屏幕中的隐私窗口内容无法被截屏或录屏。 80 81**系统接口：** 此接口为系统接口。 82 83**系统能力：** SystemCapability.WindowManager.WindowManager.Core 84 85**参数：** 86 87| 参数名 | 类型 | 必填 | 说明 | 88| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 89| type | string | 是 | 监听事件，固定为'privateModeChange'，表示屏幕隐私模式状态发生变化。 | 90| callback | Callback<boolean> | 是 | 回调函数。表示屏幕隐私模式是否改变。true表示屏幕由非隐私窗口模式变为隐私模式，false表示屏幕由隐私模式变为非隐私模式。 | 91 92**示例：** 93 94```ts 95import { Callback } from '@ohos.base'; 96 97let callback: Callback<boolean> = (data: boolean) => { 98 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 99}; 100try { 101 display.on("privateModeChange", callback); 102} catch (exception) { 103 console.error('Failed to register callback. Code: ' + JSON.stringify(exception)); 104} 105``` 106 107## display.off('privateModeChange')<sup>10+</sup> 108 109off(type: 'privateModeChange', callback?: Callback<boolean>): void 110 111关闭屏幕隐私模式变化的监听。当屏幕前台有隐私窗口，则屏幕处于隐私模式，屏幕中的隐私窗口内容无法被截屏或录屏。 112 113**系统接口：** 此接口为系统接口。 114 115**系统能力：** SystemCapability.WindowManager.WindowManager.Core 116 117**参数：** 118 119| 参数名 | 类型 | 必填 | 说明 | 120| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 121| type | string | 是 | 监听事件，固定为'privateModeChange'，表示屏幕隐私模式状态发生变化。 | 122| callback | Callback<boolean> | 否 | 回调函数。表示屏幕隐私模式是否改变。true表示屏幕由非隐私模式变为隐私模式，false表示屏幕由隐私模式变为非隐私模式。 | 123 124**示例：** 125 126```ts 127try { 128 display.off("privateModeChange"); 129} catch (exception) { 130 console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception)); 131} 132``` 133 134## display.setFoldDisplayMode<sup>10+</sup> 135setFoldDisplayMode(mode: FoldDisplayMode): void 136 137更改可折叠设备的显示模式。 138 139**系统接口：** 此接口为系统接口。 140 141**系统能力：** SystemCapability.Window.SessionManager 142 143**参数：** 144 145| 参数名 | 类型 | 必填 | 说明 | 146| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 147| mode | [FoldDisplayMode](js-apis-display.md#folddisplaymode10) | 是 | 可折叠设备的显示模式。 | 148 149**错误码：** 150 151以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 152 153| 错误码ID | 错误信息 | 154| ------- | ----------------------- | 155| 1400003 | This display manager service works abnormally. | 156 157**示例：** 158 159```ts 160import display from '@ohos.display'; 161 162try { 163 let mode: display.FoldDisplayMode = display.FoldDisplayMode.FOLD_DISPLAY_MODE_FULL; 164 display.setFoldDisplayMode(mode); 165} catch (exception) { 166 console.error('Failed to change the fold display mode. Code: ' + JSON.stringify(exception)); 167} 168``` 169 170## display.setFoldStatusLocked<sup>11+</sup> 171setFoldStatusLocked(locked: boolean): void 172 173设置可折叠设备当前折叠状态的锁定状态。 174 175**系统接口：** 此接口为系统接口。 176 177**系统能力：** SystemCapability.Window.SessionManager 178 179**参数：** 180 181| 参数名 | 类型 | 必填 | 说明 | 182| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 183| locked | boolean | 是 | 可折叠设备的折叠状态是否锁定。true表示锁定，false表示不锁定。 | 184 185**错误码：** 186 187以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 188 189| 错误码ID | 错误信息 | 190| ------- | ----------------------- | 191| 1400003 | This display manager service works abnormally. | 192 193**示例：** 194 195```ts 196import display from '@ohos.display'; 197 198try { 199 let locked: boolean = false; 200 display.setFoldStatusLocked(locked); 201} catch (exception) { 202 console.error('Failed to change the fold status locked mode. Code: ' + JSON.stringify(exception)); 203} 204``` 205 206## Display 207屏幕实例。描述display对象的属性和方法。 208 209下列API示例中都需先使用[getAllDisplays()](js-apis-display.md#displaygetalldisplays9)、[getDefaultDisplaySync()](js-apis-display.md#displaygetdefaultdisplaysync9)中的任一方法获取到Display实例，再通过此实例调用对应方法。 210 211### hasImmersiveWindow<sup>11+</sup> 212hasImmersiveWindow(callback: AsyncCallback<boolean>): void 213 214判断当前屏幕是否包含沉浸式窗口，使用callback异步回调。 215 216**系统接口：** 此接口为系统接口。 217 218**系统能力：** SystemCapability.Window.SessionManager 219 220**参数：** 221 222| 参数名 | 类型 | 必填 | 说明 | 223| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | 224| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前屏幕包含沉浸式窗口，false表示不包含。 | 225 226**错误码：** 227 228以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 229 230| 错误码ID | 错误信息 | 231| ------- | ----------------------- | 232| 1400001 | Invalid display or screen. | 233| 1400003 | This display manager service works abnormally. | 234 235**示例：** 236 237```ts 238import { BusinessError } from '@ohos.base'; 239import display from '@ohos.display' 240 241let displayClass: display.Display | null = null; 242try { 243 displayClass = display.getDefaultDisplaySync(); 244} catch (exception) { 245 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 246} 247 248try { 249 displayClass.hasImmersiveWindow((err: BusinessError, data) => { 250 const errCode: number = err.code; 251 if (errCode) { 252 console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err)); 253 return; 254 } 255 console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data)); 256 }); 257} catch (exception) { 258 console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(exception)); 259} 260``` 261### hasImmersiveWindow<sup>11+</sup> 262hasImmersiveWindow(): Promise<boolean> 263 264判断当前屏幕是否包含沉浸式窗口，使用Promise异步回调。 265 266**系统接口：** 此接口为系统接口。 267 268**系统能力：** SystemCapability.Window.SessionManager 269 270**返回值：** 271 272| 类型 | 说明 | 273| ------------------- | ------------------------- | 274| Promise<boolean> | Promise对象。返回true表示当前屏幕包含沉浸式窗口，false表示不包含。 | 275 276**错误码：** 277 278以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 279 280| 错误码ID | 错误信息 | 281| ------- | ----------------------- | 282| 1400001 | Invalid display or screen. | 283| 1400003 | This display manager service works abnormally. | 284 285**示例：** 286 287```ts 288import { BusinessError } from '@ohos.base'; 289import display from '@ohos.display' 290 291let displayClass: display.Display | null = null; 292try { 293 displayClass = display.getDefaultDisplaySync(); 294} catch (exception) { 295 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 296} 297 298let promise = displayClass.hasImmersiveWindow(); 299promise.then((data) => { 300 console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data)); 301}).catch((err: BusinessError) => { 302 console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err)); 303}) 304``` 305 306### getAvailableArea<sup>11+</sup> 307getAvailableArea(): Promise<Rect> 308 309获取当前屏幕的可用区域，使用Promise异步回调。 310 311**系统接口：** 此接口为系统接口。 312 313**系统能力：** SystemCapability.Window.SessionManager 314 315**返回值：** 316 317| 类型 | 说明 | 318| ------------------- | ------------------------- | 319| Promise<[Rect](js-apis-display.md#rect9)> | Promise对象。返回当前屏幕可用矩形区域。 | 320 321**错误码：** 322 323以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 324 325| 错误码ID | 错误信息 | 326| ------- | ----------------------- | 327| 1400001 | Invalid display or screen. | 328 329**示例：** 330 331```ts 332import { BusinessError } from '@ohos.base'; 333import display from '@ohos.display' 334 335let displayClass: display.Display | null = null; 336try { 337 displayClass = display.getDefaultDisplaySync(); 338 let promise = displayClass.getAvailableArea(); 339 promise.then((data) => { 340 console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(data)); 341 }).catch((err: BusinessError) => { 342 console.error('Failed to get the available area in this display. Code: ' + JSON.stringify(err)); 343 }) 344} catch (exception) { 345 console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); 346} 347``` 348 349### on('availableAreaChange')<sup>11+</sup> 350on(type: 'availableAreaChange', callback: Callback<Rect>): void 351 352开启当前屏幕的可用区域监听。当前屏幕有可用区域变化时，触发回调函数，返回可用区域。 353 354**系统接口：** 此接口为系统接口。 355 356**系统能力：** SystemCapability.Window.SessionManager 357 358**参数：** 359 360| 参数名 | 类型 | 必填 | 说明 | 361| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 362| type | string | 是 | 监听事件，固定为'availableAreaChange'，表示屏幕可用区域变更。 | 363| callback | Callback<[Rect](js-apis-display.md#rect9)> | 是 | 回调函数，返回改变后的可用区域。 | 364 365**错误码：** 366 367以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 368 369| 错误码ID | 错误信息 | 370| ------- | ----------------------- | 371| 1400003 | This display manager service works abnormally. | 372 373**示例：** 374 375```ts 376import { Callback } from '@ohos.base'; 377import display from '@ohos.display' 378 379let callback: Callback<display.Rect> = (data: display.Rect) => { 380 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 381}; 382let displayClass: display.Display | null = null; 383try { 384 displayClass = display.getDefaultDisplaySync(); 385 displayClass.on("availableAreaChange", callback); 386} catch (exception) { 387 console.error('Failed to register callback. Code: ' + JSON.stringify(exception)); 388} 389``` 390 391### off('availableAreaChange')<sup>11+</sup> 392 393off(type: 'availableAreaChange', callback?: Callback<Rect>): void 394 395关闭屏幕可用区域变化的监听。 396 397**系统接口：** 此接口为系统接口。 398 399**系统能力：** SystemCapability.Window.SessionManager 400 401**参数：** 402 403| 参数名 | 类型 | 必填 | 说明 | 404| -------- |------------------------------------------| ---- | ------------------------------------------------------- | 405| type | string | 是 | 监听事件，固定为'availableAreaChange'，表示屏幕可用区域变更。 | 406| callback | Callback<[Rect](js-apis-display.md#rect9)> | 否 | 回调函数，已经注册的回调函数，不填默认删除所有回调 | 407 408**错误码：** 409 410以下错误码的详细介绍请参见[屏幕错误码](errorcode-display.md)。 411 412| 错误码ID | 错误信息 | 413| ------- | ----------------------- | 414| 1400003 | This display manager service works abnormally. | 415 416**示例：** 417 418```ts 419import { Callback } from '@ohos.base'; 420import display from '@ohos.display' 421 422let callback: Callback<display.Rect> = (data: display.Rect) => { 423 console.info('Listening enabled. Data: ' + JSON.stringify(data)); 424}; 425let displayClass: display.Display | null = null; 426try { 427 displayClass = display.getDefaultDisplaySync(); 428 displayClass.off("availableAreaChange", callback); 429} catch (exception) { 430 console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception)); 431} 432``` 433