UIAbility 元件概述

UIAbility 組件是一種包含 UI 的應用組件，主要用於和用戶互動。

UIAbility 的設計理念：

原生支持應用組件級的跨端遷移和多端協同。
支持多設備和多窗口形態。

UIAbility 劃分原則與建議：

UIAbility 組件是系統調度的基本單元，為應用提供繪製界面的窗口。一個應用可以包含一個或多個 UIAbility 組件。例如，在支付應用中，可以將入口功能和收付款功能分別配置為獨立的 UIAbility。

每一個 UIAbility 組件實例都會在最近任務列表中顯示一個對應的任務。

對於開發者而言，可以根據具體場景選擇單個還是多個 UIAbility，劃分建議如下：

如果開發者希望在任務視圖中看到一個任務，則建議使用一個 UIAbility，多個頁面的方式。
如果開發者希望在任務視圖中看到多個任務，或者需要同時開啟多個窗口，則建議使用多個 UIAbility 開發不同的模塊功能。

聲明配置#

為使應用能夠正常使用 UIAbility，需要在 module.json5 配置文件的 abilities 標籤中聲明 UIAbility 的名稱、入口、標籤等相關信息。

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

UIAbility 組件生命週期#

當用戶打開、切換和返回到對應應用時，應用中的 UIAbility 實例會在其生命週期的不同狀態之間轉換。UIAbility 類提供了一系列回調，通過這些回調可以知道當前 UIAbility 實例的某個狀態發生改變，會經過 UIAbility 實例的創建和銷毀，或者 UIAbility 實例發生了前後台的狀態切換。

UIAbility 的生命週期包括 Create、Foreground、Background、Destroy 四個狀態。

Create 狀態#

Create 狀態為在應用加載過程中，UIAbility 實例創建完成時觸發，系統會調用 onCreate () 回調。可以在該回調中進行頁面初始化操作，例如變量定義資源加載等，用於後續的 UI 展示。

import { AbilityConstant, UIAbility, Want } from "@kit.AbilityKit";

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 頁面初始化
  }
  // ...
}

WindowStageCreate 和 WindowStageDestroy 狀態#

UIAbility 實例創建完成之後，在進入 Foreground 之前，系統會創建一個 WindowStage。WindowStage 創建完成後會進入 onWindowStageCreate () 回調，可以在該回調中設置 UI 加載、設置 WindowStage 的事件訂閱。

import { UIAbility } from "@kit.AbilityKit";
import { window } from "@kit.ArkUI";
import { hilog } from "@kit.PerformanceAnalysisKit";

const TAG: string = "[EntryAbility]";
const DOMAIN_NUMBER: number = 0xff00;

export default class EntryAbility extends UIAbility {
  // ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 設置WindowStage的事件訂閱（獲焦/失焦、可見/不可見）
    try {
      windowStage.on("windowStageEvent", (data) => {
        let stageEventType: window.WindowStageEventType = data;
        switch (stageEventType) {
          case window.WindowStageEventType.SHOWN: // 切到前台
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage foreground.");
            break;
          case window.WindowStageEventType.ACTIVE: // 獲焦狀態
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage active.");
            break;
          case window.WindowStageEventType.INACTIVE: // 失焦狀態
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage inactive.");
            break;
          case window.WindowStageEventType.HIDDEN: // 切到後台
            hilog.info(DOMAIN_NUMBER, TAG, "windowStage background.");
            break;
          default:
            break;
        }
      });
    } catch (exception) {
      hilog.error(
        DOMAIN_NUMBER,
        TAG,
        "Failed to enable the listener for window stage event changes. Cause:" +
          JSON.stringify(exception)
      );
    }
    hilog.info(DOMAIN_NUMBER, TAG, "%{public}s", "Ability onWindowStageCreate");
    // 設置UI加載
    windowStage.loadContent("pages/Index", (err, data) => {
      // ...
    });
  }
}

WindowStageWillDestroy 狀態#

對應 onWindowStageWillDestroy () 回調，在 WindowStage 銷毀前執行，此時 WindowStage 可以使用。

Foreground 和 Background 狀態#

Foreground 和 Background 狀態分別在 UIAbility 實例切換至前台和切換至後台時觸發，對應於 onForeground () 回調和 onBackground () 回調。

onForeground () 回調，在 UIAbility 的 UI 可見之前，如 UIAbility 切換至前台時觸發。可以在 onForeground () 回調中申請系統需要的資源，或者重新申請在 onBackground () 中釋放的資源。

onBackground () 回調，在 UIAbility 的 UI 完全不可見之後，如 UIAbility 切換至後台時觸發。可以在 onBackground () 回調中釋放 UI 不可見時無用的資源，或者在此回調中執行較為耗時的操作，例如狀態保存等。

例如應用在使用過程中需要使用用戶定位時，假設應用已獲得用戶的定位權限授權。在 UI 顯示之前，可以在 onForeground () 回調中開啟定位功能，從而獲取到當前的位置信息。

當應用切換到後台狀態，可以在 onBackground () 回調中停止定位功能，以節省系統的資源消耗。

import { UIAbility } from "@kit.AbilityKit";

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

  onForeground(): void {
    // 申請系統需要的資源，或者重新申請在onBackground()中釋放的資源
  }

  onBackground(): void {
    // 釋放UI不可見時無用的資源，或者在此回調中執行較為耗時的操作
    // 例如狀態保存等
  }
}

Destroy 狀態#

Destroy 狀態在 UIAbility 實例銷毀時觸發。可以在 onDestroy () 回調中進行系統資源的釋放、數據的保存等操作。

例如，調用 terminateSelf () 方法停止當前 UIAbility 實例，執行 onDestroy () 回調，並完成 UIAbility 實例的銷毀。

::: tip 說明
如果用戶使用最近任務列表上滑來關閉該 UIAbility 實例，將會直接終止進程。這個過程並不會執行 onDestroy () 回調。

:::

import { UIAbility } from "@kit.AbilityKit";

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

  onDestroy() {
    // 系統資源的釋放、數據的保存等
  }
}

UIAbility 組件啟動模式#

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

singleton（單實例模式）

multiton（多實例模式）

specified（指定實例模式）

UIAbility 組件啟動模式

UIAbility 組件基本用法#

UIAbility 組件的基本用法包括：指定 UIAbility 的啟動頁面以及獲取 UIAbility 的上下文 UIAbilityContext。

指定 UIAbility 的啟動頁面#

應用中的 UIAbility 在啟動過程中，需要指定啟動頁面，否則應用啟動後會因為沒有默認加載頁面而導致白屏。可以在 UIAbility 的 onWindowStageCreate () 生命週期回調中，通過 WindowStage 對象的 loadContent () 方法設置啟動頁面。

import { UIAbility } from "@kit.AbilityKit";
import { window } from "@kit.ArkUI";

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    // Main window is created, set main page for this ability
    windowStage.loadContent("pages/Index", (err, data) => {
      // ...
    });
  }
  // ...
}

此文由 Mix Space 同步更新至 xLog 原始鏈接為 http://www.sroxck.top/posts/harmony/uiability