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

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

@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  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://www.seaxiang.com/blog/9c94b1fa216549648928783f0cc78a22
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录