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