HarmonyOS API:UIAbilityContext
版本:v3.1 Beta
UIAbilityContext
更新时间: 2023-02-17 09:19
UIAbilityContext是Ability的上下文环境,继承自Context。
UIAbilityContext模块提供允许访问特定Ability的资源的能力,包括对Ability的启动、停止的设置、获取caller通信接口、拉起弹窗请求用户授权等。
说明
- 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
- 本模块接口仅可在Stage模型下使用。
属性
系统能力:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core
名称 | 类型 | 可读 | 可写 | 说明 |
abilityInfo | 是 | 否 | Abilityinfo相关信息 | |
currentHapModuleInfo | 是 | 否 | 当前hap包的信息 | |
config | 是 | 否 | 表示配置信息。 |
UIAbilityContext.startAbility
startAbility(want: Want, callback: AsyncCallback<void>): void;
启动Ability(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
want | Want | 是 | 启动Ability的want信息。 |
callback | AsyncCallback<void> | 是 | callback形式返回启动结果 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000004 | Visibility verification failed. |
16000005 | Static permission denied. The specified process does not have the permission. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000008 | Crowdtest App Expiration. |
16000009 | Can not start ability in wukong mode. |
16000010 | Can not operation with continue flag. |
16000011 | Context does not exist. |
16000051 | Network error. The network is abnormal. |
16000052 | Free install not support. The application does not support freeinstall |
16000053 | Not top ability. The application is not top ability. |
16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
16000055 | Free install timeout. |
16000056 | Can not free install other ability. |
16000057 | Not support cross device free install. |
16200001 | Caller released. The caller has been released. |
16000050 | Internal Error. |
示例:
var want = {
bundleName: "com.example.myapp",
abilityName: "MyAbility"
};
try {
this.context.startAbility(want, (error) => {
if (error.code) {
// 处理业务逻辑错误
console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// 执行正常业务
console.log('startAbility succeed');
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbility
startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void;
启动Ability(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
want | Want | 是 | 启动Ability的want信息。 |
options | 是 | 启动Ability所携带的参数。 | |
callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000004 | Visibility verification failed. |
16000005 | Static permission denied. The specified process does not have the permission. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000008 | Crowdtest App Expiration. |
16000009 | Can not start ability in wukong mode. |
16000010 | Can not operation with continue flag. |
16000011 | Context does not exist. |
16000051 | Network error. The network is abnormal. |
16000052 | Free install not support. The application does not support freeinstall |
16000053 | Not top ability. The application is not top ability. |
16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
16000055 | Free install timeout. |
16000056 | Can not free install other ability. |
16000057 | Not support cross device free install. |
16200001 | Caller released. The caller has been released. |
16000050 | Internal Error. |
示例:
var want = {
deviceId: "",
bundleName: "com.extreme.test",
abilityName: "MainAbility"
};
var options = {
windowMode: 0
};
try {
this.context.startAbility(want, options, (error) => {
if (error.code) {
// 处理业务逻辑错误
console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// 执行正常业务
console.log('startAbility succeed');
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbility
startAbility(want: Want, options?: StartOptions): Promise<void>;
启动Ability(promise形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
want | Want | 是 | 启动Ability的want信息。 |
options | 否 | 启动Ability所携带的参数。 |
返回值:
类型 | 说明 |
Promise<void> | Promise形式返回启动结果。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000004 | Visibility verification failed. |
16000005 | Static permission denied. The specified process does not have the permission. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000008 | Crowdtest App Expiration. |
16000009 | Can not start ability in wukong mode. |
16000010 | Can not operation with continue flag. |
16000011 | Context does not exist. |
16000051 | Network error. The network is abnormal. |
16000052 | Free install not support. The application does not support freeinstall |
16000053 | Not top ability. The application is not top ability. |
16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
16000055 | Free install timeout. |
16000056 | Can not free install other ability. |
16000057 | Not support cross device free install. |
16200001 | Caller released. The caller has been released. |
16000050 | Internal Error. |
示例:
var want = {
bundleName: "com.example.myapp",
abilityName: "MyAbility"
};
var options = {
windowMode: 0,
};
try {
this.context.startAbility(want, options)
.then((data) => {
// 执行正常业务
console.log('startAbility succeed');
})
.catch((error) => {
// 处理业务逻辑错误
console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResult
startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void;
启动Ability并在该Ability退出的时候返回执行结果(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
want | Want | 是 | 启动Ability的want信息。 |
callback | AsyncCallback<AbilityResult> | 是 | 执行结果回调函数。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000004 | Visibility verification failed. |
16000005 | Static permission denied. The specified process does not have the permission. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000008 | Crowdtest App Expiration. |
16000009 | Can not start ability in wukong mode. |
16000010 | Can not operation with continue flag. |
16000011 | Context does not exist. |
16000051 | Network error. The network is abnormal. |
16000052 | Free install not support. The application does not support freeinstall |
16000053 | Not top ability. The application is not top ability. |
16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
16000055 | Free install timeout. |
16000056 | Can not free install other ability. |
16000057 | Not support cross device free install. |
16200001 | Caller released. The caller has been released. |
16000050 | Internal Error. |
示例:
var want = {
deviceId: "",
bundleName: "com.extreme.test",
abilityName: "MainAbility"
};
try {
this.context.startAbilityForResult(want, (error, result) => {
if (error.code) {
// 处理业务逻辑错误
console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// 执行正常业务
console.log("startAbilityForResult succeed, result.resultCode = " +
result.resultCode)
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResult
startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void;
启动Ability并在该Ability退出的时候返回执行结果(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
want | Want | 是 | 启动Ability的want信息。 |
options | 是 | 启动Ability所携带的参数。 | |
callback | AsyncCallback<AbilityResult> | 是 | 执行结果回调函数。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000004 | Visibility verification failed. |
16000005 | Static permission denied. The specified process does not have the permission. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000008 | Crowdtest App Expiration. |
16000009 | Can not start ability in wukong mode. |
16000010 | Can not operation with continue flag. |
16000011 | Context does not exist. |
16000051 | Network error. The network is abnormal. |
16000052 | Free install not support. The application does not support freeinstall |
16000053 | Not top ability. The application is not top ability. |
16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
16000055 | Free install timeout. |
16000056 | Can not free install other ability. |
16000057 | Not support cross device free install. |
16200001 | Caller released. The caller has been released. |
16000050 | Internal Error. |
示例:
var want = {
deviceId: "",
bundleName: "com.extreme.test",
abilityName: "MainAbility"
};
var options = {
windowMode: 0,
};
try {
this.context.startAbilityForResult(want, options, (error, result) => {
if (error.code) {
// 处理业务逻辑错误
console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// 执行正常业务
console.log("startAbilityForResult succeed, result.resultCode = " +
result.resultCode)
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResult
startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>;
启动Ability并在该Ability退出的时候返回执行结果(promise形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
want | Want | 是 | 启动Ability的want信息。 |
options | 否 | 启动Ability所携带的参数。 |
返回值:
类型 | 说明 |
Promise<AbilityResult> | Promise形式返回执行结果。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000004 | Visibility verification failed. |
16000005 | Static permission denied. The specified process does not have the permission. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000008 | Crowdtest App Expiration. |
16000009 | Can not start ability in wukong mode. |
16000010 | Can not operation with continue flag. |
16000011 | Context does not exist. |
16000051 | Network error. The network is abnormal. |
16000052 | Free install not support. The application does not support freeinstall |
16000053 | Not top ability. The application is not top ability. |
16000054 | Free install busyness. There are concurrent tasks, waiting for retry. |
16000055 | Free install timeout. |
16000056 | Can not free install other ability. |
16000057 | Not support cross device free install. |
16200001 | Caller released. The caller has been released. |
16000050 | Internal Error. |
示例:
var want = {
bundleName: "com.example.myapp",
abilityName: "MyAbility"
};
var options = {
windowMode: 0,
};
try {
this.context.startAbilityForResult(want, options)
.then((result) => {
// 执行正常业务
console.log("startAbilityForResult succeed, result.resultCode = " + result.resultCode);
})
.catch((error) => {
// 处理业务逻辑错误
console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.terminateSelf
terminateSelf(callback: AsyncCallback<void>): void;
停止Ability自身(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
callback | AsyncCallback<void> | 是 | 回调函数,返回接口调用是否成功的结果。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000011 | Context does not exist. |
16000050 | Internal Error. |
示例:
this.context.terminateSelf((error) => {
if (error.code) {
// 处理业务逻辑错误
console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// 执行正常业务
console.log('terminateSelf succeed');
});
UIAbilityContext.terminateSelf
terminateSelf(): Promise<void>;
停止Ability自身(promise形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
返回值:
类型 | 说明 |
Promise<void> | 返回一个Promise,包含接口的结果。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000011 | Context does not exist. |
16000050 | Internal Error. |
示例:
this.context.terminateSelf().then((data) => {
// 执行正常业务
console.log('terminateSelf succeed');
}).catch((error) => {
// 处理业务逻辑错误
console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
UIAbilityContext.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void;
停止Ability,配合startAbilityForResult使用,返回给接口调用方AbilityResult信息(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
parameter | 是 | 返回给调用startAbilityForResult 接口调用方的相关信息。 | |
callback | AsyncCallback<void> | 是 | callback形式返回停止结果。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000011 | Context does not exist. |
16000050 | Internal Error. |
示例:
var want = {
bundleName: "com.extreme.myapplication",
abilityName: "SecondAbility"
}
var resultCode = 100;
// 返回给接口调用方AbilityResult信息
var abilityResult = {
want,
resultCode
}
try {
this.context.terminateSelfWithResult(abilityResult, (error) => {
if (error.code) {
// 处理业务逻辑错误
console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// 执行正常业务
console.log('terminateSelfWithResult succeed');
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult): Promise<void>;
停止Ability,配合startAbilityForResult使用,返回给接口调用方AbilityResult信息(promise形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
parameter | 是 | 返回给startAbilityForResult 调用方的信息。 |
返回值:
类型 | 说明 |
Promise<void> | promise形式返回停止结果。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000007 | Service busyness. There are concurrent tasks, waiting for retry. |
16000011 | Context does not exist. |
16000050 | Internal Error. |
示例:
var want = {
bundleName: "com.extreme.myapplication",
abilityName: "SecondAbility"
}
var resultCode = 100;
// 返回给接口调用方AbilityResult信息
var abilityResult = {
want,
resultCode
}
try {
this.context.terminateSelfWithResult(abilityResult)
.then((data) => {
// 执行正常业务
console.log('terminateSelfWithResult succeed');
})
.catch((error) => {
// 处理业务逻辑错误
console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.connectServiceExtensionAbility
connectServiceExtensionAbility(want: Want, options: ConnectOptions): number;
使用AbilityInfo.AbilityType.SERVICE模板将当前Ability连接到一个Ability。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
want | Want | 是 | 启动Ability的want信息。 |
options | 否 | 远端对象实例。 |
返回值:
类型 | 说明 |
number | 返回Ability连接的结果code。 |
错误码:
错误码ID | 错误信息 |
201 | The application does not have permission to call the interface. |
401 | Invalid input parameter. |
16000001 | Input error. The specified ability name does not exist. |
16000002 | Ability type error. The specified ability type is wrong. |
16000004 | Visibility verification failed. |
16000011 | Context does not exist. |
16000050 | Internal Error. |
示例:
var want = {
deviceId: "",
bundleName: "com.extreme.test",
abilityName: "MainAbility"
};
var options = {
onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
onFailed(code) { console.log('----------- onFailed -----------') }
}
var connection = null;
try {
connection = this.context.connectServiceExtensionAbility(want, options);
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.disconnectServiceExtensionAbility
disconnectServiceExtensionAbility(connection: number): Promise<void>;
断开与ServiceExtensionAbility的连接(promise形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
connection | number | 是 | 连接的ServiceExtensionAbility的数字代码,即connectServiceExtensionAbility返回的connectionId。 |
返回值:
类型 | 说明 |
Promise<void> | 返回一个Promise,包含接口的结果。 |
错误码:
错误码ID | 错误信息 |
16000001 | The specified ability does not exist. |
16000005 | The specified process does not have the permission. |
16000011 | The context does not exist. |
16000050 | Internal error. |
示例:
// connection为connectServiceExtensionAbility中的返回值
let connection = 1;
try {
this.context.disconnectServiceExtensionAbility(connection)
.then(() => {
// 执行正常业务
console.log('disconnectServiceExtensionAbility succeed');
})
.catch((error) => {
// 处理业务逻辑错误
console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.disconnectServiceExtensionAbility
disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback<void>): void;
断开与ServiceExtensionAbility的连接(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
connection | number | 是 | 连接的ServiceExtensionAbility的数字代码,即connectServiceExtensionAbility返回的connectionId。 |
callback | AsyncCallback<void> | 是 | callback形式返回断开连接的结果。 |
错误码:
错误码ID | 错误信息 |
16000001 | The specified ability does not exist. |
16000005 | The specified process does not have the permission. |
16000011 | The context does not exist. |
16000050 | Internal error. |
示例:
// connection为connectServiceExtensionAbility中的返回值
let connection = 1;
try {
this.context.disconnectServiceExtensionAbility(connection, (error) => {
if (error.code) {
// 处理业务逻辑错误
console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// 执行正常业务
console.log('disconnectServiceExtensionAbility succeed');
});
} catch (paramError) {
// 处理入参错误异常
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.setMissionLabel
setMissionLabel(label: string, callback:AsyncCallback<void>): void;
设置ability在任务中显示的名称(callback形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
label | string | 是 | 显示名称。 |
callback | AsyncCallback<void> | 是 | 回调函数,返回接口调用是否成功的结果。 |
示例:
this.context.setMissionLabel("test",(result) => {
console.log('setMissionLabel:' + JSON.stringify(result));
});
UIAbilityContext.setMissionLabel
setMissionLabel(label: string): Promise<void>;
设置ability在任务中显示的名称(promise形式)。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
label | string | 是 | 显示名称。 |
返回值:
类型 | 说明 |
Promise<void> | 返回一个Promise,包含接口的结果。 |
示例:
this.context.setMissionLabel("test").then(() => {
console.log('success');
}).catch((error) => {
console.log('failed:' + JSON.stringify(error));
});
UIAbilityContext.restoreWindowStage
restoreWindowStage(localStorage: LocalStorage) : void;
恢复ability中的window stage数据。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
参数:
参数名 | 类型 | 必填 | 说明 |
localStorage | image.LocalStorage | 是 | 用于恢复window stage的存储数据。 |
示例:
var storage = new LocalStorage();
this.context.restoreWindowStage(storage);
UIAbilityContext.isTerminating
isTerminating(): boolean;
查询ability是否在terminating状态。
系统能力:SystemCapability.Ability.AbilityRuntime.Core
返回值:
类型 | 说明 |
bool | true:ability当前处于terminating状态;false:不处于terminating状态。 |
示例:
var isTerminating = this.context.isTerminating();
console.log('ability state :' + isTerminating);