From ad8fa98b7d30b9e1d4a7f46cfcacf54038412056 Mon Sep 17 00:00:00 2001 From: "zhangyafei.echo" Date: Thu, 24 Mar 2022 22:27:47 +0800 Subject: [PATCH] Description:Update stage-call.md and stage-ability.md 1.Add blank line between list and body. 2.Add link to app_sample 3.modify promise to async/await 4.change direct link to releative link Sig:SIG_ApplicationFramework Feature or BugFix: Feature Binary Source: No Signed-off-by: zhangyafei.echo Change-Id: I1aaa7ddce65f4cfecd19bc2727055ee0021ba842 --- .../application-dev/ability/stage-ability.md | 34 ++--- zh-cn/application-dev/ability/stage-call.md | 127 ++++++++++-------- 2 files changed, 88 insertions(+), 73 deletions(-) diff --git a/zh-cn/application-dev/ability/stage-ability.md b/zh-cn/application-dev/ability/stage-ability.md index 56d2c71e05..6d3015790b 100644 --- a/zh-cn/application-dev/ability/stage-ability.md +++ b/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 = ['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 = ['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。 diff --git a/zh-cn/application-dev/ability/stage-call.md b/zh-cn/application-dev/ability/stage-call.md index beeb70478b..bf8d23810f 100644 --- a/zh-cn/application-dev/ability/stage-call.md +++ b/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。 -- GitLab