Harmony os——AbilityStage 组件管理器：我理解的 Module 级「总控台」

Harmony os------AbilityStage 组件管理器：我理解的 Module 级「总控台」

这一篇是我给 AbilityStage 写的学习笔记 + 博客稿。 可以和前面那几篇「应用模型 / UIAbility / 启动模式」放在一个 HarmonyOS 开发系列里。

---

1. AbilityStage 是什么？一句话版本

官方定义有点长，我自己总结一句：

AbilityStage = 一个 Module 级别的组件管理器，是这个 HAP「第一次被加载」时创建的总控类，用来做模块级初始化 + 全局事件监听。

几个关键点：

• 它跟 Module 一一对应：

  • 一个 Module 对应一个 AbilityStage 实例；
  • 比如 entry module 就配一个 MyAbilityStage。

• 它是在该 HAP 第一个 Ability（UIAbility / ExtensionAbility）创建之前被拉起来的；

• 适合做：资源预加载、线程创建、全局环境监听、内存回调处理、指定进程策略、关闭前拦截等。

可以把它想象成：

「这个 Module 的总调度中心」。

---

2. AbilityStage 提供了哪些回调？

AbilityStage 有两类回调：

• 生命周期回调：

  • onCreate()
  • onDestroy()

• 事件回调：

  • onAcceptWant()
  • onConfigurationUpdate()
  • onMemoryLevel()
  • onNewProcessRequest()
  • onPrepareTermination()

我按「开发时常用程度」给它分个类。

2.1 onCreate()：Module 级初始化入口

时机：

• 对应 HAP 首次加载时；
• 在创建这个 Module 的第一个 Ability（UIAbility 或某个 ExtensionAbility）之前，系统先创建 AbilityStage，然后调用 onCreate()。

适合做的事情：

• 模块级资源预加载；
• 启动一些公共线程或任务调度器；
• 注册 Application 级别的监听（比如环境变化、内存回调等）。

示例（简化版）：

 import { AbilityStage } from '@kit.AbilityKit';
 ​
 export default class MyAbilityStage extends AbilityStage {
   onCreate(): void {
     // Module 级初始化，比如资源预加载、线程创建等
     console.info('MyAbilityStage onCreate');
   }
 }

2.2 onAcceptWant()：和 UIAbility 指定实例模式配套使用

这个回调专门用在 UIAbility 的 specified 启动模式 场景下。

• 当某个 UIAbility 以 launchType: "specified" 启动时，系统会：

  1. 先进入对应 Module 的 AbilityStage.onAcceptWant(want)；

  2. 由你在这里返回一个字符串 Key；

  3. 系统用这个 Key 去匹配已有的 UIAbility 实例：

     • 有匹配的 → 复用旧实例，触发 onNewWant()；
     • 无匹配的 → 创建一个新实例，走 onCreate() + onWindowStageCreate()。

因此：

onAcceptWant 的返回值 = UIAbility 实例的标识字符串。

示例里的最简写法：

 import { AbilityStage, Want } from '@kit.AbilityKit';
 ​
 export default class MyAbilityStage extends AbilityStage {
   onAcceptWant(want: Want): string {
     // 指定实例模式下由你返回实例标识
     return 'MyAbilityStage';
   }
 }

实际业务中可以按 want.parameters 拼出更细的 key，前面 UIAbility 启动模式那篇里已经有详细例子。

---

2.3 onConfigurationUpdate()：环境变化监听（语言 / 主题 / 方向）

这个和 EnvironmentCallback 搭配尤为常用，适合做「系统配置变化 → 应用整体适配」。

系统环境变化时会触发：

• 语言变更；
• 深色 / 浅色模式切换；
• 屏幕方向变更；
• 字号缩放；
• 字重缩放等。

你可以在 AbilityStage 的 onCreate() 里注册环境监听：

 import { EnvironmentCallback, AbilityStage } from '@kit.AbilityKit';
 import { BusinessError } from '@kit.BasicServicesKit';
 ​
 export default class MyAbilityStage extends AbilityStage {
   onCreate(): void {
     console.info('AbilityStage onCreate');
 ​
     const envCallback: EnvironmentCallback = {
       onConfigurationUpdated(config) {
         console.info(`onConfigurationUpdated: ${JSON.stringify(config)}`);
         const language = config.language;           // 当前语言
         const colorMode = config.colorMode;         // 深 / 浅色模式
         const direction = config.direction;         // 屏幕方向
         const fontSizeScale = config.fontSizeScale; // 字体大小缩放
         const fontWeightScale = config.fontWeightScale; // 字体粗细缩放
         // 可以在这里触发一些全局 UI 适配逻辑
       },
       onMemoryLevel(level) {
         console.info(`onMemoryLevel level: ${level}`);
       }
     };
 ​
     try {
       const applicationContext = this.context.getApplicationContext();
       const callbackId = applicationContext.on('environment', envCallback);
       console.info(`env callbackId: ${callbackId}`);
     } catch (error) {
       console.error(
         `env callback error: ${(error as BusinessError).code}, ${(error as BusinessError).message}`
       );
     }
   }
 ​
   onDestroy(): void {
     console.info('AbilityStage onDestroy');
   }
 }

小心得： 如果你的应用有「多语言切换、主题联动、字体大小适配」这类全局需求，用 AbilityStage + EnvironmentCallback 会比在单个 UIAbility 中东一块西一块强很多。

---

2.4 onMemoryLevel()：系统内存吃紧时的自救机会

当系统内存紧张时会触发这个回调。

• 比如应用退到后台后还占着一堆内存；
• 系统会通过 onMemoryLevel() 通知你当前内存压力等级；
• 你可以主动释放一些不关键的资源（缓存大图、预加载数据等）。

好处是：

主动配合系统回收内存，有助于避免进程被系统直接 kill，提升应用整体稳定性。

上面的 envCallback 中其实已经演示了 onMemoryLevel() 的写法。

---

2.5 onNewProcessRequest()：控制 UIAbility 运行在哪个进程

这个回调是给 「多进程策略」 用的，场景会比较高级。

• 当某个 UIAbility 启动时，系统会回调 onNewProcessRequest()；

• 你可以返回一个「进程标识字符串」：

  • 若该标识对应的进程已经存在 → 复用；
  • 若不存在 → 创建新进程；

• 要启用这个能力，需要在 module.json5 里先配置：

 {
   "module": {
     // ...
     "isolationProcess": true
   }
 }

典型用途：

• 把某些高风险 / 高资源消耗的 UIAbility 放到单独进程中跑；
• 做类似「文档编辑进程」这种隔离。

---

2.6 onPrepareTermination()：应用关闭前的最后挽留

当用户「关闭应用」时，系统会先回调 onPrepareTermination()。

• 你可以在这里决定：

  • 是否立刻允许关闭；
  • 还是告诉系统「先不要关」，比如先弹个对话框问用户是否保存草稿。

• 返回值是 AbilityConstant.PrepareTermination 中的枚举，告诉系统继续关还是中断关闭动作。

典型场景：

• 用户正在编辑重要内容（文档、填表、写作业...）；
• 用户从最近任务一划而过；
• 你在 onPrepareTermination() 里检测到有未保存内容 → 先阻止关闭，给 UIAbility 发通知弹窗。

2.7 onDestroy()：Module 正常销毁时的收尾

• 当对应 Module 的 最后一个 Ability 实例退出，并且应用以「正常方式」销毁时触发；
• 可以在这里做一些模块级的资源释放、取消注册等。

注意两个不会触发的情况：

• 应用异常崩溃；
• 被系统强制终止。

这两种情况onDestroy()都不会执行，所以特别关键的数据仍然要在各 Ability 自己的生命周期里保存。

---

3. 如何在工程中启用 AbilityStage？

默认模板里是不会自动创建 AbilityStage 的，需要你自己手动加一份。

3.1 创建 AbilityStage 文件

1. 在某个 Module 的 ets 目录下新建目录 比如：ets/myabilitystage/
2. 新建 ArkTS 文件：MyAbilityStage.ets
3. 继承 AbilityStage，实现所需回调：

 import { AbilityStage, Want } from '@kit.AbilityKit';
 ​
 export default class MyAbilityStage extends AbilityStage {
   onCreate(): void {
     console.info('MyAbilityStage onCreate');
     // 模块初始化逻辑
   }
 ​
   onAcceptWant(want: Want): string {
     // 仅在 specified 启动模式下会触发
     return 'MyAbilityStage';
   }
 }

3.2 在 module.json5 里绑定入口

srcEntry 指定这个 Module 对应的 AbilityStage 入口：

 {
   "module": {
     "name": "entry",
     "type": "entry",
     "srcEntry": "./ets/myabilitystage/MyAbilityStage.ets",
     // ...
   }
 }

这样，当这个 HAP 第一次被加载时，就会先走 MyAbilityStage.onCreate()，你的模块级逻辑就能接管整体节奏了。

---

4. 我会怎么在项目里用 AbilityStage？

结合前面几篇 Stage 模型、UIAbility、ExtensionAbility 的内容，我自己会把 AbilityStage 看成一个「模块级中控」，用来集中处理：

1. 模块初始化

   • 注册环境变化监听（语言/主题/字体等）；
   • 初始化一些全局单例，比如日志、埋点、配置中心。

2. 全局事件/配置监听

   • 用 EnvironmentCallback 处理深浅色联动；
   • 用 onMemoryLevel 做内存压缩策略。

3. UIAbility 启动策略

   • 结合 onAcceptWant() + launchType: specified 做多文档/多实例管理；
   • 通过 onNewProcessRequest() 控制哪些 Ability 跑独立进程。

4. 关闭前的拦截

   • 在 onPrepareTermination() 给整个 App 做一次「善后机会」：

     • 未同步的数据提示用户；
     • 清理某些后台任务；
     • 重要日志 flush。

---

5. 小结

如果用一句比较形象的话来收尾：

UIAbility 负责「这一个窗口怎么跑」，ExtensionAbility 负责「某个扩展场景怎么跑」， 而 AbilityStage 则站在 Module 的视角，负责「这一整包能力怎么被初始化、管理和收尾」。

在 HarmonyOS NEXT 的 Stage 模型下， AbilityStage 其实是一个非常关键但容易被忽略的点------ 用好了，它能让你的应用模块结构更清晰，行为更可控，也更「系统级」。