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