显式Want与隐式Want匹配规则

2024-01-25 12:25 更新

在启动目标Ability时，会通过显式Want和隐式Want进行目标Ability的匹配，这里说的匹配规则就是调用方Want中设置的参数如何与目标Ability声明的配置文件进行匹配。

显式Want匹配原理

名称	类型	匹配项	必选	规则
deviceId	string	是	否	留空将仅匹配本设备内Ability。
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不为空，则action匹配成功。
调用方传入的want参数的action不为空，待匹配Ability的skills配置中的actions不为空且包含调用方传入的want参数的action，则action匹配成功。
调用方传入的want参数的action不为空，待匹配Ability的skills配置中的actions不为空且不包含调用方传入的want参数的action，则action匹配失败。
图1 want参数的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匹配失败。
图2 want参数的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都为空。
1. 如果待匹配Ability的skills配置中的uris数组为空，匹配成功。
2. 如果待匹配Ability的skills配置中的uris数组中存在uri的scheme和type都为空的元素，匹配成功。
3. 除以上两种情况，其他情况均为匹配失败。
调用方传入的want参数的uri不为空，type为空。
1. 如果待匹配Ability的skills配置中的uris数组为空，匹配失败。
2. 如果待匹配Ability的skills配置中的uris数组存在一条数据uri匹配成功且type为空，则匹配成功，否则匹配失败。
调用方传入的want参数的uri为空，type不为空。
1. 如果待匹配Ability的skills配置中的uris数组为空，匹配失败。
2. 如果待匹配Ability的skills配置中的uris数组存在一条数据uri的scheme为空且type匹配成功，则匹配成功，否则匹配失败。
调用方传入的want参数的uri和type都不为空，如图3所示。
1. 如果待匹配Ability的skills配置中的uris数组为空，匹配失败。
2. 如果待匹配Ability的skills配置中的uris数组存在一条数据uri匹配和type匹配需要均匹配成功，则匹配成功，否则匹配失败。