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