• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.application.abilityManager (AbilityManager)
2
3The **AbilityManager** module provides APIs for obtaining, adding, and modifying ability running information and state information.
4
5> **NOTE**
6>
7> The APIs of this module are supported since API version 8 and deprecated since API version 9. You are advised to use [@ohos.app.ability.abilityManager](js-apis-app-ability-abilityManager.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8> The APIs of this module are system APIs and cannot be called by third-party applications.
9
10## Modules to Import
11
12```ts
13import abilityManager from '@ohos.application.abilityManager';
14```
15
16## AbilityState
17
18Enumerates the ability states.
19
20**System capability**: SystemCapability.Ability.AbilityRuntime.Core
21
22**System API**: This is a system API.
23
24| Name| Value| Description|
25| -------- | -------- | -------- |
26| INITIAL | 0 | The ability is in the initial state.|
27| FOREGROUND | 9 | The ability is running in the foreground. |
28| BACKGROUND | 10 | The ability is running in the background. |
29| FOREGROUNDING | 11 | The ability is being switched to the foreground. |
30| BACKGROUNDING | 12 | The ability is being switched to the background. |
31
32## updateConfiguration
33
34updateConfiguration(config: Configuration, callback: AsyncCallback\<void>): void
35
36Updates the configuration. This API uses an asynchronous callback to return the result.
37
38**Permission required**: ohos.permission.UPDATE_CONFIGURATION
39
40**System capability**: SystemCapability.Ability.AbilityRuntime.Core
41
42**Parameters**
43
44| Name       | Type                                      | Mandatory  | Description            |
45| --------- | ---------------------------------------- | ---- | -------------- |
46| config    | [Configuration](js-apis-application-configuration.md)   | Yes   | New configuration.|
47| callback  | AsyncCallback\<void>                   | Yes   | Callback used to return the result. If the configuration is updated, **err** is undefined; otherwise, **err** is an error object.     |
48
49**Example**
50
51```ts
52import abilityManager from '@ohos.application.abilityManager';
53import { Configuration } from '@ohos.application.Configuration';
54
55let config: Configuration = {
56  language: 'chinese'
57};
58
59abilityManager.updateConfiguration(config, () => {
60    console.log('------------ updateConfiguration -----------');
61});
62```
63
64## updateConfiguration
65
66updateConfiguration(config: Configuration): Promise\<void>
67
68Updates the configuration. This API uses a promise to return the result.
69
70**Permission required**: ohos.permission.UPDATE_CONFIGURATION
71
72**System capability**: SystemCapability.Ability.AbilityRuntime.Core
73
74**System API**: This is a system API.
75
76**Parameters**
77
78| Name       | Type                                      | Mandatory  | Description            |
79| --------- | ---------------------------------------- | ---- | -------------- |
80| config    | [Configuration](js-apis-application-configuration.md)   | Yes   | New configuration.|
81
82**Return value**
83
84| Type                                      | Description     |
85| ---------------------------------------- | ------- |
86| Promise\<void> | Promise that returns no value.|
87
88**Example**
89
90```ts
91import abilityManager from '@ohos.application.abilityManager';
92import { Configuration } from '@ohos.application.Configuration';
93import { BusinessError } from '@ohos.base';
94
95let config: Configuration = {
96  language: 'chinese'
97};
98
99abilityManager.updateConfiguration(config).then(() => {
100  console.log('updateConfiguration success');
101}).catch((err: BusinessError) => {
102  console.error('updateConfiguration fail');
103});
104```
105
106## getAbilityRunningInfos
107
108getAbilityRunningInfos(callback: AsyncCallback\<Array\<AbilityRunningInfo>>): void
109
110Obtains the ability running information. This API uses an asynchronous callback to return the result.
111
112**Required permissions**: ohos.permission.GET_RUNNING_INFO
113
114**System capability**: SystemCapability.Ability.AbilityRuntime.Core
115
116**System API**: This is a system API.
117
118**Parameters**
119
120| Name       | Type                                      | Mandatory  | Description            |
121| --------- | ---------------------------------------- | ---- | -------------- |
122| callback  | AsyncCallback\<Array\<[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)>>  | Yes   | Callback used to return the ability running information.     |
123
124**Example**
125
126```ts
127import abilityManager from '@ohos.application.abilityManager';
128import { BusinessError } from '@ohos.base';
129
130abilityManager.getAbilityRunningInfos((err: BusinessError, data) => {
131    console.log(`getAbilityRunningInfos err: ${err}, data: ${JSON.stringify(data)}`);
132});
133```
134
135## getAbilityRunningInfos
136
137getAbilityRunningInfos(): Promise\<Array\<AbilityRunningInfo>>
138
139Obtains the ability running information. This API uses a promise to return the result.
140
141**Required permissions**: ohos.permission.GET_RUNNING_INFO
142
143**System capability**: SystemCapability.Ability.AbilityRuntime.Core
144
145**System API**: This is a system API.
146
147**Return value**
148
149| Type                                      | Description     |
150| ---------------------------------------- | ------- |
151| Promise\<Array\<[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)>> | Promise used to return the ability running information.|
152
153**Example**
154
155```ts
156import abilityManager from '@ohos.application.abilityManager';
157import { BusinessError } from '@ohos.base';
158
159abilityManager.getAbilityRunningInfos().then((data) => {
160    console.log(`getAbilityRunningInfos  data: ${JSON.stringify(data)}`);
161}).catch((err: BusinessError) => {
162  console.error(`getAbilityRunningInfos err: ${JSON.stringify(err)}`);
163});
164```
165