1# ParticleAbility模块(JS端SDK接口) 2 3#### 支持设备 4 5| API | 手机 | 平板 | 智慧屏 | 智能穿戴 | 轻量级智能穿戴 | 智慧视觉设备 | 6| ------------------------------------------------------------ | ---- | ---- | ------ | -------- | -------------- | ------------ | 7| ParticleAbility.startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<void> | 支持 | 支持 | 支持 | 支持 | 不支持 | 不支持 | 8| ParticleAbility.startAbility(parameter: StartAbilityParameter) | 支持 | 支持 | 支持 | 支持 | 不支持 | 不支持 | 9| ParticleAbility.terminateSelf(callback: AsyncCallback\<void>) | 支持 | 支持 | 支持 | 支持 | 不支持 | 不支持 | 10| ParticleAbility.terminateSelf() | 支持 | 支持 | 支持 | 支持 | 不支持 | 不支持 | 11| ParticleAbility.acquireDataAbilityHelper(uri: string) | 支持 | 支持 | 支持 | 支持 | 不支持 | 不支持 | 12 13#### 权限列表 14 15ohos.permission.RUNNING_LOCK permission 16 17#### 使用限制 18 19ParticleAbility模块的接口只能在Ability为Data和Service类型的时候进行调用 20 21#### 导入模块 22 23``` 24import featureAbility from '@ohos.ability.featureAbility' 25``` 26 27#### ParticleAbility.startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\<void> 28 29- 接口说明 30 31 服务ability使用此方法启动特定ability(callback形式) 32 33- startAbility参数描述 34 35 36| 名称 | 读写属性 | 类型 | 必填 | 描述 | 37| --------- | -------- | --------------------- | ---- | ----------------- | 38| parameter | 只读 | StartAbilityParameter | 是 | 指示启动的ability | 39| callback | 只读 | AsyncCallback\<void> | 是 | 被指定的回调方法 | 40 41- StartAbilityParameter类型说明 42 43| 名称 | 读写属性 | 类型 | 必填 | 描述 | 44| ------------------- | -------- | ------ | ---- | ---------------------------------- | 45| want | 只读 | want | 是 | 表示需要包含有关目标启动能力的信息 | 46| abilityStartSetting | 只读 | string | 否 | 指示启动能力中使用的特殊启动设置 | 47 48- want类型说明 49 50| 名称 | 读写属性 | 类型 | 必填 | 描述 | 51| ----------- | -------- | ------ | ---- | -------------------------- | 52| deviceId | 只读 | string | 否 | 设备id | 53| bundleName | 只读 | string | 否 | 捆绑包名称 | 54| abilityName | 只读 | string | 否 | ability 名字 | 55| uri | 只读 | string | 否 | 请求中URI的描述 | 56| type | 只读 | string | 否 | 此文件中类型的说明 | 57| flags | 只读 | number | 否 | 此文件中标志的选项是必需的 | 58| action | 只读 | string | 否 | 需求中对操作的描述 | 59| parameters | 只读 | string | 否 | Want中WantParams对象的描述 | 60| entities | 只读 | string | 否 | 对象中实体的描述 | 61 62- flags类型说明 63 64 | 名称 | 参数 | 描述 | 65 | ------------------------------------ | ---------- | ------------------------------------------------------------ | 66 | FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | 指示对URI执行读取操作的授权 | 67 | FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | 指示对URI执行写入操作的授权 | 68 | FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | 将结果返回给源异能 | 69 | FLAG_ABILITY_CONTINUATION | 0x00000008 | 确定是否可以将本地设备上的功能迁移到远程设备 | 70 | FLAG_NOT_OHOS_COMPONENT | 0x00000010 | 指定组件是否不属于OHOS | 71 | FLAG_ABILITY_FORM_ENABLED | 0x00000020 | 指定是否启动某个能力 | 72 | FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | 指示URI上可能持久化的授权 | 73 | FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | 将结果返回到源能力片 | 74 | FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | 支持分布式调度系统中的多设备启动 | 75 | FLAG_START_FOREGROUND_ABILITY | 0x00000200 | 指示无论主机应用程序是否已启动，都将启动使用服务模板的功能 | 76 | FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | 表示延续是可逆的。 | 77 | FLAG_INSTALL_ON_DEMAND | 0x00000800 | 如果未安装指定的功能，请安装该功能 | 78 | FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | 如果未安装，请使用后台模式安装指定的DI功能。 | 79 | FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | 指示清除其他任务的操作。可以为传递给{@link ohos.app.Context#startAbility}的{@code Intent}设置此标志，并且必须与{@link flag_ABILITY_NEW_MISSION}一起使用 | 80 | FLAG_ABILITY_NEW_MISSION | 0x10000000 | 指示在历史任务堆栈上创建任务的操作。 | 81 | FLAG_ABILITY_MISSION_TOP | 0x20000000 | 指示如果启动能力的现有实例已位于任务堆栈的顶部，则将重用该实例。否则，将创建一个新的能力实例。 | 82 83- 返回值 84 85 void 86 87- 示例 88 89```js 90import particleAbility from '@ohos.ability.particleAbility' 91particleAbility.startAbility( 92 { 93 want: 94 { 95 action: "action.system.home", 96 entities: ["entity.system.home"], 97 type: "MIMETYPE", 98 flags: FLAG_AUTH_READ_URI_PERMISSION; 99 deviceId: "", 100 bundleName: "com.example.Data", 101 abilityName: "com.jstest.startabilitytest5.MainAbility", 102 uri:"" 103 }, 104 }, 105) 106``` 107 108 109 110#### ParticleAbility.startAbility(parameter: StartAbilityParameter) 111 112- 接口说明 113服务ability使用此方法启动特定ability((Promise形式) 114- startAbility参数描述 115 116 117| 名称 | 读写属性 | 类型 | 必填 | 描述 | 118| --------- | -------- | --------------------- | ---- | ----------------- | 119| parameter | 只读 | StartAbilityParameter | 是 | 指示启动的ability | 120- StartAbilityParameter类型说明 121 122| 名称 | 读写属性 | 类型 | 必填 | 描述 | 123| ------------------- | -------- | ------ | ---- | ---------------------------------- | 124| want | 只读 | want | 是 | 表示需要包含有关目标启动能力的信息 | 125| abilityStartSetting | 只读 | string | 否 | 指示启动能力中使用的特殊启动设置 | 126 127- want类型说明 128 129| 名称 | 读写属性 | 类型 | 必填 | 描述 | 130| ----------- | -------- | ------ | ---- | -------------------------- | 131| deviceId | 只读 | string | 否 | 设备id | 132| bundleName | 只读 | string | 否 | 捆绑包名称 | 133| abilityName | 只读 | string | 否 | ability 名字 | 134| uri | 只读 | string | 否 | 请求中URI的描述 | 135| type | 只读 | string | 否 | 此文件中类型的说明 | 136| flags | 只读 | number | 否 | 此文件中标志的选项是必需的 | 137| action | 只读 | string | 否 | 需求中对操作的描述 | 138| parameters | 只读 | string | 否 | Want中WantParams对象的描述 | 139| entities | 只读 | string | 否 | 对象中实体的描述 | 140 141- flags类型说明 142 143 | 名称 | 参数 | 描述 | 144 | ------------------------------------ | ---------- | ------------------------------------------------------------ | 145 | FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | 指示对URI执行读取操作的授权 | 146 | FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | 指示对URI执行写入操作的授权 | 147 | FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | 将结果返回给源异能 | 148 | FLAG_ABILITY_CONTINUATION | 0x00000008 | 确定是否可以将本地设备上的功能迁移到远程设备 | 149 | FLAG_NOT_OHOS_COMPONENT | 0x00000010 | 指定组件是否不属于OHOS | 150 | FLAG_ABILITY_FORM_ENABLED | 0x00000020 | 指定是否启动某个能力 | 151 | FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | 指示URI上可能持久化的授权 | 152 | FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | 将结果返回到源能力片 | 153 | FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | 支持分布式调度系统中的多设备启动 | 154 | FLAG_START_FOREGROUND_ABILITY | 0x00000200 | 指示无论主机应用程序是否已启动，都将启动使用服务模板的功能 | 155 | FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | 表示延续是可逆的。 | 156 | FLAG_INSTALL_ON_DEMAND | 0x00000800 | 如果未安装指定的功能，请安装该功能 | 157 | FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | 如果未安装，请使用后台模式安装指定的DI功能。 | 158 | FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | 指示清除其他任务的操作。可以为传递给{@link ohos.app.Context#startAbility}的{@code Intent}设置此标志，并且必须与{@link flag_ABILITY_NEW_MISSION}一起使用 | 159 | FLAG_ABILITY_NEW_MISSION | 0x10000000 | 指示在历史任务堆栈上创建任务的操作。 | 160 | FLAG_ABILITY_MISSION_TOP | 0x20000000 | 指示如果启动能力的现有实例已位于任务堆栈的顶部，则将重用该实例。否则，将创建一个新的能力实例。 | 161 162- 返回值 163 164 void 165 166- 示例 167 168```js 169import featureAbility from '@ohos.ability.featureAbility' 170import particleAbility from '@ohos.ability.particleAbility' 171var windowMode = featureAbility.AbilityStartSetting.WINDOW_MODE_KEY; 172particleAbility.startAbility( 173 want: 174 { 175 bundleName: "com.jstest.featureabilitytest", 176 abilityName: "com.jstest.startabilitytest1.MainAbility", 177 }, 178 abilityStartSetting: 179 { 180 windowMode: featureAbility.AbilityWindowConfiguration.WINDOW_MODE_FLOATING, 181 }, 182 } 183 184 ).then((void) => { 185 console.info("==========================>startAbilityCallback=======================>"); 186}); 187``` 188 189 190 191#### ParticleAbility.terminateSelf(callback: AsyncCallback\<void>) 192 193- 接口说明 194 195 摧毁服务ability(callback形式) 196 197- terminateSelf参数描述 198 199 | 名称 | 读写属性 | 类型 | 必填 | 描述 | 200 | -------- | -------- | -------------------- | ---- | -------------------- | 201 | callback | 只读 | AsyncCallback\<void> | 是 | 表示被指定的回调方法 | 202 203- 返回值 204 205 void 206 207- 示例 208 209```js 210import particleAbility from '@ohos.ability.particleAbility' 211ParticleAbility.terminateSelf() 212``` 213 214 215 216#### ParticleAbility.terminateSelf() 217 218- 接口说明 219 220 摧毁服务ability(Promise形式) 221 222- 返回值 223 224 void 225 226- 示例 227 228```js 229import particleAbility from '@ohos.ability.particleAbility' 230particleAbility.terminateSelf().then((void) => { 231 console.info("==========================>terminateSelfCallback=======================>"); 232}); 233``` 234 235 236 237#### ParticleAbility.acquireDataAbilityHelper(uri: string) 238 239- 接口说明 240 241 获取dataAbilityHelper 242 243- acquireDataAbilityHelper参数描述 244 245 | 名称 | 读写属性 | 类型 | 必填 | 描述 | 246 | :--- | -------- | ------ | ---- | ---------------------- | 247 | uri | 只读 | string | 是 | 指示要打开的文件的路径 | 248 249- 返回值 250 251 返回dataAbilityHelper 252 253- 示例 254 255```js 256import particleAbility from '@ohos.ability.particleAbility' 257var uri = ""; 258ParticleAbility.acquireDataAbilityHelper(uri) 259``` 260 261#### ParticleAbility.connectAbility(*request*: Want, *options*:ConnectOptions): number 262 263* 接口说明 264 265 将当前ability连接到指定ServiceAbility(callback形式) 266 267* connectAbility参数描述 268 269| 名称 | 读写属性 | 类型 | 必填 | 描述 | 270| ------- | -------- | -------------- | ---- | -------------------------- | 271| request | 只读 | Want | 是 | 表示被连接的ServiceAbility | 272| options | 只读 | ConnectOptions | 是 | 被指定的回调方法 | 273 274- ConnectOptions类型说明 275 276| 名称 | 读写属性 | 类型 | 必填 | 描述 | 277| ------------ | -------- | -------- | ---- | ---------------------------------- | 278| onConnect | 只读 | function | 是 | 连接成功时的回调函数 | 279| onDisconnect | 只读 | function | 是 | 连接失败时的回调函数 | 280| onFailed | 只读 | function | 是 | ConnectAbility调用失败时的回调函数 | 281 282* 返回值 283 284 连接的ServiceAbilityID。 285 286* 示例 287 288```javascript 289import particleAbility from '@ohos.ability.particleAbility' 290var mRemote; 291var connId; 292function onConnectCallback(element, remote){ 293 mRemote = remote; 294 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 295} 296function onDisconnectCallback(element){ 297 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 298} 299function onFailedCallback(code){ 300 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 301} 302var connId = particleAbility.connectAbility( 303 { 304 bundleName: "com.ix.ServiceAbility", 305 abilityName: "ServiceAbilityA", 306 }, 307 { 308 onConnect: onConnectCallback, 309 onDisconnect: onDisconnectCallback, 310 onFailed: onFailedCallback, 311 }, 312); 313``` 314 315#### ParticleAbility.disconnectAbility(connection: number, callback:AsyncCallback<void>): void 316 317* 接口说明 318 319 断开与指定ServiceAbility的连接(callback形式) 320 321* disconnectAbility参数描述 322 323| 名称 | 读写属性 | 类型 | 必填 | 描述 | 324| ---------- | -------- | ------------- | ---- | ------------------------------ | 325| connection | 只读 | number | 是 | 指定断开连接的ServiceAbilityID | 326| callback | 只读 | AsyncCallback | 是 | 被指定的回调方法 | 327 328* 返回值 329 330 无 331 332* 示例 333 334```javascript 335import particleAbility from '@ohos.ability.particleAbility' 336var mRemote; 337var connId; 338function onConnectCallback(element, remote){ 339 mRemote = remote; 340 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 341} 342function onDisconnectCallback(element){ 343 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 344} 345function onFailedCallback(code){ 346 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 347} 348var connId = particleAbility.connectAbility( 349 { 350 bundleName: "com.ix.ServiceAbility", 351 abilityName: "ServiceAbilityA", 352 }, 353 { 354 onConnect: onConnectCallback, 355 onDisconnect: onDisconnectCallback, 356 onFailed: onFailedCallback, 357 }, 358); 359var result = particleAbility.disconnectAbility(connId, 360 (error,data) => { 361 console.log('particleAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code + " data: " + data) 362 }, 363); 364``` 365 366#### ParticleAbility.disconnectAbility(connection: number): Promise<void>; 367 368* 接口说明 369 370 断开与指定ServiceAbility的连接(promise形式) 371 372* disconnectAbility参数描述 373 374| 名称 | 读写属性 | 类型 | 必填 | 描述 | 375| ---------- | -------- | ------ | ---- | ------------------------------ | 376| connection | 只读 | number | 是 | 指定断开连接的ServiceAbilityID | 377 378* 返回值 379 380 无 381 382* 示例 383 384```javascript 385import particleAbility from '@ohos.ability.particleAbility' 386var mRemote; 387var connId; 388function onConnectCallback(element, remote){ 389 mRemote = remote; 390 console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); 391} 392function onDisconnectCallback(element){ 393 console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) 394} 395function onFailedCallback(code){ 396 console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) 397} 398var connId = particleAbility.connectAbility( 399 { 400 bundleName: "com.ix.ServiceAbility", 401 abilityName: "ServiceAbilityA", 402 }, 403 { 404 onConnect: onConnectCallback, 405 onDisconnect: onDisconnectCallback, 406 onFailed: onFailedCallback, 407 }, 408); 409var result = await particleAbility.disconnectAbility(connId); 410``` 411 412