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