• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.ability.autoStartupManager(autoStartupManager)(系统接口)
2
3<!--Kit: Ability Kit-->
4<!--Subsystem: Ability-->
5<!--Owner: @zhu-feimo; @Luobniz21-->
6<!--Designer: @ccllee1-->
7<!--Tester: @lixueqing513-->
8<!--Adviser: @huipeizi-->
9
10autoStartupManager模块提供应用开机自启动状态的监听能力，允许开发者通过回调机制感知应用自启动状态的变化。
11
12> **说明：**
13>
14> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
15>
16> 本模块接口仅可在Stage模型下使用。
17>
18> 本模块为系统接口。
19
20## 导入模块
21
22```ts
23import { autoStartupManager } from '@kit.AbilityKit';
24```
25
26## on
27
28on(type: 'systemAutoStartup', callback: AutoStartupCallback): void
29
30注册监听应用组件开机自启动状态变化的回调函数。
31
32**需要权限**：ohos.permission.MANAGE_APP_BOOT
33
34**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
35
36**参数**：
37
38| 参数名        | 类型                                       | 必填   | 说明             |
39| --------- | ---------------------------------------- | ---- | -------------- |
40| type | string | 是    | 固定取值“systemAutoStartup”，表示为系统应用所调用。 |
41| callback  | [AutoStartupCallback](js-apis-inner-application-autoStartupCallback-sys.md)   | 是    | 监听应用组件开机自启动状态变化的回调对象。      |
42
43**错误码：**
44
45以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
46
47| 错误码ID | 错误信息 |
48| -------- | -------------------------------- |
49| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
50| 202      | Permission denied, non-system app called system api. |
51| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
52| 16000050 | Internal error. |
53
54**示例**：
55
56```ts
57import { autoStartupManager, common } from '@kit.AbilityKit';
58import { BusinessError } from '@kit.BasicServicesKit';
59
60try {
61  autoStartupManager.on('systemAutoStartup', {
62    onAutoStartupOn(data: common.AutoStartupInfo) {
63      console.info(`autostartupmanager onAutoStartupOn, data: ${JSON.stringify(data)}.`);
64    },
65    onAutoStartupOff(data: common.AutoStartupInfo) {
66      console.info(`autostartupmanager onAutoStartupOff, data: ${JSON.stringify(data)}.`);
67    }
68  });
69} catch (err) {
70  let code = (err as BusinessError).code;
71  let msg = (err as BusinessError).message;
72  console.error(`autostartupmanager on failed, err code: ${code}, err msg: ${msg}.`);
73}
74```
75
76## off
77
78off(type: 'systemAutoStartup', callback?: AutoStartupCallback): void
79
80注销监听应用组件开机自启动状态变化的回调函数。
81
82**需要权限**：ohos.permission.MANAGE_APP_BOOT
83
84**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
85
86**参数**：
87
88| 参数名        | 类型                                       | 必填   | 说明             |
89| --------- | ---------------------------------------- | ---- | -------------- |
90| type | string              | 是    | 固定取值“systemAutoStartup”，表示为系统应用所调用。 |
91| callback | [AutoStartupCallback](js-apis-inner-application-autoStartupCallback-sys.md)   | 否 | 监听应用组件开机自启动状态变化的回调对象。 |
92
93**错误码：**
94
95以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
96
97| 错误码ID | 错误信息 |
98| -------- | -------------------------------- |
99| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
100| 202      | Permission denied, non-system app called system api. |
101| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
102| 16000050 | Internal error. |
103
104**示例**：
105
106```ts
107import { autoStartupManager, common } from '@kit.AbilityKit';
108import { BusinessError } from '@kit.BasicServicesKit';
109
110try {
111  autoStartupManager.off('systemAutoStartup', {
112    onAutoStartupOn(data: common.AutoStartupInfo) {
113      console.info(`autostartupmanager onAutoStartupOn, data: ${JSON.stringify(data)}.`);
114    },
115    onAutoStartupOff(data: common.AutoStartupInfo) {
116      console.info(`autostartupmanager onAutoStartupOff, data: ${JSON.stringify(data)}.`);
117    }
118  });
119} catch (err) {
120  let code = (err as BusinessError).code;
121  let msg = (err as BusinessError).message;
122  console.error(`autostartupmanager on failed, err code: ${code}, err msg: ${msg}.`);
123}
124```
125
126## setApplicationAutoStartup
127
128setApplicationAutoStartup(info: AutoStartupInfo, callback: AsyncCallback\<void\>): void
129
130设置应用组件开机自启动。使用callback异步回调。
131
132**需要权限**：ohos.permission.MANAGE_APP_BOOT
133
134**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
135
136**设备行为差异**：
137- 从API version 18开始，该接口仅在2in1和Wearable设备中可正常调用，在其他设备上返回16000050错误码。
138- 对于API version 18之前版本，该接口仅在2in1设备中可正常调用，在其他设备上返回16000050错误码。
139
140**参数**：
141
142| 参数名        | 类型                                       | 必填   | 说明             |
143| --------- | ---------------------------------------- | ---- | -------------- |
144| info | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md) | 是    | 要设置的开机自启动应用组件信息。 |
145| callback | AsyncCallback\<void\> | 是 | 回调函数。当设置应用组件开机自启动成功，err为undefined，否则为错误对象。 |
146
147**错误码**：
148
149以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
150
151| 错误码ID | 错误信息                                     |
152| -------- | -------------------------------------------- |
153| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
154| 202      | Permission denied, non-system app called system api. |
155| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
156| 16000004 | Cannot start an invisible component.         |
157| 16000013 | The application is controlled by EDM.        |
158| 16000050 | Internal error.                              |
159
160**示例**：
161
162```ts
163import { autoStartupManager } from '@kit.AbilityKit';
164import { BusinessError } from '@kit.BasicServicesKit';
165
166try {
167  autoStartupManager.setApplicationAutoStartup({
168    bundleName: 'com.example.autostartupapp',
169    abilityName: 'EntryAbility'
170  }, (err: BusinessError) => {
171    if (err) {
172      console.error(`setApplicationAutoStartup failed, err code: ${err.code}, err msg: ${err.message}.`);
173      return;
174    }
175    console.info(`setApplicationAutoStartup success.`);
176  });
177} catch (err) {
178  let code = (err as BusinessError).code;
179  let msg = (err as BusinessError).message;
180  console.error(`setApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`);
181}
182```
183
184## setApplicationAutoStartup
185
186setApplicationAutoStartup(info: AutoStartupInfo): Promise\<void\>
187
188设置应用组件开机自启动。使用Promise异步回调。
189
190**需要权限**：ohos.permission.MANAGE_APP_BOOT
191
192**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
193
194**设备行为差异**：
195- 从API version 18开始，该接口仅在2in1和Wearable设备中可正常调用，在其他设备上返回16000050错误码。
196- 对于API version 18之前版本，该接口仅在2in1设备中可正常调用，在其他设备上返回16000050错误码。
197
198**参数**：
199
200| 参数名 | 类型            | 必填 | 说明                         |
201| ------ | --------------- | ---- | ---------------------------- |
202| info   | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md) | 是   | 要设置的开机自启动应用组件信息。 |
203
204**返回值：**
205
206| 类型          | 说明                                                         |
207| ------------- | ------------------------------------------------------------ |
208| Promise\<void\> | Promise对象。无返回结果的Promise对象。 |
209
210**错误码**：
211
212以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
213
214| 错误码ID | 错误信息                                     |
215| -------- | -------------------------------------------- |
216| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
217| 202      | Permission denied, non-system app called system api. |
218| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
219| 16000004 | Cannot start an invisible component.         |
220| 16000013 | The application is controlled by EDM.        |
221| 16000050 | Internal error.                              |
222
223**示例**：
224
225```ts
226import { autoStartupManager } from '@kit.AbilityKit';
227import { BusinessError } from '@kit.BasicServicesKit';
228
229try {
230  autoStartupManager.setApplicationAutoStartup({
231    bundleName: 'com.example.autostartupapp',
232    abilityName: 'EntryAbility'
233  }).then((data: void) => {
234    console.info(`setApplicationAutoStartup success.`);
235  }).catch((err: BusinessError) => {
236    console.error(`setApplicationAutoStartup failed, err code: ${err.code}, err msg: ${err.message}.`);
237  });
238} catch (err) {
239  let code = (err as BusinessError).code;
240  let msg = (err as BusinessError).message;
241  console.error(`setApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`);
242}
243```
244
245## cancelApplicationAutoStartup
246
247cancelApplicationAutoStartup(info: AutoStartupInfo, callback: AsyncCallback\<void\>): void
248
249取消应用组件开机自启动。使用callback异步回调。
250
251**需要权限**：ohos.permission.MANAGE_APP_BOOT
252
253**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
254
255**设备行为差异**：
256- 从API version 18开始，该接口仅在2in1和Wearable设备中可正常调用，在其他设备上返回16000050错误码。
257- 对于API version 18之前版本，该接口仅在2in1设备中可正常调用，在其他设备上返回16000050错误码。
258
259**参数**：
260
261| 参数名        | 类型                                       | 必填   | 说明             |
262| --------- | ---------------------------------------- | ---- | -------------- |
263| info | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)   | 是 | 要取消的开机自启动应用组件信息。 |
264| callback | AsyncCallback\<void\> | 是    | 回调函数。当取消应用组件开机自启动成功，err为undefined，否则为错误对象。 |
265
266**错误码**：
267
268以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
269
270| 错误码ID | 错误信息                                     |
271| -------- | -------------------------------------------- |
272| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
273| 202      | Permission denied, non-system app called system api. |
274| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
275| 16000004 | Cannot start an invisible component.         |
276| 16000013 | The application is controlled by EDM.        |
277| 16000050 | Internal error.                              |
278
279**示例**：
280
281```ts
282import { autoStartupManager } from '@kit.AbilityKit';
283import { BusinessError } from '@kit.BasicServicesKit';
284
285try {
286  autoStartupManager.cancelApplicationAutoStartup({
287    bundleName: 'com.example.autostartupapp',
288    abilityName: 'EntryAbility'
289  }, (err: BusinessError) => {
290    if (err) {
291      console.error(`cancelApplicationAutoStartup failed, err code: ${err.code}, msg: ${err.message}.`);
292      return;
293    }
294    console.info(`cancelApplicationAutoStartup success.`);
295  });
296} catch (err) {
297  let code = (err as BusinessError).code;
298  let msg = (err as BusinessError).message;
299  console.error(`cancelApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`);
300}
301```
302
303## cancelApplicationAutoStartup
304
305cancelApplicationAutoStartup(info: AutoStartupInfo): Promise\<void\>
306
307取消应用组件开机自启动。使用Promise异步回调。
308
309**需要权限**：ohos.permission.MANAGE_APP_BOOT
310
311**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
312
313**设备行为差异**：
314- 从API version 18开始，该接口仅在2in1和Wearable设备中可正常调用，在其他设备上返回16000050错误码。
315- 对于API version 18之前版本，该接口仅在2in1设备中可正常调用，在其他设备上返回16000050错误码。
316
317**参数**：
318
319| 参数名        | 类型                                       | 必填   | 说明             |
320| --------- | ---------------------------------------- | ---- | -------------- |
321| info | [AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)   | 是 | 要取消的开机自启动应用组件信息。 |
322
323**返回值：**
324
325| 类型          | 说明                                                         |
326| ------------- | ------------------------------------------------------------ |
327| Promise\<void\> | Promise对象。无返回结果的Promise对象。 |
328
329**错误码**：
330
331以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
332
333| 错误码ID | 错误信息                                     |
334| -------- | -------------------------------------------- |
335| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
336| 202      | Permission denied, non-system app called system api. |
337| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
338| 16000004 | Cannot start an invisible component.         |
339| 16000013 | The application is controlled by EDM.        |
340| 16000050 | Internal error.                              |
341
342**示例**：
343
344```ts
345import { autoStartupManager } from '@kit.AbilityKit';
346import { BusinessError } from '@kit.BasicServicesKit';
347
348try {
349  autoStartupManager.cancelApplicationAutoStartup({
350    bundleName: 'com.example.autostartupapp',
351    abilityName: 'EntryAbility'
352  }).then(() => {
353    console.info(`cancelApplicationAutoStartup success.`);
354  }).catch((err: BusinessError) => {
355    console.error(`cancelApplicationAutoStartup failed, err code: ${err.code}, msg: ${err.message}.`);
356  });
357} catch (err) {
358  let code = (err as BusinessError).code;
359  let msg = (err as BusinessError).message;
360  console.error(`cancelApplicationAutoStartup failed, err code: ${code}, err msg: ${msg}.`);
361}
362```
363
364## queryAllAutoStartupApplications
365
366queryAllAutoStartupApplications(callback: AsyncCallback\<Array\<AutoStartupInfo\>\>): void
367
368查询自启动应用组件信息。使用callback异步回调。
369
370**需要权限**：ohos.permission.MANAGE_APP_BOOT
371
372**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
373
374**设备行为差异**：
375- 从API version 18开始，该接口仅在2in1和Wearable设备中可正常调用，在其他设备上返回16000050错误码。
376- 对于API version 18之前版本，该接口仅在2in1设备中可正常调用，在其他设备上返回16000050错误码。
377
378**参数**：
379
380| 参数名        | 类型                                       | 必填   | 说明             |
381| --------- | ---------------------------------------- | ---- | -------------- |
382| callback  | AsyncCallback\<Array\<[AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)\>\> | 是    | 回调函数。当查询自启动应用组件信息成功，err为undefined，data为获取到的Array\<[AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)\>；否则为错误对象。      |
383
384**错误码**：
385
386以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
387
388| 错误码ID | 错误信息                                     |
389| -------- | -------------------------------------------- |
390| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
391| 202      | Permission denied, non-system app called system api. |
392| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
393| 16000050 | Internal error. |
394
395**示例**：
396
397```ts
398import { autoStartupManager, common } from '@kit.AbilityKit';
399import { BusinessError } from '@kit.BasicServicesKit';
400
401try {
402  autoStartupManager.queryAllAutoStartupApplications((err: BusinessError, data: common.AutoStartupInfo[]) => {
403    if (err) {
404      console.error(`queryAllAutoStartupApplications failed, err code: ${err.code}, err msg: ${err.message}.`);
405      return;
406    }
407    console.info(`queryAllAutoStartupApplications success, data: ${JSON.stringify(data)}.`);
408  });
409} catch (err) {
410  let code = (err as BusinessError).code;
411  let msg = (err as BusinessError).message;
412  console.error(`queryAllAutoStartupApplications failed, err code: ${code}, err msg: ${msg}.`);
413}
414```
415
416## queryAllAutoStartupApplications
417
418 queryAllAutoStartupApplications(): Promise\<Array\<AutoStartupInfo\>\>
419
420查询自启动应用组件信息。使用Promise异步回调。
421
422**需要权限**：ohos.permission.MANAGE_APP_BOOT
423
424**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
425
426**设备行为差异**：
427- 从API version 18开始，该接口仅在2in1和Wearable设备中可正常调用，在其他设备上返回16000050错误码。
428- 对于API version 18之前版本，该接口仅在2in1设备中可正常调用，在其他设备上返回16000050错误码。
429
430**返回值：**
431
432| 类型                            | 说明                                                         |
433| ------------------------------- | ------------------------------------------------------------ |
434| Promise\<Array\<[AutoStartupInfo](js-apis-inner-application-autoStartupInfo-sys.md)\>\> | Promise对象，返回自启动应用组件信息。 |
435
436**错误码**：
437
438以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
439
440| 错误码ID | 错误信息                                     |
441| -------- | -------------------------------------------- |
442| 201      | Permission denied, interface caller does not have permission "ohos.permission.MANAGE_APP_BOOT". |
443| 202      | Permission denied, non-system app called system api. |
444| 401      | The parameter check failed. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. |
445| 16000050 | Internal error. |
446
447**示例**：
448
449```ts
450import { autoStartupManager, common } from '@kit.AbilityKit';
451import { BusinessError } from '@kit.BasicServicesKit';
452
453try {
454  autoStartupManager.queryAllAutoStartupApplications().then((data: common.AutoStartupInfo[]) => {
455    console.info(`queryAllAutoStartupApplications success, data: ${JSON.stringify(data)}.`);
456  }).catch((err: BusinessError) => {
457    console.error(`queryAllAutoStartupApplications failed, err code: ${err.code}, err msg: ${err.message}.`);
458  });
459} catch (err) {
460  let code = (err as BusinessError).code;
461  let msg = (err as BusinessError).message;
462  console.error(`queryAllAutoStartupApplications failed, err code: ${code}, err msg: ${msg}.`);
463}
464```
465