• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.appstartup.startupManager (启动框架管理能力)
2<!--Kit: Ability Kit-->
3<!--Subsystem: Ability-->
4<!--Owner: @yzkp-->
5<!--Designer: @yzkp-->
6<!--Tester: @lixueqing513-->
7<!--Adviser: @huipeizi-->
8
9本模块提供应用启动框架管理启动任务的能力，只能在主线程调用。
10
11> **说明：**
12>
13> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
14>
15> 本模块从API version 18开始支持so预加载。
16>
17> 本模块接口仅可在Stage模型下使用。
18
19## 导入模块
20
21```ts
22import { startupManager }  from '@kit.AbilityKit';
23```
24
25## startupManager.run
26run(startupTasks: Array\<string\>, config?: StartupConfig): Promise\<void\>
27
28执行启动框架启动任务或加载so文件。
29
30> **说明：**
31>
32> 如果需要执行feature类型HAP中的启动任务，不支持使用该接口，需要使用[startupManager.run](#startupmanagerrun20)接口。
33
34**系统能力**：SystemCapability.Ability.AppStartup
35
36**参数：**
37
38| 参数名 | 类型 | 必填 | 说明 |
39| -------- | -------- | -------- | -------- |
40| startupTasks | Array\<string\> | 是 | 表示准备执行的启动任务[StartupTask](js-apis-app-appstartup-startupTask.md)的名称和预加载so名称的数组。 |
41| config | [StartupConfig](./js-apis-app-appstartup-startupConfig.md) | 否 | 启动框架超时时间与启动任务监听器配置。 |
42
43**返回值：**
44
45| 类型 | 说明 |
46| -------- | -------- |
47| Promise\<void\> | Promise对象。无返回结果的Promise对象。 |
48
49**错误码：**
50
51以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
52
53  | 错误码ID | 错误信息 |
54  | ------- | -------------------------------- |
55  | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
56  | 16000050 | Internal error. |
57  | 28800001 | Startup task or its dependency not found. |
58  | 28800002  | The startup tasks have circular dependencies. |
59  | 28800003 | An error occurred while running the startup tasks. |
60  | 28800004 | Running startup tasks timeout. |
61
62**示例：**
63
64```ts
65import { AbilityConstant, UIAbility, Want, startupManager } from '@kit.AbilityKit';
66import { hilog } from '@kit.PerformanceAnalysisKit';
67import { BusinessError } from '@kit.BasicServicesKit';
68
69export default class EntryAbility extends UIAbility {
70  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
71    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
72    let startParams = ['StartupTask_001', 'libentry_001'];
73    try {
74      // 手动调用run方法
75      startupManager.run(startParams).then(() => {
76        console.log(`StartupTest startupManager run then, startParams = ${startParams}.`);
77      }).catch((error: BusinessError) => {
78        console.error(`StartupTest promise catch failed, error code: ${error.code}, error msg: ${error.message}.`);
79      });
80    } catch (error) {
81      let errMsg = (error as BusinessError).message;
82      let errCode = (error as BusinessError).code;
83      console.error(`Startup.run failed, err code: ${errCode}, err msg: ${errMsg}.`);
84    }
85  }
86
87  // ...
88}
89```
90
91## startupManager.run<sup>20+</sup>
92
93run(startupTasks: Array\<string\>, context: common.AbilityStageContext, config: StartupConfig): Promise\<void\>
94
95执行启动框架启动任务或加载so文件。支持指定[AbilityStageContext](js-apis-inner-application-abilityStageContext.md)用于启动任务的加载。使用Promise异步回调。
96
97**系统能力**：SystemCapability.Ability.AppStartup
98
99**参数：**
100
101| 参数名       | 类型                                                         | 必填 | 说明                                                         |
102| ------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
103| startupTasks | Array\<string\>                                              | 是   | 表示准备执行的启动任务[StartupTask](js-apis-app-appstartup-startupTask.md)的名称和预加载so名称的数组。 |
104| context      | [common.AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | 是   | 表示执行启动任务[StartupTask](js-apis-app-appstartup-startupTask.md)的AbilityStage上下文，作为入参传给启动任务的[init](js-apis-app-appstartup-startupTask.md#init)。 |
105| config       | [StartupConfig](./js-apis-app-appstartup-startupConfig.md)   | 是   | 启动框架超时时间与启动任务监听器配置。                       |
106
107**返回值：**
108
109| 类型            | 说明                                   |
110| --------------- | -------------------------------------- |
111| Promise\<void\> | Promise对象。无返回结果的Promise对象。 |
112
113**错误码：**
114
115以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。
116
117| 错误码ID | 错误信息                                           |
118| -------- | -------------------------------------------------- |
119| 16000050 | Internal error.                                    |
120| 28800001 | Startup task or its dependency not found.          |
121| 28800002 | The startup tasks have circular dependencies.      |
122| 28800003 | An error occurred while running the startup tasks. |
123| 28800004 | Running startup tasks timeout.                     |
124
125**示例：**
126
127```ts
128import { AbilityStage, startupManager, StartupListener, StartupConfig } from '@kit.AbilityKit';
129import { hilog } from '@kit.PerformanceAnalysisKit';
130import { BusinessError } from '@kit.BasicServicesKit';
131
132export default class MyAbilityStage extends AbilityStage {
133  onCreate(): void {
134    hilog.info(0x0000, 'testTag', 'AbilityStage onCreate');
135    let onCompletedCallback = (error: BusinessError<void>) => {
136      if (error) {
137        hilog.error(0x0000, 'testTag', 'onCompletedCallback error: %{public}s', JSON.stringify(error));
138      } else {
139        hilog.info(0x0000, 'testTag', 'onCompletedCallback: success.');
140      }
141    };
142    let startupListener: StartupListener = {
143      'onCompleted': onCompletedCallback
144    };
145    let config: StartupConfig = {
146      'timeoutMs': 10000,
147      'startupListener': startupListener
148    };
149
150    try {
151      // 手动调用run方法
152      startupManager.run(['StartupTask_001', 'libentry_001'], this.context, config).then(() => {
153        hilog.info(0x0000, 'testTag', '%{public}s', 'startupManager.run success');
154      }).catch((error: BusinessError<void>) => {
155        hilog.error(0x0000, 'testTag', 'startupManager.run promise catch error: %{public}s', JSON.stringify(error));
156      })
157    } catch (error) {
158      hilog.error(0x0000, 'testTag', 'startupManager.run catch error: %{public}s', JSON.stringify(error));
159    }
160  }
161  // ...
162}
163```
164
165## startupManager.removeAllStartupTaskResults
166
167removeAllStartupTaskResults(): void
168
169删除所有启动任务结果。
170
171如果存在so预加载任务，则将对应so文件置为未加载状态。对于缓存中已加载的so文件，不会被移除。
172
173**系统能力**：SystemCapability.Ability.AppStartup
174
175**示例：**
176
177```ts
178import { AbilityConstant, UIAbility, Want, startupManager } from '@kit.AbilityKit';
179import { window } from '@kit.ArkUI';
180import { hilog } from '@kit.PerformanceAnalysisKit';
181import { BusinessError } from '@kit.BasicServicesKit';
182
183export default class EntryAbility extends UIAbility {
184  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
185    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
186    try {
187      startupManager.run(['StartupTask_001', 'libentry_001']).then(() => {
188        hilog.info(0x0000, 'testTag', 'StartupTask_001 init successful');
189      }).catch((error: BusinessError) => {
190        hilog.error(0x0000, 'testTag', `StartupTask_001 promise catch failed, error: %{public}s`,
191          JSON.stringify(error) ?? '');
192      });
193    } catch (error) {
194      hilog.error(0x0000, 'testTag', `StartupTask_001.run failed, error: %{public}s`, JSON.stringify(error) ?? '');
195    }
196  }
197
198  onWindowStageCreate(windowStage: window.WindowStage) {
199    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
200    startupManager.removeAllStartupTaskResults(); // 移除所有启动任务结果
201
202    windowStage.loadContent('pages/Index', (err, data) => {
203      if (err.code) {
204        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
205        return;
206      }
207      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
208    });
209  }
210}
211```
212
213
214## startupManager.getStartupTaskResult
215
216getStartupTaskResult(startupTask: string): Object
217
218获取指定启动任务或so预加载任务的执行结果。
219
220**系统能力**：SystemCapability.Ability.AppStartup
221
222**参数：**
223
224  | 参数名 | 类型 | 必填 | 说明 |
225  | -------- | -------- | -------- | -------- |
226  | startupTask | string | 是 | 启动任务实现[StartupTask](./js-apis-app-appstartup-startupTask.md)接口的文件名或so文件名，所有启动任务都需要实现[StartupTask](./js-apis-app-appstartup-startupTask.md)接口的方法。 |
227
228**返回值：**
229
230  | 类型 | 说明 |
231  | -------- | -------- |
232  | Object | 输入为启动任务名时，返回指定的启动任务结果。<br/> 输入为so文件名时，返回undefined。 |
233
234**错误码：**
235
236以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
237
238  | 错误码ID | 错误信息 |
239  | ------- | -------------------------------- |
240  | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
241
242**示例：**
243
244```ts
245import { AbilityConstant, UIAbility, Want, startupManager } from '@kit.AbilityKit';
246import { window } from '@kit.ArkUI';
247import { hilog } from '@kit.PerformanceAnalysisKit';
248import { BusinessError } from '@kit.BasicServicesKit';
249
250export default class EntryAbility extends UIAbility {
251  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
252    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
253    try {
254      startupManager.run(['StartupTask_001']).then(() => {
255        hilog.info(0x0000, 'testTag', 'StartupTask_001 init successful');
256      }).catch((error: BusinessError) => {
257        hilog.error(0x0000, 'testTag', `StartupTask_001 promise catch failed, error: %{public}s`,
258          JSON.stringify(error) ?? '');
259      });
260    } catch (error) {
261      hilog.error(0x0000, 'testTag', `StartupTask_001.run failed, error: %{public}s`, JSON.stringify(error) ?? '');
262    }
263  }
264
265  onWindowStageCreate(windowStage: window.WindowStage) {
266    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
267    let result = startupManager.getStartupTaskResult('StartupTask_001'); // 手动获取启动任务结果
268    hilog.info(0x0000, 'testTag', 'getStartupTaskResult result = %{public}s', result);
269    windowStage.loadContent('pages/Index', (err, data) => {
270      if (err.code) {
271        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
272        return;
273      }
274      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
275    });
276  }
277}
278```
279
280
281## startupManager.isStartupTaskInitialized
282
283isStartupTaskInitialized(startupTask: string): boolean
284
285获取指定启动任务或so预加载任务是否已初始化。
286
287**系统能力**：SystemCapability.Ability.AppStartup
288
289**参数：**
290
291  | 参数名 | 类型 | 必填 | 说明 |
292  | -------- | -------- | -------- | -------- |
293  | startupTask | string | 是 | 启动任务实现[StartupTask](js-apis-app-appstartup-startupTask.md)接口的类名称或so文件名称。 |
294
295**返回值：**
296
297  | 类型 | 说明 |
298  | -------- | -------- |
299  | boolean | 返回布尔值，true表示该启动任务或so预加载任务已执行完成，false表示该启动任务或so预加载任务尚未执行完成。 |
300
301**错误码：**
302
303以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
304
305  | 错误码ID | 错误信息 |
306  | ------- | -------------------------------- |
307  | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
308
309**示例：**
310
311```ts
312import { AbilityConstant, UIAbility, Want, startupManager } from '@kit.AbilityKit';
313import { window } from '@kit.ArkUI';
314import { hilog } from '@kit.PerformanceAnalysisKit';
315import { BusinessError } from '@kit.BasicServicesKit';
316
317export default class EntryAbility extends UIAbility {
318  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
319    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
320    try {
321      startupManager.run(['StartupTask_001', 'libentry_001']).then(() => {
322      hilog.info(0x0000, 'testTag', 'StartupTask_001 init successful');
323      }).catch((error: BusinessError) => {
324        hilog.error(0x0000, 'testTag', `StartupTask_001 promise catch failed, error: %{public}s`,
325          JSON.stringify(error) ?? '');
326      });
327    } catch (error) {
328      hilog.error(0x0000, 'testTag', `StartupTask_001.run failed, error: %{public}s`, JSON.stringify(error) ?? '');
329    }
330  }
331
332  onWindowStageCreate(windowStage: window.WindowStage) {
333    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
334    let result1 = startupManager.isStartupTaskInitialized('StartupTask_001');
335    let result2 = startupManager.isStartupTaskInitialized('libentry_001');
336    if (result1) {
337      console.info('StartupTask_001 init successful');
338    } else {
339      console.info('StartupTask_001 uninitialized');
340    }
341    if (result2) {
342      console.info('libentry_001 init successful');
343    } else {
344      console.info('libentry_001 uninitialized');
345    }
346
347    windowStage.loadContent('pages/Index', (err, data) => {
348      if (err.code) {
349        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
350        return;
351      }
352      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
353    });
354  }
355}
356```
357
358## startupManager.removeStartupTaskResult
359
360removeStartupTaskResult(startupTask: string): void
361
362删除指定启动任务或so预加载任务的初始化结果。
363
364- 输入为启动任务名时，删除指定启动任务的初始化结果。
365
366- 输入为so文件时，将该so文件置为未加载，缓存中已加载的so文件不会被移除。
367
368**系统能力**：SystemCapability.Ability.AppStartup
369
370**参数：**
371
372  | 参数名 | 类型 | 必填 | 说明 |
373  | -------- | -------- | -------- | -------- |
374  | startupTask | string | 是 | 启动任务所实现[StartupTask](js-apis-app-appstartup-startupTask.md)接口的类名称或so文件名。 |
375
376**错误码：**
377
378以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
379
380  | 错误码ID | 错误信息 |
381  | ------- | -------------------------------- |
382  | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
383
384**示例：**
385
386```ts
387import { AbilityConstant, UIAbility, Want, startupManager } from '@kit.AbilityKit';
388import { window } from '@kit.ArkUI';
389import { hilog } from '@kit.PerformanceAnalysisKit';
390import { BusinessError } from '@kit.BasicServicesKit';
391
392export default class EntryAbility extends UIAbility {
393  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
394    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
395    try{
396      startupManager.run(['StartupTask_001', 'libentry_001']).then(() => {
397        hilog.info(0x0000, 'testTag', 'StartupTask_001 init successful');
398      }).catch((error: BusinessError) => {
399        hilog.error(0x0000, 'testTag', `StartupTask_001 promise catch failed, error: %{public}s`,
400          JSON.stringify(error) ?? '');
401      });
402    } catch (error) {
403      hilog.error(0x0000, 'testTag', `StartupTask_001.run failed, error: %{public}s`, JSON.stringify(error) ?? '');
404    }
405  }
406
407  onWindowStageCreate(windowStage: window.WindowStage) {
408    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
409    startupManager.removeStartupTaskResult('StartupTask_001');
410    startupManager.removeStartupTaskResult('libentry_001');
411
412    windowStage.loadContent('pages/Index', (err, data) => {
413      if (err.code) {
414        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
415        return;
416      }
417      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
418    });
419  }
420}
421```