AbilityDelegator

说明

本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

API 9当前为Canary版本，仅供试用，不保证接口可稳定调用。

导入模块

import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'

AbilityDelegator

addAbilityMonitor⁹⁺

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

添加AbilityMonitor实例（callback形式）

**系统能力：**SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填说明	说明
monitor	AbilityMonitor	是	AbilityMonitor实例
callback	AsyncCallback<void>	是	表示指定的回调方法

示例：

var abilityDelegator;

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

var monitor = {
    abilityName: "abilityname",
    onAbilityCreate: onAbilityCreateCallback
}

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

addAbilityMonitor⁹⁺

addAbilityMonitor(monitor: AbilityMonitor): Promise<void>

添加AbilityMonitor实例（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
monitor	AbilityMonitor	是	AbilityMonitor实例

返回值：

类型	说明
Promise<void>	以Promise形式返回。

示例：

var abilityDelegator;

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

var monitor = {
    abilityName: "abilityname",
    onAbilityCreate: onAbilityCreateCallback
}

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

removeAbilityMonitor⁹⁺

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

删除已经添加的AbilityMonitor实例（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
monitor	AbilityMonitor	是	AbilityMonitor实例
callback	AsyncCallback<void>	是	表示指定的回调方法

示例：

var abilityDelegator;

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

var 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形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

名称	类型	必填	说明
monitor	AbilityMonitor	是	AbilityMonitor实例

返回值：

类型	说明
Promise<void>	以Promise形式返回。

示例

var abilityDelegator;

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

var monitor = {
    abilityName: "abilityname",
    onAbilityCreate: onAbilityCreateCallback
}

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

waitAbilityMonitor⁹⁺

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

等待与AbilityMonitor实例匹配的ability到达OnCreate生命周期，并返回ability实例（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
monitor	AbilityMonitor	是	AbilityMonitor实例
callback	AsyncCallback<Ability>	是	表示指定的回调方法

示例：

var abilityDelegator;

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

var 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<Ability>): void

设置等待时间，等待与AbilityMonitor实例匹配的ability到达OnCreate生命周期，并返回ability实例（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
monitor	AbilityMonitor	是	AbilityMonitor实例
timeout	number	是	最大等待时间，单位毫秒（ms）
callback	AsyncCallback<Ability>	是	表示指定的回调方法

示例：

var abilityDelegator;
var timeout = 100;

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

var 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<Ability>

设置等待时间，等待与AbilityMonitor实例匹配的ability到达OnCreate生命周期，并返回ability实例（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
monitor	AbilityMonitor	是	AbilityMonitor实例
timeout	number	否	最大等待时间，单位毫秒（ms）

返回值：

类型	说明
Promise<Ability>	以Promise形式返回Ability。

示例：

var abilityDelegator;

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

var monitor = {
    abilityName: "abilityname",
    onAbilityCreate: onAbilityCreateCallback
}

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

getAppContext⁹⁺

getAppContext(): Context

获取应用Context

系统能力： SystemCapability.Ability.AbilityRuntime.Core

返回值：

类型	说明
Context	应用Context。

示例：

var abilityDelegator;

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

getAbilityState⁹⁺

getAbilityState(ability: Ability): number

获取指定ability的生命周期状态

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
ability	Ability	是	指定Ability对象

返回值：

类型	说明
number	指定ability的生命周期状态。状态枚举值使用AbilityLifecycleState。

示例：

var abilityDelegator;
var ability;

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

getCurrentTopAbility⁹⁺

getCurrentTopAbility(callback: AsyncCallback<Ability>): void

获取当前应用顶部ability（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Ability>	是	表示指定的回调方法

示例：

var abilityDelegator;
var ability;

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

getCurrentTopAbility⁹⁺

getCurrentTopAbility(): Promise<Ability>

获取当前应用顶部ability（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

返回值：

类型	说明
Promise<Ability>	以Promise形式返回当前应用顶部ability。

示例：

var abilityDelegator;
var ability;

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

doAbilityForeground⁹⁺

doAbilityForeground(ability: Ability, callback: AsyncCallback<boolean>): void

调度指定ability生命周期状态到Foreground状态（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
ability	Ability	是	指定Ability对象
callback	AsyncCallback<boolean>	是	表示指定的回调方法 - true：成功 - false：失败

示例：

var abilityDelegator;
var ability;

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

doAbilityForeground⁹⁺

doAbilityForeground(ability: Ability): Promise<boolean>

调度指定ability生命周期状态到Foreground状态（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
ability	Ability	是	指定Ability对象

返回值：

类型	说明
Promise<boolean>	以Promise形式返回执行结果。 - true：成功 - false：失败

示例：

var abilityDelegator;
var ability;

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

doAbilityBackground⁹⁺

doAbilityBackground(ability: Ability, callback: AsyncCallback<boolean>): void

调度指定ability生命周期状态到Background状态（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
ability	Ability	是	指定Ability对象
callback	AsyncCallback<boolean>	是	表示指定的回调方法 - true：成功 - false：失败

示例：

var abilityDelegator;
var ability;

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

doAbilityBackground⁹⁺

doAbilityBackground(ability: Ability): Promise<boolean>

调度指定ability生命周期状态到Background状态（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
ability	Ability	是	指定Ability对象

返回值：

类型	说明
Promise<boolean>	以Promise形式返回执行结果。 - true：成功 - false：失败

示例：

var abilityDelegator;
var ability;

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

startAbility⁹⁺

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

启动指定ability（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
want	Want	是	启动Ability参数
callback	AsyncCallback<void>	是	表示指定的回调方法

示例：

var abilityDelegator;
var want = {
    bundleName: "bundleName",
    abilityName: "abilityName"
};

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

startAbility⁹⁺

startAbility(want: Want): Promise<void>

启动指定ability（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
want	Want	是	启动Ability参数

返回值：

类型	说明
Promise<void>	以Promise形式返回。

示例：

var abilityDelegator;
var want = {
    bundleName: "bundleName",
    abilityName: "abilityName"
};

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

print

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

打印日志信息到单元测试终端控制台（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
msg	string	是	日志字符串
callback	AsyncCallback<void>	是	表示指定的回调方法

示例：

var abilityDelegator;
var msg = "msg";

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

print

print(msg: string): Promise<void>

打印日志信息到单元测试终端控制台（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
msg	string	是	日志字符串

返回值：

类型	说明
Promise<void>	以Promise形式返回。

示例：

var abilityDelegator;
var msg = "msg";

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

executeShellCommand

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

执行指定的shell命令（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
cmd	string	是	shell命令字符串
callback	AsyncCallback<ShellCmdResult>	是	表示指定的回调方法

示例：

var abilityDelegator;
var cmd = "cmd";

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

executeShellCommand

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

指定超时时间，并执行指定的shell命令（callback形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
cmd	string	是	shell命令字符串
timeoutSecs	number	是	设定命令超时时间，单位秒（s）
callback	AsyncCallback<ShellCmdResult>	是	表示指定的回调方法

示例：

var abilityDelegator;
var cmd = "cmd";
var timeout = 100;

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

executeShellCommand

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

指定超时时间，并执行指定的shell命令（promise形式）

系统能力： SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
cmd	string	是	shell命令字符串
timeoutSecs	number	否	设定命令超时时间，单位秒（s）

返回值：

类型	说明
Promise<ShellCmdResult>	以Promise形式返回Shell命令执行结果ShellCmdResult对象。

示例：

var abilityDelegator;
var cmd = "cmd";
var timeout = 100;

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

AbilityDelegator

导入模块

AbilityDelegator

addAbilityMonitor9+

addAbilityMonitor9+

removeAbilityMonitor9+

removeAbilityMonitor9+

waitAbilityMonitor9+

waitAbilityMonitor9+

waitAbilityMonitor9+

getAppContext9+

getAbilityState9+

getCurrentTopAbility9+

getCurrentTopAbility9+

doAbilityForeground9+

doAbilityForeground9+

doAbilityBackground9+

doAbilityBackground9+

startAbility9+

startAbility9+

print

print

executeShellCommand

executeShellCommand

executeShellCommand

addAbilityMonitor⁹⁺

addAbilityMonitor⁹⁺

removeAbilityMonitor⁹⁺

removeAbilityMonitor⁹⁺

waitAbilityMonitor⁹⁺

waitAbilityMonitor⁹⁺

waitAbilityMonitor⁹⁺

getAppContext⁹⁺

getAbilityState⁹⁺

getCurrentTopAbility⁹⁺

getCurrentTopAbility⁹⁺

doAbilityForeground⁹⁺

doAbilityForeground⁹⁺

doAbilityBackground⁹⁺

doAbilityBackground⁹⁺

startAbility⁹⁺

startAbility⁹⁺