1# particleAbility模块 2 3>  **说明：** 4> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6## 使用限制 7 8particleAbility模块用来对Data和Service类型的Ability进行操作。 9 10## 导入模块 11 12```js 13import particleAbility from '@ohos.ability.particleAbility' 14``` 15 16## particleAbility.startAbility 17 18startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<void>): void 19 20使用此方法启动指定的particleAbility（callback形式）。 21 22**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 23 24**参数：** 25 26 27| 名称 | 类型 | 必填 | 描述 | 28| --------- | ----------------------------------------------- | ---- | ----------------- | 29| parameter | [StartAbilityParameter](#startabilityparameter) | 是 | 指示启动的ability | 30| callback | AsyncCallback\<void> | 是 | 被指定的回调方法 | 31 32**示例：** 33 34```js 35import particleAbility from '@ohos.ability.particleAbility' 36import wantConstant from '@ohos.ability.wantConstant' 37particleAbility.startAbility( 38 { 39 want: 40 { 41 action: "action.system.home", 42 entities: ["entity.system.home"], 43 type: "MIMETYPE", 44 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 45 deviceId: "", 46 bundleName: "com.example.Data", 47 abilityName: "com.example.Data.MainAbility", 48 uri:"" 49 }, 50 }, 51 (error, result) => { 52 console.log('particleAbility startAbility errCode:' + error + 'result:' + result) 53 }, 54) 55``` 56 57 58 59## particleAbility.startAbility 60 61startAbility(parameter: StartAbilityParameter): Promise\<void>; 62 63使用此方法启动指定的particleAbility（Promise形式）。 64 65**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 66 67**参数：** 68 69 70| 名称 | 类型 | 必填 | 描述 | 71| --------- | ----------------------------------------------- | ---- | ----------------- | 72| parameter | [StartAbilityParameter](#startabilityparameter) | 是 | 指示启动的ability | 73 74**返回值：** 75 76| 类型 | 说明 | 77| -------------- | ------------------------- | 78| Promise\<void> | 使用Promise形式返回结果。 | 79 80**示例：** 81 82```js 83import particleAbility from '@ohos.ability.particleAbility' 84import wantConstant from '@ohos.ability.wantConstant' 85particleAbility.startAbility( 86 { 87 want: 88 { 89 action: "action.system.home", 90 entities: ["entity.system.home"], 91 type: "MIMETYPE", 92 flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, 93 deviceId: "", 94 bundleName: "com.example.Data", 95 abilityName: "com.example. Data.MainAbility", 96 uri:"" 97 }, 98 }, 99).then((data) => { 100 console.info("particleAbility startAbility"); 101}); 102``` 103 104 105 106## particleAbility.terminateSelf 107 108terminateSelf(callback: AsyncCallback\<void>): void 109 110终止particleAbility（callback形式）。 111 112**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 113 114**参数：** 115 116| 名称 | 类型 | 必填 | 描述 | 117| -------- | -------------------- | ---- | -------------------- | 118| callback | AsyncCallback\<void> | 是 | 表示被指定的回调方法 | 119 120**示例：** 121 122```js 123import particleAbility from '@ohos.ability.particleAbility' 124particleAbility.terminateSelf( 125 (error, result) => { 126 console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result) 127 } 128) 129``` 130 131 132 133## particleAbility.terminateSelf 134 135terminateSelf(): Promise\<void> 136 137终止particleAbility（Promise形式）。 138 139**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 140 141**返回值：** 142 143| 类型 | 说明 | 144| -------------- | ------------------------- | 145| Promise\<void> | 使用Promise形式返回结果。 | 146 147**示例：** 148 149```js 150import particleAbility from '@ohos.ability.particleAbility' 151particleAbility.terminateSelf().then((data) => { 152 console.info("particleAbility terminateSelf"); 153}); 154``` 155 156 157 158## particleAbility.acquireDataAbilityHelper 159 160acquireDataAbilityHelper(uri: string): DataAbilityHelper 161 162获取dataAbilityHelper。 163 164**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 165 166**参数：** 167 168| 名称 | 类型 | 必填 | 描述 | 169| :--- | ------ | ---- | ------------------------ | 170| uri | string | 是 | 指示要打开的文件的路径。 | 171 172**返回值：** 173 174| 类型 | 说明 | 175| ----------------- | -------------------------------------------- | 176| DataAbilityHelper | 用来协助其他Ability访问DataAbility的工具类。 | 177 178**示例：** 179 180```js 181import particleAbility from '@ohos.ability.particleAbility' 182var uri = ""; 183particleAbility.acquireDataAbilityHelper(uri) 184``` 185 186 187## particleAbility.startBackgroundRunning 188 189startBackgroundRunning(id: number, request: NotificationRequest, callback: AsyncCallback<void>): void; 190 191向系统申请长时任务，使用callback形式返回结果，建议使用新接口[backgroundTaskManager.startBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstartbackgroundrunning8)。 192 193**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 194 195**系统能力**：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 196 197**参数：** 198 199 | 参数名 | 类型 | 必填 | 说明 | 200 | -------- | -------- | -------- | -------- | 201 | id | number | 是 | 长时任务通知id号 | 202 | request | NotificationRequest | 是 | 通知参数，用于显示通知栏的信息 | 203 | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | 204 205 **示例**： 206 207```js 208import notification from '@ohos.notification'; 209import particleAbility from '@ohos.ability.particleAbility'; 210import wantAgent from '@ohos.wantAgent'; 211 212function callback(err, data) { 213 if (err) { 214 console.error("Operation failed Cause: " + err); 215 } else { 216 console.info("Operation succeeded"); 217 } 218} 219 220let wantAgentInfo = { 221 wants: [ 222 { 223 bundleName: "com.example.myapplication", 224 abilityName: "com.example.myapplication.MainAbility" 225 } 226 ], 227 operationType: wantAgent.OperationType.START_ABILITY, 228 requestCode: 0, 229 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] 230}; 231 232wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 233 let basicContent = { 234 title: "title", 235 text: "text" 236 }; 237 let notificationContent = { 238 contentType: notification.ContentType.NOTIFICATION_CONTENT_TEXT, 239 normal: basicContent 240 }; 241 let request = { 242 content: notificatonContent, 243 wantAgent: wantAgentObj 244 }; 245 let id = 1; 246 particleAbility.startBackgroundRunning(id, request, callback); 247}); 248 249``` 250 251## particleAbility.startBackgroundRunning 252 253startBackgroundRunning(id: number, request: NotificationRequest): Promise<void> 254 255**需要权限:** ohos.permission.KEEP_BACKGROUND_RUNNING 256 257**系统能力**：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 258 259向系统申请长时任务，使用promise形式返回结果，建议使用新接口[backgroundTaskManager.startBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstartbackgroundrunning8-1)。 260 261**参数：** 262 263| 参数名 | 类型 | 必填 | 说明 | 264| -------- | -------- | -------- | -------- | 265| id | number | 是 | 长时任务通知id号 | 266| request | NotificationRequest | 是 | 通知参数，用于显示通知栏的信息 | 267 268**返回值：** 269 270| 类型 | 说明 | 271| -------------- | ------------------------- | 272| Promise\<void> | 使用Promise形式返回结果。 | 273 274**示例**： 275 276```js 277import notification from '@ohos.notification'; 278import particleAbility from '@ohos.ability.particleAbility'; 279import wantAgent from '@ohos.wantAgent'; 280 281let wantAgentInfo = { 282 wants: [ 283 { 284 bundleName: "com.example.myapplication", 285 abilityName: "com.example.myapplication.MainAbility" 286 } 287 ], 288 operationType: wantAgent.OperationType.START_ABILITY, 289 requestCode: 0, 290 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] 291}; 292 293wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { 294 let basicContent = { 295 title: "title", 296 text: "text" 297 }; 298 let notificationContent = { 299 contentType: notification.ContentType.NOTIFICATION_CONTENT_TEXT, 300 normal: basicContent 301 }; 302 let request = { 303 content: notificatonContent, 304 wantAgent: wantAgentObj 305 }; 306 let id = 1; 307 particleAbility.startBackgroundRunning(id, request).then(() => { 308 console.info("Operation succeeded"); 309 }).catch((err) => { 310 console.error("Operation failed Cause: " + err); 311 }); 312}); 313 314``` 315 316## particleAbility.cancelBackgroundRunning 317 318cancelBackgroundRunning(callback: AsyncCallback<void>): void; 319 320向系统申请取消长时任务，使用callback形式返回结果，建议使用新接口[backgroundTaskManager.stopBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstopbackgroundrunning8)。 321 322**系统能力**：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 323 324 **参数：** 325 326 | 参数名 | 类型 | 必填 | 说明 | 327 | -------- | -------- | -------- | -------- | 328 | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | 329 330 **示例**： 331 332```js 333import particleAbility from '@ohos.ability.particleAbility'; 334 335function callback(err, data) { 336 if (err) { 337 console.error("Operation failed Cause: " + err); 338 } else { 339 console.info("Operation succeeded"); 340 } 341} 342 343particleAbility.cancelBackgroundRunning(callback); 344 345``` 346 347## particleAbility.cancelBackgroundRunning 348 349cancelBackgroundRunning(): Promise<void>; 350 351向系统申请取消长时任务，使用promise形式返回结果，建议使用新接口[backgroundTaskManager.stopBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstopbackgroundrunning8-1)。 352 353**系统能力**：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 354 355**返回值：** 356 357| 类型 | 说明 | 358| -------------- | ------------------------- | 359| Promise\<void> | 使用Promise形式返回结果。 | 360 361 **示例**： 362 363```js 364import particleAbility from '@ohos.ability.particleAbility'; 365 366particleAbility.cancelBackgroundRunning().then(() => { 367 console.info("Operation succeeded"); 368}).catch((err) => { 369 console.error("Operation failed Cause: " + err); 370}); 371 372``` 373 374 375## particleAbility.connectAbility 376 377connectAbility(request: Want, options:ConnectOptions): number 378 379将当前ability连接到指定ServiceAbility（callback形式）。 380 381**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 382 383**参数：** 384 385| 名称 | 类型 | 必填 | 描述 | 386| ------- | -------------- | ---- | ---------------------------- | 387| request | [Want](#want) | 是 | 表示被连接的ServiceAbility。 | 388| options | ConnectOptions | 是 | 被指定的回调方法。 | 389 390 391**ConnectOptions类型说明：** 392 393**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core 394 395| 名称 | 读写属性 | 类型 | 必填 | 描述 | 396| ------------ | ---- | -------- | ---- | ------------------------- | 397| onConnect | 只读 | function | 是 | 连接成功时的回调函数。 | 398| onDisconnect | 只读 | function | 是 | 连接失败时的回调函数。 | 399| onFailed | 只读 | function | 是 | ConnectAbility调用失败时的回调函数。 | 400 401**示例**： 402 403```js 404 function onConnectCallback(element, remote){ 405 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 406 } 407 function onDisconnectCallback(element){ 408 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 409 } 410 function onFailedCallback(code){ 411 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 412 } 413 var connId = particleAbility.connectAbility( 414 { 415 bundleName: "com.ix.ServiceAbility", 416 abilityName: "ServiceAbilityA", 417 }, 418 { 419 onConnect: onConnectCallback, 420 onDisconnect: onDisconnectCallback, 421 onFailed: onFailedCallback, 422 }, 423 ); 424 425 particleAbility.disconnectAbility(connId).then((error,data)=>{ 426 console.log('particleAbilityTest result errCode : ' + error.code + " data: " + data); 427 }); 428 429 430``` 431 432 433## particleAbility.disconnectAbility 434 435disconnectAbility(connection: number, callback:AsyncCallback\<void>): void; 436 437将功能与服务功能断开连接。 438 439**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 440 441**参数：** 442 443 | 参数名 | 类型 | 必填 | 说明 | 444 | -------- | -------- | -------- | -------- | 445 | callback | AsyncCallback<void> | 是 | callback形式返回断开连接的结果 | 446 447**示例**： 448 449```js 450 function onConnectCallback(element, remote){ 451 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 452 } 453 function onDisconnectCallback(element){ 454 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 455 } 456 function onFailedCallback(code){ 457 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 458 } 459 var connId = particleAbility.connectAbility( 460 { 461 bundleName: "com.ix.ServiceAbility", 462 abilityName: "ServiceAbilityA", 463 }, 464 { 465 onConnect: onConnectCallback, 466 onDisconnect: onDisconnectCallback, 467 onFailed: onFailedCallback, 468 }, 469 ); 470 var result = particleAbility.disconnectAbility(connId, 471 (error,data) => { 472 console.log('particleAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code + " data: " + data) 473 }, 474 ); 475 476``` 477 478 479## particleAbility.disconnectAbility 480 481disconnectAbility(connection: number): Promise\<void>; 482 483将功能与服务功能断开连接。 484 485**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 486 487**返回值：** 488 489| 类型 | 说明 | 490| -------------- | ------------------------- | 491| Promise\<void> | 使用Promise形式返回结果。 | 492 493**示例**： 494 495```js 496function onConnectCallback(element, remote){ 497 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 498 } 499 function onDisconnectCallback(element){ 500 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 501 } 502 function onFailedCallback(code){ 503 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 504 } 505 var connId = particleAbility.connectAbility( 506 { 507 bundleName: "com.ix.ServiceAbility", 508 abilityName: "ServiceAbilityA", 509 }, 510 { 511 onConnect: onConnectCallback, 512 onDisconnect: onDisconnectCallback, 513 onFailed: onFailedCallback, 514 }, 515 ); 516 517 particleAbility.disconnectAbility(connId).then((error,data)=>{ 518 console.log('particleAbilityTest result errCode : ' + error.code + " data: " + data); 519 }); 520 521``` 522 523## ErrorCode 524 525获取错误代码。 526 527**系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel 528 529| 变量 | 值 | 说明 | 530| ----------------------------- | ---- | ------------------------------------------------------------ | 531| INVALID_PARAMETER | -1 | 无效的参数。 | 532 533 534 535 536 537 538 539 540 541
