1# @ohos.ability.featureAbility (FeatureAbility模块) 2 3FeatureAbility模块提供与用户进行交互的Ability的能力，包括启动新的Ability、停止Ability、获取dataAbilityHelper对象、获取当前Ability对应的窗口，连接断连Service等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 本模块接口仅可在FA模型下使用。Stage模型下需使用[UIAbility模块](js-apis-app-ability-uiAbility.md)和[UIAbilityContext模块](js-apis-inner-application-uiAbilityContext.md)。 9 10## 使用限制 11 12FeatureAbility模块的接口只能在Page类型的Ability中调用 13 14## 导入模块 15 16```ts 17import featureAbility from '@ohos.ability.featureAbility'; 18``` 19 20## featureAbility.startAbility 21 22startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<number>): void 23 24启动新的Ability（callback形式）。 25 26使用规则： 27 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 28 - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 29 - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) 30 31**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 32 33**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.startAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)。 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| --------- | ---------------------------------------- | ---- | -------------- | 39| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示被启动的Ability。 | 40| callback | AsyncCallback\<number> | 是 | 回调函数。当启动Ability成功，err为undefined，data为0表示启动成功，data为其他表示启动失败；否则为错误对象。 | 41 42**示例：** 43 44```ts 45import featureAbility from '@ohos.ability.featureAbility'; 46import wantConstant from '@ohos.app.ability.wantConstant'; 47featureAbility.startAbility( 48 { 49 want: 50 { 51 action: '', 52 entities: [''], 53 type: '', 54 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 55 deviceId: '', 56 bundleName: 'com.example.myapplication', 57 /* FA模型中abilityName由package + Ability name组成 */ 58 abilityName: 'com.example.myapplication.secondAbility', 59 uri: '' 60 }, 61 }, 62 (error, data) => { 63 if (error && error.code !== 0) { 64 console.error(`startAbility fail, error: ${JSON.stringify(error)}`); 65 } else { 66 console.log(`startAbility success, data: ${JSON.stringify(data)}`); 67 } 68 } 69); 70``` 71 72 73 74## featureAbility.startAbility 75 76startAbility(parameter: StartAbilityParameter): Promise\<number> 77 78启动新的Ability（Promise形式）。 79 80使用规则： 81 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 82 - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 83 - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) 84 85**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 86 87**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.startAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability-2)。 88 89**参数：** 90 91| 参数名 | 类型 | 必填 | 说明 | 92| --------- | ---------------------------------------- | ---- | -------------- | 93| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示被启动的Ability。 | 94 95**返回值：** 96 97| 类型 | 说明 | 98| ---------------------------------------- | ------- | 99| Promise\<number> | Promise对象。返回0表示启动成功，返回其他表示启动失败。 | 100 101**示例：** 102 103```ts 104import featureAbility from '@ohos.ability.featureAbility'; 105import wantConstant from '@ohos.app.ability.wantConstant'; 106featureAbility.startAbility( 107 { 108 want: 109 { 110 action: 'ohos.want.action.home', 111 entities: ['entity.system.home'], 112 type: 'MIMETYPE', 113 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 114 deviceId: '', 115 bundleName: 'com.example.myapplication', 116 /* FA模型中abilityName由package + Ability name组成 */ 117 abilityName: 'com.example.myapplication.secondAbility', 118 uri: '' 119 }, 120 } 121).then((data) => { 122 console.info(`startAbility data: ${JSON.stringify(data)}`); 123}); 124``` 125 126## featureAbility.acquireDataAbilityHelper<sup>7+</sup> 127 128acquireDataAbilityHelper(uri: string): DataAbilityHelper 129 130获取dataAbilityHelper对象。 131 132使用规则： 133 - 跨应用访问dataAbility，对端应用需配置关联启动 134 - 调用方应用位于后台时，使用该接口访问dataAbility需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限（基于API 8或更早版本SDK开发的应用在启动DataAbility组件时不受此限制的约束） 135 - 跨应用场景下，目标dataAbility的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 136 - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) 137 138**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 139 140**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[dataShare.createDataShareHelper](../apis-arkdata/js-apis-data-dataShare-sys.md#datasharecreatedatasharehelper)。 141 142**参数：** 143 144| 参数名 | 类型 | 必填 | 说明 | 145| ---- | ------ | ---- | ------------ | 146| uri | string | 是 | 表示要打开的文件的路径。 | 147 148**返回值：** 149 150| 类型 | 说明 | 151| ----------------- | ------------------------------- | 152| [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | 用来协助其他Ability访问DataAbility的工具类。 | 153 154**示例：** 155 156```ts 157import featureAbility from '@ohos.ability.featureAbility'; 158let dataAbilityHelper = featureAbility.acquireDataAbilityHelper( 159 'dataability:///com.example.DataAbility' 160); 161``` 162 163## featureAbility.startAbilityForResult<sup>7+</sup> 164 165startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback\<AbilityResult>): void 166 167启动一个Ability。Ability被启动后，有如下情况(callback形式): 168 - 正常情况下可通过调用[terminateSelfWithResult](#featureabilityterminateselfwithresult7)接口使之终止并且返回结果给调用方。 169 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 170 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](#featureabilityterminateselfwithresult7)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。 171 172使用规则： 173 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 174 - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 175 - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) 176 177**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 178 179**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.startAbilityForResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartabilityforresult)。 180 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| --------- | ---------------------------------------- | ---- | -------------- | 186| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示被启动的Ability。 | 187| callback | AsyncCallback\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 回调函数。当启动Ability成功，err为undefined，data为ability的启动结果；否则为错误对象。 | 188 189**示例：** 190 191```ts 192import featureAbility from '@ohos.ability.featureAbility'; 193import wantConstant from '@ohos.app.ability.wantConstant'; 194featureAbility.startAbilityForResult( 195 { 196 want: 197 { 198 action: 'ohos.want.action.home', 199 entities: ['entity.system.home'], 200 type: 'MIMETYPE', 201 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 202 deviceId: '', 203 bundleName: 'com.example.myapplication', 204 /* FA模型中abilityName由package + Ability name组成 */ 205 abilityName: 'com.example.myapplication.secondAbility', 206 uri:'' 207 }, 208 }, 209 (error, data) => { 210 if (error && error.code !== 0) { 211 console.error(`startAbilityForResult fail, error: ${JSON.stringify(error)}`); 212 } else { 213 console.log(`startAbilityForResult success, data: ${JSON.stringify(data)}`); 214 } 215 } 216); 217``` 218 219## featureAbility.startAbilityForResult<sup>7+</sup> 220 221startAbilityForResult(parameter: StartAbilityParameter): Promise\<AbilityResult> 222 223启动一个Ability。Ability被启动后，有如下情况(Promise形式): 224 - 正常情况下可通过调用[terminateSelfWithResult](#featureabilityterminateselfwithresult7)接口使之终止并且返回结果给调用方。 225 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 226 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](#featureabilityterminateselfwithresult7)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。 227 228使用规则： 229 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 230 - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 231 - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) 232 233**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 234 235**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.startAbilityForResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartabilityforresult-2)。 236 237**参数：** 238 239| 参数名 | 类型 | 必填 | 说明 | 240| --------- | ---------------------------------------- | ---- | ------------- | 241| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示被启动的Ability | 242 243**返回值：** 244 245| 类型 | 说明 | 246| ---------------------------------------- | ------- | 247| Promise\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise对象，返回启动Ability的结果。 | 248 249**示例：** 250 251```ts 252import featureAbility from '@ohos.ability.featureAbility'; 253import wantConstant from '@ohos.app.ability.wantConstant'; 254featureAbility.startAbilityForResult( 255 { 256 want: 257 { 258 action: 'ohos.want.action.home', 259 entities: ['entity.system.home'], 260 type: 'MIMETYPE', 261 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 262 deviceId: '', 263 bundleName: 'com.example.myapplication', 264 /* FA模型中abilityName由package + Ability name组成 */ 265 abilityName: 'com.example.myapplication.secondAbility', 266 uri:'', 267 parameters: 268 { 269 mykey0: 1111, 270 mykey1: [1, 2, 3], 271 mykey2: '[1, 2, 3]', 272 mykey3: 'xxxxxxxxxxxxxxxxxxxxxx', 273 mykey4: [1, 15], 274 mykey5: [false, true, false], 275 mykey6: ['aaaaaa', 'bbbbb', 'ccccccccccc'], 276 mykey7: true, 277 }, 278 }, 279 }, 280).then((data) => { 281 console.info(`startAbilityForResult data: ${JSON.stringify(data)}`); 282}); 283``` 284 285## featureAbility.terminateSelfWithResult<sup>7+</sup> 286 287terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback\<void>): void 288 289停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（callback形式）。 290 291**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 292 293**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)。 294 295**参数：** 296 297| 参数名 | 类型 | 必填 | 说明 | 298| --------- | ------------------------------- | ---- | -------------- | 299| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 表示停止Ability之后返回的结果。 | 300| callback | AsyncCallback\<void> | 是 | 回调函数。当停止当前Ability成功，err为undefined，否则为错误对象。 | 301 302**示例：** 303 304```ts 305import featureAbility from '@ohos.ability.featureAbility'; 306import wantConstant from '@ohos.app.ability.wantConstant'; 307featureAbility.terminateSelfWithResult( 308 { 309 resultCode: 1, 310 want: 311 { 312 action: 'ohos.want.action.home', 313 entities: ['entity.system.home'], 314 type: 'MIMETYPE', 315 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 316 deviceId: '', 317 bundleName: 'com.example.myapplication', 318 /* FA模型中abilityName由package + Ability name组成 */ 319 abilityName: 'com.example.myapplication.secondAbility', 320 uri:'', 321 parameters: { 322 mykey0: 2222, 323 mykey1: [1, 2, 3], 324 mykey2: '[1, 2, 3]', 325 mykey3: 'ssssssssssssssssssssssssss', 326 mykey4: [1, 15], 327 mykey5: [false, true, false], 328 mykey6: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 329 mykey7: true, 330 } 331 }, 332 }, 333 (error) => { 334 console.error(`error: ${JSON.stringify(error)}`); 335 } 336); 337``` 338 339## featureAbility.terminateSelfWithResult<sup>7+</sup> 340 341terminateSelfWithResult(parameter: AbilityResult): Promise\<void> 342 343停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（Promise形式）。 344 345**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 346 347**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult-1)。 348 349**参数：** 350 351| 参数名 | 类型 | 必填 | 说明 | 352| --------- | ------------------------------- | ---- | ------------- | 353| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 表示停止Ability之后返回的结果 | 354 355**返回值：** 356 357| 类型 | 说明 | 358| -------------- | --------------- | 359| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 360 361**示例：** 362 363```ts 364import featureAbility from '@ohos.ability.featureAbility'; 365import wantConstant from '@ohos.app.ability.wantConstant'; 366featureAbility.terminateSelfWithResult( 367 { 368 resultCode: 1, 369 want: 370 { 371 action: 'ohos.want.action.home', 372 entities: ['entity.system.home'], 373 type: 'MIMETYPE', 374 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 375 deviceId: '', 376 bundleName: 'com.example.myapplication', 377 /* FA模型中abilityName由package + Ability name组成 */ 378 abilityName: 'com.example.myapplication.secondAbility', 379 uri:'', 380 parameters: { 381 mykey0: 2222, 382 mykey1: [1, 2, 3], 383 mykey2: '[1, 2, 3]', 384 mykey3: 'ssssssssssssssssssssssssss', 385 mykey4: [1, 15], 386 mykey5: [false, true, false], 387 mykey6: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 388 mykey7: true, 389 } 390 }, 391 } 392).then(() => { 393 console.info('==========================>terminateSelfWithResult=======================>'); 394}); 395``` 396 397## featureAbility.hasWindowFocus<sup>7+<sup> 398 399hasWindowFocus(callback: AsyncCallback\<boolean>): void 400 401检查Ability的主窗口是否具有窗口焦点（callback形式）。 402 403**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 404 405**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[on('windowEvent')](../apis-arkui/js-apis-window.md#onwindowevent10)。 406 407**参数：** 408 409| 参数名 | 类型 | 必填 | 说明 | 410| -------- | ----------------------- | ---- | ---------------------------------------- | 411| callback | AsyncCallback\<boolean> | 是 | 以callback的形式返回结果。<br>如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | 412 413**示例：** 414 415```ts 416import featureAbility from '@ohos.ability.featureAbility'; 417featureAbility.hasWindowFocus((error, data) => { 418 if (error && error.code !== 0) { 419 console.error(`hasWindowFocus fail, error: ${JSON.stringify(error)}`); 420 } else { 421 console.log(`hasWindowFocus success, data: ${JSON.stringify(data)}`); 422 } 423}); 424``` 425 426## featureAbility.hasWindowFocus<sup>7+<sup> 427 428hasWindowFocus(): Promise\<boolean> 429 430检查Ability的主窗口是否具有窗口焦点（Promise形式）。 431 432**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 433 434**返回值：** 435 436| 类型 | 说明 | 437| ----------------- | ------------------------------------- | 438| Promise\<boolean> | Promise形式返回结果，如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | 439 440**示例：** 441 442```ts 443import featureAbility from '@ohos.ability.featureAbility'; 444featureAbility.hasWindowFocus().then((data) => { 445 console.info(`hasWindowFocus data: ${JSON.stringify(data)}`); 446}); 447``` 448 449## featureAbility.getWant 450 451getWant(callback: AsyncCallback\<Want>): void 452 453获取要拉起的Ability对应的Want（callback形式）。 454 455**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 456 457**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbility.launchWant](js-apis-app-ability-uiAbility.md#属性)。 458 459**参数：** 460 461| 参数名 | 类型 | 必填 | 说明 | 462| -------- | ----------------------------- | ---- | --------- | 463| callback | AsyncCallback\<[Want](js-apis-application-want.md)> | 是 | 以callback的形式返回want。 | 464 465**示例：** 466 467```ts 468import featureAbility from '@ohos.ability.featureAbility'; 469featureAbility.getWant((error, data) => { 470 if (error && error.code !== 0) { 471 console.error(`getWant fail, error: ${JSON.stringify(error)}`); 472 } else { 473 console.log(`getWant success, data: ${JSON.stringify(data)}`); 474 } 475}); 476``` 477 478## featureAbility.getWant 479 480getWant(): Promise\<Want> 481 482获取要拉起的Ability对应的Want（Promise形式）。 483 484**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 485 486**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbility.launchWant](js-apis-app-ability-uiAbility.md#属性)。 487 488**返回值：** 489 490| 类型 | 说明 | 491| ----------------------- | ---------------- | 492| Promise\<[Want](js-apis-application-want.md)> | 以Promise的形式返回want。 | 493 494**示例：** 495 496```ts 497import featureAbility from '@ohos.ability.featureAbility'; 498featureAbility.getWant().then((data) => { 499 console.info(`getWant data: ${JSON.stringify(data)}`); 500}); 501``` 502 503## featureAbility.getContext 504 505getContext(): Context 506 507获取应用上下文。 508 509**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 510 511**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbility.context](js-apis-app-ability-uiAbility.md#属性)。 512 513**返回值：** 514 515| 类型 | 说明 | 516| ------- | ---------- | 517| Context | 返回应用程序上下文。 | 518 519**示例：** 520 521```ts 522import featureAbility from '@ohos.ability.featureAbility'; 523let context = featureAbility.getContext(); 524context.getBundleName((error, data) => { 525 if (error && error.code !== 0) { 526 console.error(`getBundleName fail, error: ${JSON.stringify(error)}`); 527 } else { 528 console.log(`getBundleName success, data: ${JSON.stringify(data)}`); 529 } 530}); 531``` 532 533## featureAbility.terminateSelf<sup>7+</sup> 534 535terminateSelf(callback: AsyncCallback\<void>): void 536 537停止当前的Ability（callback形式）。 538 539**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 540 541**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.terminateSelf](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)。 542 543**参数：** 544 545| 参数名 | 类型 | 必填 | 说明 | 546| -------- | -------------------- | ---- | -------- | 547| callback | AsyncCallback\<void> | 是 | 以callback的形式返回停止当前Ability结果 | 548 549**示例：** 550 551```ts 552import featureAbility from '@ohos.ability.featureAbility'; 553featureAbility.terminateSelf( 554 (error) => { 555 console.error(`error: ${JSON.stringify(error)}`); 556 } 557) 558``` 559 560## featureAbility.terminateSelf<sup>7+</sup> 561 562terminateSelf(): Promise\<void> 563 564停止当前的Ability（Promise形式）。 565 566**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 567 568**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.terminateSelf](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself-1)。 569 570**返回值：** 571 572| 类型 | 说明 | 573| -------------- | ---------------- | 574| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 575 576**示例：** 577 578```ts 579import featureAbility from '@ohos.ability.featureAbility'; 580featureAbility.terminateSelf().then(() => { 581 console.info('==========================>terminateSelf=======================>'); 582}); 583``` 584 585## featureAbility.connectAbility<sup>7+</sup> 586 587connectAbility(request: Want, options:ConnectOptions): number 588 589将当前Ability与指定的ServiceAbility进行连接。 590 591使用规则： 592 - 跨应用连接serviceAbility，对端应用需配置关联启动 593 - 调用方应用位于后台时，使用该接口连接serviceAbility需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限（基于API 8或更早版本SDK开发的应用在启动ServiceAbility组件时不受此限制的约束） 594 - 跨应用场景下，目标serviceAbility的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 595 - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) 596 597**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 598 599**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.connectServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability)。 600 601**参数：** 602 603| 参数名 | 类型 | 必填 | 说明 | 604| ------- | -------------- | ---- | --------------------- | 605| request | [Want](js-apis-application-want.md) | 是 | 表示被连接的ServiceAbility。 | 606| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | 表示连接回调函数。 | 607 608**返回值：** 609 610| 类型 | 说明 | 611| ------ | -------------------- | 612| number | 连接的ServiceAbility的ID(ID从0开始自增，每连接成功一次ID加1)。 | 613 614**示例：** 615 616```ts 617import rpc from '@ohos.rpc'; 618import featureAbility from '@ohos.ability.featureAbility'; 619 620let connectId = featureAbility.connectAbility( 621 { 622 deviceId: '', 623 bundleName: 'com.ix.ServiceAbility', 624 abilityName: 'com.ix.ServiceAbility.ServiceAbilityA', 625 }, 626 { 627 onConnect: (element, remote) => { 628 console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`); 629 }, 630 onDisconnect: (element) => { 631 console.log(`ConnectAbility onDisconnect element.deviceId : ${element.deviceId}`) 632 }, 633 onFailed: (code) => { 634 console.error(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`) 635 }, 636 }, 637); 638``` 639 640## featureAbility.disconnectAbility<sup>7+</sup> 641 642disconnectAbility(connection: number, callback:AsyncCallback\<void>): void 643 644断开与指定ServiceAbility的连接（callback形式）。 645 646**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 647 648**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.disconnectAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectserviceextensionability-1)。 649 650**参数：** 651 652| 参数名 | 类型 | 必填 | 说明 | 653| ---------- | -------------------- | ---- | ----------------------- | 654| connection | number | 是 | 表示断开连接的ServiceAbility的ID。 | 655| callback | AsyncCallback\<void> | 是 | 以callback的形式返回断开连接结果 | 656 657**示例：** 658 659```ts 660import rpc from '@ohos.rpc'; 661import featureAbility from '@ohos.ability.featureAbility'; 662 663let connectId = featureAbility.connectAbility( 664 { 665 bundleName: 'com.ix.ServiceAbility', 666 abilityName: 'com.ix.ServiceAbility.ServiceAbilityA', 667 }, 668 { 669 onConnect: (element, remote) => { 670 console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`); 671 }, 672 onDisconnect: (element) => { 673 console.log(`ConnectAbility onDisconnect element.deviceId : ${element.deviceId}`); 674 }, 675 onFailed: (code) => { 676 console.error(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`); 677 }, 678 }, 679); 680 681featureAbility.disconnectAbility(connectId, (error) => { 682 if (error && error.code !== 0) { 683 console.error(`disconnectAbility fail, connectId: ${connectId}, error: ${JSON.stringify(error)}`); 684 } else { 685 console.log(`disconnectAbility success， connectId: ${connectId}`); 686 } 687}); 688``` 689 690## featureAbility.disconnectAbility<sup>7+</sup> 691 692disconnectAbility(connection: number): Promise\<void> 693 694断开与指定ServiceAbility的连接（Promise形式）。 695 696**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 697 698**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[UIAbilityContext.disconnectAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectserviceextensionability)。 699 700**参数：** 701 702| 参数名 | 类型 | 必填 | 说明 | 703| ---------- | ------ | ---- | ----------------------- | 704| connection | number | 是 | 表示断开连接的ServiceAbility的ID。 | 705 706**返回值：** 707 708| 类型 | 说明 | 709| -------------- | --------------- | 710| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 711 712**示例：** 713 714```ts 715import rpc from '@ohos.rpc'; 716import featureAbility from '@ohos.ability.featureAbility'; 717import { BusinessError } from '@ohos.base'; 718 719let connectId = featureAbility.connectAbility( 720 { 721 bundleName: 'com.ix.ServiceAbility', 722 abilityName: 'com.ix.ServiceAbility.ServiceAbilityA', 723 }, 724 { 725 onConnect: (element, remote) => { 726 console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`); 727 }, 728 onDisconnect: (element) => { 729 console.log(`ConnectAbility onDisconnect element.deviceId : ${element.deviceId}`); 730 }, 731 onFailed: (code) => { 732 console.error(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`); 733 }, 734 }, 735); 736 737featureAbility.disconnectAbility(connectId).then(() => { 738 console.log('disconnectAbility success') 739}).catch((error: BusinessError)=>{ 740 console.error(`featureAbilityTest result errCode : ${error.code}`); 741}); 742``` 743 744 745## featureAbility.getWindow<sup>7+</sup> 746 747getWindow(callback: AsyncCallback\<window.Window>): void 748 749获取当前Ability对应的窗口（callback形式）。 750 751**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 752 753**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[window.getLastWindow](../apis-arkui/js-apis-window.md#windowgetlastwindow9)。 754 755**参数：** 756 757| 参数名 | 类型 | 必填 | 说明 | 758| -------- | ----------------------------- | ---- | ----------------------------- | 759| callback | AsyncCallback\<[window.Window](../apis-arkui/js-apis-window.md#window)> | 是 | callback形式返回当前Ability对应的窗口。 | 760 761**示例：** 762 763```ts 764import featureAbility from '@ohos.ability.featureAbility'; 765import { BusinessError } from '@ohos.base'; 766import window from '@ohos.window'; 767 768featureAbility.getWindow((error: BusinessError, data: window.Window) => { 769 if (error && error.code !== 0) { 770 console.error(`getWindow fail, error: ${JSON.stringify(error)}`); 771 } else { 772 console.log(`getWindow success, data: ${typeof(data)}`); 773 } 774}); 775``` 776 777## featureAbility.getWindow<sup>7+</sup> 778 779getWindow(): Promise\<window.Window> 780 781获取当前Ability对应的窗口（Promise形式）。 782 783**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 784 785**说明**：本接口仅可在FA模型下使用。Stage模型下需使用[window.getLastWindow](../apis-arkui/js-apis-window.md#windowgetlastwindow9-1)。 786 787**返回值：** 788 789| 类型 | 说明 | 790| ----------------------- | ----------------------------- | 791| Promise\<[window.Window](../apis-arkui/js-apis-window.md#window)> | Promise形式返回当前Ability对应的窗口。 | 792 793**示例：** 794 795```ts 796import featureAbility from '@ohos.ability.featureAbility'; 797import { BusinessError } from '@ohos.base'; 798import window from '@ohos.window'; 799 800featureAbility.getWindow().then((data: window.Window) => { 801 console.log(`getWindow success, data: ${typeof(data)}`); 802}).catch((error: BusinessError)=>{ 803 console.error(`getWindow fail, error: ${JSON.stringify(error)}`); 804}); 805``` 806 807## AbilityWindowConfiguration 808 809表示当前Ability对应的窗口配置项，使用时通过featureAbility.AbilityWindowConfiguration获取。 810 811**示例：** 812 813``` 814featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED 815``` 816 817**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 818 819| 名称 | 值 | 说明 | 820| ---------------------------------------- | ---- | ---------------------------------------- | 821| WINDOW_MODE_UNDEFINED<sup>7+</sup> | 0 | 未定义。 | 822| WINDOW_MODE_FULLSCREEN<sup>7+</sup> | 1 | 全屏。 | 823| WINDOW_MODE_SPLIT_PRIMARY<sup>7+</sup> | 100 | 屏幕如果是水平方向表示左分屏，屏幕如果是竖直方向表示上分屏。 | 824| WINDOW_MODE_SPLIT_SECONDARY<sup>7+</sup> | 101 | 屏幕如果是水平方向表示右分屏，屏幕如果是竖直方向表示下分屏。 | 825| WINDOW_MODE_FLOATING<sup>7+</sup> | 102 | 悬浮窗。 | 826 827 828## AbilityStartSetting 829 830表示当前Ability对应的窗口属性，abilityStartSetting属性是一个定义为[key: string]: any的对象，key对应设定类型为：AbilityStartSetting枚举类型，value对应设定类型为：AbilityWindowConfiguration枚举类型。 831 832使用时通过featureAbility.AbilityStartSetting获取。 833 834**示例：** 835 836``` 837featureAbility.AbilityStartSetting.BOUNDS_KEY 838``` 839 840**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 841 842| 名称 | 值 | 说明 | 843| ---------------------------- | --------------- | ---------------------------------------- | 844| BOUNDS_KEY<sup>7+</sup> | 'abilityBounds' | 窗口显示大小属性的参数名。 | 845| WINDOW_MODE_KEY<sup>7+</sup> | 'windowMode' | 窗口显示模式属性的参数名。| 846| DISPLAY_ID_KEY<sup>7+</sup> | 'displayId' | 窗口显示设备ID属性的参数名。 | 847 848## ErrorCode<sup>7+</sup> 849 850定义启动Ability时返回的错误码。 851 852**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 853 854| 名称 | 值 | 说明 | 855| ------------------------------ | ---- | ---------------------------------------- | 856| NO_ERROR | 0 | 没有异常。 | 857| INVALID_PARAMETER | -1 | 无效的参数。 | 858| ABILITY_NOT_FOUND | -2 | 找不到ABILITY。 | 859| PERMISSION_DENY | -3 | 权限拒绝。 | 860 861## DataAbilityOperationType 862 863表示数据的操作类型。DataAbility批量操作数据时可以通过该枚举值指定操作类型 864 865**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 866 867| 名称 | 值 | 说明 | 868| ------------------------ | ---- | ---------------------------------------- | 869| TYPE_INSERT<sup>7+</sup> | 1 | 插入类型。 | 870| TYPE_UPDATE<sup>7+</sup> | 2 | 修改类型。 | 871| TYPE_DELETE<sup>7+</sup> | 3 | 删除类型。 | 872| TYPE_ASSERT<sup>7+</sup> | 4 | 声明类型。 |