UIAbility組件啟動模式

UIAbility的啟動模式是指UIAbility實例在啟動時的不同呈現狀態。針對不同的業務場景，系統提供了三種啟動模式：

singleton啟動模式

singleton啟動模式為單實例模式，也是默認情況下的啟動模式。

每次調用[startAbility()]方法時，如果應用進程中該類型的UIAbility實例已經存在，則復用系統中的UIAbility實例。系統中只存在唯一一個該UIAbility實例，即在最近任務列表中只存在一個該類型的UIAbility實例。

圖1 單實例模式演示效果

說明 ：
開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
應用的UIAbility實例已創建，該UIAbility配置為單實例模式，再次調用[startAbility()]方法啟動該UIAbility實例。由于啟動的還是原來的UIAbility實例，并未重新創建一個新的UIAbility實例，此時只會進入該UIAbility的[onNewWant()]回調，不會進入其[onCreate()]和[onWindowStageCreate()]生命周期回調。

如果需要使用singleton啟動模式，在[module.json5配置文件]中的launchType字段配置為singleton即可。

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

multiton啟動模式

multiton啟動模式為多實例模式，每次調用[startAbility()]方法時，都會在應用進程中創建一個新的該類型UIAbility實例。即在最近任務列表中可以看到有多個該類型的UIAbility實例。這種情況下可以將UIAbility配置為multiton（多實例模式）。

圖2 多實例模式演示效果

multiton啟動模式的開發使用，在[module.json5配置文件]中的launchType字段配置為multiton即可。

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

specified啟動模式

specified啟動模式為指定實例模式，針對一些特殊場景使用（例如文檔應用中每次新建文檔希望都能新建一個文檔實例，重復打開一個已保存的文檔希望打開的都是同一個文檔實例）。

圖3 指定實例模式演示效果

例如有兩個UIAbility：EntryAbility和SpecifiedAbility，SpecifiedAbility配置為指定實例模式啟動，需要從EntryAbility的頁面中啟動SpecifiedAbility。

1. 在SpecifiedAbility中，將[module.json5配置文件]的launchType字段配置為specified。

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

2. 在創建UIAbility實例之前，開發者可以為該實例指定一個唯一的字符串Key，這樣在調用[startAbility()]方法時，應用就可以根據指定的Key來識別響應請求的UIAbility實例。在EntryAbility中，調用[startAbility()]方法時，可以在want參數中增加一個自定義參數，例如instanceKey，以此來區分不同的UIAbility實例。

   // 在啟動指定實例模式的UIAbility時，給每一個UIAbility實例配置一個獨立的Key標識
    // 例如在文檔使用場景中，可以用文檔路徑作為Key標識
    import common from '@ohos.app.ability.common';
    import hilog from '@ohos.hilog';
    import Want from '@ohos.app.ability.Want';
    import { BusinessError } from '@ohos.base';
   
    const TAG: string = '[Page_StartModel]';
    const DOMAIN_NUMBER: number = 0xFF00;
   
    function getInstance() : string {
      return 'KEY';
    }
   
    @Entry
    @Component
    struct Page_StartModel {
      private KEY_NEW = 'KEY';
      build() {
        Row() {
          Column() {
            // ...
            Button()
            // ...
            .onClick(() = > {
              let context:common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
              // context為調用方UIAbility的UIAbilityContext;
              let want: Want = {
                deviceId: '', // deviceId為空表示本設備
                bundleName: 'com.samples.stagemodelabilitydevelop',
                abilityName: 'SpecifiedFirstAbility',
                moduleName: 'entry', // moduleName非必選
                parameters: { // 自定義信息
                  instanceKey: this.KEY_NEW
                }
              };
              context.startAbility(want).then(() = > {
                hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting SpecifiedAbility.');
              }).catch((err: BusinessError) = > {
                hilog.error(DOMAIN_NUMBER, TAG, `Failed to start SpecifiedAbility. Code is ${err.code}, message is ${err.message}`);
              })
              this.KEY_NEW = this.KEY_NEW + 'a';
            })
            // ...
            Button()
            // ...
            .onClick(() = > {
              let context:common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
              // context為調用方UIAbility的UIAbilityContext;
              let want: Want = {
                deviceId: '', // deviceId為空表示本設備
                bundleName: 'com.samples.stagemodelabilitydevelop',
                abilityName: 'SpecifiedSecondAbility',
                moduleName: 'entry', // moduleName非必選
                parameters: { // 自定義信息
                  instanceKey: getInstance()
                }
              };
              context.startAbility(want).then(() = > {
                hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in starting SpecifiedAbility.');
              }).catch((err: BusinessError) = > {
                hilog.error(DOMAIN_NUMBER, TAG, `Failed to start SpecifiedAbility. Code is ${err.code}, message is ${err.message}`);
              })
              this.KEY_NEW = this.KEY_NEW + 'a';
            })
            // ...
          }
          .width('100%')
        }
        .height('100%')
      }
    }
   

3. 由于SpecifiedAbility的啟動模式被配置為指定實例啟動模式，因此在SpecifiedAbility啟動之前，會先進入對應的AbilityStage的[onAcceptWant()]生命周期回調中，以獲取該UIAbility實例的Key值。然后系統會自動匹配，如果存在與該UIAbility實例匹配的Key，則會啟動與之綁定的UIAbility實例，并進入該UIAbility實例的[onNewWant()]回調函數；否則會創建一個新的UIAbility實例，并進入該UIAbility實例的[onCreate()]回調函數和[onWindowStageCreate()]回調函數。
   示例代碼中，通過實現[onAcceptWant()]生命周期回調函數，解析傳入的want參數，獲取自定義參數instanceKey。業務邏輯會根據這個參數返回一個字符串Key，用于標識當前UIAbility實例。如果返回的Key已經對應一個已啟動的UIAbility實例，系統會將該UIAbility實例拉回前臺并獲焦，而不會創建新的實例。如果返回的Key沒有對應已啟動的UIAbility實例，則系統會創建新的UIAbility實例并啟動。

   import AbilityStage from '@ohos.app.ability.AbilityStage';
   import type Want from '@ohos.app.ability.Want';
   
   export default class MyAbilityStage extends AbilityStage {
     onAcceptWant(want: Want): string {
       // 在被調用方的AbilityStage中，針對啟動模式為specified的UIAbility返回一個UIAbility實例對應的一個Key值
       // 當前示例指的是module1 Module的SpecifiedAbility
       if (want.abilityName === 'SpecifiedFirstAbility' || want.abilityName === 'SpecifiedSecondAbility') {
         // 返回的字符串Key標識為自定義拼接的字符串內容
         if (want.parameters) {
           return `SpecifiedAbilityInstance_${want.parameters.instanceKey}`;
         }
       }
        // ...
       return 'MyAbilityStage';
     }
   }
   

說明：
HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿

1. 當應用的UIAbility實例已經被創建，并且配置為指定實例模式時，如果再次調用[startAbility()]方法啟動該UIAbility實例，且[AbilityStage]的[onAcceptWant()]回調匹配到一個已創建的UIAbility實例，則系統會啟動原來的UIAbility實例，并且不會重新創建一個新的UIAbility實例。此時，該UIAbility實例的[onNewWant()]回調會被觸發，而不會觸發[onCreate()]和[onWindowStageCreate()]生命周期回調。
2. DevEco Studio默認工程中未自動生成AbilityStage，AbilityStage文件的創建請參見[AbilityStage組件容器]。

例如在文檔應用中，可以為不同的文檔實例內容綁定不同的Key值。每次新建文檔時，可以傳入一個新的Key值（例如可以將文件的路徑作為一個Key標識），此時AbilityStage中啟動UIAbility時都會創建一個新的UIAbility實例；當新建的文檔保存之后，回到桌面，或者新打開一個已保存的文檔，回到桌面，此時再次打開該已保存的文檔，此時AbilityStage中再次啟動該UIAbility時，打開的仍然是之前原來已保存的文檔界面。

以如下步驟所示進行舉例說明。

1.  打開`文件A`，對應啟動一個新的UIAbility實例，例如啟動`UIAbility實例1`。
1.  在最近任務列表中關閉`文件A`的任務進程，此時`UIAbility實例1`被銷毀，回到桌面，再次打開`文件A`，此時對應啟動一個新的UIAbility實例，例如啟動`UIAbility實例2`。
1.  回到桌面，打開`文件B`，此時對應啟動一個新的UIAbility實例，例如啟動`UIAbility實例3`。
1.  回到桌面，再次打開`文件A`，此時仍然啟動之前的`UIAbility實例2`，因為系統會自動匹配UIAbility實例的Key值，如果存在與之匹配的Key，則會啟動與之綁定的UIAbility實例。在此例中，之前啟動的`UIAbility實例2`與`文件A`綁定的Key是相同的，因此系統會拉回`UIAbility實例2`并讓其獲焦，而不會創建新的實例。

審核編輯 黃宇