HarmonyOS API：FA模型能力接口

joytrian

发布于 2023-3-31 17:46

浏览

0收藏

版本：v3.1 Beta

@ohos.ability.particleAbility (ParticleAbility模块)

更新时间: 2023-02-17 09:19

particleAbility模块提供了Service类型Ability的能力，包括启动、停止指定的particleAbility，获取dataAbilityHelper，连接、断开当前Ability与指定ServiceAbility等。

说明

本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块接口仅可在FA模型下使用。

使用限制

particleAbility模块用来对Data和Service类型的Ability进行操作。

导入模块

import particleAbility from '@ohos.ability.particleAbility'1.

particleAbility.startAbility

startAbility(parameter: StartAbilityParameter, callback: AsyncCallback<void>): void

使用此方法启动指定的particleAbility（callback形式）。

系统能力：SystemCapability.Ability.AbilityRuntime.FAModel

参数：

参数名	类型	必填	说明
parameter	StartAbilityParameter	是	指示启动的ability
callback	AsyncCallback<void>	是	被指定的回调方法

示例：

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)
    },
)1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.

particleAbility.startAbility

startAbility(parameter: StartAbilityParameter): Promise<void>;

使用此方法启动指定的particleAbility（Promise形式）。

系统能力：SystemCapability.Ability.AbilityRuntime.FAModel

参数：

参数名	类型	必填	说明
parameter	StartAbilityParameter	是	指示启动的ability

返回值：

类型	说明
Promise<void>	使用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");
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.

particleAbility.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

终止particleAbility（callback形式）。

系统能力：SystemCapability.Ability.AbilityRuntime.FAModel

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	表示被指定的回调方法

示例：

import particleAbility from '@ohos.ability.particleAbility'

particleAbility.terminateSelf(
    (error, result) => {
        console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result)
    }
)1.
2.
3.
4.
5.
6.
7.

particleAbility.terminateSelf

terminateSelf(): Promise<void>

终止particleAbility（Promise形式）。

系统能力：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

类型	说明
Promise<void>	使用Promise形式返回结果。

示例：

import particleAbility from '@ohos.ability.particleAbility'

particleAbility.terminateSelf().then((data) => {
    console.info("particleAbility terminateSelf");
});1.
2.
3.
4.
5.

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)1.
2.
3.
4.

particleAbility.startBackgroundRunning

startBackgroundRunning(id: number, request: NotificationRequest, callback: AsyncCallback<void>): void;

向系统申请长时任务，使用callback形式返回结果。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

系统能力：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

参数：

参数名	类型	必填	说明
id	number	是	长时任务通知id号
request	NotificationRequest	是	通知参数，用于显示通知栏的信息
callback	AsyncCallback<void>	是	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: " + JSON.stringify(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);
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.

particleAbility.startBackgroundRunning

startBackgroundRunning(id: number, request: NotificationRequest): Promise<void>

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

系统能力：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

向系统申请长时任务，使用promise形式返回结果。

参数：

参数名	类型	必填	说明
id	number	是	长时任务通知id号
request	NotificationRequest	是	通知参数，用于显示通知栏的信息

返回值：

类型	说明
Promise<void>	使用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: " + JSON.stringify(err));
    });
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.

particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(callback: AsyncCallback<void>): void;

向系统申请取消长时任务，使用callback形式返回结果。

系统能力：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	callback形式返回启动长时任务的结果

示例：

import particleAbility from '@ohos.ability.particleAbility';

function callback(err, data) {
    if (err) {
        console.error("Operation failed cause: " + JSON.stringify(err));
    } else {
        console.info("Operation succeeded");
    }
}

particleAbility.cancelBackgroundRunning(callback);1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(): Promise<void>;

向系统申请取消长时任务，使用promise形式返回结果。

系统能力：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

返回值：

类型	说明
Promise<void>	使用Promise形式返回结果。

示例：

import particleAbility from '@ohos.ability.particleAbility';

particleAbility.cancelBackgroundRunning().then(() => {
    console.info("Operation succeeded");
}).catch((err) => {
    console.error("Operation failed cause: " + JSON.stringify(err));
});1.
2.
3.
4.
5.
6.
7.

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)
});
    1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.

particleAbility.disconnectAbility

disconnectAbility(connection: number, callback:AsyncCallback<void>): void;

将功能与服务功能断开连接。

系统能力：SystemCapability.Ability.AbilityRuntime.FAModel

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	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)
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.

particleAbility.disconnectAbility

disconnectAbility(connection: number): Promise<void>;

将功能与服务功能断开连接。

系统能力：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

类型	说明
Promise<void>	使用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)
});1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.

ErrorCode

获取错误代码。

系统能力：SystemCapability.Ability.AbilityRuntime.FAModel

名称	值	说明
INVALID_PARAMETER	-1	无效的参数。

文章转载自：https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-ability-particleability-0000001478341281-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001478341281__导入模块

分类

卡片开发

三方库

标签

HarmonyOS API

已于2023-3-31 17:46:46修改

51CTO

51CTO博客

51CTO学堂

HarmonyOS API：FA模型能力接口

@ohos.ability.particleAbility (ParticleAbility模块)

使用限制

导入模块

particleAbility.startAbility

particleAbility.startAbility

particleAbility.terminateSelf

particleAbility.terminateSelf

particleAbility.acquireDataAbilityHelper

particleAbility.startBackgroundRunning

particleAbility.startBackgroundRunning

particleAbility.cancelBackgroundRunning

particleAbility.cancelBackgroundRunning

particleAbility.connectAbility

particleAbility.disconnectAbility

particleAbility.disconnectAbility

ErrorCode

目录

订阅鸿蒙技术特刊，精选内容抢先看