UIAbility組件概述

UIAbility組件是HarmonyOS中一種包含UI界面的應(yīng)用組件，主要用于與用戶進(jìn)行交互。每個(gè)UIAbility組件實(shí)例對應(yīng)最近任務(wù)列表中的一個(gè)任務(wù)，可以包含多個(gè)頁面來實(shí)現(xiàn)不同功能模塊。

聲明配置

為了使用UIAbility，首先需要在module.json5配置文件的abilities標(biāo)簽中聲明UIAbility的相關(guān)信息，包括名稱、入口、描述、圖標(biāo)等。

{
  "module": {
    // ...
    "abilities": [
      {
        "name": "EntryAbility", // UIAbility組件的名稱
        "srcEntrance": "./ets/entryability/EntryAbility.ts", // UIAbility組件的代碼路徑
        "description": "$string:EntryAbility_desc", // UIAbility組件的描述信息
        "icon": "$media:icon", // UIAbility組件的圖標(biāo)
        "label": "$string:EntryAbility_label", // UIAbility組件的標(biāo)簽
        "startWindowIcon": "$media:icon", // UIAbility組件啟動(dòng)頁面圖標(biāo)資源文件的索引
        "startWindowBackground": "$color:start_window_background", // UIAbility組件啟動(dòng)頁面背景顏色資源文件的索引
        // ...
      }
    ]
  }
}

UIAbility組件生命周期

UIAbility組件的生命周期包括四個(gè)狀態(tài)：Create、Foreground、Background、Destroy。在不同狀態(tài)之間轉(zhuǎn)換時(shí)，系統(tǒng)會(huì)調(diào)用相應(yīng)的生命周期回調(diào)函數(shù)。

Create狀態(tài)

Create狀態(tài)表示UIAbility實(shí)例創(chuàng)建完成時(shí)觸發(fā)，系統(tǒng)調(diào)用onCreate()回調(diào)。在該回調(diào)中可以進(jìn)行應(yīng)用初始化操作，如變量定義、資源加載等，為后續(xù)的UI界面展示做準(zhǔn)備。

import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
    onCreate(want, launchParam) {
        // 應(yīng)用初始化
    }
    // ...
}

WindowStageCreate和WindowStageDestroy狀態(tài)

在UIAbility實(shí)例創(chuàng)建完成后，在進(jìn)入Foreground之前，系統(tǒng)會(huì)創(chuàng)建一個(gè)WindowStage。WindowStage創(chuàng)建完成后會(huì)觸發(fā)onWindowStageCreate()回調(diào)，可以在該回調(diào)中設(shè)置UI界面加載和訂閱WindowStage的事件。

import UIAbility from '@ohos.app.ability.UIAbility';
import Window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: Window.WindowStage) {
        // 設(shè)置WindowStage的事件訂閱（獲焦/失焦、可見/不可見）

        // 設(shè)置UI界面加載
        windowStage.loadContent('pages/Index', (err, data) => {
            // ...
        });
    }
    // ...
}

// 對應(yīng)onWindowStageCreate回調(diào)，在UIAbility實(shí)例銷毀之前，會(huì)先進(jìn)入onWindowStageDestroy回調(diào)，可以在該回調(diào)中釋放UI界面資源。
export default class EntryAbility extends UIAbility {
    // ...

    onWindowStageDestroy() {
        // 釋放UI界面資源
    }
}

Foreground和Background狀態(tài)

Foreground和Background狀態(tài)分別在UIAbility實(shí)例切換至前臺(tái)和切換至后臺(tái)時(shí)觸發(fā)，對應(yīng)于onForeground()和onBackground()回調(diào)。在onForeground()中可以申請系統(tǒng)需要的資源，而在onBackground()中可以釋放UI界面不可見時(shí)無用的資源。

import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
    onForeground() {
        // 申請系統(tǒng)需要的資源，或者重新申請?jiān)趏nBackground中釋放的資源
    }

    onBackground() {
        // 釋放UI界面不可見時(shí)無用的資源，或者在此回調(diào)中執(zhí)行較為耗時(shí)的操作，例如狀態(tài)保存等
    }
}

Destroy狀態(tài)

Destroy狀態(tài)在UIAbility實(shí)例銷毀時(shí)觸發(fā)，可以在onDestroy()回調(diào)中進(jìn)行系統(tǒng)資源的釋放、數(shù)據(jù)的保存等操作。

import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
    onDestroy() {
        // 系統(tǒng)資源的釋放、數(shù)據(jù)的保存等
    }
}

UIAbility組件啟動(dòng)模式

UIAbility的啟動(dòng)模式有三種：singleton（單實(shí)例模式）、standard（標(biāo)準(zhǔn)實(shí)例模式）、specified（指定實(shí)例模式）。

Singleton啟動(dòng)模式

Singleton啟動(dòng)模式為單實(shí)例模式，是默認(rèn)的啟動(dòng)模式。每次調(diào)用startAbility()方法時(shí)，如果應(yīng)用進(jìn)程中該類型的UIAbility實(shí)例已經(jīng)存在，則復(fù)用該實(shí)例。系統(tǒng)中只存在唯一一個(gè)該UIAbility實(shí)例。

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

Standard啟動(dòng)模式

Standard啟動(dòng)模式為標(biāo)準(zhǔn)實(shí)例模式，每次調(diào)用startAbility()方法時(shí)，都會(huì)在應(yīng)用進(jìn)程中創(chuàng)建一個(gè)新的該類型UIAbility實(shí)例。在最近任務(wù)列表中可以看到多個(gè)該類型的UIAbility實(shí)例。

{
  "module": {
    // ...
    "abilities": [
      {
        "launchType": "standard",
        // ...
      }
    ]
  }
}

Specified啟動(dòng)模式

Specified啟動(dòng)模式為指定實(shí)例模式，允許為UIAbility實(shí)例創(chuàng)建一個(gè)唯一的Key，后續(xù)每次調(diào)用startAbility()方法時(shí)，都會(huì)詢問應(yīng)用使用哪個(gè)Key對應(yīng)的UIAbility實(shí)例來響應(yīng)請求。

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

在指定實(shí)例模式下，需要在啟動(dòng)UIAbility時(shí)傳入自定義參數(shù)，如"instanceKey"，用于區(qū)分UIAbility實(shí)例。

let want = {
    deviceId: '', // deviceId為空表示本設(shè)備
    bundleName: 'com.example.myapplication',
    abilityName: 'FuncAbility',
    moduleName: 'module1', // moduleName非必選
    parameters: { // 自定義信息
        instanceKey: getInstance(),
    },
};

// context

為調(diào)用方UIAbility的AbilityContext
this.context.startAbility(want).then(() => {
    // ...
}).catch((err) => {
    // ...
});

在被調(diào)用方UIAbility的AbilityStage中，通過onAcceptWant()生命周期回調(diào)返回一個(gè)字符串Key標(biāo)識(shí)，用于匹配已創(chuàng)建的UIAbility實(shí)例。

import AbilityStage from '@ohos.app.ability.AbilityStage';

export default class MyAbilityStage extends AbilityStage {
    onAcceptWant(want): string {
        // 在被調(diào)用方的AbilityStage中，針對啟動(dòng)模式為specified的UIAbility返回一個(gè)UIAbility實(shí)例對應(yīng)的一個(gè)Key值
        // 當(dāng)前示例指的是module1 Module的FuncAbility
        if (want.abilityName === 'FuncAbility') {
            // 返回的字符串Key標(biāo)識(shí)為自定義拼接的字符串內(nèi)容
            return `ControlModule_EntryAbilityInstance_${want.parameters.instanceKey}`;
        }

        return '';
    }
}

例如，在文檔應(yīng)用中，可以將文件路徑作為一個(gè)Key標(biāo)識(shí)，實(shí)現(xiàn)每次新建文檔都創(chuàng)建一個(gè)新的UIAbility實(shí)例，而打開已保存的文檔時(shí)重用相應(yīng)的UIAbility實(shí)例。

以上就是HarmonyOS UIAbility組件的概述、聲明配置、生命周期、以及啟動(dòng)模式的詳細(xì)介紹。通過了解這些知識(shí)點(diǎn)，開發(fā)者可以更好地利用UIAbility組件構(gòu)建豐富的HarmonyOS應(yīng)用。

HarmonyOS UIAbility組件進(jìn)階

WindowStage和UI界面

在HarmonyOS中，UIAbility組件的界面展示主要通過WindowStage和UI界面來實(shí)現(xiàn)。WindowStage代表著UIAbility的窗口舞臺(tái)，而UI界面則通過加載相應(yīng)的頁面來完成展示。

WindowStage的創(chuàng)建和銷毀

在UIAbility實(shí)例創(chuàng)建完成后，在進(jìn)入Foreground狀態(tài)之前，系統(tǒng)會(huì)創(chuàng)建一個(gè)WindowStage。在onWindowStageCreate()回調(diào)中，可以設(shè)置UIAbility要加載的頁面，并訂閱WindowStage的事件。

import UIAbility from '@ohos.app.ability.UIAbility';
import Window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: Window.WindowStage) {
        // 設(shè)置WindowStage的事件訂閱（獲焦/失焦、可見/不可見）

        // 設(shè)置UI界面加載
        windowStage.loadContent('pages/Index', (err, data) => {
            // ...
        });
    }

    // ...
}

對應(yīng)的，在UIAbility實(shí)例銷毀之前，會(huì)先進(jìn)入onWindowStageDestroy()回調(diào)，可以在該回調(diào)中釋放UI界面資源。

import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
    // ...

    onWindowStageDestroy() {
        // 釋放UI界面資源
    }
}

UI界面的加載

在onWindowStageCreate()回調(diào)中，通過loadContent()方法設(shè)置UIAbility要加載的頁面。這里的頁面路徑可以是相對路徑，也可以是絕對路徑。

import UIAbility from '@ohos.app.ability.UIAbility';
import Window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    onWindowStageCreate(windowStage: Window.WindowStage) {
        // 設(shè)置WindowStage的事件訂閱（獲焦/失焦、可見/不可見）

        // 設(shè)置UI界面加載
        windowStage.loadContent('pages/Index', (err, data) => {
            // ...
        });
    }

    // ...
}

生命周期示例

下面以一個(gè)簡單的示例說明UIAbility的生命周期狀態(tài)變化：

import UIAbility from '@ohos.app.ability.UIAbility';
import Window from '@ohos.window';

export default class EntryAbility extends UIAbility {
    onCreate(want, launchParam) {
        // Create狀態(tài)
        console.info('onCreate');
    }

    onWindowStageCreate(windowStage: Window.WindowStage) {
        // WindowStageCreate狀態(tài)
        console.info('onWindowStageCreate');

        // 設(shè)置UI界面加載
        windowStage.loadContent('pages/Index', (err, data) => {
            // ...
        });
    }

    onForeground() {
        // Foreground狀態(tài)
        console.info('onForeground');
    }

    onBackground() {
        // Background狀態(tài)
        console.info('onBackground');
    }

    onDestroy() {
        // Destroy狀態(tài)
        console.info('onDestroy');
    }
}

在應(yīng)用加載過程中，onCreate()回調(diào)表示Create狀態(tài)，之后進(jìn)入Foreground狀態(tài)前會(huì)觸發(fā)onWindowStageCreate()回調(diào)，然后在切換至后臺(tái)和銷毀時(shí)分別觸發(fā)onBackground()和onDestroy()回調(diào)。

UIAbility組件啟動(dòng)模式進(jìn)階

在前面提到的UIAbility的啟動(dòng)模式中，除了基本的singleton、standard、specified啟動(dòng)模式外，還可以根據(jù)實(shí)際場景進(jìn)行靈活的配置和使用。

使用singleton啟動(dòng)模式

singleton啟動(dòng)模式為單實(shí)例模式，默認(rèn)情況下的啟動(dòng)模式。每次調(diào)用startAbility()方法時(shí)，如果應(yīng)用進(jìn)程中已存在該類型的UIAbility實(shí)例，則系統(tǒng)會(huì)復(fù)用該實(shí)例。系統(tǒng)中只存在唯一一個(gè)該UIAbility實(shí)例。

`配置文件中的"abilities"標(biāo)簽下的"launchType"字段配置為"singleton"即可。

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

使用standard啟動(dòng)模式

standard啟動(dòng)模式為標(biāo)準(zhǔn)實(shí)例模式，每次調(diào)用startAbility()方法時(shí)，都會(huì)在應(yīng)用進(jìn)程中創(chuàng)建一個(gè)新的該類型UIAbility實(shí)例。在最近任務(wù)列表中可以看到有多個(gè)該類型的UIAbility實(shí)例。

在module.json5配置文件中的"abilities"標(biāo)簽下的"launchType"字段配置為"standard"即可。

{
    "module": {
        // ...
        "abilities": [
            {
                "launchType": "standard",
                // ...
            }
        ]
    }
}

使用specified啟動(dòng)模式

specified啟動(dòng)模式為指定實(shí)例模式，允許在UIAbility實(shí)例創(chuàng)建之前為其創(chuàng)建一個(gè)唯一的字符串Key。每次調(diào)用startAbility()方法時(shí)，會(huì)詢問應(yīng)用使用哪個(gè)Key對應(yīng)的UIAbility實(shí)例來響應(yīng)請求。如果匹配有該UIAbility實(shí)例的Key，則直接拉起與之綁定的UIAbility實(shí)例，否則創(chuàng)建一個(gè)新的UIAbility實(shí)例。

在module.json5配置文件中的"abilities"標(biāo)簽下的"launchType"字段配置為"specified"即可。

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

指定實(shí)例模式的使用場景

specified啟動(dòng)模式適用于一些特殊場景，例如文檔應(yīng)用中每次新建文檔希望都能新建一個(gè)文檔實(shí)例，而重復(fù)打開一個(gè)已保存的文檔時(shí)希望打開的都是同一個(gè)文檔實(shí)例。

在使用指定實(shí)例模式時(shí)，需要在UIAbility實(shí)例創(chuàng)建之前為其創(chuàng)建一個(gè)唯一的字符串Key。在啟動(dòng)UIAbility時(shí)，通過自定義參數(shù)傳遞這個(gè)Key，用于匹配已創(chuàng)建的UIAbility實(shí)例。

例如，有兩個(gè)UIAbility：EntryAbility和FuncAbility，其中FuncAbility配置為specified啟動(dòng)模式。在EntryAbility中調(diào)用startAbility()方法啟動(dòng)FuncAbility時(shí)，需要在want參數(shù)中增加一個(gè)自定義參數(shù)來區(qū)別UIAbility實(shí)例，例如增加一個(gè)"instanceKey"自定義參數(shù)。

// 在啟動(dòng)指定實(shí)例模式的UIAbility時(shí)，給每一個(gè)UIAbility實(shí)例配置一個(gè)獨(dú)立的Key標(biāo)識(shí)
// 例如在文檔使用場景中，可以用文檔路徑作為Key標(biāo)識(shí)
function getInstance() {
    // ...
}

let want = {
    deviceId: '', // deviceId為空表示本設(shè)備
    bundleName: 'com.example.myapplication',
    abilityName: 'FuncAbility',
    moduleName: 'module1', // moduleName非必選
    parameters: { // 自定義信息
        instanceKey: getInstance(),
    },
}

// context為調(diào)用方UIAbility的AbilityContext
this.context.startAbility(want).then(() => {
    // ...
}).catch((err) => {
    // ...
});

在被調(diào)用方UIAbility的AbilityStage中，通過onAcceptWant()生命周期回調(diào)返回一個(gè)字符串Key標(biāo)識(shí)，用于匹配已創(chuàng)建的UIAbility實(shí)例。

import AbilityStage from '@ohos.app.ability.AbilityStage';

export default class MyAbilityStage extends AbilityStage {
    onAcceptWant(want): string {
        // 在被調(diào)用方的AbilityStage中，針對啟動(dòng)模式為specified的UIAbility返回一個(gè)UIAbility實(shí)例對應(yīng)的一個(gè)Key值
        // 當(dāng)前示例指的是module1 Module的FuncAbility
        if (want.abilityName === 'FuncAbility') {
            // 返回的字符串Key標(biāo)識(shí)為自定義拼接的字符串內(nèi)容
            return `ControlModule_EntryAbilityInstance_${want.parameters.instanceKey}`;
        }

        return '';
    }
}

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

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

這樣，通過指定實(shí)例模式的配置，可以實(shí)現(xiàn)更加靈活和符合業(yè)務(wù)場景的UIAbility啟動(dòng)方式。

審核編輯 黃宇