1# UIAbility Launch Type
2
3
4The launch type of the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) component refers to the state of the UIAbility instance at startup. Three launch types are available:
5
6
7- [Singleton](#singleton)
8
9- [Multiton](#multiton)
10
11- [Specified](#specified)
12
13> **NOTE**
14>
15> standard is the former name of multiton and provides the same effect as the multiton mode.
16
17## Singleton
18
19singleton is the default launch type.
20
21Each time [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, if a [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance of this type already exists in the application process, the instance is reused. In other words, UIAbility of this type can have only one instance in the system, meaning that only one mission is displayed in the system application Recents.
22
23**Figure 1** Demonstration effect in singleton mode
24
25![uiability-launch-type1](figures/uiability-launch-type1.gif)
26
27> **NOTE**
28>
29> If [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called to start an existing UIAbility instance in singleton mode, that instance is started, and no new UIAbility instance is created. In this case, the [onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant) callback is invoked, but the [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) and [onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) callbacks are not. If **startAbility()** is called to start an instance that is being started, error code 16000082 will be returned.
30
31To use the singleton mode, set **launchType** in the [module.json5 file](../quick-start/module-configuration-file.md) to **singleton**.
32
33
34```json
35{
36  "module": {
37    // ...
38    "abilities": [
39      {
40        "launchType": "singleton",
41        // ...
42      }
43    ]
44  }
45}
46```
47
48
49## Multiton
50
51In multiton mode, each time [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, a new [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance is created in the application process. Multiple missions are displayed for UIAbility of this type in Recents.
52
53**Figure 2** Demonstration effect in multiton mode
54
55![uiability-launch-type2](figures/uiability-launch-type2.gif)
56
57To use the multiton mode, set **launchType** in the [module.json5 file](../quick-start/module-configuration-file.md) to **multiton**.
58
59
60```json
61{
62  "module": {
63    // ...
64    "abilities": [
65      {
66        "launchType": "multiton",
67        // ...
68      }
69    ]
70  }
71}
72```
73
74
75## Specified
76
77The specified mode is used in some special scenarios. For example, in a document application, you may want a document instance to be created each time you create a document, and you may also want to use the same document instance when you open an existing document.
78
79**Figure 3** Principle in specified mode
80
81![uiability-launch-type3-principle](figures/uiability-launch-type3-principle.png)
82
83This section assumes that an application has two [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instances: EntryAbility and SpecifiedAbility, and EntryAbility will start SpecifiedAbility in specified mode. The basic principle is as follows:
84
85  1. EntryAbility calls [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) and sets a unique key in the **parameters** field of [Want](../reference/apis-ability-kit/js-apis-app-ability-want.md) to identify SpecifiedAbility.
86  2. Before starting SpecifiedAbility, the system invokes the [onAcceptWant()](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) lifecycle callback of the corresponding [AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md) to obtain the key that identifies the target UIAbility.
87  3. The system matches the UIAbility based on the key obtained.
88      * If a UIAbility instance is matched, that UIAbility instance is started, and its [onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant) lifecycle callback is invoked.
89      * If no UIAbility instance is matched, a new UIAbility instance is created, and its [onCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityoncreate) and [onWindowStageCreate()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) lifecycle callbacks are invoked.
90
91**Figure 4** Demonstration effect in specified mode
92
93![uiability-launch-type3](figures/uiability-launch-type3.gif)
94
951. In SpecifiedAbility, set **launchType** in the [module.json5 file](../quick-start/module-configuration-file.md) to **specified**.
96
97   ```json
98   {
99     "module": {
100       // ...
101       "abilities": [
102         {
103           "launchType": "specified",
104           // ...
105         }
106       ]
107     }
108   }
109   ```
110
1112. In EntryAbility, pass the custom parameter **instanceKey** as the unique identifier into the [want](../reference/apis-ability-kit/js-apis-app-ability-want.md) parameter in [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to specify the target UIAbility instance. In the example, **instanceKey** is set to **'KEY'**.
112
113   ```ts
114    // Configure a unique key for each UIAbility instance.
115    // For example, in the document usage scenario, use the document path as the key.
116    import { common, Want } from '@kit.AbilityKit';
117    import { hilog } from '@kit.PerformanceAnalysisKit';
118    import { BusinessError } from '@kit.BasicServicesKit';
119
120    const TAG: string = '[Page_StartModel]';
121    const DOMAIN_NUMBER: number = 0xFF00;
122
123    function getInstance(): string {
124      return 'KEY';
125    }
126
127    @Entry
128    @Component
129    struct Page_StartModel {
130      private KEY_NEW = 'KEY';
131
132      build() {
133        Row() {
134          Column() {
135            // ...
136            Button()
137              .onClick(() => {
138                let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
139                // context is the UIAbilityContext of the initiator UIAbility.
140                let want: Want = {
141                  deviceId: '', // An empty deviceId indicates the local device.
142                  bundleName: 'com.samples.stagemodelabilitydevelop',
143                  abilityName: 'SpecifiedFirstAbility',
144                  moduleName: 'entry', // moduleName is optional.
145                  parameters: {
146                    // Custom information.
147                    instanceKey: this.KEY_NEW
148                  }
149                };
150                context.startAbility(want).then(() => {
151                  hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting SpecifiedAbility.');
152                }).catch((err: BusinessError) => {
153                  hilog.error(DOMAIN_NUMBER, TAG, `Failed to start SpecifiedAbility. Code is ${err.code}, message is ${err.message}`);
154                })
155                this.KEY_NEW = this.KEY_NEW + 'a';
156              })
157            // ...
158            Button()
159              .onClick(() => {
160                let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
161                // context is the UIAbilityContext of the initiator UIAbility.
162                let want: Want = {
163                  deviceId: '', // An empty deviceId indicates the local device.
164                  bundleName: 'com.samples.stagemodelabilitydevelop',
165                  abilityName: 'SpecifiedSecondAbility',
166                  moduleName: 'entry', // moduleName is optional.
167                  parameters: {
168                    // Custom information.
169                    instanceKey: getInstance()
170                  }
171                };
172                context.startAbility(want).then(() => {
173                  hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting SpecifiedAbility.');
174                }).catch((err: BusinessError) => {
175                  hilog.error(DOMAIN_NUMBER, TAG, `Failed to start SpecifiedAbility. Code is ${err.code}, message is ${err.message}`);
176                })
177                this.KEY_NEW = this.KEY_NEW + 'a';
178              })
179            // ...
180          }
181          .width('100%')
182        }
183        .height('100%')
184      }
185    }
186   ```
187
1883. Set the UIAbility identifier based on the [onAcceptWant()](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) lifecycle callback of SpecifiedAbility. In the example, the identifier is set to **SpecifiedAbilityInstance_KEY**.
189
190   ```ts
191    import { AbilityStage, Want } from '@kit.AbilityKit';
192
193    export default class MyAbilityStage extends AbilityStage {
194      onAcceptWant(want: Want): string {
195        // In the AbilityStage instance of the callee, a key string corresponding to a UIAbility instance is returned for UIAbility whose launch type is specified.
196        // In this example, SpecifiedAbility of module1 is returned.
197        if (want.abilityName === 'SpecifiedFirstAbility' || want.abilityName === 'SpecifiedSecondAbility') {
198          // The returned KEY string is a custom string.
199          if (want.parameters) {
200            return `SpecifiedAbilityInstance_${want.parameters.instanceKey}`;
201          }
202        }
203        // ...
204        return 'MyAbilityStage';
205      }
206    }
207   ```
208
209   > **NOTE**
210   >
211   > - If [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called to start an existing UIAbility instance in specified mode, and the [onAcceptWant()](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback of [AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md) matches that UIAbility instance, that instance is started, and no new UIAbility instance is created. In this case, the **onNewWant()** callback is invoked, but the **onCreate()** and **onWindowStageCreate()** callbacks are not.
212   > - AbilityStage is not automatically generated by default in the project of DevEco Studio. For details about how to create an AbilityStage file, see [AbilityStage Component Container](abilitystage.md).
213
214For example, in the document application, different keys are bound to different document instances. Each time a document is created, a new key (for example, file path) is passed in, and a new [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) instance is created when the UIAbility is started in [AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md). However, when an existing document is opened, the same UIAbility instance is started again in AbilityStage.
215
216The following steps are used as an example.
217
218   1. Open file A. A UIAbility instance, UIAbility instance 1, is started.
219   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, UIAbility instance 2, is started.
220   3. Return to the home screen and open file B. A new UIAbility instance, UIAbility instance 3, is started.
221   4. Return to the home screen and open file A again. UIAbility instance 2 is started. This is because the system automatically matches the key with the UIAbility instance and starts the UIAbility instance that has a matching key. In this example, UIAbility instance 2 has the same key as file A. Therefore, the system pulls back UIAbility instance 2 and focuses it without creating a new instance.
222