【HarmonyOS 5】鴻蒙中的UIAbility詳解（一）

一、UIAbility是什么？

Stage模型中的組件類型名，即UIAbility組件，包含UI，提供展示UI的能力，主要用于和用戶交互。

UIAbility類似于傳統移動開發Android中的Activity或者Fragment。類似IOS開發中的 UIViewController。

UIAbility 是 HarmonyOS 應用框架的核心組件，負責管理應用的用戶界面生命周期和上下文信息。

二、設置指定啟動頁面

啟動頁面必須設置：否則應用啟動后會白屏。

避免應用啟動后白屏，需在onWindowStageCreate生命周期中設置默認加載頁面。通過WindowStage的loadContent()方法指定頁面路徑。

export default class EntryAbility extends UIAbility {onWindowStageCreate(windowStage: window.WindowStage): void {windowStage.loadContent('pages/Index', (err, data) => { /* 處理回調 */ });}
}

DevEco Studio默認生成的項目會自動加載Index頁面，可按需修改路徑。

三、獲取上下文信息（UIAbilityContext）

獲取應用配置信息（如包名、Ability名稱等），或調用操作Ability的方法（如啟動、終止Ability）。通過this.context直接訪問。

export default class EntryAbility extends UIAbility {onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {const context = this.context; // 直接獲取上下文}
}

在頁面組件中獲取：
通過getUIContext().getHostContext()轉換為UIAbilityContext。

@Entry
@Component
struct Page {private context = this.getUIContext().getHostContext() as common.UIAbilityContext;startAbilityTest() { this.context.startAbility(want); } // 啟動其他Ability
}

啟動頁面設置與上下文使用代碼示例

// UIAbility定義
export default class EntryAbility extends UIAbility {onWindowStageCreate(windowStage: window.WindowStage) {windowStage.loadContent('pages/Main', () => {}); // 設置啟動頁面}onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {const context = this.context; // 獲取上下文context.startAbility({ abilityName: 'OtherAbility' }); // 啟動其他Ability}
}// 頁面組件中使用上下文
@Entry
@Component
struct MainPage {private context = this.getUIContext().getHostContext() as common.UIAbilityContext;build() {Button('終止當前Ability').onClick(() => this.context.terminateSelf());}
}

四、UIAbility生命周期與操作

UIAbility的生命周期包含 Create（創建）、Foreground（前臺）、Background（后臺）、Destroy（銷毀） 四個核心狀態，以及與窗口（WindowStage）相關的子狀態。通過生命周期回調鉤子函數，可監聽狀態變化并執行對應操作。

生命周期狀態流轉圖

創建實例          窗口創建       進入前臺         切到后臺         窗口銷毀       實例銷毀↓               ↓             ↓               ↓               ↓             ↓
onCreate() → onWindowStageCreate() → onForeground() → onBackground() → onWindowStageDestroy() → onDestroy()↑       ↖                ↗                ↖                ↑└─────── WindowStageWillDestroy() ────────────────────────┘

1、onCreate

UIAbility實例創建完成時觸發。初始化頁面數據、加載資源（如定義變量、獲取上下文this.context）。

export default class EntryAbility extends UIAbility {onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {// 初始化操作（如獲取上下文、配置數據）const context = this.context; }
}

2、WindowStageCreate

UIAbility實例創建后，進入前臺前，系統創建WindowStage時觸發。設置啟動頁面（loadContent()）、訂閱窗口事件（如前后臺切換、焦點變化）。

onWindowStageCreate(windowStage: window.WindowStage) {windowStage.loadContent('pages/Index'); // 設置啟動頁面windowStage.on('windowStageEvent', (event) => { // 訂閱窗口事件switch (event) {case window.WindowStageEventType.SHOWN: // 切到前臺console.log('窗口切到前臺');break;}});}

3、WindowStageWillDestroy

WindowStage銷毀前觸發（此時窗口仍可用）。釋放通過WindowStage獲取的資源，注銷事件訂閱（off('windowStageEvent')）。

4、WindowStageDestroy

WindowStage銷毀時觸發（UI資源釋放）。釋放UI相關資源（如臨時文件、圖形對象）。

5、Foreground

UIAbility切換至前臺、UI可見前觸發。申請系統資源（如定位、傳感器權限）、恢復后臺釋放的資源。

    onForeground() {// 開啟定位功能location.start(); }

6、Background

UIAbility切換至后臺、UI完全不可見后觸發。釋放無用資源、執行耗時操作（如數據持久化）。

    onBackground() {// 停止定位、保存當前狀態location.stop(); saveDataToLocal();}

7、onDestroy

UIAbility實例被終止時觸發（如調用terminateSelf()）。釋放全局資源、清理內存（如關閉網絡連接、注銷監聽器）。

onDestroy() {// 釋放數據庫連接、取消定時器db.close(); clearInterval(timer);
}

注意：API 13+中，若用戶通過最近任務一鍵清理應用，不會觸發onDestroy()，而是直接終止進程。

四、UIAbility的常用函數操作

1. 終止UIAbility實例

調用terminateSelf()終止當前Ability。

context.terminateSelf((err) => {if (err) { console.error('終止失敗:', err); } else { console.info('終止成功'); }
});

2. 獲取拉起方信息

當UIAbilityA通過startAbility啟動UIAbilityB時，UIAbilityB可獲取調用方信息。

export default class UIAbilityB extends UIAbility {onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {console.log(`調用方Pid: ${want.parameters?.['ohos.aafwk.param.callerPid']}`);}
}

跨Ability信息傳遞代碼示例

// UIAbilityA中啟動UIAbilityB
@Entry
@Component
struct UIAbilityAPage {private context = this.getUIContext().getHostContext() as common.UIAbilityContext;build() {Button('拉起UIAbilityB').onClick(() => {this.context.startAbility({ bundleName: this.context.abilityInfo.bundleName, abilityName: 'UIAbilityB' });});}
}// UIAbilityB中獲取調用方信息
export default class UIAbilityB extends UIAbility {onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {console.log(`調用方包名: ${want.parameters?.['ohos.aafwk.param.callerBundleName']}`);}
}

注意

當UIAbility設置為singleton啟動模式時，重復調用startAbility()啟動同一實例，不會重新走onCreate和onWindowStageCreate流程，而是觸發onNewWant回調。

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {// 根據新的Want參數更新頁面數據this.data = want.parameters?.data; 
}