harmony 鸿蒙@ohos.ability.particleAbility (ParticleAbility模块)

  • 2022-12-13
  • 浏览 (618)

@ohos.ability.particleAbility (ParticleAbility模块)

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

说明:

本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
本模块接口仅可在FA模型下使用。

使用限制

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

导入模块

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

particleAbility.startAbility

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

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

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

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

参数:

参数名 类型 必填 说明
parameter StartAbilityParameter 表示启动的ability
callback AsyncCallback<void> 以callback的形式返回启动Ability的结果

示例:

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

particleAbility.startAbility(
    {
        want:
        {
            action: 'ohos.want.action.home',
            entities: ['entity.system.home'],
            type: 'MIMETYPE',
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: '',
            bundleName: 'com.example.Data',
            abilityName: 'EntryAbility',
            uri: ''
        },
    },
    (error, data) => {
        if (error && error.code !== 0) {
            console.error(`startAbility fail, error: ${JSON.stringify(error)}`);
        } else {
            console.log(`startAbility success, data: ${JSON.stringify(data)}`);
        }
    },
);

particleAbility.startAbility

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

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

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

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

参数:

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

返回值:

类型 说明
Promise<void> Promise形式返回启动Ability的结果。

示例:

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

particleAbility.startAbility(
    {
        want:
        {
            action: 'ohos.want.action.home',
            entities: ['entity.system.home'],
            type: 'MIMETYPE',
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: '',
            bundleName: 'com.example.Data',
            abilityName: 'EntryAbility',
            uri: ''
        },
    },
).then((data) => {
    console.info('particleAbility startAbility');
});

particleAbility.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

销毁当前particleAbility(callback形式)。

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

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 以callback的形式返回停止当前Ability结果

示例:

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

particleAbility.terminateSelf(
    (error, data) => {
        if (error && error.code !== 0) {
            console.error(`terminateSelf fail, error: ${JSON.stringify(error)}`);
        } else {
            console.log(`terminateSelf success, data: ${JSON.stringify(data)}`);
        }
    }
);

particleAbility.terminateSelf

terminateSelf(): Promise<void>

销毁当前particleAbility(Promise形式)。

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

返回值:

类型 说明
Promise<void> 使用Promise形式返回停止当前Ability结果。

示例:

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

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

particleAbility.acquireDataAbilityHelper

acquireDataAbilityHelper(uri: string): DataAbilityHelper

获取dataAbilityHelper对象。

使用规则: - 跨应用访问dataAbility,对端应用需配置关联启动 - 调用方应用位于后台时,使用该接口访问dataAbility需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限(基于API 8或更早版本SDK开发的应用在启动DataAbility组件时不受此限制的约束) - 跨应用场景下,目标dataAbility的visible属性若配置为false,调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限 - 组件启动规则详见:组件启动规则(FA模型)

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

参数:

参数名 类型 必填 说明
uri string 表示要打开的文件的路径。

返回值:

类型 说明
DataAbilityHelper 用来协助其他Ability访问DataAbility的工具类。

示例:

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

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

particleAbility.startBackgroundRunning

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

向系统申请长时任务,使用callback形式返回结果,建议使用新接口backgroundTaskManager.startBackgroundRunning

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数:

参数名 类型 必填 说明
id number 长时任务通知id号
request NotificationRequest 通知参数,用于显示通知栏的信息
callback AsyncCallback&lt;void&gt; callback形式返回启动长时任务的结果

示例

import notification from '@ohos.notificationManager';
import particleAbility from '@ohos.ability.particleAbility';
import wantAgent from '@ohos.app.ability.wantAgent';
import { BusinessError } from '@ohos.base';

function callback(error: BusinessError, data: void) {
    if (error && error.code !== 0) {
        console.error(`Operation failed error: ${JSON.stringify(error)}`);
    } else {
        console.info(`Operation succeeded, data: ${data}`);
    }
}

let wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
        {
            bundleName: 'com.example.myapplication',
            abilityName: 'EntryAbility'
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
    let id = 1;
    particleAbility.startBackgroundRunning(id, {
        content:
        {
            contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
            normal:
            {
                title: 'title',
                text: 'text'
            }
        },
        wantAgent: wantAgentObj
    }, callback);
});

particleAbility.startBackgroundRunning

startBackgroundRunning(id: number, request: NotificationRequest): Promise&lt;void&gt;

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

向系统申请长时任务,使用promise形式返回结果,建议使用新接口backgroundTaskManager.startBackgroundRunning

参数:

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

返回值:

类型 说明
Promise<void> 使用Promise形式返回启动长时任务的结果。

示例

import notification from '@ohos.notificationManager';
import particleAbility from '@ohos.ability.particleAbility';
import wantAgent from '@ohos.app.ability.wantAgent';
import { BusinessError } from '@ohos.base';

let wantAgentInfo: wantAgent.WantAgentInfo = {
    wants: [
        {
            bundleName: 'com.example.myapplication',
            abilityName: 'EntryAbility'
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
    let id = 1;
    particleAbility.startBackgroundRunning(id, {
        content:
        {
            contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
            normal:
            {
                title: 'title',
                text: 'text'
            }
        },
        wantAgent: wantAgentObj
    }).then(() => {
        console.info('Operation succeeded');
    }).catch((err: BusinessError) => {
        console.error(`Operation failed cause: ${JSON.stringify(err)}`);
    });
});

particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(callback: AsyncCallback&lt;void&gt;): void;

向系统申请取消长时任务,使用callback形式返回结果,建议使用新接口backgroundTaskManager.stopBackgroundRunning

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

参数:

参数名 类型 必填 说明
callback AsyncCallback&lt;void&gt; callback形式返回取消长时任务的结果

示例

import particleAbility from '@ohos.ability.particleAbility';
import { BusinessError } from '@ohos.base';

function callback(error: BusinessError, data: void) {
    if (error && error.code !== 0) {
        console.error(`Operation failed error: ${JSON.stringify(error)}`);
    } else {
        console.info(`Operation succeeded, data: ${data}`);
    }
}

particleAbility.cancelBackgroundRunning(callback);

particleAbility.cancelBackgroundRunning

cancelBackgroundRunning(): Promise&lt;void&gt;;

向系统申请取消长时任务,使用promise形式返回结果,建议使用新接口backgroundTaskManager.stopBackgroundRunning

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

返回值:

类型 说明
Promise<void> 使用Promise形式返回取消长时任务的结果。

示例

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

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

particleAbility.connectAbility

connectAbility(request: Want, options:ConnectOptions): number

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

使用规则: - 跨应用连接serviceAbility,对端应用需配置关联启动 - 调用方应用位于后台时,使用该接口连接serviceAbility需申请ohos.permission.START_ABILITIES_FROM_BACKGROUND权限(基于API 8或更早版本SDK开发的应用在启动ServiceAbility组件时不受此限制的约束) - 跨应用场景下,目标serviceAbility的visible属性若配置为false,调用方应用需申请ohos.permission.START_INVISIBLE_ABILITY权限 - 组件启动规则详见:组件启动规则(FA模型)

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

参数:

参数名 类型 必填 说明
request Want 表示被连接的ServiceAbility。
options ConnectOptions 连接回调方法。

示例

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

let connId = particleAbility.connectAbility(
    {
        bundleName: 'com.ix.ServiceAbility',
        abilityName: 'ServiceAbilityA',
    },
    {
        onConnect: (element, remote) => {
            console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`);
        },
        onDisconnect: (element) => {
            console.log(`ConnectAbility onDisconnect element.deviceId: ${element.deviceId}`);
        },
        onFailed: (code) => {
            console.error(`particleAbilityTest ConnectAbility onFailed errCode: ${code}`);
        },
    },
);

particleAbility.disconnectAbility(connId).then((data) => {
    console.log(`data: ${data}`);
}).catch((error: BusinessError) => {
    console.error(`particleAbilityTest result errCode: ${error.code}`);
});

particleAbility.disconnectAbility

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

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

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

参数:

参数名 类型 必填 说明
callback AsyncCallback&lt;void&gt; callback形式返回断开连接的结果

示例

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

let connId = particleAbility.connectAbility(
    {
        bundleName: 'com.ix.ServiceAbility',
        abilityName: 'ServiceAbilityA',
    },
    {
        onConnect: (element, remote) => {
            console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`);
        },
        onDisconnect: (element) => {
            console.log(`ConnectAbility onDisconnect element.deviceId: ${element.deviceId}`);
        },
        onFailed: (code) => {
            console.error(`particleAbilityTest ConnectAbility onFailed errCode: ${code}`);
        },
    },
);

particleAbility.disconnectAbility(connId, (err) => {
    console.error(`particleAbilityTest disconnectAbility err: ${JSON.stringify(err)}`);
});

particleAbility.disconnectAbility

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

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

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

返回值:

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

示例

import particleAbility from '@ohos.ability.particleAbility';
import rpc from '@ohos.rpc';
import { BusinessError } from '@ohos.base';

let connId = particleAbility.connectAbility(
    {
        bundleName: 'com.ix.ServiceAbility',
        abilityName: 'ServiceAbilityA',
    },
    {
        onConnect: (element, remote) => {
            console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`);
        },
        onDisconnect: (element) => {
            console.log(`ConnectAbility onDisconnect element.deviceId: ${element.deviceId}`);
        },
        onFailed: (code) => {
            console.error(`particleAbilityTest ConnectAbility onFailed errCode: ${code}`);
        },
    },
);

particleAbility.disconnectAbility(connId).then((data) => {
    console.log(`data: ${data}`);
}).catch((error: BusinessError) => {
    console.error(`particleAbilityTest result errCode : ${error.code}`);
});

ErrorCode

表示错误码。

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

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述(仅对系统应用开放)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0  赞