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节点中配置属性说明nameUIAbility 组件的类名srcEntryUIAbility 组件的代码路径descriptionUIAbility 组件的描述信息icon/labelUIAbility 的图标和显示名称创建页面与指定启动页入口页面新建工程默认在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指定启动页否则会出现白屏。