From 1d4d73abb80cd88616a13bf85f57b9cfb84b23cd Mon Sep 17 00:00:00 2001 From: xuzhihao Date: Fri, 29 Apr 2022 15:15:05 +0800 Subject: [PATCH] Fix uri issues of Ability Signed-off-by: xuzhihao --- .../ability/context-userguide.md | 238 ------------------ .../ability/stage-formextension.md | 2 - .../apis/js-apis-application-context.md | 81 ++++++ .../apis/js-apis-formextensioncontext.md | 63 +++++ .../apis/js-apis-service-extension-context.md | 223 ++++++++++++++++ 5 files changed, 367 insertions(+), 240 deletions(-) delete mode 100644 zh-cn/application-dev/ability/context-userguide.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-application-context.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md diff --git a/zh-cn/application-dev/ability/context-userguide.md b/zh-cn/application-dev/ability/context-userguide.md deleted file mode 100644 index f5472f3e54..0000000000 --- a/zh-cn/application-dev/ability/context-userguide.md +++ /dev/null @@ -1,238 +0,0 @@ -# 应用上下文使用指导 - -## Context概述 -​ context是应用中对象的上下文，提供获取应用程序环境信息的能力。 - -## Context整体结构介绍 - -​ OpenHarmony的应用框架分为FA模型和Stage两种模型。对应存在两套Context机制适配两种应用框架模型： - -​ **application/BaseContext** 属于一个通用的Context基类，既不属于FA模型也不属于Stage模型，里面只有一个属性stageMode，用来区分开发模型是FA还是Stage。 - -​ **FA模型** 只有app/Context中的方法属于FA模型对应的Context。该模式下，应用级别的Context和Ability级别的Context都是该类型的实例，如果在应用级别的Context里面调用了Ability级别的方法，会产生错误。所以开发者需要注意context实例所代表的实际含义。 - -​ **Stage模型** 除了app/Context之外的Context都属于Stage模型，分别有application/Context、application/AbilityStageContext、application/ExtensionContext、application/AbilityContext、application/FormExtensionContext和application/ServiceExtensionContext六种Context。这些Context的介绍及使用方式将会在[Stage模型和Context详细介绍](#stage模型和context详细介绍)种进行说明。 - - -![contextIntroduction](figures/contextIntroduction.png) - -## FA模型的Context详细介绍 - -​ 只有app/Context中的方法属于FA模型对应的Context。 - -​ FA模型只有一个Context定义。Context中所有的功能都是通过方法来提供的，它提供了一些featureAbility中不存在的方法，相当于featureAbility的一个扩展和补全。 - -​ d.ts文件如下： - -​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/app/context.d.ts - -​ 应用的使用方式： - -```javascript -// 1.引入featureAbility -import featureAbility from '@ohos.ability.featureAbility' - -export default { - onCreate() { - console.log('Application onCreate') - - // 2.获取Context - let context = featureAbility.getContext(); - - // 3.调用对应的方法 - context.setShowOnLockScreen(false, (data) => { - console.log("data: " + JSON.stringify(data)); - }); - }, - onActive() { - console.log('Application onActive') - }, - onDestroy() { - console.log('Application onDestroy') - }, -} -``` - -## Stage模型和Context详细介绍 - -​ Stage模型有6大Context： - -### application/Context - -**概述** - -​ application/Context类型的Context是基类Context，里面提供了应用的一些基础信息：resourceManager、applicationInfo、cacheDir等，还有应用的一些基本方法：createBundleContext、switchArea等。应用级别的Context也是application/Context这种类型。 - -**获取方法** - -​ 需要在AbilityStage、Ability、Extension等组件中通过context.getApplicationContext()拿到。 - -**示例** - -```javascript -export default class MainAbility extends Ability { - onCreate(want, launchParam) { - console.log('MainAbility onCreate is called' + want + launchParam); - // 获取ApplicationContext - let appContext = this.context.getApplicationContext(); - // 获取路径 - console.log('filesDir is ' + appContext.filesDir); - } - - onDestroy() { - console.log('MainAbility onDestroy is called'); - } -} -``` - -**d.ts声明** - -​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/Context.d.ts - -### application/AbilityStageContext - -​ **概述** - -​ application/AbilityStageContext是Hap包级别的Context。和基类Context相比，Hap包级别的Context中多了HapModuleInfo和Configuration两个信息。 - -**获取方法** - -​ 可以直接在AbilityStage中通过context属性拿到。 - -**示例** - -```javascript -export default class MyAbilityStage extends AbilityStage { - onCreate() { - // 属性context就是AbilityStageContext类型的 - console.log('HapModuleInfo is ' + context.currentHapModuleInfo); - } -} -``` - -**d.ts声明** - -​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/AbilityStageContext.d.ts - -### application/AbilityContext - -​ **概述** - -​ Stage模型下，每个Ability中都包含了一个Context属性。 - -​ Ability功能主要是处理生命周期，其余操作Ability的方法(如startAbility、connectAbility等)都是在AbilityContext中实现的。 - -**获取方法** - -​ 在Ability中通过context属性拿到。 - -**示例** - -```javascript -export default class MainAbility extends Ability { - onCreate(want, launchParam) { - console.log('MainAbility onCreate is called' + want + launchParam); - var want = { - "bundleName": "com.example.MyApplication", - "abilityName": "ServiceExtAbility", - } - // 1.这里的Context就是AbilityContext - let contxt = this.context; - // 2.startAbility - contxt.startAbility(want).then((data) => { - console.info("startAbility success:" + JSON.stringify(data)); - }).catch((error) => { - console.error("startAbility failed:" + JSON.stringify(error)); - }); - } - - onDestroy() { - console.log("MainAbility on Destroy is called"); - } -} -``` - -**d.ts声明** - -​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/AbilityContext.d.ts - -### application/ExtensionContext - -​ **概述** - -​ 和FA模型不同的是，Stage模型把Service从Ability中剥离出来，单独定义了一组通用扩展类Extension用来处理等同的功能。Extension是一个基类，不承担具体业务功能。业务方根据自己的需要去扩展对应的Extension，例如：ServiceAbility扩展为了ServiceExtensionAbility，卡片扩展为了FormExtension。 - -​ 因此新增了一种和Extension匹配的ExtensionContext。ExtensionContext中包含HapModuleInfo和Configuration两个属性。 - -**获取方法** - -​ 不会单独使用。 - -**d.ts声明** - -​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/ExtensionContext.d.ts - -### application/ServiceExtensionContext - -​ **概述** - -​ ServiceExtensionAbility类似于FA模型的ServiceAbility，里面只有生命周期回调相关的处理。 - -​ 操作ServiceExtensionAbility的方法移动到了ServiceExtensionContext中(如startAbility、connectAbility等)。 - -**获取方法** - -​ ServiceExtensionAbility中通过context属性获取。 - -**示例** -```javascript -export default class ServiceExtAbility extends ServiceExtensionAbility { - onCreate(want) { - console.info("ServiceAbility onCreate**"); - // 1.这里的Context就是ServiceExtensionContext - let contxt = this.context; - } - - onRequest(want, startId) { - console.info("ServiceAbility onRequest**"); - } - - onConnect(want) { - console.info("ServiceAbility onConnect**"); - return new StubTest("test"); - } - - onDisconnect(want) { - console.info("ServiceAbility onDisconnect**"); - } - - onDestroy() { - console.info("ServiceAbility onDestroy**"); - } -} - -``` - -**d.ts声明** - -​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/ServiceExtensionContext.d.ts - -### application/FormExtensionContext - -​ [FormExtensionContext](/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md) - -**d.ts声明** - -​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/FormExtensionContext.d.ts - -## 常见问题 - -**通过globalThis去获取Context** - -**结论** - -​ FA模型可以通过该方式去获取；Stage模型不可通过该方式去获取，要通过对应组件的属性去获取。 - -**原因** - -​ 应用框架在API8上推出了新的应用模型（Stage模型）。在老的模型（FA模型）下，每个Ability实例有一个js虚拟机实例，所以可以从js引擎的global对象上，获取到一个全局的Ability实例，但是在新的模型（Stage模型）下，整个应用进程共用一个js虚拟机实例，其中可以运行多个Ability实例，这样就不存在一个全局的Ability实例。如果开发者在新的模型（Stage模型）下，调用的API实现仍然走到了获取全局Ability实例的方法，就可能会发生错误或者崩溃。 \ No newline at end of file diff --git a/zh-cn/application-dev/ability/stage-formextension.md b/zh-cn/application-dev/ability/stage-formextension.md index d6977be8d4..4d49eaaad1 100644 --- a/zh-cn/application-dev/ability/stage-formextension.md +++ b/zh-cn/application-dev/ability/stage-formextension.md @@ -244,8 +244,6 @@ Form需要在应用配置文件module.json中进行配置。 } ``` -具体的持久化方法可以参考[轻量级数据存储开发指导](../database/database-preference-guidelines.md)。 - 需要注意的是，卡片使用方在请求卡片时传递给提供方应用的Want数据中存在临时标记字段，表示此次请求的卡片是否为临时卡片： 常态卡片：卡片使用方会持久化的卡片； diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-context.md b/zh-cn/application-dev/reference/apis/js-apis-application-context.md new file mode 100644 index 0000000000..4fa6b87cff --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-application-context.md @@ -0,0 +1,81 @@ +# Context + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +提供开发者运行代码的上下文环境，包括应用信息、ResourceManager等信息。 + + +## 使用说明 + + +通过AbilityContext等继承实现。 + + +## 属性 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core + + | 名称 | 参数类型 | 可读 | 可写 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| resourceManager | ResourceManager | 是 | 否 | ResourceManager对象。 | +| applicationInfo | ApplicationInfo | 是 | 否 | 当前应用信息。 | +| cacheDir | string | 是 | 否 | 应用在内部存储上的缓存路径。 | +| tempDir | string | 是 | 否 | 应用的临时文件路径。 | +| filesDir | string | 是 | 否 | 应用在内部存储上的文件路径。 | +| databaseDir | string | 是 | 否 | 获取本地数据存储路径。 | +| storageDir | string | 是 | 否 | 获取轻量级数据存储路径。 | +| bundleCodeDir | string | 是 | 否 | 应用安装路径。 | +| distributedFilesDir | string | 是 | 否 | 应用的分布式文件路径。 | +| eventHub | [EventHub](js-apis-eventhub.md) | 是 | 否 | 事件中心信息。| + + +## Context.createBundleContext + +createBundleContext(bundleName: string): Context; + +创建指定应用上下文。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | bundleName | string | 是 | 应用bundle名。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | Context | 对应创建应用的上下文context。 | + +**示例：** + + ```js + let test = "com.example.test"; + let context = this.context.createBundleContext(test); + ``` + + +## Context.getApplicationContext + +getApplicationContext(): Context; + +获取当前context。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | Context | 当前Context 信息。 | + +**示例：** + + ```js + // 必选项。 + let context = this.context.getApplicationContext(); + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md b/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md new file mode 100644 index 0000000000..cad850c9af --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-formextensioncontext.md @@ -0,0 +1,63 @@ +# FormExtensionContext + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +FormExtension的上下文环境，提供FormExtension具有的能力和接口，继承自ExtensionContext。 + +## FormExtensionContext.updateForm + +updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void + +主动更新卡片。 + +**系统能力**：SystemCapability.Ability.Form + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | --------------- | ------------------------------------------------------------ | ---- | -------------------------------------- | + | formId | string | 是 | 请求更新的卡片ID。 | + | formBindingData | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | 是 | 卡片新的数据。 | + | callback | AsyncCallback\ | 是 | 回调函数，返回接口调用是否成功的结果。 | + +**示例：** + + ```js + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + this.context.updateForm(formId, obj2, (data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }); + ``` + +## FormExtensionContext.updateForm + +updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise\ + +更新卡片。 + +**系统能力**：SystemCapability.Ability.Form + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | --------------- | ------------------------------------------------------------ | ---- | ------------------ | + | formId | string | 是 | 请求更新的卡片ID。 | + | formBindingData | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | 是 | 卡片新的数据。 | + +**返回值：** + + | 类型 | 说明 | + | -------------- | --------------------------------- | + | Promise\ | 返回一个Promise，包含接口的结果。 | + +**示例：** + + ``` + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + this.context.updateForm(formId, obj2) + .then((data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md b/zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md new file mode 100644 index 0000000000..4a0c2748f2 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-service-extension-context.md @@ -0,0 +1,223 @@ +# ServiceExtensionContext + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +ServiceExtension的上下文环境，提供ServiceExtension具有的能力和接口，继承自ExtensionContext。 + + +## startAbility + +startAbility(want: Want, callback: AsyncCallback<void>): void; + +启动Ability。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 | + | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | + +**示例：** + + ```js + let want = { + "bundleName": "com.example.myapp", + "abilityName": "com.example.myapp.MyAbility" + }; + this.context.startAbility(want, (err) => { + console.log('startAbility result:' + JSON.stringfy(err)); + }); + ``` + + +## ServiceExtensionContext.startAbility + +startAbility(want: Want): Promise<void>; + +启动Ability。通过Promise返回结果。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 返回一个Promise，包含接口的结果。 | + +**示例：** + + ```js + let want = { + "bundleName": "com.example.myapp", + "abilityName": "com.example.myapp.MyAbility" + }; + this.context.startAbility(want).then((data) => { + console.log('success:' + JSON.stringfy(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringfy(error)); + }); + ``` + + +## ServiceExtensionContext.terminateSelf + +terminateSelf(callback: AsyncCallback<void>): void; + +停止Ability自身。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | + +**示例：** + + ```js + this.context.terminateSelf((err) => { + console.log('terminateSelf result:' + JSON.stringfy(err)); + }); + ``` + + +## ServiceExtensionContext.terminateSelf + +terminateSelf(): Promise<void>; + +停止自身。通过Promise返回结果。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 返回一个Promise，包含接口的结果。 | + +**示例：** + + ```js + this.context.terminateSelf(want).then((data) => { + console.log('success:' + JSON.stringfy(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringfy(error)); + }); + ``` + + +## ServiceExtensionContext.connectAbility + +connectAbility(want: Want, options: ConnectOptions): number; + +将一个Ability与服务类型的Ability绑定。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 | + | options | [ConnectOptions](#connectoptions) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | number | 返回一个number，后续根据这个number去断开连接。 | + +**示例：** + + ```js + let want = { + "bundleName": "com.example.myapp", + "abilityName": "com.example.myapp.MyAbility" + }; + let options = { + onConnect: function(elementName, proxy) {}, + onDisConnect: function(elementName) {}, + onFailed: function(code) {} + } + let connection = this.context.connectAbility(want,options); + ``` + + +## ServiceExtensionContext.disconnectAbility + +disconnectAbility(connection: number, callback:AsyncCallback<void>): void; + +将一个Ability与绑定的服务类型的Ability解绑。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | connection | number | 是 | 在connectAbility中返回的number。 | + | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 | + +**示例：** + + ```js + this.context.disconnectAbility(connection, (err) => { // connection为connectAbility中的返回值 + console.log('terminateSelf result:' + JSON.stringfy(err)); + }); + ``` + + +## ServiceExtensionContext.disconnectAbility + +disconnectAbility(connection: number): Promise<void>; + +将一个Ability与绑定的服务类型的Ability解绑。通过Promise返回结果。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | connection | number | 是 | 在connectAbility中返回的number。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | 返回一个Promise，包含接口的结果。 | + +**示例：** + + ```js + this.context.disconnectAbility(connection).then((data) => { // connection为connectAbility中的返回值 + console.log('success:' + JSON.stringfy(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringfy(error)); + }); + ``` + + +## ConnectOptions + +ConnectOptions数据结构。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core + +| 名称 | 说明 | +| -------- | -------- | +| onConnect(elementName:ElementName, remote:IRemoteObject) | Ability成功连接一个服务类型Ability的回调接口。 | +| onDisconnect(elementName:ElementName) | 对端服务发生异常或者被杀死回调该接口。 | +| onFailed(code: number) | 连接失败时回调该接口。 | -- GitLab