• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# UIAbility Component Launch Type
2
3
4The launch type of the UIAbility component refers to the state of the UIAbility instance at startup. The system provides three launch types:
5
6
7- [Singleton](#singleton)
8
9- [Standard](#standard)
10
11- [Specified](#specified)
12
13
14## Singleton
15
16**singleton** is the default launch type.
17
18Each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, if a UIAbility instance of this type already exists in the application process, the instance is reused. Therefore, only one UIAbility instance of this type exists in the system, that is, displayed in **Recents**.
19
20**Figure 1** Demonstration effect in singleton mode
21
22![uiability-launch-type1](figures/uiability-launch-type1.png)
23
24> **NOTE**
25>
26> Assume that the application already has a UIAbility instance created, and the launch type of the UIAbility instance is set to **singleton**. If [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called again to start the UIAbility instance, the original UIAbility instance is started, and no new UIAbility instance is created. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback is invoked, but the [onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate) and [onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) callbacks are not.
27
28To use the singleton mode, set **launchType** in the [module.json5 configuration file](../quick-start/module-configuration-file.md) to **singleton**.
29
30
31```json
32{
33  "module": {
34    // ...
35    "abilities": [
36      {
37        "launchType": "singleton",
38        // ...
39      }
40    ]
41  }
42}
43```
44
45
46## Standard
47
48In standard mode, each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, a new UIAbility instance of this type is created in the application process. Multiple UIAbility instances of this type are displayed in **Recents**.
49
50**Figure 2** Demonstration effect in standard mode
51
52![standard-mode](figures/standard-mode.png)
53
54To use the standard mode, set **launchType** in the [module.json5 configuration file](../quick-start/module-configuration-file.md) to **standard**.
55
56
57```json
58{
59  "module": {
60    // ...
61    "abilities": [
62      {
63        "launchType": "standard",
64        // ...
65      }
66    ]
67  }
68}
69```
70
71
72## Specified
73
74The **specified** mode is used in some special scenarios. For example, in a document application, you want a document instance to be created each time you create a document, but you want to use the same document instance when you repeatedly open an existing document.
75
76**Figure 3** Demonstration effect in specified mode
77
78![uiability-launch-type2](figures/uiability-launch-type2.png)
79
80For example, there are EntryAbility and SpecifiedAbility, and the launch type of SpecifiedAbility is set to **specified**. You are required to start SpecifiedAbility from EntryAbility.
81
821. In SpecifiedAbility, set the **launchType** field in the [module.json5 configuration file](../quick-start/module-configuration-file.md) to **specified**.
83
84   ```json
85   {
86     "module": {
87       // ...
88       "abilities": [
89         {
90           "launchType": "specified",
91           // ...
92         }
93       ]
94     }
95   }
96   ```
97
982. Before a UIAbility instance is created, you can create a unique string key for the instance. The key is bound to the UIAbility instance when it is created. Each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, the application is asked which UIAbility instance is used to respond to the [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) request.
99   In EntryAbility, add a custom parameter, for example, **instanceKey**, to the [want](want-overview.md) parameter in [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to distinguish the UIAbility instances.
100
101   ```ts
102   // Configure an independent key for each UIAbility instance.
103   // For example, in the document usage scenario, use the document path as the key.
104   function getInstance() {
105       // ...
106   }
107
108   let want = {
109       deviceId: '', // An empty deviceId indicates the local device.
110       bundleName: 'com.example.myapplication',
111       abilityName: 'SpecifiedAbility',
112       moduleName: 'module1', // moduleName is optional.
113       parameters: {// Custom information.
114           instanceKey: getInstance(),
115       },
116   }
117   // context is the ability-level context of the initiator UIAbility.
118   this.context.startAbility(want).then(() => {
119       // ...
120   }).catch((err) => {
121       // ...
122   })
123   ```
124
1253. During running, the internal service of UIAbility determines whether to create multiple instances. If the key is matched, the UIAbility instance bound to the key is started. Otherwise, a new UIAbility instance is created.
126   The launch type of SpecifiedAbility is set to **specified**. Before SpecifiedAbility is started, the [onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback of the corresponding AbilityStage instance is invoked to parse the input **want** parameter and obtain the custom parameter **instanceKey**. A string key identifier is returned through the [onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback of the AbilityStage instance. [If the returned key corresponds to a started UIAbility instance](mission-management-launch-type.md#fig14520125175314), that UIAbility instance is switched to the foreground and gains focus again. Otherwise, a new instance is created and started.
127
128   ```ts
129   import AbilityStage from '@ohos.app.ability.AbilityStage';
130
131   export default class MyAbilityStage extends AbilityStage {
132       onAcceptWant(want): string {
133           // In the AbilityStage instance of the callee, a key value corresponding to a UIAbility instance is returned for UIAbility whose launch type is specified.
134           // In this example, SpecifiedAbility of module1 is returned.
135           if (want.abilityName === 'SpecifiedAbility') {
136               // The returned string key is a custom string.
137               return `SpecifiedAbilityInstance_${want.parameters.instanceKey}`;
138           }
139
140           return '';
141       }
142   }
143   ```
144
145   > **NOTE**
146   >
147   > 1. Assume that the application already has a UIAbility instance created, and the launch type of the UIAbility instance is set to **specified**. If [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called again to start the UIAbility instance, and the [onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback of [AbilityStage](../reference/apis/js-apis-app-ability-abilityStage.md) matches a created UIAbility instance, the original UIAbility instance is started, and no new UIAbility instance is created. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback is invoked, but the [onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate) and [onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) callbacks are not.
148   > 2. AbilityStage is not automatically generated in the default project of DevEco Studio. For details about how to create an AbilityStage file, see [AbilityStage Component Container](abilitystage.md).
149
150   For example, in the document application, different key values are bound to different document instances. Each time a document is created, a new key value (for example, file path) is passed, and a new UIAbility instance is created when UIAbility is started in AbilityStage. However, when you open an existing document, the same UIAbility instance is started again in AbilityStage.
151
152
153The following steps are used as an example.
154   1. Open file A. A UIAbility instance, for example, UIAbility instance 1, is started.
155
156   2. Close the process of file A in **Recents**. UIAbility instance 1 is destroyed. Return to the home screen and open file A again. A new UIAbility instance is started, for example, UIAbility instance 2.
157
158   3. Return to the home screen and open file B. A new UIAbility instance is started, for example, UIAbility instance 3.
159
160   4. Return to the home screen and open file A again. UIAbility instance 2 is started.
161
162