| OpenHarmony应用开发 | 您所在的位置：网站首页 › intent的定义和用途 › OpenHarmony应用开发 |
OpenHarmony应用开发
|
版本：v3.2 Beta5 Want概述Want的定义与用途Want是一种对象，用于在应用组件之间传递信息。 其中，一种常见的使用场景是作为startAbility()方法的参数。例如，当UIAbilityA需要启动UIAbilityB并向UIAbilityB传递一些数据时，可以使用Want作为一个载体，将数据传递给UIAbilityB。 图1 Want用法示意
let wantInfo = { deviceId: '', // deviceId为空表示本设备 bundleName: 'com.example.myapplication', abilityName: 'FuncAbility', }隐式Want：在启动Ability时，如果未指定abilityName，则称为隐式Want。 当需要处理的对象不明确时，可以使用隐式Want，在当前应用中使用其他应用提供的某个能力，而不关心提供该能力的具体应用。隐式Want使用skills标签来定义需要使用的能力，并由系统匹配声明支持该请求的所有应用来处理请求。例如，需要打开一个链接的请求，系统将匹配所有声明支持该请求的应用，然后让用户选择使用哪个应用打开链接。
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与隐式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不为空且包含调用方传入的want参数的action，则action匹配成功。调用方传入的want参数的action不为空，待匹配Ability的skills配置中的actions不为空且不包含调用方传入的want参数的action，则action匹配失败。图1want参数的action匹配规则
将调用方传入的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参数发起组件启动请求，系统会遍历当前系统已安装的组件列表，并逐个匹配待匹配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为空。1. 如果待匹配Ability的skills配置中的uris数组为空，匹配失败。 2. 如果待匹配Ability的skills配置中的uris数组存在一条数据uri匹配成功且type为空，则匹配成功，否则匹配失败。 调用方传入的want参数的uri为空，type不为空。如果待匹配Ability的skills配置中的uris数组为空，匹配失败。如果待匹配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的具体匹配规则
这里为了简化描述，称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/pathRegextype匹配规则说明： 此小节所述的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与entitiesaction：表示调用方要执行的通用操作（如查看、分享、应用详情）。在隐式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组件来完成某些特定任务。在启动UIAbility时，指定了abilityName和bundleName参数，可以使用显式Want方式启动UIAbility。显式Want的使用 针对应用的特定任务，用户需要通过点击应用内的按钮来启动指定的UIAbility组件。在启动UIAbility时，需要提供abilityName和bundleName参数，并使用显式Want方式来启动。关于如何使用显式Want方式启动应用内的UIAbility，请参见启动应用内的UIAbility。 使用隐式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", // ... } // ... ] }, ]开发步骤 1.在自定义函数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}`) } } 匹配过程如下： want内action不为空，且被skills内action包括，匹配成功。want内entities不为空，且被skills内entities包括，匹配成功。skills内uris拼接为https://www.test.com:8080/query* (*为通配符)包含want内uri，匹配成功。want内type不为空，且被skills内type包含，匹配成功。2.当有多个匹配应用时，会被应用选择器展示给用户进行选择。
在应用使用场景中，用户经常需要将一个应用内的数据（如文字、图片等）分享至另一个应用内继续操作。下面以PDF文件分享为例，介绍应用间使用Want分享数据的方法。 前提条件数据分享涉及2个UIAbility组件（分享方和被分享方）和1个系统部件（应用选择框）。当分享方通过startAbility接口发起数据分享后，将拉起应用选择框。其将隐式匹配并展示所有支持接受分享数据类型的应用，由用户主动选取，并由系统拉起点击应用完成数据的分享。在本章节中，将继续以按钮形式来触发分享，实际开发场景中并不局限于此，此章节着重讲解分享时Want的配置。本章节涉及的action：ACTION_SELECT （ohos.want.action.select）：指示显示应用程序选择框的操作。用于拉起应用选择框。ACTION_SEND_DATA （ohos.want.action.sendData）：指示发送单个数据记录的操作。用于传递数据至分享方。开发步骤分享方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);在前提条件中介绍了分享的流程。分享方需先拉起应用选择框，并将数据分享给应用选择框，并由应用选择框代理传递至被分享方，完成分享。因此分享方的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将传递至所选应用。 被分享方：上文中提到，应用选择器通过“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”字段匹配时，仍可匹配成功且传递额外数据。 应用选择器拉起被分享方后，系统将调用其“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; // ... } } 文章转载自：https://docs.openharmony.cn/pages/v3.2Beta/zh-cn/application-dev/application-models/data-share-via-want.md/ |
【本文地址】