@ohos.screen (屏幕)(系统接口)

本模块提供管理屏幕的一些基础能力，包括获取屏幕对象，监听屏幕变化，创建和销毁虚拟屏幕等。

说明：

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

本模块接口为系统接口。

针对系统能力SystemCapability.Window.SessionManager，请先使用canIUse()接口判断当前设备是否支持此syscap及对应接口。

导入模块

import { screen } from '@kit.ArkUI';

screen.getAllScreens

getAllScreens(callback: AsyncCallback<Array<Screen>>): void

获取所有的屏幕，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<Screen>>	是	回调函数。返回当前获取的屏幕对象集合。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let screenClass: screen.Screen | null = null;
screen.getAllScreens((err: BusinessError, data: Array<screen.Screen>) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to get all screens. Code:${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`Succeeded in getting all screens. Data: ${JSON.stringify(data)}`);
  if (data.length > 0) {
    screenClass = data[0];
  }
});

screen.getAllScreens

getAllScreens(): Promise<Array<Screen>>

获取所有的屏幕，使用Promise异步回调。

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

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

返回值：

类型	说明
Promise<Array<Screen>>	Promise对象。返回当前获取的屏幕对象集合。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let screenClass: screen.Screen | null = null;
let promise: Promise<Array<screen.Screen>> = screen.getAllScreens();
promise.then((data: Array<screen.Screen>) => {
  if(data.length > 0){
    screenClass = data[0];
  }
  console.info(`Succeeded in getting all screens. Data: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to get all screens. Code: ${err.code}, message : ${err.message}`);
});

screen.on('connect' | 'disconnect' | 'change')

on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void

开启屏幕状态变化的监听。

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

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

参数：

参数名	类型	必填	说明
eventType	string	是	监听事件。 -eventType为"connect"表示屏幕连接事件。 -eventType为"disconnect"表示断开屏幕连接事件。 -eventType为"change"表示屏幕状态改变事件。
callback	Callback<number>	是	回调函数。返回屏幕的id，该参数为整数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.

示例：

let callback: Callback<number> = (data: number) => {
  console.info(`Succeeded in registering the callback for screen changes. Data: ${data}`)
};
screen.on('connect', callback);

screen.off('connect' | 'disconnect' | 'change')

off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void

关闭屏幕状态变化的监听。

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

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

参数：

参数名	类型	必填	说明
eventType	string	是	监听事件。 -eventType为"connect"表示屏幕连接事件。 -eventType为"disconnect"表示断开屏幕连接事件。 -eventType为"change"表示屏幕状态改变事件。
callback	Callback<number>	否	回调函数。返回屏幕的id，该参数为整数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.

示例：

let callback: Callback<number> = (data: number) => {
  console.info(`Succeeded in unregistering the callback for screen changes. Data: ${data}`)
};
screen.off('connect', callback);
screen.off('connect');

screen.makeMirror

makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void

将屏幕设置为镜像模式，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
mainScreen	number	是	主屏幕ID，该参数仅支持整数输入。
mirrorScreen	Array<number>	是	镜像屏幕ID集合，其中ID应为整数。
callback	AsyncCallback<number>	是	回调函数。返回镜像屏幕的群组id，其中id为整数。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let mainScreenId: number = 0;
let mirrorScreenIds: Array<number> = [1, 2, 3];
screen.makeMirror(mainScreenId, mirrorScreenIds, (err: BusinessError, data: number) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to set screen mirroring. Code:${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`Succeeded in setting screen mirroring. Data: ${data}`);
});

screen.makeMirror

makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number>

将屏幕设置为镜像模式，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
mainScreen	number	是	主屏幕ID，该参数仅支持整数输入。
mirrorScreen	Array<number>	是	镜像屏幕ID集合。其中ID应为整数。

返回值：

类型	说明
Promise<number>	Promise对象。返回镜像屏幕的群组id，其中id为整数。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let mainScreenId: number = 0;
let mirrorScreenIds: Array<number> = [1, 2, 3];
screen.makeMirror(mainScreenId, mirrorScreenIds).then((data: number) => {
  console.info(`Succeeded in setting screen mirroring. Data: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to set screen mirroring. Code:${err.code}, message is ${err.message}`);
});

screen.stopMirror¹⁰⁺

stopMirror(mirrorScreen:Array<number>, callback: AsyncCallback<void>): void

停止屏幕的镜像模式，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
mirrorScreen	Array<number>	是	镜像屏幕ID集合，其中ID应为整数。 mirrorScreen数组大小不应超过1000。
callback	AsyncCallback<void>	是	回调函数。当停止屏幕镜像模式成功，err为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let mirrorScreenIds: Array<number> = [1, 2, 3];
screen.stopMirror(mirrorScreenIds, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to stop mirror screens. Code:${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in stopping mirror screens.');
});

screen.stopMirror¹⁰⁺

stopMirror(mirrorScreen:Array<number>): Promise<void>

停止屏幕的镜像模式，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
mirrorScreen	Array<number>	是	镜像屏幕ID集合，其中ID应为整数。mirrorScreen数组大小不应超过1000。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let mirrorScreenIds: Array<number> = [1, 2, 3];
screen.stopMirror(mirrorScreenIds).then(() => {
  console.info('Succeeded in stopping mirror screens.');
}).catch((err: BusinessError) => {
  console.error(`Failed to stop mirror screens.Code:${err.code}, message is ${err.message}`);
});

screen.makeUnique¹⁸⁺

makeUnique(uniqueScreen: Array<number>): Promise<Array<number>>

将屏幕设置为异源模式，使用Promise异步回调。

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

系统能力： SystemCapability.Window.SessionManager

设备行为差异： 该接口在Phone设备、PC/2in1设备、Tablet设备中可正常调用，在Wearable设备中报801错误码，在其他设备中不生效也不报错。

参数：

参数名	类型	必填	说明
uniqueScreen	Array<number>	是	异源屏幕ID集合。其中ID应为大于0的整数，否则返回401错误码。

返回值：

类型	说明
Promise<Array<number>>	Promise对象。返回异源屏幕的displayId集合，其中id为大于0的整数。

错误码：

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

错误码ID	错误信息
202	Permission verification failed, non-system application uses system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1400001	Invalid display or screen.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let uniqueScreenIds: Array<number> = [1001, 1002, 1003];
screen.makeUnique(uniqueScreenIds).then((data: Array<number>) => {
  console.info('Succeeded in making unique screens.');
}).catch((err: BusinessError) => {
  console.error(`Failed to make unique screens. Code:${err.code}, message is ${err.message}`);
});

screen.createVirtualScreen

createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void

创建虚拟屏幕，使用callback异步回调。

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

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

需要权限：ohos.permission.CAPTURE_SCREEN

参数：

参数名	类型	必填	说明
options	VirtualScreenOption	是	用于创建虚拟屏幕的参数。
callback	AsyncCallback<Screen>	是	回调函数，返回创建的虚拟屏幕对象。

错误码：

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

错误码ID	错误信息
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let screenClass: screen.Screen | null = null;
class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = { 
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};
screen.createVirtualScreen(option, (err: BusinessError, data: screen.Screen) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
    return;
  }
  screenClass = data;
  console.info(`Succeeded in creating the virtual screen. Data: ${JSON.stringify(data)}`);
});

screen.createVirtualScreen

createVirtualScreen(options:VirtualScreenOption): Promise<Screen>

创建虚拟屏幕，使用Promise异步回调。

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

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

需要权限：ohos.permission.CAPTURE_SCREEN

参数：

参数名	类型	必填	说明
options	VirtualScreenOption	是	用于创建虚拟屏幕的参数。

返回值：

类型	说明
Promise<Screen>	Promise对象。返回创建的虚拟屏幕对象。

错误码：

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

错误码ID	错误信息
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let screenClass: screen.Screen | null = null;
class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = { 
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};

screen.createVirtualScreen(option).then((data: screen.Screen) => {
  screenClass = data;
  console.info(`Succeeded in creating the virtual screen. Data: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
});

screen.destroyVirtualScreen

destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void

销毁虚拟屏幕，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
screenId	number	是	屏幕的id，该参数仅支持整数输入。
callback	AsyncCallback<void>	是	回调函数。当销毁虚拟屏幕成功，err为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.
1400002	Unauthorized operation.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let screenId: number = 1;
screen.destroyVirtualScreen(screenId, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to destroy the virtual screen. Code:${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in destroying the virtual screen.');
});

screen.destroyVirtualScreen

destroyVirtualScreen(screenId:number): Promise<void>

销毁虚拟屏幕，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
screenId	number	是	屏幕的id，该参数仅支持整数输入。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.
1400002	Unauthorized operation.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let screenId: number = 1;
screen.destroyVirtualScreen(screenId).then(() => {
  console.info('Succeeded in destroying the virtual screen.');
}).catch((err: BusinessError) => {
  console.error(`Failed to destroy the virtual screen.Code:${err.code}, message is ${err.message}`);
});

screen.setVirtualScreenSurface

setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void

设置虚拟屏幕的surface，表示当前虚拟屏用于显示对应surface中的内容，使用callback异步回调。

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

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

需要权限：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。

参数：

参数名	类型	必填	说明
screenId	number	是	屏幕的id，该参数仅支持整数输入。
surfaceId	string	是	代表虚拟屏幕的surface标识符，surfaceId值可自行定义，由用户指定某一实际存在的surface对应的surfaceId。
callback	AsyncCallback<void>	是	回调函数。当设置虚拟屏幕surface成功，err为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

// Index.ets
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  xComponentController: XComponentController = new XComponentController();

  setVirtualScreenSurface = () => {
    let screenId: number = 1;
    let surfaceId = this.xComponentController.getXComponentSurfaceId();
    screen.setVirtualScreenSurface(screenId, surfaceId, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set the surface for the virtual screen. Code:${err.code}, message is ${err.message}`);
      return;
    }
      console.info('Succeeded in setting the surface for the virtual screen.');
    });
  }
  build() {
    RelativeContainer() {
      XComponent({
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
      Button('setSurface')
        .onClick((event: ClickEvent) => {
          this.setVirtualScreenSurface();
      }).width('100%')
      .height(20)
    }
    .width('100%')
    .height('100%')
  }
}

screen.setVirtualScreenSurface

setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void>

设置虚拟屏幕的surface，表示当前虚拟屏用于显示对应surface中的内容，使用Promise异步回调。

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

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

需要权限：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。

参数：

参数名	类型	必填	说明
screenId	number	是	屏幕的id，该参数仅支持整数输入。
surfaceId	string	是	代表虚拟屏幕的surface标识符，surfaceId值可自行定义，由用户指定某一实际存在的surface对应的surfaceId。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
201	Permission verification failed. The application does not have the permission required to call the API.
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

// Index.ets
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  xComponentController: XComponentController = new XComponentController();

  setVirtualScreenSurface = () => {
    let screenId: number = 1;
    let surfaceId = this.xComponentController.getXComponentSurfaceId();
    screen.setVirtualScreenSurface(screenId, surfaceId).then(() => {
      console.info('Succeeded in setting the surface for the virtual screen.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to set the surface for the virtual screen. Code:${err.code}, message is ${err.message}`);
    });
  }
  build() {
    RelativeContainer() {
      XComponent({
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
      Button('setSurface')
        .onClick((event: ClickEvent) => {
          this.setVirtualScreenSurface();
      }).width('100%')
      .height(20)
    }
    .width('100%')
    .height('100%')
  }
}

screen.setScreenPrivacyMaskImage¹⁹⁺

setScreenPrivacyMaskImage(screenId:number, image?: image.PixelMap): Promise<void>

设置屏幕的隐私蒙版图片，使用Promise异步回调。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名	类型	必填	说明
screenId	number	是	屏幕的id，该参数仅支持正整数输入。
image	image.PixelMap	否	屏幕的隐私蒙版图片，不传入则使用默认隐私蒙版图片。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
801	Capability not supported. Failed to call the API due to limited device capabilities.
1400001	Invalid display or screen.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';

const color: ArrayBuffer = new ArrayBuffer(96); // 96为需要创建的像素buffer大小，取值为：height * width *4
let opts: image.InitializationOptions = { editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 4, width: 6 } }
image.createPixelMap(color, opts).then((pixelMap: image.PixelMap) => {
  console.info('Succeeded in creating pixelmap.');
  let screenId: number = 1;
  screen.setScreenPrivacyMaskImage(screenId, pixelMap).then(() => {
    console.info('Succeeded in setting the privacy mask image for the screen.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set the privacy mask image for the screen. Code:${err.code}, message is ${err.message}`);
  });
}).catch((error: BusinessError) => {
  console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`);
})

screen.isScreenRotationLocked

isScreenRotationLocked(): Promise<boolean>

查询当前自动转屏是否锁定，使用Promise异步回调。

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

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

返回值：

类型	说明
Promise<boolean>	Promise对象。返回true表示当前自动转屏处于锁定状态；返回false表示当前自动转屏不处于锁定状态。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

screen.isScreenRotationLocked().then((isLocked: boolean) => {
  console.info(`Succeeded in getting the screen rotation lock status. isLocked: ${isLocked}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to get the screen rotation lock status. Code:${err.code}, message is ${err.message}`);
});

screen.isScreenRotationLocked

isScreenRotationLocked(callback: AsyncCallback<boolean>): void

查询当前自动转屏是否锁定，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
callback	AsyncCallback<boolean>	是	回调函数。返回true表示当前自动转屏处于锁定状态；返回false表示当前自动转屏不处于锁定状态。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

screen.isScreenRotationLocked((err: BusinessError, isLocked: boolean) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to get the screen rotation lock status. Code:${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`Succeeded in getting the screen rotation lock status. isLocked: ${isLocked}`);
});

screen.setScreenRotationLocked

setScreenRotationLocked(isLocked: boolean): Promise<void>

设置自动转屏开关是否锁定，使用Promise异步回调。

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

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

设备行为差异： 仅在支持跟随sensor旋转的设备中生效，其他设备调用不生效不报错。

参数：

参数名	类型	必填	说明
isLocked	boolean	是	自动转屏开关是否锁定。true为锁定，false为未锁定。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let isLocked: boolean = false;
screen.setScreenRotationLocked(isLocked).then(() => {
  console.info('Succeeded in unlocking auto rotate');
}).catch((err: BusinessError) => {
  console.error(`Failed to unlock auto rotate. Code:${err.code}, message is ${err.message}`);
});

screen.setScreenRotationLocked

setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void

设置自动转屏开关是否锁定，使用callback异步回调。

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

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

设备行为差异： 仅在支持跟随sensor旋转的设备中生效，其他设备调用不生效不报错。

参数：

参数名	类型	必填	说明
isLocked	boolean	是	自动转屏开关是否锁定。true为锁定，false为未锁定。
callback	AsyncCallback<void>	是	回调函数。当设置自动转屏是否锁定成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let isLocked: boolean = false;
screen.setScreenRotationLocked(isLocked, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to unlock auto rotate. Code:${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in unlocking auto rotate.');
});

screen.setMultiScreenMode¹³⁺

setMultiScreenMode(primaryScreenId: number, secondaryScreenId: number, secondaryScreenMode: MultiScreenMode): Promise<void>

设置扩展屏幕的显示模式（镜像/扩展），使用Promise异步回调。primaryScreenId和secondaryScreenId均为0时，仅在扩展屏显示。

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

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

参数：

参数名	类型	必填	说明
primaryScreenId	number	是	主屏的id，该参数应为非负整数。如果输入的数字包含小数部分，向下取整。
secondaryScreenId	number	是	扩展屏幕的id，该参数应为非负整数。如果输入的数字包含小数部分，向下取整。
secondaryScreenMode	MultiScreenMode	是	扩展屏幕的显示模式。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed, non-system application uses system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let primaryScreenId: number = 0;
let secondaryScreenId: number = 12;
let screenMode: screen.MultiScreenMode = screen.MultiScreenMode.SCREEN_MIRROR;
screen.setMultiScreenMode(primaryScreenId, secondaryScreenId, screenMode).then(() => {
  console.info('Succeeded in setting multi screen mode. Data: ');
}).catch((err: BusinessError) => {
  console.error(`Failed to set multi screen mode. Code:${err.code}, message is ${err.message}`);
});

screen.setMultiScreenRelativePosition¹³⁺

setMultiScreenRelativePosition(mainScreenOptions: MultiScreenPositionOptions, secondaryScreenOptions: MultiScreenPositionOptions): Promise<void>

仅在扩展模式下，设置主屏和扩展屏幕的位置信息，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
mainScreenOptions	MultiScreenPositionOptions	是	主屏的位置信息。
secondaryScreenOptions	MultiScreenPositionOptions	是	扩展屏幕的位置信息。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed, non-system application uses system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let mainScreenOptions: screen.MultiScreenPositionOptions = {
  id : 0,
  startX : 0,
  startY : 0
};

let secondaryScreenOptions: screen.MultiScreenPositionOptions = {
  id : 12,
  startX : 1000,
  startY : 1000
};

screen.setMultiScreenRelativePosition(mainScreenOptions, secondaryScreenOptions).then(() => {
  console.info('Succeeded in setting multi screen relative position.');
}).catch((err: BusinessError) => {
  console.error(`Failed to set multi screen relative position. Code:${err.code}, message is ${err.message}`);
});

screen.resizeVirtualScreen²⁴⁺

resizeVirtualScreen(screenId: number, width: number, height: number): Promise<void>

修改指定虚拟屏的尺寸，使用Promise异步回调。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名	类型	必填	说明
screenId	number	是	要修改的虚拟屏的屏幕ID，取值范围为[1000, 2147483647]的正整数，超出有效范围时返回错误码1400004。
width	number	是	虚拟屏的新宽度，单位为px，取值范围为[1, 65536]的正整数，超出有效范围时返回错误码1400004。
height	number	是	虚拟屏的新高度，单位为px，取值范围为[1, 65536]的正整数，超出有效范围时返回错误码1400004。

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
801	Capability not supported. Function can not work because the current device does not support this ability.
1400001	Invalid display or screen.
1400003	This display manager service works abnormally.
1400004	Parameter error. Possible cause: 1. Invalid parameter range.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let screenId: number = 1000;
let width: number = 1920;
let height: number = 1080;
screen.resizeVirtualScreen(screenId, width, height).then(() => {
  console.info(`Succeeded in resizing virtual screen: screenId=${screenId}, width=${width}, height=${height}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to set screen area mirroring. Code:${err.code}, message is ${err.message}`);
});

screen.makeMirrorWithRegion¹⁹⁺

makeMirrorWithRegion(mainScreen:number, mirrorScreen:Array<number>, mainScreenRegion:Rect): Promise<number>

将屏幕的某一矩形区域设置为镜像模式，使用Promise异步回调。调用该接口后，不建议再进行屏幕的旋转/折叠，否则可能导致镜像内容异常。

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

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

参数：

参数名	类型	必填	说明
mainScreen	number	是	主屏幕ID，该参数仅支持正整数输入。
mirrorScreen	Array<number>	是	镜像屏幕ID集合。其中ID应为正整数。
mainScreenRegion	Rect	是	主屏创建镜像的矩形区域。

返回值：

类型	说明
Promise<number>	Promise对象。返回镜像屏幕的群组id，其中id为正整数。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let mainScreenId: number = 0;
let mirrorScreenIds: Array<number> = [1, 2, 3];
let mainScreenRegion: screen.Rect = {
  left : 0,
  top : 0,
  width : 1920,
  height : 1080
};
screen.makeMirrorWithRegion(mainScreenId, mirrorScreenIds, mainScreenRegion).then((data: number) => {
  console.info(`Succeeded in setting screen mirroring. Data: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to set screen area mirroring. Code:${err.code}, message is ${err.message}`);
});

screen.makeExpand^(deprecated)

makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void

将屏幕设置为扩展模式，使用callback异步回调。

说明：

从API version 9开始支持，从API version 20开始废弃。

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

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

参数：

参数名	类型	必填	说明
options	Array<ExpandOption>	是	设置扩展屏幕的参数集合。
callback	AsyncCallback<number>	是	回调函数。返回扩展屏幕的群组id，其中id为整数。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let groupId: number | null = null;
class ExpandOption {
  screenId: number = 0;
  startX: number = 0;
  startY: number = 0;
}
let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 };
let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 };
let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ];
screen.makeExpand(expandOptionArray, (err: BusinessError, data: number) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to expand the screen. Code:${err.code}, message is ${err.message}`);
    return;
  }
  groupId = data;
  console.info(`Succeeded in expanding the screen. Data: ${data}`);
});

screen.makeExpand^(deprecated)

makeExpand(options:Array<ExpandOption>): Promise<number>

将屏幕设置为扩展模式，使用Promise异步回调。

说明：

从API version 9开始支持，从API version 20开始废弃。

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

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

参数：

参数名	类型	必填	说明
options	Array<ExpandOption>	是	设置扩展屏幕的参数集合。

返回值：

类型	说明
Promise<number>	Promise对象。返回扩展屏幕的群组id，其中id为整数。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

class ExpandOption {
  screenId: number = 0;
  startX: number = 0;
  startY: number = 0;
}
let mainScreenOption: ExpandOption = { screenId: 0, startX: 0, startY: 0 };
let otherScreenOption: ExpandOption = { screenId: 1, startX: 1080, startY: 0 };
let expandOptionArray : ExpandOption[] = [ mainScreenOption, otherScreenOption ];
screen.makeExpand(expandOptionArray).then((
  data: number) => {
  console.info(`Succeeded in expanding the screen. Data: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to expand the screen. Code:${err.code}, message is ${err.message}`);
});

screen.stopExpand^(deprecated)

stopExpand(expandScreen:Array<number>, callback: AsyncCallback<void>): void

停止屏幕的扩展模式，使用callback异步回调。

说明：

从API version 10开始支持，从API version 20开始废弃。

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

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

参数：

参数名	类型	必填	说明
expandScreen	Array<number>	是	扩展屏幕ID集合，其中ID为整数。 expandScreen数组大小不应超过1000。
callback	AsyncCallback<void>	是	回调函数。当停止屏幕扩展模式成功，err为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let expandScreenIds: Array<number> = [1, 2, 3];
screen.stopExpand(expandScreenIds, (err: BusinessError) => {
  const errCode: number = err.code;
  if (errCode) {
    console.error(`Failed to stop expand screens. Code:${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in stopping expand screens.');
});

screen.stopExpand^(deprecated)

stopExpand(expandScreen:Array<number>): Promise<void>

停止屏幕的扩展模式，使用Promise异步回调。

说明：

从API version 10开始支持，从API version 20开始废弃。

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

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

参数：

参数名	类型	必填	说明
expandScreen	Array<number>	是	扩展屏幕ID集合，其中ID为整数。expandScreen数组大小不应超过1000。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
1400001	Invalid display or screen.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let expandScreenIds: Array<number> = [1, 2, 3];
screen.stopExpand(expandScreenIds).then(() => {
  console.info('Succeeded in stopping expand screens.');
}).catch((err: BusinessError) => {
  console.error(`Failed to stop expand screens. Code:${err.code}, message is ${err.message}`);
});

ExpandOption

扩展屏幕的参数。

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

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

名称	类型	只读	可选	说明
screenId	number	否	否	屏幕的id，该参数应为整数。
startX	number	否	否	屏幕的起始X轴坐标，该参数应为整数。
startY	number	否	否	屏幕的起始Y轴坐标，该参数应为整数。

MultiScreenMode¹³⁺

屏幕模式枚举。

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

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

名称	值	说明
SCREEN_MIRROR	0	表示屏幕为镜像模式。
SCREEN_EXTEND	1	表示屏幕为扩展模式。

MultiScreenPositionOptions¹³⁺

屏幕位置信息。

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

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

名称	类型	只读	可选	说明
id	number	否	否	屏幕的ID，该参数应为正整数，非正整数会作为非法参数报错。
startX	number	否	否	屏幕的起始X轴坐标。以两块屏幕外接矩形的左上顶点为原点，向右为正方向。该参数应为正整数，非正整数会作为非法参数报错。
startY	number	否	否	屏幕的起始Y轴坐标。以两块屏幕外接矩形的左上顶点为原点，向下为正方向。该参数应为正整数，非正整数会作为非法参数报错。

VirtualScreenOption

创建虚拟屏幕的参数。

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

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

名称	类型	只读	可选	说明
name	string	否	否	指定虚拟屏幕的名称。
width	number	否	否	指定虚拟屏幕的宽度，单位为px，该参数应为整数。
height	number	否	否	指定虚拟屏幕的高度，单位为px，该参数应为整数。
density	number	否	否	指定虚拟屏幕的密度，该参数为浮点数。
surfaceId	string	否	否	指定虚拟屏幕的surfaceId。
supportsFocus²²⁺	boolean	否	是	指定虚拟屏幕是否可获得焦点。true表示可获焦，false表示不可获焦，默认值为true。
userId²⁴⁺	number	否	是	指定虚拟屏幕的用户ID，该参数为整数。默认值为-1。

Screen

物理屏屏幕实例。

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

属性

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

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

名称	类型	只读	可选	说明
id	number	是	否	屏幕的ID，该参数为整数。
rsId²¹⁺	number	是	否	屏幕端口的id，该参数为整数。
parent	number	是	否	屏幕所属群组的id，该参数为整数。
supportedModeInfo	Array<ScreenModeInfo>	是	否	屏幕支持的模式集合。
activeModeIndex	number	是	否	当前屏幕所处模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化。该参数为整数。
orientation	Orientation	是	否	屏幕方向。
sourceMode¹⁰⁺	ScreenSourceMode	是	否	屏幕来源模式。
serialNumber¹⁵⁺	string	是	是	扩展屏幕的序列号，默认返回为空字符串。
densityDpi	number	是	是	屏幕的物理像素密度，即每英寸的像素数。起始版本： 26.0.0 模型约束：此接口仅可在Stage模型下使用。

setOrientation

setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void

设置屏幕方向，使用callback异步回调。当设置的方向符合应用旋转策略（可通过配置module.json5文件中abilities标签的orientation字段设置应用旋转策略）时，屏幕方向才会发生改变；当设置方向不符合应用旋转策略时，屏幕方向不会发生变化，且接口不会抛异常。

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

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

参数：

参数名	类型	必填	说明
orientation	Orientation	是	屏幕方向。orientation值必须来自Orientation枚举方向。
callback	AsyncCallback<void>	是	回调函数。当设置屏幕方向成功，err为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = {
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};

screen.createVirtualScreen(option).then((data: screen.Screen) => {
  let screenClass: screen.Screen = data;
  console.info(`Succeeded in creating the virtual screen. Data: ${JSON.stringify(data)}`);
  screenClass.setOrientation(screen.Orientation.VERTICAL, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set the vertical orientation. Code:${err.code}, message is ${err.message}`);
      return;
    }
    console.info('Succeeded in setting the vertical orientation.');
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
});

setOrientation

setOrientation(orientation: Orientation): Promise<void>

设置屏幕方向，使用Promise异步回调。当设置的方向符合应用旋转策略（可通过配置module.json5文件中abilities标签的orientation字段设置应用旋转策略）时，屏幕方向才会发生改变；当设置方向不符合应用旋转策略时，屏幕方向不会发生变化，且接口不会抛异常。

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

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

参数：

参数名	类型	必填	说明
orientation	Orientation	是	屏幕方向。orientation值必须来自Orientation枚举方向。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = {
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};

screen.createVirtualScreen(option).then((data: screen.Screen) => {
  let screenClass: screen.Screen = data;
  console.info(`Succeeded in creating the virtual screen. Data: ${JSON.stringify(data)}`);
  let promise: Promise<void> = screenClass.setOrientation(screen.Orientation.VERTICAL);
  promise.then(() => {
    console.info('Succeeded in setting the vertical orientation.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set the vertical orientation. Code:${err.code}, message is ${err.message}`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
});

setOrientation

setOrientation(orientation: Orientation, orientationOptions?: OrientationOptions): Promise<void>

设置屏幕方向，使用Promise异步回调。

可通过orientationOptions参数指定旋转时是否带有动画、是否忽略系统窗口的旋转锁定。

当设置的方向符合应用旋转策略（可通过配置module.json5文件中abilities标签的orientation字段设置应用旋转策略）时，屏幕方向才会发生改变；当设置方向不符合应用旋转策略时，屏幕方向不会发生变化，且接口不会抛出异常。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

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

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

参数：

参数名	类型	必填	说明
orientation	Orientation	是	屏幕方向。
orientationOptions	OrientationOptions	否	设置屏幕旋转时的可选参数。默认带动画旋转屏幕，不忽略旋转锁定。

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let orientationOptions : screen.OrientationOptions = {
  needAnimation: true,
  ignoreRotationLock: false,
};

let screenClass: screen.Screen | null = null;
let screensPromise: Promise<Array<screen.Screen>> = screen.getAllScreens();
screensPromise.then((data: Array<screen.Screen>) => {
  if (data.length > 0) {
    screenClass = data[0];
    let promise: Promise<void> = screenClass.setOrientation(screen.Orientation.VERTICAL, orientationOptions);
    promise.then(() => {
      console.info('Succeeded in setting the vertical orientation with orientationOptions.');
    }).catch((err: BusinessError) => {
      console.error(`Failed to set the vertical orientation with orientationOptions. Code:${err.code}, message is ${err.message}`);
    });
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to get all screens. Code:${err.code}, message is ${err.message}`);
});

setScreenActiveMode

setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void

设置屏幕当前显示模式，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
modeIndex	number	是	模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化，该参数仅支持整数输入。索引为screen中ScreenModeInfo属性的模式id。
callback	AsyncCallback<void>	是	回调函数。当设置屏幕当前显示模式成功，err为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = {
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};

screen.createVirtualScreen(option).then((data: screen.Screen) => {
  let screenClass: screen.Screen = data;
  console.info(`Succeeded in creating the virtual screen. Data: ${JSON.stringify(data)}`);
  let modeIndex: number = 0;
  screenClass.setScreenActiveMode(modeIndex, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set screen active mode 0. Code:${err.code}, message is ${err.message}`);
      return;
    }
    console.info('Succeeded in setting the screen active mode 0.');
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
});

setScreenActiveMode

setScreenActiveMode(modeIndex: number): Promise<void>

设置屏幕当前显示模式，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
modeIndex	number	是	模式索引。模式索引的当前值和值的范围，会根据屏幕当前分辨率、刷新率和设备硬件差异产生变化，该参数仅支持整数输入。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = {
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};

screen.createVirtualScreen(option).then((data: screen.Screen) => {
  let screenClass: screen.Screen = data;
  console.info(`Succeeded in creating the virtual screen. Data: ${JSON.stringify(data)}`);
  let modeIndex: number = 0;
  let promise: Promise<void> = screenClass.setScreenActiveMode(modeIndex);
  promise.then(() => {
    console.info('Succeeded in setting screen active mode 0.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set screen active mode 0.Code:${err.code}, message is ${err.message}`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
});

setDensityDpi

setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void;

设置屏幕的像素密度，使用callback异步回调。

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

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

参数：

参数名	类型	必填	说明
densityDpi	number	是	像素密度。支持的输入范围为[80, 640]，该参数仅支持整数输入。
callback	AsyncCallback<void>	是	回调函数。当设置屏幕的像素密度成功，err为undefined，否则为错误对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let densityDpi: number = 320;
class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = {
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};

screen.createVirtualScreen(option).then((data: screen.Screen) => {
  let screenClass: screen.Screen = data;
  console.info(`Succeeded in creating the virtual screen. Data: ${JSON.stringify(data)}`);
  screenClass.setDensityDpi(densityDpi, (err: BusinessError) => {
    const errCode: number = err.code;
    if (errCode) {
      console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code}, message is ${err.message}`);
      return;
    }
    console.info('Succeeded in setting the density dpi.');
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
});

setDensityDpi

setDensityDpi(densityDpi: number): Promise<void>

设置屏幕的像素密度，使用Promise异步回调。

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

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

参数：

参数名	类型	必填	说明
densityDpi	number	是	像素密度。支持的输入范围为[80, 640]，该参数仅支持整数输入。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

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

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
1400003	This display manager service works abnormally.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let densityDpi: number = 320;
class VirtualScreenOption {
  name : string = '';
  width : number =  0;
  height : number = 0;
  density : number = 0;
  surfaceId : string = '';
  supportsFocus ?: boolean = true;
}

let option : VirtualScreenOption = {
  name: 'screen01',
  width: 1080,
  height: 2340,
  density: 2,
  surfaceId: '',
  supportsFocus: false
};

screen.createVirtualScreen(option).then((data: screen.Screen) => {
  let screenClass: screen.Screen = data;
  let promise: Promise<void> = screenClass.setDensityDpi(densityDpi);
  promise.then(() => {
    console.info('Succeeded in setting the pixel density of the screen to 320.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to set the pixel density of the screen to 320. Code:${err.code}, message is ${err.message}`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to create the virtual screen. Code:${err.code}, message is ${err.message}`);
});

Orientation

屏幕方向枚举。

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

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

名称	值	说明
UNSPECIFIED	0	表示未指定屏幕方向，由系统指定。
VERTICAL	1	表示指定屏幕为垂直方向。
HORIZONTAL	2	表示指定屏幕为水平方向。
REVERSE_VERTICAL	3	表示指定屏幕为反向垂直方向。
REVERSE_HORIZONTAL	4	表示指定屏幕为反向水平方向。

ScreenSourceMode¹⁰⁺

屏幕显示内容来源模式枚举。

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

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

名称	值	说明
SCREEN_MAIN	0	表示屏幕为默认主屏。
SCREEN_MIRROR	1	表示屏幕内容来自镜像。
SCREEN_EXTEND	2	表示屏幕内容来自扩展。
SCREEN_ALONE	3	表示屏幕为未指定来源。

ScreenModeInfo

屏幕显示模式信息。

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

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

名称	类型	只读	可选	说明
id	number	否	否	模式ID，所支持的模式由具体设备分辨率和刷新率决定，该参数为整数。
width	number	否	否	屏幕的宽度，单位为px，该参数为整数。
height	number	否	否	屏幕的高度，单位为px，该参数为整数。
refreshRate	number	否	否	屏幕的刷新率，单位为hz，该参数为整数。

Rect¹⁹⁺

矩形信息。

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

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

名称	类型	只读	可选	说明
left	number	否	否	矩形左上角顶点的X轴坐标，单位为px，该参数应为整数。
top	number	否	否	矩形左上角顶点的Y轴坐标，单位为px，该参数应为整数。
width	number	否	否	矩形的宽度，单位为px，该参数应为整数。
height	number	否	否	矩形的高度，单位为px，该参数应为整数。

OrientationOptions

设置屏幕方向的可选参数。

起始版本： 26.0.0

模型约束： 此字段仅可在Stage模型下使用。

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

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

名称	类型	只读	可选	说明
needAnimation	boolean	否	是	是否带动画旋转。true表示带动画旋转屏幕，false表示不带动画旋转屏幕。默认值为true。
ignoreRotationLock	boolean	否	是	是否忽略旋转锁定。true表示即使某些系统窗口锁定屏幕旋转，也允许屏幕旋转；false表示当系统窗口锁定屏幕旋转时，不允许屏幕旋转。默认值为false。设备行为差异：该字段仅在PC/2in1设备（非折叠PC）和其他设备的电脑模式下生效，在其他设备中调用不生效不报错。

@ohos.screen (屏幕)(系统接口)

导入模块

screen.getAllScreens

screen.getAllScreens

screen.on('connect' | 'disconnect' | 'change')

screen.off('connect' | 'disconnect' | 'change')

screen.makeMirror

screen.makeMirror

screen.stopMirror10+

screen.stopMirror10+

screen.makeUnique18+

screen.createVirtualScreen

screen.createVirtualScreen

screen.destroyVirtualScreen

screen.destroyVirtualScreen

screen.setVirtualScreenSurface

screen.setVirtualScreenSurface

screen.setScreenPrivacyMaskImage19+

screen.isScreenRotationLocked

screen.isScreenRotationLocked

screen.setScreenRotationLocked

screen.setScreenRotationLocked

screen.setMultiScreenMode13+

screen.setMultiScreenRelativePosition13+

screen.resizeVirtualScreen24+

screen.makeMirrorWithRegion19+

screen.makeExpand(deprecated)

screen.makeExpand(deprecated)

screen.stopExpand(deprecated)

screen.stopExpand(deprecated)

ExpandOption

MultiScreenMode13+

MultiScreenPositionOptions13+

VirtualScreenOption

Screen

属性

setOrientation

setOrientation

setOrientation

setScreenActiveMode

setScreenActiveMode

setDensityDpi

setDensityDpi

Orientation

ScreenSourceMode10+

ScreenModeInfo

Rect19+

OrientationOptions

screen.stopMirror¹⁰⁺

screen.stopMirror¹⁰⁺

screen.makeUnique¹⁸⁺

screen.setScreenPrivacyMaskImage¹⁹⁺

screen.setMultiScreenMode¹³⁺

screen.setMultiScreenRelativePosition¹³⁺

screen.resizeVirtualScreen²⁴⁺

screen.makeMirrorWithRegion¹⁹⁺

screen.makeExpand^(deprecated)

screen.makeExpand^(deprecated)

screen.stopExpand^(deprecated)

screen.stopExpand^(deprecated)

MultiScreenMode¹³⁺

MultiScreenPositionOptions¹³⁺

ScreenSourceMode¹⁰⁺

Rect¹⁹⁺