1# 应用启动框架AppStartup
2
3
4## 概述
5
6应用启动时通常需要执行一系列初始化启动任务，如果将启动任务都放在应用主模块（即entry类型的[Module](../quick-start/application-package-overview.md#module类型)）的[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)组件的[onCreate](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate)生命周期中，那么只能在主线程中依次执行，不但影响应用的启动速度，而且当启动任务过多时，任务之间复杂的依赖关系还会使得代码难以维护。
7
8AppStartup提供了一种简单高效的应用启动方式，可以支持任务的异步启动，加快应用启动速度。同时，通过在一个配置文件中统一设置多个启动任务的执行顺序以及依赖关系，让执行启动任务的代码变得更加简洁清晰、容易维护。
9
10启动框架支持以自动模式或手动模式执行启动任务，默认采用自动模式。在构造[AbilityStage组件容器](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md)过程中开始加载开发者配置的启动任务，并执行自动模式的启动任务。开发者也可以在UIAbility创建完后调用[startupManager.run](../reference/apis-ability-kit/js-apis-app-appstartup-startupManager.md#startupmanagerrun)方法，执行手动模式的启动任务。
11
12  **图1** 启动框架执行时机
13  ![app-startup-procedure](figures/app-startup-procedure.png)
14
15## 约束限制
16
17- 启动框架只支持在entry类型的[Module](../quick-start/application-package-overview.md#module类型)下的UIAbility中使用。
18
19- 启动任务之间不允许存在循环依赖。
20
21## 开发流程
22
231. [定义启动框架配置文件](#定义启动框架配置文件)：在资源文件目录下创建启动框架配置文件、添加启动任务的配置信息，并在[module.json5](../quick-start/module-configuration-file.md)配置文件中引用。
242. [设置启动参数](#设置启动参数)：在启动参数文件中，设置超时时间和启动任务的监听器等参数。
253. [为每个待初始化组件添加启动任务](#为每个待初始化组件添加启动任务)：通过实现[StartupTask](../reference/apis-ability-kit/js-apis-app-appstartup-startupTask.md)接口，启动框架将会按顺序执行初始化流程。
26
27## 开发步骤
28
29### 定义启动框架配置文件
30
311. 在应用主模块（即entry类型的[Module](../quick-start/application-package-overview.md#module类型)）的“resources/base/profile”路径下，新建启动框架配置文件。文件名可以自定义，本文以"startup_config.json"为例。
32
332. 在启动框架配置文件startup_config.json中，依次添加各个启动任务的配置信息。
34
35    假设当前应用启动框架共包含6个启动任务，任务之间的依赖关系如下图所示。为了便于并发执行启动任务，单个启动任务文件包含的启动任务应尽量单一，本例中每个启动任务对应一个启动任务文件。
36
37    **图2** 启动任务依赖关系图
38    ![app-startup](figures/app-startup.png)
39
40    1. 在“ets/startup”路径下，依次创建6个启动任务文件、以及一个公共的启动参数配置文件。文件名称必须确保唯一性。
41
42        1. 创建启动任务文件。本例中的6个文件名分别为StartupTask_001.ets~StartupTask_006.ets。
43        2. 创建启动任务参数配置文件。本例中的文件名为StartupConfig.ets。
44
45    2. 在启动框架配置文件startup_config.json中，添加所有启动任务以及启动参数配置文件的相关信息。
46
47        startup_config.json文件示例如下：
48
49        ```json
50        {
51          "startupTasks": [
52            {
53              "name": "StartupTask_001",
54              "srcEntry": "./ets/startup/StartupTask_001.ets",
55              "dependencies": [
56                "StartupTask_002",
57                "StartupTask_003"
58              ],
59              "runOnThread": "taskPool",
60              "waitOnMainThread": false
61            },
62            {
63              "name": "StartupTask_002",
64              "srcEntry": "./ets/startup/StartupTask_002.ets",
65              "dependencies": [
66                "StartupTask_004"
67              ],
68              "runOnThread": "taskPool",
69              "waitOnMainThread": false
70            },
71            {
72              "name": "StartupTask_003",
73              "srcEntry": "./ets/startup/StartupTask_003.ets",
74              "dependencies": [
75                "StartupTask_004"
76              ],
77              "runOnThread": "taskPool",
78              "waitOnMainThread": false
79            },
80            {
81              "name": "StartupTask_004",
82              "srcEntry": "./ets/startup/StartupTask_004.ets",
83              "runOnThread": "taskPool",
84              "waitOnMainThread": false
85            },
86            {
87              "name": "StartupTask_005",
88              "srcEntry": "./ets/startup/StartupTask_005.ets",
89              "dependencies": [
90                "StartupTask_006"
91              ],
92              "runOnThread": "mainThread",
93              "waitOnMainThread": true,
94              "excludeFromAutoStart": true
95            },
96            {
97              "name": "StartupTask_006",
98              "srcEntry": "./ets/startup/StartupTask_006.ets",
99              "runOnThread": "mainThread",
100              "waitOnMainThread": false,
101              "excludeFromAutoStart": true
102            }
103          ],
104          "configEntry": "./ets/startup/StartupConfig.ets"
105        }
106        ```
107
108        **表1** startup_config.json配置文件标签说明
109
110        | 属性名称 | 含义 | 数据类型 | 是否可缺省 |
111        | -------- | -------- | -------- | -------- |
112        | startupTasks | 启动任务配置信息，标签说明详见下表。 | 对象数组 | 该标签不可缺省。 |
113        | configEntry | 启动参数配置文件所在路径。 | 字符串 | 该标签不可缺省。 |
114
115
116        **表2** startupTasks标签说明
117
118        | 属性名称 | 含义 | 数据类型 | 是否可缺省 |
119        | -------- | -------- | -------- | -------- |
120        | name | 启动任务对应的类名。 | 字符串 | 该标签不可缺省。 |
121        | srcEntry | 启动任务对应的文件路径。 | 字符串 | 该标签不可缺省。 |
122        | dependencies | 启动任务依赖的其他启动任务的类名数组。 | 对象数组 | 该标签可缺省，缺省值为空。 |
123        | excludeFromAutoStart | 是否排除自动模式，详细介绍可以查看[修改启动模式](#可选修改启动模式)。 <br/>-&nbsp;true：手动模式。 <br/>-&nbsp;false：自动模式。 | 布尔值 | 该标签可缺省，缺省值为false。 |
124        | runOnThread | 执行初始化所在的线程。<br/>-&nbsp;`mainThread`：在主线程中执行。<br/>-&nbsp;`taskPool`：在异步线程中执行。 | 字符串 | 该标签可缺省，缺省值为`mainThread`。 |
125        | waitOnMainThread | 主线程是否需要等待启动框架执行。当runOnThread取值为`taskPool`时，该字段生效。 <br/>-&nbsp;true：主线程等待启动框架执行完之后，才会加载应用首页。 <br/>-&nbsp;false：主线程不等待启动任务执行。 | 布尔值 | 该标签可缺省，缺省值为true。 |
126
127
128      3. 在[module.json5配置文件](../quick-start/module-configuration-file.md)的appStartup标签中，添加启动框架配置文件的索引。
129
130          module.json5示例代码如下。
131
132          ```json
133          {
134            "module": {
135              "name": "entry",
136              "type": "entry",
137              // ...
138              "appStartup": "$profile:startup_config", // 启动框架的配置文件
139              // ...
140            }
141          }
142          ```
143
144### 设置启动参数
145
146在启动参数配置文件（本文为“ets/startup/StartupConfig.ets”文件）中，使用[StartupConfigEntry](../reference/apis-ability-kit/js-apis-app-appstartup-startupConfigEntry.md)接口实现启动框架公共参数的配置，包括超时时间和启动任务的监听器等参数，其中需要用到如下接口：
147
148- [StartupConfig](../reference/apis-ability-kit/js-apis-app-appstartup-startupConfig.md)：用于设置任务超时时间和启动框架的监听器。
149- [StartupListener](../reference/apis-ability-kit/js-apis-app-appstartup-startupListener.md)：用于监听启动任务是否执行成功。
150
151
152
153```ts
154import { StartupConfig, StartupConfigEntry, StartupListener } from '@kit.AbilityKit';
155import { hilog } from '@kit.PerformanceAnalysisKit';
156import { BusinessError } from '@kit.BasicServicesKit';
157
158export default class MyStartupConfigEntry extends StartupConfigEntry {
159  onConfig() {
160    hilog.info(0x0000, 'testTag', `onConfig`);
161    let onCompletedCallback = (error: BusinessError<void>) => {
162      hilog.info(0x0000, 'testTag', `onCompletedCallback`);
163      if (error) {
164        hilog.info(0x0000, 'testTag', 'onCompletedCallback: %{public}d, message: %{public}s', error.code, error.message);
165      } else {
166        hilog.info(0x0000, 'testTag', `onCompletedCallback: success.`);
167      }
168    };
169    let startupListener: StartupListener = {
170      'onCompleted': onCompletedCallback
171    };
172    let config: StartupConfig = {
173      'timeoutMs': 10000,
174      'startupListener': startupListener
175    };
176    return config;
177  }
178}
179```
180
181### 为每个待初始化组件添加启动任务
182
183上述操作中已完成启动框架配置文件、启动参数的配置，还需要在每个组件对应的启动任务文件中，通过实现[StartupTask](../reference/apis-ability-kit/js-apis-app-appstartup-startupTask.md)来添加启动任务。其中，需要用到下面的两个方法：
184
185- [init](../reference/apis-ability-kit/js-apis-app-appstartup-startupTask.md#startuptaskinit)：启动任务初始化。当该任务依赖的启动任务全部执行完毕，即onDependencyCompleted完成调用后，才会执行init方法对该任务进行初始化。
186- [onDependencyCompleted](../reference/apis-ability-kit/js-apis-app-appstartup-startupTask.md#startuptaskondependencycompleted)：当前任务依赖的启动任务执行完成时，调用该方法。
187
188
189下面以[startup_config.json](#定义启动框架配置文件)中的StartupTask_001.ets文件为例，示例代码如下。开发者需要分别为每个待初始化组件添加启动任务。
190
191> **说明：**
192>
193> 由于StartupTask采用了[Sendable协议](../arkts-utils/arkts-sendable.md#sendable协议)，在继承该接口时，必须添加Sendable注解。
194
195```ts
196import { StartupTask, common } from '@kit.AbilityKit';
197import { hilog } from '@kit.PerformanceAnalysisKit';
198
199@Sendable
200export default class StartupTask_001 extends StartupTask {
201  constructor() {
202    super();
203  }
204
205  async init(context: common.AbilityStageContext) {
206    hilog.info(0x0000, 'testTag', 'StartupTask_001 init.');
207    return 'StartupTask_001';
208  }
209
210  onDependencyCompleted(dependence: string, result: Object): void {
211    hilog.info(0x0000, 'testTag', 'StartupTask_001 onDependencyCompleted, dependence: %{public}s, result: %{public}s',
212      dependence, JSON.stringify(result));
213  }
214}
215```
216
217### （可选）修改启动模式
218
219AppStartup分别提供了自动和手动两种方式来执行启动任务，默认采用自动模式。开发者可以根据需要修改为手动模式。
220
221- 自动模式：当AbilityStage组件容器完成创建后，自动执行启动任务。
222- 手动模式：在UIAbility完成创建后手动调用，来执行启动任务。对于某些使用频率不高的模块，不需要应用最开始启动时就进行初始化。开发者可以选择将该部分启动任务修改为手动模式，在应用启动完成后调用[startupManager.run](../reference/apis-ability-kit/js-apis-app-appstartup-startupManager.md#startupmanagerrun)方法来执行启动任务。
223
224下面以UIAbility的onCreate生命周期中为例，介绍如何采用手动模式来启动任务，示例代码如下。
225
226```ts
227import { AbilityConstant, UIAbility, Want, startupManager } from '@kit.AbilityKit';
228import { hilog } from '@kit.PerformanceAnalysisKit';
229import { BusinessError } from '@kit.BasicServicesKit';
230
231export default class EntryAbility extends UIAbility {
232  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
233    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
234    let startParams = ['StartupTask_005', 'StartupTask_006'];
235    try {
236      startupManager.run(startParams).then(() => {
237        console.log('StartupTest startupManager run then, startParams = ');
238      }).catch((error: BusinessError) => {
239        console.info("StartupTest promise catch error, error = " + JSON.stringify(error));
240        console.info("StartupTest promise catch error, startParams = "
241          + JSON.stringify(startParams));
242      })
243    } catch (error) {
244      let errMsg = JSON.stringify(error);
245      let errCode: number = error.code;
246      console.log('Startup catch error , errCode= ' + errCode);
247      console.log('Startup catch error ,error= ' + errMsg);
248    }
249  }
250
251  // ...
252}
253```
254
255开发者还可以在页面加载完成后，在页面中调用启动框架手动模式，示例代码如下。
256
257```ts
258import { startupManager } from '@kit.AbilityKit';
259
260@Entry
261@Component
262struct Index {
263  @State message: string = '手动模式';
264  @State startParams: Array<string> = ['StartupTask_006'];
265
266  build() {
267    RelativeContainer() {
268      Button(this.message)
269        .id('AppStartup')
270        .fontSize(20)
271        .fontWeight(FontWeight.Bold)
272        .onClick(() => {
273          if (!startupManager.isStartupTaskInitialized("StartupTask_006")) { // 判断是否已经完成初始化
274            startupManager.run(this.startParams)
275          }
276        })
277        .alignRules({
278          center: {anchor: '__container__', align: VerticalAlign.Center},
279          middle: {anchor: '__container__', align: HorizontalAlign.Center}
280        })
281    }
282    .height('100%')
283    .width('100%')
284  }
285}
286```
287