AbilityContext
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 can be used only in the stage model.
Implements the ability context. This module is inherited from Context.
Modules to Import
import Ability from '@ohos.application.Ability'
Usage
Before using the AbilityContext module, you must define a child class that inherits from Ability.
import Ability from '@ohos.application.Ability'
class MainAbility extends Ability {
onWindowStageCreate(windowStage) {
let context = this.context;
}
}
Attributes
System capability: SystemCapability.Ability.AbilityRuntime.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
abilityInfo | AbilityInfo | Yes | No | Ability information. |
currentHapModuleInfo | HapModuleInfo | Yes | No | Information about the current HAP. |
AbilityContext.startAbility
startAbility(want: Want, callback: AsyncCallback<void>): void
Starts an ability. This API uses a callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Information about the Want used for starting an ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
this.context.startAbility(want, (error) => {
console.log("error.code = " + error.code)
})
AbilityContext.startAbility
startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void
Starts an ability. This API uses a callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Information about the Want used for starting an ability. |
options | StartOptions | Yes | Parameters used for starting the ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var options = {
windowMode: 0,
};
this.context.startAbility(want, options, (error) => {
console.log("error.code = " + error.code)
})
AbilityContext.startAbility
startAbility(want: Want, options?: StartOptions): Promise<void>;
Starts an ability. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Information about the Want used for starting an ability. |
options | StartOptions | No | Parameters used for starting the ability. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
var want = {
"deviceId": "",
"bundleName": "com.extreme.test",
"abilityName": "MainAbility"
};
var options = {
windowMode: 0,
};
this.context.startAbility(want, options)
.then((data) => {
console.log('Operation successful.')
}).catch((error) => {
console.log('Operation failed.');
})
AbilityContext.startAbilityForResult
startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void;
Starts an ability. This API uses a callback to return the result when the ability is terminated.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Information about the Want used for starting an ability. |
callback | AsyncCallback<AbilityResult> | Yes | Callback used to return the result. |
Example
this.context.startAbilityForResult(
{deviceId: "", bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"},
(error, result) => {
console.log("startAbilityForResult AsyncCallback is called, error.code = " + error.code)
console.log("startAbilityForResult AsyncCallback is called, result.resultCode = " + result.resultCode)
}
);
AbilityContext.startAbilityForResult
startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void;
Starts an ability. This API uses a callback to return the result when the ability is terminated.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Information about the Want used for starting an ability. |
options | StartOptions | Yes | Parameters used for starting the ability. |
callback | AsyncCallback<AbilityResult> | Yes | Callback used to return the result. |
Example
var options = {
windowMode: 0,
};
this.context.startAbilityForResult(
{deviceId: "", bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"}, options,
(error, result) => {
console.log("startAbilityForResult AsyncCallback is called, error.code = " + error.code)
console.log("startAbilityForResult AsyncCallback is called, result.resultCode = " + result.resultCode)
}
);
AbilityContext.startAbilityForResult
startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>;
Starts an ability. This API uses a promise to return the result when the ability is terminated.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Information about the Want used for starting an ability. |
options | StartOptions | No | Parameters used for starting the ability. |
Return value
Type | Description |
---|---|
Promise<AbilityResult> | Promise used to return the result. |
Example
var options = {
windowMode: 0,
};
this.context.startAbilityForResult({deviceId: "", bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"}, options).then((result) => {
console.log("startAbilityForResult Promise.resolve is called, result.resultCode = " + result.resultCode)
}, (error) => {
console.log("startAbilityForResult Promise.Reject is called, error.code = " + error.code)
})
AbilityContext.terminateSelf
terminateSelf(callback: AsyncCallback<void>): void;
Terminates this ability. This API uses a callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether the API is successfully called. |
Example
this.context.terminateSelf((err) => {
console.log('terminateSelf result:' + JSON.stringify(err));
});
AbilityContext.terminateSelf
terminateSelf(): Promise<void>;
Terminates this ability. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result indicating whether the API is successfully called. |
Example
this.context.terminateSelf(want).then((data) => {
console.log('success:' + JSON.stringify(data));
}).catch((error) => {
console.log('failed:' + JSON.stringify(error));
});
AbilityContext.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void;
Terminates this ability. This API uses a callback to return the information to the caller of startAbilityForResult.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | AbilityResult | Yes | Information returned to the caller. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
this.context.terminateSelfWithResult(
{
want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"},
resultCode: 100
}, (error) => {
console.log("terminateSelfWithResult is called = " + error.code)
}
);
AbilityContext.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult): Promise<void>;
Terminates this ability. This API uses a promise to return information to the caller of startAbilityForResult.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | AbilityResult | Yes | Information returned to the caller. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
this.context.terminateSelfWithResult(
{
want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"},
resultCode: 100
}).then((result) => {
console.log("terminateSelfWithResult")
}
)
AbilityContext.startAbilityByCall
startAbilityByCall(want: Want): Promise<Caller>;
Obtains the caller interface of the specified ability, and if the specified ability is not started, starts the ability in the background.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Information about the ability to start, including the ability name, bundle name, and device ID. If the device ID is left blank or the default value is used, the local ability will be started. |
Return value
Type | Description |
---|---|
Promise<Caller> | Promise used to return the caller object to communicate with. |
Example
import Ability from '@ohos.application.Ability';
var caller;
export default class MainAbility extends Ability {
onWindowStageCreate(windowStage) {
this.context.startAbilityByCall({
bundleName: "com.example.myservice",
abilityName: "MainAbility",
deviceId: ""
}).then((obj) => {
caller = obj;
console.log('Caller GetCaller Get ' + caller);
}).catch((e) => {
console.log('Caller GetCaller error ' + e);
});
}
}
AbilityContext.requestPermissionsFromUser
requestPermissionsFromUser(permissions: Array<string>, requestCallback: AsyncCallback<PermissionRequestResult>) : void;
Requests permissions from the user by displaying a pop-up window. This API uses a callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
permissions | Array<string> | Yes | Permissions to request. |
callback | AsyncCallback<PermissionRequestResult> | Yes | Callback used to return the result indicating whether the API is successfully called. |
Example
var permissions=['com.example.permission']
this.context.requestPermissionsFromUser(permissions,(result) => {
console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
});
AbilityContext.requestPermissionsFromUser
requestPermissionsFromUser(permissions: Array<string>) : Promise<PermissionRequestResult>;
Requests permissions from the user by displaying a pop-up window. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
permissions | Array<string> | Yes | Permissions to request. |
Return value
Type | Description |
---|---|
Promise<PermissionRequestResult> | Promise used to return the result indicating whether the API is successfully called. |
Example
var permissions=['com.example.permission']
this.context.requestPermissionsFromUser(permissions).then((data) => {
console.log('success:' + JSON.stringify(data));
}).catch((error) => {
console.log('failed:' + JSON.stringify(error));
});
AbilityContext.setMissionLabel
setMissionLabel(label: string, callback:AsyncCallback<void>): void;
Sets the label of the ability in the mission. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
label | string | Yes | Label of the ability to set. |
callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether the API is successfully called. |
Example
this.context.setMissionLabel("test",(result) => {
console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
});
AbilityContext.setMissionLabel
setMissionLabel(label: string): Promise<void>
Sets the label of the ability in the mission. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
label | string | Yes | Label of the ability to set. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result indicating whether the API is successfully called. |
Example
this.context.setMissionLabel("test").then((data) => {
console.log('success:' + JSON.stringify(data));
}).catch((error) => {
console.log('failed:' + JSON.stringify(error));
});
AbilityContext.isTerminating
isTerminating(): boolean;
Checks whether this ability is in the terminating state.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
bool | The value true means that the ability is in terminating state, and false means the opposite. |
Example
var isTerminating = this.context.isTerminating();
console.log('ability state :' + isTerminating);