HarmonyOS開(kāi)發(fā)案例：【UIAbility和自定義組件生命周期】

介紹

本文檔主要描述了應(yīng)用運(yùn)行過(guò)程中UIAbility和自定義組件的生命周期。對(duì)于UIAbility，描述了Create、Foreground、Background、Destroy四種生命周期。對(duì)于頁(yè)面和自定義組件描述了aboutToAppear、onPageShow、onPageHide、onBackPress、aboutToDisappear五種生命周期。

相關(guān)概念

• [UIAbility]：UIAbility是包含UI界面的應(yīng)用組件，提供組件創(chuàng)建、銷(xiāo)毀、前后臺(tái)切換等生命周期回調(diào)，同時(shí)也具備組件協(xié)同的能力。
• [自定義組件的生命周期]：自定義組件的生命周期回調(diào)函數(shù)用于通知用戶該自定義組件的生命周期，這些回調(diào)函數(shù)是私有的，在運(yùn)行時(shí)由開(kāi)發(fā)框架在特定的時(shí)間進(jìn)行調(diào)用，不能從應(yīng)用程序中手動(dòng)調(diào)用這些回調(diào)函數(shù)。
• [窗口開(kāi)發(fā)指導(dǎo)]：窗口模塊用于在同一塊物理屏幕上，提供多個(gè)應(yīng)用界面顯示、交互的機(jī)制。

環(huán)境搭建

軟件要求

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

硬件要求

• 開(kāi)發(fā)板類(lèi)型：[潤(rùn)和RK3568開(kāi)發(fā)板]。
• OpenHarmony系統(tǒng)：3.2 Release。

環(huán)境搭建

完成本篇Codelab我們首先要完成開(kāi)發(fā)環(huán)境的搭建，本示例以RK3568開(kāi)發(fā)板為例，參照以下步驟進(jìn)行：

1. [獲取OpenHarmony系統(tǒng)版本]：標(biāo)準(zhǔn)系統(tǒng)解決方案（二進(jìn)制）。以3.2 Release版本為例：
   
2. 搭建燒錄環(huán)境。
   1. [完成DevEco Device Tool的安裝]
   2. [完成RK3568開(kāi)發(fā)板的燒錄](méi)
3. 搭建開(kāi)發(fā)環(huán)境。
   1. 開(kāi)始前請(qǐng)參考[工具準(zhǔn)備]，完成DevEco Studio的安裝和開(kāi)發(fā)環(huán)境配置。
   2. 開(kāi)發(fā)環(huán)境配置完成后，請(qǐng)參考[使用工程向?qū)創(chuàng)建工程（模板選擇“Empty Ability”）。
   3. 工程創(chuàng)建完成后，選擇使用[真機(jī)進(jìn)行調(diào)測(cè)]。
   4. 開(kāi)發(fā)前請(qǐng)熟悉鴻蒙開(kāi)發(fā)指導(dǎo)文檔：[复制gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

代碼結(jié)構(gòu)解讀

本篇Codelab只對(duì)核心代碼進(jìn)行講解，對(duì)于完整代碼，我們會(huì)在gitee中提供。

复制├──entry/src/main/ets                // 代碼區(qū)
│  ├──common
│  │  ├──constants
│  │  │  └──CommonConstants.ets      // 公共常量類(lèi)
│  │  └──util
│  │     └──Logger.ets               // 日志管理工具類(lèi)
│  ├──entryability
│  │  └──EntryAbility.ts             // 程序入口類(lèi)
│  └──pages
│     └──LifeCyclePage.ets           // 跳轉(zhuǎn)頁(yè)
└──entry/src/main/resources          // 資源文件目錄

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

UIAbility生命周期

當(dāng)用戶打開(kāi)、切換和返回到應(yīng)用時(shí)，UIAbility實(shí)例會(huì)在其生命周期的不同狀態(tài)之間轉(zhuǎn)換。UIAbility類(lèi)提供了一系列回調(diào)，通過(guò)這些回調(diào)可以知道當(dāng)前UIAbility實(shí)例的某個(gè)狀態(tài)發(fā)生改變，UIAbility實(shí)例的創(chuàng)建和銷(xiāo)毀，或者UIAbility實(shí)例發(fā)生了前后臺(tái)的狀態(tài)切換。Create、Foreground、Background、Destroy四個(gè)狀態(tài)：

Create狀態(tài) ：在應(yīng)用首次創(chuàng)建UIAbility實(shí)例時(shí)觸發(fā)，此時(shí)系統(tǒng)會(huì)調(diào)用onCreate()回調(diào)?？梢栽谠摶卣{(diào)中進(jìn)行應(yīng)用初始化操作，例如變量定義資源加載等，用于后續(xù)的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 {
    // 初始化應(yīng)用
    ...
  }
  ...
}

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

在onWindowStageCreate()回調(diào)中通過(guò)loadContent()方法設(shè)置應(yīng)用要加載的頁(yè)面，并根據(jù)需要調(diào)用on('windowStageEvent')方法訂閱WindowStage的事件（獲焦/失焦、可見(jiàn)/不可見(jiàn)）。

复制// 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;
    // 設(shè)置WindowStage事件訂閱（獲取/失焦、可見(jiàn)/不可見(jiàn)）
    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) ?? ''
      );
    }
    // 設(shè)置UI加載
    windowStage.loadContent('pages/LifeCyclePage', (err, data) = > {
      ...
    });
  }
}

Foreground和Background狀態(tài)

Foreground和Background狀態(tài)分別在UIAbility實(shí)例切換至前臺(tái)和切換至后臺(tái)時(shí)觸發(fā)，對(duì)應(yīng)于onForeground()回調(diào)和onBackground()回調(diào)。

• onForeground()回調(diào)，在UIAbility的UI界面可見(jiàn)之前，如UIAbility切換至前臺(tái)時(shí)觸發(fā)?？梢栽趏nForeground()回調(diào)中申請(qǐng)系統(tǒng)需要的資源，或者重新申請(qǐng)?jiān)趏nBackground()中釋放的資源。
• onBackground()回調(diào)，在UIAbility的UI界面完全不可見(jiàn)之后，如UIAbility切換至后臺(tái)時(shí)觸發(fā)?？梢栽趏nBackground()回調(diào)中釋放UI界面不可見(jiàn)時(shí)無(wú)用的資源，或者在此回調(diào)中執(zhí)行較為耗時(shí)的操作，例如狀態(tài)保存等。

例如應(yīng)用在使用過(guò)程中需要使用用戶定位時(shí)，假設(shè)應(yīng)用已獲得用戶的定位權(quán)限授權(quán)。在UI界面顯示之前，可以在onForeground()回調(diào)中開(kāi)啟定位功能，從而獲取到當(dāng)前的位置信息。

當(dāng)應(yīng)用切換到后臺(tái)狀態(tài)，可以在onBackground()回調(diào)中停止定位功能，以節(jié)省系統(tǒng)的資源消耗。

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

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

  onBackground(): void {
    // UI不可見(jiàn)時(shí)釋放無(wú)用資源，或在此回調(diào)中執(zhí)行耗時(shí)操作
    // 例如，狀態(tài)保存
  }
}

Destory狀態(tài)

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

例如調(diào)用terminateSelf()方法停止當(dāng)前UIAbility實(shí)例，從而完成UIAbility實(shí)例的銷(xiāo)毀；或者用戶使用最近任務(wù)列表關(guān)閉該UIAbility實(shí)例，完成UIAbility的銷(xiāo)毀。

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

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

自定義組件生命周期

自定義組件的生命周期回調(diào)函數(shù)用于通知用戶該自定義組件的生命周期，這些回調(diào)函數(shù)是私有的，在運(yùn)行時(shí)由開(kāi)發(fā)框架在特定的時(shí)間進(jìn)行調(diào)用，不能從應(yīng)用程序中手動(dòng)調(diào)用這些回調(diào)函數(shù)。

說(shuō)明：

• 允許在生命周期函數(shù)中使用Promise和異步回調(diào)函數(shù)，比如網(wǎng)絡(luò)資源獲取，定時(shí)器設(shè)置等。

自定義組件的生命周期包括aboutToAppear、onPageShow、onPageHide、onBackPress、aboutToDisappear五種狀態(tài)

• aboutToAppear
  aboutToAppear?(): void
  aboutToAppear函數(shù)在創(chuàng)建自定義組件的新實(shí)例后，在執(zhí)行其build()函數(shù)之前執(zhí)行。允許在aboutToAppear函數(shù)中改變狀態(tài)變量，更改將在后續(xù)執(zhí)行build()函數(shù)中生效。
• aboutToDisappear
  aboutToDisappear?(): void
  aboutToDisappear函數(shù)在自定義組件析構(gòu)銷(xiāo)毀之前執(zhí)行。不允許在aboutToDisappear函數(shù)中改變狀態(tài)變量，特別是@Link變量的修改可能會(huì)導(dǎo)致應(yīng)用程序行為不穩(wěn)定。
• onPageShow
  onPageShow?(): void
  頁(yè)面每次顯示時(shí)觸發(fā)一次，包括路由過(guò)程、應(yīng)用進(jìn)入前后臺(tái)等場(chǎng)景，僅**@Entry**修飾的自定義組件生效。
• onPageHide
  onPageHide?(): void
  頁(yè)面每次隱藏時(shí)觸發(fā)一次，包括路由過(guò)程、應(yīng)用進(jìn)入前后臺(tái)等場(chǎng)景，僅**@Entry**修飾的自定義組件生效。
• onBackPress
  onBackPress?(): void
  當(dāng)用戶點(diǎn)擊返回按鈕時(shí)觸發(fā)，僅**@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)
    }
  }
  

審核編輯 黃宇