AbilityDelegator

The AbilityDelegator module provides APIs for managing AbilityMonitor instances that are used to monitor the lifecycle state changes of a specified ability. You can use the APIs to add and remove AbilityMonitor instances, wait for an ability to reach the OnCreate lifecycle state, set the waiting time, obtain the lifecycle state of an ability, obtain the top ability of the current application, and start an ability.

NOTE

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

Modules to Import

import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry';

Usage

An AbilityDelegator object is obtained by calling getAbilityDelegator in AbilityDelegatorRegistry.

import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry';

AbilityDelegator

addAbilityMonitor⁹⁺

addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<void>): void;

Adds an AbilityMonitor instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    abilityName: 'abilityname',
    onAbilityCreate: onAbilityCreateCallback
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityMonitor(monitor, (err : any) => {
    console.info('addAbilityMonitor callback');
});

addAbilityMonitor⁹⁺

addAbilityMonitor(monitor: AbilityMonitor): Promise<void>;

Adds an AbilityMonitor instance. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    abilityName: 'abilityname',
    onAbilityCreate: onAbilityCreateCallback
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityMonitor(monitor).then(() => {
    console.info('addAbilityMonitor promise');
});

removeAbilityMonitor⁹⁺

removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<void>): void;

Removes an AbilityMonitor instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    abilityName: 'abilityname',
    onAbilityCreate: onAbilityCreateCallback
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.removeAbilityMonitor(monitor, (err : any) => {
    console.info('removeAbilityMonitor callback');
});

removeAbilityMonitor⁹⁺

removeAbilityMonitor(monitor: AbilityMonitor): Promise<void>;

ɾ���Ѿ����ӵ�AbilityMonitorʵ����promise��ʽ��

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

• Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    abilityName: 'abilityname',
    onAbilityCreate: onAbilityCreateCallback
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.removeAbilityMonitor(monitor).then(() => {
    console.info('removeAbilityMonitor promise');
});

waitAbilityMonitor⁹⁺

waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<UIAbility>): void;

Waits for the Ability instance that matches the AbilityMonitor instance to reach the OnCreate lifecycle state and returns the Ability instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    abilityName: 'abilityname',
    onAbilityCreate: onAbilityCreateCallback
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor, (err : any, data : any) => {
    console.info('waitAbilityMonitor callback');
});

waitAbilityMonitor⁹⁺

waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback<UIAbility>): void;

Waits a period of time for the Ability instance that matches the AbilityMonitor instance to reach the OnCreate lifecycle state and returns the Ability instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let timeout = 100;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    abilityName: 'abilityname',
    onAbilityCreate: onAbilityCreateCallback
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor, timeout, (err : any, data : any) => {
    console.info('waitAbilityMonitor callback');
});

waitAbilityMonitor⁹⁺

waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise<UIAbility>;

Waits a period of time for the Ability instance that matches the AbilityMonitor instance to reach the OnCreate lifecycle state and returns the Ability instance. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    abilityName: 'abilityname',
    onAbilityCreate: onAbilityCreateCallback
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor).then((data : any) => {
    console.info('waitAbilityMonitor promise');
});

getAppContext⁹⁺

getAppContext(): Context;

Obtains the application context.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
let context = abilityDelegator.getAppContext();

getAbilityState⁹⁺

getAbilityState(ability: UIAbility): number;

Obtains the lifecycle state of an ability.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let ability;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
    console.info('getCurrentTopAbility callback');
    ability = data;
    let state = abilityDelegator.getAbilityState(ability);
    console.info('getAbilityState' + state);
});

getCurrentTopAbility⁹⁺

getCurrentTopAbility(callback: AsyncCallback<UIAbility>): void;

Obtains the top ability of this application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let ability;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
    console.info('getCurrentTopAbility callback');
    ability = data;
});

getCurrentTopAbility⁹⁺

getCurrentTopAbility(): Promise<UIAbility>;

Obtains the top ability of this application. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let ability;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility().then((data : any) => {
    console.info('getCurrentTopAbility promise');
    ability = data;
});

startAbility⁹⁺

startAbility(want: Want, callback: AsyncCallback<void>): void;

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

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let want = {
    bundleName: 'bundleName',
    abilityName: 'abilityName'
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.startAbility(want, (err : any, data : any) => {
    console.info('startAbility callback');
});

startAbility⁹⁺

startAbility(want: Want): Promise<void>;

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

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let want = {
    bundleName: 'bundleName',
    abilityName: 'abilityName'
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.startAbility(want).then((data: any) => {
    console.info('startAbility promise');
});

doAbilityForeground⁹⁺

doAbilityForeground(ability: UIAbility, callback: AsyncCallback<void>): void;

Schedules the lifecycle state of an ability to Foreground. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let ability;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
    console.info('getCurrentTopAbility callback');
    ability = data;
    abilityDelegator.doAbilityForeground(ability, (err : any) => {
        console.info("doAbilityForeground callback");
    });
});

doAbilityForeground⁹⁺

doAbilityForeground(ability: UIAbility): Promise<void>;

Schedules the lifecycle state of an ability to Foreground. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let ability;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
    console.info('getCurrentTopAbility callback');
    ability = data;
    abilityDelegator.doAbilityForeground(ability).then(() => {
        console.info("doAbilityForeground promise");
    });
});

doAbilityBackground⁹⁺

doAbilityBackground(ability: UIAbility, callback: AsyncCallback<void>): void;

Schedules the lifecycle state of an ability to Background. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let ability;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
    console.info('getCurrentTopAbility callback');
    ability = data;
    abilityDelegator.doAbilityBackground(ability, (err : any) => {
        console.info("doAbilityBackground callback");
    });
});

doAbilityBackground⁹⁺

doAbilityBackground(ability: UIAbility): Promise<void>;

Schedules the lifecycle state of an ability to Background. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let ability;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
    console.info('getCurrentTopAbility callback');
    ability = data;
    abilityDelegator.doAbilityBackground(ability).then(() => {
        console.info("doAbilityBackground promise");
    });
});

printSync⁹⁺

printSync(msg: string): void;

Prints log information to the unit test console.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let msg = 'msg';

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.printSync(msg);

print

print(msg: string, callback: AsyncCallback<void>): void;

Prints log information to the unit test console. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let msg = 'msg';

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.print(msg, (err : any) => {
    console.info('print callback');
});

print

print(msg: string): Promise<void>;

Prints log information to the unit test console. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let msg = 'msg';

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.print(msg).then(() => {
    console.info('print promise');
});

executeShellCommand

executeShellCommand(cmd: string, callback: AsyncCallback<ShellCmdResult>): void;

Executes a shell command. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let cmd = 'cmd';

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, (err : any, data : any) => {
    console.info('executeShellCommand callback');
});

executeShellCommand

executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback<ShellCmdResult>): void;

Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let cmd = 'cmd';
let timeout = 100;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, timeout, (err : any, data : any) => {
    console.info('executeShellCommand callback');
});

executeShellCommand

executeShellCommand(cmd: string, timeoutSecs?: number): Promise<ShellCmdResult>;

Executes a shell command with the timeout period specified. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let cmd = 'cmd';
let timeout = 100;

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, timeout).then((data : any) => {
    console.info('executeShellCommand promise');
});

finishTest⁹⁺

finishTest(msg: string, code: number, callback: AsyncCallback<void>): void;

Finishes the test and prints log information to the unit test console. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let msg = 'msg';

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.finishTest(msg, 0, (err : any) => {
    console.info('finishTest callback');
});

finishTest⁹⁺

finishTest(msg: string, code: number): Promise<void>;

Finishes the test and prints log information to the unit test console. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let msg = 'msg';

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.finishTest(msg, 0).then(() => {
    console.info('finishTest promise');
});

addAbilityStageMonitor⁹⁺

addAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback<void>): void;

Adds an AbilityStageMonitor instance to monitor the lifecycle state changes of an ability stage. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

let monitor = {
    moduleName: 'moduleName',
    srcEntrance: 'srcEntrance',
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityStageMonitor(monitor, (err : any) => {
    console.info('addAbilityStageMonitor callback');
});

addAbilityStageMonitor⁹⁺

addAbilityStageMonitor(monitor: AbilityStageMonitor): Promise<void>;

Adds an AbilityStageMonitor instance to monitor the lifecycle state changes of an ability stage. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

let monitor = {
    moduleName: 'moduleName',
    srcEntrance: 'srcEntrance',
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityStageMonitor(monitor).then(() => {
    console.info('addAbilityStageMonitor promise');
});

removeAbilityStageMonitor⁹⁺

removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback<void>): void;

Removes an AbilityStageMonitor instance from the application memory. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

let monitor = {
    moduleName: 'moduleName',
    srcEntrance: 'srcEntrance',
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.removeAbilityStageMonitor(monitor, (err : any) => {
    console.info('removeAbilityStageMonitor callback');
});

removeAbilityStageMonitor⁹⁺

removeAbilityStageMonitor(monitor: AbilityStageMonitor): Promise<void>;

Removes an AbilityStageMonitor object from the application memory. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

let monitor = {
    moduleName: 'moduleName',
    srcEntrance: 'srcEntrance',
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.removeAbilityStageMonitor(monitor).then(() => {
    console.info('removeAbilityStageMonitor promise');
});

waitAbilityStageMonitor⁹⁺

waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback<AbilityStage>): void;

Waits for an AbilityStage instance that matches the conditions set in an AbilityStageMonitor instance and returns the AbilityStage instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    moduleName: 'moduleName',
    srcEntrance: 'srcEntrance',
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityStageMonitor(monitor, (err : any, data : any) => {
    console.info('waitAbilityStageMonitor callback');
});

waitAbilityStageMonitor⁹⁺

waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout?: number): Promise<AbilityStage>;

Waits for an AbilityStage instance that matches the conditions set in an AbilityStageMonitor instance and returns the AbilityStage instance. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    moduleName: 'moduleName',
    srcEntrance: 'srcEntrance',
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityStageMonitor(monitor).then((data : any) => {
    console.info('waitAbilityStageMonitor promise');
});

waitAbilityStageMonitor⁹⁺

waitAbilityStageMonitor(monitor: AbilityStageMonitor, timeout: number, callback: AsyncCallback<AbilityStage>): void;

Waits a period of time for an AbilityStage instance that matches the conditions set in an AbilityStageMonitor instance and returns the AbilityStage instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator;
let timeout = 100;

function onAbilityCreateCallback(data) {
    console.info('onAbilityCreateCallback');
}

let monitor = {
    moduleName: 'moduleName',
    srcEntrance: 'srcEntrance',
};

abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityStageMonitor(monitor, timeout, (err : any, data : any) => {
    console.info('waitAbilityStageMonitor callback');
});