HarmonyOS实战开发:@ohos.ability.particleAbility (ParticleAbility模块)

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

说明:

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

使用限制

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用ServiceExtensionContext.startAbility

参数:

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

错误码:

错误码ID错误信息
1Get ability error.
202Parameter is invalid.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

错误码详细介绍请参考errcode-ability

示例:

import particleAbility from '@ohos.ability.particleAbility';
import wantConstant from '@ohos.app.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: 'com.example.Data.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

说明:本接口仅可在FA模型下使用,Stage模型下需使用ServiceExtensionContext.startAbility

参数:

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

返回值:

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码:

错误码ID错误信息
1Get ability error.
202Parameter is invalid.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

错误码详细介绍请参考errcode-ability

示例:

import particleAbility from '@ohos.ability.particleAbility';
import wantConstant from '@ohos.app.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: 'com.example.Data.EntryAbility',
            uri: ''
        },
    },
).then(() => {
    console.info('particleAbility startAbility');
});

particleAbility.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

销毁当前particleAbility(callback形式)。

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用ServiceExtensionContext.terminateSelf

参数:

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

错误码:

错误码ID错误信息
16000001The specified ability does not exist.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

错误码详细介绍请参考errcode-ability

示例:

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

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

particleAbility.terminateSelf

terminateSelf(): Promise<void>

销毁当前particleAbility(Promise形式)。

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用ServiceExtensionContext.terminateSelf

返回值:

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码:

错误码ID错误信息
16000001The specified ability does not exist.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

错误码详细介绍请参考errcode-ability

示例:

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

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

particleAbility.acquireDataAbilityHelper

acquireDataAbilityHelper(uri: string): DataAbilityHelper

获取dataAbilityHelper对象。

使用规则:

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

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用dataShare.createDataShareHelper

参数:

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

返回值:

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

示例:

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

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

particleAbility.startBackgroundRunning(deprecated)

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

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

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用backgroundTaskManager.startBackgroundRunning

参数:

参数名类型必填说明
idnumber长时任务通知id号
requestNotificationRequest通知参数,用于显示通知栏的信息
callbackAsyncCallback<void>callback形式返回启动长时任务的结果

错误码:

错误码ID错误信息
-102Failed to acquire ability object.
-104Parameter is invalid.
201Permission denied.
202System API verification failed. Only system application can apply.
9800407The bgMode cannot be null and its type must be BackgroundMode object.
980000401Manager is not ready.
980000501Continuous task is already exist.
980000503Continuous Task verification failed. TASK_KEEPING background mode only supported in particular device.
980000504Continuous Task verification failed. The bgMode is invalid.
980000601Notification verification failed. The title or text of the notification cannot be empty.
980000603Continuous task param is null.

示例

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(deprecated)

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

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

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用backgroundTaskManager.startBackgroundRunning

参数:

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

返回值:

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码:

错误码ID错误信息
-102Failed to acquire ability object.
-104Parameter is invalid.
201Permission denied.
202System API verification failed. Only system application can apply.
9800407The bgMode cannot be null and its type must be BackgroundMode object.
980000401Manager is not ready.
980000501Continuous task is already exist.
980000503Continuous Task verification failed. TASK_KEEPING background mode only supported in particular device.
980000504Continuous Task verification failed. The bgMode is invalid.
980000601Notification verification failed. The title or text of the notification cannot be empty.
980000603Continuous task param is null.

示例

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(deprecated)

cancelBackgroundRunning(callback: AsyncCallback<void>): void

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

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用backgroundTaskManager.stopBackgroundRunning

参数:

参数名类型必填说明
callbackAsyncCallback<void>callback形式返回取消长时任务的结果

错误码:

错误码ID错误信息
401The input param is invalid.
980000401Manager is not ready.
980000502Continuous Task verification failed. The application has applied for a continuous task.
980000602Notification verification failed. Failed to send or cancel the notification.
980000603Continuous task param is null.

示例

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(deprecated)

cancelBackgroundRunning(): Promise<void>

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

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用backgroundTaskManager.stopBackgroundRunning

返回值:

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码:

错误码ID错误信息
401The input param is invalid.
980000401Manager is not ready.
980000502Continuous Task verification failed. The application has applied for a continuous task.
980000602Notification verification failed. Failed to send or cancel the notification.
980000603Continuous task param is null.

示例

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

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需申请权限(基于API 8或更早版本SDK开发的应用在启动ServiceAbility组件时不受此限制的约束)ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下,目标serviceAbility的visible属性若配置为false,调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见:组件启动规则(FA模型)

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用ServiceExtensionContext.connectServiceExtensionAbility

参数:

参数名类型必填说明
requestWant表示被连接的ServiceAbility。
optionsConnectOptions连接回调方法。

返回值:

类型说明
number连接的ServiceAbility的ID(ID从0开始自增,每连接成功一次ID加1)。

错误码:

错误码ID错误信息
-1Invalid parameter.
-2Ability not found.
-3Permission denied.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000011The context does not exist.
16000050Internal error.

错误码详细介绍请参考errcode-ability

示例

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

particleAbility.disconnectAbility

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

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

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用ServiceExtensionContext.disconnectServiceExtensionAbility

参数:

参数名类型必填说明
connectionnumber表示断开连接的ServiceAbility的ID。
callbackAsyncCallback<void>callback形式返回断开连接的结果

错误码:

错误码ID错误信息
-102Failed to acquire ability object.
-105Type of ability is invalid.
16000011The context does not exist.
16000050Internal error.

错误码详细介绍请参考errcode-ability

示例

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

说明:本接口仅可在FA模型下使用,Stage模型下需使用ServiceExtensionContext.disconnectServiceExtensionAbility

返回值:

类型说明
connectionnumber
Promise<void>Promise对象。无返回结果的Promise对象。

错误码:

错误码ID错误信息
-102Failed to acquire ability object.
-105Type of ability is invalid.
16000011The context does not exist.
16000050Internal error.

错误码详细介绍请参考errcode-ability

示例

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(() => {
    console.log('disconnectAbility success');
}).catch((error: BusinessError) => {
    console.error(`particleAbilityTest result errCode : ${error.code}`);
});

最后

有很多小伙伴不知道学习哪些鸿蒙开发技术?不知道需要重点掌握哪些鸿蒙应用开发知识点?而且学习时频繁踩坑,最终浪费大量时间。所以有一份实用的鸿蒙(HarmonyOS NEXT)资料用来跟着学习是非常有必要的。 

这份鸿蒙(HarmonyOS NEXT)资料包含了鸿蒙开发必掌握的核心知识要点,内容包含了ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、Harmony南向开发、鸿蒙项目实战等等)鸿蒙(HarmonyOS NEXT)技术知识点。

希望这一份鸿蒙学习资料能够给大家带来帮助,有需要的小伙伴自行领取,限时开源,先到先得~无套路领取!!

获取这份完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS学习资料

鸿蒙(HarmonyOS NEXT)最新学习路线

  •  HarmonOS基础技能

  • HarmonOS就业必备技能 
  •  HarmonOS多媒体技术

  • 鸿蒙NaPi组件进阶

  • HarmonOS高级技能

  • 初识HarmonOS内核 
  • 实战就业级设备开发

有了路线图,怎么能没有学习资料呢,小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙(OpenHarmony )学习手册(共计1236页)鸿蒙(OpenHarmony )开发入门教学视频,内容包含:ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。

获取以上完整版高清学习路线,请点击→纯血版全套鸿蒙HarmonyOS学习资料

《鸿蒙 (OpenHarmony)开发入门教学视频》

《鸿蒙生态应用开发V2.0白皮书》

图片

《鸿蒙 (OpenHarmony)开发基础到实战手册》

OpenHarmony北向、南向开发环境搭建

图片

 《鸿蒙开发基础》

  • ArkTS语言
  • 安装DevEco Studio
  • 运用你的第一个ArkTS应用
  • ArkUI声明式UI开发
  • .……

图片

 《鸿蒙开发进阶》

  • Stage模型入门
  • 网络管理
  • 数据管理
  • 电话服务
  • 分布式应用开发
  • 通知与窗口管理
  • 多媒体技术
  • 安全技能
  • 任务管理
  • WebGL
  • 国际化开发
  • 应用测试
  • DFX面向未来设计
  • 鸿蒙系统移植和裁剪定制
  • ……

图片

《鸿蒙进阶实战》

  • ArkTS实践
  • UIAbility应用
  • 网络案例
  • ……

图片

 获取以上完整鸿蒙HarmonyOS学习资料,请点击→纯血版全套鸿蒙HarmonyOS学习资料

总结

总的来说,华为鸿蒙不再兼容安卓,对中年程序员来说是一个挑战,也是一个机会。只有积极应对变化,不断学习和提升自己,他们才能在这个变革的时代中立于不败之地。

  • 16
    点赞
  • 24
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值