ArkTS Api详解(ParticleAbility)

53 阅读2分钟

@ohos.ability.particleAbility

particleAbility模块提供了操作Service类型的Ability的能力,包括启动、停止指定的particleAbility,获取dataAbilityHelper,连接、断连指定的ServiceAbility等。

particleAbility.startAbility

启动指定的particleAbility(callback形式)。

使用规则:

  • 调用方应用位于后台时,使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限
  • 目标Ability的visible属性若配置为false,调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限
  • 组件启动规则详见:组件启动规则(FA模型)
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

启动指定的particleAbility(Promise形式)。

使用规则:

  • 调用方应用位于后台时,使用该接口启动Ability需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限
  • 目标Ability的visible属性若配置为false,调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限
  • 组件启动规则详见:组件启动规则(FA模型)
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形式)。

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

particleAbility.terminateSelf(
    (error, result) => {
        console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result);
    }
);

particleAbility.terminateSelf

terminateSelf(): Promise

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

particleAbility.terminateSelf().then((data) => {
    console.info('particleAbility terminateSelf');
});

particleAbility.acquireDataAbilityHelper

获取dataAbilityHelper对象。

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

let uri = '';
particleAbility.acquireDataAbilityHelper(uri);

particleAbility.startBackgroundRunning

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

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

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);
});

particleAbility.startBackgroundRunning

startBackgroundRunning(id: number, 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: ' + JSON.stringify(err));
    });
});

particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(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);

particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(): Promise;

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

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

particleAbility.cancelBackgroundRunning().then(() => {
    console.info('Operation succeeded');
}).catch((err) => {
    console.error('Operation failed cause: ' + JSON.stringify(err));
});

particleAbility.connectAbility

将当前ability与指定的ServiceAbility进行连接(callback形式)。

import particleAbility from '@ohos.ability.particleAbility';
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);
}

let 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;

断开当前ability与指定ServiceAbility的连接(callback形式)。

import particleAbility from '@ohos.ability.particleAbility';
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);
}

let connId = particleAbility.connectAbility(
    {
        bundleName: 'com.ix.ServiceAbility',
        abilityName: 'ServiceAbilityA',
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

particleAbility.disconnectAbility(connId, (err) => {
    console.log('particleAbilityTest disconnectAbility err====>'
    + ('json err=') + JSON.stringify(err));
});

particleAbility.disconnectAbility

disconnectAbility(connection: number): Promise;

断开当前ability与指定ServiceAbility的连接(Promise形式)。

import particleAbility from '@ohos.ability.particleAbility';
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);
}

let 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);
});