diff --git a/zh-cn/application-dev/application-models/explicit-implicit-want-mappings.md b/zh-cn/application-dev/application-models/explicit-implicit-want-mappings.md index 2fb7d0343bcca817dff168c590a12be694dac0e2..68f76dbca091de66c228c052207a2658fcbc60ed 100644 --- a/zh-cn/application-dev/application-models/explicit-implicit-want-mappings.md +++ b/zh-cn/application-dev/application-models/explicit-implicit-want-mappings.md @@ -1,39 +1,41 @@ # 显式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<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匹配原理详解](#隐式want匹配原理详解)。 | - | moduleName | string | 是 | 否 | - | uri | string | 是 | 否 | - | type | string | 是 | 否 | - | action | string | 是 | 否 | - | entities | Array<string> | 是 | 否 | - | flags | number | 否 | 否 | 不参与匹配，直接传递给系统处理，一般用来设置运行态信息，例如URI数据授权等。 | - | parameters | {[key: string]: any} | 否 | 否 | 不参与匹配，应用自定义数据将直接传递给目标Ability。 | - -# 隐式Want匹配原理详解 - +在启动目标Ability时，会通过显式Want或者隐式Want进行目标Ability的匹配，这里说的匹配规则就是调用方Want中设置的参数如何与目标Ability声明的配置文件进行匹配。 + +## 显式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匹配原理 + +隐式Want匹配原理如下表所示。 + +| 名称 | 类型 | 匹配项 | 必选 | 规则 | +| ----------- | ------------------------------ | ------ | ---- | ------------------------------------------------------------ | +| deviceId | string | 是 | 否 | 跨设备目前不支持隐式调用。 | +| abilityName | string | 否 | 否 | 该字段必须留空表示隐式匹配。 | +| bundleName | string | 是 | 否 | - 声明bundleName时，隐式搜索将仅限于对应应用包内。
- 声明bundleName与moduleName时，隐式搜索将仅限于对应应用的对应Module内。
- 单独声明moduleName时，该字段无效。
- 同时声明bundleName与moduleName时，隐式搜索将仅限于对应应用包内的对应模块内。
这些字段将用来隐式匹配，具体规则可参考[隐式Want匹配原理详解](#隐式want匹配原理详解)。 | +| moduleName | string | 是 | 否 | | +| uri | string | 是 | 否 | | +| type | string | 是 | 否 | | +| action | string | 是 | 否 | | +| entities | Array<string> | 是 | 否 | | +| flags | number | 否 | 否 | 不参与匹配，直接传递给系统处理，一般用来设置运行态信息，例如URI数据授权等。 | +| parameters | {[key: string]: any} | 否 | 否 | 不参与匹配，应用自定义数据将直接传递给目标Ability。 | 从隐式Want的定义，可得知： @@ -46,7 +48,7 @@ 系统将调用方传入的want参数（包含action、entities、uri和type属性）与已安装待匹配的应用Ability的skills配置（包含actions、entities、uris和type属性）依次进行匹配。当四个属性匹配均通过，则此应用才会被应用选择器展示给用户进行选择。 -## want参数的action匹配规则 +### want参数的action匹配规则 将调用方传入的want参数的[action](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction)与待匹配Ability的skills配置中的actions进行匹配。 @@ -58,10 +60,11 @@ - 调用方传入的want参数的action不为空，待匹配Ability的skills配置中的actions不为空且不包含调用方传入的want参数的action，则action匹配失败。 - **图1** want参数的action匹配规则  want-action + **图1** want参数的action匹配规则 + want-action -## want参数的entities匹配规则 +### want参数的entities匹配规则 将调用方传入的want参数的[entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity)与待匹配Ability的skills配置中的entities进行匹配。 @@ -79,7 +82,7 @@ want-entities -## want参数的uri和type匹配规则 +### want参数的uri和type匹配规则 调用方传入的want参数中设置uri和type参数发起组件启动请求，系统会遍历当前系统已安装的组件列表，并逐个匹配待匹配Ability的skills配置中的uris数组，如果待匹配Ability的skills配置中的uris数组中只要有一个可以匹配调用方传入的want参数中设置的uri和type即为匹配成功。 @@ -113,7 +116,7 @@ want-uri-type2 -## uri匹配规则 +### uri匹配规则 这里为了简化描述，称want中传入的uri为w_uri，待匹配Ability的skills配置中uri为s_uri，具体的匹配规则如下： @@ -139,7 +142,7 @@ > - **正则表达式**：`scheme://host:port/pathRegex` -## type匹配规则 +### type匹配规则 > **说明：** > 此小节所述的type匹配规则的适用性需建立在want参数内type不为空的基础上。当want参数内type为空时请参见[want参数的uri和type匹配规则](#want参数的uri和type匹配规则)。