• 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- [Multiton](#multiton)
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![uiability-launch-type1](figures/uiability-launch-type1.gif)
22
23> **NOTE**
24>
25> 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.
26
27To use the singleton mode, set **launchType** in the [module.json5 configuration file](../quick-start/module-configuration-file.md) to **singleton**.
28
29
30```json
31{
32  "module": {
33    // ...
34    "abilities": [
35      {
36        "launchType": "singleton",
37        // ...
38      }
39    ]
40  }
41}
42```
43
44
45## Multiton
46
47In multiton 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**.
48
49**Figure 2** Demonstration effect in multiton mode
50
51![uiability-launch-type2](figures/uiability-launch-type2.gif)
52
53To use the multiton mode, set **launchType** in the [module.json5 file](../quick-start/module-configuration-file.md) to **multiton**.
54
55
56```json
57{
58  "module": {
59    // ...
60    "abilities": [
61      {
62        "launchType": "multiton",
63        // ...
64      }
65    ]
66  }
67}
68```
69
70
71## Specified
72
73The **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.
74
75**Figure 3** Demonstration effect in specified mode
76![uiability-launch-type3](figures/uiability-launch-type3.gif)
77
78For example, there are two UIAbility components: EntryAbility and SpecifiedAbility (with the launch type **specified**). You are required to start SpecifiedAbility from EntryAbility.
79
801. In SpecifiedAbility, set the **launchType** field in the [module.json5 file](../quick-start/module-configuration-file.md) to **specified**.
81
82   ```json
83   {
84     "module": {
85       // ...
86       "abilities": [
87         {
88           "launchType": "specified",
89           // ...
90         }
91       ]
92     }
93   }
94   ```
95
962. Create a unique string key for the instance. Each time [startAbility()](../reference/apis/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** parameter in [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to distinguish the UIAbility instance.
97
98   ```ts
99   // Configure an independent key for each UIAbility instance.
100   // For example, in the document usage scenario, use the document path as the key.
101   function getInstance() {
102       // ...
103   }
104
105   let want = {
106       deviceId: '', // An empty deviceId indicates the local device.
107       bundleName: 'com.example.myapplication',
108       abilityName: 'SpecifiedAbility',
109       moduleName: 'module1', // moduleName is optional.
110       parameters: {// Custom information.
111           instanceKey: getInstance(),
112       },
113   }
114   // context is the UIAbilityContext of the initiator UIAbility.
115   this.context.startAbility(want).then(() => {
116       // ...
117   }).catch((err) => {
118       // ...
119   })
120   ```
121
1223. Before SpecifiedAbility is started, the [onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback of the corresponding AbilityStage instance is invoked to obtain the key of the UIAbility, because the launch type of SpecifiedAbility is set to **specified**. If a UIAbility instance matching the key exists, the system starts the UIAbility instance and invokes its [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback. Otherwise, the system creates a new UIAbility instance and invokes its [onCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityoncreate) and [onWindowStageCreate()](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) callbacks.
123
124   In the sample code, the [onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant) callback parses the **want** parameter to obtain the custom parameter **instanceKey**. The service logic returns a key string based on **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 obtains the focus. If the returned key does not map to a started UIAbility instance, the system creates a new UIAbility instance and starts it.
125
126   ```ts
127   import AbilityStage from '@ohos.app.ability.AbilityStage';
128
129   export default class MyAbilityStage extends AbilityStage {
130       onAcceptWant(want): string {
131           // In the AbilityStage instance of the callee, a key value corresponding to a UIAbility instance is returned for UIAbility whose launch type is specified.
132           // In this example, SpecifiedAbility of module1 is returned.
133           if (want.abilityName === 'SpecifiedAbility') {
134               // The returned key string is a custom string.
135               return `SpecifiedAbilityInstance_${want.parameters.instanceKey}`;
136           }
137
138           return '';
139       }
140   }
141   ```
142
143   > **NOTE**
144   >
145   > 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.
146   > 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).
147
148   For 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, 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.
149
150   The following steps are used as an example.
151
152   1. Open file A. A UIAbility instance, for example, UIAbility instance 1, is started.
153   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.
154   3. Return to the home screen and open file B. A new UIAbility instance is started, for example, UIAbility instance 3.
155   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 of 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.
156