1# FeatureAbility 2 3> **NOTE** 4> 5> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 6> API version 9 is a canary version for trial use. The APIs of this version may be unstable. 7 8## Constraints 9 10APIs of the **FeatureAbility** module can be called only by Page abilities. 11 12## Modules to Import 13 14``` 15import featureAbility from '@ohos.ability.featureAbility' 16``` 17 18## featureAbility.startAbility 19 20startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<number>): void 21 22Starts an ability. This API uses an asynchronous callback to return the result. 23 24**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 25 26**Parameters** 27 28| Name | Type | Mandatory | Description | 29| --------- | ---------------------------------------- | ---- | -------------- | 30| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| 31| callback | AsyncCallback\<number> | Yes | Callback used to return the result. | 32 33**Example** 34 35```javascript 36import featureAbility from '@ohos.ability.featureAbility' 37import wantConstant from '@ohos.ability.wantConstant' 38featureAbility.startAbility( 39 { 40 want: 41 { 42 action: "", 43 entities: [""], 44 type: "", 45 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 46 deviceId: "", 47 bundleName: "com.example.startability", 48 abilityName: "com.example.startability.MainAbility", 49 uri: "" 50 }, 51 }, 52 (err, data) => { 53 console.info("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)) 54 } 55); 56``` 57 58 59 60## featureAbility.startAbility 61 62startAbility(parameter: StartAbilityParameter): Promise\<number> 63 64Starts an ability. This API uses a promise to return the result. 65 66**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 67 68**Parameters** 69 70| Name | Type | Mandatory | Description | 71| --------- | ---------------------------------------- | ---- | -------------- | 72| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| 73 74**Example** 75 76```javascript 77import featureAbility from '@ohos.ability.featureAbility' 78import wantConstant from '@ohos.ability.wantConstant' 79featureAbility.startAbility( 80 { 81 want: 82 { 83 action: "action.system.home", 84 entities: ["entity.system.home"], 85 type: "MIMETYPE", 86 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 87 deviceId: "", 88 bundleName: "com.example.startability", 89 abilityName: "com.example.startability.MainAbility", 90 uri: "" 91 }, 92 } 93 ).then((data) => { 94 console.info("==========================>startAbility=======================>"); 95}); 96``` 97 98## featureAbility.acquireDataAbilityHelper<sup>7+</sup> 99 100acquireDataAbilityHelper(uri: string): DataAbilityHelper 101 102Obtains a **dataAbilityHelper** object. 103 104**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 105 106**Parameters** 107 108| Name | Type | Mandatory | Description | 109| ---- | ------ | ---- | ------------ | 110| uri | string | Yes | URI of the file to open.| 111 112**Return value** 113 114| Type | Description | 115| ----------------- | ------------------------------- | 116| DataAbilityHelper | A utility class used to help other abilities access the Data ability.| 117 118**Example** 119 120```javascript 121import featureAbility from '@ohos.ability.featureAbility' 122featureAbility.acquireDataAbilityHelper( 123 "dataability:///com.example.DataAbility" 124) 125``` 126 127## featureAbility.startAbilityForResult<sup>7+</sup> 128 129startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback\<AbilityResult>): void 130 131Starts an ability. This API uses an asynchronous callback to return the execution result when the ability is destroyed. 132 133**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 134 135**Parameters** 136 137| Name | Type | Mandatory | Description | 138| --------- | ---------------------------------------- | ---- | -------------- | 139| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| 140| callback | AsyncCallback\<[AbilityResult](#abilityresult)> | Yes | Callback used to return the result. | 141 142**Example** 143 144```javascript 145import featureAbility from '@ohos.ability.featureAbility'; 146import wantConstant from '@ohos.ability.wantConstant' 147featureAbility.startAbilityForResult( 148 { 149 want: 150 { 151 action: "action.system.home", 152 entities: ["entity.system.home"], 153 type: "MIMETYPE", 154 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 155 deviceId: "", 156 bundleName: "com.example.featureabilitytest", 157 abilityName: "com.example.featureabilitytest.MainAbility", 158 uri:"" 159 }, 160 }, 161 (err, data) => { 162 console.info("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)) 163 } 164) 165``` 166 167## featureAbility.startAbilityForResult<sup>7+</sup> 168 169startAbilityForResult(parameter: StartAbilityParameter): Promise\<AbilityResult> 170 171Starts an ability. This API uses a promise to return the execution result when the ability is destroyed. 172 173**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 174 175**Parameters** 176 177| Name | Type | Mandatory | Description | 178| --------- | ---------------------------------------- | ---- | ------------- | 179| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| 180 181**Return value** 182 183| Type | Description | 184| ---------------------------------------- | ------- | 185| Promise\<[AbilityResult](#abilityresult)> | Promised returned with the execution result.| 186 187**Example** 188 189```javascript 190import featureAbility from '@ohos.ability.featureAbility'; 191import wantConstant from '@ohos.ability.wantConstant' 192featureAbility.startAbilityForResult( 193 { 194 want: 195 { 196 action: "action.system.home", 197 entities: ["entity.system.home"], 198 type: "MIMETYPE", 199 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 200 deviceId: "", 201 bundleName: "com.example.featureabilitytest", 202 abilityName: "com.example.featureabilitytest.MainAbility", 203 uri:"", 204 parameters: 205 { 206 mykey0: 1111, 207 mykey1: [1, 2, 3], 208 mykey2: "[1, 2, 3]", 209 mykey3: "xxxxxxxxxxxxxxxxxxxxxx", 210 mykey4: [1, 15], 211 mykey5: [false, true, false], 212 mykey6: ["aaaaaa", "bbbbb", "ccccccccccc"], 213 mykey7: true, 214 }, 215 }, 216 requestCode: 2, 217 }, 218).then((data) => { 219 console.info("==========================>startAbilityForResult=======================>"); 220}); 221``` 222 223## featureAbility.terminateSelfWithResult<sup>7+</sup> 224 225terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback\<void>): void 226 227Destroys this Page ability, with the result code and data sent to the caller. This API uses an asynchronous callback to return the result. 228 229**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 230 231**Parameters** 232 233| Name | Type | Mandatory | Description | 234| --------- | ------------------------------- | ---- | -------------- | 235| parameter | [AbilityResult](#abilityresult) | Yes | Ability to destroy.| 236| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 237 238**Example** 239 240```javascript 241import featureAbility from '@ohos.ability.featureAbility' 242import wantConstant from '@ohos.ability.wantConstant' 243featureAbility.terminateSelfWithResult( 244 { 245 resultCode: 1, 246 want: 247 { 248 action: "action.system.home", 249 entities: ["entity.system.home"], 250 type: "MIMETYPE", 251 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 252 deviceId: "", 253 bundleName: "com.example.featureabilitytest", 254 abilityName: "com.example.featureabilitytest.MainAbility", 255 uri:"", 256 parameters: { 257 mykey0: 2222, 258 mykey1: [1, 2, 3], 259 mykey2: "[1, 2, 3]", 260 mykey3: "ssssssssssssssssssssssssss", 261 mykey4: [1, 15], 262 mykey5: [false, true, false], 263 mykey6: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], 264 mykey7: true, 265 } 266 }, 267 }, 268 (err) => { 269 console.info("err: " + JSON.stringify(err)) 270 } 271); 272``` 273 274## featureAbility.terminateSelfWithResult<sup>7+</sup> 275 276terminateSelfWithResult(parameter: AbilityResult): Promise\<void> 277 278Destroys this Page ability, with the result code and data sent to the caller. This API uses a promise to return the result. 279 280**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 281 282**Parameters** 283 284| Name | Type | Mandatory | Description | 285| --------- | ------------------------------- | ---- | ------------- | 286| parameter | [AbilityResult](#abilityresult) | Yes | Ability to destroy.| 287 288**Return value** 289 290| Type | Description | 291| -------------- | --------------- | 292| Promise\<void> | Promise used to return the result.| 293 294**Example** 295 296```javascript 297import featureAbility from '@ohos.ability.featureAbility'; 298import wantConstant from '@ohos.ability.wantConstant' 299featureAbility.terminateSelfWithResult( 300 { 301 resultCode: 1, 302 want: 303 { 304 action: "action.system.home", 305 entities: ["entity.system.home"], 306 type: "MIMETYPE", 307 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 308 deviceId: "", 309 bundleName: "com.example.featureabilitytest", 310 abilityName: "com.example.featureabilitytest.MainAbility", 311 uri:"", 312 parameters: { 313 mykey0: 2222, 314 mykey1: [1, 2, 3], 315 mykey2: "[1, 2, 3]", 316 mykey3: "ssssssssssssssssssssssssss", 317 mykey4: [1, 15], 318 mykey5: [false, true, false], 319 mykey6: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], 320 mykey7: true, 321 } 322 }, 323 } 324).then((data) => { 325 console.info("==========================>terminateSelfWithResult=======================>"); 326}); 327``` 328 329 330 331## featureAbility.hasWindowFocus<sup>7+<sup> 332 333hasWindowFocus(callback: AsyncCallback\<boolean>): void 334 335Checks whether the main window of this ability has the focus. This API uses an asynchronous callback to return the result. 336 337**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 338 339**Parameters** 340 341| Name | Type | Mandatory | Description | 342| -------- | ----------------------- | ---- | ---------------------------------------- | 343| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>Returns **true** if the main window of this ability has the focus; returns **false** otherwise.| 344 345**Example** 346 347```javascript 348import featureAbility from '@ohos.ability.featureAbility'; 349featureAbility.hasWindowFocus( 350 (err, data) => { 351 console.info("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)) 352 } 353) 354``` 355 356 357 358## featureAbility.hasWindowFocus<sup>7+<sup> 359 360hasWindowFocus(): Promise\<boolean> 361 362Checks whether the main window of this ability has the focus. This API uses a promise to return the result. 363 364**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 365 366**Return value** 367 368| Type | Description | 369| ----------------- | ------------------------------------- | 370| Promise\<boolean> | Returns **true** if the main window of this ability has the focus; returns **false** otherwise.| 371 372**Example** 373 374```javascript 375import featureAbility from '@ohos.ability.featureAbility'; 376featureAbility.hasWindowFocus().then((data) => { 377 console.info("==========================>hasWindowFocus=======================>"); 378}); 379``` 380 381 382 383## featureAbility.getWant 384 385getWant(callback: AsyncCallback\<Want>): void 386 387Obtains the **Want** object sent from this ability. This API uses an asynchronous callback to return the result. 388 389**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 390 391**Parameters** 392 393| Name | Type | Mandatory | Description | 394| -------- | ----------------------------- | ---- | --------- | 395| callback | AsyncCallback\<[Want](#want)> | Yes | Callback used to return the result.| 396 397**Example** 398 399```javascript 400import featureAbility from '@ohos.ability.featureAbility'; 401featureAbility.getWant( 402 (err, data) => { 403 console.info("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)) 404 } 405) 406``` 407 408 409 410## featureAbility.getWant 411 412getWant(): Promise\<Want> 413 414Obtains the **Want** object sent from this ability. This API uses a promise to return the result. 415 416**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 417 418**Return value** 419 420| Type | Description | 421| ----------------------- | ---------------- | 422| Promise\<[Want](#want)> | Promise used to return the result.| 423 424**Example** 425 426```javascript 427import featureAbility from '@ohos.ability.featureAbility'; 428featureAbility.getWant().then((data) => { 429 console.info("==========================>getWantCallBack=======================>"); 430}); 431``` 432 433## featureAbility.getContext 434 435getContext(): Context 436 437Obtains the application context. 438 439**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 440 441**Return value** 442 443| Type | Description | 444| ------- | ---------- | 445| Context | Application context.| 446 447**Example** 448 449```javascript 450import featureAbility from '@ohos.ability.featureAbility'; 451var context = featureAbility.getContext() 452context.getBundleName() 453``` 454 455 456 457## featureAbility.terminateSelf<sup>7+</sup> 458 459terminateSelf(callback: AsyncCallback\<void>): void 460 461Destroys this Page ability, with the result code and data sent to the caller. This API uses an asynchronous callback to return the result. 462 463**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 464 465**Parameters** 466 467| Name | Type | Mandatory | Description | 468| -------- | -------------------- | ---- | -------- | 469| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 470 471**Example** 472 473```javascript 474import featureAbility from '@ohos.ability.featureAbility'; 475featureAbility.terminateSelf( 476 (err) => { 477 console.info("err: " + JSON.stringify(err)) 478 } 479) 480``` 481 482 483 484## featureAbility.terminateSelf<sup>7+</sup> 485 486terminateSelf(): Promise\<void> 487 488Destroys this Page ability, with the result code and data sent to the caller. This API uses a promise to return the result. 489 490**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 491 492**Return value** 493 494| Type | Description | 495| -------------- | ---------------- | 496| Promise\<void> | Promise used to return the result.| 497 498**Example** 499 500```javascript 501import featureAbility from '@ohos.ability.featureAbility'; 502featureAbility.terminateSelf().then((data) => { console.info("==========================>terminateSelfCallBack=======================>"); 503}); 504``` 505 506## featureAbility.connectAbility<sup>7+</sup> 507 508connectAbility(request: Want, options:ConnectOptions): number 509 510Connects this ability to a specific Service ability. This API uses an asynchronous callback to return the result. 511 512**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 513 514**Parameters** 515 516| Name | Type | Mandatory | Description | 517| ------- | -------------- | ---- | --------------------- | 518| request | [Want](#want) | Yes | Service ability to connect.| 519| options | ConnectOptions | Yes | Callback used to return the result. | 520 521Want 522 523**System capability**: SystemCapability.Ability.AbilityBase 524 525| Name | Readable/Writable | Type | Mandatory | Description | 526| ----------- | ----------------- | ------ | --------- | ------------------------------------------------------------ | 527| deviceId | Read-only | string | No | Device ID of the Service ability to connect. The default value is the local device ID. | 528| bundleName | Read-only | string | Yes | Bundle name of the Service ability to connect. | 529| abilityName | Read-only | string | Yes | Class name of the Service ability to connect. | 530 531ConnectOptions 532 533**System capability**: SystemCapability.Ability.AbilityRuntime.Core 534 535| Name | Readable/Writable | Type | Mandatory | Description | 536| ------------ | -- | -------- | ---- | ------------------------- | 537| onConnect | Read-only | function | Yes | Callback invoked when the connection is successful. | 538| onDisconnect | Read-only | function | Yes | Callback invoked when the connection fails. | 539| onFailed | Read-only | function | Yes | Callback invoked when **connectAbility** fails to be called.| 540 541**Return value** 542 543| Type | Description | 544| ------ | -------------------- | 545| number | ID of the Service ability connected.| 546 547**Example** 548 549```javascript 550import rpc from '@ohos.rpc' 551import featureAbility from '@ohos.ability.featureAbility' 552function onConnectCallback(element, remote){ 553 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 554} 555function onDisconnectCallback(element){ 556 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 557} 558function onFailedCallback(code){ 559 console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) 560} 561var connId = featureAbility.connectAbility( 562 { 563 deviceId: "", 564 bundleName: "com.ix.ServiceAbility", 565 abilityName: "ServiceAbilityA", 566 }, 567 { 568 onConnect: onConnectCallback, 569 onDisconnect: onDisconnectCallback, 570 onFailed: onFailedCallback, 571 }, 572); 573``` 574 575## featureAbility.disconnectAbility<sup>7+</sup> 576 577disconnectAbility(connection: number, callback:AsyncCallback\<void>): void 578 579Disconnects this ability from a specific Service ability. This API uses an asynchronous callback to return the result. 580 581**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 582 583**Parameters** 584 585| Name | Type | Mandatory | Description | 586| ---------- | -------------------- | ---- | ----------------------- | 587| connection | number | Yes | ID of the Service ability to disconnect.| 588| callback | AsyncCallback\<void> | Yes | Callback used to return the result. | 589 590**Example** 591 592```javascript 593import rpc from '@ohos.rpc' 594import featureAbility from '@ohos.ability.featureAbility' 595function onConnectCallback(element, remote){ 596 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 597} 598function onDisconnectCallback(element){ 599 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 600} 601function onFailedCallback(code){ 602 console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) 603} 604var connId = featureAbility.connectAbility( 605 { 606 bundleName: "com.ix.ServiceAbility", 607 abilityName: "ServiceAbilityA", 608 }, 609 { 610 onConnect: onConnectCallback, 611 onDisconnect: onDisconnectCallback, 612 onFailed: onFailedCallback, 613 }, 614); 615var result = featureAbility.disconnectAbility(connId, 616 (error) => { 617 console.log('featureAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code) 618 }, 619); 620``` 621 622## featureAbility.disconnectAbility<sup>7+</sup> 623 624disconnectAbility(connection: number): Promise\<void> 625 626Disconnects this ability from a specific Service ability. This API uses a promise to return the result. 627 628**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 629 630**Parameters** 631 632| Name | Type | Mandatory | Description | 633| ---------- | ------ | ---- | ----------------------- | 634| connection | number | Yes | ID of the Service ability to disconnect.| 635 636**Return value** 637 638| Type | Description | 639| -------------- | --------------- | 640| Promise\<void> | Promise used to return the result.| 641 642**Example** 643 644```javascript 645import rpc from '@ohos.rpc' 646import featureAbility from '@ohos.ability.featureAbility' 647function onConnectCallback(element, remote){ 648 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 649} 650function onDisconnectCallback(element){ 651 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 652} 653function onFailedCallback(code){ 654 console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) 655} 656var connId = featureAbility.connectAbility( 657 { 658 bundleName: "com.ix.ServiceAbility", 659 abilityName: "ServiceAbilityA", 660 }, 661 { 662 onConnect: onConnectCallback, 663 onDisconnect: onDisconnectCallback, 664 onFailed: onFailedCallback, 665 }, 666); 667 668featureAbility.disconnectAbility(connId).then((error,data)=>{ 669 console.log('featureAbilityTest result errCode : ' + error.code + " data: " + data); 670}); 671``` 672 673 674## featureAbility.getWindow<sup>7+</sup> 675 676getWindow(callback: AsyncCallback\<window.Window>): void 677 678Obtains the window corresponding to this ability. This API uses an asynchronous callback to return the result. 679 680**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 681 682**Parameters** 683 684| Name | Type | Mandatory| Description | 685| -------- | ----------------------------- | ---- | ----------------------------- | 686| callback | AsyncCallback\<window.Window> | Yes | Callback used to return the window.| 687 688**Example** 689 690```javascript 691featureAbility.getWindow( 692 (err, data) => { 693 console.info("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)) 694 } 695) 696``` 697 698## featureAbility.getWindow<sup>7+</sup> 699 700getWindow(): Promise\<window.Window>; 701 702Obtains the window corresponding to this ability. This API uses a promise to return the result. 703 704**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 705 706**Return value** 707 708| Type | Description | 709| ----------------------- | ----------------------------- | 710| Promise\<window.Window> | Promise used to return the window.| 711 712**Example** 713 714```javascript 715featureAbility.getWindow().then((data) => { 716 console.info("=============getWindowPromise========== " + JSON.stringify(data)); 717}); 718``` 719 720## ConnectOptions.onConnect<sup>7+</sup> 721 722onConnect(elementName: ElementName, remote: rpc.IRemoteObject): void; 723 724Callback invoked when the connection is successful. 725 726**System capability**: SystemCapability.Ability.AbilityRuntime.Core 727 728**Parameters** 729 730| Name | Type | Mandatory | Description | 731| ----------- | ----------------- | ---- | -------- | 732| elementName | ElementName | Yes | Element name. | 733| remote | rpc.IRemoteObject | Yes | RPC remote object.| 734 735**Example** 736 737```javascript 738import rpc from '@ohos.rpc' 739import featureAbility from '@ohos.ability.featureAbility' 740function onConnectCallback(element, remote){ 741 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 742} 743function onDisconnectCallback(element){ 744 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 745} 746function onFailedCallback(code){ 747 console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) 748} 749var connId = featureAbility.connectAbility( 750 { 751 deviceId: "", 752 bundleName: "com.ix.ServiceAbility", 753 abilityName: "ServiceAbilityA", 754 }, 755 { 756 onConnect: onConnectCallback, 757 onDisconnect: onDisconnectCallback, 758 onFailed: onFailedCallback, 759 }, 760); 761``` 762 763## ConnectOptions.onDisconnect<sup>7+</sup> 764 765onDisconnect(elementName: ElementName): void; 766 767Callback invoked when the connection fails. 768 769**System capability**: SystemCapability.Ability.AbilityRuntime.Core 770 771**Parameters** 772 773| Name | Type | Mandatory | Description | 774| ----------- | ----------- | ---- | ---- | 775| elementName | ElementName | Yes | Element name.| 776 777**Example** 778 779```javascript 780import rpc from '@ohos.rpc' 781import featureAbility from '@ohos.ability.featureAbility' 782function onConnectCallback(element, remote){ 783 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 784} 785function onDisconnectCallback(element){ 786 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 787} 788function onFailedCallback(code){ 789 console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) 790} 791var connId = featureAbility.connectAbility( 792 { 793 deviceId: "", 794 bundleName: "com.ix.ServiceAbility", 795 abilityName: "ServiceAbilityA", 796 }, 797 { 798 onConnect: onConnectCallback, 799 onDisconnect: onDisconnectCallback, 800 onFailed: onFailedCallback, 801 }, 802); 803``` 804 805## ConnectOptions.onFailed<sup>7+</sup> 806 807onFailed(code: number): void; 808 809Callback invoked when **connectAbility** fails to be called. 810 811**System capability**: SystemCapability.Ability.AbilityRuntime.Core 812 813**Parameters** 814 815| Name | Type | Mandatory | Description | 816| ---- | ------ | ---- | --------- | 817| code | number | Yes | Number type.| 818 819**Example** 820 821```javascript 822import rpc from '@ohos.rpc' 823import featureAbility from '@ohos.ability.featureAbility' 824function onConnectCallback(element, remote){ 825 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 826} 827function onDisconnectCallback(element){ 828 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 829} 830function onFailedCallback(code){ 831 console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) 832} 833var connId = featureAbility.connectAbility( 834 { 835 deviceId: "", 836 bundleName: "com.ix.ServiceAbility", 837 abilityName: "ServiceAbilityA", 838 }, 839 { 840 onConnect: onConnectCallback, 841 onDisconnect: onDisconnectCallback, 842 onFailed: onFailedCallback, 843 }, 844); 845``` 846 847 848 849 850 851## AbilityWindowConfiguration 852 853The value is obtained through the **featureAbility.AbilityWindowConfiguration** API. 854 855**Example** 856 857``` 858featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED 859``` 860 861**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 862 863| Name | Value | Description | 864| ---------------------------------------- | ---- | ---------------------------------------- | 865| WINDOW_MODE_UNDEFINED<sup>7+</sup> | 0 | The Page ability is in an undefined window display mode.| 866| WINDOW_MODE_FULLSCREEN<sup>7+</sup> | 1 | The Page ability is in full screen mode. | 867| WINDOW_MODE_SPLIT_PRIMARY<sup>7+</sup> | 100 | The Page ability is displayed in the primary window when it is in split-screen mode.| 868| WINDOW_MODE_SPLIT_SECONDARY<sup>7+</sup> | 101 | The Page ability is displayed in the secondary window when it is in split-screen mode.| 869| WINDOW_MODE_FLOATING<sup>7+</sup> | 102 | The Page ability is displayed in floating window mode.| 870 871 872## AbilityStartSetting 873 874The **AbilityStartSetting** attribute is an object defined as [key: string]: any. The key is a type of **AbilityStartSetting**, and the value is a type of **AbilityWindowConfiguration**. 875 876The value is obtained through the **featureAbility.AbilityStartSetting** API. 877 878**Example** 879 880``` 881featureAbility.AbilityStartSetting.BOUNDS_KEY 882``` 883 884**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 885 886| Name | Value | Description | 887| ---------------------------- | --------------- | ---------------------------------------- | 888| BOUNDS_KEY<sup>7+</sup> | "abilityBounds" | Ability window size.| 889| WINDOW_MODE_KEY<sup>7+</sup> | "windowMode" | Ability window display mode.| 890| DISPLAY_ID_KEY<sup>7+</sup> | "displayId" | Display device ID.| 891 892## ErrorCode 893 894Enumerates error codes. 895 896**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 897 898| Name | Value | Description | 899| ------------------------------ | ---- | ---------------------------------------- | 900| NO_ERROR<sup>7+</sup> | 0 | No error occurs.| 901| INVALID_PARAMETER<sup>7+</sup> | -1 | Invalid parameter.| 902| ABILITY_NOT_FOUND<sup>7+</sup> | -2 | The ability is not found.| 903| PERMISSION_DENY<sup>7+</sup> | -3 | The request is denied.| 904 905 906## DataAbilityOperationType 907 908Enumerates operation types of the Data ability. 909 910**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 911 912| Name | Value | Description | 913| ------------------------ | ---- | ---------------------------------------- | 914| TYPE_INSERT<sup>7+</sup> | 1 | Insert operation.| 915| TYPE_UPDATE<sup>7+</sup> | 2 | Update operation.| 916| TYPE_DELETE<sup>7+</sup> | 3 | Deletion operation.| 917| TYPE_ASSERT<sup>7+</sup> | 4 | Assert operation.| 918 919 920 921## AbilityResult 922 923**System capability**: SystemCapability.Ability.AbilityBase 924 925| Name | Readable/Writable | Type | Mandatory | Description | 926| --------------- |-------- | ------ | ------------------------------------- | ------------------------------------- | 927| resultCode<sup>7+</sup>| Read-only | number| Yes | Result code returned after the ability is destroyed. The feature for defining error-specific result codes is coming soon.| 928| want<sup>7+</sup> | Read-only | [Want](#want)| No | Data returned after the ability is destroyed. You can define the data to be returned. This parameter can be **null**. | 929 930## StartAbilityParameter 931 932**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel 933 934| Name | Readable/Writable | Type | Mandatory | Description | 935| ------------------- | -------- | -------------------- | -------------------- | -------------------- | 936| want | Read-only | [Want](#want)| Yes | Information about the ability to start. | 937| abilityStartSetting | Read-only | {[key: string]: any} | No | Special attribute of the ability to start. This attribute can be passed in the method call.| 938 939 940## Want 941 942**System capability**: SystemCapability.Ability.AbilityBase 943 944| Name | Readable/Writable | Type | Mandatory | Description | 945| --------------------------------- | ----------------- | --------------------------- | --------- | ------------------------------------------------------------ | 946| deviceId | Read-only | string | No | ID of the device that runs the ability. | 947| bundleName | Read-only | string | No | Bundle name of the ability to start. | 948| abilityName | Read-only | string | No | Name of the ability to start. If both **package** and **AbilityName** are specified in this field in a **Want** object, the **Want** object can directly match the specified ability. | 949| uri | Read-only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**. | 950| type | Read-only | string | No | MIME type, for example, text/plain or image/*. | 951| flags | Read-only | number | No | How the **Want** object will be handled. By default, a number is passed. For details, see [flags](#flags). | 952| action | Read-only | string | No | Action option. | 953| parameters | Read-only | {[key: string]: any} | No | List of parameters in the **Want** object. | 954| entities | Read-only | Array\<string> | No | List of entities. | 955| extensionAbilityType<sup>9+</sup> | Read-only | bundle.ExtensionAbilityType | No | Type of the Extension ability. | 956| extensionAbilityName<sup>9+<sup> | Read-only | string | No | Description of the Extension ability name in the **Want** object. | 957 958## flags 959 960**System capability**: SystemCapability.Ability.AbilityBase 961 962| Name | Value | Description | 963| ------------------------------------ | ---------- | ---------------------------------------- | 964| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI. | 965| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write the URI. | 966| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | Returns the result to the ability. | 967| FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be migrated to a remote device. | 968| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS. | 969| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates whether to enable an ability. | 970| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent. | 971| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching. | 972| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler. | 973| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the Service ability is started regardless of whether the host application has been started. | 974| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that the migration is reversible. | 975| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. | 976| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. | 977| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object in the **startAbility** API passed to [ohos.app.Context](js-apis-ability-context.md) and must be used together with **flag_ABILITY_NEW_MISSION**.| 978| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on the historical mission stack. | 979| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Starts the mission on the top of the existing mission stack; creates an ability instance if no mission exists.| 980