Open Harmony 能力增强：Stage 模型下 UIAbility 生命周期完整解析 🚀

前言 🌟

在 OpenHarmony / HarmonyOS 应用开发中，UIAbility 是应用页面能力的核心入口。很多初学者会先关注 ArkUI 页面怎么写，但真正把应用跑起来、切到前台、退到后台、加载首页、释放窗口资源时，都会绕不开 UIAbility 生命周期。

本文基于当前项目中的真实代码展开，不虚构复杂业务场景。当前项目是一个 Stage 模型的 ArkTS 应用，入口 Ability 位于：

entry/src/main/ets/entryability/EntryAbility.ets

页面位于：

entry/src/main/ets/pages/Index.ets

本文重点不是“做一个很炫的页面”，而是把应用启动和页面加载这条主链路讲清楚。理解这部分后，再去做沉浸式页面、复杂路由、多页面业务，会更稳。

项目中的入口结构 📱

当前项目的 module.json5 中指定了主入口：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true
      }
    ]
  }
}

这段配置说明了几件事：

1. 当前模块是 entry 类型模块。
2. 应用主入口是 EntryAbility。
3. EntryAbility 的源码位置是 ./ets/entryability/EntryAbility.ets。
4. 这个 Ability 通过 skills 配置承接桌面入口启动。

也就是说，当用户点击应用图标时，系统会根据配置找到 EntryAbility，再由它加载具体页面。

UIAbility 的创建阶段 ⚙️

项目中的核心代码如下：

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    try {
      this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    } catch (err) {
      hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
    }
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
  }
}

onCreate 是 Ability 创建时的重要回调。当前项目在这里做了两件事：

第一，设置应用颜色模式：

this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);

这里使用的是 COLOR_MODE_NOT_SET，含义是应用本身不强行指定某一种颜色模式，而是交给系统环境处理。对于后续适配深色模式、跟随系统主题来说，这是一个比较稳妥的起点。

第二，使用 hilog 输出日志：

hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');

日志在实际开发中非常重要。尤其是生命周期问题，有时页面没有显示，不一定是页面代码写错，也可能是 Ability 没有进入预期阶段。通过日志可以快速定位执行链路。

窗口创建与首页加载 🧩

真正把 ArkUI 页面加载出来的是 onWindowStageCreate：

onWindowStageCreate(windowStage: window.WindowStage): void {
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');

  windowStage.loadContent('pages/Index', (err) => {
    if (err.code) {
      hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
      return;
    }
    hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
  });
}

这里的关键点是：

windowStage.loadContent('pages/Index', ...)

pages/Index 对应当前项目中的页面文件：

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    RelativeContainer() {
      Text(this.message)
        .id('HelloWorld')
    }
    .height('100%')
    .width('100%')
  }
}

也就是说，EntryAbility 负责生命周期与窗口，Index.ets 负责页面展示。这种职责拆分非常清楚：Ability 管入口，页面管 UI。

前后台切换 🔄

当前项目中还保留了前后台生命周期日志：

onForeground(): void {
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
}

onBackground(): void {
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
}

这两个方法在真实项目中很常用。例如：

1. 应用回到前台时刷新必要数据。
2. 应用进入后台时暂停动画或停止不必要任务。
3. 页面涉及音视频、定位、网络轮询时，根据前后台状态控制资源使用。

当前项目没有接入这些复杂逻辑，所以这里只做日志记录。这是符合实际情况的：基础工程先保留生命周期钩子，后续业务扩展时再接入真实逻辑。

销毁阶段与资源释放 🧹

项目中也有 onWindowStageDestroy 和 onDestroy：

onWindowStageDestroy(): void {
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
}

onDestroy(): void {
  hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
}

当前代码没有持有复杂资源，所以没有额外释放逻辑。但如果后续加入监听器、长连接、下载任务、定时任务，就应该结合这些生命周期做清理。

尤其要注意一点：生命周期不是用来堆业务代码的。更推荐的方式是把网络请求、数据处理、缓存逻辑放到 service 或 store 中，Ability 只负责调度和入口管理。

从当前项目可以总结出的开发经验 ✅

当前项目虽然还是基础模板，但已经具备一条完整链路：

1. module.json5 声明入口 Ability。
2. EntryAbility 创建并配置颜色模式。
3. onWindowStageCreate 加载 pages/Index。
4. Index.ets 使用 ArkUI 构建页面。
5. 前后台和销毁阶段通过 hilog 输出日志。

这条链路对 OpenHarmony 应用非常关键。后续无论是做内容流、个人中心、设置页，还是接入更复杂的系统能力，都应该先保证这条入口链路清晰稳定。

总结 🚀

这篇文章对应“四大主题”中的 能力增强。它没有夸大项目能力，而是基于真实项目代码，把 Stage 模型下 UIAbility 的启动、窗口创建、页面加载、前后台切换和销毁流程梳理了一遍。

对于初学者来说，先理解 UIAbility，再写复杂页面，会少走很多弯路。对于实际项目来说，生命周期日志、入口配置和页面加载路径，也是排查问题时最先检查的地方。

参考资料：

• HarmonyOS 官方文档：UIAbility 生命周期
• HarmonyOS 官方文档：Stage 模型应用开发
• 当前项目文件：EntryAbility.ets、Index.ets、module.json5