鸿蒙开发接口Ability框架：【@ohos.ability.particleAbility (particleAbility模块)】
particleAbility模块
particleAbility模块提供了Service类型Ability的能力，包括启动、停止指定的particleAbility，获取dataAbilityHelper，连接、断开当前Ability与指定ServiceAbility等。
说明：
本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
本模块接口仅可在FA模型下使用。
使用限制
particleAbility模块用来对Data和Service类型的Ability进行操作。
导入模块
import particleAbility from '@ohos.ability.particleAbility'
开发前请熟悉鸿蒙开发指导文档：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
particleAbility.startAbility
startAbility(parameter: StartAbilityParameter, callback: AsyncCallback): void
使用此方法启动指定的particleAbility（callback形式）。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
参数：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| parameter | [StartAbilityParameter] | 是 | 指示启动的ability |
| callback | AsyncCallback | 是 | 被指定的回调方法 |
示例：
import particleAbility from '@ohos.ability.particleAbility'
import wantConstant from '@ohos.ability.wantConstant'
particleAbility.startAbility(
{
want:
{
action: "action.system.home",
entities: ["entity.system.home"],
type: "MIMETYPE",
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: "",
bundleName: "com.example.Data",
abilityName: "com.example.Data.MainAbility",
uri:""
},
},
(error, result) = > {
console.log('particleAbility startAbility errCode:' + error + 'result:' + result)
},
)
particleAbility.startAbility
startAbility(parameter: StartAbilityParameter): Promise;
使用此方法启动指定的particleAbility（Promise形式）。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
参数：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| parameter | [StartAbilityParameter] | 是 | 指示启动的ability |
返回值：
| 类型 | 说明 |
|---|---|
| Promise | 使用Promise形式返回结果。 |
示例：
import particleAbility from '@ohos.ability.particleAbility'
import wantConstant from '@ohos.ability.wantConstant'
particleAbility.startAbility(
{
want:
{
action: "action.system.home",
entities: ["entity.system.home"],
type: "MIMETYPE",
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: "",
bundleName: "com.example.Data",
abilityName: "com.example. Data.MainAbility",
uri:""
},
},
).then((data) = > {
console.info("particleAbility startAbility");
});
particleAbility.terminateSelf
terminateSelf(callback: AsyncCallback): void
终止particleAbility（callback形式）。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
参数：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| callback | AsyncCallback | 是 | 表示被指定的回调方法 |
示例：
import particleAbility from '@ohos.ability.particleAbility'
particleAbility.terminateSelf(
(error, result) = > {
console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result)
}
)
particleAbility.terminateSelf
terminateSelf(): Promise
终止particleAbility（Promise形式）。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
返回值：
| 类型 | 说明 |
|---|---|
| Promise | 使用Promise形式返回结果。 |
示例：
import particleAbility from '@ohos.ability.particleAbility'
particleAbility.terminateSelf().then((data) = > {
console.info("particleAbility terminateSelf");
});
particleAbility.acquireDataAbilityHelper
acquireDataAbilityHelper(uri: string): DataAbilityHelper
获取dataAbilityHelper。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
参数：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| uri | string | 是 | 指示要打开的文件的路径。 |
返回值：
| 类型 | 说明 |
|---|---|
| DataAbilityHelper | 用来协助其他Ability访问DataAbility的工具类。 |
示例：
import particleAbility from '@ohos.ability.particleAbility'
var uri = "";
particleAbility.acquireDataAbilityHelper(uri)
particleAbility.startBackgroundRunning
startBackgroundRunning(id: number, request: NotificationRequest, callback: AsyncCallback): void;
向系统申请长时任务，使用callback形式返回结果，建议使用新接口[backgroundTaskManager.startBackgroundRunning]
需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING
系统能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | number | 是 | 长时任务通知id号 |
| request | NotificationRequest | 是 | 通知参数，用于显示通知栏的信息 |
| callback | AsyncCallback | 是 | callback形式返回启动长时任务的结果 |
示例 ：
import notification from '@ohos.notification';
import particleAbility from '@ohos.ability.particleAbility';
import wantAgent from '@ohos.wantAgent';
function callback(err, data) {
if (err) {
console.error("Operation failed Cause: " + err);
} else {
console.info("Operation succeeded");
}
}
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) = > {
let basicContent = {
title: "title",
text: "text"
};
let notificationContent = {
contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: basicContent
};
let request = {
content: notificationContent,
wantAgent: wantAgentObj
};
let id = 1;
particleAbility.startBackgroundRunning(id, request, callback);
});
particleAbility.startBackgroundRunning
startBackgroundRunning(id: number, request: NotificationRequest): Promise
需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING
系统能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
向系统申请长时任务，使用promise形式返回结果，建议使用新接口[backgroundTaskManager.startBackgroundRunning]
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | number | 是 | 长时任务通知id号 |
| request | NotificationRequest | 是 | 通知参数，用于显示通知栏的信息 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise | 使用Promise形式返回结果。 |
示例 ：
import notification from '@ohos.notification';
import particleAbility from '@ohos.ability.particleAbility';
import wantAgent from '@ohos.wantAgent';
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) = > {
let basicContent = {
title: "title",
text: "text"
};
let notificationContent = {
contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: basicContent
};
let request = {
content: notificationContent,
wantAgent: wantAgentObj
};
let id = 1;
particleAbility.startBackgroundRunning(id, request).then(() = > {
console.info("Operation succeeded");
}).catch((err) = > {
console.error("Operation failed Cause: " + err);
});
});
particleAbility.cancelBackgroundRunning
cancelBackgroundRunning(callback: AsyncCallback): void;
向系统申请取消长时任务，使用callback形式返回结果，建议使用新接口[backgroundTaskManager.stopBackgroundRunning]
系统能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | AsyncCallback | 是 | callback形式返回启动长时任务的结果 |
示例 ：
import particleAbility from '@ohos.ability.particleAbility';
function callback(err, data) {
if (err) {
console.error("Operation failed Cause: " + err);
} else {
console.info("Operation succeeded");
}
}
particleAbility.cancelBackgroundRunning(callback);
particleAbility.cancelBackgroundRunning
cancelBackgroundRunning(): Promise;
向系统申请取消长时任务，使用promise形式返回结果，建议使用新接口[backgroundTaskManager.stopBackgroundRunning]
系统能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
返回值：
| 类型 | 说明 |
|---|---|
| Promise | 使用Promise形式返回结果。 |
示例 ：
import particleAbility from '@ohos.ability.particleAbility';
particleAbility.cancelBackgroundRunning().then(() = > {
console.info("Operation succeeded");
}).catch((err) = > {
console.error("Operation failed Cause: " + err);
});
particleAbility.connectAbility
connectAbility(request: Want, options:ConnectOptions): number
将当前ability连接到指定ServiceAbility（callback形式）。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
参数：
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| request | [Want]) | 是 | 表示被连接的ServiceAbility。 |
| options | ConnectOptions | 是 | 被指定的回调方法。 |
ConnectOptions类型说明：
系统能力 ：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core
| 名称 | 读写属性 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
| onConnect | 只读 | function | 是 | 连接成功时的回调函数。 |
| onDisconnect | 只读 | function | 是 | 连接失败时的回调函数。 |
| onFailed | 只读 | function | 是 | ConnectAbility调用失败时的回调函数。 |
示例 ：
import rpc from '@ohos.rpc'
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('particleAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = particleAbility.connectAbility(
{
bundleName: "com.ix.ServiceAbility",
abilityName: "ServiceAbilityA",
},
{
onConnect: onConnectCallback,
onDisconnect: onDisconnectCallback,
onFailed: onFailedCallback,
},
);
particleAbility.disconnectAbility(connId).then((data)= >{
console.log( " data: " + data);
}).catch((error)= >{
console.log('particleAbilityTest result errCode : ' + error.code )
});
particleAbility.disconnectAbility
disconnectAbility(connection: number, callback:AsyncCallback): void;
将功能与服务功能断开连接。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | AsyncCallback | 是 | callback形式返回断开连接的结果 |
示例 ：
import rpc from '@ohos.rpc'
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('particleAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = particleAbility.connectAbility(
{
bundleName: "com.ix.ServiceAbility",
abilityName: "ServiceAbilityA",
},
{
onConnect: onConnectCallback,
onDisconnect: onDisconnectCallback,
onFailed: onFailedCallback,
},
);
var result = particleAbility.disconnectAbility(connId).then((data)= >{
console.log( " data: " + data);
}).catch((error)= >{
console.log('particleAbilityTest result errCode : ' + error.code )
});
particleAbility.disconnectAbility
disconnectAbility(connection: number): Promise;
将功能与服务功能断开连接。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
返回值：
| 类型 | 说明 |
|---|---|
| Promise | 使用Promise形式返回结果。 |
示例 ：
import rpc from '@ohos.rpc'
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('particleAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connId = particleAbility.connectAbility(
{
bundleName: "com.ix.ServiceAbility",
abilityName: "ServiceAbilityA",
},
{
onConnect: onConnectCallback,
onDisconnect: onDisconnectCallback,
onFailed: onFailedCallback,
},
);
particleAbility.disconnectAbility(connId).then((data)= >{
console.log( " data: " + data);
}).catch((error)= >{
console.log('particleAbilityTest result errCode : ' + error.code )
});
ErrorCode
获取错误代码。
系统能力 ：SystemCapability.Ability.AbilityRuntime.FAModel
| 变量 | 值 | 说明 |
|---|---|---|
| INVALID_PARAMETER | -1 | 无效的参数。 |
审核编辑 黄宇
-
接口
+关注
关注
33文章
8574浏览量
151011 -
框架
+关注
关注
0文章
403浏览量
17474 -
鸿蒙
+关注
关注
57文章
2339浏览量
42803
发布评论请先 登录
相关推荐
鸿蒙开发接口Ability框架：【@ohos.application.Ability (Ability)】
鸿蒙开发接口Ability框架：【@ohos.ability.featureAbility (FeatureAbility模块)】
鸿蒙开发接口Ability框架：【@ohos.application.missionManager (missionManager)】
鸿蒙开发接口Ability框架：【 (Context模块)】
鸿蒙开发接口Ability框架：【(AbilityContext)】
鸿蒙开发接口Ability框架：【(AbilityDelegator)】
鸿蒙开发接口Ability框架：【AbilityRunningInfo】
鸿蒙开发接口Ability框架：【AbilityDelegator】
鸿蒙Ability开发-Stage模型下Ability的创建和使用
使用FeatureAbility模块启动其他Ability
HarmonyOS/OpenHarmony应用开发-ArkTS的Ability基类
鸿蒙之@ohos.app.ability.appRecovery (appRecovery)
鸿蒙开发接口Ability框架：【AbilityRunningInfo】
鸿蒙Ability Kit（程序框架服务）【Ability内页面间的跳转】
鸿蒙Ability Kit（程序框架服务）【Ability与ServiceExtensionAbility通信】
工商网监
评论