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