• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 显式Want跳转切换应用链接跳转适配指导
2
3
4## 概述
5
6从API 12开始，已不再推荐三方应用使用指定Ability方式（即显式Want）拉起其他应用，推荐通过指定[应用链接](app-startup-overview.md#应用链接)的方式来实现。
7
8本章节介绍如何从显式Want跳转切换到应用链接跳转。
9
10## 启动其他应用的UIAbility
11
121. 将待跳转的应用安装到设备，在其对应UIAbility的[module.json5配置文件](../quick-start/module-configuration-file.md)中配置skills标签的entities字段、actions字段和uri字段：
13    - "actions"列表中包含"ohos.want.action.viewData"。
14    - "entities"列表中包含"entity.system.browsable"。
15    - "uris"列表中包含"scheme"为"https"且"domainVerify"为true的元素。uri的匹配规则参考[uri匹配](explicit-implicit-want-mappings.md#uri匹配规则), domainVerify为true代表开启域名检查，通过applinking匹配该应用时需经过配置的域名校验后才能匹配到。applinking域名配置具体可参考AppLinking。
16
17    ```json
18    {
19      "module": {
20        // ...
21        "abilities": [
22          {
23            // ...
24            "skills": [
25              {
26                "entities": [
27                  "entity.system.browsable"
28                ],
29                "actions": [
30                  "ohos.want.action.viewData"
31                ],
32                "uris": [
33                  {
34                    "scheme": "https",
35                    "host": "www.example.com",
36                  }
37                ],
38              "domainVerify": true
39              }
40            ]
41          }
42        ]
43      }
44    }
45    ```
46
472. 调用方通过[openLink](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextopenlink12)接口执行跳转，在接口入参需要传入转换后的link和配置[options](../reference/apis-ability-kit/js-apis-app-ability-openLinkOptions.md), 不再传入bundleName、moduleName和abilityName。系统会根据传入的link匹配到符合skill配置的应用。
48    - 当options中的appLinkingOnly为true时，匹配到的应用会经过应用市场域名检查（需联网）返回域名校验检查的唯一匹配项或未匹配结果。
49    - 当options中的appLinkingOnly为false时，会优先尝试以AppLinking的方式拉起，如果没有匹配的应用则改为使用DeepLinking的方式拉起目标应用。
50
51    具体请参考AppLinking开发指南。
52
53    ```ts
54    import { common } from '@kit.AbilityKit';
55    import OpenLinkOptions from '@ohos.app.ability.OpenLinkOptions';
56    import { BusinessError } from '@ohos.base';
57    import hilog from '@ohos.hilog';
58
59    const TAG: string = '[UIAbilityComponentsOpenLink]';
60    const DOMAIN_NUMBER: number = 0xFF00;
61
62    @Entry
63    @Component
64    struct Index {
65      build() {
66        Button('start link', { type: ButtonType.Capsule, stateEffect: true })
67          .width('87%')
68          .height('5%')
69          .margin({ bottom: '12vp' })
70          .onClick(() => {
71            let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
72            // let want: Want = {
73            //   bundleName: "com.test.example",
74            //   moduleName: "entry",
75            //   abilityName: "EntryAbility"
76            // };
77            // try {
78            //   context.startAbility(want)
79            //     .then(() => {
80            //       hilog.info(DOMAIN_NUMBER, TAG, 'startAbility success.');
81            //     }).catch((err: BusinessError) => {
82            //       hilog.error(DOMAIN_NUMBER, TAG, `startAbility failed. Code is ${err.code}, message is ${err.message}`);
83            //     })
84            // } catch (paramError) {
85            //   hilog.error(DOMAIN_NUMBER, TAG, `Failed to startAbility. Code is ${paramError.code}, message is ${paramError.message}`);
86            // }
87            let link: string = "https://www.example.com";
88            let openLinkOptions: OpenLinkOptions = {
89              // 匹配的abilities选项是否需要通过AppLinking域名校验，匹配到唯一配置过的应用ability
90              appLinkingOnly: true,
91              // 同want中的parameter，用于传递的参数
92              parameters: {demo_key: "demo_value"}
93            };
94
95            try {
96              context.openLink(link, openLinkOptions)
97                .then(() => {
98                  hilog.info(DOMAIN_NUMBER, TAG, 'open link success.');
99                }).catch((err: BusinessError) => {
100                  hilog.error(DOMAIN_NUMBER, TAG, `open link failed. Code is ${err.code}, message is ${err.message}`);
101                })
102            } catch (paramError) {
103              hilog.error(DOMAIN_NUMBER, TAG, `Failed to start link. Code is ${paramError.code}, message is ${paramError.message}`);
104            }
105          })
106      }
107    }
108    ```
109
110## 启动其他应用的UIAbility并获取返回结果
111
1121. 将待跳转的应用安装到设备，在其对应UIAbility的[module.json5配置文件](../quick-start/module-configuration-file.md)中配置skills标签的entities字段、actions字段和uri字段：
113
114    - "actions"列表中包含"ohos.want.action.viewData"。
115    - "entities"列表中包含"entity.system.browsable"。
116    - "uris"列表中包含"scheme"为"https"且"domainVerify"为true的元素。uri的匹配规则参考[uri匹配](explicit-implicit-want-mappings.md#uri匹配规则), domainVerify为true代表开启域名检查，通过applinking匹配该应用时需经过配置的域名校验后才能匹配到。applinking域名配置具体可参考App Linking。
117
118    ```json
119    {
120      "module": {
121        // ...
122        "abilities": [
123          {
124            // ...
125            "skills": [
126              {
127                "entities": [
128                  "entity.system.browsable"
129                ],
130                "actions": [
131                  "ohos.want.action.viewData"
132                ],
133                "uris": [
134                  {
135                    "scheme": "https",
136                    "host": "www.example.com",
137                  }
138                ],
139              "domainVerify": true
140              }
141            ]
142          }
143        ]
144      }
145    }
146    ```
147
1482. 调用方通过[openLink](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextopenlink12)接口执行跳转，在接口入参需要传入转换后的link和配置[options](../reference/apis-ability-kit/js-apis-app-ability-openLinkOptions.md), 不再传入bundleName、moduleName和abilityName。系统会根据传入的link匹配到符合skills配置的应用。AbilityResult回调结果返回通过入参传入回调函数，在启动ability停止自身后返回给调用方的信息。启动成功和失败结果仍通过Promise返回。<br>
149    - 当options中的appLinkingOnly为true时，匹配到的应用会经过应用市场域名检查（需联网）返回域名校验检查的唯一匹配项或未匹配结果。
150    - 当options中的appLinkingOnly为false时，会优先尝试以AppLinking的方式拉起，如果没有匹配的应用则改为使用DeepLinking的方式拉起目标应用。
151    <br>具体请参考AppLinking开发指南。
152
153    ```ts
154    import { common } from '@kit.AbilityKit';
155    import OpenLinkOptions from '@ohos.app.ability.OpenLinkOptions';
156    import { BusinessError } from '@ohos.base';
157    import hilog from '@ohos.hilog';
158
159    const TAG: string = '[UIAbilityComponentsOpenLink]';
160    const DOMAIN_NUMBER: number = 0xFF00;
161
162    @Entry
163    @Component
164    struct Index {
165      build() {
166        Button('start link', { type: ButtonType.Capsule, stateEffect: true })
167          .width('87%')
168          .height('5%')
169          .margin({ bottom: '12vp' })
170          .onClick(() => {
171            let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
172            // let want: Want = {
173            //   bundleName: "com.test.example",
174            //   moduleName: "entry",
175            //   abilityName: "EntryAbility"
176            // };
177            // try {
178            //   context.startAbilityForResult(want)
179            //     .then((data) => {
180            //       hilog.info(DOMAIN_NUMBER, TAG, 'startAbility success. data:' + JSON.stringify(data));
181            //     }).catch((err: BusinessError) => {
182            //       hilog.error(DOMAIN_NUMBER, TAG, `startAbility failed. Code is ${err.code}, message is ${err.message}`);
183            //     })
184            // } catch (paramError) {
185            //   hilog.error(DOMAIN_NUMBER, TAG, `Failed to startAbility. Code is ${paramError.code}, message is ${paramError.message}`);
186            // }
187            let link: string = "https://www.example.com";
188            let openLinkOptions: OpenLinkOptions = {
189              // 匹配的abilities选项是否需要通过AppLinking域名校验，匹配到唯一配置过的应用ability
190              appLinkingOnly: true,
191              // 同want中的parameter，用于传递的参数
192              parameters: {demo_key: "demo_value"}
193            };
194
195            try {
196              context.openLink(link, openLinkOptions, (err, data) => {
197                // AbilityResult callback回调，仅在被拉起ability死亡时触发
198                hilog.info(DOMAIN_NUMBER, TAG, 'open link success. Callback result:' + JSON.stringify(data));
199              }).then(() => {
200                hilog.info(DOMAIN_NUMBER, TAG, 'open link success.');
201              }).catch((err: BusinessError) => {
202                hilog.error(DOMAIN_NUMBER, TAG, `open link failed. Code is ${err.code}, message is ${err.message}`);
203              })
204            } catch (paramError) {
205              hilog.error(DOMAIN_NUMBER, TAG, `Failed to start link. Code is ${paramError.code}, message is ${paramError.message}`);
206            }
207          })
208      }
209    }
210    ```