UIAbility和自定義組件生命周期（ArkTS）

介紹

本文檔主要描述了應用運行過程中UIAbility和自定義組件的生命周期。對于UIAbility，描述了Create、Foreground、Background、Destroy四種生命周期。對于頁面和自定義組件描述了aboutToAppear、onPageShow、onPageHide、onBackPress、aboutToDisappear五種生命周期。

環境搭建

軟件要求

[DevEco Studio]版本：DevEco Studio 3.1 Release。
OpenHarmony SDK版本：API version 9。

硬件要求

開發板類型：[潤和RK3568開發板]。
OpenHarmony系統：3.2 Release。
開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

環境搭建

完成本篇Codelab我們首先要完成開發環境的搭建，本示例以RK3568開發板為例，參照以下步驟進行：

[獲取OpenHarmony系統版本]：標準系統解決方案（二進制）。以3.2 Release版本為例：
搭建燒錄環境。
1. [完成DevEco Device Tool的安裝]
2. [完成RK3568開發板的燒錄]
搭建開發環境。
1. 開始前請參考[工具準備]，完成DevEco Studio的安裝和開發環境配置。
2. 開發環境配置完成后，請參考[使用工程向導]創建工程（模板選擇“Empty Ability”）。
3. 工程創建完成后，選擇使用[真機進行調測]。

代碼結構解讀

本篇Codelab只對核心代碼進行講解，對于完整代碼，我們會在gitee中提供。

├──entry/src/main/ets                // 代碼區
│  ├──common
│  │  ├──constants
│  │  │  └──CommonConstants.ets      // 公共常量類
│  │  └──util
│  │     └──Logger.ets               // 日志管理工具類
│  ├──entryability
│  │  └──EntryAbility.ts             // 程序入口類
│  └──pages
│     └──LifeCyclePage.ets           // 跳轉頁
└──entry/src/main/resources          // 資源文件目錄

UIAbility生命周期

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

Create狀態 ：在應用首次創建UIAbility實例時觸發，此時系統會調用onCreate()回調。可以在該回調中進行應用初始化操作，例如變量定義資源加載等，用于后續的UI界面展示。

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

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

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

在onWindowStageCreate()回調中通過loadContent()方法設置應用要加載的頁面，并根據需要調用on('windowStageEvent')方法訂閱WindowStage的事件（獲焦/失焦、可見/不可見）。

// EntryAbility.ts
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

export default class EntryAbility extends UIAbility {
  ...
  onWindowStageCreate(windowStage: window.WindowStage): void {
    this.windowStage = windowStage;
    // 設置WindowStage事件訂閱（獲取/失焦、可見/不可見）
    try {
      windowStage.on('windowStageEvent', (data) = > {
        hilog.info(
          this.domain,
          'Succeeded in enabling the listener for window stage event changes. Data: %{public}',
          JSON.stringify(data) ?? ''
        );
      });
    } catch (exception) {
      hilog.error(
        this.domain,
        'Failed to enable the listener for window stage event changes. Cause: %{public}',
        JSON.stringify(exception) ?? ''
      );
    }
    // 設置UI加載
    windowStage.loadContent('pages/LifeCyclePage', (err, data) = > {
      ...
    });
  }
}

Foreground和Background狀態

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

onForeground()回調，在UIAbility的UI界面可見之前，如UIAbility切換至前臺時觸發。可以在onForeground()回調中申請系統需要的資源，或者重新申請在onBackground()中釋放的資源。
onBackground()回調，在UIAbility的UI界面完全不可見之后，如UIAbility切換至后臺時觸發。可以在onBackground()回調中釋放UI界面不可見時無用的資源，或者在此回調中執行較為耗時的操作，例如狀態保存等。

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

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

// EntryAbility.ts
import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
  ...
  onForeground(): void {
    // 申請系統所需的資源或在onBackground中申請釋放的資源
  }

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

Destory狀態

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

例如調用terminateSelf()方法停止當前UIAbility實例，從而完成UIAbility實例的銷毀；或者用戶使用最近任務列表關閉該UIAbility實例，完成UIAbility的銷毀。

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

export default class EntryAbility extends UIAbility {
  ...
  onDestroy(): void | Promise< void > {
    // 釋放系統資源，保存數據
  }
}

自定義組件生命周期

自定義組件的生命周期回調函數用于通知用戶該自定義組件的生命周期，這些回調函數是私有的，在運行時由開發框架在特定的時間進行調用，不能從應用程序中手動調用這些回調函數。

說明：
HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿
允許在生命周期函數中使用Promise和異步回調函數，比如網絡資源獲取，定時器設置等。

新文檔.png
自定義組件的生命周期包括aboutToAppear、onPageShow、onPageHide、onBackPress、aboutToDisappear五種狀態

aboutToAppear
aboutToAppear?(): void
aboutToAppear函數在創建自定義組件的新實例后，在執行其build()函數之前執行。允許在aboutToAppear函數中改變狀態變量，更改將在后續執行build()函數中生效。
aboutToDisappear
aboutToDisappear?(): void
aboutToDisappear函數在自定義組件析構銷毀之前執行。不允許在aboutToDisappear函數中改變狀態變量，特別是@Link變量的修改可能會導致應用程序行為不穩定。
onPageShow
onPageShow?(): void
頁面每次顯示時觸發一次，包括路由過程、應用進入前后臺等場景，僅**@Entry**修飾的自定義組件生效。
onPageHide
onPageHide?(): void
頁面每次隱藏時觸發一次，包括路由過程、應用進入前后臺等場景，僅**@Entry**修飾的自定義組件生效。

onBackPress
onBackPress?(): void
當用戶點擊返回按鈕時觸發，僅**@Entry**裝飾的自定義組件生效。

// LifeCyclePage.ets
@Entry
@Component
struct LifeCyclePage {
  @State textColor: Color = Color.Black;

  aboutToAppear() {
    this.textColor = Color.Blue;
    Logger.info('[LifeCyclePage]  LifeCyclePage aboutToAppear');
  }

  onPageShow() {
    this.textColor = Color.Brown;
    Logger.info('[LifeCyclePage]  LifeCyclePage onPageShow');
  }

  onPageHide() {
    Logger.info('[LifeCyclePage]  LifeCyclePage onPageHide');
  }

  onBackPress() {
    this.textColor = Color.Red;
    Logger.info('[LifeCyclePage]  LifeCyclePage onBackPress');
    return false;
  }

  aboutToDisappear() {
    Logger.info('[LifeCyclePage]  LifeCyclePage aboutToDisappear');
  }

  build() {
    Column() {
      Text($r('app.string.hello_message'))
        .fontSize(CommonConstants.DEFAULT_FONT_SIZE)
        .fontColor(this.textColor)
        .margin(CommonConstants.DEFAULT_MARGIN)
        .fontWeight(FontWeight.Bold)
    }
    .width(CommonConstants.FULL_WIDTH)
  }
}