UIAbility組件啟動模式

UIAbility的啟動模式是指UIAbility實例在啟動時的不同呈現(xiàn)狀態(tài)。針對不同的業(yè)務(wù)場景，系統(tǒng)提供了三種啟動模式：

singleton啟動模式

singleton啟動模式為單實例模式，也是默認(rèn)情況下的啟動模式。

每次調(diào)用[startAbility()]方法時，如果應(yīng)用進程中該類型的UIAbility實例已經(jīng)存在，則復(fù)用系統(tǒng)中的UIAbility實例。系統(tǒng)中只存在唯一一個該UIAbility實例，即在最近任務(wù)列表中只存在一個該類型的UIAbility實例。

圖1 單實例模式演示效果

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

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

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

multiton啟動模式

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

圖2 多實例模式演示效果

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

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

specified啟動模式

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

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

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

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

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

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

   // 在啟動指定實例模式的UIAbility時，給每一個UIAbility實例配置一個獨立的Key標(biāo)識
    // 例如在文檔使用場景中，可以用文檔路徑作為Key標(biāo)識
    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為調(diào)用方UIAbility的UIAbilityContext;
              let want: Want = {
                deviceId: '', // deviceId為空表示本設(shè)備
                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為調(diào)用方UIAbility的UIAbilityContext;
              let want: Want = {
                deviceId: '', // deviceId為空表示本設(shè)備
                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啟動之前，會先進入對應(yīng)的AbilityStage的[onAcceptWant()]生命周期回調(diào)中，以獲取該UIAbility實例的Key值。然后系統(tǒng)會自動匹配，如果存在與該UIAbility實例匹配的Key，則會啟動與之綁定的UIAbility實例，并進入該UIAbility實例的[onNewWant()]回調(diào)函數(shù)；否則會創(chuàng)建一個新的UIAbility實例，并進入該UIAbility實例的[onCreate()]回調(diào)函數(shù)和[onWindowStageCreate()]回調(diào)函數(shù)。
   示例代碼中，通過實現(xiàn)[onAcceptWant()]生命周期回調(diào)函數(shù)，解析傳入的want參數(shù)，獲取自定義參數(shù)instanceKey。業(yè)務(wù)邏輯會根據(jù)這個參數(shù)返回一個字符串Key，用于標(biāo)識當(dāng)前UIAbility實例。如果返回的Key已經(jīng)對應(yīng)一個已啟動的UIAbility實例，系統(tǒng)會將該UIAbility實例拉回前臺并獲焦，而不會創(chuàng)建新的實例。如果返回的Key沒有對應(yīng)已啟動的UIAbility實例，則系統(tǒng)會創(chuàng)建新的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 {
       // 在被調(diào)用方的AbilityStage中，針對啟動模式為specified的UIAbility返回一個UIAbility實例對應(yīng)的一個Key值
       // 當(dāng)前示例指的是module1 Module的SpecifiedAbility
       if (want.abilityName === 'SpecifiedFirstAbility' || want.abilityName === 'SpecifiedSecondAbility') {
         // 返回的字符串Key標(biāo)識為自定義拼接的字符串內(nèi)容
         if (want.parameters) {
           return `SpecifiedAbilityInstance_${want.parameters.instanceKey}`;
         }
       }
        // ...
       return 'MyAbilityStage';
     }
   }
   

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

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

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

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

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

審核編輯 黃宇