@ohos.display (屏幕属性)(系统接口)

屏幕属性提供管理显示设备的一些基础能力，包括获取默认显示设备的信息，获取所有显示设备的信息以及监听显示设备的插拔行为。

说明：

  • 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

  • 当前页面仅包含本模块的系统接口，其他公开接口参见@ohso.display (屏幕属性)。

导入模块

import display from '@ohos.display';

display.hasPrivateWindow9+

hasPrivateWindow(displayId: number): boolean

查询指定display对象上是否有可见的隐私窗口。可通过setWindowPrivacyMode()接口设置隐私窗口。隐私窗口内容将无法被截屏或录屏。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.WindowManager.WindowManager.Core

参数：

参数名 类型 必填 说明
id number 是 显示设备的id，该参数仅支持整数输入。

返回值：

类型 说明
boolean 查询的display对象上是否有可见的隐私窗口。
true表示此display对象上有可见的隐私窗口，false表示此display对象上没有可见的隐私窗口。

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400003 This display manager service works abnormally.

示例：

import display from '@ohos.display';

let displayClass: display.Display | null = null;
try {
  displayClass = display.getDefaultDisplaySync();

  let ret: boolean = true;
  try {
    ret = display.hasPrivateWindow(displayClass.id);
  } catch (exception) {
    console.error('Failed to check has privateWindow or not. Code: ' + JSON.stringify(exception));
  }
  if (ret == undefined) {
    console.log("Failed to check has privateWindow or not.");
  }
  if (ret) {
    console.log("There has privateWindow.");
  } else if (!ret) {
    console.log("There has no privateWindow.");
  }
} catch (exception) {
  console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

display.on('privateModeChange')10+

on(type: 'privateModeChange', callback: Callback<boolean>): void

开启屏幕隐私模式变化的监听。当屏幕前台有隐私窗口，则屏幕处于隐私模式，屏幕中的隐私窗口内容无法被截屏或录屏。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.WindowManager.WindowManager.Core

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'privateModeChange'，表示屏幕隐私模式状态发生变化。
callback Callback<boolean> 是 回调函数。表示屏幕隐私模式是否改变。true表示屏幕由非隐私窗口模式变为隐私模式，false表示屏幕由隐私模式变为非隐私模式。

示例：

import { Callback } from '@ohos.base';

let callback: Callback<boolean> = (data: boolean) => {
  console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
try {
  display.on("privateModeChange", callback);
} catch (exception) {
  console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
}

display.off('privateModeChange')10+

off(type: 'privateModeChange', callback?: Callback<boolean>): void

关闭屏幕隐私模式变化的监听。当屏幕前台有隐私窗口，则屏幕处于隐私模式，屏幕中的隐私窗口内容无法被截屏或录屏。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.WindowManager.WindowManager.Core

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'privateModeChange'，表示屏幕隐私模式状态发生变化。
callback Callback<boolean> 否 回调函数。表示屏幕隐私模式是否改变。true表示屏幕由非隐私模式变为隐私模式，false表示屏幕由隐私模式变为非隐私模式。

示例：

try {
  display.off("privateModeChange");
} catch (exception) {
  console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
}

display.setFoldDisplayMode10+

setFoldDisplayMode(mode: FoldDisplayMode): void

更改可折叠设备的显示模式。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
mode FoldDisplayMode 是 可折叠设备的显示模式。

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400003 This display manager service works abnormally.

示例：

import display from '@ohos.display';

try {
  let mode: display.FoldDisplayMode = display.FoldDisplayMode.FOLD_DISPLAY_MODE_FULL;
  display.setFoldDisplayMode(mode);
} catch (exception) {
  console.error('Failed to change the fold display mode. Code: ' + JSON.stringify(exception));
}

display.setFoldStatusLocked11+

setFoldStatusLocked(locked: boolean): void

设置可折叠设备当前折叠状态的锁定状态。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
locked boolean 是 可折叠设备的折叠状态是否锁定。true表示锁定，false表示不锁定。

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400003 This display manager service works abnormally.

示例：

import display from '@ohos.display';

try {
  let locked: boolean = false;
  display.setFoldStatusLocked(locked);
} catch (exception) {
  console.error('Failed to change the fold status locked mode. Code: ' + JSON.stringify(exception));
}

Display

屏幕实例。描述display对象的属性和方法。

下列API示例中都需先使用getAllDisplays()、getDefaultDisplaySync()中的任一方法获取到Display实例，再通过此实例调用对应方法。

hasImmersiveWindow11+

hasImmersiveWindow(callback: AsyncCallback<boolean>): void

判断当前屏幕是否包含沉浸式窗口，使用callback异步回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。返回true表示当前屏幕包含沉浸式窗口，false表示不包含。

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400001 Invalid display or screen.
1400003 This display manager service works abnormally.

示例：

import { BusinessError } from '@ohos.base';
import display from '@ohos.display'

let displayClass: display.Display | null = null;
try {
  displayClass = display.getDefaultDisplaySync();
} catch (exception) {
  console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

try {
  displayClass.hasImmersiveWindow((err: BusinessError, data) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err));
      return;
    }
    console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data));
  });
} catch (exception) {
  console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(exception));
}

hasImmersiveWindow11+

hasImmersiveWindow(): Promise<boolean>

判断当前屏幕是否包含沉浸式窗口，使用Promise异步回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

返回值：

类型 说明
Promise<boolean> Promise对象。返回true表示当前屏幕包含沉浸式窗口，false表示不包含。

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400001 Invalid display or screen.
1400003 This display manager service works abnormally.

示例：

import { BusinessError } from '@ohos.base';
import display from '@ohos.display'

let displayClass: display.Display | null = null;
try {
  displayClass = display.getDefaultDisplaySync();
} catch (exception) {
  console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

let promise = displayClass.hasImmersiveWindow();
promise.then((data) => {
  console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err));
})

getAvailableArea11+

getAvailableArea(): Promise<Rect>

获取当前屏幕的可用区域，使用Promise异步回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

返回值：

类型 说明
Promise<Rect> Promise对象。返回当前屏幕可用矩形区域。

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400001 Invalid display or screen.

示例：

import { BusinessError } from '@ohos.base';
import display from '@ohos.display'

let displayClass: display.Display | null = null;
try {
  displayClass = display.getDefaultDisplaySync();
  let promise = displayClass.getAvailableArea();
  promise.then((data) => {
    console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error('Failed to get the available area in this display. Code: ' + JSON.stringify(err));
  })
} catch (exception) {
  console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
}

on('availableAreaChange')11+

on(type: 'availableAreaChange', callback: Callback<Rect>): void

开启当前屏幕的可用区域监听。当前屏幕有可用区域变化时，触发回调函数，返回可用区域。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'availableAreaChange'，表示屏幕可用区域变更。
callback Callback<Rect> 是 回调函数，返回改变后的可用区域。

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400003 This display manager service works abnormally.

示例：

import { Callback } from '@ohos.base';
import display from '@ohos.display'

let callback: Callback<display.Rect> = (data: display.Rect) => {
  console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
let displayClass: display.Display | null = null;
try {
  displayClass = display.getDefaultDisplaySync();
  displayClass.on("availableAreaChange", callback);
} catch (exception) {
  console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
}

off('availableAreaChange')11+

off(type: 'availableAreaChange', callback?: Callback<Rect>): void

关闭屏幕可用区域变化的监听。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Window.SessionManager

参数：

参数名 类型 必填 说明
type string 是 监听事件，固定为'availableAreaChange'，表示屏幕可用区域变更。
callback Callback<Rect> 否 回调函数，已经注册的回调函数，不填默认删除所有回调

错误码：

以下错误码的详细介绍请参见屏幕错误码。

错误码ID 错误信息
1400003 This display manager service works abnormally.

示例：

import { Callback } from '@ohos.base';
import display from '@ohos.display'

let callback: Callback<display.Rect> = (data: display.Rect) => {
  console.info('Listening enabled. Data: ' + JSON.stringify(data));
};
let displayClass: display.Display | null = null;
try {
  displayClass = display.getDefaultDisplaySync();
  displayClass.off("availableAreaChange", callback);
} catch (exception) {
  console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
}