HarmonyOS UIAbility 组件完全指南：生命周期与开发基础
引言
在 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 步骤
在工程根目录右键，点击
New。点击
Module进入新建 Module 流程。选择
Empty Ability模板，点击Next。配置 Module 名称、类型、支持设备类型。
设置 UIAbility 名称，配置
exported属性（标识当前 UIAbility 是否可被其他应用拉起）。点击
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 组件的基础知识：
UIAbility 定义：包含用户界面的应用组件，用于与用户交互，是系统调度的单元，提供窗口用于界面绘制，每个实例对应最近任务列表中的一个任务项。
生命周期流程：完整的生命周期为
Create → WindowStageCreate → Foreground ⇄ Background → WindowStageWillDestroy → WindowStageDestroy → Destroy。每个回调都有特定的触发时机和开发用途，掌握这些是 HarmonyOS 开发的核心考点。工程目录结构：包括配置文件（
app.json5）、ArkTS 源码文件（ets目录）、资源文件（resources目录）以及编译构建配置文件（build-profile.json5、hvigorfile.ts、obfuscation-rules.txt、oh-package.json5）。UIAbility 开发基本用法：通过
Empty Ability模板创建 UIAbility，在module.json5中配置相关属性；页面创建后需在路由配置文件中添加路由信息；必须在onWindowStageCreate中调用loadContent指定启动页，否则会出现白屏。