提交 8b733dae 编写于 作者: zyjhandsome's avatar zyjhandsome

优化部分Want章节内容和Want API的内容。

Signed-off-by: zyjhandsome's avatarzyjhandsome <zyjhandsome@126.com>
上级 7da6f882
# 使用显式Want启动Ability
在应用使用场景中,当用户点击某个按钮时,应用经常需要拉起指定UIAbility组件来完成某些特定任务。下面介绍如何通过显式Want拉起应用内一个指定UIAbility组件。
## 开发步骤
1. Stage模型工程内,创建一个Ability(此示例内命名为callerAbility)与相应Page(此示例中名为Index.ets),并在callerAbility.ts文件内的onWindowStageCreate函数内通过windowStage.loadContent()方法将两者绑定。
```ts
// ...
// callerAbility.ts
onWindowStageCreate(windowStage) {
// Main window is created, set main page for this ability
console.info('[Demo] EntryAbility onWindowStageCreate')
// Bind callerAbility with a paged named Index
windowStage.loadContent('pages/Index')
}
// ...
```
2. 同上方法再创建一个Ability,此示例内命名为“calleeAbility”。
3. 在callerAbility的“Index.ets”页面内新增一个按钮。
```ts
// ...
build() {
Row() {
Column() {
Text('hello')
.fontSize(50)
.fontWeight(FontWeight.Bold)
// A new button with will call explicitStartAbility() when clicked.
Button("CLICKME")
.onClick(this.explicitStartAbility) // explicitStartAbility见下面示例代码
// ...
}
.width('100%')
}
.height('100%')
}
// ...
```
4. 补充相对应的onClick方法,并使用**显式Want**在方法内启动calleeAbility。bundleName字段可在工程AppScope&gt;app.json5文件内获取;abilityName可在对应模块内的“yourModuleName &gt; src &gt; main &gt; module.json5”文件查看。
```ts
import common from '@ohos.app.ability.common';
// ...
async explicitStartAbility() {
try {
// Explicit want with abilityName specified.
let want = {
deviceId: "",
bundleName: "com.example.myapplication",
abilityName: "calleeAbility"
};
let context = getContext(this) as common.UIAbilityContext;
await context.startAbility(want);
console.info(`explicit start ability succeed`);
} catch (error) {
console.info(`explicit start ability failed with ${error.code}`);
}
}
// ...
```
5. 至此,当您点击CLICKME按钮时,应看到页面的跳转。
<img src="figures/startAbilityWtExplicitWant.PNG" alt="startAbilityWtExplicitWant" style="zoom: 80%;" />
在应用使用场景中,当用户在应用内点击某个按钮时,经常需要拉起指定UIAbility组件来完成某些特定任务。在启动UIAbility时,指定了abilityName和bundleName参数,可以使用显示Want方式启动UIAbility。显示Want的使用请参见[启动应用内的UIAbility](uiability-intra-device-interaction.md#启动应用内的uiability)
......@@ -41,7 +41,7 @@
## 开发步骤
1. 在自定义函数implicitStartAbility内使用**隐式Want**启动Ability。
```ts
async implicitStartAbility() {
try {
......@@ -71,12 +71,12 @@
匹配过程如下:
1. want内action不为空,且被skills内action包括,匹配成功。
2. want内entities不为空,且被skills内entities包括,匹配成功。
3. skills内uris拼接为https://www.test.com:8080/query\* (\*为通配符)包含want内uri,匹配成功。
3. skills内uris拼接为`https://www.test.com:8080/query*` (\*为通配符)包含want内uri,匹配成功。
4. want内type不为空,且被skills内type包含,匹配成功。
2. 当有多个匹配应用时,会被应用选择器展示给用户进行选择。
<img src="figures/stage-want1.png" alt="stage-want1" style="zoom:80%;" />
2. 当有多个匹配应用时,会被应用选择器展示给用户进行选择。
<img src="figures/stage-want1.png" alt="stage-want1" style="zoom:80%;" />
# 常见action与entities
**[action](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction)**:表示调用方要执行的通用操作(如查看、分享、应用详情)。在隐式Want中,您可定义该字段,配合uri或parameters来表示对数据要执行的操作。如打开,查看该uri数据。例如,当uri为一段网址,action为ohos.want.action.viewData则表示匹配可查看该网址的Ability。在Want内声明action字段表示希望被调用方应用支持声明的操作。在被调用方应用配置文件skills字段内声明actions表示该应用支持声明操作。
......@@ -15,7 +14,6 @@
- ACTION_VIEW_MULTIPLE_DATA:发送多个数据记录的操作。
**[entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity)**:表示目标Ability的类别信息(如浏览器、视频播放器),在隐式Want中是对action的补充。在隐式Want中,开发者可定义该字段,来过滤匹配应用的类别,例如必须是浏览器。在Want内声明entities字段表示希望被调用方应用属于声明的类别。在被调用方应用配置文件skills字段内声明entites表示该应用支持的类别。
......
......@@ -64,7 +64,7 @@
- "ability.picker.fileSizes":应用选择器根据该字段展示文件大小。以字节为单位。
- "ability.picker.fileNames"与"ability.picker.fileSizes"为数组,其有一一对应关系。
例如:当"ability.picker.type"为“application/pdf”,"ability.picker.fileNames"为“["接口文档.pdf"]”,"ability.picker.fileSizes"为“[350 \* 1024]”时,应用选择器将以下形式展示。
例如:当"ability.picker.type"为“application/pdf”,"ability.picker.fileNames"为“["接口文档.pdf"]”,"ability.picker.fileSizes"为“[350 \* 1024]”时,应用选择器将以下形式展示。
<img src="figures/stage-want2.png" alt="stage-want2" style="zoom:50%;" />
示例代码中“ability.want.params.INTENT”字段是一个嵌套Want,内部所含action、type等字段将由应用选择器进行隐式匹配,具体隐式匹配规则可参考[隐式Want匹配原理详解](explicit-implicit-want-mappings.md#隐式want匹配原理详解)。当用户选择具体应用后,“ability.want.params.INTENT”字段的嵌套Want将传递至所选应用。
......
......@@ -49,7 +49,7 @@
### want参数的action匹配规则
将调用方传入的want参数的action与待匹配Ability的skills配置中的actions进行匹配。
将调用方传入的want参数的[action](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction)与待匹配Ability的skills配置中的actions进行匹配。
- 调用方传入的want参数的action不为空,待匹配Ability的skills配置中的actions为空,则action匹配失败。
......@@ -64,7 +64,7 @@
### want参数的entities匹配规则
将调用方传入的want参数的entities与待匹配Ability的skills配置中的entities进行匹配。
将调用方传入的want参数的[entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity)与待匹配Ability的skills配置中的entities进行匹配。
- 调用方传入的want参数的entities为空,待匹配Ability的skills配置中的entities不为空,则entities匹配成功。
......@@ -84,7 +84,7 @@
调用方传入的want参数中设置uri和type参数发起组件启动请求,系统会遍历当前系统已安装的组件列表,并逐个匹配待匹配Ability的skills配置中的uris数组,如果待匹配Ability的skills配置中的uris数组中只要有一个可以匹配调用方传入的want参数中设置的uri和type即为匹配成功。
**图3** want参数中uri和type皆不为空时的匹配规则
**图3** want参数中uri和type皆不为空时的匹配规则
<img src="figures/want-uri-type1.png" alt="want-uri-type1" style="zoom: 80%;" />
实际应用中,uri和type共存在四种情况,下面将讲解四种情况的具体匹配规则:
......@@ -110,7 +110,7 @@
下图为了简化描述,称want中传入的uri为w_uri,称want中传入的type为w_type, 待匹配Ability的skills配置中uris为s_uris,其中每个元素为s_uri;按自上而下顺序匹配。
**图4** want参数中uri和type的具体匹配规则
**图4** want参数中uri和type的具体匹配规则
<img src="figures/want-uri-type2.png" alt="want-uri-type2" style="zoom:80%;" />
......@@ -133,24 +133,24 @@
> **说明:**
> 待匹配Ability的skills配置的uris中scheme、host、port、path、pathStartWith和pathRegex属性拼接,如果依次声明了path、pathStartWith和pathRegex属性时,uris将分别拼接为如下三种表达式:
>
> - **全路径表达式**:scheme://host:port/path
> - **全路径表达式**:`scheme://host:port/path`
>
> - **前缀表达式**:scheme://host:port/pathStartWith
> - **前缀表达式**:`scheme://host:port/pathStartWith`
>
> - **正则表达式**:scheme://host:port/pathRegex
> - **正则表达式**:`scheme://host:port/pathRegex`
### type匹配规则
> **说明:**
> 此小节所述的type匹配规则的适用性需建立在want参数内type不为空的基础上。当want参数内type为空时请参[want参数的uri和type匹配规则](#want参数的uri和type匹配规则)。
> 此小节所述的type匹配规则的适用性需建立在want参数内type不为空的基础上。当want参数内type为空时请参[want参数的uri和type匹配规则](#want参数的uri和type匹配规则)。
这里为了简化描述,称want中传入的uri为w_type,待匹配Ability的skills数组中uris的type数据为s_type,具体的匹配规则如下:
- 如果s_type为空,则匹配失败。
- 如果s_type或者w_type为通配符"\*/\*",则匹配成功。
- 如果s_type或者w_type为通配符`*/*`,则匹配成功。
- 如果s_type最后一个字符为通配符'\*',如"prefixType/\*",则当w_type包含"prefixType/"时匹配成功,否则匹配失败。
- 如果s_type最后一个字符为通配符`*`,如`prefixType/*`,则当w_type包含`prefixType/`时匹配成功,否则匹配失败。
- 如果w_type最后一个字符为通配符'\*',如"prefixType/\*",则当s_type包含"prefixType/"时匹配成功,否则匹配失败。
- 如果w_type最后一个字符为通配符`*`,如`prefixType/*`,则当s_type包含`prefixType/`时匹配成功,否则匹配失败。
......@@ -12,7 +12,7 @@
## Want的类型
- **显式Want**:在启动Ability时指定了abilityName和bundleName的Want称为显式Want。
当有明确处理请求的对象时,通过提供目标Ability所在应用的Bundle名称信息(bundleName),并在Want内指定abilityName便可启动目标Ability。显式Want通常用于在当前应用开发中启动某个已知的Ability。参数说明参见[Want参数说明](want-overview.md#Want参数说明)
当有明确处理请求的对象时,通过提供目标Ability所在应用的Bundle名称信息(bundleName),并在Want内指定abilityName便可启动目标Ability。显式Want通常用于在当前应用开发中启动某个已知的Ability。
```ts
let wantInfo = {
......@@ -22,7 +22,7 @@
}
```
- **隐式Want**:在启动UIAbility时未指定abilityName的Want称为隐式Want。
- **隐式Want**:在启动Ability时未指定abilityName的Want称为隐式Want。
当请求处理的对象不明确时,希望在当前应用中使用其他应用提供的某个能力(通过[skills标签](../quick-start/module-configuration-file.md#skills标签)定义),而不关心提供该能力的具体应用,可以使用隐式Want。例如使用隐式Want描述需要打开一个链接的请求,而不关心通过具体哪个应用打开,系统将匹配声明支持该请求的所有应用。
......@@ -47,18 +47,3 @@
> - 调用方传入的want参数中不带有abilityName和bundleName,则不允许通过隐式Want启动所有应用的ServiceExtensionAbility。
>
> - 调用方传入的want参数中带有bundleName,则允许使用startServiceExtensionAbility()方法隐式Want启动ServiceExtensionAbility,默认返回优先级最高的ServiceExtensionAbility,如果优先级相同,返回第一个。
## Want参数说明
| 名称 | 读写属性 | 类型 | 必填 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| deviceId | 只读 | string | 否 | 表示目标Ability所在设备ID。如果未设置该字段,则表明本设备。 |
| bundleName | 只读 | string | 否 | 表示目标Ability所在应用名称。 |
| moduleName | 只读 | string | 否 | 表示目标Ability所属的模块名称。 |
| abilityName | 只读 | string | 否 | 表示目标Ability名称。如果未设置该字段,则该Want为隐式。如果在Want中同时指定了bundleName,moduleName和abilityName,则Want可以直接匹配到指定的Ability。 |
| uri | 只读 | string | 否 | 表示携带的数据,一般配合type使用,指明待处理的数据类型。如果在Want中指定了uri,则Want将匹配指定的Uri信息,包括scheme,&nbsp;schemeSpecificPart,&nbsp;authority和path信息。 |
| type | 只读 | string | 否 | 表示携带数据类型,使用[MIME类型](https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com%E3%80%82)规范。例如:"text/plain"、"image/\*"等。 |
| [action](../reference/apis/js-apis-ability-wantConstant.md) | 只读 | string | 否 | 表示要执行的通用操作(如:查看、分享、应用详情)。在隐式Want中,您可定义该字段,配合uri或parameters来表示对数据要执行的操作。如打开,查看该uri数据。例如,当uri为一段网址,action为ohos.want.action.viewData则表示匹配可查看该网址的Ability。 |
| [entities](../reference/apis/js-apis-ability-wantConstant.md) | 只读 | Array&lt;string&gt; | 否 | 表示目标Ability额外的类别信息(如:浏览器,视频播放器),在隐式Want中是对action的补充。在隐式Want中,您可定义该字段,来过滤匹配UIAbility类别,如必须是浏览器。例如,在action字段的举例中,可存在多个应用声明了支持查看网址的操作,其中有应用为普通社交应用,有的为浏览器应用,您可通过entity.system.browsable过滤掉非浏览器的其他应用。 |
| [flags](../reference/apis/js-apis-ability-wantConstant.md#wantconstantflags) | 只读 | number | 否 | 表示处理Want的方式。例如通过wantConstant.Flags.FLAG_ABILITY_CONTINUATION表示是否以设备间迁移方式启动Ability。 |
| parameters | 只读 | {[key:&nbsp;string]:&nbsp;any} | 否 | 此参数用于传递自定义数据,通过用户自定义的键值对进行数据填充,具体支持的数据类型如[Want&nbsp;API](../reference/apis/js-apis-app-ability-want.md)所示。 |
# @ohos.app.ability.Want (Want)
Want是对象间信息传递的载体, 可以用于应用组件间的信息传递。 Want的使用场景之一是作为startAbility的参数, 其包含了指定的启动目标, 以及启动时需携带的相关数据, 如bundleName和abilityName字段分别指明目标Ability所在应用的包名以及对应包内的Ability名称。当Ability A需要启动Ability B并传入一些数据时, 可使用Want作为载体将这些数据传递给Ability B。
Want是对象间信息传递的载体, 可以用于应用组件间的信息传递。 Want的使用场景之一是作为startAbility的参数, 其包含了指定的启动目标, 以及启动时需携带的相关数据, 如bundleName和abilityName字段分别指明目标Ability所在应用的包名以及对应包内的Ability名称。当UIAbilityA需要启动UIAbilityB并传入一些数据时, 可使用Want作为载体将这些数据传递给UIAbilityB。
> **说明:**
>
......@@ -19,25 +19,25 @@ import Want from '@ohos.app.ability.Want';
| 名称 | 类型 | 必填 | 说明 |
| ----------- | -------------------- | ---- | ------------------------------------------------------------ |
| deviceId | string | 否 | 表示运行指定Ability的设备ID。如果未设置该字段,则表明指定本设备。 |
| bundleName | string | 否 | 表示Bundle名称。 |
| abilityName | string | 否 | 表示待启动的Ability名称。如果在Want中该字段同时指定了BundleName和AbilityName,则Want可以直接匹配到指定的Ability。AbilityName需要在一个应用的范围内保证唯一。 |
| uri | string | 否 | 表示Uri描述。如果在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。 |
| flags | number | 否 | 表示处理Want的方式。默认传数字,具体参考:[flags说明](js-apis-app-ability-wantConstant.md#wantConstant.Flags)。 |
| action | string | 否 | 表示要执行的通用操作(如:查看、分享、应用详情)。在隐式Want中,您可以定义该字段,配合uri或parameters来表示对数据要执行的操作。具体参考:[action说明](js-apis-app-ability-wantConstant.md#wantConstant.Action)。隐式Want定义及匹配规则参考:[显式Want与隐式Want匹配规则](application-models/explicit-implicit-want-mappings.md) |
| parameters | {[key: string]: any} | 否 | 表示WantParams描述,由开发者自行决定传入的键值对。默认会携带以下key值:<br>ohos.aafwk.callerPid 表示拉起方的pid。<br>ohos.aafwk.param.callerToken 表示拉起方的token。<br>ohos.aafwk.param.callerUid 表示[bundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1)中的uid,应用包里应用程序的uid。 |
| entities | Array\<string> | 否 | 表示目标Ability额外的类别信息(如:浏览器、视频播放器)。在隐式Want中是对action字段的补充。在隐式Want中,您可以定义该字段,来过滤匹配Ability类型。具体参考:[entity说明](js-apis-app-ability-wantConstant.md#wantConstant.Entity) |
| moduleName | string | 否 | 表示待启动的Ability所属的模块(module)。 |
| bundleName | string | 否 | 表示待启动Ability所在的应用Bundle名称。 |
| moduleName | string | 否 | 表示待启动的Ability所属的模块名称。 |
| abilityName | string | 否 | 表示待启动Ability名称。如果在Want中该字段同时指定了BundleName和AbilityName,则Want可以直接匹配到指定的Ability。AbilityName需要在一个应用的范围内保证唯一。 |
| [action](js-apis-app-ability-wantConstant.md#wantConstant.Action) | string | 否 | 表示要执行的通用操作(如:查看、分享、应用详情)。在隐式Want中,您可以定义该字段,配合uri或parameters来表示对数据要执行的操作。隐式Want定义及匹配规则请参见[显式Want与隐式Want匹配规则](application-models/explicit-implicit-want-mappings.md) |
| [entities](js-apis-app-ability-wantConstant.md#wantConstant.Entity) | Array\<string> | 否 | 表示目标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值:<br />- ohos.aafwk.callerPid:表示拉起方的pid。<br />- ohos.aafwk.param.callerToken:表示拉起方的token。<br />- ohos.aafwk.param.callerUid:表示[BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1)中的uid,应用包里应用程序的uid。 |
| [flags](js-apis-ability-wantConstant.md#wantconstantflags) | number | 否 | 表示处理Want的方式。默认传数字。<br />例如通过wantConstant.Flags.FLAG_ABILITY_CONTINUATION表示是否以设备间迁移方式启动Ability。 |
**示例:**
- 基础用法(在UIAbility对象中调用,其中示例中的context为UIAbility的上下文对象)
- 基础用法(在UIAbility对象中调用,其中示例中的context为UIAbility的上下文对象)。
```ts
let want = {
"deviceId": "", // deviceId为空表示本设备
"bundleName": "com.extreme.test",
"abilityName": "MainAbility",
"bundleName": "com.example.myapplication",
"abilityName": "FuncAbility",
"moduleName": "entry" // moduleName非必选
};
this.context.startAbility(want, (error) => {
......@@ -46,13 +46,13 @@ import Want from '@ohos.app.ability.Want';
})
```
- 通过自定字段传递数据, 以下为当前支持类型。(在UIAbility对象中调用,其中示例中的context为UIAbility的上下文对象)
- 通过自定字段传递数据, 以下为当前支持类型(在UIAbility对象中调用,其中示例中的context为UIAbility的上下文对象)。
* 字符串(String)
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForString: "str",
},
......@@ -61,8 +61,8 @@ import Want from '@ohos.app.ability.Want';
* 数字(Number)
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForInt: 100,
keyForDouble: 99.99,
......@@ -72,8 +72,8 @@ import Want from '@ohos.app.ability.Want';
* 布尔(Boolean)
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForBool: true,
},
......@@ -82,8 +82,8 @@ import Want from '@ohos.app.ability.Want';
* 对象(Object)
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForObject: {
keyForObjectString: "str",
......@@ -97,8 +97,8 @@ import Want from '@ohos.app.ability.Want';
* 数组(Array)
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForArrayString: ["str1", "str2", "str3"],
keyForArrayInt: [100, 200, 300, 400],
......@@ -109,30 +109,29 @@ import Want from '@ohos.app.ability.Want';
```
* 文件描述符(FD)
```ts
import fileio from '@ohos.fileio';
let fd;
try {
fd = fileio.openSync("/data/storage/el2/base/haps/pic.png");
} catch(e) {
console.log("openSync fail:" + JSON.stringify(e));
import fileio from '@ohos.fileio';
let fd;
try {
fd = fileio.openSync("/data/storage/el2/base/haps/pic.png");
} catch(e) {
console.log("openSync fail:" + JSON.stringify(e));
}
let want = {
"deviceId": "", // deviceId为空表示本设备
"bundleName": "com.example.myapplication",
"abilityName": "FuncAbility",
"moduleName": "entry", // moduleName非必选
"parameters": {
"keyFd":{"type":"FD", "value":fd}
}
let want = {
"deviceId": "", // deviceId为空表示本设备
"bundleName": "com.extreme.test",
"abilityName": "MainAbility",
"moduleName": "entry", // moduleName非必选
"parameters": {
"keyFd":{"type":"FD", "value":fd}
}
};
this.context.startAbility(want, (error) => {
// 显式拉起Ability,通过bundleName、abilityName和moduleName可以唯一确定一个Ability
console.log("error.code = " + error.code)
})
};
this.context.startAbility(want, (error) => {
// 显式拉起Ability,通过bundleName、abilityName和moduleName可以唯一确定一个Ability
console.log("error.code = " + error.code)
})
```
- 更多详细说明和示例请参见: [应用模型](../../application-models/Readme-CN.md)的信息传递载体Want
<!--no_check-->
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册