UIAbility コンポーネントの概要

UIAbility コンポーネントは、ユーザーと対話するために主に使用される UI を含むアプリケーションコンポーネントです。

UIAbility の設計理念：

アプリケーションコンポーネントレベルのクロスプラットフォーム移行とマルチデバイス協調をネイティブにサポートします。
複数のデバイスとウィンドウ形態をサポートします。

UIAbility の区分原則と提案：

UIAbility コンポーネントは、システムスケジューリングの基本単位であり、アプリケーションにインターフェースを描画するウィンドウを提供します。アプリケーションは、1 つまたは複数の UIAbility コンポーネントを含むことができます。たとえば、支払いアプリでは、エントリ機能と送受金機能をそれぞれ独立した UIAbility として構成できます。

各 UIAbility コンポーネントインスタンスは、最近のタスクリストに対応するタスクを表示します。

開発者にとっては、特定のシーンに応じて単一または複数の UIAbility を選択できます。区分の提案は以下の通りです：

開発者がタスクビューで 1 つのタスクを見たい場合は、1 つの 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 の 4 つの状態が含まれます。

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,
        "ウィンドウステージイベントの変更リスナーを有効にできませんでした。原因:" +
          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 がフロントに切り替わるときにトリガーされます。このコールバック内でシステムが必要とするリソースを要求したり、onBackground () で解放されたリソースを再度要求したりできます。

onBackground () コールバックは、UIAbility の UI が完全に不可視になった後、つまり UIAbility がバックグラウンドに切り替わるときにトリガーされます。このコールバック内で 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 インスタンスが起動時に異なる表示状態を指します。異なるビジネスシーンに応じて、システムは 3 つの起動モードを提供します：

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 {
    // メインウィンドウが作成され、これに対するメインページを設定
    windowStage.loadContent("pages/Index", (err, data) => {
      // ...
    });
  }
  // ...
}

この記事は Mix Space によって xLog に同期更新されました
元のリンクは http://www.sroxck.top/posts/harmony/uiability