引言

在 HarmonyOS 应用开发中，UIAbility 是包含用户界面的核心应用组件，负责与用户交互、管理界面生命周期、处理用户操作以及协调页面跳转与数据传递。无论是通过桌面图标启动应用，还是从最近任务列表返回应用，这些交互都基于 UIAbility 实现。本节课将系统讲解 UIAbility 的基础概念、完整生命周期流程、工程目录结构以及 UIAbility 的创建与页面配置方法。

核心内容

UIAbility 基础概念

定义：UIAbility 是 HarmonyOS 中一种包含用户界面的应用组件，核心作用是与用户交互，负责管理界面生命周期、处理用户操作、协调页面跳转与数据传递。

核心定位：UIAbility 是系统调度应用的单元，每一个 UIAbility 实例会在最近任务列表中对应一个任务项，并且会为界面绘制提供独立窗口。

应用场景示例：

• 天气应用：打开应用后主界面由 UIAbility 管理，同时在最近任务列表生成对应任务项。

• 桌面点击图标启动应用、从最近任务列表返回应用，界面交互都基于 UIAbility 实现。

UIAbility 生命周期流程

掌握 UIAbility 的生命周期对于应用开发非常重要。UIAbility 组件的核心生命周期包括 Create、Foreground、Background、Destroy 四个状态。作为包含 UI 的应用组件，UIAbility 的生命周期与 WindowStage 的生命周期存在联系。

完整生命周期流程：

UIAbility Start → Create → WindowStageCreate → Foreground ⇄ Background → WindowStageWillDestroy → WindowStageDestroy → Destroy → UIAbility End

各生命周期回调详解

1. onCreate(want: Want, launchParam: AbilityConstant.LaunchParam)

• 触发时机：UIAbility 实例创建完成时触发。

• 开发用途：应用预初始化，进行变量定义、全局资源加载，为后续 UI 展示做准备。

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        // 应用初始化阶段，可以进行资源加载
        // ...
    }
    // ...
}

2. onWindowStageCreate(windowStage: window.WindowStage)

• 触发时机：WindowStage 创建完成后触发，每个 UIAbility 实例会绑定一个 WindowStage。

• 概念补充：WindowStage 是 UIAbility 的窗口管理器，负责窗口创建、销毁、显示与属性控制，持有主窗口为 UI 提供绘制区域。

• 开发用途：加载 UI 页面、订阅 WindowStage 事件（如获焦/失焦、可见/不可见）。

onWindowStageCreate(windowStage: window.WindowStage) {
    // 设置 UI 页面加载
    // 设置 WindowStage 的事件订阅（获焦/失焦、可见/不可见）
    // ...
    windowStage.loadContent('pages/Index', (err, data) => {
        // ...
    });
}

3. onForeground()

• 触发时机：UIAbility 切换至前台、UI 渲染完成前触发。

• 开发用途：申请系统需要的资源，或者重新申请在 onBackground 中释放的资源。

• 示例：需要获取用户定位时，在该回调中开启定位功能获取位置。

onForeground() {
    // 申请系统需要的资源，或者重新申请在 onBackground 中释放的资源
    // ...
}

4. onBackground()

• 触发时机：UIAbility 切换至后台，UI 完全不可见后触发。

• 开发用途：释放 UI 页面不可见时无用的资源、保存应用状态，降低系统资源消耗。

• 示例：定位应用切后台后，在该回调中停止定位节省资源。

onBackground() {
    // 释放 UI 页面不可见时无用的资源，或者在此回调中执行较为耗时的操作
    // 例如状态保存等
    // ...
}

5. onWindowStageWillDestroy()

• 触发时机：WindowStage 销毁前触发，此时 WindowStage 仍可使用。

• 开发用途：释放通过 WindowStage 对象获取的资源，注销 WindowStage 的事件订阅。

onWindowStageWillDestroy() {
    // 释放通过 windowStage 对象获取的资源
    // ...
}

6. onWindowStageDestroy()

• 触发时机：WindowStage 销毁后执行，此时 WindowStage 不可再使用。

• 开发用途：释放 UI 相关资源，注销获焦失焦等 WindowStage 事件。

7. onDestroy()

• 触发时机：UIAbility 实例销毁前触发（如用户从最近任务列表关闭应用）。

• 开发用途：释放系统资源、保存应用数据等收尾工作。

onDestroy() {
    // 系统资源的释放、数据的保存等
    // ...
}

HarmonyOS 工程目录结构

文件类型	说明
配置文件	包含应用级和 Module 级配置：AppScope > app.json5 存储全局配置（应用 Bundle 名称、应用名称、应用图标、应用版本号等）；AppScope > resources 存放应用全局需要的资源文件
ArkTS 源码文件	Module_name > src > main > ets 存放当前 Module 的 ArkTS 源代码（.ets 文件）
资源文件	Module_name > src > main > resources 存放应用需要的各类资源，支持图形、多媒体、字符串、布局文件等
其他配置文件	编译构建相关配置：build-profile.json5（工程/Module 级构建配置，包含应用签名、产品配置）、hvigorfile.ts（编译构建任务脚本）、obfuscation-rules.txt（混淆规则）、oh-package.json5（存储依赖库信息，包含第三方库和共享包依赖）

UIAbility 开发基本用法

创建 UIAbility 步骤

1. 在工程根目录右键，点击 New。

2. 点击 Module 进入新建 Module 流程。

3. 选择 Empty Ability 模板，点击 Next。

4. 配置 Module 名称、类型、支持设备类型。

5. 设置 UIAbility 名称，配置 exported 属性（标识当前 UIAbility 是否可被其他应用拉起）。

6. 点击 Finish 完成创建。

UIAbility 配置说明

在 module.json5 的 ability 节点中配置：

属性	说明
name	UIAbility 组件的类名
srcEntry	UIAbility 组件的代码路径
description	UIAbility 组件的描述信息
icon / label	UIAbility 的图标和显示名称

创建页面与指定启动页

• 入口页面：新建工程默认在 pages 目录生成 Index.ets 作为 UIAbility 的入口页面，一个页面有且仅有一个 @Entry 装饰的入口组件。

• 新建页面：右键 pages 目录新建 .ets 页面文件，需要在路由配置文件中手动添加路由信息。

• 指定启动页：必须在 onWindowStageCreate 回调中通过 windowStage.loadContent() 指定启动页面，否则应用启动后会出现白屏。默认创建 UIAbility 时会自动加载 pages/Index，需要修改时替换方法中的页面路径即可。

总结

本节课学习了 UIAbility 组件的基础知识：

1. UIAbility 定义：包含用户界面的应用组件，用于与用户交互，是系统调度的单元，提供窗口用于界面绘制，每个实例对应最近任务列表中的一个任务项。

2. 生命周期流程：完整的生命周期为 Create → WindowStageCreate → Foreground ⇄ Background → WindowStageWillDestroy → WindowStageDestroy → Destroy。每个回调都有特定的触发时机和开发用途，掌握这些是 HarmonyOS 开发的核心考点。

3. 工程目录结构：包括配置文件（app.json5）、ArkTS 源码文件（ets 目录）、资源文件（resources 目录）以及编译构建配置文件（build-profile.json5、hvigorfile.ts、obfuscation-rules.txt、oh-package.json5）。

4. UIAbility 开发基本用法：通过 Empty Ability 模板创建 UIAbility，在 module.json5 中配置相关属性；页面创建后需在路由配置文件中添加路由信息；必须在 onWindowStageCreate 中调用 loadContent 指定启动页，否则会出现白屏。