!10212 窗口子系统模块文档更新

Merge pull request !10212 from ZhengJiangliang/master

zh-cn/application-dev/reference/apis/js-apis-display.md

@@ -11,7 +11,6 @@
 import display from '@ohos.display';
 ```
 
-
 ## DisplayState
 
 显示设备的状态枚举。
@@ -65,61 +64,6 @@ import display from '@ohos.display';
 | boundingRects                | Array\<[Rect](#rect9)> | 是   | 否   | 挖孔、刘海等区域的边界矩形。 |
 | waterfallDisplayAreaRects   | [WaterfallDisplayAreaRects](#waterfalldisplayarearects9) | 是 | 否 | 瀑布屏曲面部分显示区域。 |
 
-## display.getDefaultDisplay
-
-getDefaultDisplay(callback: AsyncCallback&lt;Display&gt;): void
-
-获取当前默认的display对象，使用callback异步回调。
-
-**系统能力：** SystemCapability.WindowManager.WindowManager.Core
-
-**参数：**
-
-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| callback | AsyncCallback&lt;[Display](#display)&gt; | 是 | 回调函数。返回当前默认的display对象。 |
-
-**示例：**
-
-```js
-var displayClass = null;
-display.getDefaultDisplay((err, data) => {
-    if (err.code) {
-        console.error('Failed to obtain the default display object. Code:  ' + JSON.stringify(err));
-        return;
-    }
-    console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
-    displayClass = data;
-});
-```
-
-## display.getDefaultDisplay
-
-getDefaultDisplay(): Promise&lt;Display&gt;
-
-获取当前默认的display对象，使用Promise异步回调。
-
-**系统能力：** SystemCapability.WindowManager.WindowManager.Core
-
-**返回值：**
-
-| 类型                               | 说明                                           |
-| ---------------------------------- | ---------------------------------------------- |
-| Promise&lt;[Display](#display)&gt; | Promise对象。返回当前默认的display对象。 |
-
-**示例：**
-
-```js
-var displayClass = null;
-let promise = display.getDefaultDisplay();
-promise.then((data) => {
-    displayClass = data;
-    console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
-}).catch((err) => {
-    console.error('Failed to obtain the default display object. Code:  ' + JSON.stringify(err));
-});
-```
-
 ## display.getDefaultDisplaySync<sup>9+</sup>
 
 getDefaultDisplaySync(): Display
@@ -134,15 +78,27 @@ getDefaultDisplaySync(): Display
 | ------------------------------| ----------------------------------------------|
 | [Display](#display) | 返回默认的display对象。 |
 
+**错误码：**
+
+以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。
+
+| 错误码ID | 错误信息 |
+| ------- | ----------------------- |
+| 1400001 | This is invalid screen. |
+
 **示例：**
 
 ```js
-var displayClass = display.getDefaultDisplaySync();
+try {
+    let displayClass = display.getDefaultDisplaySync();
+} catch (exception) {
+    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
+};
 ```
 
-## display.getAllDisplay
+## display.getAllDisplays<sup>9+</sup>
 
-getAllDisplay(callback: AsyncCallback&lt;Array&lt;Display&gt;&gt;): void
+getAllDisplays(callback: AsyncCallback&lt;Array&lt;Display&gt;&gt;): void
 
 获取当前所有的display对象，使用callback异步回调。
 
@@ -154,10 +110,20 @@ getAllDisplay(callback: AsyncCallback&lt;Array&lt;Display&gt;&gt;): void
 | -------- | ---------------------------------------------------- | ---- | ------------------------------- |
 | callback | AsyncCallback&lt;Array&lt;[Display](#display)&gt;&gt; | 是 | 回调函数。返回当前所有的display对象。 |
 
+**错误码：**
+
+以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。
+
+| 错误码ID | 错误信息 |
+| ------- | ----------------------- |
+| 1400001 | This is invalid screen. |
+
 **示例：**
 
 ```js
-display.getAllDisplay((err, data) => {
+let displayClass = null;
+display.getAllDisplays((err, data) => {
+    displayClass = data;
     if (err.code) {
         console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
         return;
@@ -166,9 +132,9 @@ display.getAllDisplay((err, data) => {
 });
 ```
 
-## display.getAllDisplay
+## display.getAllDisplays<sup>9+</sup>
 
-getAllDisplay(): Promise&lt;Array&lt;Display&gt;&gt;
+getAllDisplays(): Promise&lt;Array&lt;Display&gt;&gt;
 
 获取当前所有的display对象，使用Promise异步回调。
 
@@ -180,11 +146,21 @@ getAllDisplay(): Promise&lt;Array&lt;Display&gt;&gt;
 | ----------------------------------------------- | ------------------------------------------------------- |
 | Promise&lt;Array&lt;[Display](#display)&gt;&gt; | Promise对象。返回当前所有的display对象。 |
 
+**错误码：**
+
+以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。
+
+| 错误码ID | 错误信息 |
+| ------- | ----------------------- |
+| 1400001 | This is invalid screen. |
+
 **示例：**
 
 ```js
-let promise = display.getAllDisplay();
+let displayClass = null;
+let promise = display.getAllDisplays();
 promise.then((data) => {
+    displayClass = data;
     console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
 }).catch((err) => {
     console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
@@ -195,7 +171,7 @@ promise.then((data) => {
 
 hasPrivateWindow(displayId: number): boolean
 
-查询指定display对象上是否有可见的隐私窗口。可通过[setPrivacyMode](js-apis-window.md#setprivacymode7)接口设置隐私窗口。隐私窗口内容将无法被截屏或录屏。
+查询指定display对象上是否有可见的隐私窗口。可通过[setWindowPrivacyMode()](js-apis-window.md#setwindowprivacymode9)接口设置隐私窗口。隐私窗口内容将无法被截屏或录屏。
 
 **系统接口：** 此接口为系统接口。
 
@@ -213,20 +189,30 @@ hasPrivateWindow(displayId: number): boolean
 | -------------------------------- |-----------------------------------------------------------------------|
 |boolean | 查询的display对象上是否有可见的隐私窗口。<br>true表示此display对象上有可见的隐私窗口，false表示此display对象上没有可见的隐私窗口。</br> |
 
+**错误码：**
+
+以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。
+
+| 错误码ID | 错误信息 |
+| ------- | -------------------------------------------- |
+| 1400003 | This window manager service work abnormally. |
+
 **示例：**
 
 ```js
-var displayClass = null;
-display.getDefaultDisplay((err, data) => {
-  if (err.code) {
-    console.error('Failed to obtain the default display object. Code:  ' + JSON.stringify(err));
+let displayClass = null;
+try {
+    displayClass = display.getDefaultDisplaySync();
+} catch (exception) {
+    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
     return;
-  }
-  console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
-  displayClass = data;
-});
+};
 
-var ret = display.hasPrivateWindow(displayClass.id);
+try {
+    let 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.");
 }
@@ -234,7 +220,7 @@ if (ret) {
   console.log("There has privateWindow.");
 } else if (!ret) {
   console.log("There has no privateWindow.");
-}
+};
 ```
 
 ## display.on('add'|'remove'|'change')
@@ -255,10 +241,14 @@ on(type: 'add'|'remove'|'change', callback: Callback&lt;number&gt;): void
 **示例：**
 
 ```js
-var callback = (data) => {
+let callback = (data) => {
     console.info('Listening enabled. Data: ' + JSON.stringify(data));
 }
-display.on("add", callback);
+try {
+    display.on("add", callback);
+} catch (exception) {
+    console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
+};
 ```
 
 ## display.off('add'|'remove'|'change')
@@ -279,13 +269,139 @@ off(type: 'add'|'remove'|'change', callback?: Callback&lt;number&gt;): void
 **示例：**
 
 ```js
-display.off("remove");
+try {
+    display.off("remove");
+} catch (exception) {
+    console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
+};
+```
+
+## display.getDefaultDisplay<sup>(deprecated)</sup>
+
+getDefaultDisplay(callback: AsyncCallback&lt;Display&gt;): void
+
+获取当前默认的display对象，使用callback异步回调。
+
+> **说明：**
+> 
+> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。
+
+**系统能力：** SystemCapability.WindowManager.WindowManager.Core
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| callback | AsyncCallback&lt;[Display](#display)&gt; | 是 | 回调函数。返回当前默认的display对象。 |
+
+**示例：**
+
+```js
+let displayClass = null;
+display.getDefaultDisplay((err, data) => {
+    if (err.code) {
+        console.error('Failed to obtain the default display object. Code:  ' + JSON.stringify(err));
+        return;
+    }
+    console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
+    displayClass = data;
+});
+```
+
+## display.getDefaultDisplay<sup>(deprecated)</sup>
+
+getDefaultDisplay(): Promise&lt;Display&gt;
+
+获取当前默认的display对象，使用Promise异步回调。
+
+> **说明：**
+> 
+> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)。
+
+**系统能力：** SystemCapability.WindowManager.WindowManager.Core
+
+**返回值：**
+
+| 类型                               | 说明                                           |
+| ---------------------------------- | ---------------------------------------------- |
+| Promise&lt;[Display](#display)&gt; | Promise对象。返回当前默认的display对象。 |
+
+**示例：**
+
+```js
+let displayClass = null;
+let promise = display.getDefaultDisplay();
+promise.then((data) => {
+    displayClass = data;
+    console.info('Succeeded in obtaining the default display object. Data:' + JSON.stringify(data));
+}).catch((err) => {
+    console.error('Failed to obtain the default display object. Code:  ' + JSON.stringify(err));
+});
+```
+
+## display.getAllDisplay<sup>(deprecated)</sup>
+
+getAllDisplay(callback: AsyncCallback&lt;Array&lt;Display&gt;&gt;): void
+
+获取当前所有的display对象，使用callback异步回调。
+
+> **说明：**
+> 
+> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9)。
+
+**系统能力：** SystemCapability.WindowManager.WindowManager.Core
+
+**参数：**
+
+| 参数名   | 类型                                                 | 必填 | 说明                            |
+| -------- | ---------------------------------------------------- | ---- | ------------------------------- |
+| callback | AsyncCallback&lt;Array&lt;[Display](#display)&gt;&gt; | 是   | 回调函数。返回当前所有的display对象。 |
+
+**示例：**
+
+```js
+display.getAllDisplay((err, data) => {
+    if (err.code) {
+        console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
+        return;
+    }
+    console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
+});
+```
+
+## display.getAllDisplay<sup>(deprecated)</sup>
+
+getAllDisplay(): Promise&lt;Array&lt;Display&gt;&gt;
+
+获取当前所有的display对象，使用Promise异步回调。
+
+> **说明：**
+> 
+> 从 API version 7开始支持，从API version 9开始废弃，推荐使用[getAllDisplays()](#displaygetalldisplays9-1)。
+
+**系统能力：** SystemCapability.WindowManager.WindowManager.Core
+
+**返回值：**
+
+| 类型                                            | 说明                                                    |
+| ----------------------------------------------- | ------------------------------------------------------- |
+| Promise&lt;Array&lt;[Display](#display)&gt;&gt; | Promise对象。返回当前所有的display对象。 |
+
+**示例：**
+
+```js
+let promise = display.getAllDisplay();
+promise.then((data) => {
+    console.info('Succeeded in obtaining all the display objects. Data: ' + JSON.stringify(data));
+}).catch((err) => {
+    console.error('Failed to obtain all the display objects. Code: ' + JSON.stringify(err));
+});
 ```
 
 ## Display
 屏幕实例。描述display对象的属性和方法。
 
-下列API示例中都需先使用[getAllDisplay()](#displaygetalldisplay)、[getDefaultDisplay()](#displaygetdefaultdisplay)、[getDefaultDisplaySync()](#displaygetdefaultdisplaysync)中的任一方法获取到Display实例，再通过此实例调用对应方法。
+下列API示例中都需先使用[getAllDisplays()](#displaygetalldisplays9)、[getDefaultDisplaySync()](#displaygetdefaultdisplaysync9)中的任一方法获取到Display实例，再通过此实例调用对应方法。
 
 **系统能力：** SystemCapability.WindowManager.WindowManager.Core
 
@@ -312,20 +428,36 @@ getCutoutInfo(callback: AsyncCallback&lt;CutoutInfo&gt;): void
 
 **系统能力：** SystemCapability.WindowManager.WindowManager.Core
 
+**参数：**
+
 | 参数名      | 类型                        | 必填 | 说明                                                         |
 | ----------- | --------------------------- | ---- | ------------------------------------------------------------ |
 | callback    | AsyncCallback&lt;[CutoutInfo](#cutoutinfo9)&gt;   | 是   | 回调函数。当获取信息成功，err为undefined，data为获取到的CutoutInfo对象；否则err为错误对象。 |
 
+**错误码：**
+
+以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。
+
+| 错误码ID | 错误信息 |
+| ------- | ----------------------- |
+| 1400001 | This is invalid screen. |
+
 **示例：**
 
 ```js
+try {
+    let displayClass = display.getDefaultDisplaySync();
+} catch (exception) {
+    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
+};
+
 displayClass.getCutoutInfo((err, data) => {
     if (err.code) {
-        console.error('Failed to get cutoutInfo. Cause: ' + JSON.stringify(err));
+        console.error('Failed to get cutoutInfo. Code: ' + JSON.stringify(err));
         return;
     }
     console.info('Succeeded in getting cutoutInfo. data: ' + JSON.stringify(data));
-})
+});
 ```
 ### getCutoutInfo<sup>9+</sup>
 getCutoutInfo(): Promise&lt;CutoutInfo&gt;
@@ -340,9 +472,23 @@ getCutoutInfo(): Promise&lt;CutoutInfo&gt;
 | ------------------- | ------------------------- |
 | Promise&lt;[CutoutInfo](#cutoutinfo9)&gt; | Promise对象，返回描述不可用屏幕区域的CutoutInfo对象。 |
 
+**错误码：**
+
+以下错误码的详细介绍请参见[屏幕错误码](../errorcodes/errorcode-display.md)。
+
+| 错误码ID | 错误信息 |
+| ------- | ----------------------- |
+| 1400001 | This is invalid screen. |
+
 **示例：**
 
 ```js
+try {
+    let displayClass = display.getDefaultDisplaySync();
+} catch (exception) {
+    console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
+};
+
 let promise = displayClass.getCutoutInfo();
 promise.then((data) => {
     console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(data));

zh-cn/application-dev/reference/apis/js-apis-screenshot.md

@@ -73,7 +73,7 @@ save(options: ScreenshotOptions, callback: AsyncCallback<image.PixelMap>):
 **示例：**
 
   ```js
-  var screenshotOptions = {
+  let screenshotOptions = {
     "screenRect": {
         "left": 200,
         "top": 100,
@@ -85,14 +85,18 @@ save(options: ScreenshotOptions, callback: AsyncCallback<image.PixelMap>):
     "rotation": 0,
     "displayId": 0
   };
+  try {
     screenshot.save(screenshotOptions, (err, pixelMap) => {
       if (err) {
-        console.log('Failed to save screenshot: ' + JSON.stringify(err));
+          console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
           return;
       }
       console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
       pixelMap.release(); // PixelMap使用完后及时释放内存
     });
+  } catch (exception) {
+    console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
+  };
   ```
 
 ## screenshot.save
@@ -114,14 +118,18 @@ save(callback: AsyncCallback<image.PixelMap>): void
 **示例：**
 
   ```js
+  try {
     screenshot.save((err, pixelMap) => {
       if (err) {
-        console.log('Failed to save screenshot: ' + JSON.stringify(err));
+          console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
           return;
       }
       console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
       pixelMap.release(); // PixelMap使用完后及时释放内存
     });
+  } catch (exception) {
+    console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
+  };
   ```
 
 ## screenshot.save
@@ -149,7 +157,7 @@ save(options?: ScreenshotOptions): Promise<image.PixelMap>
 **示例：**
 
   ```js
-  var screenshotOptions = {
+  let screenshotOptions = {
   	"screenRect": {
   		"left": 200,
   		"top": 100,
@@ -161,11 +169,15 @@ save(options?: ScreenshotOptions): Promise<image.PixelMap>
   	"rotation": 0,
   	"displayId": 0
   };
+  try {
     let promise = screenshot.save(screenshotOptions);
     promise.then((pixelMap) => {
         console.log('Succeeded in saving sreenshot. Pixel bytes number: ' + pixelMap.getPixelBytesNumber());
         pixelMap.release(); // PixelMap使用完后及时释放内存
     }).catch((err) => {
-      console.log('Failed to save screenshot: ' + JSON.stringify(err));
+        console.log('Failed to save screenshot. Code: ' + JSON.stringify(err));
     });
+  } catch (exception) {
+    console.error('Failed to save screenshot. Code: ' + JSON.stringify(exception));
+  };
   ```

zh-cn/application-dev/reference/errorcodes/errorcode-display.md

+# 屏幕错误码
+
+## 1400001 无效虚拟屏
+### 错误信息
+This is invalid screen.
+### 错误描述
+当操作无效的虚拟屏时，会报此错误码。
+### 可能原因
+1. 虚拟屏未创建。
+2. 虚拟屏已销毁。
+### 处理步骤
+1. 在操作虚拟屏前，检查该虚拟屏是否已经存在，确保已创建该虚拟屏。
+2. 在操作虚拟屏前，检查虚拟屏是否已被销毁，确保其未被销毁，再进行相关操作。
+
+## 1400002 无权限操作
+### 错误信息
+This operation is not access.
+### 错误描述
+当对无操作权限的对象进行操作时，会报此错误码。
+### 可能原因
+操作了其它进程的虚拟屏对象。
+### 处理步骤
+请检查是否非法操作了别的进程的对象，删除相关非法操作。
+
+## 1400003 系统服务工作异常
+### 错误信息
+This window manager service work abnormally.
+### 错误描述
+当系统服务工作异常时，会报此错误码。
+### 可能原因
+1. 窗口内部服务没有正常启动。
+2. 底层图形图像合成渲染异常。
+### 处理步骤
+系统服务内部工作异常，请稍候重试，或者重启设备尝试。

zh-cn/application-dev/reference/errorcodes/errorcode-window.md

+# 窗口错误码
+
+## 1300001 重复操作
+### 错误信息
+This is repeat operation.
+### 错误描述
+当进行某些重复操作时，系统会报此错误码。
+### 可能原因
+创建的窗口已经存在时，再次创建该窗口会报错。
+### 处理步骤
+在创建窗口前，检查该窗口是否已经存在，确保为首次创建该窗口。
+
+## 1300002 窗口状态异常
+### 错误信息
+This window state is abnormal.
+### 错误描述
+当窗口状态异常，如已被销毁时，操作该窗口，会报此错误码。
+### 可能原因
+操作窗口时，该窗口已被销毁。
+### 处理步骤
+在对窗口进行操作前，检查该窗口是否存在，确保其未被销毁，再进行相关操作。
+
+## 1300003 系统服务工作异常
+### 错误信息
+This window manager service work abnormally.
+### 错误描述
+当系统服务工作异常时，会报此错误码。
+### 可能原因
+窗口内部服务没有正常启动。
+### 处理步骤
+系统服务内部工作异常，请稍候重试，或者重启设备尝试。
+
+## 1300004 无权限操作
+### 错误信息
+This operation is not access.
+### 错误描述
+当对无操作权限的对象进行操作时，会报此错误码。
+### 可能原因
+操作了其它进程的窗口对象。
+### 处理步骤
+请检查是否非法操作了别的进程的对象，删除相关操作。
+
+## 1300005 WindowStage异常
+### 错误信息
+This window stage is abnormal.
+### 错误描述
+当WindowStage异常，如已被销毁时，操作该WindowStage，会报此错误码。
+### 可能原因
+操作WindowStage时，该WindowStage已被销毁。
+### 处理步骤
+在对WindowStage进行操作前，检查该WindowStage是否存在，若已被销毁，请释放该WindowStage下的窗口。
+
+## 1300006 窗口上下文异常
+### 错误信息
+This window context is abnormal.
+### 错误描述
+当窗口上下文异常，如已被销毁时，操作该窗口上下文，会报此错误码。
+### 可能原因
+操作窗口上下文时，该窗口上下文已被销毁。
+### 处理步骤
+在对窗口上下文进行操作前，检查该窗口上下文是否存在，确保其未被销毁，再进行相关操作。