@ohos.app.ability.abilityManager (AbilityManager)

The AbilityManager module provides APIs for obtaining, adding, and updating ability running information and state information.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. The APIs of this module are system APIs and cannot be called by third-party applications.

Modules to Import

import abilityManager from '@ohos.app.ability.abilityManager';

AbilityState

Enumerates the ability states. This enum can be used together with AbilityRunningInfo to return the ability state.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

updateConfiguration

updateConfiguration(config: Configuration, callback: AsyncCallback<void>): void

Updates the configuration. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

For details about the error codes, see Ability Error Codes.

Example

import abilityManager from '@ohos.app.ability.abilityManager';
import { Configuration } from '@ohos.app.ability.Configuration';
import ConfigurationConstant from '@ohos.app.ability.ConfigurationConstant';
import { BusinessError } from '@ohos.base';

const config: Configuration = {
  language: 'Zh-Hans',                 // Simplified Chinese.
  colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT,         // Light theme.
  direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL,       // Vertical direction.
  screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI,  // The screen pixel density is 'sdpi'.
  displayId: 1,                        // The application is displayed on the display with ID 1.
  hasPointerDevice: true,              // A pointer device is connected.
};

try {
    abilityManager.updateConfiguration(config, (err: BusinessError) => {
        if (err) {
            console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`);
        } else {
            console.log('updateConfiguration success.');
        }
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

updateConfiguration

updateConfiguration(config: Configuration): Promise<void>

Updates the configuration. This API uses a promise to return the result.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

For details about the error codes, see Ability Error Codes.

Example

import abilityManager from '@ohos.app.ability.abilityManager';
import { Configuration } from '@ohos.app.ability.Configuration';
import ConfigurationConstant from '@ohos.app.ability.ConfigurationConstant';
import { BusinessError } from '@ohos.base';

const config: Configuration = {
  language: 'Zh-Hans',                 // Simplified Chinese.
  colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT,         // Light theme.
  direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL,       // Vertical direction.
  screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI,  // The screen pixel density is 'sdpi'.
  displayId: 1,                        // The application is displayed on the display with ID 1.
  hasPointerDevice: true,              // A pointer device is connected.
};

try {
    abilityManager.updateConfiguration(config).then(() => {
        console.log('updateConfiguration success.');
    }).catch((err: BusinessError) => {
        console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`);
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

getAbilityRunningInfos

getAbilityRunningInfos(callback: AsyncCallback<Array<AbilityRunningInfo>>): void

Obtains the UIAbility running information. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

try {
    abilityManager.getAbilityRunningInfos((err: BusinessError, data: Array<AbilityRunningInfo>) => {
        if (err) {
            console.error(`getAbilityRunningInfos fail, error: ${JSON.stringify(err)}`);
        } else {
            console.log(`getAbilityRunningInfos success, data: ${JSON.stringify(data)}`);
        }
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

getAbilityRunningInfos

getAbilityRunningInfos(): Promise<Array<AbilityRunningInfo>>

Obtains the UIAbility running information. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

try {
    abilityManager.getAbilityRunningInfos().then((data: Array<AbilityRunningInfo>) => {
        console.log(`getAbilityRunningInfos success, data: ${JSON.stringify(data)}`);
    }).catch((err: BusinessError) => {
        console.error(`getAbilityRunningInfos fail, err: ${JSON.stringify(err)}`);
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

getExtensionRunningInfos

getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback<Array<ExtensionRunningInfo>>): void

Obtains the ExtensionAbility running information. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

let upperLimit = 10;

try {
    abilityManager.getExtensionRunningInfos(upperLimit, (err: BusinessError, data: Array<abilityManager.ExtensionRunningInfo>) => {
        if (err) {
            console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`);
        } else {
            console.log(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`);
        }
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

getExtensionRunningInfos

getExtensionRunningInfos(upperLimit: number): Promise<Array<ExtensionRunningInfo>>

Obtains the ExtensionAbility running information. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

let upperLimit = 10;

try {
    abilityManager.getExtensionRunningInfos(upperLimit).then((data: Array<abilityManager.ExtensionRunningInfo>) => {
        console.log(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`);
    }).catch((err: BusinessError) => {
        console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`);
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

getTopAbility

getTopAbility(callback: AsyncCallback<ElementName>): void

Obtains the top ability, which is the ability that has the window focus. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

abilityManager.getTopAbility((err: BusinessError, data) => { 
    if (err) {
        console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`);
    } else {
        console.log(`getTopAbility success, data: ${JSON.stringify(data)}`);
    }
});

getTopAbility

getTopAbility(): Promise<ElementName>

Obtains the top ability, which is the ability that has the window focus. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

abilityManager.getTopAbility().then((data) => {
    console.log(`getTopAbility success, data: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
    console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`);
});

acquireShareData¹⁰⁺

acquireShareData(missionId: number, callback: AsyncCallback<{[key: string]: Object}>): void

Called by a system dialog box to obtain shared data, which is set by the target UIAbility through onShare(). This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

try {
    abilityManager.acquireShareData(1, (err: BusinessError, wantParam: Record<string, Object>) => { 
        if (err) {
            console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`);
        } else {
            console.log(`acquireShareData success, data: ${JSON.stringify(wantParam)}`);
        }
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

acquireShareData¹⁰⁺

acquireShareData(missionId: number): Promise<{[key: string]: Object}>

Called by a system dialog box to obtain shared data, which is set by the target UIAbility through onShare(). This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

For details about the error codes, see Ability Error Codes.

Example

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

try {
    abilityManager.acquireShareData(1).then((wantParam: Record<string, Object>) => {
    console.log(`acquireShareData success, data: ${JSON.stringify(wantParam)}`);
    }).catch((err: BusinessError) => {
    console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`);
    });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

notifySaveAsResult¹⁰⁺

notifySaveAsResult(parameter: AbilityResult, requestCode: number, callback: AsyncCallback<void>): void

Used by the Data Loss Prevention (DLP) management application to notify a sandbox application of the data saving result. This API uses an asynchronous callback to return the result.

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

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

For details about the error codes, see Ability Error Codes.

Example

import abilityManager from '@ohos.app.ability.abilityManager';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
let want: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let resultCode = 100;
// AbilityResult information returned to the initiator of the save-as behavior.
let abilityResult: common.AbilityResult = {
    want,
    resultCode
};
let requestCode = 1;
try {
  abilityManager.notifySaveAsResult(abilityResult, requestCode, (err: BusinessError) => {
    if (err && err.code != 0) {
      console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`);
    } else {
      console.log(`notifySaveAsResult success`);
    }
  });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}

notifySaveAsResult¹⁰⁺

notifySaveAsResult(parameter: AbilityResult, requestCode: number): Promise<void>

Used by the Data Loss Prevention (DLP) management application to notify a sandbox application of the data saving result. This API uses a promise to return the result.

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

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

For details about the error codes, see Ability Error Codes.

Example

import abilityManager from '@ohos.app.ability.abilityManager';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
let want: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let resultCode = 100;
// AbilityResult information returned to the initiator of the save-as behavior.
let abilityResult: common.AbilityResult = {
    want,
    resultCode
};
let requestCode = 1;
try {
  abilityManager.notifySaveAsResult(abilityResult, requestCode).catch((err: BusinessError) => {
    console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`);
  }).then(() => {
    console.log(`notifySaveAsResult success`);
  });
} catch (paramError) {
    let code: string = (paramError as BusinessError).code;
    let message: string = (paramError as BusinessError).message;
    console.error(`error.code: ${code}, error.message: ${message}`);
}