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