HarmonyOS Developer Stage 模型开发指导
信息传递载体Want
Want概述
Want的定义与用途
Want是对象间信息传递的载体,可以用于应用组件间的信息传递。其使用场景之一是作为startAbility()的参数,包含了指定的启动目标以及启动时需携带的相关数据,如bundleName和abilityName字段分别指明目标Ability所在应用的包名以及对应包内的Ability名称。当UIAbilityA启动UIAbilityB并需要传入一些数据给UIAbilityB时,Want可以作为一个载体将数据传给UIAbilityB。
图1 Want用法示意
Want的类型
- 显式Want:在启动Ability时指定了abilityName和bundleName的Want称为显式Want。
当有明确处理请求的对象时,通过提供目标Ability所在应用的包名信息(bundleName),并在Want内指定abilityName便可启动目标Ability。显式Want通常用于在当前应用开发中启动某个已知的Ability。参数说明参见Want参数说明。
let wantInfo = {
deviceId: '', // deviceId为空表示本设备
bundleName: 'com.example.myapplication',
abilityName: 'FuncAbility',
}
- 隐式Want:当请求处理的对象不明确时,希望在当前应用中使用其他应用提供的某个能力(通过skills标签定义),而不关心提供该能力的具体应用,可以使用隐式Want。例如使用隐式Want描述需要打开一个链接的请求,而不关心通过具体哪个应用打开,系统将匹配声明支持该请求的所有应用。
let wantInfo = {
// uncomment line below if wish to implicitly query only in the specific bundle.
// bundleName: 'com.example.myapplication',
action: 'ohos.want.action.search',
// entities can be omitted
entities: [ 'entity.system.browsable' ],
uri: 'https://www.test.com:8080/query/student',
type: 'text/plain',
};
说明
- 根据系统中待匹配Ability的匹配情况不同,使用隐式Want启动Ability时会出现以下三种情况。
○ 未匹配到满足条件的Ability:启动失败。
○ 匹配到一个满足条件的Ability:直接启动该Ability。
○ 匹配到多个满足条件的Ability(UIAbility):弹出选择框让用户选择。
- 调用方传入的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, schemeSpecificPart, authority和path信息。 |
type | 只读 | string | 否 | 表示携带数据类型,使用MIME类型规范。例如:"text/plain"、"image/*"等。 |
action | 只读 | string | 否 | 表示要执行的通用操作(如:查看、分享、应用详情)。在隐式Want中,您可定义该字段,配合uri或parameters来表示对数据要执行的操作。如打开,查看该uri数据。例如,当uri为一段网址,action为ohos.want.action.viewData则表示匹配可查看该网址的Ability。 |
只读 | Array<string> | 否 | 表示目标Ability额外的类别信息(如:浏览器,视频播放器),在隐式Want中是对action的补充。在隐式Want中,您可定义该字段,来过滤匹配UIAbility类别,如必须是浏览器。例如,在action字段的举例中,可存在多个应用声明了支持查看网址的操作,其中有应用为普通社交应用,有的为浏览器应用,您可通过entity.system.browsable过滤掉非浏览器的其他应用。 | |
flags | 只读 | number | 否 | 表示处理Want的方式。例如通过wantConstant.Flags.FLAG_ABILITY_CONTINUATION表示是否以设备间迁移方式启动Ability。 |
parameters | 只读 | {[key: string]: any} | 否 | 此参数用于传递自定义数据,通过用户自定义的键值对进行数据填充,具体支持的数据类型如Want API所示。 |
显式Want与隐式Want匹配规则
在启动目标Ability时,会通过显式Want和隐式Want进行目标Ability的匹配,这里说的匹配规则就是调用方Want中设置的参数如何与目标Ability声明的配置文件进行匹配。
- 显式Want匹配原理
名称 | 类型 | 匹配项 | 必选 | 规则 |
deviceId | string | 是 | 否 | 留空将仅匹配本设备内UIAbility。 |
bundleName | string | 是 | 是 | 如果指定abilityName,而不指定bundleName,则匹配失败。 |
moduleName | string | 是 | 否 | 留空时当同一个应用内存在多个模块且模块间存在重名Ability,将默认匹配第一个。 |
abilityName | string | 是 | 是 | 该字段必须设置表示显式匹配。 |
uri | string | 否 | 否 | 系统匹配时将忽略该参数,但仍可作为参数传递给目标Ability。 |
type | string | 否 | 否 | 系统匹配时将忽略该参数,但仍可作为参数传递给目标Ability。 |
action | string | 否 | 否 | 系统匹配时将忽略该参数,但仍可作为参数传递给目标Ability。 |
entities | Array<string> | 否 | 否 | 系统匹配时将忽略该参数,但仍可作为参数传递给目标Ability。 |
flags | number | 否 | 否 | 不参与匹配,直接传递给系统处理,一般用来设置运行态信息,例如URI数据授权等。 |
parameters | {[key: string]: any} | 否 | 否 | 不参与匹配,应用自定义数据将直接传递给目标Ability。 |
- 隐式Want匹配原理
名称 | 类型 | 匹配项 | 必选 | 规则 |
deviceId | string | 是 | 否 | 跨设备目前不支持隐式调用。 说明 当前版本暂不支持跨设备能力。 |
abilityName | string | 否 | 否 | 该字段必须留空表示隐式匹配。 |
bundleName | string | 是 | 否 | - 声明bundleName时,隐式搜索将仅限于对应应用包内。 - 声明bundleName与moduleName时,隐式搜索将仅限于对应应用的对应Module内。 - 单独声明moduleName时,该字段无效。 - 同时声明bundleName与moduleName时,隐式搜索将仅限于对应应用包内的对应模块内。 这些字段将用来隐式匹配,具体规则可参考隐式Want匹配原理详解。 |
moduleName | string | 是 | 否 | - |
uri | string | 是 | 否 | - |
type | string | 是 | 否 | - |
action | string | 是 | 否 | - |
entities | Array<string> | 是 | 否 | - |
flags | number | 否 | 否 | 不参与匹配,直接传递给系统处理,一般用来设置运行态信息,例如URI数据授权等。 |
parameters | {[key: string]: any} | 否 | 否 | 不参与匹配,应用自定义数据将直接传递给目标Ability。 |
隐式Want匹配原理详解
从隐式Want的定义,可得知:
- 调用方传入的want参数,表明调用方需要执行的操作,并提供相关数据以及其他应用类型限制。
- 待匹配Ability的skills配置,声明其具备的能力(module.json5配置文件中的skills标签参数)。
系统将调用方传入的want参数(包含action、entities、uri和type属性)与已安装待匹配的应用Ability的skills配置(包含actions、entities、uris和type属性)依次进行匹配。当四个属性匹配均通过,则此应用才会被应用选择器展示给用户进行选择。
want参数的action匹配规则
将调用方传入的want参数的action与待匹配Ability的skills配置中的actions进行匹配。
- 调用方传入的want参数的action不为空,待匹配Ability的skills配置中的actions为空,则action匹配失败。
- 调用方传入的want参数的action为空,待匹配Ability的skills配置中的actions不为空,则action匹配成功。
- 调用方传入的want参数的action不为空,待匹配Ability的skills配置中的actions不为空且包含调用方传入的want参数的action,则action匹配成功。
- 调用方传入的want参数的action不为空,待匹配Ability的skills配置中的actions不为空且不包含调用方传入的want参数的action,则action匹配失败。
图1want参数的action匹配规则
want参数的entities匹配规则
将调用方传入的want参数的entities与待匹配Ability的skills配置中的entities进行匹配。
- 调用方传入的want参数的entities为空,待匹配Ability的skills配置中的entities不为空,则entities匹配成功。
- 调用方传入的want参数的entities为空,待匹配Ability的skills配置中的entities为空,则entities匹配成功。
- 调用方传入的want参数的entities不为空,待匹配Ability的skills配置中的entities为空,则entities匹配失败。
- 调用方传入的want参数的entities不为空,待匹配Ability的skills配置中的entities不为空且包含调用方传入的want参数的entities,则entities匹配成功。
- 调用方传入的want参数的entities不为空,待匹配Ability的skills配置中的entities不为空且不完全包含调用方传入的want参数的entities,则entities匹配失败。
图2want参数的entities匹配规则
want参数的uri和type匹配规则
调用方传入的want参数中设置uri和type参数发起组件启动请求,系统会遍历当前系统已安装的组件列表,并逐个匹配待匹配Ability的skills配置中的uris数组,如果待匹配Ability的skills配置中的uris数组中只要有一个可以匹配调用方传入的want参数中设置的uri和type即为匹配成功。
图3 want参数中uri和type皆不为空时的匹配规则
实际应用中,uri和type共存在四种情况,下面将讲解四种情况的具体匹配规则:
- 调用方传入的want参数的uri和type都为空。
a.如果待匹配Ability的skills配置中的uris数组为空,匹配成功。
b.如果待匹配Ability的skills配置中的uris数组中存在uri的scheme和type都为空的元素,匹配成功。
c.除以上两种情况,其他情况均为匹配失败。
- 调用方传入的want参数的uri不为空,type为空。
a.如果待匹配Ability的skills配置中的uris数组为空,匹配失败。
b.如果待匹配Ability的skills配置中的uris数组存在一条数据uri匹配成功且type为空,则匹配成功,否则匹配失败。
- 调用方传入的want参数的uri为空,type不为空。
a.如果待匹配Ability的skills配置中的uris数组为空,匹配失败。
b.如果待匹配Ability的skills配置中的uris数组存在一条数据uri的scheme为空且type匹配成功,则匹配成功,否则匹配失败。
- 调用方传入的want参数的uri和type都不为空,如图3所示。
a.如果待匹配Ability的skills配置中的uris数组为空,匹配失败。
b.如果待匹配Ability的skills配置中的uris数组存在一条数据uri匹配和type匹配需要均匹配成功,则匹配成功,否则匹配失败。
下图为了简化描述,称want中传入的uri为w_uri,称want中传入的type为w_type, 待匹配Ability的skills配置中uris为s_uris,其中每个元素为s_uri;按自上而下顺序匹配。
图4 want参数中uri和type的具体匹配规则
uri匹配规则
这里为了简化描述,称want中传入的uri为w_uri,待匹配Ability的skills配置中uri为s_uri,具体的匹配规则如下:
- 如果s_uri的scheme为空,当w_uri为空时匹配成功,否则匹配失败;
- 如果s_uri的host为空,当w_uri和s_uri的scheme相同时匹配成功,否则匹配失败;
- 如果s_uri的path、pathStartWith和pathRegex都为空,当w_uri和s_uri完全相同时匹配成功,否则匹配失败;
- 如果s_uri的path不为空,当w_uri和s_uri全路径表达式相同时匹配成功,否则继续进行pathStartWith的匹配;
- 如果s_uri的pathStartWith不为空,当w_uri包含s_uri前缀表达式时匹配成功,否则继续进行pathRegex的匹配;
- 如果s_uri的pathRegex不为空,当w_uri满足s_uri正则表达式时匹配成功,否则匹配失败;
说明
待匹配Ability的skills配置的uris中scheme、host、port、path、pathStartWith和pathRegex属性拼接,如果依次声明了path、pathStartWith和pathRegex属性时,uris将分别拼接为如下三种表达式:
- 全路径表达式:scheme://host:port/path
- 前缀表达式:scheme://host:port/pathStartWith
- 正则表达式:scheme://host:port/pathRegex
type匹配规则
说明
此小节所述的type匹配规则的适用性需建立在want参数内type不为空的基础上。当want参数内type为空时请参考want参数的uri和type匹配规则。
这里为了简化描述,称want中传入的uri为w_type,待匹配Ability的skills数组中uris的type数据为s_type,具体的匹配规则如下:
- 如果s_type为空,则匹配失败。
- 如果s_type或者w_type为通配符"*/*",则匹配成功。
- 如果s_type最后一个字符为通配符'*',如"prefixType/*",则当w_type包含"prefixType/"时匹配成功,否则匹配失败。
- 如果w_type最后一个字符为通配符'*',如"prefixType/*",则当s_type包含"prefixType/"时匹配成功,否则匹配失败。
常见action与entities
action:表示调用方要执行的通用操作(如查看、分享、应用详情)。在隐式Want中,您可定义该字段,配合uri或parameters来表示对数据要执行的操作。如打开,查看该uri数据。例如,当uri为一段网址,action为ohos.want.action.viewData则表示匹配可查看该网址的Ability。在Want内声明action字段表示希望被调用方应用支持声明的操作。在被调用方应用配置文件skills字段内声明actions表示该应用支持声明操作。
常见action
- ACTION_HOME:启动应用入口组件的动作,需要和ENTITY_HOME配合使用;系统桌面应用图标就是显式的入口组件,点击也是启动入口组件;入口组件可以配置多个。
- ACTION_CHOOSE:选择本地资源数据,例如联系人、相册等;系统一般对不同类型的数据有对应的Picker应用,例如联系人和图库。
- ACTION_VIEW_DATA:查看数据,当使用网址uri时,则表示显示该网址对应的内容。
- ACTION_VIEW_MULTIPLE_DATA:发送多个数据记录的操作。
entities:表示目标Ability的类别信息(如浏览器、视频播放器),在隐式Want中是对action的补充。在隐式Want中,开发者可定义该字段,来过滤匹配应用的类别,例如必须是浏览器。在Want内声明entities字段表示希望被调用方应用属于声明的类别。在被调用方应用配置文件skills字段内声明entites表示该应用支持的类别。
常用entities
- ENTITY_DEFAULT:默认类别无实际意义。
- ENTITY_HOME:主屏幕有图标点击入口类别。
- ENTITY_BROWSABLE:指示浏览器类别。
使用显式Want启动Ability
在应用使用场景中,当用户点击某个按钮时,应用经常需要拉起指定UIAbility组件来完成某些特定任务。下面介绍如何通过显式Want拉起应用内一个指定UIAbility组件。
开发步骤
- Stage模型工程内,创建一个Ability(此示例内命名为callerAbility)与相应Page(此示例中名为Index.ets),并在callerAbility.ts文件内的onWindowStageCreate函数内通过windowStage.loadContent()方法将两者绑定。
// ...
// 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')
}
// ...
- 同上方法再创建一个Ability,此示例内命名为“calleeAbility”。
- 在callerAbility的“Index.ets”页面内新增一个按钮。
// ...
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%')
}
// ...
- 补充相对应的onClick方法,并使用显式Want在方法内启动calleeAbility。bundleName字段可在工程AppScope>app.json5文件内获取;abilityName可在对应模块内的“yourModuleName > src > main > module.json5”文件查看。
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}`);
}
}
// ...
- 至此,当您点击CLICKME按钮时,应看到页面的跳转。
使用隐式Want打开网址
前提条件
设备上安装了一个或多个浏览器。
浏览器应用中通过module.json5配置如下:
"skills": [
{
"entities": [
"entity.system.browsable"
// ...
],
"actions": [
"ohos.want.action.viewData"
// ...
],
"uris": [
{
"scheme": "https",
"host": "www.test.com",
"port": "8080",
// prefix matching
"pathStartWith": "query",
"type": "text/*"
},
{
"scheme": "http",
// ...
}
// ...
]
},
]
开发步骤
- 在自定义函数implicitStartAbility内使用隐式Want启动Ability。
async implicitStartAbility() {
try {
let want = {
// 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.browsable" ],
"uri": "https://www.test.com:8080/query/student",
"type": "text/plain"
}
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}`)
}
}
匹配过程如下:
a. want内action不为空,且被skills内action包括,匹配成功。
b. want内entities不为空,且被skills内entities包括,匹配成功。
c. skills内uris拼接为https://www.test.com:8080/query\* (*为通配符)包含want内uri,匹配成功。
d. want内type不为空,且被skills内type包含,匹配成功。
- 当有多个匹配应用时,会被应用选择器展示给用户进行选择。
应用间使用Want分享数据
在应用使用场景中,用户经常需要将一个应用内的数据(如文字、图片等)分享至另一个应用内继续操作。下面以PDF文件分享为例,介绍应用间使用Want分享数据的方法。
前提条件
- 数据分享涉及2个UIAbility组件(分享方和被分享方)和1个系统部件(应用选择框)。当分享方通过startAbility接口发起数据分享后,将拉起应用选择框。其将隐式匹配并展示所有支持接受分享数据类型的应用,由用户主动选取,并由系统拉起点击应用完成数据的分享。
- 在本章节中,将继续以按钮形式来触发分享,实际开发场景中并不局限于此,此章节着重讲解分享时Want的配置。
- 本章节涉及的action:
○ ACTION_SELECT (ohos.want.action.select):指示显示应用程序选择框的操作。用于拉起应用选择框。
○ ACTION_SEND_DATA (ohos.want.action.sendData):指示发送单个数据记录的操作。用于传递数据至分享方。
开发步骤
- 分享方
a. Stage模型下经常会遇到需要分享文件的场景,在这种场景下我们需要使用文件描述符(FD)来传递文件。此示例中,默认已获取分享文件的路径。
import fileIO from '@ohos.fileio';
// let path = ...
// file open where path is a variable contains the file path.
let fileFd = fileIO.openSync(path, 0o102, 0o666);
b. 在前提条件中介绍了分享的流程。分享方需先拉起应用选择框,并将数据分享给应用选择框,并由应用选择框代理传递至被分享方,完成分享。因此分享方的Want需使用2层嵌套,在第1层中使用隐式Want并配合“ohos.want.action.select”action拉起应用选择框,并在自定义字段parameters内声明一个完整的want作为第2层,其中声明传递给被分享方的数据。
import wantConstant from '@ohos.app.ability.wantConstant';
// let path = ...
// let fileFd = ...
// let fileSize = ...
let want = {
// This action is used to implicitly match the application selctor.
action: wantConstant.Action.ACTION_SELECT,
// This is the custom parameter in the first layer of want
// which is intended to add info to application selector.
parameters: {
// The MIME type of pdf
"ability.picker.type": "application/pdf",
"ability.picker.fileNames": [path],
"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}
}
}
}
}
以上代码中使用Want自定义字段paramters,其中第一层paramters中的“ability.picker.*”字段用于传递展示信息给应用选择器,具体字段表示为:
- "ability.picker.type":应用选择器根据该字段渲染相应的文件类型图标。
- "ability.picker.fileNames":应用选择器根据该字段展示文件名。
- "ability.picker.fileSizes":应用选择器根据该字段展示文件大小。以字节为单位。
- "ability.picker.fileNames"与"ability.picker.fileSizes"为数组,其有一一对应关系。
例如:当"ability.picker.type"为“application/pdf”,"ability.picker.fileNames"为“["接口文档.pdf"]”,"ability.picker.fileSizes"为“[350 * 1024]”时,应用选择器将以下形式展示。
示例代码中“ability.want.params.INTENT”字段是一个嵌套Want,内部所含action、type等字段将由应用选择器进行隐式匹配,具体隐式匹配规则可参考隐式Want匹配原理详解。当用户选择具体应用后,“ability.want.params.INTENT”字段的嵌套Want将传递至所选应用。
- 被分享方:
a. 上文中提到,应用选择器通过“ability.want.params.INTENT”字段进行隐式匹配。因此被分享方Ability配置文件内(stage模型下的module.json5)skills字段需配置如下。
"skills": [
{
"entities": [
// ...
],
"actions": [
"ohos.want.action.sendData"
// ...
],
"uris": [
{
"type": "application/pdf"
},
// ...
]
},
]
其中"actions"字段和“uris”内“type”字段分别与“ability.want.params.INTENT”内“action”,“type”字段匹配。
注意:当前文件传递不支持uri方式传递,仅支持FD方式,但隐式匹配中,Want内的“type”字段需与被分享方配置文件skills内“uris”字段下的“type”字段匹配,因此skills内的“uris”字段建议只声明“type”字段,增加“host”,“port”等字段在上述示例中将匹配失败。因为应用选择框通过“ability.want.params.INTENT”发起隐式匹配,所以在“ability.want.params.INTENT”字段内增加uri字段,且与skills内的“uris”字段匹配时,仍可匹配成功且传递额外数据。
b. 应用选择器拉起被分享方后,系统将调用其“onCreate”接口,并传入“ability.want.params.INTENT”至其入参want内。
onCreate(want, launchParam) {
// note when keyFd is undefined, app crash will happen.
if (want["parameters"]["keyFd"] !== undefined) {
// receive file descriptor
let fd = want["parameters"]["keyFd"].value;
// ...
}
}