diff --git a/zh-cn/application-dev/reference/apis/js-apis-screen.md b/zh-cn/application-dev/reference/apis/js-apis-screen.md index 9472f9f6d445586231e7bbb44ec1c87b1cc1dc52..42475c74b7761fd32f73468efa545a209f15d63d 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-screen.md +++ b/zh-cn/application-dev/reference/apis/js-apis-screen.md @@ -1,4 +1,5 @@ # 屏幕 + 本模块提供管理屏幕的一些基础能力，包括获取屏幕对象，监听屏幕变化，创建和销毁虚拟屏幕等。 > **说明：** @@ -6,6 +7,7 @@ > 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > > 本模块接口为系统接口。 + ## 导入模块 ```js @@ -39,6 +41,7 @@ screen.getAllScreens((err, data) => { screenClass = data[0]; }); ``` + ## screen.getAllScreens getAllScreens(): Promise<Array<Screen>> @@ -48,11 +51,13 @@ getAllScreens(): Promise<Array<Screen>> **系统能力：** SystemCapability.WindowManager.WindowManager.Core **返回值：** + | 类型 | 说明 | | --------------------------------------------- | ----------------------------------------- | | Promise<Array<[Screen](#screen)>> | Promise对象。返回当前获取的屏幕对象集合。 | **示例：** + ```js var screenClass = null; let promise = screen.getAllScreens(); @@ -63,7 +68,9 @@ promise.then((data) => { console.log('Failed to get all screens . Cause: ' + JSON.stringify(err)); }); ``` + ## screen.on('connect' | 'disconnect' | 'change') + on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number>): void 开启屏幕状态变化的监听。 @@ -71,19 +78,23 @@ on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback<number& **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** + | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------- | ---- | ------------------------------------------------------------ | | eventType | string | 是 | 监听事件。
-eventType为"connect"表示屏幕连接事件。
-eventType为"disconnect"表示断开屏幕连接事件。
-eventType为"change"表示屏幕状态改变事件。 | | callback | Callback<number> | 是 | 回调函数。返回屏幕的id。 | **示例：** + ```js var callback = (data) => { console.info('Register the callback for screen changes. Data: ' + JSON.stringify(data)) }; screen.on("connect", callback); ``` + ## screen.off('connect' | 'disconnect' | 'change') + off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<number>): void 关闭屏幕状态变化的监听。 @@ -91,12 +102,14 @@ off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback<numbe **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** + | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------- | ---- | ------------------------------------------------------------ | | eventType | string | 是 | 监听事件。
-eventType为"connect"表示屏幕连接事件。
-eventType为"disconnect"表示断开屏幕连接事件。
-eventType为"change"表示屏幕状态改变事件。 | | callback | Callback<number> | 否 | 回调函数。返回屏幕的id。 | **示例：** + ```js var callback = (data) => { console.info('Unegister the callback for screen changes. Data: ' + JSON.stringify(data)) @@ -105,6 +118,7 @@ screen.off("connect", callback); ``` ## screen.makeExpand + makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number>): void 将屏幕设置为扩展模式，使用callback异步回调。 @@ -112,6 +126,7 @@ makeExpand(options:Array<ExpandOption>, callback: AsyncCallback<number& **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** + | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------ | ---- | -------------------------------- | | options | Array<[ExpandOption](#expandoption)> | 是 | 设置扩展屏幕的参数集合。 | @@ -132,6 +147,7 @@ screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 10 ``` ## screen.makeExpand + makeExpand(options:Array<ExpandOption>): Promise<number> 将屏幕设置为扩展模式，使用Promise异步回调。 @@ -145,11 +161,13 @@ makeExpand(options:Array<ExpandOption>): Promise<number> | options | Array<[ExpandOption](#expandoption)> | 是 | 设置扩展屏幕的参数集合。 | **返回值：** + | 类型 | 说明 | | --------------------- | ----------------------------------- | | Promise<number> | Promise对象。返回扩展屏幕的群组id。 | **示例：** + ```js screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 1080, startY: 0}]).then((data) => { console.info('Succeeded in making screens as expand-screen.Data:' + JSON.stringify(data)); @@ -159,6 +177,7 @@ screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 10 ``` ## screen.makeMirror + makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncCallback<number>): void 将屏幕设置为镜像模式，使用callback异步回调。 @@ -174,6 +193,7 @@ makeMirror(mainScreen:number, mirrorScreen:Array<number>, callback: AsyncC | callback | AsyncCallback<number> | 是 | 回调函数。返回镜像屏幕的群组id。 | **示例：** + ```js var mainScreenId = 0; var mirrorScreenIds = [1, 2, 3]; @@ -187,6 +207,7 @@ screen.makeMirror(mainScreenId, mirrorScreenIds, (err, data) => { ``` ## screen.makeMirror + makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<number> 将屏幕设置为镜像模式，使用Promise异步回调。 @@ -201,11 +222,13 @@ makeMirror(mainScreen:number, mirrorScreen:Array<number>): Promise<numb | mirrorScreen | Array<number> | 是 | 镜像屏幕id集合。 | **返回值：** + | 类型 | 说明 | | --------------------- | ----------------------------------- | | Promise<number> | Promise对象。返回镜像屏幕的群组id。 | **示例：** + ```js var mainScreenId = 0; var mirrorScreenIds = [1, 2, 3]; @@ -217,6 +240,7 @@ screen.makeMirror(mainScreenId, mirrorScreenIds).then((data) => { ``` ## screen.createVirtualScreen + createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Screen>): void 创建虚拟屏幕，使用callback异步回调。 @@ -233,6 +257,7 @@ createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback<Scre | callback | AsyncCallback<[Screen](#screen)> | 是 | 回调函数，返回创建的虚拟屏幕对象。 | **示例：** + ```js var screenClass = null; screen.createVirtualScreen({ @@ -252,6 +277,7 @@ screen.createVirtualScreen({ ``` ## screen.createVirtualScreen + createVirtualScreen(options:VirtualScreenOption): Promise<Screen> 创建虚拟屏幕，使用Promise异步回调。 @@ -261,6 +287,7 @@ createVirtualScreen(options:VirtualScreenOption): Promise<Screen> **需要权限**：ohos.permission.CAPTURE_SCREEN，如果VirtualScreenOption.surfaceId有效，此权限是必需的。仅系统应用可用。 **参数：** + | 参数名 | 类型 | 必填 | 说明 | | ------- | ------------------------------------------- | ---- | ------------------------ | | options | [VirtualScreenOption](#virtualscreenoption) | 是 | 用于创建虚拟屏幕的参数。 | @@ -272,6 +299,7 @@ createVirtualScreen(options:VirtualScreenOption): Promise<Screen> | Promise<[Screen](#screen)> | Promise对象。返回创建的虚拟屏幕对象。 | **示例：** + ```js var screenClass = null; screen.createVirtualScreen({ @@ -289,6 +317,7 @@ screen.createVirtualScreen({ ``` ## screen.destroyVirtualScreen + destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void 销毁虚拟屏幕，使用callback异步回调。 @@ -296,12 +325,14 @@ destroyVirtualScreen(screenId:number, callback: AsyncCallback<void>): void **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** + | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ------------------------------------------------------------ | | screenId | number | 是 | 屏幕的id。 | | callback | AsyncCallback<void> | 是 | 回调函数。当销毁虚拟屏幕成功，err为undefined，否则为错误对象。 | **示例：** + ```js var screenId = 1; screen.destroyVirtualScreen(screenId, (err,data) => { @@ -314,6 +345,7 @@ screen.destroyVirtualScreen(screenId, (err,data) => { ``` ## screen.destroyVirtualScreen + destroyVirtualScreen(screenId:number): Promise<void> 销毁虚拟屏幕，使用Promise异步回调。 @@ -321,16 +353,19 @@ destroyVirtualScreen(screenId:number): Promise<void> **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** + | 参数名 | 类型 | 必填 | 说明 | | -------- | ------ | ---- | ---------- | | screenId | number | 是 | 屏幕的id。 | **返回值：** + | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **示例：** + ```js var screenId = 1; screen.destroyVirtualScreen(screenId).then((data) => { @@ -341,6 +376,7 @@ screen.destroyVirtualScreen(screenId).then((data) => { ``` ## screen.setVirtualScreenSurface + setVirtualScreenSurface(screenId:number, surfaceId: string, callback: AsyncCallback<void>): void 设置虚拟屏幕的surface，使用callback异步回调。 @@ -372,6 +408,7 @@ screen.setVirtualScreenSurface(screenId, surfaceId, (err,data) => { ``` ## screen.setVirtualScreenSurface + setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> 设置虚拟屏幕的surface，使用Promise异步回调。 @@ -381,17 +418,20 @@ setVirtualScreenSurface(screenId:number, surfaceId: string): Promise<void> **需要权限**：ohos.permission.CAPTURE_SCREEN，仅系统应用可用。 **参数：** + | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ------------- | | screenId | number | 是 | 屏幕的id。 | | surfaceId | string | 是 | surface的id。 | **返回值：** + | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **示例：** + ```js var screenId = 1; var surfaceId = '2048'; @@ -403,6 +443,7 @@ screen.setVirtualScreenSurface(screenId, surfaceId).then((data) => { ``` ## screen.isScreenRotationLocked + isScreenRotationLocked(): Promise<boolean> 查询当前自动转屏是否锁定，使用Promise异步回调。 @@ -410,11 +451,13 @@ isScreenRotationLocked(): Promise<boolean> **系统能力：** SystemCapability.WindowManager.WindowManager.Core **返回值：** + | 类型 | 说明 | | ---------------------- | ------------------------------------- | | Promise<boolean> | Promise对象。返回true表示当前自动转屏处于锁定状态；返回false表示当前自动转屏不处于锁定状态。 | **示例：** + ```js screen.isScreenRotationLocked().then((isLocked) => { console.info('Succeeded in getting screen rotation lock status. isLocked:'+ JSON.stringify(isLocked)); @@ -424,6 +467,7 @@ screen.isScreenRotationLocked().then((isLocked) => { ``` ## screen.isScreenRotationLocked + isScreenRotationLocked(callback: AsyncCallback<boolean>): void 查询当前自动转屏是否锁定，使用callback异步回调。 @@ -449,6 +493,7 @@ screen.isScreenRotationLocked((err, isLocked) => { ``` ## screen.setScreenRotationLocked + setScreenRotationLocked(isLocked: boolean): Promise<void> 设置自动转屏开关是否锁定，使用Promise异步回调。 @@ -456,16 +501,19 @@ setScreenRotationLocked(isLocked: boolean): Promise<void> **系统能力：** SystemCapability.WindowManager.WindowManager.Core **参数：** + | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ------------- | | isLocked | boolean | 是 | 自动转屏开关是否锁定。true为锁定，false为未锁定. | **返回值：** + | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **示例：** + ```js var isLocked = false; screen.setScreenRotationLocked(isLocked).then((data) => { @@ -476,6 +524,7 @@ screen.setScreenRotationLocked(isLocked).then((data) => { ``` ## screen.setScreenRotationLocked + setScreenRotationLocked(isLocked: boolean, callback: AsyncCallback<void>): void 设置自动转屏开关是否锁定，使用callback异步回调。 @@ -503,6 +552,7 @@ screen.setScreenRotationLocked(isLocked, (err, data) => { ``` ## ExpandOption + 扩展屏幕的参数。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core @@ -514,6 +564,7 @@ screen.setScreenRotationLocked(isLocked, (err, data) => { | startY | number | 是 | 是 | 屏幕的起始Y轴坐标。 | ## VirtualScreenOption + 创建虚拟屏幕的参数。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core @@ -527,6 +578,7 @@ screen.setScreenRotationLocked(isLocked, (err, data) => { | surfaceId | string | 是 | 是 | 指定虚拟屏幕的surfaceId。 | ## Screen + 屏幕实例。 下列API示例中都需先使用[getAllScreens()](#screengetallscreens)、[createVirtualScreen()](#screencreatevirtualscreen)中的任一方法获取到Screen实例，再通过此实例调用对应方法。 @@ -542,6 +594,7 @@ screen.setScreenRotationLocked(isLocked, (err, data) => { | orientation | [Orientation](#orientation) | 是 | 否 | 屏幕方向。 | ### setOrientation + setOrientation(orientation: Orientation, callback: AsyncCallback<void>): void 设置屏幕方向，使用callback异步回调。 @@ -554,6 +607,7 @@ setOrientation(orientation: Orientation, callback: AsyncCallback<void>): v | callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕方向成功，err为undefined，否则为错误对象。 | **示例：** + ```js screenClass.setOrientation(screen.Orientation.VERTICAL, (err, data) => { if (err.code) { @@ -563,7 +617,9 @@ screenClass.setOrientation(screen.Orientation.VERTICAL, (err, data) => { console.info('Succeeded in setting Orientation VERTICAL. data: ' + JSON.stringify(data)); }) ``` + ### setOrientation + setOrientation(orientation: Orientation): Promise<void> 设置屏幕方向，使用Promise异步回调。 @@ -575,11 +631,13 @@ setOrientation(orientation: Orientation): Promise<void> | orientation | [Orientation](#orientation) | 是 | 屏幕方向。 | **返回值：** + | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **示例：** + ```js let promise = screenClass.setOrientation(screen.Orientation.VERTICAL); promise.then((data) => { @@ -588,7 +646,9 @@ promise.then((data) => { console.error('Failed to set Orientation VERTICAL. Cause: ' + JSON.stringify(err)); }) ``` + ### setScreenActiveMode + setScreenActiveMode(modeIndex: number, callback: AsyncCallback<void>): void 设置屏幕当前显示模式，使用callback异步回调。 @@ -612,7 +672,9 @@ screenClass.setScreenActiveMode(modeIndex, (err, data) => { console.info('Succeeded in setting ScreenActiveMode 0. data: ' + JSON.stringify(data)); }) ``` + ### setScreenActiveMode + setScreenActiveMode(modeIndex: number): Promise<void> 设置屏幕当前显示模式，使用Promise异步回调。 @@ -630,6 +692,7 @@ setScreenActiveMode(modeIndex: number): Promise<void> | Promise<void> | 无返回结果的Promise对象。 | **示例：** + ```js var modeIndex = 0; let promise = screenClass.setScreenActiveMode(modeIndex); @@ -641,6 +704,7 @@ promise.then((data) => { ``` ### setDensityDpi + setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; 设置屏幕的像素密度，使用callback异步回调。 @@ -653,6 +717,7 @@ setDensityDpi(densityDpi: number, callback: AsyncCallback<void>): void; | callback | AsyncCallback<void> | 是 | 回调函数。当设置屏幕的像素密度成功，err为undefined，否则为错误对象。 | **示例：** + ```js var densityDpi = 320; screenClass.setDensityDpi(densityDpi, (err, data) => { @@ -665,6 +730,7 @@ screenClass.setDensityDpi(densityDpi, (err, data) => { ``` ### setDensityDpi + setDensityDpi(densityDpi: number): Promise<void> 设置屏幕的像素密度，使用Promise异步回调。 @@ -682,6 +748,7 @@ setDensityDpi(densityDpi: number): Promise<void> | Promise<void> | 无返回结果的Promise对象。 | **示例：** + ```js var densityDpi = 320; var promise = screenClass.setDensityDpi(densityDpi); @@ -693,6 +760,7 @@ promise.then((data) => { ``` ## Orientation + 屏幕方向枚举。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core @@ -706,6 +774,7 @@ promise.then((data) => { | REVERSE_HORIZONTAL | 4 | 表示指定屏幕为反向水平方向。 | ## ScreenModeInfo + 屏幕显示模式信息。 **系统能力：** SystemCapability.WindowManager.WindowManager.Core