ApplicationContext
The ApplicationContext module, inherited from Context, provides application-level context capabilities, including APIs for registering and deregistering the lifecycle of application components.
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.
Modules to Import
import common from '@ohos.app.ability.common';
Usage
Before calling any APIs in ApplicationContext, obtain an ApplicationContext instance through the context instance.
ApplicationContext.on(type: 'abilityLifecycle', callback: AbilityLifecycleCallback)
on(type: 'abilityLifecycle', callback: AbilityLifecycleCallback): number
Registers a listener to monitor the ability lifecycle of the application. This API uses an asynchronous callback to return the result. Multi-thread concurrent calls are not supported.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'abilityLifecycle' | Yes | Event type. |
callback | AbilityLifecycleCallback | Yes | Callback used to return the ID of the registered listener. |
Return value
Type | Description |
---|---|
number | ID of the registered listener. The ID is incremented by 1 each time the listener is registered. When the ID exceeds 2^63-1, -1 is returned. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityLifecycleCallback from '@ohos.app.ability.AbilityLifecycleCallback';
let lifecycleId: number;
export default class EntryAbility extends UIAbility {
onCreate() {
console.log('MyAbility onCreate');
let AbilityLifecycleCallback: AbilityLifecycleCallback = {
onAbilityCreate(ability) {
console.log(`AbilityLifecycleCallback onAbilityCreate ability: ${ability}`);
},
onWindowStageCreate(ability, windowStage) {
console.log(`AbilityLifecycleCallback onWindowStageCreate ability: ${ability}`);
console.log(`AbilityLifecycleCallback onWindowStageCreate windowStage: ${windowStage}`);
},
onWindowStageActive(ability, windowStage) {
console.log(`AbilityLifecycleCallback onWindowStageActive ability: ${ability}`);
console.log(`AbilityLifecycleCallback onWindowStageActive windowStage: ${windowStage}`);
},
onWindowStageInactive(ability, windowStage) {
console.log(`AbilityLifecycleCallback onWindowStageInactive ability: ${ability}`);
console.log(`AbilityLifecycleCallback onWindowStageInactive windowStage: ${windowStage}`);
},
onWindowStageDestroy(ability, windowStage) {
console.log(`AbilityLifecycleCallback onWindowStageDestroy ability: ${ability}`);
console.log(`AbilityLifecycleCallback onWindowStageDestroy windowStage: ${windowStage}`);
},
onAbilityDestroy(ability) {
console.log(`AbilityLifecycleCallback onAbilityDestroy ability: ${ability}`);
},
onAbilityForeground(ability) {
console.log(`AbilityLifecycleCallback onAbilityForeground ability: ${ability}`);
},
onAbilityBackground(ability) {
console.log(`AbilityLifecycleCallback onAbilityBackground ability: ${ability}`);
},
onAbilityContinue(ability) {
console.log(`AbilityLifecycleCallback onAbilityContinue ability: ${ability}`);
}
}
// 1. Obtain applicationContext through the context attribute.
let applicationContext = this.context.getApplicationContext();
// 2. Use applicationContext.on() to subscribe to the 'abilityLifecycle' event.
lifecycleId = applicationContext.on('abilityLifecycle', AbilityLifecycleCallback);
console.log(`registerAbilityLifecycleCallback lifecycleId: ${lifecycleId}`);
}
}
ApplicationContext.off(type: 'abilityLifecycle', callbackId: number, callback: AsyncCallback<void>)
off(type: 'abilityLifecycle', callbackId: number, callback: AsyncCallback<void>): void
Deregisters the listener that monitors the ability lifecycle of the application. This API uses an asynchronous callback to return the result. Multi-thread concurrent calls are not supported.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'abilityLifecycle' | Yes | Event type. |
callbackId | number | Yes | ID of the listener to deregister. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the deregistration is successful, err is undefined. Otherwise, err is an error object. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
let lifecycleId: number;
export default class EntryAbility extends UIAbility {
onDestroy() {
let applicationContext = this.context.getApplicationContext();
console.log(`stage applicationContext: ${applicationContext}`);
applicationContext.off('abilityLifecycle', lifecycleId, (error, data) => {
if (error) {
console.error(`unregisterAbilityLifecycleCallback fail, err: ${JSON.stringify(error)}`);
} else {
console.log(`unregisterAbilityLifecycleCallback success, data: ${JSON.stringify(data)}`);
}
});
}
}
ApplicationContext.off(type: 'abilityLifecycle', callbackId: number)
off(type: 'abilityLifecycle', callbackId: number): Promise<void>
Deregisters the listener that monitors the ability lifecycle of the application. This API uses a promise to return the result. Multi-thread concurrent calls are not supported.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'abilityLifecycle' | Yes | Event type. |
callbackId | number | Yes | ID of the listener to deregister. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Example
import Ability from '@ohos.app.ability.UIAbility';
let lifecycleId: number;
export default class MyAbility extends Ability {
onDestroy() {
let applicationContext = this.context.getApplicationContext();
console.log(`stage applicationContext: ${applicationContext}`);
applicationContext.off('abilityLifecycle', lifecycleId);
}
}
ApplicationContext.on(type: 'environment', callback: EnvironmentCallback)
on(type: 'environment', callback: EnvironmentCallback): number
Registers a listener for system environment changes. This API uses an asynchronous callback to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'environment' | Yes | Event type. |
callback | EnvironmentCallback | Yes | Callback used to return the system environment changes. |
Return value
Type | Description |
---|---|
number | ID of the registered listener. The ID is incremented by 1 each time the listener is registered. When the ID exceeds 2^63-1, -1 is returned. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import EnvironmentCallback from '@ohos.app.ability.EnvironmentCallback';
let callbackId: number;
export default class EntryAbility extends UIAbility {
onCreate() {
console.log('MyAbility onCreate')
let environmentCallback: EnvironmentCallback = {
onConfigurationUpdated(config){
console.log(`onConfigurationUpdated config: ${JSON.stringify(config)}`);
},
onMemoryLevel(level){
console.log(`onMemoryLevel level: ${level}`);
}
};
// 1. Obtain an applicationContext object.
let applicationContext = this.context.getApplicationContext();
// 2. Use applicationContext.on() to subscribe to the 'environment' event.
callbackId = applicationContext.on('environment', environmentCallback);
console.log(`registerEnvironmentCallback callbackId: ${callbackId}`);
}
}
ApplicationContext.off(type: 'environment', callbackId: number, callback: AsyncCallback<void>)
off(type: 'environment', callbackId: number, callback: AsyncCallback<void>): void
Deregisters the listener for system environment changes. This API uses an asynchronous callback to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'environment' | Yes | Event type. |
callbackId | number | Yes | ID of the listener to deregister. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the deregistration is successful, err is undefined. Otherwise, err is an error object. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
let callbackId: number;
export default class EntryAbility extends UIAbility {
onDestroy() {
let applicationContext = this.context.getApplicationContext();
applicationContext.off('environment', callbackId, (error, data) => {
if (error) {
console.error(`unregisterEnvironmentCallback fail, err: ${JSON.stringify(error)}`);
} else {
console.log(`unregisterEnvironmentCallback success, data: ${JSON.stringify(data)}`);
}
});
}
}
ApplicationContext.off(type: 'environment', callbackId: number)
off(type: 'environment', callbackId: number): Promise<void>
Deregisters the listener for system environment changes. This API uses a promise to return the result. Multi-thread concurrent calls are not supported.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'environment' | Yes | Event type. |
callbackId | number | Yes | ID of the listener to deregister. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Example
import Ability from '@ohos.app.ability.UIAbility';
let callbackId: number;
export default class MyAbility extends Ability {
onDestroy() {
let applicationContext = this.context.getApplicationContext();
applicationContext.off('environment', callbackId);
}
}
ApplicationContext.on(type: 'applicationStateChange', callback: ApplicationStateChangeCallback)10+
on(type: 'applicationStateChange', callback: ApplicationStateChangeCallback): void
Registers a listener for application foreground/background state changes. This API uses an asynchronous callback to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'applicationStateChange' | Yes | Event type. |
callback | ApplicationStateChangeCallback | Yes | Callback used to return the result. You can define a callback for switching from the background to the foreground and a callback for switching from the foreground to the background. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import ApplicationStateChangeCallback from '@ohos.app.ability.ApplicationStateChangeCallback';
export default class MyAbility extends UIAbility {
onCreate() {
console.log('MyAbility onCreate');
let applicationStateChangeCallback: ApplicationStateChangeCallback = {
onApplicationForeground() {
console.info('applicationStateChangeCallback onApplicationForeground');
},
onApplicationBackground() {
console.info('applicationStateChangeCallback onApplicationBackground');
}
}
// 1. Obtain an applicationContext object.
let applicationContext = this.context.getApplicationContext();
// 2. Use applicationContext.on() to subscribe to the 'applicationStateChange' event.
applicationContext.on('applicationStateChange', applicationStateChangeCallback);
console.log('Resgiter applicationStateChangeCallback');
}
}
ApplicationContext.off(type: 'applicationStateChange', callback?: ApplicationStateChangeCallback)10+
off(type: 'applicationStateChange', callback?: ApplicationStateChangeCallback): void
Deregisters all the listeners for application foreground/background state changes. This API uses an asynchronous callback to return the result. Multi-thread concurrent calls are not supported.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | 'applicationStateChange' | Yes | Event type. |
callback | ApplicationStateChangeCallback | No | Callback used to return the result. You can define a callback for switching from the background to the foreground and a callback for switching from the foreground to the background. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
export default class MyAbility extends UIAbility {
onDestroy() {
let applicationContext = this.context.getApplicationContext();
applicationContext.off('applicationStateChange');
}
}
ApplicationContext.getRunningProcessInformation
getRunningProcessInformation(): Promise<Array<ProcessInformation>>
Obtains information about the running processes. This API uses a promise to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
Promise<Array<ProcessInformation>> | Promise used to return the API call result and the process running information. You can perform error handling or custom processing in this callback. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
export default class MyAbility extends UIAbility {
onForeground() {
let applicationContext = this.context.getApplicationContext();
applicationContext.getRunningProcessInformation().then((data) => {
console.log(`The process running information is: ${JSON.stringify(data)}`);
}).catch((error: BusinessError) => {
console.error(`error: ${JSON.stringify(error)}`);
});
}
}
ApplicationContext.getRunningProcessInformation
getRunningProcessInformation(callback: AsyncCallback<Array<ProcessInformation>>): void
Obtains information about the running processes. This API uses an asynchronous callback to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Array<ProcessInformation>> | Yes | Callback used to return the information about the running processes. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
export default class MyAbility extends UIAbility {
onForeground() {
let applicationContext = this.context.getApplicationContext();
applicationContext.getRunningProcessInformation((err, data) => {
if (err) {
console.error(`getRunningProcessInformation faile, err: ${JSON.stringify(err)}`);
} else {
console.log(`The process running information is: ${JSON.stringify(data)}`);
}
})
}
}
ApplicationContext.killAllProcesses
killAllProcesses(): Promise<void>
Kills all the processes where the application is located. This API uses a promise to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
export default class MyAbility extends UIAbility {
onBackground() {
let applicationContext = this.context.getApplicationContext();
applicationContext.killAllProcesses();
}
}
ApplicationContext.killAllProcesses
killAllProcesses(callback: AsyncCallback<void>)
Kills all the processes where the application is located. This API uses an asynchronous callback to return the result.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. If all the processes are killed, err is undefined. Otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
export default class MyAbility extends UIAbility {
onBackground() {
let applicationContext = this.context.getApplicationContext();
applicationContext.killAllProcesses(error => {
if (error) {
console.error(`killAllProcesses fail, error: ${JSON.stringify(error)}`);
}
});
}
}
ApplicationContext.setColorMode11+
setColorMode(colorMode: ConfigurationConstant.ColorMode): void
Sets the color mode for the application.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
colorMode | ConfigurationConstant.ColorMode | Yes | Target color mode, including dark mode, light mode, and system theme mode (no setting). |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
401 | If the input parameter is not valid parameter. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import ConfigurationConstant from '@ohos.app.ability.ConfigurationConstant';
export default class MyAbility extends UIAbility {
onCreate() {
let applicationContext = this.context.getApplicationContext();
applicationContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
}
}
ApplicationContext.setLanguage11+
setLanguage(language: string): void
Sets the language for the application.
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
language | string | Yes | Target language. The list of supported languages can be obtained by using static getSystemLanguage(): Array |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
401 | If the input parameter is not valid parameter. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
export default class MyAbility extends UIAbility {
onCreate() {
let applicationContext = this.context.getApplicationContext();
applicationContext.setLanguage('zh-cn');
}
}
ApplicationContext.clearUpApplicationData11+
clearUpApplicationData(): Promise<void>
Clears up the application data and revokes the permissions that the application has requested from users. This API uses a promise to return the result.
NOTE
This API stops the application process. After the application process is stopped, all subsequent callbacks will not be triggered.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
export default class MyAbility extends UIAbility {
onBackground() {
let applicationContext = this.context.getApplicationContext();
applicationContext.clearUpApplicationData();
}
}
ApplicationContext.clearUpApplicationData11+
clearUpApplicationData(callback: AsyncCallback<void>): void
Clears up the application data and revokes the permissions that the application has requested from users. This API uses an asynchronous callback to return the result.
NOTE
This API stops the application process. After the application process is stopped, all subsequent callbacks will not be triggered.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the application data is cleared up, error is undefined; otherwise, error is an error object. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
export default class MyAbility extends UIAbility {
onBackground() {
let applicationContext = this.context.getApplicationContext();
applicationContext.clearUpApplicationData(error => {
if (error) {
console.error(`clearUpApplicationData fail, error: ${JSON.stringify(error)}`);
}
});
}
}