未验证 提交 1484dc2e 编写于 作者: 葛亚芳 提交者: Gitee

update zh-cn/application-dev/reference/apis/js-apis-screen.md.

Signed-off-by: N葛亚芳 <geyafang@huawei.com>
上级 b05d87f2
# 屏幕
本模块提供管理屏幕的一些基础能力,包括获取屏幕对象,监听屏幕变化,创建和销毁虚拟屏幕等。
> **说明:**
......@@ -6,6 +7,7 @@
> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
>
> 本模块接口为系统接口。
## 导入模块
```js
......@@ -39,6 +41,7 @@ screen.getAllScreens((err, data) => {
screenClass = data[0];
});
```
## screen.getAllScreens
getAllScreens(): Promise&lt;Array&lt;Screen&gt;&gt;
......@@ -48,11 +51,13 @@ getAllScreens(): Promise&lt;Array&lt;Screen&gt;&gt;
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**返回值:**
| 类型 | 说明 |
| --------------------------------------------- | ----------------------------------------- |
| Promise&lt;Array&lt;[Screen](#screen)&gt;&gt; | 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&lt;number&gt;): void
开启屏幕状态变化的监听。
......@@ -71,19 +78,23 @@ on(eventType: 'connect' | 'disconnect' | 'change', callback: Callback&lt;number&
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------------------- | ---- | ------------------------------------------------------------ |
| eventType | string | 是 | 监听事件。<br/>-eventType为"connect"表示屏幕连接事件。<br/>-eventType为"disconnect"表示断开屏幕连接事件。<br/>-eventType为"change"表示屏幕状态改变事件。 |
| callback | Callback&lt;number&gt; | 是 | 回调函数。返回屏幕的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&lt;number&gt;): void
关闭屏幕状态变化的监听。
......@@ -91,12 +102,14 @@ off(eventType: 'connect' | 'disconnect' | 'change', callback?: Callback&lt;numbe
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ---------------------- | ---- | ------------------------------------------------------------ |
| eventType | string | 是 | 监听事件。<br/>-eventType为"connect"表示屏幕连接事件。<br/>-eventType为"disconnect"表示断开屏幕连接事件。<br/>-eventType为"change"表示屏幕状态改变事件。 |
| callback | Callback&lt;number&gt; | 否 | 回调函数。返回屏幕的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&lt;ExpandOption&gt;, callback: AsyncCallback&lt;number&gt;): void
将屏幕设置为扩展模式,使用callback异步回调。
......@@ -112,6 +126,7 @@ makeExpand(options:Array&lt;ExpandOption&gt;, callback: AsyncCallback&lt;number&
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------ | ---- | -------------------------------- |
| options | Array&lt;[ExpandOption](#expandoption)&gt; | 是 | 设置扩展屏幕的参数集合。 |
......@@ -132,6 +147,7 @@ screen.makeExpand([{screenId: 0, startX: 0, startY: 0}, {screenId: 1, startX: 10
```
## screen.makeExpand
makeExpand(options:Array&lt;ExpandOption&gt;): Promise&lt;number&gt;
将屏幕设置为扩展模式,使用Promise异步回调。
......@@ -145,11 +161,13 @@ makeExpand(options:Array&lt;ExpandOption&gt;): Promise&lt;number&gt;
| options | Array&lt;[ExpandOption](#expandoption)&gt; | 是 | 设置扩展屏幕的参数集合。 |
**返回值:**
| 类型 | 说明 |
| --------------------- | ----------------------------------- |
| Promise&lt;number&gt; | 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&lt;number&gt;, callback: AsyncCallback&lt;number&gt;): void
将屏幕设置为镜像模式,使用callback异步回调。
......@@ -174,6 +193,7 @@ makeMirror(mainScreen:number, mirrorScreen:Array&lt;number&gt;, callback: AsyncC
| callback | AsyncCallback&lt;number&gt; | 是 | 回调函数。返回镜像屏幕的群组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&lt;number&gt;): Promise&lt;number&gt;
将屏幕设置为镜像模式,使用Promise异步回调。
......@@ -201,11 +222,13 @@ makeMirror(mainScreen:number, mirrorScreen:Array&lt;number&gt;): Promise&lt;numb
| mirrorScreen | Array&lt;number&gt; | 是 | 镜像屏幕id集合。 |
**返回值:**
| 类型 | 说明 |
| --------------------- | ----------------------------------- |
| Promise&lt;number&gt; | 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&lt;Screen&gt;): void
创建虚拟屏幕,使用callback异步回调。
......@@ -233,6 +257,7 @@ createVirtualScreen(options:VirtualScreenOption, callback: AsyncCallback&lt;Scre
| callback | AsyncCallback&lt;[Screen](#screen)&gt; | 是 | 回调函数,返回创建的虚拟屏幕对象。 |
**示例:**
```js
var screenClass = null;
screen.createVirtualScreen({
......@@ -252,6 +277,7 @@ screen.createVirtualScreen({
```
## screen.createVirtualScreen
createVirtualScreen(options:VirtualScreenOption): Promise&lt;Screen&gt;
创建虚拟屏幕,使用Promise异步回调。
......@@ -261,6 +287,7 @@ createVirtualScreen(options:VirtualScreenOption): Promise&lt;Screen&gt;
**需要权限**:ohos.permission.CAPTURE_SCREEN,如果VirtualScreenOption.surfaceId有效,此权限是必需的。仅系统应用可用。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------------------------------------- | ---- | ------------------------ |
| options | [VirtualScreenOption](#virtualscreenoption) | 是 | 用于创建虚拟屏幕的参数。 |
......@@ -272,6 +299,7 @@ createVirtualScreen(options:VirtualScreenOption): Promise&lt;Screen&gt;
| Promise&lt;[Screen](#screen)&gt; | Promise对象。返回创建的虚拟屏幕对象。 |
**示例:**
```js
var screenClass = null;
screen.createVirtualScreen({
......@@ -289,6 +317,7 @@ screen.createVirtualScreen({
```
## screen.destroyVirtualScreen
destroyVirtualScreen(screenId:number, callback: AsyncCallback&lt;void&gt;): void
销毁虚拟屏幕,使用callback异步回调。
......@@ -296,12 +325,14 @@ destroyVirtualScreen(screenId:number, callback: AsyncCallback&lt;void&gt;): void
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| screenId | number | 是 | 屏幕的id。 |
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当销毁虚拟屏幕成功,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&lt;void&gt;
销毁虚拟屏幕,使用Promise异步回调。
......@@ -321,16 +353,19 @@ destroyVirtualScreen(screenId:number): Promise&lt;void&gt;
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ---------- |
| screenId | number | 是 | 屏幕的id。 |
**返回值:**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | 无返回结果的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&lt;void&gt;): void
设置虚拟屏幕的surface,使用callback异步回调。
......@@ -372,6 +408,7 @@ screen.setVirtualScreenSurface(screenId, surfaceId, (err,data) => {
```
## screen.setVirtualScreenSurface
setVirtualScreenSurface(screenId:number, surfaceId: string): Promise&lt;void&gt;
设置虚拟屏幕的surface,使用Promise异步回调。
......@@ -381,17 +418,20 @@ setVirtualScreenSurface(screenId:number, surfaceId: string): Promise&lt;void&gt;
**需要权限**:ohos.permission.CAPTURE_SCREEN,仅系统应用可用。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ------------- |
| screenId | number | 是 | 屏幕的id。 |
| surfaceId | string | 是 | surface的id。 |
**返回值:**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例:**
```js
var screenId = 1;
var surfaceId = '2048';
......@@ -403,6 +443,7 @@ screen.setVirtualScreenSurface(screenId, surfaceId).then((data) => {
```
## screen.isScreenRotationLocked
isScreenRotationLocked(): Promise&lt;boolean&gt;
查询当前自动转屏是否锁定,使用Promise异步回调。
......@@ -410,11 +451,13 @@ isScreenRotationLocked(): Promise&lt;boolean&gt;
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**返回值:**
| 类型 | 说明 |
| ---------------------- | ------------------------------------- |
| Promise&lt;boolean&gt; | 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&lt;boolean&gt;): void
查询当前自动转屏是否锁定,使用callback异步回调。
......@@ -449,6 +493,7 @@ screen.isScreenRotationLocked((err, isLocked) => {
```
## screen.setScreenRotationLocked
setScreenRotationLocked(isLocked: boolean): Promise&lt;void&gt;
设置自动转屏开关是否锁定,使用Promise异步回调。
......@@ -456,16 +501,19 @@ setScreenRotationLocked(isLocked: boolean): Promise&lt;void&gt;
**系统能力:** SystemCapability.WindowManager.WindowManager.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | ------------- |
| isLocked | boolean | 是 | 自动转屏开关是否锁定。true为锁定,false为未锁定. |
**返回值:**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | 无返回结果的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&lt;void&gt;): 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&lt;void&gt;): void
设置屏幕方向,使用callback异步回调。
......@@ -554,6 +607,7 @@ setOrientation(orientation: Orientation, callback: AsyncCallback&lt;void&gt;): v
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当设置屏幕方向成功,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&lt;void&gt;
设置屏幕方向,使用Promise异步回调。
......@@ -575,11 +631,13 @@ setOrientation(orientation: Orientation): Promise&lt;void&gt;
| orientation | [Orientation](#orientation) | 是 | 屏幕方向。 |
**返回值:**
| 类型 | 说明 |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | 无返回结果的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&lt;void&gt;): 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&lt;void&gt;
设置屏幕当前显示模式,使用Promise异步回调。
......@@ -630,6 +692,7 @@ setScreenActiveMode(modeIndex: number): Promise&lt;void&gt;
| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
**示例:**
```js
var modeIndex = 0;
let promise = screenClass.setScreenActiveMode(modeIndex);
......@@ -641,6 +704,7 @@ promise.then((data) => {
```
### setDensityDpi
setDensityDpi(densityDpi: number, callback: AsyncCallback&lt;void&gt;): void;
设置屏幕的像素密度,使用callback异步回调。
......@@ -653,6 +717,7 @@ setDensityDpi(densityDpi: number, callback: AsyncCallback&lt;void&gt;): void;
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当设置屏幕的像素密度成功,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&lt;void&gt;
设置屏幕的像素密度,使用Promise异步回调。
......@@ -682,6 +748,7 @@ setDensityDpi(densityDpi: number): Promise&lt;void&gt;
| Promise&lt;void&gt; | 无返回结果的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
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册