particleAbility模塊

particleAbility模塊提供了Service類型Ability的能力，包括啟動、停止指定的particleAbility，獲取dataAbilityHelper，連接、斷開當前Ability與指定ServiceAbility等。

說明：

本模塊首批接口從API version 7開始支持。后續(xù)版本的新增接口，采用上角標單獨標記接口的起始版本。
本模塊接口僅可在FA模型下使用。

使用限制

particleAbility模塊用來對Data和Service類型的Ability進行操作。

導入模塊

import particleAbility from '@ohos.ability.particleAbility'

開發(fā)前請熟悉鴻蒙開發(fā)指導文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

particleAbility.startAbility

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

使用此方法啟動指定的particleAbility（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

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形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

返回值：

示例：

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形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

import particleAbility from '@ohos.ability.particleAbility'
particleAbility.terminateSelf(
    (error, result) = > {
		console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result)
    }
)

particleAbility.terminateSelf

terminateSelf(): Promise

終止particleAbility（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

示例：

import particleAbility from '@ohos.ability.particleAbility'
particleAbility.terminateSelf().then((data) = > {
	console.info("particleAbility terminateSelf");
});

particleAbility.acquireDataAbilityHelper

acquireDataAbilityHelper(uri: string): DataAbilityHelper

獲取dataAbilityHelper。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

返回值：

示例：

import particleAbility from '@ohos.ability.particleAbility'     
var uri = "";
particleAbility.acquireDataAbilityHelper(uri)

particleAbility.startBackgroundRunning

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

向系統(tǒng)申請長時任務，使用callback形式返回結果，建議使用新接口[backgroundTaskManager.startBackgroundRunning]

需要權限: ohos.permission.KEEP_BACKGROUND_RUNNING

系統(tǒng)能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

參數(shù)：

示例 ：

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

系統(tǒng)能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

向系統(tǒng)申請長時任務，使用promise形式返回結果，建議使用新接口[backgroundTaskManager.startBackgroundRunning]

參數(shù)：

返回值：

示例 ：

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;

向系統(tǒng)申請取消長時任務，使用callback形式返回結果，建議使用新接口[backgroundTaskManager.stopBackgroundRunning]

系統(tǒng)能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

參數(shù)：

示例 ：

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;

向系統(tǒng)申請取消長時任務，使用promise形式返回結果，建議使用新接口[backgroundTaskManager.stopBackgroundRunning]

系統(tǒng)能力 ：SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

返回值：

示例 ：

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形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

ConnectOptions類型說明：

系統(tǒng)能力 ：以下各項對應的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.Core

示例 ：

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;

將功能與服務功能斷開連接。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例 ：

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;

將功能與服務功能斷開連接。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

示例 ：

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

獲取錯誤代碼。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

審核編輯 黃宇