@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 '@ohos.ability.featureAbility';

featureAbility.startAbility

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

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

Observe the following when using this API:

• If an application running in the background needs to call this API to start an ability, it must have the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission.
• If visible of the target ability is false, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
• 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

Example

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
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: ''
        },
    },
    (err, data) => {
        console.info('startAbility err: ' + JSON.stringify(err) + 'data: ' + JSON.stringify(data));
    }
);

featureAbility.startAbility

startAbility(parameter: StartAbilityParameter): Promise<number>

Starts an ability. This API uses a promise to return the result.

Observe the following when using this API:

• If an application running in the background needs to call this API to start an ability, it must have the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission.
• If visible of the target ability is false, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
• 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

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
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 sington 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.

Observe the following when using this API:

• If an application running in the background needs to call this API to start an ability, it must have the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission.
• If visible of the target ability is false, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
• 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

Example

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
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:''
        },
    },
    (err, data) => {
        console.info('startAbilityForResult err: ' + JSON.stringify(err) + '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 to an ability after it is started:

• 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 sington 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.

Observe the following when using this API:

• If an application running in the background needs to call this API to start an ability, it must have the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission.
• If visible of the target ability is false, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
• 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

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
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. If the ability is started by calling startAbilityForResult, the result is returned to the caller in the form of a callback when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
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,
            }
        },
    },
    (err) => {
        console.error('err: ' + JSON.stringify(err));
    }
);

featureAbility.terminateSelfWithResult⁷⁺

terminateSelfWithResult(parameter: AbilityResult): Promise<void>

Terminates this ability. If the ability is started by calling startAbilityForResult, the result is returned to the caller in the form of a promise when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
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((data) => {
    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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus((err, data) => {
    console.info('hasWindowFocus err: ' + JSON.stringify(err) + '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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant((err, data) => {
    console.info('getWant err: ' + JSON.stringify(err) + '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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant().then((data) => {
    console.info('getWant data: ' + JSON.stringify(data));
});

featureAbility.getContext

getContext(): Context

Obtains the application context.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
context.getBundleName((err, data) => {
    console.info('getBundleName err: ' + JSON.stringify(err) + 'data: ' + JSON.stringify(data));
});

featureAbility.terminateSelf⁷⁺

terminateSelf(callback: AsyncCallback<void>): void

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

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf(
    (err) => {
        console.error('err: ' + JSON.stringify(err));
    }
)

featureAbility.terminateSelf⁷⁺

terminateSelf(): Promise<void>

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

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf().then((data) => {
    console.info('==========================>terminateSelf=======================>');
});

featureAbility.connectAbility⁷⁺

connectAbility(request: Want, options:ConnectOptions): number

Connects this ability to a ServiceAbility.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Return value

Example

import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
let connectId = featureAbility.connectAbility(
    {
        deviceId: '',
        bundleName: 'com.ix.ServiceAbility',
        abilityName: 'com.ix.ServiceAbility.ServiceAbilityA',
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId);
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code);
}
let connectId = featureAbility.connectAbility(
    {
        bundleName: 'com.ix.ServiceAbility',
        abilityName: 'com.ix.ServiceAbility.ServiceAbilityA',
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

featureAbility.disconnectAbility(connectId, (err) => {
    console.error('featureAbilityTest disconnectAbility err====>'
    + ('json err=') + JSON.stringify(err));
});

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

Return value

Example

import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId);
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code);
}
let connectId = featureAbility.connectAbility(
    {
        bundleName: 'com.ix.ServiceAbility',
        abilityName: 'com.ix.ServiceAbility.ServiceAbilityA',
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

featureAbility.disconnectAbility(connectId).then((data) => {
    console.log('data : '  + data);
}).catch((error)=>{
    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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Parameters

Example

featureAbility.getWindow((err, data) => {
    console.info('getWindow err: ' + JSON.stringify(err) + '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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

Return value

Example

featureAbility.getWindow().then((data) => {
    console.info('getWindow data: ' + typeof(data));
});

AbilityWindowConfiguration

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

Example

featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

AbilityStartSetting

Defines the window attribute corresponding to this ability. The abilityStartSetting attribute 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.

Example

featureAbility.AbilityStartSetting.BOUNDS_KEY

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

ErrorCode

Enumerates the error codes.

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.

System capability: SystemCapability.Ability.AbilityRuntime.FAModel

flags

Enumerates the flags that specify how the Want will be handled.

System capability: SystemCapability.Ability.AbilityBase