harmony 鸿蒙@ohos.ability.particleAbility (ParticleAbility模块)
@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<void>): void;
向系统申请长时任务,使用callback形式返回结果,建议使用新接口backgroundTaskManager.startBackgroundRunning。
需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING
系统能力:SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
id | number | 是 | 长时任务通知id号 |
request | NotificationRequest | 是 | 通知参数,用于显示通知栏的信息 |
callback | AsyncCallback<void> | 是 | 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<void>
需要权限: 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<void>): void;
向系统申请取消长时任务,使用callback形式返回结果,建议使用新接口backgroundTaskManager.stopBackgroundRunning。
系统能力:SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
callback | AsyncCallback<void> | 是 | 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<void>;
向系统申请取消长时任务,使用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<void> | 是 | 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 鸿蒙BundleStatusCallback
harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)
harmony 鸿蒙@ohos.distributedBundle (分布式包管理)
harmony 鸿蒙@ohos.bundle (Bundle模块)
harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)
- 所属分类: 后端技术
- 本文标签:
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦