@ohos.ability.featureAbility (FeatureAbility)

The FeatureAbility module provides APIs that enable user interaction. You can use the APIs to start or terminate an ability, obtain a dataAbilityHelper object, obtain the window corresponding to the current ability, and connect to or disconnect from a ServiceAbility.

NOTE

The initial APIs of this module are supported since API version 6. 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 APIs of the FeatureAbility module can be called only by PageAbilities.

Modules to Import

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

featureAbility.startAbility

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

Starts an ability. 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).

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

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

featureAbility.startAbility(
  {
    want:
    {
      action: '',
      entities: [''],
      type: '',
      flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
      deviceId: '',
      bundleName: 'com.example.myapplication',
      /* In the FA model, abilityName consists of package and ability names. */
      abilityName: 'com.example.myapplication.secondAbility',
      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)}`);
    }
  }
);

featureAbility.startAbility

startAbility(parameter: StartAbilityParameter): Promise<number>

Starts an ability. 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

Model restriction: This API can be used only in the FA model.

Parameters

Return value

Example

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

featureAbility.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.myapplication',
      /* In the FA model, abilityName consists of package and ability names. */
      abilityName: 'com.example.myapplication.secondAbility',
      uri: ''
    },
  }
).then((data) => {
  console.info(`startAbility data: ${JSON.stringify(data)}`);
});

featureAbility.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).

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

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

let dataAbilityHelper = featureAbility.acquireDataAbilityHelper(
  'dataability:///com.example.DataAbility'
);

featureAbility.startAbilityForResult⁷⁺

startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback<AbilityResult>): void

Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: - Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller. - If an exception occurs, for example, the ability is killed, an exception message, in which resultCode is -1, is returned to the caller. - If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an exception message, in which resultCode is -1, is returned to others.

NOTE

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

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

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

featureAbility.startAbilityForResult(
  {
    want:
    {
      action: 'ohos.want.action.home',
      entities: ['entity.system.home'],
      type: 'MIMETYPE',
      flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
      deviceId: '',
      bundleName: 'com.example.myapplication',
      /* In the FA model, abilityName consists of package and ability names. */
      abilityName: 'com.example.myapplication.secondAbility',
      uri: ''
    },
  },
  (error, data) => {
    if (error && error.code !== 0) {
      console.error(`startAbilityForResult fail, error: ${JSON.stringify(error)}`);
    } else {
      console.log(`startAbilityForResult success, data: ${JSON.stringify(data)}`);
    }
  }
);

featureAbility.startAbilityForResult⁷⁺

startAbilityForResult(parameter: StartAbilityParameter): Promise<AbilityResult>

Starts an ability. This API uses a promise to return the result when the ability is terminated. The following situations may be possible for a started ability: - Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller. - If an exception occurs, for example, the ability is killed, an exception message, in which resultCode is -1, is returned to the caller. - If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an exception message, in which resultCode is -1, is returned to others.

NOTE

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

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

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

featureAbility.startAbilityForResult(
  {
    want:
    {
      action: 'ohos.want.action.home',
      entities: ['entity.system.home'],
      type: 'MIMETYPE',
      flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
      deviceId: '',
      bundleName: 'com.example.myapplication',
      /* In the FA model, abilityName consists of package and ability names. */
      abilityName: 'com.example.myapplication.secondAbility',
      uri: '',
      parameters:
      {
        mykey0: 1111,
        mykey1: [1, 2, 3],
        mykey2: '[1, 2, 3]',
        mykey3: 'xxxxxxxxxxxxxxxxxxxxxx',
        mykey4: [1, 15],
        mykey5: [false, true, false],
        mykey6: ['aaaaaa', 'bbbbb', 'ccccccccccc'],
        mykey7: true,
      },
    },
  },
).then((data) => {
  console.info(`startAbilityForResult data: ${JSON.stringify(data)}`);
});

featureAbility.terminateSelfWithResult⁷⁺

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void

Terminates this ability. This API uses an asynchronous callback to return the result. If the ability is started by calling startAbilityForResult, the result is returned to the caller when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

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

featureAbility.terminateSelfWithResult(
  {
    resultCode: 1,
    want:
    {
      action: 'ohos.want.action.home',
      entities: ['entity.system.home'],
      type: 'MIMETYPE',
      flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
      deviceId: '',
      bundleName: 'com.example.myapplication',
      /* In the FA model, abilityName consists of package and ability names. */
      abilityName: 'com.example.myapplication.secondAbility',
      uri: '',
      parameters: {
        mykey0: 2222,
        mykey1: [1, 2, 3],
        mykey2: '[1, 2, 3]',
        mykey3: 'ssssssssssssssssssssssssss',
        mykey4: [1, 15],
        mykey5: [false, true, false],
        mykey6: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
        mykey7: true,
      }
    },
  },
  (error) => {
    console.error(`error: ${JSON.stringify(error)}`);
  }
);

featureAbility.terminateSelfWithResult⁷⁺

terminateSelfWithResult(parameter: AbilityResult): Promise<void>

Terminates this ability. This API uses a promise to return the result. If the ability is started by calling startAbilityForResult, the result is returned to the caller when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

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

featureAbility.terminateSelfWithResult(
  {
    resultCode: 1,
    want:
    {
      action: 'ohos.want.action.home',
      entities: ['entity.system.home'],
      type: 'MIMETYPE',
      flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
      deviceId: '',
      bundleName: 'com.example.myapplication',
      /* In the FA model, abilityName consists of package and ability names. */
      abilityName: 'com.example.myapplication.secondAbility',
      uri:'',
      parameters: {
        mykey0: 2222,
        mykey1: [1, 2, 3],
        mykey2: '[1, 2, 3]',
        mykey3: 'ssssssssssssssssssssssssss',
        mykey4: [1, 15],
        mykey5: [false, true, false],
        mykey6: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
        mykey7: true,
      }
    },
  }
).then(() => {
  console.info('==========================>terminateSelfWithResult=======================>');
});

featureAbility.hasWindowFocus⁷⁺

hasWindowFocus(callback: AsyncCallback<boolean>): void

Checks whether the main window of this ability has the focus. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

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

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

featureAbility.hasWindowFocus⁷⁺

hasWindowFocus(): Promise<boolean>

Checks whether the main window of this ability has the focus. This API uses a promise to return the result.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

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

featureAbility.hasWindowFocus().then((data) => {
  console.info(`hasWindowFocus data: ${JSON.stringify(data)}`);
});

featureAbility.getWant

getWant(callback: AsyncCallback<Want>): void

Obtains the Want corresponding to the ability to start. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

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

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

featureAbility.getWant

getWant(): Promise<Want>

Obtains the Want corresponding to the ability to start. This API uses a promise to return the result.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

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

featureAbility.getWant().then((data) => {
  console.info(`getWant data: ${JSON.stringify(data)}`);
});

featureAbility.getContext

getContext(): Context

Obtains the application context.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

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

let context = featureAbility.getContext();
context.getBundleName((error, data) => {
  if (error && error.code !== 0) {
    console.error(`getBundleName fail, error: ${JSON.stringify(error)}`);
  } else {
    console.log(`getBundleName success, data: ${JSON.stringify(data)}`);
  }
});

featureAbility.terminateSelf⁷⁺

terminateSelf(callback: AsyncCallback<void>): void

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

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

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

featureAbility.terminateSelf(
  (error) => {
    console.error(`error: ${JSON.stringify(error)}`);
  }
)

featureAbility.terminateSelf⁷⁺

terminateSelf(): Promise<void>

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

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

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

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

featureAbility.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).

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

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

let connectId = featureAbility.connectAbility(
  {
    deviceId: '',
    bundleName: 'com.ix.ServiceAbility',
    abilityName: 'com.ix.ServiceAbility.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(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`);
    },
  },
);

featureAbility.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.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

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

let connectId = featureAbility.connectAbility(
  {
    bundleName: 'com.ix.ServiceAbility',
    abilityName: 'com.ix.ServiceAbility.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(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`);
    },
  },
);

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

featureAbility.disconnectAbility⁷⁺

disconnectAbility(connection: number): Promise<void>

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

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

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

let connectId = featureAbility.connectAbility(
  {
    bundleName: 'com.ix.ServiceAbility',
    abilityName: 'com.ix.ServiceAbility.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(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`);
    },
  },
);

featureAbility.disconnectAbility(connectId).then(() => {
  console.log('disconnectAbility success');
}).catch((error: BusinessError)=>{
  console.error(`featureAbilityTest result errCode : ${error.code}`);
});

featureAbility.getWindow⁷⁺

getWindow(callback: AsyncCallback<window.Window>): void

Obtains the window corresponding to this ability. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

import { featureAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

featureAbility.getWindow((error: BusinessError, data: window.Window) => {
  if (error && error.code !== 0) {
    console.error(`getWindow fail, error: ${JSON.stringify(error)}`);
  } else {
    console.log(`getWindow success, data: ${typeof(data)}`);
  }
});

featureAbility.getWindow⁷⁺

getWindow(): Promise<window.Window>

Obtains the window corresponding to this ability. This API uses a promise to return the result.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

import { featureAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

featureAbility.getWindow().then((data: window.Window) => {
  console.log(`getWindow success, data: ${typeof(data)}`);
}).catch((error: BusinessError)=>{
  console.error(`getWindow fail, error: ${JSON.stringify(error)}`);
});

AbilityWindowConfiguration⁷⁺

Defines the window configuration corresponding to this ability. The configuration is obtained through featureAbility.AbilityWindowConfiguration.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Example

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

featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED

AbilityStartSetting⁷⁺

Defines the window property corresponding to this ability. The abilityStartSetting property is an object defined in the format of [key: string]: any, where key is an enumerated value of AbilityStartSetting and value is an enumerated value of AbilityWindowConfiguration.

The value is obtained through featureAbility.AbilityStartSetting.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Example

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

featureAbility.AbilityStartSetting.BOUNDS_KEY

ErrorCode⁷⁺

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

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

DataAbilityOperationType⁷⁺

Enumerates the operation types of a DataAbility. The DataAbility can use an enumerated value to specify the operation type when operating data in batches.

Model restriction: This API can be used only in the FA model.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Context⁹⁺

type Context = _Context

Defines the Context module.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Model restriction: This API can be used only in the FA model.

AppVersionInfo⁹⁺

type AppVersionInfo = _AppVersionInfo

Defines an AppVersionInfo object.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Model restriction: This API can be used only in the FA model.

ProcessInfo⁹⁺

type ProcessInfo = _ProcessInfo

Defines a ProcessInfo object.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Model restriction: This API can be used only in the FA model.

你可能感兴趣的鸿蒙文章

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