HarmonyOS4.0系统性深入开发15Want概述

Want概述

Want的定义与用途

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

图1 Want用法示意

HarmonyOS4.0系统性深入开发15Want概述_第1张图片

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:在启动UIAbility时未指定abilityName的Want称为隐式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。
entities 只读 Array 表示目标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 留空将仅匹配本设备内Ability。
    bundleName string 如果指定abilityName,而不指定bundleName,则匹配失败。
    moduleName string 留空时当同一个应用内存在多个模块且模块间存在重名Ability,将默认匹配第一个。
    abilityName string 该字段必须设置表示显式匹配。
    uri string 系统匹配时将忽略该参数,但仍可作为参数传递给目标Ability。
    type string 系统匹配时将忽略该参数,但仍可作为参数传递给目标Ability。
    action string 系统匹配时将忽略该参数,但仍可作为参数传递给目标Ability。
    entities Array 系统匹配时将忽略该参数,但仍可作为参数传递给目标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 -
    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匹配规则

    HarmonyOS4.0系统性深入开发15Want概述_第2张图片

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匹配规则

    HarmonyOS4.0系统性深入开发15Want概述_第3张图片

want参数的uri和type匹配规则

调用方传入的want参数中设置uri和type参数发起组件启动请求,系统会遍历当前系统已安装的组件列表,并逐个匹配待匹配Ability的skills配置中的uris数组,如果待匹配Ability的skills配置中的uris数组中只要有一个可以匹配调用方传入的want参数中设置的uri和type即为匹配成功。

图3 want参数中uri和type皆不为空时的匹配规则

HarmonyOS4.0系统性深入开发15Want概述_第4张图片

实际应用中,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匹配需要均匹配成功,则匹配成功,否则匹配失败。

下图为了简化描述,称want中传入的uri为w_uri,称want中传入的type为w_type, 待匹配Ability的skills配置中uris为s_uris,其中每个元素为s_uri;按自上而下顺序匹配。

图4 want参数中uri和type的具体匹配规则

HarmonyOS4.0系统性深入开发15Want概述_第5张图片

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/"时匹配成功,否则匹配失败。

你可能感兴趣的:(鸿蒙系统,intellij,idea,microsoft,windows,harmonyos)