• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
19**singleton** 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.
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** Demonstration effect in specified mode
80
81![uiability-launch-type3](figures/uiability-launch-type3.gif)
82
83In the following example, there are two [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) components: EntryAbility and SpecifiedAbility (with the launch type **specified**). To start SpecifiedAbility from EntryAbility, proceed as follows:
84
851. In SpecifiedAbility, set **launchType** in the [module.json5 file](../quick-start/module-configuration-file.md) to **specified**.
86
87   ```json
88   {
89     "module": {
90       // ...
91       "abilities": [
92         {
93           "launchType": "specified",
94           // ...
95         }
96       ]
97     }
98   }
99   ```
100
1012. Create a unique string key for the SpecifiedAbility instance. Each time [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, the application, based on the key, identifies the UIAbility instance used to respond to the request. In EntryAbility, add a custom parameter, for example, **instanceKey**, to 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 distinguish the UIAbility instances.
102
103   ```ts
104    // Configure a unique key for each UIAbility instance.
105    // For example, in the document usage scenario, use the document path as the key.
106    import { common, Want } from '@kit.AbilityKit';
107    import { hilog } from '@kit.PerformanceAnalysisKit';
108    import { BusinessError } from '@kit.BasicServicesKit';
109
110    const TAG: string = '[Page_StartModel]';
111    const DOMAIN_NUMBER: number = 0xFF00;
112
113    function getInstance(): string {
114      return 'KEY';
115    }
116
117    @Entry
118    @Component
119    struct Page_StartModel {
120      private KEY_NEW = 'KEY';
121
122      build() {
123        Row() {
124          Column() {
125            // ...
126            Button()// ...
127              .onClick(() => {
128                let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
129                // context is the UIAbilityContext of the initiator UIAbility.
130                let want: Want = {
131                  deviceId: '', // An empty deviceId indicates the local device.
132                  bundleName: 'com.samples.stagemodelabilitydevelop',
133                  abilityName: 'SpecifiedFirstAbility',
134                  moduleName: 'entry', // moduleName is optional.
135                  parameters: {
136                    // Custom information.
137                    instanceKey: this.KEY_NEW
138                  }
139                };
140                context.startAbility(want).then(() => {
141                  hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting SpecifiedAbility.');
142                }).catch((err: BusinessError) => {
143                  hilog.error(DOMAIN_NUMBER, TAG, `Failed to start SpecifiedAbility. Code is ${err.code}, message is ${err.message}`);
144                })
145                this.KEY_NEW = this.KEY_NEW + 'a';
146              })
147            // ...
148            Button()// ...
149              .onClick(() => {
150                let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
151                // context is the UIAbilityContext of the initiator UIAbility.
152                let want: Want = {
153                  deviceId: '', // An empty deviceId indicates the local device.
154                  bundleName: 'com.samples.stagemodelabilitydevelop',
155                  abilityName: 'SpecifiedSecondAbility',
156                  moduleName: 'entry', // moduleName is optional.
157                  parameters: {
158                    // Custom information.
159                    instanceKey: getInstance()
160                  }
161                };
162                context.startAbility(want).then(() => {
163                  hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting SpecifiedAbility.');
164                }).catch((err: BusinessError) => {
165                  hilog.error(DOMAIN_NUMBER, TAG, `Failed to start SpecifiedAbility. Code is ${err.code}, message is ${err.message}`);
166                })
167                this.KEY_NEW = this.KEY_NEW + 'a';
168              })
169            // ...
170          }
171          .width('100%')
172        }
173        .height('100%')
174      }
175    }
176   ```
177
1783. Before SpecifiedAbility is started, the [onAcceptWant()](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback of the corresponding AbilityStage instance is invoked to obtain the key of the target [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md). If a UIAbility instance matching the key exists, the system starts the UIAbility instance and invokes its [onNewWant()](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonnewwant) callback. Otherwise, the system creates a new UIAbility instance and invokes 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) callbacks.
179
180   In the sample code, the [onAcceptWant()](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback uses the passed [want](../reference/apis-ability-kit/js-apis-app-ability-want.md) parameter to obtain the custom parameter **instanceKey**. The service logic returns a key string based on the **instanceKey** parameter to identify the UIAbility instance. If the returned key maps to a started UIAbility instance, the system pulls the UIAbility instance back to the foreground and gives it the focus. If the returned key does not map to a started UIAbility instance, the system creates a new UIAbility instance and starts it.
181
182   ```ts
183    import { AbilityStage, Want } from '@kit.AbilityKit';
184
185    export default class MyAbilityStage extends AbilityStage {
186      onAcceptWant(want: Want): string {
187        // In the AbilityStage instance of the callee, a key string corresponding to a UIAbility instance is returned for UIAbility whose launch type is specified.
188        // In this example, SpecifiedAbility of module1 is returned.
189        if (want.abilityName === 'SpecifiedFirstAbility' || want.abilityName === 'SpecifiedSecondAbility') {
190          // The returned key string is a custom string.
191          if (want.parameters) {
192            return `SpecifiedAbilityInstance_${want.parameters.instanceKey}`;
193          }
194        }
195        // ...
196        return 'MyAbilityStage';
197      }
198    }
199   ```
200
201   > **NOTE**
202   >
203   > - 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.
204   >
205   > - 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).
206
207For 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.
208
209The following steps are used as an example.
210
211   1. Open file A. A UIAbility instance, UIAbility instance 1, is started.
212   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.
213   3. Return to the home screen and open file B. A new UIAbility instance, UIAbility instance 3, is started.
214   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.
215