1.HarmonyOS开发学习入门-Stage模型

一、Stage模型

Stage 模型是为了适应多设备、多窗口、多Ability、分布式协同场景而设计的新一代应用运行架构。

1.逻辑结构

HarmonyOS Stage 模型逻辑结构

应用模型的逻辑结构表达的是 HarmonyOS 应用运行时的逻辑层级，其中Application 是整个应用的最高层逻辑概念（整个应用的逻辑根），它代表的是一个完整应用。

Application 下面主要包含三类内容：AppScope、Module、Feature Module。

  1. AppScope 是应用全局的配置区域（身份证），对应工程中的典型位置是：AppScope/app.json5。
  2. Module 是应用的功能承载单元，不是页面，也不是组件，而是比页面更高一级的功能容器。
    1. AbilityStage 是 Module 的运行入口和生命周期管理者。
    2. UIAbility 是 Stage 模型里最核心的 UI 入口，可以显示界面（实际开发可能只有一个主 UIAbility 通过路由管理多个页面）。
      1. WindowStage 是 UIAbility 下的窗口管理对象，Stage 模型中，页面不直接挂在 UIAbility，而是挂在 WindowStage 下，这点非常重要。因为 HarmonyOS 的 UI 展示是通过窗口系统承载的，WindowStage 就是页面显示之前必须经过的窗口层。
        1. Page 负责组织一个完整页面的 UI 和交互逻辑，是用户真正看到的页面。在 ArkUI 中，一个页面通常由一个 @Entry 组件作为入口。
          1. Component 是页面的最小 UI 构建单元，是 Page 内部的 UI 组成单元。
    3. Resources 是 Module 的资源区域，Module 内的多个 Ability、Page、Component 都可以共享这些资源。
  3. Feature Module 是应用的功能扩展模块，和普通 Module 的关系不是“包含关系”，而是“并列关系”，通常用于拆分独立功能，让应用具备更好的模块化能力。

运行流程：用户点击应用图标 → Application 被系统识别 → 读取 AppScope 中的应用级配置 → 加载对应 Module → 创建 Module 的 AbilityStage → 启动 Module 中的 UIAbility → UIAbility 创建 WindowStage → WindowStage 加载 Page → Page 渲染 Component

2.工程目录

HarmonyOS Stage 模型工程目录结构

应用的工程目录结构是 Stage 应用模型的物理实现形式。

  1. Application 逻辑结构上是系统识别的应用实体，承载整个应用。

对应工程目录：

  • MyApplication：工程根目录
  • AppScope：应用全局配置区
  • hvigor / oh_modules / 根目录配置文件（build-profile.json5, oh-package.json5, hvigorfile.ts 等）为工程级构建和依赖配置

说明：

  • Application 本身不是目录，而是系统根据 AppScope 和模块信息生成的逻辑对象。
  • 一对多对应：因为 Application 对应多个工程目录位置（AppScope、工程根目录文件和依赖目录），这些都参与 Application 的构建与识别。
  1. AppScope 逻辑结构上是应用全局配置区域（“身份证”），存放应用级信息。

对应工程目录：

  • AppScope/app.json5：应用唯一标识、版本、图标等信息
  • AppScope/resources（如果存在）：应用全局资源

说明：

  • 一对一对应，AppScope 在工程中就是 Application 级别的配置承载。
  1. Module 逻辑结构上是应用功能承载单元，比 Page 更高一级。主要包含：AbilityStage、UIAbility、Resources、Page 和 Component（通过 UIAbility 挂载）。

对应工程目录：

  • entry/：主模块目录
  • entry/src/main/module.json5：模块配置，声明 Module 类型、Abilities、页面入口
  • entry/src/main/ets/entryability/EntryAbility.ets：UIAbility 实现文件
  • entry/src/main/ets/entrybackupability/：通常用于 BackupExtensionAbility 或备份恢复相关能力源码，不等于 AbilityStage。
  • entry/src/main/ets/pages/Index.ets：Page 入口
  • entry/src/main/ets/pages 下其他组件文件：Component
  • entry/src/main/resources/：模块资源

说明：

  • 一对多对应：Module 对应 entry/ 目录及其下的多个子目录（ets、resources、测试目录 mock/test/ohosTest 等），因为一个模块可能包含多种能力（Ability）、页面和资源。
  • AbilityStage、UIAbility、Page、Component 在目录中以不同文件或目录承载，而逻辑上属于同一个 Module。
  1. AbilityStage 逻辑结构上是 Module 的运行入口和生命周期管理者。

对应工程目录：

  • entry/src/main/ets/entrybackupability/ 或自定义 AbilityStage 文件（例如 BackupAbility.ets）

说明：

  • 一对多对应：多个文件可以承载 Module 的生命周期逻辑（主 Ability + 扩展能力）。
  • AbilityStage 不一定是单个文件，可在多个 ets 文件中实现逻辑。
  1. UIAbility 逻辑结构上是 stage 模型的核心 UI 入口，可显示界面。Module 中通常只有一个主 UIAbility。

对应工程目录：

  • entry/src/main/ets/entryability/EntryAbility.ets
  • 相关配置：entry/src/main/module.json5 中声明 UIAbility 对应 srcEntry。

说明：

  • 一对一对应，逻辑上一个 UIAbility 对应一个主 ets 文件，但可能通过路由管理多个 Page。
  • UIAbility 是逻辑实体，EntryAbility.ets 是物理实现。
  1. WindowStage 逻辑结构上是 UIAbility 下的窗口管理对象，Stage 中页面挂载的窗口层。

对应工程目录：

  • 不存在对应目录，WindowStage 由系统在运行时创建。
  • 相关的 Page 加载由 EntryAbility.ets 的 onWindowStageCreate() 调用实现. windowStage.loadContent('pages/Index');

说明：

  • 该逻辑结构对象没有物理目录，运行时动态生成。目录中的 pages/Index.ets 挂载在 WindowStage 下。
  1. Page 逻辑结构上负责完整页面的 UI 和交互逻辑，通常由一个 @Entry 组件作为入口。

对应工程目录：

  • entry/src/main/ets/pages/Index.ets
  • entry/src/main/ets/pages/ 下其他页面文件（如果存在多个页面）

说明：

  • 一对多对应：Page 通常对应 pages 目录下的一个页面文件。Component 可以写在页面文件内部，也可以拆到 components 目录中复用。一个 Page 可以包含多个 Component。
  1. Component 逻辑结构上是 ArkUI 声明式 UI 的基本组织单元。。

对应工程目录：

  • 页面文件内部定义的 @Component 结构，如 Index.ets 内部
  • 如果拆分，可存在 entry/src/main/ets/components/ 目录存放组件

说明：

  • 多个 Component 对应一个 Page 文件，可一对多映射。
  1. Resources 逻辑结构上是Module 的资源区域，可供 Ability、Page、Component 共享。

对应工程目录：

  • entry/src/main/resources/

说明：

  • 一对一对应，Module 内所有 UIAbility/Pages/Components 都可访问这些资源。
  1. Feature Module 逻辑结构上是并列于 Module 的独立功能模块，用于功能拆分和模块化。

对应工程目录：

  • feature_XXX/：feature模块目录
  • feature_XXX/src/main/module.json5：模块配置，声明 Module 类型、Abilities、页面入口
  • feature_XXX/src/main/ets/entryability/EntryAbility.ets：UIAbility 实现文件
  • feature_XXX/src/main/ets/entrybackupability/：AbilityStage 或 ExtensionAbility 备份能力
  • feature_XXX/src/main/ets/pages/Index.ets：Page 入口
  • feature_XXX/src/main/ets/pages 下其他组件文件：Component
  • feature_XXX/src/main/resources/：模块资源

说明：

  • feature_xxx/ 是一个独立目录，和 entry/ 平级。
  • 每个 Feature Module 内部结构与主模块类似，包含 ets、resources、module.json5 等。
  • 系统运行时把 Feature Module 与主模块并列管理，它们不是包含关系，而是平行的功能模块。
  • Feature Module 不是脱离 Module 的另一类结构。
  • Feature Module 本质上也是 Module，只是模块类型或模块用途不同。

3.整理

  1. 一定要区分“逻辑对象”和“工程目录”
    • 目录结构是物理实现；
    • 逻辑结构是运行时抽象；
    • 配置文件是二者之间的桥梁；
    • ETS 文件是逻辑对象的代码实现；
    • 系统运行时负责创建和调度 UIAbility、WindowStage、Page、Context。
  2. Module 是 Stage 模型的核心组织单元
    • Feature Module 本质上也是 Module，不是 Module 之外的独立大类。
    • feature 目录名不是固定的，通常是 feature_xxx 或开发者自定义模块名。
  3. 其他
    • hvigor、oh_modules、build-profile.json5 等属于构建依赖体系，不是运行时逻辑结构。
    • 运行时不是直接读取工程目录，而是基于编译打包后的应用配置和模块配置启动。