Understanding UIAbility Launch Types in HarmonyOS Next

Read the original article：Understanding UIAbility Launch Types in HarmonyOS Next

Introduction

In HarmonyOS Next, the UIAbility component is a fundamental building block for creating user interfaces and managing application workflows. One of the key aspects of UIAbility is its launch type, which determines how instances are created and managed.

There are three launch types available:

1. Singleton — Only one instance exists in the system.
2. Multiton — A new instance is created every time.
3. Specified — Custom instance management for specific use cases.

Let’s explore each of them in detail.

1. Singleton Mode (Default)

Behavior

• Only one instance of the UIAbility can exist at any time.
• If startAbility() is called while an instance already exists:
• The existing instance is reused.
• The onNewWant() callback is triggered (not onCreate() or onWindowStageCreate()).
• Only one mission appears in the Recents (multitasking view).

Use Case

Best for apps where only one instance should ever be active (e.g., a settings page).

Configuration

{
  "module": {
    "abilities": [
      {
        "launchType": "singleton"
      }
    ]
  }
}

Example Scenario

• User opens Settings → A new UIAbility instance is created.
• User tries to open Settings again → The same instance is brought to the foreground.

2. Multiton Mode (Formerly “Standard”)

Behavior

• A new instance is created every time startAbility() is called.
• Multiple missions appear in Recents.

Use Case

Ideal for scenarios where multiple independent instances are needed (e.g., a notes app where each note opens in a new window).

Configuration

{
  "module": {
    "abilities": [
      {
        "launchType": "multiton"
      }
    ]
  }
}

Example Scenario

• User opens Note 1 → Instance A is created.
• User opens Note 2 → Instance B is created.
• Both instances appear separately in Recents.

3. Specified Mode (Custom Instance Management)

Behavior

• Allows custom logic to decide whether to reuse an existing instance or create a new one.
• Uses a unique key (instanceKey) to identify instances.
• The onAcceptWant() callback in AbilityStage determines which instance to launch

Use Case

Useful for apps like document editors where:

• New document → Create a new instance.
• Existing document → Reuse the same instance.

Configuration

Step 1: Set launchType to specified

{
  "module": {
    "abilities": [
      {
        "launchType": "specified"
      }
    ]
  }
}

Step 2: Pass a Unique Key in startAbility()

let want: Want = {
  bundleName: 'com.example.app',
  abilityName: 'DocumentAbility',
  parameters: {
    instanceKey: 'doc123' // Unique identifier
  }
};
context.startAbility(want);

Step 3: Implement onAcceptWant() in AbilityStage

export default class MyAbilityStage extends AbilityStage {
  onAcceptWant(want: Want): string {
    if (want.abilityName === 'DocumentAbility') {
      return `DocumentInstance_${want.parameters.instanceKey}`;
    }
    return '';
  }
}

Example Scenario

1. Open File A → Instance 1 is created (DocumentInstance_A).
2. Close File A → Instance 1 is destroyed.
3. Reopen File A → A new instance (DocumentInstance_A) is created.
4. Open File B → Instance 2 (ocumentInstance_B) is created.
5. Reopen File A → Instance 1 is reused.

Key Takeaways

Launch TypeBehaviorBest ForSingletonOnly one instance existsSettings, single-instance appsMultitonNew instance every timeMulti-window apps (e.g., notes)SpecifiedCustom instance controlDocument editors, file-based apps

Conclusion

Choosing the right UIAbility launch type is crucial for managing app behavior efficiently:

• Singleton ensures only one instance runs.
• Multiton allows multiple independent instances.
• Specified provides fine-grained control for specialized cases.

By understanding these modes, developers can optimize performance and user experience in HarmonyOS Next applications.

Further Reading

https://developer.huawei.com/consumer/en/doc/harmonyos-guides/uiability-launch-type

Written by Jeorge Kiryienko