@[toc]

深入了解Arkts语言中的Want对象

Arkts语言中的Want是一种用于对象间信息传递的载体，主要用于应用组件之间的信息传递。本文将深入探讨Want的定义、用途、类型以及参数说明，并介绍显式和隐式Want的使用场景和匹配规则。

Want的定义与用途

Want作为对象间信息传递的载体，常用于启动能力（Ability）时传递相关数据。在启动目标Ability时，Want包含了指定的启动目标和启动时需携带的相关数据，如bundleName和abilityName字段分别指明目标Ability所在应用的包名和对应包内的Ability名称。

例如，在启动UIAbilityA时需要传递数据给UIAbilityB，可以使用Want作为载体，将数据传递给UIAbilityB。

图1 Want用法示意

Want的类型

显式Want

显式Want在启动Ability时指定了abilityName和bundleName，用于在当前应用开发中启动已知的Ability。以下是显式Want的示例：

let wantInfo = {
    deviceId: '', // deviceId为空表示本设备
    bundleName: 'com.example.myapplication',
    abilityName: 'FuncAbility',
}

隐式Want

隐式Want在启动UIAbility时未指定abilityName，用于请求处理对象不明确的情况。系统将匹配声明支持该请求的所有应用，用户可以选择其中一个应用进行启动。以下是隐式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: ['entity.system.browsable'],
    uri: 'https://www.test.com:8080/query/student',
    type: 'text/plain',
};

隐式Want启动Ability时可能出现未匹配、匹配到一个、匹配到多个的情况，系统将根据匹配情况决定如何处理。

Want参数说明

下表列出了Want对象中的各参数及其说明：

显式Want与隐式Want匹配规则

在启动目标Ability时，会通过显式Want和隐式Want进行目标Ability的匹配。以下是显式Want和隐式Want的匹配规则：

名称

• deviceId
• bundleName
• moduleName
• abilityName
• uri
• type
• action
• entities
• flags
• parameters

类型

• string
• string
• string
• string
• string
• string
• string
• Array<string>
• number
• {[key: string]: any}

匹配项

• 是
• 是
• 否
• 是
• 否
• 否
• 否
• 否
• 否
• 否

规则

1. deviceId：留空将仅匹配本设备。
2. bundleName：如果指定abilityName，而不指定bundleName，则匹配失败。
3. moduleName：留空时，当同一个应用内存在多个模块且模块间存在重名Ability，将默认匹配第一个。
4. abilityName：该字段必须设置表示显式匹配。
5. uri：系统匹配时将忽略该参数，但仍可作为参数传递给目标Ability。
6. type：系统匹配时将忽略该参数，但仍可作为参数传递给目标Ability。
7. action：系统匹配时将忽略该参数，但仍可作为参数传递给目标Ability。
8. entities：系统匹配时将忽略该参数，但仍可作为参数传递给目标Ability。
9. flags：不参与匹配，直接传递给系统处理，一般用来设置运行态信息，例如URI数据授权等。
10. parameters：不参与匹配，应用自定义数据将直接传递给目标Ability。

隐式Want匹配原理

名称

• deviceId
• abilityName
• bundleName
• moduleName
• uri
• type
• action
• entities
• flags
• parameters

类型

• string
• string
• string
• string
• string
• string
• string
• Array<string>
• number
• {[key: string]: any}

匹配项

• 是
• 否
• 是
• 否
• 是
• 是
• 是
• 是
• 否
• 否

规则

1. deviceId：跨设备目前不支持隐式调用。

说明： 当前版本暂不支持跨设备能力。

2. abilityName：该字段必须留空表示隐式匹配。
3. bundleName：
   • 声明bundleName时，隐式搜索将仅限于对应应用包内。
   • 声明bundleName与moduleName时，隐式搜索将仅限于对应应用的对应Module内。
   • 单独声明moduleName时，该字段无效。
   • 同时声明bundleName与moduleName时，隐式搜索将仅限于对应应用包内的对应模块内。
4. moduleName：-
5. uri：-
6. type：-
7. action：-
8. entities：-
9. flags：不参与匹配，直接传递给系统处理，一般用来设置运行态信息，例如URI数据授权等。
10. parameters：不参与匹配，应用自定义数据将直接传递给目标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进行匹配。

1. 调用方传入的want参数的action为空，待匹配Ability的skills配置中的actions为空，则action匹配失败。
2. 调用方传入的want参数的action不为空，待匹配Ability的skills配置中的actions为空，则action匹配失败。
3. 调用方传入的want参数的action为空，待匹配Ability的skills配置中的actions不为空，则action匹配成功。
4. 调用方传入的want参数的action不为空，待匹配Ability的skills配置中的actions不为空且包含调用方传入的want参数的action，则action匹配成功。
5. 调用方传入的want参数的action不为空，待匹配Ability的skills配置中的actions不为空且不包含调用方传入的want参数的action，则action匹配失败。

总结：

本文深入介绍了Arkts语言中的Want对象，该对象是一种在应用组件之间进行信息传递的载体。主要讨论了Want的定义、用途、类型以及参数说明，并详细介绍了显式和隐式Want的使用场景和匹配规则。

在Want的定义与用途部分，文中阐述了Want作为对象间信息传递的重要载体，特别是在启动能力时传递相关数据的应用。示例图展示了Want在启动UIAbilityA时传递数据给UIAbilityB的实际用法。

Want的类型部分详细介绍了显式和隐式Want。显式Want在启动Ability时明确指定abilityName和bundleName，而隐式Want则用于请求处理对象不明确的情况，系统将匹配声明支持该请求的所有应用。

随后，文中列出了Want对象中的各参数及其说明，包括deviceId、bundleName、moduleName、abilityName等参数，以及它们的类型和是否必填。对于Want的显式和隐式匹配规则进行了详细解释，包括各参数的匹配项和规则，以及隐式匹配原理的详细说明。

总体而言，本文全面深入地探讨了Arkts语言中的Want对象，为开发者提供了清晰的指导和理解。