js-apis-featureAbility.md 32.9 KB
Newer Older
1
# FeatureAbility模块(JS端SDK接口)
X
xuchenghua09 已提交
2

3
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:**
4 5
> 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。  
> 本模块接口仅可在FA模型下使用。
6

Z
zengyawen 已提交
7
## 使用限制
X
xuchenghua09 已提交
8 9 10

FeatureAbility模块的接口只能在Page类型的Ability调用

Z
zengyawen 已提交
11
## 导入模块
X
xuchenghua09 已提交
12 13 14 15 16

```
import featureAbility from '@ohos.ability.featureAbility'
```

Z
zengyawen 已提交
17
## featureAbility.startAbility
X
xuchenghua09 已提交
18

Z
zengyawen 已提交
19
startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<number>): void
X
xuchenghua09 已提交
20

Z
zengyawen 已提交
21
启动新的ability(callback形式)。
X
xuchenghua09 已提交
22

Y
yuyaozhi 已提交
23
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
24

Z
zengyawen 已提交
25
**参数:**
X
xuchenghua09 已提交
26

H
HelloCrease 已提交
27 28 29 30
| 名称        | 类型                                       | 必填   | 描述             |
| --------- | ---------------------------------------- | ---- | -------------- |
| parameter | [StartAbilityParameter](#startabilityparameter) | 是    | 表示被启动的Ability。 |
| callback  | AsyncCallback\<number>                   | 是    | 被指定的回调方法。      |
X
xuchenghua09 已提交
31

Z
zengyawen 已提交
32
**示例:**
X
xuchenghua09 已提交
33 34 35

```javascript
import featureAbility from '@ohos.ability.featureAbility'
36
import wantConstant from '@ohos.ability.wantConstant'
X
xuchenghua09 已提交
37
featureAbility.startAbility(
38
    {
X
xuchenghua09 已提交
39 40 41 42 43
        want:
        {
            action: "",
            entities: [""],
            type: "",
44
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
X
xuchenghua09 已提交
45
            deviceId: "",
G
guyuanzhang 已提交
46 47
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
Y
yuyaozhi 已提交
48
            abilityName: "com.example.entry.secondAbility",
X
xuchenghua09 已提交
49 50 51
            uri: ""
        },
    },
52
);
X
xuchenghua09 已提交
53 54 55 56
```



Z
zengyawen 已提交
57
## featureAbility.startAbility
X
xuchenghua09 已提交
58

Z
zengyawen 已提交
59
startAbility(parameter: StartAbilityParameter): Promise\<number>
X
xuchenghua09 已提交
60

Z
zengyawen 已提交
61
启动新的ability(Promise形式)。
X
xuchenghua09 已提交
62

Y
yuyaozhi 已提交
63
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
64

Z
zengyawen 已提交
65
**参数:**
X
xuchenghua09 已提交
66

H
HelloCrease 已提交
67 68 69
| 名称        | 类型                                       | 必填   | 描述             |
| --------- | ---------------------------------------- | ---- | -------------- |
| parameter | [StartAbilityParameter](#startabilityparameter) | 是    | 表示被启动的Ability。 |
X
xuchenghua09 已提交
70

Z
zengyawen 已提交
71
**示例:**
X
xuchenghua09 已提交
72 73 74

```javascript
import featureAbility from '@ohos.ability.featureAbility'
75
import wantConstant from '@ohos.ability.wantConstant'
X
xuchenghua09 已提交
76 77 78 79
featureAbility.startAbility(
    {
        want:
        {
80
            action: "action.system.home",
X
xuchenghua09 已提交
81 82
            entities: ["entity.system.home"],
            type: "MIMETYPE",
83 84
			flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: "",
G
guyuanzhang 已提交
85 86 87
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
X
xuchenghua09 已提交
88 89 90
            uri: ""
        },
    }
91
).then((data) => {
X
xuchenghua09 已提交
92 93 94 95
	console.info("==========================>startAbility=======================>");
});
```

96
## featureAbility.acquireDataAbilityHelper<sup>7+</sup>
X
xuchenghua09 已提交
97

Z
zengyawen 已提交
98
acquireDataAbilityHelper(uri: string): DataAbilityHelper
X
xuchenghua09 已提交
99

Z
zengyawen 已提交
100
获取dataAbilityHelper。
X
xuchenghua09 已提交
101

Y
yuyaozhi 已提交
102
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
103

Z
zengyawen 已提交
104
**参数:**
X
xuchenghua09 已提交
105

H
HelloCrease 已提交
106 107 108
| 名称   | 类型     | 必填   | 描述           |
| ---- | ------ | ---- | ------------ |
| uri  | string | 是    | 指示要打开的文件的路径。 |
X
xuchenghua09 已提交
109

Z
zengyawen 已提交
110
**返回值:**
X
xuchenghua09 已提交
111

H
HelloCrease 已提交
112 113
| 类型                | 说明                              |
| ----------------- | ------------------------------- |
Z
zengyawen 已提交
114
| DataAbilityHelper | 用来协助其他Ability访问DataAbility的工具类。 |
X
xuchenghua09 已提交
115

Z
zengyawen 已提交
116
**示例:**
X
xuchenghua09 已提交
117 118 119 120

```javascript
import featureAbility from '@ohos.ability.featureAbility'
featureAbility.acquireDataAbilityHelper(
Y
yuyaozhi 已提交
121
    "dataability:///com.example.DataAbility"
X
xuchenghua09 已提交
122 123 124
)
```

125
## featureAbility.startAbilityForResult<sup>7+</sup>
X
xuchenghua09 已提交
126

Z
zengyawen 已提交
127
startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback\<AbilityResult>): void
X
xuchenghua09 已提交
128

Z
zengyawen 已提交
129
启动一个ability,并在该ability被销毁时返回执行结果(callback形式)。
X
xuchenghua09 已提交
130

Y
yuyaozhi 已提交
131
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
132

Z
zengyawen 已提交
133
**参数:**
X
xuchenghua09 已提交
134

H
HelloCrease 已提交
135 136 137 138
| 名称        | 类型                                       | 必填   | 描述             |
| --------- | ---------------------------------------- | ---- | -------------- |
| parameter | [StartAbilityParameter](#startabilityparameter) | 是    | 表示被启动的Ability。 |
| callback  | AsyncCallback\<[AbilityResult](#abilityresult)> | 是    | 被指定的回调方法。      |
X
xuchenghua09 已提交
139

Z
zengyawen 已提交
140
**示例:**
X
xuchenghua09 已提交
141 142

```javascript
Y
yuyaozhi 已提交
143
import featureAbility from '@ohos.ability.featureAbility';
144
import wantConstant from '@ohos.ability.wantConstant'
X
xuchenghua09 已提交
145 146 147 148 149 150 151
featureAbility.startAbilityForResult(
   {
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
152
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
X
xuchenghua09 已提交
153
            deviceId: "",
G
guyuanzhang 已提交
154 155 156
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
X
xuchenghua09 已提交
157 158 159
            uri:""
        },
    },
160
    (err, data) => {
Y
yuyaozhi 已提交
161
        console.info("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data))
162
    }
X
xuchenghua09 已提交
163 164 165
)
```

166
## featureAbility.startAbilityForResult<sup>7+</sup>
X
xuchenghua09 已提交
167

Z
zengyawen 已提交
168
startAbilityForResult(parameter: StartAbilityParameter): Promise\<AbilityResult>
X
xuchenghua09 已提交
169

Z
zengyawen 已提交
170
启动一个ability,并在该ability被销毁时返回执行结果(Promise形式)。
X
xuchenghua09 已提交
171

Y
yuyaozhi 已提交
172
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
173

Z
zengyawen 已提交
174
**参数:**
X
xuchenghua09 已提交
175

H
HelloCrease 已提交
176 177 178
| 名称        | 类型                                       | 必填   | 描述            |
| --------- | ---------------------------------------- | ---- | ------------- |
| parameter | [StartAbilityParameter](#startabilityparameter) | 是    | 表示被启动的Ability |
X
xuchenghua09 已提交
179

Z
zengyawen 已提交
180
**返回值:**
Y
yuyaozhi 已提交
181

H
HelloCrease 已提交
182 183
| 类型                                       | 说明      |
| ---------------------------------------- | ------- |
Z
zengyawen 已提交
184
| Promise\<[AbilityResult](#abilityresult)> | 返回执行结果。 |
X
xuchenghua09 已提交
185

Z
zengyawen 已提交
186
**示例:**
X
xuchenghua09 已提交
187 188

```javascript
Y
yuyaozhi 已提交
189
import featureAbility from '@ohos.ability.featureAbility';
190
import wantConstant from '@ohos.ability.wantConstant'
X
xuchenghua09 已提交
191 192 193 194 195 196 197
featureAbility.startAbilityForResult(
    {
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
198
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
X
xuchenghua09 已提交
199
            deviceId: "",
G
guyuanzhang 已提交
200 201 202
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
X
xuchenghua09 已提交
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
            uri:"",
            parameters:
            {
                mykey0: 1111,
                mykey1: [1, 2, 3],
                mykey2: "[1, 2, 3]",
                mykey3: "xxxxxxxxxxxxxxxxxxxxxx",
                mykey4: [1, 15],
                mykey5: [false, true, false],
                mykey6: ["aaaaaa", "bbbbb", "ccccccccccc"],
                mykey7: true,
            },
        },
        requestCode: 2,
    },
218
).then((data) => {
X
xuchenghua09 已提交
219 220 221 222
    console.info("==========================>startAbilityForResult=======================>");
});
```

223
## featureAbility.terminateSelfWithResult<sup>7+</sup>
X
xuchenghua09 已提交
224

Z
zengyawen 已提交
225
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback\<void>): void
X
xuchenghua09 已提交
226

Z
zengyawen 已提交
227
设置此Page Ability将返回给调用者的结果代码和数据并破坏此Page Ability(callback形式)。
X
xuchenghua09 已提交
228

Y
yuyaozhi 已提交
229
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
230

Z
zengyawen 已提交
231
**参数:**
X
xuchenghua09 已提交
232

H
HelloCrease 已提交
233 234 235 236
| 名称        | 类型                              | 必填   | 描述             |
| --------- | ------------------------------- | ---- | -------------- |
| parameter | [AbilityResult](#abilityresult) | 是    | 表示被启动的Ability。 |
| callback  | AsyncCallback\<void>            | 是    | 被指定的回调方法。      |
X
xuchenghua09 已提交
237

Z
zengyawen 已提交
238
**示例:**
X
xuchenghua09 已提交
239 240 241

```javascript
import featureAbility from '@ohos.ability.featureAbility'
242
import wantConstant from '@ohos.ability.wantConstant'
X
xuchenghua09 已提交
243 244 245 246 247 248 249 250
featureAbility.terminateSelfWithResult(
    {
        resultCode: 1,
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
251
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
X
xuchenghua09 已提交
252
            deviceId: "",
G
guyuanzhang 已提交
253 254 255
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
X
xuchenghua09 已提交
256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271
            uri:"",
            parameters: {
                mykey0: 2222,
                mykey1: [1, 2, 3],
                mykey2: "[1, 2, 3]",
                mykey3: "ssssssssssssssssssssssssss",
                mykey4: [1, 15],
                mykey5: [false, true, false],
                mykey6: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"],
                mykey7: true,
            }
        },
    },
);
```

272
## featureAbility.terminateSelfWithResult<sup>7+</sup>
X
xuchenghua09 已提交
273

Z
zengyawen 已提交
274
terminateSelfWithResult(parameter: AbilityResult): Promise\<void>
X
xuchenghua09 已提交
275

Z
zengyawen 已提交
276
设置此Page Ability将返回给调用者的结果代码和数据并破坏此Page Ability(Promise形式)。
X
xuchenghua09 已提交
277

Y
yuyaozhi 已提交
278
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
279

Z
zengyawen 已提交
280
**参数:**
X
xuchenghua09 已提交
281

H
HelloCrease 已提交
282 283 284
| 名称        | 类型                              | 必填   | 描述            |
| --------- | ------------------------------- | ---- | ------------- |
| parameter | [AbilityResult](#abilityresult) | 是    | 表示被启动的Ability |
X
xuchenghua09 已提交
285

Z
zengyawen 已提交
286
**返回值:**
Y
yuyaozhi 已提交
287

H
HelloCrease 已提交
288 289
| 类型             | 说明              |
| -------------- | --------------- |
Z
zengyawen 已提交
290
| Promise\<void> | 以Promise形式返回结果。 |
X
xuchenghua09 已提交
291

Z
zengyawen 已提交
292
**示例:**
X
xuchenghua09 已提交
293 294

```javascript
Y
yuyaozhi 已提交
295
import featureAbility from '@ohos.ability.featureAbility';
296
import wantConstant from '@ohos.ability.wantConstant'
X
xuchenghua09 已提交
297 298 299 300 301 302 303 304
featureAbility.terminateSelfWithResult(
    {
        resultCode: 1,
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
305
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
X
xuchenghua09 已提交
306
            deviceId: "",
G
guyuanzhang 已提交
307 308 309
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
X
xuchenghua09 已提交
310 311 312 313 314 315 316 317 318 319 320 321 322
            uri:"",
            parameters: {
                mykey0: 2222,
                mykey1: [1, 2, 3],
                mykey2: "[1, 2, 3]",
                mykey3: "ssssssssssssssssssssssssss",
                mykey4: [1, 15],
                mykey5: [false, true, false],
                mykey6: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"],
                mykey7: true,
            }
        },
    }
323
).then((data) => {
X
xuchenghua09 已提交
324 325 326 327 328 329
    console.info("==========================>terminateSelfWithResult=======================>");
});
```



330
## featureAbility.hasWindowFocus<sup>7+<sup>
X
xuchenghua09 已提交
331

Z
zengyawen 已提交
332
hasWindowFocus(callback: AsyncCallback\<boolean>): void
X
xuchenghua09 已提交
333

Z
zengyawen 已提交
334
检查Ability的主窗口是否具有窗口焦点(callback形式)。
X
xuchenghua09 已提交
335

Y
yuyaozhi 已提交
336
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
337

Z
zengyawen 已提交
338
**参数:**
X
xuchenghua09 已提交
339

H
HelloCrease 已提交
340 341 342
| 名称       | 类型                      | 必填   | 描述                                       |
| -------- | ----------------------- | ---- | ---------------------------------------- |
| callback | AsyncCallback\<boolean> | 是    | 被指定的回调方法。<br>如果此Ability当前具有视窗焦点,则返回true;否则返回false。 |
X
xuchenghua09 已提交
343

Z
zengyawen 已提交
344
**示例:**
X
xuchenghua09 已提交
345 346

```javascript
Y
yuyaozhi 已提交
347
import featureAbility from '@ohos.ability.featureAbility';
X
xuchenghua09 已提交
348 349 350 351 352
featureAbility.hasWindowFocus()
```



353
## featureAbility.hasWindowFocus<sup>7+<sup>
X
xuchenghua09 已提交
354

Z
zengyawen 已提交
355
hasWindowFocus(): Promise\<boolean>
X
xuchenghua09 已提交
356

Z
zengyawen 已提交
357
检查Ability的主窗口是否具有窗口焦点(Promise形式)。
X
xuchenghua09 已提交
358

Y
yuyaozhi 已提交
359
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
360

Z
zengyawen 已提交
361
**返回值:**
X
xuchenghua09 已提交
362

H
HelloCrease 已提交
363 364
| 类型                | 说明                                    |
| ----------------- | ------------------------------------- |
Z
zengyawen 已提交
365
| Promise\<boolean> | 如果此Ability当前具有视窗焦点,则返回true;否则返回false。 |
X
xuchenghua09 已提交
366

Z
zengyawen 已提交
367
**示例:**
X
xuchenghua09 已提交
368 369 370

```javascript
import featureAbility from '@ohos.ability.featureability';
371
featureAbility.hasWindowFocus().then((data) => {
X
xuchenghua09 已提交
372 373 374 375 376 377
    console.info("==========================>hasWindowFocus=======================>");
});
```



Z
zengyawen 已提交
378
## featureAbility.getWant
X
xuchenghua09 已提交
379

Z
zengyawen 已提交
380
getWant(callback: AsyncCallback\<Want>): void
X
xuchenghua09 已提交
381

Z
zengyawen 已提交
382
获取从Ability发送的Want(callback形式)。
X
xuchenghua09 已提交
383

Y
yuyaozhi 已提交
384
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
385

Z
zengyawen 已提交
386
**参数:**
X
xuchenghua09 已提交
387

H
HelloCrease 已提交
388 389
| 名称       | 类型                            | 必填   | 描述        |
| -------- | ----------------------------- | ---- | --------- |
ahjxliubao2's avatar
ahjxliubao2 已提交
390
| callback | AsyncCallback\<[Want](js-apis-application-Want.md)> | 是    | 被指定的回调方法。 |
X
xuchenghua09 已提交
391

Z
zengyawen 已提交
392
**示例:**
X
xuchenghua09 已提交
393 394

```javascript
Y
yuyaozhi 已提交
395
import featureAbility from '@ohos.ability.featureAbility';
X
xuchenghua09 已提交
396 397 398 399 400
featureAbility.getWant()
```



Z
zengyawen 已提交
401
## featureAbility.getWant
X
xuchenghua09 已提交
402

Z
zengyawen 已提交
403
getWant(): Promise\<Want>
X
xuchenghua09 已提交
404

Z
zengyawen 已提交
405
获取从Ability发送的Want(Promise形式)。
X
xuchenghua09 已提交
406

Y
yuyaozhi 已提交
407
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
408

Z
zengyawen 已提交
409
**返回值:**
Y
yuyaozhi 已提交
410

H
HelloCrease 已提交
411 412
| 类型                      | 说明               |
| ----------------------- | ---------------- |
ahjxliubao2's avatar
ahjxliubao2 已提交
413
| Promise\<[Want](js-apis-application-Want.md)> | 以Promise的形式返回结果。 |
X
xuchenghua09 已提交
414

Z
zengyawen 已提交
415
**示例:**
X
xuchenghua09 已提交
416 417

```javascript
Y
yuyaozhi 已提交
418
import featureAbility from '@ohos.ability.featureAbility';
419
featureAbility.getWant().then((data) => {
420
	console.info("==========================>getWantCallBack=======================>");
X
xuchenghua09 已提交
421 422 423
});
```

Z
zengyawen 已提交
424
## featureAbility.getContext
X
xuchenghua09 已提交
425

Z
zengyawen 已提交
426
getContext(): Context
X
xuchenghua09 已提交
427

Z
zengyawen 已提交
428
获取应用上下文。
X
xuchenghua09 已提交
429

Y
yuyaozhi 已提交
430
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
431

Z
zengyawen 已提交
432
**返回值:**
Y
yuyaozhi 已提交
433

H
HelloCrease 已提交
434 435
| 类型      | 说明         |
| ------- | ---------- |
Z
zengyawen 已提交
436
| Context | 返回应用程序上下文。 |
X
xuchenghua09 已提交
437

Z
zengyawen 已提交
438
**示例:**
X
xuchenghua09 已提交
439 440

```javascript
Y
yuyaozhi 已提交
441
import featureAbility from '@ohos.ability.featureAbility';
X
xuchenghua09 已提交
442 443 444 445 446 447
var context = featureAbility.getContext()
context.getBundleName()
```



448
## featureAbility.terminateSelf<sup>7+</sup>
X
xuchenghua09 已提交
449

Z
zengyawen 已提交
450
terminateSelf(callback: AsyncCallback\<void>): void
X
xuchenghua09 已提交
451

Z
zengyawen 已提交
452
设置Page Ability返回给被调用方的结果代码和数据,并销毁此Page Ability(callback形式)。
X
xuchenghua09 已提交
453

Y
yuyaozhi 已提交
454
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
455

Z
zengyawen 已提交
456
**参数:**
X
xuchenghua09 已提交
457

H
HelloCrease 已提交
458 459 460
| 名称       | 类型                   | 必填   | 描述       |
| -------- | -------------------- | ---- | -------- |
| callback | AsyncCallback\<void> | 是    | 被指定的回调方法 |
X
xuchenghua09 已提交
461

Z
zengyawen 已提交
462
**示例:**
X
xuchenghua09 已提交
463 464

```javascript
Y
yuyaozhi 已提交
465
import featureAbility from '@ohos.ability.featureAbility';
X
xuchenghua09 已提交
466 467 468 469 470
featureAbility.terminateSelf()
```



471
## featureAbility.terminateSelf<sup>7+</sup>
X
xuchenghua09 已提交
472

Z
zengyawen 已提交
473
terminateSelf(): Promise\<void>
X
xuchenghua09 已提交
474

Z
zengyawen 已提交
475
设置Page Ability返回给被调用方的结果代码和数据,并销毁此Page Ability(Promise形式)。
X
xuchenghua09 已提交
476

Y
yuyaozhi 已提交
477
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
478

Z
zengyawen 已提交
479
**返回值:**
Y
yuyaozhi 已提交
480

H
HelloCrease 已提交
481 482
| 类型             | 说明               |
| -------------- | ---------------- |
Z
zengyawen 已提交
483
| Promise\<void> | 以Promise的形式返回结果。 |
X
xuchenghua09 已提交
484

Z
zengyawen 已提交
485
**示例:**
X
xuchenghua09 已提交
486 487

```javascript
Y
yuyaozhi 已提交
488
import featureAbility from '@ohos.ability.featureAbility';
489 490
featureAbility.terminateSelf().then((data) => {
    console.info("==========================>terminateSelfCallBack=======================>");
X
xuchenghua09 已提交
491 492 493
});
```

494
## featureAbility.connectAbility<sup>7+</sup>
X
xuchenghua09 已提交
495

Z
zengyawen 已提交
496
connectAbility(request: Want, options:ConnectOptions): number
X
xuchenghua09 已提交
497

Z
zengyawen 已提交
498
将当前ability连接到指定ServiceAbility(callback形式)。
X
xuchenghua09 已提交
499

Y
yuyaozhi 已提交
500
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
501

Z
zengyawen 已提交
502
**参数:**
X
xuchenghua09 已提交
503

H
HelloCrease 已提交
504 505
| 名称      | 类型             | 必填   | 描述                    |
| ------- | -------------- | ---- | --------------------- |
ahjxliubao2's avatar
ahjxliubao2 已提交
506
| request | [Want](js-apis-application-Want.md)  | 是    | 表示被连接的ServiceAbility。 |
H
HelloCrease 已提交
507
| options | ConnectOptions | 是    | 被指定的回调方法。             |
X
xuchenghua09 已提交
508

Z
zengyawen 已提交
509
**Want类型说明:**
510

ahjxliubao2's avatar
ahjxliubao2 已提交
511 512
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase

H
HelloCrease 已提交
513 514 515 516 517
| 名称          | 读写属性 | 类型     | 必填   | 描述                                       |
| ----------- | ---- | ------ | ---- | ---------------------------------------- |
| deviceId    | 只读   | string | 否    | 表示被连接的ServiceAbility的设备id,缺省表示连接本地的ServiceAbility。 |
| bundleName  | 只读   | string | 是    | 表示被连接的ServiceAbility的包名。                 |
| abilityName | 只读   | string | 是    | 表示被连接的ServiceAbility的类名。                 |
518

Z
zengyawen 已提交
519
**ConnectOptions类型说明:**
X
xuchenghua09 已提交
520

ahjxliubao2's avatar
ahjxliubao2 已提交
521 522
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core

H
HelloCrease 已提交
523 524 525 526 527
| 名称           | 读写属性 | 类型       | 必填   | 描述                        |
| ------------ | ---- | -------- | ---- | ------------------------- |
| onConnect    | 只读   | function | 是    | 连接成功时的回调函数。               |
| onDisconnect | 只读   | function | 是    | 连接失败时的回调函数。               |
| onFailed     | 只读   | function | 是    | ConnectAbility调用失败时的回调函数。 |
X
xuchenghua09 已提交
528

Z
zengyawen 已提交
529
**返回值:**
Y
yuyaozhi 已提交
530

H
HelloCrease 已提交
531 532
| 类型     | 说明                   |
| ------ | -------------------- |
Z
zengyawen 已提交
533
| number | 连接的ServiceAbilityID。 |
X
xuchenghua09 已提交
534

Z
zengyawen 已提交
535
**示例:**
X
xuchenghua09 已提交
536 537

```javascript
H
hanhaibin 已提交
538
import rpc from '@ohos.rpc'
X
xuchenghua09 已提交
539 540 541 542 543 544 545 546 547 548 549 550
import featureAbility from '@ohos.ability.featureAbility'
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = featureAbility.connectAbility(
    {
551
        deviceId: "",
X
xuchenghua09 已提交
552 553 554 555 556 557 558 559 560 561 562
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
```

563
## featureAbility.disconnectAbility<sup>7+</sup>
X
xuchenghua09 已提交
564

Z
zengyawen 已提交
565
disconnectAbility(connection: number, callback:AsyncCallback\<void>): void
X
xuchenghua09 已提交
566

Z
zengyawen 已提交
567
断开与指定ServiceAbility的连接(callback形式)。
X
xuchenghua09 已提交
568

Y
yuyaozhi 已提交
569
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
570

Z
zengyawen 已提交
571
**参数:**
X
xuchenghua09 已提交
572

H
HelloCrease 已提交
573 574 575 576
| 名称         | 类型                   | 必填   | 描述                      |
| ---------- | -------------------- | ---- | ----------------------- |
| connection | number               | 是    | 指定断开连接的ServiceAbilityID |
| callback   | AsyncCallback\<void> | 是    | 被指定的回调方法                |
X
xuchenghua09 已提交
577

Z
zengyawen 已提交
578
**示例:**
X
xuchenghua09 已提交
579 580

```javascript
H
hanhaibin 已提交
581
import rpc from '@ohos.rpc'
X
xuchenghua09 已提交
582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604
import featureAbility from '@ohos.ability.featureAbility'
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = featureAbility.connectAbility(
    {
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
var result = featureAbility.disconnectAbility(connId,
    (error,data) => {
605
        console.log('featureAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code + " data: " + data)
X
xuchenghua09 已提交
606 607 608 609
    },
);
```

610
## featureAbility.disconnectAbility<sup>7+</sup>
X
xuchenghua09 已提交
611

Z
zengyawen 已提交
612
disconnectAbility(connection: number): Promise\<void>
X
xuchenghua09 已提交
613

Z
zengyawen 已提交
614
断开与指定ServiceAbility的连接(Promise形式)。
X
xuchenghua09 已提交
615

Y
yuyaozhi 已提交
616
**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel
ahjxliubao2's avatar
ahjxliubao2 已提交
617

Z
zengyawen 已提交
618
**参数:**
X
xuchenghua09 已提交
619

H
HelloCrease 已提交
620 621 622
| 名称         | 类型     | 必填   | 描述                      |
| ---------- | ------ | ---- | ----------------------- |
| connection | number | 是    | 指定断开连接的ServiceAbilityID |
X
xuchenghua09 已提交
623

Z
zengyawen 已提交
624
**返回值:**
Y
yuyaozhi 已提交
625

H
HelloCrease 已提交
626 627
| 类型             | 说明              |
| -------------- | --------------- |
Z
zengyawen 已提交
628
| Promise\<void> | 以Promise形式返回结果。 |
X
xuchenghua09 已提交
629

Z
zengyawen 已提交
630
**示例:**
X
xuchenghua09 已提交
631 632

```javascript
H
hanhaibin 已提交
633
import rpc from '@ohos.rpc'
X
xuchenghua09 已提交
634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654
import featureAbility from '@ohos.ability.featureAbility'
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = featureAbility.connectAbility(
    {
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
ahjxliubao2's avatar
ahjxliubao2 已提交
655

656
featureAbility.disconnectAbility(connId).then((error,data) => {
ahjxliubao2's avatar
ahjxliubao2 已提交
657 658
    console.log('featureAbilityTest result errCode : ' + error.code + " data: " + data);
});
X
xuchenghua09 已提交
659 660
```

661 662 663 664 665

## featureAbility.getWindow<sup>7+</sup>

getWindow(callback: AsyncCallback\<window.Window>): void

666
获取当前Ability对应的窗口(callback形式)。
667 668 669 670 671

**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel

**参数:**

672 673 674
| 名称     | 类型                          | 必填 | 描述                          |
| -------- | ----------------------------- | ---- | ----------------------------- |
| callback | AsyncCallback\<window.Window> | 是   | 返回与当前Ability对应的窗口。 |
675 676 677 678

**示例:**

```javascript
H
HelloCrease 已提交
679
featureAbility.getWindow()
680 681 682 683 684 685
```

## featureAbility.getWindow<sup>7+</sup>

getWindow(): Promise\<window.Window>;

686
获取当前Ability对应的窗口(Promise形式)。
687 688 689 690 691

**系统能力**:SystemCapability.Ability.AbilityRuntime.FAModel

**返回值:**

692 693 694
| 类型                    | 说明                          |
| ----------------------- | ----------------------------- |
| Promise\<window.Window> | 返回与当前Ability对应的窗口。 |
695 696 697 698

**示例:**

```javascript
H
HelloCrease 已提交
699
featureAbility.getWindow().then((data) => {
700
  console.info("=============getWindowPromise========== " +  JSON.stringify(data)); 
H
HelloCrease 已提交
701
});
702 703
```

704 705 706 707 708 709 710 711 712 713
## ConnectOptions.onConnect<sup>7+</sup>

onConnect(elementName: ElementName, remote: rpc.IRemoteObject): void;

连接成功时的回调函数。

**系统能力**:SystemCapability.Ability.AbilityRuntime.Core

**参数:**

H
HelloCrease 已提交
714 715 716 717
| 名称          | 类型                | 必填   | 描述       |
| ----------- | ----------------- | ---- | -------- |
| elementName | ElementName       | 是    | 元素名。     |
| remote      | rpc.IRemoteObject | 是    | rpc远程对象。 |
718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756

**示例:**

```javascript
import rpc from '@ohos.rpc'
import featureAbility from '@ohos.ability.featureAbility'
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
```

## ConnectOptions.onDisconnect<sup>7+</sup>

onDisconnect(elementName: ElementName): void;

连接失败时的回调函数。

**系统能力**:SystemCapability.Ability.AbilityRuntime.Core

**参数:**

H
HelloCrease 已提交
757 758 759
| 名称          | 类型          | 必填   | 描述   |
| ----------- | ----------- | ---- | ---- |
| elementName | ElementName | 是    | 元素名。 |
760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798

**示例:**

```javascript
import rpc from '@ohos.rpc'
import featureAbility from '@ohos.ability.featureAbility'
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
```

## ConnectOptions.onFailed<sup>7+</sup>

onFailed(code: number): void;

ConnectAbility调用失败时的回调函数。

**系统能力**:SystemCapability.Ability.AbilityRuntime.Core

**参数:**

H
HelloCrease 已提交
799 800 801
| 名称   | 类型     | 必填   | 描述        |
| ---- | ------ | ---- | --------- |
| code | number | 是    | number类型。 |
802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833

**示例:**

```javascript
import rpc from '@ohos.rpc'
import featureAbility from '@ohos.ability.featureAbility'
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
```




834 835 836 837 838 839 840 841

## AbilityWindowConfiguration

使用时通过featureAbility.AbilityWindowConfiguration获取。

**示例:**

```
842
featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED
843 844
```

845 846
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

H
HelloCrease 已提交
847 848
| 名称                                       | 参数   | 描述                                       |
| ---------------------------------------- | ---- | ---------------------------------------- |
849 850 851 852 853
| WINDOW_MODE_UNDEFINED<sup>7+</sup>       | 0    | 未定义。 |
| WINDOW_MODE_FULLSCREEN<sup>7+</sup>      | 1    | 全屏。    |
| WINDOW_MODE_SPLIT_PRIMARY<sup>7+</sup>   | 100  | 分屏主屏。 |
| WINDOW_MODE_SPLIT_SECONDARY<sup>7+</sup> | 101  | 分屏次屏。 |
| WINDOW_MODE_FLOATING<sup>7+</sup>        | 102  | 悬浮窗。 |
854 855 856 857 858 859 860 861 862 863 864


## AbilityStartSetting

abilityStartSetting属性是一个定义为[key: string]: any的对象,key对应设定类型为:AbilityStartSetting枚举类型,value对应设定类型为:AbilityWindowConfiguration枚举类型。

使用时通过featureAbility.AbilityStartSetting获取。

**示例:**

```
865
featureAbility.AbilityStartSetting.BOUNDS_KEY
866 867
```

868 869
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

H
HelloCrease 已提交
870 871
| 名称                           | 参数              | 描述                                       |
| ---------------------------- | --------------- | ---------------------------------------- |
872 873 874
| BOUNDS_KEY<sup>7+</sup>      | "abilityBounds" | 窗口显示大小属性的名称。 |
| WINDOW_MODE_KEY<sup>7+</sup> | "windowMode"    | 窗口显示模式属性的名称。|
| DISPLAY_ID_KEY<sup>7+</sup>  | "displayId"     | 窗口显示设备ID属性的名称。 |
875 876 877 878 879

## ErrorCode

获取错误代码。

880 881
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

H
HelloCrease 已提交
882 883
| 变量                             | 值    | 说明                                       |
| ------------------------------ | ---- | ---------------------------------------- |
884 885 886 887
| NO_ERROR<sup>7+</sup>          | 0    | 没有错误。 |
| INVALID_PARAMETER<sup>7+</sup> | -1   | 无效的参数。 |
| ABILITY_NOT_FOUND<sup>7+</sup> | -2   | 找不到能力。 |
| PERMISSION_DENY<sup>7+</sup>   | -3   | 拒绝许可。 |
888 889 890 891 892 893


## DataAbilityOperationType

指示数据的操作类型。

894 895
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

H
HelloCrease 已提交
896 897
| 变量                       | 值    | 说明                                       |
| ------------------------ | ---- | ---------------------------------------- |
898 899 900 901
| TYPE_INSERT<sup>7+</sup> | 1    | 插入类型。 |
| TYPE_UPDATE<sup>7+</sup> | 2    | 修改类型。 |
| TYPE_DELETE<sup>7+</sup> | 3    | 删除类型。 |
| TYPE_ASSERT<sup>7+</sup> | 4    | 声明类型。 |
902 903 904



Z
zengyawen 已提交
905
## AbilityResult
X
xuchenghua09 已提交
906

ahjxliubao2's avatar
ahjxliubao2 已提交
907 908
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase

H
HelloCrease 已提交
909 910 911
| 名称                      | 读写属性 | 类型            | 必填   | 描述                                    |
| ----------------------- | ---- | ------------- | ---- | ------------------------------------- |
| resultCode<sup>7+</sup> | 只读   | number        | 是    | 指示销毁该能力后返回的结果代码。您可以定义结果代码来识别错误(暂不支持)。 |
ahjxliubao2's avatar
ahjxliubao2 已提交
912
| want<sup>7+</sup>       | 只读   | [Want](js-apis-application-Want.md) | 否    | 指示销毁该能力后返回的数据。您可以定义返回的数据。此参数可以为null。  |
X
xuchenghua09 已提交
913

Z
zengyawen 已提交
914
## StartAbilityParameter
X
xuchenghua09 已提交
915

ahjxliubao2's avatar
ahjxliubao2 已提交
916 917
**系统能力**:以下各项对应的系统能力均为SystemCapability.AbilityRuntime.FAModel 

H
HelloCrease 已提交
918 919
| 名称                  | 读写属性 | 类型                   | 必填   | 描述                                     |
| ------------------- | ---- | -------------------- | ---- | -------------------------------------- |
ahjxliubao2's avatar
ahjxliubao2 已提交
920
| want                | 只读   | [Want](js-apis-application-Want.md)        | 是    | 表示需要包含有关目标启动能力的信息。                     |
H
HelloCrease 已提交
921
| abilityStartSetting | 只读   | {[key: string]: any} | 否    | 表示能力的特殊属性,当开发者启动能力时,该属性可以作为调用中的输入参数传递。 |
X
xuchenghua09 已提交
922 923 924

## flags说明

ahjxliubao2's avatar
ahjxliubao2 已提交
925 926
**系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase

H
HelloCrease 已提交
927 928 929 930 931 932 933 934 935 936 937 938 939 940 941
| 名称                                   | 参数         | 描述                                       |
| ------------------------------------ | ---------- | ---------------------------------------- |
| FLAG_AUTH_READ_URI_PERMISSION        | 0x00000001 | 指示对URI执行读取操作的授权。                         |
| FLAG_AUTH_WRITE_URI_PERMISSION       | 0x00000002 | 指示对URI执行写入操作的授权。                         |
| FLAG_ABILITY_FORWARD_RESULT          | 0x00000004 | 将结果返回给元能力。                               |
| FLAG_ABILITY_CONTINUATION            | 0x00000008 | 确定是否可以将本地设备上的功能迁移到远程设备。                  |
| FLAG_NOT_OHOS_COMPONENT              | 0x00000010 | 指定组件是否属于OHOS。                            |
| FLAG_ABILITY_FORM_ENABLED            | 0x00000020 | 指定是否启动某个能力。                              |
| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | 指示URI上可能持久化的授权。                          |
| FLAG_AUTH_PREFIX_URI_PERMISSION      | 0x00000080 | 按照前缀匹配的方式验证URI权限。                        |
| FLAG_ABILITYSLICE_MULTI_DEVICE       | 0x00000100 | 支持分布式调度系统中的多设备启动。                        |
| FLAG_START_FOREGROUND_ABILITY        | 0x00000200 | 指示无论主机应用程序是否已启动,都将启动使用服务模板的功能。           |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | 表示迁移是可拉回的。                               |
| FLAG_INSTALL_ON_DEMAND               | 0x00000800 | 如果未安装指定的功能,请安装该功能。                       |
| FLAG_INSTALL_WITH_BACKGROUND_MODE    | 0x80000000 | 如果未安装,使用后台模式安装该功能。                       |
942
| FLAG_ABILITY_CLEAR_MISSION           | 0x00008000 | 指示清除其他任务的操作。可以为传递给 **[ohos.app.Context](js-apis-ability-context.md)****startAbility**方法的**Want**设置此标志,并且必须与**flag_ABILITY_NEW_MISSION**一起使用。 |
H
HelloCrease 已提交
943
| FLAG_ABILITY_NEW_MISSION             | 0x10000000 | 指示在历史任务堆栈上创建任务的操作。                       |
ahjxliubao2's avatar
ahjxliubao2 已提交
944
| FLAG_ABILITY_MISSION_TOP             | 0x20000000 | 指示如果启动能力的现有实例已位于任务堆栈的顶部,则将重用该实例。否则,将创建一个新的能力实例。 |
X
xuchenghua09 已提交
945