1# FeatureAbility模块(JS端SDK接口) 2 3>  **说明：** 4> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5> 6> API 9当前为Canary版本，仅供使用，不保证接口可稳定调用。 7 8## 使用限制 9 10FeatureAbility模块的接口只能在Page类型的Ability调用 11 12## 导入模块 13 14``` 15import featureAbility from '@ohos.ability.featureAbility' 16``` 17 18## featureAbility.startAbility 19 20startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<number>): void 21 22启动新的ability（callback形式）。 23 24**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 25 26**参数：** 27 28| 名称 | 类型 | 必填 | 描述 | 29| --------- | ---------------------------------------- | ---- | -------------- | 30| parameter | [StartAbilityParameter](#startabilityparameter) | 是 | 表示被启动的Ability。 | 31| callback | AsyncCallback\<number> | 是 | 被指定的回调方法。 | 32 33**示例：** 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 64启动新的ability（Promise形式）。 65 66**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 67 68**参数：** 69 70| 名称 | 类型 | 必填 | 描述 | 71| --------- | ---------------------------------------- | ---- | -------------- | 72| parameter | [StartAbilityParameter](#startabilityparameter) | 是 | 表示被启动的Ability。 | 73 74**示例：** 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 102获取dataAbilityHelper。 103 104**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 105 106**参数：** 107 108| 名称 | 类型 | 必填 | 描述 | 109| ---- | ------ | ---- | ------------ | 110| uri | string | 是 | 指示要打开的文件的路径。 | 111 112**返回值：** 113 114| 类型 | 说明 | 115| ----------------- | ------------------------------- | 116| DataAbilityHelper | 用来协助其他Ability访问DataAbility的工具类。 | 117 118**示例：** 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 131启动一个ability，并在该ability被销毁时返回执行结果（callback形式）。 132 133**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 134 135**参数：** 136 137| 名称 | 类型 | 必填 | 描述 | 138| --------- | ---------------------------------------- | ---- | -------------- | 139| parameter | [StartAbilityParameter](#startabilityparameter) | 是 | 表示被启动的Ability。 | 140| callback | AsyncCallback\<[AbilityResult](#abilityresult)> | 是 | 被指定的回调方法。 | 141 142**示例：** 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 171启动一个ability，并在该ability被销毁时返回执行结果（Promise形式）。 172 173**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 174 175**参数：** 176 177| 名称 | 类型 | 必填 | 描述 | 178| --------- | ---------------------------------------- | ---- | ------------- | 179| parameter | [StartAbilityParameter](#startabilityparameter) | 是 | 表示被启动的Ability | 180 181**返回值：** 182 183| 类型 | 说明 | 184| ---------------------------------------- | ------- | 185| Promise\<[AbilityResult](#abilityresult)> | 返回执行结果。 | 186 187**示例：** 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 227设置此Page Ability将返回给调用者的结果代码和数据并破坏此Page Ability（callback形式）。 228 229**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 230 231**参数：** 232 233| 名称 | 类型 | 必填 | 描述 | 234| --------- | ------------------------------- | ---- | -------------- | 235| parameter | [AbilityResult](#abilityresult) | 是 | 表示被启动的Ability。 | 236| callback | AsyncCallback\<void> | 是 | 被指定的回调方法。 | 237 238**示例：** 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 278设置此Page Ability将返回给调用者的结果代码和数据并破坏此Page Ability（Promise形式）。 279 280**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 281 282**参数：** 283 284| 名称 | 类型 | 必填 | 描述 | 285| --------- | ------------------------------- | ---- | ------------- | 286| parameter | [AbilityResult](#abilityresult) | 是 | 表示被启动的Ability | 287 288**返回值：** 289 290| 类型 | 说明 | 291| -------------- | --------------- | 292| Promise\<void> | 以Promise形式返回结果。 | 293 294**示例：** 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 335检查Ability的主窗口是否具有窗口焦点（callback形式）。 336 337**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 338 339**参数：** 340 341| 名称 | 类型 | 必填 | 描述 | 342| -------- | ----------------------- | ---- | ---------------------------------------- | 343| callback | AsyncCallback\<boolean> | 是 | 被指定的回调方法。<br>如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | 344 345**示例：** 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 362检查Ability的主窗口是否具有窗口焦点（Promise形式）。 363 364**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 365 366**返回值：** 367 368| 类型 | 说明 | 369| ----------------- | ------------------------------------- | 370| Promise\<boolean> | 如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | 371 372**示例：** 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 387获取从Ability发送的Want（callback形式）。 388 389**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 390 391**参数：** 392 393| 名称 | 类型 | 必填 | 描述 | 394| -------- | ----------------------------- | ---- | --------- | 395| callback | AsyncCallback\<[Want](#want)> | 是 | 被指定的回调方法。 | 396 397**示例：** 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 414获取从Ability发送的Want（Promise形式）。 415 416**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 417 418**返回值：** 419 420| 类型 | 说明 | 421| ----------------------- | ---------------- | 422| Promise\<[Want](#want)> | 以Promise的形式返回结果。 | 423 424**示例：** 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 437获取应用上下文。 438 439**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 440 441**返回值：** 442 443| 类型 | 说明 | 444| ------- | ---------- | 445| Context | 返回应用程序上下文。 | 446 447**示例：** 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 461设置Page Ability返回给被调用方的结果代码和数据，并销毁此Page Ability（callback形式）。 462 463**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 464 465**参数：** 466 467| 名称 | 类型 | 必填 | 描述 | 468| -------- | -------------------- | ---- | -------- | 469| callback | AsyncCallback\<void> | 是 | 被指定的回调方法 | 470 471**示例：** 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 488设置Page Ability返回给被调用方的结果代码和数据，并销毁此Page Ability（Promise形式）。 489 490**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 491 492**返回值：** 493 494| 类型 | 说明 | 495| -------------- | ---------------- | 496| Promise\<void> | 以Promise的形式返回结果。 | 497 498**示例：** 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 510将当前ability连接到指定ServiceAbility（callback形式）。 511 512**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 513 514**参数：** 515 516| 名称 | 类型 | 必填 | 描述 | 517| ------- | -------------- | ---- | --------------------- | 518| request | [Want](#want) | 是 | 表示被连接的ServiceAbility。 | 519| options | ConnectOptions | 是 | 被指定的回调方法。 | 520 521**Want类型说明：** 522 523**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase 524 525| 名称 | 读写属性 | 类型 | 必填 | 描述 | 526| ----------- | ---- | ------ | ---- | ---------------------------------------- | 527| deviceId | 只读 | string | 否 | 表示被连接的ServiceAbility的设备id，缺省表示连接本地的ServiceAbility。 | 528| bundleName | 只读 | string | 是 | 表示被连接的ServiceAbility的包名。 | 529| abilityName | 只读 | string | 是 | 表示被连接的ServiceAbility的类名。 | 530 531**ConnectOptions类型说明：** 532 533**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core 534 535| 名称 | 读写属性 | 类型 | 必填 | 描述 | 536| ------------ | ---- | -------- | ---- | ------------------------- | 537| onConnect | 只读 | function | 是 | 连接成功时的回调函数。 | 538| onDisconnect | 只读 | function | 是 | 连接失败时的回调函数。 | 539| onFailed | 只读 | function | 是 | ConnectAbility调用失败时的回调函数。 | 540 541**返回值：** 542 543| 类型 | 说明 | 544| ------ | -------------------- | 545| number | 连接的ServiceAbilityID。 | 546 547**示例：** 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 579断开与指定ServiceAbility的连接（callback形式）。 580 581**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 582 583**参数：** 584 585| 名称 | 类型 | 必填 | 描述 | 586| ---------- | -------------------- | ---- | ----------------------- | 587| connection | number | 是 | 指定断开连接的ServiceAbilityID | 588| callback | AsyncCallback\<void> | 是 | 被指定的回调方法 | 589 590**示例：** 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 626断开与指定ServiceAbility的连接（Promise形式）。 627 628**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 629 630**参数：** 631 632| 名称 | 类型 | 必填 | 描述 | 633| ---------- | ------ | ---- | ----------------------- | 634| connection | number | 是 | 指定断开连接的ServiceAbilityID | 635 636**返回值：** 637 638| 类型 | 说明 | 639| -------------- | --------------- | 640| Promise\<void> | 以Promise形式返回结果。 | 641 642**示例：** 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 678获取当前Ability对应的窗口（callback形式）。 679 680**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 681 682**参数：** 683 684| 名称 | 类型 | 必填 | 描述 | 685| -------- | ----------------------------- | ---- | ----------------------------- | 686| callback | AsyncCallback\<window.Window> | 是 | 返回与当前Ability对应的窗口。 | 687 688**示例：** 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 702获取当前Ability对应的窗口（Promise形式）。 703 704**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 705 706**返回值：** 707 708| 类型 | 说明 | 709| ----------------------- | ----------------------------- | 710| Promise\<window.Window> | 返回与当前Ability对应的窗口。 | 711 712**示例：** 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 724连接成功时的回调函数。 725 726**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 727 728**参数：** 729 730| 名称 | 类型 | 必填 | 描述 | 731| ----------- | ----------------- | ---- | -------- | 732| elementName | ElementName | 是 | 元素名。 | 733| remote | rpc.IRemoteObject | 是 | rpc远程对象。 | 734 735**示例：** 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 767连接失败时的回调函数。 768 769**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 770 771**参数：** 772 773| 名称 | 类型 | 必填 | 描述 | 774| ----------- | ----------- | ---- | ---- | 775| elementName | ElementName | 是 | 元素名。 | 776 777**示例：** 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 809ConnectAbility调用失败时的回调函数。 810 811**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 812 813**参数：** 814 815| 名称 | 类型 | 必填 | 描述 | 816| ---- | ------ | ---- | --------- | 817| code | number | 是 | number类型。 | 818 819**示例：** 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 853使用时通过featureAbility.AbilityWindowConfiguration获取。 854 855**示例：** 856 857``` 858featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED 859``` 860 861**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel 862 863| 名称 | 参数 | 描述 | 864| ---------------------------------------- | ---- | ---------------------------------------- | 865| WINDOW_MODE_UNDEFINED<sup>7+</sup> | 0 | 未定义。 | 866| WINDOW_MODE_FULLSCREEN<sup>7+</sup> | 1 | 全屏。 | 867| WINDOW_MODE_SPLIT_PRIMARY<sup>7+</sup> | 100 | 分屏主屏。 | 868| WINDOW_MODE_SPLIT_SECONDARY<sup>7+</sup> | 101 | 分屏次屏。 | 869| WINDOW_MODE_FLOATING<sup>7+</sup> | 102 | 悬浮窗。 | 870 871 872## AbilityStartSetting 873 874abilityStartSetting属性是一个定义为[key: string]: any的对象，key对应设定类型为：AbilityStartSetting枚举类型，value对应设定类型为：AbilityWindowConfiguration枚举类型。 875 876使用时通过featureAbility.AbilityStartSetting获取。 877 878**示例：** 879 880``` 881featureAbility.AbilityStartSetting.BOUNDS_KEY 882``` 883 884**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel 885 886| 名称 | 参数 | 描述 | 887| ---------------------------- | --------------- | ---------------------------------------- | 888| BOUNDS_KEY<sup>7+</sup> | "abilityBounds" | 窗口显示大小属性的名称。 | 889| WINDOW_MODE_KEY<sup>7+</sup> | "windowMode" | 窗口显示模式属性的名称。| 890| DISPLAY_ID_KEY<sup>7+</sup> | "displayId" | 窗口显示设备ID属性的名称。 | 891 892## ErrorCode 893 894获取错误代码。 895 896**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel 897 898| 变量 | 值 | 说明 | 899| ------------------------------ | ---- | ---------------------------------------- | 900| NO_ERROR<sup>7+</sup> | 0 | 没有错误。 | 901| INVALID_PARAMETER<sup>7+</sup> | -1 | 无效的参数。 | 902| ABILITY_NOT_FOUND<sup>7+</sup> | -2 | 找不到能力。 | 903| PERMISSION_DENY<sup>7+</sup> | -3 | 拒绝许可。 | 904 905 906## DataAbilityOperationType 907 908指示数据的操作类型。 909 910**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel 911 912| 变量 | 值 | 说明 | 913| ------------------------ | ---- | ---------------------------------------- | 914| TYPE_INSERT<sup>7+</sup> | 1 | 插入类型。 | 915| TYPE_UPDATE<sup>7+</sup> | 2 | 修改类型。 | 916| TYPE_DELETE<sup>7+</sup> | 3 | 删除类型。 | 917| TYPE_ASSERT<sup>7+</sup> | 4 | 声明类型。 | 918 919 920 921## AbilityResult 922 923**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase 924 925| 名称 | 读写属性 | 类型 | 必填 | 描述 | 926| ----------------------- | ---- | ------------- | ---- | ------------------------------------- | 927| resultCode<sup>7+</sup> | 只读 | number | 是 | 指示销毁该能力后返回的结果代码。您可以定义结果代码来识别错误（暂不支持）。 | 928| want<sup>7+</sup> | 只读 | [Want](#want) | 否 | 指示销毁该能力后返回的数据。您可以定义返回的数据。此参数可以为null。 | 929 930## StartAbilityParameter 931 932**系统能力**：以下各项对应的系统能力均为SystemCapability.AbilityRuntime.FAModel 933 934| 名称 | 读写属性 | 类型 | 必填 | 描述 | 935| ------------------- | ---- | -------------------- | ---- | -------------------------------------- | 936| want | 只读 | [Want](#want) | 是 | 表示需要包含有关目标启动能力的信息。 | 937| abilityStartSetting | 只读 | {[key: string]: any} | 否 | 表示能力的特殊属性，当开发者启动能力时，该属性可以作为调用中的输入参数传递。 | 938 939 940## Want 941 942**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase 943 944| 名称 | 读写属性 | 类型 | 必填 | 描述 | 945| -------------------------------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | 946| deviceId | 只读 | string | 否 | 表示运行指定Ability的设备ID。 | 947| bundleName | 只读 | string | 否 | 表示包描述。| 948| abilityName | 只读 | string | 否 | 表示待启动的Ability名称。如果在Want中该字段同时指定了package和AbilityName，则Want可以直接匹配到指定的Ability。 | 949| uri | 只读 | string | 否 | 表示Uri描述。如果在Want中指定了Uri，则Want将匹配指定的Uri信息，包括scheme, schemeSpecificPart, authority和path信息。 | 950| type | 只读 | string | 否 | 表示MIME type类型描述，比如："text/plain" 、 "image/*"等。 | 951| flags | 只读 | number | 否 | 表示处理Want的方式。默认传数字，具体参考：[flags说明](#flags说明)。 | 952| action | 只读 | string | 否 | 表示action选项描述。 | 953| parameters | 只读 | {[key: string]: any} | 否 | 表示WantParams描述。 | 954| entities | 只读 | Array\<string> | 否 | 表示entities相关描述。 | 955| extensionAbilityType<sup>9+</sup> | 只读 | bundle.ExtensionAbilityType | 否 | ExtensionAbility类型 | 956| extensionAbilityName<sup>9+<sup> | 只读 | string | 否 | Want中扩展能力名称的描述。 | 957 958## flags说明 959 960**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase 961 962| 名称 | 参数 | 描述 | 963| ------------------------------------ | ---------- | ---------------------------------------- | 964| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | 指示对URI执行读取操作的授权。 | 965| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | 指示对URI执行写入操作的授权。 | 966| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | 将结果返回给元能力。 | 967| FLAG_ABILITY_CONTINUATION | 0x00000008 | 确定是否可以将本地设备上的功能迁移到远程设备。 | 968| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | 指定组件是否属于OHOS。 | 969| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | 指定是否启动某个能力。 | 970| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | 指示URI上可能持久化的授权。 | 971| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | 按照前缀匹配的方式验证URI权限。 | 972| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | 支持分布式调度系统中的多设备启动。 | 973| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | 指示无论主机应用程序是否已启动，都将启动使用服务模板的功能。 | 974| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | 表示迁移是可拉回的。 | 975| FLAG_INSTALL_ON_DEMAND | 0x00000800 | 如果未安装指定的功能，请安装该功能。 | 976| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | 如果未安装，使用后台模式安装该功能。 | 977| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | 指示清除其他任务的操作。可以为传递给 **[ohos.app.Context](js-apis-ability-context.md)** 中**startAbility**方法的**Want**设置此标志，并且必须与**flag_ABILITY_NEW_MISSION**一起使用。 | 978| FLAG_ABILITY_NEW_MISSION | 0x10000000 | 指示在历史任务堆栈上创建任务的操作。 | 979| FLAG_ABILITY_MISSION_TOP | 0x20000000 | 指示如果启动能力的现有实例已位于任务堆栈的顶部，则将重用该实例。否则，将创建一个新的能力实例。 | 980 981
