!2527 更新Stage模型ability及call文档

Merge pull request !2527 from 张亚菲/zyf

zh-cn/application-dev/ability/stage-ability.md

@@ -11,7 +11,7 @@ Stage模型是基于API version 9的应用开发模型，对此模型的介绍
 - 应用迁移，详见[应用迁移开发指导](stage-ability-continuation.md)。
 
 ## 接口说明
-AbilityStage功能如下（AbilityStage类，拥有context属性，具体的API详见[接口文档](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-application-abilitystage.md)）：
+AbilityStage功能如下（AbilityStage类，拥有context属性，具体的API详见[接口文档](../reference/apis/js-apis-application-abilitystage.md)）：
 
 **表1** AbilityStage API接口功能介绍
 |接口名|描述|
@@ -20,7 +20,7 @@ AbilityStage功能如下（AbilityStage类，拥有context属性，具体的API
 |string onAcceptWant(want: Want)|启动指定Ability时被调用。|
 |void onConfigurationUpdated(config: Configuration)|全局配置发生变更时被调用。|
 
-Ability功能如下（bility类，具体的API详见[接口文档](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-application-ability.md)）：
+Ability功能如下（Ability类，具体的API详见[接口文档](../reference/apis/js-apis-application-ability.md)）：
 
 **表2** Ability API接口功能介绍
 |接口名|描述|
@@ -34,7 +34,7 @@ Ability功能如下（bility类，具体的API详见[接口文档](https://gitee
 |void onNewWant(want: Want)|Ability回调，Ability的启动模式设置为单例时被调用。|
 |void onConfigurationUpdated(config: Configuration)|Ability回调，Ability的系统配置更新时被调用。|
 
-Ability类拥有context属性，context属性为AbilityContext类，AbilityContext类拥有abilityInfo、currentHapModuleInfo等属性，具体的API详见[接口文档](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-ability-context.md)。
+Ability类拥有context属性，context属性为AbilityContext类，AbilityContext类拥有abilityInfo、currentHapModuleInfo等属性，具体的API详见[接口文档](../reference/apis/js-apis-ability-context.md)。
 
 **表3** AbilityContext API接口功能介绍
 |接口名|描述|
@@ -70,36 +70,36 @@ Ability类拥有context属性，context属性为AbilityContext类，AbilityConte
    import Ability from '@ohos.application.Ability'
    ```
 4. 实现Ability生命周期接口。
-   
-   在`onWindowStageCreate(windowStage)`中通过loadContent接口设置应用要加载的页面，window接口的使用详见[窗口开发指导](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/windowmanager/window-guidelines.md/)。
+
+   在`onWindowStageCreate(windowStage)`中通过loadContent接口设置应用要加载的页面，window接口的使用详见[窗口开发指导](../windowmanager/window-guidelines.md)。
    ```ts
    export default class MainAbility extends Ability {
     onCreate(want, launchParam) {
         console.log("MainAbility onCreate")
     }
-   
+
     onDestroy() {
         console.log("MainAbility onDestroy")
     }
-   
+
     onWindowStageCreate(windowStage) {
         console.log("MainAbility onWindowStageCreate")
-   
+
         windowStage.loadContent("pages/index").then((data) => {
             console.log("MainAbility load content succeed with data: " + JSON.stringify(data))
         }).catch((error) => {
             console.error("MainAbility load content failed with error: "+ JSON.stringify(error))
         })
     }
-   
+
     onWindowStageDestroy() {
         console.log("MainAbility onWindowStageDestroy")
     }
-   
+
     onForeground() {
         console.log("MainAbility onForeground")
     }
-   
+
     onBackground() {
         console.log("MainAbility onBackground")
     }
@@ -202,7 +202,7 @@ function getRemoteDeviceId() {
 应用需要某些权限如存储、位置信息、访问日历时，需要向用户申请授权。具体示例代码如下：
 ```ts
 let context = this.context
-let permissions = ohos.permission.READ_CALENDAR
+let permissions: Array<string> = ['ohos.permission.READ_CALENDAR']
 context.requestPermissionsFromUser(permissions).then((data) => {
     console.log("Succeed to request permission from user with data: "+ JSON.stringify(data))
 }).catch((error) => {
@@ -212,7 +212,7 @@ context.requestPermissionsFromUser(permissions).then((data) => {
 在跨设备场景下，需要向用户申请数据同步的权限。具体示例代码如下：
 ```ts
 let context = this.context
-let permissions = ohos.permission.DISTRIBUTED_DATASYNC
+let permissions: Array<string> = ['ohos.permission.DISTRIBUTED_DATASYNC']
 context.requestPermissionsFromUser(permissions).then((data) => {
     console.log("Succeed to request permission from user with data: "+ JSON.stringify(data))
 }).catch((error) => {
@@ -221,7 +221,7 @@ context.requestPermissionsFromUser(permissions).then((data) => {
 ```
 
 ### 系统环境变化通知给AbilityStage及Ability
-全局配置，比如系统语言和颜色模式发生变化时，通过onConfigurationUpdated接口通知给AbilityStage和Ability。如下示例展示了AbilityStage的onConfigurationUpdated回调实现，系统语言和颜色模式发生变化时触发该回调。具体示例代码如下：
+全局配置，比如系统语言和颜色模式发生变化时，通过`onConfigurationUpdated`接口通知给AbilityStage和Ability。系统应用可以通过`updateConfiguration`接口更新系统语言和颜色模式。如下示例展示了AbilityStage的`onConfigurationUpdated`回调实现，系统语言和颜色模式发生变化时触发该回调。具体示例代码如下：
 ```ts
 import Ability from '@ohos.application.Ability'
 import ConfigurationConstant from '@ohos.application.ConfigurationConstant'
@@ -234,7 +234,7 @@ export default class MyAbilityStage extends AbilityStage {
 }
 ```
 
-如下示例展示了Ability的onConfigurationUpdated回调实现，系统语言、颜色模式以及Display相关的参数，比如方向、Density，发生变化时触发该回调。具体示例代码如下：
+如下示例展示了Ability的`onConfigurationUpdated`回调实现，系统语言、颜色模式以及Display相关的参数，比如方向、Density，发生变化时触发该回调。具体示例代码如下：
 ```ts
 import Ability from '@ohos.application.Ability'
 import ConfigurationConstant from '@ohos.application.ConfigurationConstant'
@@ -253,6 +253,6 @@ export default class MainAbility extends Ability { {
 ## 开发实例
 针对Stage模型Ability开发，有以下示例工程可供参考：
 
-[eTSStageCallAbility]()
+[eTSStageCallAbility](https://gitee.com/openharmony/app_samples/tree/master/ability/eTSStageCallAbility)
 
-本示例eTSStageCallAbility中，在Application目录的AbilityStage.ts中实现AbilityStage的接口，在MainAbility目录实现Ability的接口并设置"pages/index"中的内容为Ability的界面，在SecondAbility目录实现另一个Ability并设置"pages/second"为Ability的界面。支持MainAbility启动SecondAbility。
\ No newline at end of file
+本示例eTSStageCallAbility中，在Application目录的AbilityStage.ts中实现AbilityStage的接口，在MainAbility目录实现Ability的接口并设置"pages/index"为Ability的页面，在CaleeAbility目录实现另一个Ability并设置"pages/second"为Ability的页面。支持MainAbility启动CaleeAbility。

zh-cn/application-dev/ability/stage-call.md

@@ -9,7 +9,7 @@ Ability Call调用是Ability能力的扩展，它为Ability提供一种能够被
 ![stage-call](figures/stage-call.png)
 
 ## 接口说明
-Caller及Callee功能如下：具体的API详见[接口文档](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-application-ability.md#caller)。
+Caller及Callee功能如下：具体的API详见[接口文档](../reference/apis/js-apis-application-ability.md#caller)。
 
 **表1** Call API接口功能介绍
 |接口名|描述|
@@ -53,7 +53,7 @@ import Ability from '@ohos.application.Ability'
 
   调用端及被调用端发送接收的数据格式需协商一致，如下示例约定数据由number和string组成。具体示例代码如下：
 ```ts
-export class MySequenceable {
+export default class MySequenceable {
     num: number = 0
     str: String = ""
 
@@ -77,32 +77,38 @@ export class MySequenceable {
 ```
 4. 实现Callee.on监听及Callee.off解除监听
 
-  被调用端Callee的监听函数注册时机, 取决于应用开发者。注册监听之前的数据不会被处理，取消监听之后的数据不会被处理。如下示例在Ability的onCreate注册'CalleeSortMethod'监听，在onDestroy取消监听，收到序列化数据后对字符串排序后返回，应用开发者根据实际需要做相应处理。具体示例代码如下：
+  被调用端Callee的监听函数注册时机, 取决于应用开发者。注册监听之前的数据不会被处理，取消监听之后的数据不会被处理。如下示例在Ability的onCreate注册'CalleeSortMethod'监听，在onDestroy取消监听，收到序列化数据后作相应处理并返回，应用开发者根据实际需要做相应处理。具体示例代码如下：
 ```ts
-let TAG = '[CalleeAbility] '
-let method = 'CalleeSortMethod'
-
-function CalleeSortFunc(data) {
-    let receiveData = new MySequenceable(0, '')
-    data.readSequenceable(receiveData)
-    console.log(TAG + 'receiveData[' + receiveData.num + ',' + receiveData.str + ']')
-    return new MySequenceable(receiveData.num + 1, Array.from(receiveData.str).sort().join(''))
+const TAG: string = '[CalleeAbility]'
+const MSG_SEND_METHOD: string = 'CallSendMsg'
+
+function sendMsgCallback(data) {
+    Logger.log(TAG, 'CalleeSortFunc called')
+
+    // 获取Caller发送的序列化数据
+    let receivedData = new MySequenceable(0, '')
+    data.readSequenceable(receivedData)
+    Logger.log(TAG, `receiveData[${receivedData.num}, ${receivedData.str}]`)
+
+    // 作相应处理
+    // 返回序列化数据result给Caller
+    return new MySequenceable(receivedData.num + 1, `send ${receivedData.str} succeed`)
 }
 
 export default class CalleeAbility extends Ability {
     onCreate(want, launchParam) {
         try {
-            this.callee.on(method, CalleeSortFunc)
+            this.callee.on(MSG_SEND_METHOD, sendMsgCallback)
         } catch (error) {
-            console.error(TAG + method + 'register failed with error: ' + JSON.stringify(error))
+            Logger.error(TAG, `${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`)
         }
     }
 
     onDestroy() {
         try {
-            this.callee.off(method)
+            this.callee.off(MSG_SEND_METHOD)
         } catch (error) {
-            console.error(TAG + method + 'unregister failed with error: ' + JSON.stringify(error))
+            console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`)
         }
     }
 }
@@ -117,26 +123,25 @@ import Ability from '@ohos.application.Ability'
 
   Ability的context属性实现了startAbilityByCall方法，用于获取指定通用组件的Caller通信接口。如下示例通过`this.context`获取Ability实例的context属性，使用startAbilityByCall拉起Callee被调用端并获取Caller通信接口，注册Caller的onRelease监听。应用开发者根据实际需要做相应处理。具体示例代码如下：
 ```ts
-let TAG = '[MainAbility] '
-var caller = undefined
-let context = this.context
-
-context.startAbilityByCall({
-    bundleName: 'com.samples.CallApplication',
-    abilityName: 'CalleeAbility'
-}).then((data) => {
-    if (data != null) {
-        caller = data
-        console.log(TAG + 'get caller success')
-        // 注册caller的release监听
-        caller.onRelease((msg) => {
-            console.log(TAG + 'caller onRelease is called ' + msg)
+async onButtonGetCaller() {
+    try {
+        this.caller = await context.startAbilityByCall({
+            bundleName: 'com.samples.CallApplication',
+            abilityName: 'CalleeAbility'
         })
-        console.log(TAG + 'caller register OnRelease succeed')
+        if (this.caller === undefined) {
+            Logger.error(TAG, 'get caller failed')
+            return
+        }
+        Logger.log(TAG, 'get caller success')
+        this.regOnRelease(this.caller)
+    } catch (error) {
+        Logger.error(TAG, `get caller failed with ${error}`)
     }
-}).catch((error) => {
+}.catch((error) => {
     console.error(TAG + 'get caller failed with ' + error)
 })
+```
 在跨设备场景下，需指定对端设备deviceId。具体示例代码如下：
 ```ts
 let TAG = '[MainAbility] '
@@ -190,46 +195,56 @@ context.requestPermissionsFromUser(permissions).then((data) => {
 })
 ```
 3. 发送约定序列化数据
+
 向被调用端发送Sequenceable数据有两种方式，一种是不带返回值，一种是获取被调用端返回的数据，method以及序列化数据需要与被调用端协商一致。如下示例调用Call接口，向Calee被调用端发送数据。具体示例代码如下：
 ```ts
-let method = 'CalleeSortMethod'
-let msg = new MySequenceable(1, 'call_str')
-caller.call(method, msg).then(() => {
-        console.log(TAG + 'caller call succeed')
-    }).catch((error) => {
-    console.error(TAG + 'caller call failed with ' + error)
-})
+const MSG_SEND_METHOD: string = 'CallSendMsg'
+async onButtonCall() {
+    try {
+        let msg = new MySequenceable(1, 'origin_Msg')
+        await this.caller.call(MSG_SEND_METHOD, msg)
+    } catch (error) {
+        Logger.error(TAG, `caller call failed with ${error}`)
+    }
+}
 ```
 
-如下示例调用CallWithResult接口，向Calee被调用端发送待处理的数据，并将method方法处理完毕的数据赋值给callback。具体示例代码如下：
+如下示例调用CallWithResult接口，向Calee被调用端发送待处理的数据`originMsg`，并将'CallSendMsg'方法处理完毕的数据赋值给`backMsg`。具体示例代码如下：
 ```ts
-let method = 'CalleeSortMethod'
-let msg = new MySequenceable(1, sortString)
-caller.callWithResult(method, msg)
-    .then((data) => {
-        let resultMsg = new MySequenceable(0, '')
-        data.readSequenceable(resultMsg)
-        callback(resultMsg.str)
-        console.log(TAG + 'caller result is [' + resultMsg.num + ',' + resultMsg.str + ']')
-    }).catch((error) => {
-    console.error(TAG + 'caller callWithResult failed with ' + error)
-})
+const MSG_SEND_METHOD: string = 'CallSendMsg'
+originMsg: string = ''
+backMsg: string = ''
+async onButtonCallWithResult(originMsg, backMsg) {
+    try {
+        let msg = new MySequenceable(1, originMsg)
+        const data = await this.caller.callWithResult(MSG_SEND_METHOD, msg)
+        Logger.log(TAG, 'caller callWithResult succeed')
+
+        let result = new MySequenceable(0, '')
+        data.readSequenceable(result)
+        backMsg(result.str)
+        Logger.log(TAG, `caller result is [${result.num}, ${result.str}]`)
+    } catch (error) {
+        Logger.error(TAG, `caller callWithResult failed with ${error}`)
+    }
+}
 ```
 4. 释放Caller通信接口
+
 Caller不再使用后，应用开发者可以通过release接口释放Caller。具体示例代码如下：
 ```ts
 try {
-    caller.release()
-    caller = undefined
-    console.log(TAG + 'caller release succeed')
+    this.caller.release()
+    this.caller = undefined
+    Logger.log(TAG, 'caller release succeed')
 } catch (error) {
-    console.error(TAG + 'caller release failed with ' + error)
+    Logger.error(TAG, `caller release failed with ${error}`)
 }
 ```
 
 ## 开发实例
 针对Stage模型本地Call功能开发，有以下示例工程可供参考：
 
-[eTSStageCallAbility]()
+[eTSStageCallAbility](https://gitee.com/openharmony/app_samples/tree/master/ability/eTSStageCallAbility)
 
-本示例eTSStageCallAbility中，在Application目录的AbilityStage.ts中实现AbilityStage的接口，在MainAbility目录实现Ability的接口并设置"pages/index"为应用的界面，在CaleeAbility目录实现Callee被调用端。MainAbility获取Caller通信接口后，支持用户输入字符串，做序列化处理后传递给CaleeAbility被调用端处理，Calee将字符串排序，返回序列化数据并将排序结果显示在页面上。
\ No newline at end of file
+本示例eTSStageCallAbility中，在Application目录的AbilityStage.ts中实现AbilityStage的接口，在MainAbility目录实现Ability的接口并设置"pages/index"为Ability的页面，在CaleeAbility目录实现Ability的接口、Callee被调用端，设置"pages/second"为Ability的页面。MainAbility作为调用端，CalleeAbility作为被调用端。MainAbility拉起CalleeAbility，获取Caller通信接口后，支持用户输入字符串，做序列化处理后传递给CaleeAbility处理，CaleeAbility根据收到的数据做页面刷新并返回结果给MainAbility。