openharmony 鸿蒙 js-apis-ability-particleAbility

2025-06-12 浏览 (1)

@ohos.ability.particleAbility (ParticleAbility)

The particleAbility module provides APIs for operating a DataAbility and ServiceAbility. You can use the APIs to start and terminate a ParticleAbility, obtain a dataAbilityHelper object, and connect to or disconnect from a ServiceAbility.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module can be used only in the FA model.

Constraints

The ParticleAbility module is used to perform operations on abilities of the Data and Service types.

Modules to Import

import { particleAbility } from '@kit.AbilityKit';

particleAbility.startAbility

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

Starts a ParticleAbility. This API uses an asynchronous callback to return the result.

NOTE

For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model).

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

NameTypeMandatoryDescription
parameterStartAbilityParameterYesAbility to start.
callbackAsyncCallback<void>YesCallback used to return the result. If the ParticleAbility is started, err is undefined; otherwise, err is an error object.

Example

import { particleAbility, wantConstant } from '@kit.AbilityKit';

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>

Starts a ParticleAbility. This API uses a promise to return the result.

NOTE

For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model).

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

NameTypeMandatoryDescription
parameterStartAbilityParameterYesAbility to start.

Return value

TypeDescription
Promise<void>Promise used to return the result. Promise that returns no value.

Example

import { particleAbility, wantConstant } from '@kit.AbilityKit';

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

Terminates this ParticleAbility. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<void>YesCallback used to return the result. If the ParticleAbility is terminated, err is undefined; otherwise, err is an error object.

Example

import { particleAbility } from '@kit.AbilityKit';

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

particleAbility.terminateSelf

terminateSelf(): Promise<void>

Terminates this ParticleAbility. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

TypeDescription
Promise<void>Promise used to return the result. Promise that returns no value.

Example

import { particleAbility } from '@kit.AbilityKit';

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

particleAbility.acquireDataAbilityHelper

acquireDataAbilityHelper(uri: string): DataAbilityHelper

Obtains a dataAbilityHelper object.

NOTE

For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model). To access a DataAbility of another application, the target application must be configured with associated startup (AssociateWakeUp set to true).

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

NameTypeMandatoryDescription
uristringYesURI of the file to open.

Return value

TypeDescription
DataAbilityHelperA utility class used to help other abilities access a DataAbility.

Example

import { particleAbility } from '@kit.AbilityKit';

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

particleAbility.startBackgroundRunning(deprecated)

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

Requests a continuous task from the system. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.KEEP_BACKGROUND_RUNNING

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

NOTE

This API is deprecated since API version 9. You are advised to use backgroundTaskManager.startBackgroundRunning instead.

Parameters

NameTypeMandatoryDescription
idnumberYesNotification ID of the continuous task.
requestNotificationRequestYesNotification parameter, which is used to display information in the notification bar.
callbackAsyncCallback<void>YesCallback used to return the result. If the continuous task is requested, err is undefined. Otherwise, err is an error object.

Example

import { particleAbility, wantAgent } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import notification from '@ohos.notification';

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>

Requests a continuous task from the system. This API uses a promise to return the result.

Required permissions: ohos.permission.KEEP_BACKGROUND_RUNNING

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

NOTE

This API is deprecated since API version 9. You are advised to use backgroundTaskManager.startBackgroundRunning instead.

Parameters

NameTypeMandatoryDescription
idnumberYesNotification ID of the continuous task.
requestNotificationRequestYesNotification parameter, which is used to display information in the notification bar.

Return value

TypeDescription
Promise<void>Promise used to return the result. Promise that returns no value.

Example

import { particleAbility, wantAgent } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import notification from '@ohos.notification';

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

Requests to cancel a continuous task from the system. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

NOTE

This API is deprecated since API version 9. You are advised to use backgroundTaskManager.stopBackgroundRunning instead.

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<void>YesCallback used to return the result. If the continuous task is canceled, err is undefined. Otherwise, err is an error object.

Example

import { particleAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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>

Requests to cancel a continuous task from the system. This API uses a promise to return the result.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

NOTE

This API is deprecated since API version 9. You are advised to use backgroundTaskManager.stopBackgroundRunning instead.

Return value

TypeDescription
Promise<void>Promise used to return the result. Promise that returns no value.

Example

import { particleAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

Connects this ability to a ServiceAbility.

NOTE

For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model). To connect to a ServiceAbility of another application, the target application must be configured with associated startup (AssociateWakeUp set to true).

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

NameTypeMandatoryDescription
requestWantYesServiceAbility to connect.
optionsConnectOptionsYesConnection options.

Return value

TypeDescription
numberID of the connected ServiceAbility. The ID starts from 0 and is incremented by 1 each time a connection is set up.

Example

import { particleAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

Disconnects this ability from a specific ServiceAbility. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

NameTypeMandatoryDescription
connectionnumberYesID of the ServiceAbility to disconnect.
callbackAsyncCallback<void>YesCallback used to return the result. If the disconnection is successful, err is undefined. Otherwise, err is an error object.

Example

import { particleAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';

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>

Disconnects this ability from a specific ServiceAbility. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

NameTypeMandatoryDescription
connectionnumberYesID of the ServiceAbility to disconnect.

Return value

TypeDescription
Promise<void>Promise used to return the result. Promise that returns no value.

Example

import { particleAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

ErrorCode

Enumerates the error codes that may be returned when an ability is started.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

NameValueDescription
INVALID_PARAMETER-1Invalid parameter.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit

harmony 鸿蒙AbilityAccessControl

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_access_control.h

harmony 鸿蒙ability_base_common.h

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/YYmzFC