HarmonyOS 鸿蒙Next ArkTS语言教程入门学习第48天，显式Want与隐式Want匹配规则

发布于 1周前 作者 caililin 来自 鸿蒙OS

HarmonyOS 鸿蒙Next ArkTS语言教程入门学习第48天，显式Want与隐式Want匹配规则

1、Want概述

Want的定义与用途

Want是对象间信息传递的载体，可以用于应用组件间的信息传递。其使用场景之一是作为startAbility()的参数，包含了指定的启动目标以及启动时需携带的相关数据，如bundleName和abilityName字段分别指明目标Ability所在应用的包名以及对应包内的Ability名称。当UIAbilityA启动UIAbilityB并需要传入一些数据给UIAbilityB时，

Want可以作为一个载体将数据传给UIAbilityB。

图1 Want用法示意

2、Want的类型

显式Want

在启动Ability时指定了abilityName和bundleName的Want称为显式Want。

当有明确处理请求的对象时，通过提供目标Ability所在应用的包名信息（bundleName），并在Want内指定abilityName便可启动目标Ability。显式Want通常用于在当前应用开发中启动某个已知的Ability。参数说明参见Want参数说明。

隐式Want

在启动UIAbility时未指定abilityName的Want称为隐式Want。

当请求处理的对象不明确时，希望在当前应用中使用其他应用提供的某个能力（通过skills标签定义），而不关心提供该能力的具体应用，可以使用隐式Want。

例如使用隐式Want描述需要打开一个链接的请求，而不关心通过具体哪个应用打开，系统将匹配声明支持该请求的所有应用。

3、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。
entities 只读 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所示。

4、显式Want与隐式Want匹配规则

显式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。

5、隐式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都为空。
    • 如果待匹配Ability的skills配置中的uris数组为空，匹配成功。
    • 如果待匹配Ability的skills配置中的uris数组中存在uri的scheme和type都为空的元素，匹配成功。
    • 除以上两种情况，其他情况均为匹配失败。
  • 调用方传入的want参数的uri不为空，type为空。
    • 如果待匹配Ability的skills配置中的uris数组为空，匹配失败。
    • 如果待匹配Ability的skills配置中的uris数组存在一条数据uri匹配成功且type为空，则匹配成功，否则匹配失败。
  • 调用方传入的want参数的uri为空，type不为空。
    • 如果待匹配Ability的skills配置中的uris数组为空，匹配失败。
    • 如果待匹配Ability的skills配置中的uris数组存在一条数据uri的scheme为空且type匹配成功，则匹配成功，否则匹配失败。
  • 调用方传入的want参数的uri和type都不为空，如图3所示。
    • 如果待匹配Ability的skills配置中的uris数组为空，匹配失败。
    • 如果待匹配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/"时匹配成功，否则匹配失败。

更多关于HarmonyOS 鸿蒙Next ArkTS语言教程入门学习第48天，显式Want与隐式Want匹配规则的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html

2 回复

在HarmonyOS中，Want是用于组件间通信的一种机制，分为显式Want和隐式Want。

显式Want通过指定目标组件的具体信息（如bundleName、abilityName）来启动目标组件，适用于明确知道目标组件的情况。隐式Want通过指定action、uri、type等属性，由系统根据匹配规则选择合适的组件，适用于不明确目标组件但知道操作类型的情况。

显式Want的匹配规则是直接根据指定的bundleName和abilityName找到目标组件。隐式Want的匹配规则则基于action、uri、type等属性，系统会根据这些属性在已安装的应用中查找符合条件的组件。如果多个组件符合条件，系统会弹出选择框让用户选择。

在ArkTS中，显式Want的使用示例：

let want = {
    bundleName: "com.example.myapp",
    abilityName: "MainAbility"
};
this.context.startAbility(want);

隐式Want的使用示例：

let want = {
    action: "ohos.intent.action.VIEW",
    uri: "https://www.example.com",
    type: "text/html"
};
this.context.startAbility(want);

显式Want和隐式Want的匹配规则是HarmonyOS中组件通信的基础，开发者需要根据具体需求选择合适的Want类型。

更多关于HarmonyOS 鸿蒙Next ArkTS语言教程入门学习第48天，显式Want与隐式Want匹配规则的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


在HarmonyOS的ArkTS语言中，显式Want和隐式Want是用于启动组件（如Ability）的两种方式。显式Want通过指定具体的组件名称和包名来启动目标组件，适用于明确知道目标组件的情况。隐式Want则通过指定操作（action）、数据类型（type）等条件，由系统根据匹配规则选择合适的组件，适用于需要动态选择组件的场景。匹配规则包括：

  1. 系统会根据隐式Want的条件筛选符合条件的组件；
  2. 如果有多个组件匹配，用户可以选择；
  3. 如果没有匹配的组件，系统会返回错误。

合理使用显式和隐式Want可以提升应用的灵活性和用户体验。

回到顶部
AI 助手
你好，我是IT营的 AI 助手
您可以尝试点击下方的快捷入口开启体验！