diff --git a/zh-cn/application-dev/application-models/ability-startup-with-implicit-want.md b/zh-cn/application-dev/application-models/ability-startup-with-implicit-want.md index 643b8931eee32882fd66ba9bbccb8acd075ce201..ac6af46ca51c5798877dbc834103f4eb4c977805 100644 --- a/zh-cn/application-dev/application-models/ability-startup-with-implicit-want.md +++ b/zh-cn/application-dev/application-models/ability-startup-with-implicit-want.md @@ -52,11 +52,11 @@ function implicitStartAbility() { let context = getContext(this) as common.UIAbilityContext; let wantInfo = { // uncomment line below if wish to implicitly query only in the specific bundle. - // bundleName: "com.example.myapplication", - "action": "ohos.want.action.viewData", + // bundleName: 'com.example.myapplication', + 'action': 'ohos.want.action.viewData', // entities can be omitted. - "entities": ["entity.system.browsable"], - "uri": "https://www.test.com:8080/query/student" + 'entities': ['entity.system.browsable'], + 'uri': 'https://www.test.com:8080/query/student' } context.startAbility(wantInfo).then(() => { // ... @@ -73,5 +73,5 @@ function implicitStartAbility() { 3. 待匹配Ability的skills配置中内uris拼接为`https://www.test.com:8080/query*` （其中*表示通配符），包含调用方传入的want参数的uri，uri匹配成功。 4. 调用方传入的want参数的type不为空，待匹配Ability的skills配置中的type不为空且包含调用方传入的want参数的type，type匹配成功。 -当有多个匹配应用时，会被应用选择器展示给用户进行选择。 示意效果如下图所示。 +当存在多个匹配的应用时，系统将弹出应用选择框供用户选择。示意效果如下图所示。 ![](figures/ability-startup-with-implicit-want1.png) diff --git a/zh-cn/application-dev/application-models/application-context-stage.md b/zh-cn/application-dev/application-models/application-context-stage.md index b959ddaadb8146f814ef151b785c08ce61a09b22..b734131b18246d0ec6ce82399cca6957dd91dd45 100644 --- a/zh-cn/application-dev/application-models/application-context-stage.md +++ b/zh-cn/application-dev/application-models/application-context-stage.md @@ -43,7 +43,7 @@ - 获取[AbilityStageContext](../reference/apis/js-apis-inner-application-abilityStageContext.md)。Module级别的Context，和基类Context相比，额外提供HapModuleInfo、Configuration等信息。 ```ts - import AbilityStage from "@ohos.app.ability.AbilityStage"; + import AbilityStage from '@ohos.app.ability.AbilityStage'; export default class MyAbilityStage extends AbilityStage { onCreate() { let abilityStageContext = this.context; @@ -80,17 +80,17 @@ 从Context中获取的应用开发路径如下表所示。 - **表1** 应用开发路径说明 +**表1** 应用开发路径说明 | 属性名称 | 参数类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | -| cacheDir | string | 是 | 否 | 应用在内部存储上的缓存路径。
对应于"设置 > 应用管理"，找到对应应用的"存储"中的缓存内容。 | -| tempDir | string | 是 | 否 | 应用的临时文件路径。
在应用卸载后，系统会删除存储在此目录中的文件。 | -| filesDir | string | 是 | 否 | 应用在内部存储上的文件路径。
本目录下存放的文件可能会被应用迁移或者备份的时候同步到其他目录中。 | -| databaseDir | string | 是 | 否 | 获取本地数据库存储路径。 | -| bundleCodeDir | string | 是 | 否 | 应用在内部存储上的安装路径。 | -| distributedFilesDir | string | 是 | 否 | 应用的分布式文件路径。 | -| preferencesDir | string | 是 | 是 | 指示应用程序首选项目录。 | +| bundleCodeDir | string | 是 | 否 | 安装文件路径。应用在内部存储上的安装路径。 | +| cacheDir | string | 是 | 否 | 应用缓存文件路径。应用在内部存储上的缓存路径。
对应于“设置 > 应用管理”，找到对应应用的“存储”中的缓存内容。 | +| filesDir | string | 是 | 否 | 应用通用文件路径。应用在内部存储上的文件路径。
本目录下存放的文件可能会被应用迁移或者备份的时候同步到其他目录中。 | +| preferencesDir | string | 是 | 是 | 应用首选项文件路径。指示应用程序首选项目录。 | +| tempDir | string | 是 | 否 | 应用临时文件路径。
在应用卸载后，系统会删除存储在此目录中的文件。 | +| databaseDir | string | 是 | 否 | 数据库路径。获取本地数据库存储路径。 | +| distributedFilesDir | string | 是 | 否 | 应用分布式文件路径。 | 获取路径的能力是基类Context中提供的能力，因此在ApplicationContext、AbilityStageContext、UIAbilityContext和ExtensionContext中均可以获取，在各类Context中获取到的路径会有一些差别，具体差别如下图所示。 @@ -198,7 +198,7 @@ export default class EntryAbility extends UIAbility { export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { - let bundleName2 = "com.example.application"; + let bundleName2 = 'com.example.application'; let context2 = this.context.createBundleContext(bundleName2); let label2 = context2.applicationInfo.label; // ... @@ -208,19 +208,20 @@ export default class EntryAbility extends UIAbility { - 调用createModuleContext(bundleName:string, moduleName:string)方法，获取指定应用指定Module的上下文信息。获取到指定应用指定Module的Context之后，即可获取到相应应用Module的资源信息。 > **说明：** + > > 当获取的是其他应用的指定Module的Context时： - > - > - 申请`ohos.permission.GET_BUNDLE_INFO_PRIVILEGED`权限，配置方式请参见[访问控制授权申请](../security/accesstoken-guidelines.md#配置文件权限声明)。 - > + > + > - 申请`ohos.permission.GET_BUNDLE_INFO_PRIVILEGED`权限，配置方式请参见[配置文件权限声明](../security/accesstoken-guidelines.md#配置文件权限声明)。 + > > - 接口为系统接口，三方应用不支持调用。 - + ```ts import UIAbility from '@ohos.app.ability.UIAbility'; export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { - let bundleName2 = "com.example.application"; - let moduleName2 = "module1"; + let bundleName2 = 'com.example.application'; + let moduleName2 = 'module1'; let context2 = this.context.createModuleContext(bundleName2, moduleName2); // ... } @@ -234,7 +235,7 @@ export default class EntryAbility extends UIAbility { export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { - let moduleName2 = "module1"; + let moduleName2 = 'module1'; let context2 = this.context.createModuleContext(moduleName2); // ... } @@ -306,7 +307,7 @@ export default class EntryAbility extends UIAbility { // 获取应用上下文 let applicationContext = this.context.getApplicationContext(); // 注册应用内生命周期回调 - this.lifecycleId = applicationContext.on("abilityLifecycle", abilityLifecycleCallback); + this.lifecycleId = applicationContext.on('abilityLifecycle', abilityLifecycleCallback); console.log(TAG, `register callback number: ${this.lifecycleId}`); } @@ -316,7 +317,7 @@ export default class EntryAbility extends UIAbility { // 获取应用上下文 let applicationContext = this.context.getApplicationContext(); // 取消应用内生命周期回调 - applicationContext.off("abilityLifecycle", this.lifecycleId); + applicationContext.off('abilityLifecycle', this.lifecycleId); } } ``` diff --git a/zh-cn/application-dev/application-models/data-share-via-want.md b/zh-cn/application-dev/application-models/data-share-via-want.md index 82173c8d066192ec738f515b191fa27494ffae1b..e23e11d2404c97a1cb7e9a57cd4aaf1487f51e75 100644 --- a/zh-cn/application-dev/application-models/data-share-via-want.md +++ b/zh-cn/application-dev/application-models/data-share-via-want.md @@ -2,20 +2,20 @@ 在应用使用场景中，用户经常需要将应用内的数据（如文字、图片等）分享至其他应用以供进一步处理。以分享PDF文件为例，本文将介绍如何使用Want来实现应用间的数据分享。 -数据分享需要使用两个UIAbility组件（分享方和被分享方）以及一个系统组件（应用选择框）。当分享方使用`startAbility()`方法发起数据分享时，系统会隐式匹配所有支持接收分享数据类型的应用，并将其展示给用户以供选择。用户选择应用后，系统将启动该应用来完成数据分享操作。 +数据分享需要使用两个UIAbility组件（分享方和被分享方）以及一个系统组件（应用分享框）。当分享方使用`startAbility()`方法发起数据分享时，系统会隐式匹配所有支持接收分享数据类型的应用，并将其展示给用户以供选择。用户选择应用后，系统将启动该应用来完成数据分享操作。 在本文中，我们将使用按钮的形式触发分享操作，但实际开发中并不限于此。本文主要介绍如何配置Want以实现数据分享的功能。 本文中涉及的两个Action为： -- `ohos.want.action.select`：用于启动应用选择框。 +- `ohos.want.action.select`：用于启动应用分享框。 - `ohos.want.action.sendData`：用于发送单个数据记录。此Action用于将数据传递给分享方应用。 ## 分享方 -为了实现数据分享功能，分享方需要先拉起应用选择框并将要分享的数据传递给被分享方应用。因此，在分享方的代码中需要嵌套使用两层Want。在第一层中，使用隐式Want和`ohos.want.action.select`的action来启动应用选择框。在第二层Want中，声明要传递给被分享方应用的数据。 +为了实现数据分享功能，分享方需要先拉起应用分享框并将要分享的数据传递给被分享方应用。因此，在分享方的代码中需要嵌套使用两层Want。在第一层中，使用隐式Want和`ohos.want.action.select`的action来启动应用分享框。在第二层Want中，声明要传递给被分享方应用的数据。 -具体来说，可以将要分享的数据放在自定义字段`parameters`中，然后将包含`ohos.want.action.sendData`的action和`parameters`字段的Want作为第二层Want传递给应用选择框。被分享方应用可以通过获取参数`parameters`来获取分享的数据。 +具体来说，可以将要分享的数据放在自定义字段`parameters`中，然后将包含`ohos.want.action.sendData`的action和`parameters`字段的Want作为第二层Want传递给应用分享框。被分享方应用可以通过获取参数`parameters`来获取分享的数据。 ```ts import common from '@ohos.app.ability.common'; @@ -34,15 +34,15 @@ function implicitStartAbility() { // which is intended to add info to application selector. parameters: { // The MIME type of pdf - "ability.picker.type": fileType, - "ability.picker.fileNames": [fileName], - "ability.picker.fileSizes": [fileSize], + 'ability.picker.type': fileType, + 'ability.picker.fileNames': [fileName], + 'ability.picker.fileSizes': [fileSize], // This a nested want which will be directly send to the user selected application. - "ability.want.params.INTENT": { - "action": "ohos.want.action.sendData", - "type": "application/pdf", - "parameters": { - "keyFd": { "type": "FD", "value": fileFd } + 'ability.want.params.INTENT': { + 'action': 'ohos.want.action.sendData', + 'type': 'application/pdf', + 'parameters': { + 'keyFd': { 'type': 'FD', 'value': fileFd } } } } diff --git a/zh-cn/application-dev/application-models/uiability-intra-device-interaction.md b/zh-cn/application-dev/application-models/uiability-intra-device-interaction.md index 298ec3f6bf415a2a5e036969df20452877a8c5b4..fafbe6935b781117851968f32e87ad339fcfc252 100644 --- a/zh-cn/application-dev/application-models/uiability-intra-device-interaction.md +++ b/zh-cn/application-dev/application-models/uiability-intra-device-interaction.md @@ -31,45 +31,52 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 1. 在EntryAbility中，通过调用[startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)方法启动UIAbility，[want](../reference/apis/js-apis-app-ability-want.md)为UIAbility实例启动的入口参数，其中bundleName为待启动应用的Bundle名称，abilityName为待启动的Ability名称，moduleName在待启动的UIAbility属于不同的Module时添加，parameters为自定义信息参数。示例中的context的获取方式请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)。 ```ts + let context = ...; // UIAbilityContext let wantInfo = { - deviceId: '', // deviceId为空表示本设备 - bundleName: 'com.example.myapplication', - abilityName: 'FuncAbility', - moduleName: 'module1', // moduleName非必选 - parameters: { // 自定义信息 - info: '来自EntryAbility Index页面', - }, + deviceId: '', // deviceId为空表示本设备 + bundleName: 'com.example.myapplication', + abilityName: 'FuncAbility', + moduleName: 'module1', // moduleName非必选 + parameters: { // 自定义信息 + info: '来自EntryAbility Index页面', + }, } // context为调用方UIAbility的UIAbilityContext - this.context.startAbility(wantInfo).then(() => { - // ... + context.startAbility(wantInfo).then(() => { + // ... }).catch((err) => { - // ... + // ... }) ``` - -2. 在FuncAbility的生命周期回调文件中接收EntryAbility传递过来的参数。 + +2. 在FuncAbility的[onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate)或者[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonnewwant)生命周期回调文件中接收EntryAbility传递过来的参数。 ```ts import UIAbility from '@ohos.app.ability.UIAbility'; import window from '@ohos.window'; export default class FuncAbility extends UIAbility { - onCreate(want, launchParam) { - // 接收调用方UIAbility传过来的参数 - let funcAbilityWant = want; - let info = funcAbilityWant?.parameters?.info; - // ... - } + onCreate(want, launchParam) { + // 接收调用方UIAbility传过来的参数 + let funcAbilityWant = want; + let info = funcAbilityWant?.parameters?.info; + // ... + } } ``` + > **说明：** + > + > 在被拉起的FuncAbility中，可以通过获取传递过来的`want`参数的`parameters`来获取拉起方UIAbility的PID、Bundle Name等信息。 + 3. 在FuncAbility业务完成之后，如需要停止当前UIAbility实例，在FuncAbility中通过调用[terminateSelf()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)方法实现。 ```ts + let context = ...; // UIAbilityContext + // context为需要停止的UIAbility实例的AbilityContext - this.context.terminateSelf((err) => { - // ... + context.terminateSelf((err) => { + // ... }); ``` @@ -87,60 +94,63 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 1. 在EntryAbility中，调用[startAbilityForResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口启动FuncAbility，异步回调中的data用于接收FuncAbility停止自身后返回给EntryAbility的信息。示例中的context的获取方式请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)。 ```ts + let context = ...; // UIAbilityContext let wantInfo = { - deviceId: '', // deviceId为空表示本设备 - bundleName: 'com.example.myapplication', - abilityName: 'FuncAbility', - moduleName: 'module1', // moduleName非必选 - parameters: { // 自定义信息 - info: '来自EntryAbility Index页面', - }, + deviceId: '', // deviceId为空表示本设备 + bundleName: 'com.example.myapplication', + abilityName: 'FuncAbility', + moduleName: 'module1', // moduleName非必选 + parameters: { // 自定义信息 + info: '来自EntryAbility Index页面', + }, } // context为调用方UIAbility的UIAbilityContext - this.context.startAbilityForResult(wantInfo).then((data) => { - // ... + context.startAbilityForResult(wantInfo).then((data) => { + // ... }).catch((err) => { - // ... + // ... }) ``` - + 2. 在FuncAbility停止自身时，需要调用[terminateSelfWithResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)方法，入参abilityResult为FuncAbility需要返回给EntryAbility的信息。 ```ts + let context = ...; // UIAbilityContext const RESULT_CODE: number = 1001; let abilityResult = { - resultCode: RESULT_CODE, - want: { - bundleName: 'com.example.myapplication', - abilityName: 'FuncAbility', - moduleName: 'module1', - parameters: { - info: '来自FuncAbility Index页面', - }, + resultCode: RESULT_CODE, + want: { + bundleName: 'com.example.myapplication', + abilityName: 'FuncAbility', + moduleName: 'module1', + parameters: { + info: '来自FuncAbility Index页面', }, + }, } // context为被调用方UIAbility的AbilityContext - this.context.terminateSelfWithResult(abilityResult, (err) => { - // ... + context.terminateSelfWithResult(abilityResult, (err) => { + // ... }); ``` - + 3. FuncAbility停止自身后，EntryAbility通过[startAbilityForResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)方法回调接收被FuncAbility返回的信息，RESULT_CODE需要与前面的数值保持一致。 ```ts + let context = ...; // UIAbilityContext const RESULT_CODE: number = 1001; // ... // context为调用方UIAbility的UIAbilityContext - this.context.startAbilityForResult(want).then((data) => { - if (data?.resultCode === RESULT_CODE) { - // 解析被调用方UIAbility返回的信息 - let info = data.want?.parameters?.info; - // ... - } - }).catch((err) => { + context.startAbilityForResult(wantInfo).then((data) => { + if (data?.resultCode === RESULT_CODE) { + // 解析被调用方UIAbility返回的信息 + let info = data.want?.parameters?.info; // ... + } + }).catch((err) => { + // ... }) ``` @@ -186,32 +196,35 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 2. 在调用方want参数中的entities和action需要被包含在待匹配UIAbility的skills配置的entities和actions中。系统匹配到符合entities和actions参数条件的UIAbility后，会弹出选择框展示匹配到的UIAbility实例列表供用户选择使用。示例中的context的获取方式请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)。 ```ts + let context = ...; // UIAbilityContext let wantInfo = { - deviceId: '', // deviceId为空表示本设备 - // uncomment line below if wish to implicitly query only in the specific bundle. - // bundleName: 'com.example.myapplication', - action: 'ohos.want.action.viewData', - // entities can be omitted. - entities: ['entity.system.default'], + deviceId: '', // deviceId为空表示本设备 + // uncomment line below if wish to implicitly query only in the specific bundle. + // bundleName: 'com.example.myapplication', + action: 'ohos.want.action.viewData', + // entities can be omitted. + entities: ['entity.system.default'], } // context为调用方UIAbility的UIAbilityContext - this.context.startAbility(wantInfo).then(() => { - // ... + context.startAbility(wantInfo).then(() => { + // ... }).catch((err) => { - // ... + // ... }) ``` - + 效果示意如下图所示，点击“打开PDF文档”时，会弹出选择框供用户选择。 ![](figures/uiability-intra-device-interaction.png) 3. 在文档应用使用完成之后，如需要停止当前UIAbility实例，通过调用[terminateSelf()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)方法实现。 ```ts + let context = ...; // UIAbilityContext + // context为需要停止的UIAbility实例的AbilityContext - this.context.terminateSelf((err) => { - // ... + context.terminateSelf((err) => { + // ... }); ``` @@ -249,47 +262,50 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 2. 调用方使用[startAbilityForResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)方法启动支付应用的UIAbility，在调用方want参数中的entities和action需要被包含在待匹配UIAbility的skills配置的entities和actions中。异步回调中的data用于后续接收支付UIAbility停止自身后返回给调用方的信息。系统匹配到符合entities和actions参数条件的UIAbility后，会弹出选择框展示匹配到的UIAbility实例列表供用户选择使用。 ```ts + let context = ...; // UIAbilityContext let wantInfo = { - deviceId: '', // deviceId为空表示本设备 - // uncomment line below if wish to implicitly query only in the specific bundle. - // bundleName: 'com.example.myapplication', - action: 'ohos.want.action.editData', - // entities can be omitted. - entities: ['entity.system.default'], + deviceId: '', // deviceId为空表示本设备 + // uncomment line below if wish to implicitly query only in the specific bundle. + // bundleName: 'com.example.myapplication', + action: 'ohos.want.action.editData', + // entities can be omitted. + entities: ['entity.system.default'], } // context为调用方UIAbility的UIAbilityContext - this.context.startAbilityForResult(wantInfo).then((data) => { - // ... + context.startAbilityForResult(wantInfo).then((data) => { + // ... }).catch((err) => { - // ... + // ... }) ``` - + 3. 在支付UIAbility完成支付之后，需要调用[terminateSelfWithResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)方法实现停止自身，并将abilityResult参数信息返回给调用方。 ```ts + let context = ...; // UIAbilityContext const RESULT_CODE: number = 1001; let abilityResult = { - resultCode: RESULT_CODE, - want: { - bundleName: 'com.example.myapplication', - abilityName: 'EntryAbility', - moduleName: 'entry', - parameters: { - payResult: 'OKay', - }, + resultCode: RESULT_CODE, + want: { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', + moduleName: 'entry', + parameters: { + payResult: 'OKay', }, + }, } // context为被调用方UIAbility的AbilityContext - this.context.terminateSelfWithResult(abilityResult, (err) => { - // ... + context.terminateSelfWithResult(abilityResult, (err) => { + // ... }); ``` - + 4. 在调用方[startAbilityForResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)方法回调中接收支付应用返回的信息，RESULT_CODE需要与前面[terminateSelfWithResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)返回的数值保持一致。 ```ts + let context = ...; // UIAbilityContext const RESULT_CODE: number = 1001; let want = { @@ -297,14 +313,14 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 }; // context为调用方UIAbility的UIAbilityContext - this.context.startAbilityForResult(want).then((data) => { - if (data?.resultCode === RESULT_CODE) { - // 解析被调用方UIAbility返回的信息 - let payResult = data.want?.parameters?.payResult; - // ... - } - }).catch((err) => { + context.startAbilityForResult(want).then((data) => { + if (data?.resultCode === RESULT_CODE) { + // 解析被调用方UIAbility返回的信息 + let payResult = data.want?.parameters?.payResult; // ... + } + }).catch((err) => { + // ... }) ``` @@ -335,6 +351,7 @@ UIAbility是系统调度的最小单元。在设备内的功能模块之间跳 ```ts import AbilityConstant from '@ohos.app.ability.AbilityConstant'; +let context = ...; // UIAbilityContext let wantInfo = { deviceId: '', // deviceId为空表示本设备 bundleName: 'com.example.myapplication', @@ -348,7 +365,7 @@ let options = { windowMode: AbilityConstant.WindowMode.WINDOW_MODE_FLOATING } // context为调用方UIAbility的UIAbilityContext -this.context.startAbility(wantInfo, options).then(() => { +context.startAbility(wantInfo, options).then(() => { // ... }).catch((err) => { // ... @@ -369,6 +386,7 @@ this.context.startAbility(wantInfo, options).then(() => { ```ts +let context = ...; // UIAbilityContext let wantInfo = { deviceId: '', // deviceId为空表示本设备 bundleName: 'com.example.myapplication', @@ -379,7 +397,7 @@ let wantInfo = { }, } // context为调用方UIAbility的UIAbilityContext -this.context.startAbility(wantInfo).then(() => { +context.startAbility(wantInfo).then(() => { // ... }).catch((err) => { // ... @@ -397,25 +415,25 @@ import UIAbility from '@ohos.app.ability.UIAbility' import Window from '@ohos.window' export default class FuncAbility extends UIAbility { - funcAbilityWant; - - onCreate(want, launchParam) { - // 接收调用方UIAbility传过来的参数 - this.funcAbilityWant = want; - } - - onWindowStageCreate(windowStage: Window.WindowStage) { - // Main window is created, set main page for this ability - let url = 'pages/Index'; - if (this.funcAbilityWant?.parameters?.router) { - if (this.funcAbilityWant.parameters.router === 'funA') { - url = 'pages/Second'; - } - } - windowStage.loadContent(url, (err, data) => { - // ... - }); + funcAbilityWant; + + onCreate(want, launchParam) { + // 接收调用方UIAbility传过来的参数 + this.funcAbilityWant = want; + } + + onWindowStageCreate(windowStage: Window.WindowStage) { + // Main window is created, set main page for this ability + let url = 'pages/Index'; + if (this.funcAbilityWant?.parameters?.router) { + if (this.funcAbilityWant.parameters.router === 'funA') { + url = 'pages/Second'; + } } + windowStage.loadContent(url, (err, data) => { + // ... + }); + } } ``` @@ -434,11 +452,11 @@ export default class FuncAbility extends UIAbility { import UIAbility from '@ohos.app.ability.UIAbility' export default class FuncAbility extends UIAbility { - onNewWant(want, launchParam) { - // 接收调用方UIAbility传过来的参数 - globalThis.funcAbilityWant = want; - // ... - } + onNewWant(want, launchParam) { + // 接收调用方UIAbility传过来的参数 + globalThis.funcAbilityWant = want; + // ... + } } ``` @@ -468,12 +486,12 @@ export default class FuncAbility extends UIAbility { ``` > **说明：** -> 当被调用方[Ability的启动模式](uiability-launch-type.md)设置为standard启动模式时，每次启动都会创建一个新的实例，那么[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)回调就不会被用到。 +> 当被调用方[UIAbility组件启动模式](uiability-launch-type.md)设置为standard启动模式时，每次启动都会创建一个新的实例，那么[onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)回调就不会被用到。 ## 通过Call调用实现UIAbility交互（仅对系统应用开放） -Call调用是UIAbility能力的扩展，它为UIAbility提供一种能够被外部调用并与外部进行通信的能力。Call调用支持前台与后台两种启动方式，使UIAbility既能被拉起到前台展示UI，也可以在后台被创建并运行。Call调用在调用方与被调用方间建立了IPC通信，因此应用开发者可通过Call调用实现不同Ability之间的数据共享。 +Call调用是UIAbility能力的扩展，它为UIAbility提供一种能够被外部调用并与外部进行通信的能力。Call调用支持前台与后台两种启动方式，使UIAbility既能被拉起到前台展示UI，也可以在后台被创建并运行。Call调用在调用方与被调用方间建立了IPC通信，因此应用开发者可通过Call调用实现不同UIAbility之间的数据共享。 Call调用的核心接口是startAbilityByCall方法，与startAbility接口的不同之处在于： @@ -541,32 +559,14 @@ Call功能主要接口如下表所示。具体的API详见[接口文档](../refe 在Callee被调用端，需要实现指定方法的数据接收回调函数、数据的序列化及反序列化方法。在需要接收数据期间，通过on接口注册监听，无需接收数据时通过off接口解除监听。 -1. 配置Ability的启动模式。 - 配置module.json5，将CalleeAbility配置为单实例"singleton"。 - - | Json字段 | 字段说明 | - | -------- | -------- | - | "launchType" | Ability的启动模式，设置为"singleton"类型。 | - - Ability配置标签示例如下： - +1. 配置UIAbility的启动模式。 + + 例如将CalleeAbility配置为单实例模式`singleton`，配置方式请参见[UIAbility组件启动模式](uiability-launch-type.md)。 - ```json - "abilities":[{ - "name": ".CalleeAbility", - "srcEntrance": "./ets/CalleeAbility/CalleeAbility.ts", - "launchType": "singleton", - "description": "$string:CalleeAbility_desc", - "icon": "$media:icon", - "label": "$string:CalleeAbility_label", - "visible": true - }] - ``` - 2. 导入UIAbility模块。 ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; ``` 3. 定义约定的序列化数据。 @@ -575,30 +575,30 @@ Call功能主要接口如下表所示。具体的API详见[接口文档](../refe ```ts export default class MyParcelable { - num: number = 0 - str: string = "" + num: number = 0; + str: string = ''; - constructor(num, string) { - this.num = num - this.str = string - } + constructor(num, string) { + this.num = num; + this.str = string; + } - marshalling(messageSequence) { - messageSequence.writeInt(this.num) - messageSequence.writeString(this.str) - return true - } + marshalling(messageSequence) { + messageSequence.writeInt(this.num); + messageSequence.writeString(this.str); + return true + } - unmarshalling(messageSequence) { - this.num = messageSequence.readInt() - this.str = messageSequence.readString() - return true - } + unmarshalling(messageSequence) { + this.num = messageSequence.readInt(); + this.str = messageSequence.readString(); + return true; + } } ``` 4. 实现Callee.on监听及Callee.off解除监听。 - 被调用端Callee的监听函数注册时机，取决于应用开发者。注册监听之前的数据不会被处理，取消监听之后的数据不会被处理。如下示例在Ability的onCreate注册'MSG_SEND_METHOD'监听，在onDestroy取消监听，收到序列化数据后作相应处理并返回，应用开发者根据实际需要做相应处理。具体示例代码如下： + 被调用端Callee的监听函数注册时机，取决于应用开发者。注册监听之前的数据不会被处理，取消监听之后的数据不会被处理。如下示例在UIAbility的onCreate注册'MSG_SEND_METHOD'监听，在onDestroy取消监听，收到序列化数据后作相应处理并返回，应用开发者根据实际需要做相应处理。具体示例代码如下： ```ts @@ -606,34 +606,34 @@ Call功能主要接口如下表所示。具体的API详见[接口文档](../refe const MSG_SEND_METHOD: string = 'CallSendMsg'; function sendMsgCallback(data) { - console.info('CalleeSortFunc called'); + console.info('CalleeSortFunc called'); - // 获取Caller发送的序列化数据 - let receivedData = new MyParcelable(0, ''); - data.readParcelable(receivedData); - console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`); + // 获取Caller发送的序列化数据 + let receivedData = new MyParcelable(0, ''); + data.readParcelable(receivedData); + console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`); - // 作相应处理 - // 返回序列化数据result给Caller - return new MyParcelable(receivedData.num + 1, `send ${receivedData.str} succeed`); + // 作相应处理 + // 返回序列化数据result给Caller + return new MyParcelable(receivedData.num + 1, `send ${receivedData.str} succeed`); } - export default class CalleeAbility extends Ability { - onCreate(want, launchParam) { - try { - this.callee.on(MSG_SEND_METHOD, sendMsgCallback); - } catch (error) { - console.info(`${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`); - } + export default class CalleeAbility extends UIAbility { + onCreate(want, launchParam) { + try { + this.callee.on(MSG_SEND_METHOD, sendMsgCallback); + } catch (error) { + console.info(`${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`); } + } - onDestroy() { - try { - this.callee.off(MSG_SEND_METHOD); - } catch (error) { - console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`); - } + onDestroy() { + try { + this.callee.off(MSG_SEND_METHOD); + } catch (error) { + console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`); } + } } ``` @@ -643,40 +643,40 @@ Call功能主要接口如下表所示。具体的API详见[接口文档](../refe 1. 导入UIAbility模块。 ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; ``` 2. 获取Caller通信接口。 - Ability的context属性实现了startAbilityByCall方法，用于获取指定通用组件的Caller通信接口。如下示例通过this.context获取Ability实例的context属性，使用startAbilityByCall拉起Callee被调用端并获取Caller通信接口，注册Caller的onRelease监听。应用开发者根据实际需要做相应处理。 + UIAbilityContext属性实现了startAbilityByCall方法，用于获取指定通用组件的Caller通信接口。如下示例通过this.context获取UIAbility实例的context属性，使用startAbilityByCall拉起Callee被调用端并获取Caller通信接口，注册Caller的onRelease监听。应用开发者根据实际需要做相应处理。 ```ts // 注册caller的release监听 private regOnRelease(caller) { - try { - caller.on("release", (msg) => { - console.info(`caller onRelease is called ${msg}`); - }) - console.info('caller register OnRelease succeed'); - } catch (error) { - console.info(`caller register OnRelease failed with ${error}`); - } + try { + caller.on('release', (msg) => { + console.info(`caller onRelease is called ${msg}`); + }) + console.info('caller register OnRelease succeed'); + } catch (error) { + console.info(`caller register OnRelease failed with ${error}`); + } } async onButtonGetCaller() { - try { - this.caller = await context.startAbilityByCall({ - bundleName: 'com.samples.CallApplication', - abilityName: 'CalleeAbility' - }) - if (this.caller === undefined) { - console.info('get caller failed') - return - } - console.info('get caller success') - this.regOnRelease(this.caller) - } catch (error) { - console.info(`get caller failed with ${error}`) + try { + this.caller = await context.startAbilityByCall({ + bundleName: 'com.samples.CallApplication', + abilityName: 'CalleeAbility' + }) + if (this.caller === undefined) { + console.info('get caller failed') + return } + console.info('get caller success') + this.regOnRelease(this.caller) + } catch (error) { + console.info(`get caller failed with ${error}`) + } } ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-want.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-want.md index 6b938dfa1c2dfa3ff782f61f09f1763280a3fc71..ba737871aa6fb6434745828b4c551e6cf9cdae51 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-want.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-want.md @@ -26,7 +26,7 @@ import Want from '@ohos.app.ability.Want'; | entities | Array\ | 否 | 表示目标Ability额外的类别信息（如：浏览器、视频播放器）。在隐式Want中是对action字段的补充。在隐式Want中，您可以定义该字段，来过滤匹配Ability类型。 | | uri | string | 否 | 表示携带的数据，一般配合type使用，指明待处理的数据类型。如果在Want中指定了uri，则Want将匹配指定的Uri信息，包括`scheme`、`schemeSpecificPart`、`authority`和`path`信息。 | | type | string | 否 | 表示MIME type类型描述，打开文件的类型，主要用于文管打开文件。比如：'text/xml' 、 'image/*'等，MIME定义请参见https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com。 | -| parameters | {[key: string]: any} | 否 | 表示WantParams描述，由开发者自行决定传入的键值对。默认会携带以下key值：
- ohos.aafwk.callerPid：表示拉起方的pid。
- ohos.aafwk.param.callerToken：表示拉起方的token。
- ohos.aafwk.param.callerUid：表示[BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1)中的uid，应用包里应用程序的uid。
- component.startup.newRules：表示是否启用新的管控规则。
- moduleName：表示拉起方的模块名，该字段的值即使定义成其他字符串，在传递到另一端时会被修改为正确的值。
- ohos.dlp.params.sandbox：表示dlp文件才会有。 | +| parameters | {[key: string]: any} | 否 | 表示WantParams描述，由开发者自行决定传入的键值对。默认会携带以下key值：
- ohos.aafwk.callerPid：表示拉起方的pid。
- ohos.aafwk.param.callerBundleName：表示拉起方的Bundle Name。
- ohos.aafwk.param.callerToken：表示拉起方的token。
- ohos.aafwk.param.callerUid：表示[BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1)中的uid，应用包里应用程序的uid。
- component.startup.newRules：表示是否启用新的管控规则。
- moduleName：表示拉起方的模块名，该字段的值即使定义成其他字符串，在传递到另一端时会被修改为正确的值。
- ohos.dlp.params.sandbox：表示dlp文件才会有。 | | [flags](js-apis-ability-wantConstant.md#wantconstantflags) | number | 否 | 表示处理Want的方式。默认传数字。
例如通过wantConstant.Flags.FLAG_ABILITY_CONTINUATION表示是否以设备间迁移方式启动Ability。 | **示例：** @@ -34,6 +34,7 @@ import Want from '@ohos.app.ability.Want'; - 基础用法：在UIAbility对象中调用，示例中的context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 ```ts + let context = ...; // UIAbilityContext let want = { 'deviceId': '', // deviceId为空表示本设备 'bundleName': 'com.example.myapplication', @@ -41,16 +42,17 @@ import Want from '@ohos.app.ability.Want'; 'moduleName': 'entry' // moduleName非必选 }; - this.context.startAbility(want, (err) => { + context.startAbility(want, (err) => { // 显式拉起Ability，通过bundleName、abilityName和moduleName可以唯一确定一个Ability - console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); + console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); }); ``` -- 通过自定字段传递数据，以下为当前支持类型（在UIAbility对象中调用，示例中的context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)）。 +- 目前支持的数据类型有：字符串、数字、布尔、对象、数组和文件描述符等。 * 字符串（String） ```ts + let context = ...; // UIAbilityContext let want = { bundleName: 'com.example.myapplication', abilityName: 'FuncAbility', @@ -59,12 +61,13 @@ import Want from '@ohos.app.ability.Want'; }, }; - this.context.startAbility(want, (err) => { - console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); + context.startAbility(want, (err) => { + console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); }); ``` * 数字（Number） ```ts + let context = ...; // UIAbilityContext let want = { bundleName: 'com.example.myapplication', abilityName: 'FuncAbility', @@ -74,12 +77,13 @@ import Want from '@ohos.app.ability.Want'; }, }; - this.context.startAbility(want, (err) => { - console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); + context.startAbility(want, (err) => { + console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); }); ``` * 布尔（Boolean） ```ts + let context = ...; // UIAbilityContext let want = { bundleName: 'com.example.myapplication', abilityName: 'FuncAbility', @@ -88,12 +92,13 @@ import Want from '@ohos.app.ability.Want'; }, }; - this.context.startAbility(want, (err) => { - console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); + context.startAbility(want, (err) => { + console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); }); ``` * 对象（Object） ```ts + let context = ...; // UIAbilityContext let want = { bundleName: 'com.example.myapplication', abilityName: 'FuncAbility', @@ -107,12 +112,13 @@ import Want from '@ohos.app.ability.Want'; }, }; - this.context.startAbility(want, (err) => { - console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); + context.startAbility(want, (err) => { + console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); }); ``` * 数组（Array） ```ts + let context = ...; // UIAbilityContext let want = { bundleName: 'com.example.myapplication', abilityName: 'FuncAbility', @@ -124,19 +130,21 @@ import Want from '@ohos.app.ability.Want'; }, }; - this.context.startAbility(want, (err) => { - console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); + context.startAbility(want, (err) => { + console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); }); ``` * 文件描述符（FD） ```ts import fs from '@ohos.file.fs'; + let context = ...; // UIAbilityContext + let fd; try { - fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd; - } catch(e) { - console.error('openSync fail: ${JSON.stringify(e)}'); + fd = fs.openSync('/data/storage/el2/base/haps/pic.png').fd; + } catch(err) { + console.error(`Failed to openSync. Code: ${err.code}, message: ${err.message}`); } let want = { 'deviceId': '', // deviceId为空表示本设备 @@ -148,8 +156,7 @@ import Want from '@ohos.app.ability.Want'; } }; - this.context.startAbility(want, (err) => { - console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); + context.startAbility(want, (err) => { + console.error(`Failed to startAbility. Code: ${err.code}, message: ${err.message}`); }); ``` -