鸿蒙应用开发UI基础第二节：鸿蒙应用程序框架核心解析与实操

学习目标

• 建立鸿蒙应用“宏观-微观”完整认知：明确应用、应用程序包、HAP/HSP、组件、页面的层级关系，理解 Stage 模型编译期与运行期概念的对应逻辑；
  
• 清晰区分 Stage 模型与 FA 模型的核心差异，理解 Stage 模型在资源利用、配置管理、跨端适配等实际开发场景中的核心优势；
  
• 掌握 Stage 模型进程/线程管理机制，理解 UIAbility 与 ExtensionAbility 的线程隔离特性，以及多线程开发的核心思路；
  
• 熟练掌握 UIAbility 在 module.json5 中的核心配置项及规则，精准定位 Stage 工程核心文件并理清依赖链路；
  
• 能独立完成应用名称/图标修改、UIAbility 配置调整、页面加载路径切换等实操，结合工程编译机制验证效果并排查基础配置与编译错误。
  

上一节我们掌握了应用配置签名真机调试，本节开始从“应用整体架构”切入，聚焦 Stage 模型核心交互组件 UIAbility 核心能力展开，结合工程编译机制，帮助构建鸿蒙应用开发基础认知体系，为后续应用生命周期、Context 上下文、进程通信等进阶内容学习打下基础。
一、回顾鸿蒙系统架构

鸿蒙系统采用分层架构，共四层，开发者核心工作集中在顶层两层：

• 应用层：面向用户的应用载体，包含两种形态
  
  
  
  • 原生应用：基于 ArkTS 开发，性能最优，能深度调用分布式能力，是鸿蒙生态核心；
    
  • 元服务：免安装、轻量便捷，适合高频次、低留存场景（如扫码支付）；
    
  
  
• 框架层：开发聚焦在框架层，提供 ArkUI 组件、状态管理、路由/导航跳转等核心能力，后续组件开发、布局设计均依赖此层；
  
• 系统服务层：封装分布式能力、设备管理等基础服务，开发者通过 API 调用即可，无需关注底层实现；
  
• 内核层：负责进程调度、内存管理等底层操作，开发者无需深入接触。
  

图 1：鸿蒙系统架构图 - 展示四层架构层级关系，标注开发者核心关注的应用层与框架层。

HarmonyOS 5.0 开始彻底完成 Linux 内核和安卓开放源代码项目（AOSP）的全面替换，采用纯鸿蒙内核（HarmonyOS Kernel），实现全栈自研。本阶段所有内容均基于鸿蒙 5.0~6.0 版本进行应用开发讲解。

二、程序框架服务（Ability Kit）

（一）核心定义

Ability Kit（程序框架服务）是鸿蒙系统为应用提供的核心运行时基础框架，抽象提炼应用开发所需核心能力，提供标准化组件体系和运行机制。核心价值是让开发者基于统一模型开发应用，同时保障应用在多设备、多场景下的兼容性与性能。
（二）核心能力与使用场景

能力范围具体内容典型使用场景生命周期与进程管理应用/组件进程创建销毁、生命周期调度多 Module 应用开发，HAP/HSP 分工实现功能组件交互能力组件间/应用间跳转、跨设备流转办公应用内启动视频会议组件、购物应用跳转支付应用、视频跨设备流转基础支撑能力上下文环境、系统事件监听、启动框架、意图框架等应用快捷方式配置、程序访问控制、密码自动填充（三）核心特征

• 标准化开发范式：抽象应用开发通用能力，提供统一的组件体系、生命周期规则，降低跨设备/跨版本适配成本；
  
• 高效资源调度：统一管理应用进程/线程，优化组件启动、内存占用等性能指标；
  
• 系统能力封装：内置意图框架、启动框架、流转能力等，无需开发者手动对接底层系统 API；
  
• 多场景支撑：通过 ExtensionAbility 覆盖备份、输入法、卡片等无 UI/轻 UI 场景，平衡功能扩展与系统管控。
  

（四）核心关联

• ArkUI：UIAbility 组件中可使用 ArkUI 的组件、事件、动效、状态管理等能力实现界面开发；
  
• ArkTS：提供语言运行时能力，支撑 Ability Kit 的代码执行；
  
• Hvigor：鸿蒙官方构建工具，为 Ability Kit 相关组件与配置提供编译构建能力，实现代码与配置的工程化落地。
  

三、鸿蒙应用模型

（一）核心定义与构成要素

应用模型是 Ability Kit 对应用开发能力的抽象封装，定义应用的组件体系、运行机制、配置规范等核心规则，核心构成要素如下：
构成要素核心作用应用组件应用运行入口，通过生命周期回调感知状态变化进程/线程模型定义进程/线程的创建、销毁及通信方式任务管理模型定义任务创建、销毁及与组件的关联（仅系统应用）应用配置文件存储应用/组件配置、权限等信息，供编译/运行阶段使用（二）演进历程：FA 模型 → Stage 模型

模型类型适配版本核心状态官方开发优势FA 模型API 7~8已停止更新-Stage 模型API 9+主推且长期演进1. 组件职责清晰，开发效率更高；2. 资源占用更低，启动速度更快；3. 跨端适配更便捷；4. 系统能力集成更简单；5. 编译分层设计，支持模块按需编译，提升开发效率（三）FA 模型与 Stage 模型核心差异

对比维度FA 模型Stage 模型组件体系Page/Service/DataAbility（匿名对象）UIAbility+ExtensionAbility（类继承）引擎机制每个组件独享 ArkTS 引擎实例所有组件共享一个 ArkTS 引擎实例进程模型主进程+渲染进程主进程+可配置独立进程（ExtensionAbility支持进程自定义）线程模型引擎实例在非主线程创建，不支持进程内对象共享引擎实例在主线程创建，支持进程内对象共享配置文件单一 config.json（混编全局/模块配置）app.json5（应用级）+ module.json5（模块级）编译机制整体工程编译，修改局部需重新编译全部分层编译，支持模块/全局编译，按需编译修改部分，效率更高（四）Stage 模型核心架构与组成

1. Stage 模型核心架构图

图 2：Stage 模型编译期-运行期架构图 - 左侧为运行期概念（应用实例化流程），右侧为编译期概念（开发打包流程），展示“模块→组件→页面”的打包与实例化对应关系。

2. 核心组成单元

• AbilityStage：可选实现（若不实现，系统默认创建）；Entry/Feature 类型 HAP 的运行时载体，一个 HAP 对应一个 AbilityStage 实例，负责 HAP 的初始化、组件创建分发、模块级生命周期管理；
  
• UIAbility：带 UI 的核心交互组件，通过 WindowStage 管理窗口，实现用户交互；
  
• ExtensionAbility：面向特定场景的扩展组件（如 EntryBackupAbility、InputMethodExtensionAbility），是 UIAbility 的扩展，用于无界面的后台能力（如备份、输入法）；
  
• WindowStage：与 UIAbility 实例绑定的窗口管理器，负责窗口创建、销毁，为 ArkUI 提供绘制区域；
  
• Context：派生类（ApplicationContext/AbilityStageContext/UIAbilityContext）为不同层级提供运行期资源调用、权限管理等能力；
  
• 三级生命周期：Application（应用级）→ AbilityStage（模块级）→ UIAbility/ExtensionAbility（组件级），由 Ability Kit 统一调度，实现资源精细化管理。
  

3. 核心层级关系说明

• 层级关联：Application（应用全局）→ AbilityStage（HAP 模块）→ UIAbility/ExtensionAbility（组件），依次依赖创建；
  
• 持有关系：UIAbility→WindowStage→Window→ArkUI Page，且各层级均持有对应 Context；
  
• 对应关系：Application ↔ Bundle，AbilityStage ↔ HAP（1:1 绑定）。
  

1. # 编译期（开发/打包）
2. 应用程序包（Bundle） → 模块（HAP/HSP） → 组件（UIAbility/ExtensionAbility） → 页面（Page）
4. # 运行期（安装/启动）
5. Application（应用全局实例） → AbilityStage（HAP 模块实例） → 组件实例 → 页面渲染

复制代码

（五）Stage 模型开发与运行全流程

1. 开发阶段

开发者基于 Stage 模型完成应用功能开发与配置，核心工作包括：

• 应用组件开发：通过 UIAbility 组件开发带界面的用户交互模块（如应用主界面），通过 ExtensionAbility 等组件开发各类扩展功能模块；
  
• 模块解耦设计：为减少不同功能模块间的依赖和耦合，可将 UIAbility 和各类 ExtensionAbility 的实现分别放在不同的 HAP 包中，同时将两者共同依赖的通用功能放在 HSP 包中；
  
• 配置文件编写：在 app.json5 中配置应用名称、版本号、应用图标等全局信息，在 module.json5 中配置对应 HAP 包下的组件清单、组件权限、进程归属等模块级信息；配置信息会在应用编译、安装时被系统解析，便于系统和其他模块识别、交互。
  

2. 运行阶段

当应用安装到设备运行时，系统通过一套应用进程和线程的管理机制，确保功能的有序运行：

• 进程是应用运行的基础单元，负责资源分配和隔离；
  
• 线程是进程内的执行单元，负责具体代码逻辑的执行；
  
• Ability Kit 统一管控进程/线程的创建、销毁和调度，保障应用稳定运行。
  

3. 进程模型

• 基础规则：UIAbility 组件默认运行在应用主进程中； ExtensionAbility 组件进程行为可配置，可通过module.json5中的process字段进行配置；
  
• 配置方式：在 ExtensionAbility 组件的配置节点中添加process字段，值以:开头表示配置为独立进程运行，未配置则默认与 UIAbility 同进程运行；
  
• 通信规则：ExtensionAbility 与 UIAbility 同进程时为线程隔离状态，数据和资源不直接互通；独立进程时需通过跨进程通信机制实现数据交互；
  
• 核心价值：进程可配置性兼顾了应用性能和稳定性——轻量扩展组件与主进程共享资源，减少进程开销；核心/高隔离性扩展组件独立进程运行，避免单一组件异常影响整个应用。
  

4. 组件通信机制

鸿蒙提供多套通信机制，适配不同组件类型、不同进程归属的通信场景，核心分类如下：

• 进程内通信：适用于同一进程内的 UIAbility 与 ExtensionAbility、UIAbility 与页面间，优先使用EventHub，轻量高效、无需复杂配置；
  
• 跨进程通信：适用于跨应用、独立进程的 HAP 之间、独立进程 ExtensionAbility 与 UIAbility 之间，使用IPC基础通信机制；
  
• ExtensionAbility 专属通信：不同类型的 ExtensionAbility 提供专属通信接口，适配自身业务场景，核心接口如下：
  
  
  
  • ServiceExtensionAbility：通过connectServiceExtensionAbility()建立连接，实现主从组件的双向通信；
    
  • DataShareExtensionAbility：通过createDataShareHelper()创建助手实例，实现数据的增删改查共享。
    
  
  

纯 ArkTS 单进程应用，优先使用 EventHub 实现组件/线程间通信；涉及独立进程或跨应用交互时，根据组件类型选择对应专属通信接口或基础 IPC 机制。

5. 线程模型

• 基础支撑：Stage 模型提供 worker、taskpool 等机制支撑应用多线程开发场景；
  
• 开发建议：应用若有复杂的耗时逻辑（如大数据处理、网络请求、复杂计算），建议通过创建 worker 线程的方式处理，避免阻塞主线程（UI 线程），保障应用界面流畅性；
  
• 线程隔离：无论 ExtensionAbility 与 UIAbility 同进程还是独立进程，其内部均为线程隔离设计，耗时逻辑均需放在子线程执行，不可直接在组件主线程处理。
  

（六）Stage 模型开发流程

核心任务关键内容应用组件开发开发 UIAbility/ExtensionAbility，按功能拆分到不同 HAP，通用能力抽离到 HSP进程/线程模型适配基于业务需求配置 ExtensionAbility 进程归属，耗时逻辑通过 worker 处理，遵循线程隔离规则配置文件编写配置 app.json5（全局）/module.json5（模块）的应用/组件/进程信息，保证路径与语法合规通信机制实现按进程归属和组件类型选择 EventHub、专属接口或 IPC 实现通信效果验证基于模块编译验证局部修改效果，全局编译生成完整应用包四、鸿蒙应用组成结构

（一）应用程序包（Bundle）

• 定义：鸿蒙应用分发、安装的最小单位（后缀.app），由全局编译整合所有 HAP/HSP 模块编译产物生成；
  
• 构成：Entry HAP（必选，应用启动入口）、Feature HAP（可选，扩展功能）、HSP（可选，代码/资源共享）；
  
• 多包机制：1 个 Bundle 可包含多个 HAP（Entry HAP 最多 1 个，Feature HAP 不限），HAP 之间通过 HSP 共享代码/资源，各模块可独立编译，最终整合至 Bundle。
  

（二）模块（HAP/HSP）

模块类型核心作用关键特征运行期关联实例典型使用场景编译特性Entry HAP应用主模块，提供启动入口必选，包含主 UIAbility，可单独安装运行对应 1 个 AbilityStage 实例应用主界面、核心交互功能可独立编译为 HAP 包，支持单独运行验证Feature HAP扩展功能模块可选，依赖 Entry HAP 运行，支持按需加载对应 1 个 AbilityStage 实例备份、输入法等扩展功能可独立编译，需结合 Entry HAP 运行HSP代码/资源共享包可选，无独立运行组件，仅用于模块间复用无对应的 AbilityStage 实例通用工具类、常量定义、公共资源编译为共享包，被其他 HAP 依赖调用

关于包的类型以及使用创建方法，我们会在项目阶段学习掌握。

（三）核心组件（Stage 模型两类组件）

组件类型核心作用交互方式开发方式进程默认配置细分类型/示例文件UIAbility应用入口+窗口管理，实现用户交互桌面启动、可视化交互面向对象开发（类继承）应用主进程EntryAbility.ets（应用主界面）ExtensionAbility备份/输入法等无 UI/轻 UI 场景系统/事件触发面向对象开发（派生类实现）应用主进程EntryBackupAbility.ets（备份）、DataShareExtensionAbility.ets（数据共享）五、工程结构

延用上一节创建的项目FirstApplication（基于鸿蒙 5.0 API 12 + DevEco Studio 6.0+），工程核心结构如下，其中build目录为编译后自动生成，build-profile.json5和hvigorfile.ts为鸿蒙 Hvigor 构建工具的核心编译配置文件，实现工程与模块的分层编译管理：

1. FirstApplication                    
2. ├── AppScope/                # 应用全局配置目录
3. │   ├── resources/           # 应用全局资源目录
4. │   │   ├── base/            # 全局基础资源目录
5. │   │   │   ├── element/     # 全局字符串、颜色等配置
6. │   │   │   │   └── string.json
7. │   │   │   ├── media/       # 全局媒体资源（层叠图标配置、兜底图标）
8. │   │   │   │   ├── app_icon.png // 自定义的应用图标
9. │   │   │   │   ├── background.png
10. │   │   │   │   ├── foreground.png
11. │   │   │   │   └── layered_image.json
12. │   │   │   └── profile/     # 全局配置文件（如页面路由、备份配置等）
13. │   └── app.json5            # 全局配置文件（包名、版本、图标、名称等，供全局编译解析）
14. ├── entry/                   # Entry HAP主模块（核心开发目录）
15. │   ├── build/               # 模块编译产物目录（编译后自动生成，存放entry模块HAP包）
16. │   ├── src/
17. │   │   ├── main/            # entry模块核心源码目录
18. │   │   │   ├── ets/         # ArkTS代码目录
19. │   │   │   │   ├── entryability/ # UIAbility核心组件目录
20. │   │   │   │   │   └── EntryAbility.ets
21. │   │   │   │   ├── entrybackupability/ # 备份扩展组件目录
22. │   │   │   │   │   └── EntryBackupAbility.ets
23. │   │   │   │   └── pages/   # 页面目录
24. │   │   │   │       ├── Index.ets
25. │   │   │   │       └── Home.ets
26. │   │   │   ├── resources/   # 模块级静态资源目录（编译时自动打包优化）
27. │   │   │   │   ├── base/    # 基础资源目录（默认主题）
28. │   │   │   │   │   ├── element/ # 模块级元素配置
29. │   │   │   │   │   ├── media/   # 模块级媒体资源
30. │   │   │   │   │   │   ├── background.png
31. │   │   │   │   │   │   ├── foreground.png
32. │   │   │   │   │   │   ├── startIcon.png // 默认的窗口图标
33. │   │   │   │   │   │   └── layered_image.json
34. │   │   │   │   ├── dark/    # 深色模式资源目录
35. │   │   │   │   └── rawfile/ # 原生文件目录（无需编译的静态文件）
36. │   │   │   └── module.json5 # Entry HAP模块配置文件（组件、权限、进程等，供模块编译解析）
37. │   ├── mock/                # 模拟数据目录（测试用）
38. │   ├── ohosTest/            # OpenHarmony测试目录
39. │   ├── test/                # 本地测试目录
40. │   ├── .gitignore           # Git忽略文件配置
41. │   ├── build-profile.json5  # 模块编译配置文件（指定SDK版本、签名关联等编译规则）
42. │   └── hvigorfile.ts        # 模块编译脚本（Hvigor构建工具模块级执行入口）
43. ├── build/                   # 工程全局编译产物目录（编译后自动生成，存放全局整合的HAP/APP包）
44. ├── build-profile.json5      # 工程全局编译配置文件（统一管理所有模块编译规则、编译模式）
45. ├── hvigorfile.ts            # 工程全局编译脚本（Hvigor构建工具全局执行入口，触发所有模块编译）
46. ├── oh-package.json5         # ohpm依赖配置文件（编译前自动解析下载依赖）
47. └── oh-package-lock.json5    # ohpm依赖版本锁定文件

复制代码

说明：鸿蒙工程基于Hvigor（鸿蒙官方自研构建工具）实现编译，采用按需编译原则，仅修改过的模块/文件会重新编译，未修改部分复用原有编译产物，提升开发效率；build目录删除后可通过重新编译生成，不影响工程源码。

六、UIAbility 核心实操

（一）核心定位

• 应用入口：用户点击应用图标后，系统首先创建并启动 UIAbility 实例；
  
• 窗口管理载体：每个 UIAbility 实例启动后会创建一个 WindowStage（窗口管理器），负责窗口的创建、销毁，并通过 WindowStage 加载 ArkUI 页面；
  
• 实例模式：支持单实例、多实例、指定实例等配置（通过 module.json5 的launchType字段），满足不同业务场景需求；
  
• 编译关联：UIAbility 的类名、文件路径需与 module.json5 中name、srcEntry配置完全一致，否则会导致模块编译失败，无法生成 HAP 包；
  
• 权限核心：作为应用核心交互组件，UIAbility 是应用权限申请和校验的核心载体，后台启动其他组件需依赖专属系统权限。
  

（二）核心配置

1. 模块级配置（module.json5）

1. {
2.   "module": {
3.     "name": "entry", // 模块名称
4.     "type": "entry", // 模块类型：entry/feature/har/hsp
5.     "description": "$string:module_desc", // 模块描述
6.     "mainElement": "EntryAbility", // 默认启动组件
7.     "deviceTypes": [ // 支持的设备类型
8.       "phone"
9.     ],
10.     "deliveryWithInstall": true, // 是否随应用安装交付
11.     "installationFree": false, // 是否免安装
12.     "pages": "$profile:main_pages", // 页面路由配置
13.     "abilities": [ // UIAbility组件配置
14.       {
15.         "name": "EntryAbility", // 组件名称（与代码类名一致，编译校验关键）
16.         "srcEntry": "./src/main/ets/entryability/EntryAbility.ets", // 入口路径（必须./开头，编译校验关键）
17.         "description": "$string:EntryAbility_desc", // 组件描述
18.         "icon": "$media:layered_image", // 组件图标（模块级，不重名的情况下优先生效）
19.         "label": "$string:EntryAbility_label", // 组件显示名称（模块级，优先级更高）
20.         "startWindowIcon": "$media:startIcon", // 启动窗口图标
21.         "startWindowBackground": "$color:start_window_background", // 启动窗口背景
22.         "exported": true, // 是否允许跨应用调用
23.         "launchType": "singleton", // 默认的启动模式，可以不写
24.         "skills": [ // 桌面图标必配：缺少则桌面无应用图标
25.           {
26.             "entities": [
27.               "entity.system.home" // 桌面入口标识
28.             ],
29.             "actions": [
30.               "ohos.want.action.home" // 桌面启动动作
31.             ]
32.           }
33.         ]
34.       }
35.     ],
36.     "extensionAbilities": [ // 扩展组件配置
37.       {
38.         "name": "EntryBackupAbility", // 备份扩展组件名称
39.         "srcEntry": "./src/main/ets/entrybackupability/EntryBackupAbility.ets",
40.         "type": "backup", // 扩展类型（backup/dataShare/inputMethod等）
41.         "exported": false, // 仅内部使用
42.         "metadata": [ // 扩展元数据
43.           {
44.             "name": "ohos.extension.backup", // 元数据名称
45.             "resource": "$profile:backup_config" // 元数据配置文件
46.           }
47.         ]
48.       }
49.     ]
50.   }
51. }

复制代码

2. 配置关键规则

• mainElement：Entry HAP 必须配置为 UIAbility，Feature HAP 无默认启动组件；
  
• name：组件名称必须与代码中导出的类名一致，不可随意修改，编译时会严格校验；
  
• srcEntry：路径需以./开头，严格匹配文件的目录/文件名（区分大小写），路径错误会直接导致编译失败；
  
• exported：跨应用调用的组件需设为 true，仅内部使用的组件设为 false 即可；
  
• skills：仅 UIAbility 需配置（桌面图标展示），ExtensionAbility 无需配置；缺失或配置不全则桌面无图标，点击图标进入应用详情页；
  
• type：ExtensionAbility 必选字段，需与扩展类型匹配（如 backup、dataShare、inputMethod 等）；
  
• process：ExtensionAbility 可选配置字段，用于设置进程归属，值以:开头表示独立进程，未配置则默认与主进程同进程；
  
• JSON 语法：禁止末尾多余逗号，配置项、文件/目录名称均区分大小写，语法错误会导致编译解析失败。
  

3. 全局配置（app.json5）

1. {
2.   "app": {
3.     "bundleName": "com.sanxiu.firstapp",
4.     "vendor": "example",
5.     "versionCode": 1000000,
6.     "versionName": "1.0.0",
7.     "icon": "$media:layered_image", // 全局应用图标
8.     "label": "$string:app_name" // 全局应用名称
9.   }
10. }

复制代码

4. 层叠图标配置（layered_image.json）

路径：

• 全局：AppScope/resources/base/media/layered_image.json
  
• 模块级：entry/src/main/resources/base/media/layered_image.json
  

1. {
2.   "layered-image": {
3.     "background": "$media:background",
4.     "foreground": "$media:foreground"
5.   }
6. }

复制代码

核心规则：

• 资源覆盖：编译期 AppScope 和模块内重名资源，AppScope 资源优先级更高；
  
• 模块级 icon 生效前提：UIAbility 的 skills 字段必须包含entity.system.home和ohos.want.action.home；多 Ability 时取mainElement对应配置；
  
• 图标尺寸规范：鸿蒙层叠图标推荐基础尺寸：foreground/background 均为1024×1024（png 格式，透明背景），编译时系统会自动适配不同设备的图标尺寸，无需手动制作多尺寸版本。
  

5. 页面路由配置（main_pages.json）

通过 New -> Page -> Empty Page 创建的页面会自动导入main_pages.json，其他方法创建的页面需要手动管理路由配置。

1. {
2.   "src": [
3.     "pages/Index",
4.     "pages/Home" // 新增Home页面路径
5.   ]
6. }

复制代码

（三）页面加载核心逻辑（EntryAbility.ets）

1. import UIAbility from '@ohos.app.ability.UIAbility';
2. import window from '@ohos.window';
3. import hilog from '@ohos.hilog';
4. import { AbilityConstant, Want } from '@kit.AbilityKit';
5. import { BusinessError } from '@ohos.base';
7. const DOMAIN: number = 0x0000;
8. const TAG: string = 'EntryAbility';
10. export default class EntryAbility extends UIAbility {
11.   // 组件创建时触发，可初始化资源
12.   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
13.     hilog.info(DOMAIN, TAG, 'EntryAbility onCreate called');
14.   }
16.   // 组件销毁时触发，可释放资源
17.   onDestroy() {
18.     hilog.info(DOMAIN, TAG, 'EntryAbility onDestroy called');
19.   }
21.   // 窗口创建后触发，仅此处可加载页面
22.   onWindowStageCreate(windowStage: window.WindowStage): void {
23.     hilog.info(DOMAIN, TAG, '--- onWindowStageCreate 触发（加载页面）---');
24.     // 加载页面
25.     windowStage.loadContent('pages/Index', (err) => {
26.       if (err.code) {
27.         hilog.error(DOMAIN, TAG, `页面加载失败：code=${err.code}, message=${err.message}`);
28.         return;
29.       }
30.       hilog.info(DOMAIN, TAG, 'Index页面加载成功');
31.     });
32.   }
34.   onWindowStageDestroy(): void {
35.     // Main window is destroyed, release UI related resources
36.     hilog.info(DOMAIN, TAG, '%{public}s', '主窗口即将销毁，释放UI相关资源');
37.   }
39.   onForeground(): void {
40.     // Ability has brought to foreground
41.     hilog.info(DOMAIN, TAG, '%{public}s', '应用切换至前台，恢复业务逻辑');
42.   }
44.   onBackground(): void {
45.     // Ability has back to background
46.     hilog.info(DOMAIN, TAG, '%{public}s', '应用切换至后台，暂停业务逻辑，不可启动其他组件');
47.   }
48. }

复制代码

页面加载规则

• 仅能通过WindowStage.loadContent()加载页面；
  
• 该方法仅可在onWindowStageCreate生命周期中调用；
  
• 路径需严格遵循“无.ets后缀、区分大小写、基于pages根目录的相对路径”，且需与main_pages.json中注册的路径完全一致，否则编译通过但运行时页面加载失败；
  
• 页面文件命名、路径错误会导致编译时资源打包失败，或运行时页面空白。
  

（四）自定义首页开发

步骤 1：创建 Home 页面（pages/Home.ets）

1. @Entry
2. @Component
3. struct Home {
4.   build() {
5.     Column({ space: 20 }) {
6.       Text('我的Stage应用首页')
7.         .fontSize(30)
8.         .fontWeight(FontWeight.Bold);
9.     }
10.     .width('100%')
11.     .height('100%')
12.     .justifyContent(FlexAlign.Center);
13.   }
14. }

复制代码

步骤 2：注册 Home 页面到路由配置（main_pages.json）

打开路径：entry/src/main/resources/base/profile/main_pages.json，在src数组中新增 Home 页面路径，确保与实际文件路径一致：

1. {
2.   "src": [
3.     "pages/Index",
4.     "pages/Home" // 必须注册，否则运行时页面加载失败
5.   ]
6. }

复制代码

步骤 3：修改页面加载路径（EntryAbility.ets）

将windowStage.loadContent('pages/Index', ...)修改为：

1. // 加载页面
2. windowStage.loadContent('pages/Home').then(()=>{
3.   hilog.info(DOMAIN, TAG, 'Home页面加载成功');
4. }).catch((err: BusinessError)=>{
5.   hilog.error(DOMAIN, TAG, `页面加载失败：code=${err.code}, message=${err.message}`);
6. })

复制代码

效果验证

• 应用内验证：正常展示我的Stage应用首页，无空白、无报错；
  
• 日志端验证：Logcat 中筛选TAG:EntryAbility，可看到“Home页面加载成功”相关日志。
  

（五）配置应用名称和图标

1. 层叠图标方案-模块级配置

默认工程中，全局应用图标、模块级图标、layered-image 及前后背景图的命名均一致。
若需让模块级应用图标生效，需删除AppScope/resources/base/media/ 目录下的 layered-image 相关文件（含layered_image.json、background.png、foreground.png），避免全局重名资源覆盖（不推荐）。
推荐方案：确保资源不重名，使用自定义图标名称，同时保证module.json5 中配置了skills字段（桌面图标正常显示前提）：

• 确认 entry 模块layered_image.json配置（路径：entry/src/main/resources/base/media/layered_image.json）；
  
• 确保 module.json5 中 UIAbility 配置"icon": "$media:layered_image"。
  

2. 层叠图标方案-全局级配置

直接将应用图标图片命名为foreground，或自定义 layered_image.json 中foreground的资源引用为"foreground": "$media:app_icon"：

• 配置 AppScope 下layered_image.json（路径：AppScope/resources/base/media/layered_image.json）；
  
• 在AppScope/app.json5中配置全局图标："icon": "$media:layered_image"。
  

3. 应用名称配置

应用名称的配置优先级：模块级别 > 全局级别。若需让全局资源配置的应用名称生效，需在 module.json5 中注释/删除 UIAbility 的 label 配置："label": "$string:EntryAbility_label"。

• 名称修改后需检查string.json中对应字符是否存在，字符缺失会导致编译时资源解析错误；
  
• 配置完成后执行模块编译，验证桌面应用名称是否更新；
  
• 全局名称路径：AppScope/resources/base/element/string.json
  1. {
  2.   "string": [
  3.     {
  4.       "name": "app_name",
  5.       "value": "第一个应用"
  6.     }
  7.   ]
  8. }

  复制代码

运行验证

将应用运行至真机/模拟器，桌面端应用名称显示为第一个应用，图标为全局配置的层叠样式。

七、清理、构建HAP/APP包

鸿蒙工程基于Hvigor构建工具实现模块级编译和全局级构建，顶部菜单栏Build为核心操作入口，覆盖「清理-编译-构建-发布」全流程，以下为精准实操和工具说明：
1. 清理操作

• 操作：顶部菜单栏Build > Clean Project
  
• 功能：删除全工程所有编译相关文件（缓存、临时产物、已生成的包文件等），仅保留源码、配置和资源文件
  
• 作用：解决编译异常、缓存冲突、配置修改不生效等问题，清理完成控制台显示BUILD SUCCESSFUL
  

2. 模块编译

适用于修改entry模块后快速验证局部效果，仅生成单模块HAP包：

• 操作：选中entry文件，点击顶部菜单栏Build > Make Module 'entry'
  
• 结果：控制台显示BUILD SUCCESSFUL即为成功，HAP包存放于entry/build/outputs/hap/
  
• 作用：快速验证entry模块代码/配置修改效果
  

3. 构建完整应用包（用于安装/分发/上架）

适用于真机/模拟器部署、应用发布上架，整合全模块生成完整.app包：

• 操作：顶部菜单栏Build > Build Hap(s)/APP(s) > Build App(s)
  
• 结果：控制台显示BUILD SUCCESSFUL即为成功，.app包存放于build/outputs/app/，主模块entry打包产出.hap包
  
• 作用：生成可部署/发布的完整Bundle应用包
  

4. Build菜单核心工具选项全解

选项名称核心作用典型使用场景Make Module 'entry'编译entry模块，生成单模块HAP包验证entry模块局部修改效果Build Hap(s)/APP(s)Build Hap(s)：编译单/多模块生成HAP包；Build App(s)：整合全模块生成.app包局部调试用Hap(s)；部署/发布用App(s)Generate Build Profile 'entry'生成entry模块专属编译配置文件自定义entry模块编译规则Clean Project删除全工程所有编译文件，彻底清理缓存编译异常、缓存冲突、配置修改不生效Rebuild Project先执行Clean Project，再全工程重新编译清理后仍编译失败、工程长期未编译Generate Key and CSR生成.p12密钥+CSR文件，用于申请官方发布签名应用正式发布上架Upload Product将正式版.app包上传至华为应用市场后台应用提交上架提审Build Analyzer分析构建耗时、资源占用，定位构建失败原因构建速度慢、排查构建失败问题八、代码仓库

• 工程名称：FirstApplication
  
• 仓库地址：https://gitee.com/HarmonyOS-UI-Basics/harmony-os-ui-basics.git
  

九、下节预告

下一节将深入学习 UIAbility 生命周期全解析，核心内容包括：

• UIAbility 全生命周期核心方法的触发时机、核心作用及执行次数约束；
  
• WindowStage 事件体系与生命周期的联动逻辑，掌握窗口状态（获焦/失焦、前台/后台）的合法监听方式；
  
• onDestroy 方法的特殊触发规则（API 13+一键清理、调试模式、手动调用API等不同场景）；
  
• 页面仅能在 onWindowStageCreate 加载的底层原因及生命周期相关开发避坑要点；
  
• 实操验证启动/前后台切换/关闭等场景下的生命周期执行顺序，掌握关键数据的安全保存策略。
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

前排留名，哈哈哈

感谢分享，下载保存了，貌似很强大

新版吗？好像是停更了吧。

谢谢分享，辛苦了

感谢分享

yyds。多谢分享

收藏一下   不知道什么时候能用到

分享、互助 让互联网精神温暖你我

很好很强大  我过来先占个楼 待编辑

懂技术并乐意极积无私分享的人越来越少。珍惜

感谢分享，学习下。

这个好，看起来很实用

喜欢鼓捣这些软件，现在用得少，谢谢分享！

感谢发布原创作品，程序园因你更精彩

感谢分享，学习下。

新版吗？好像是停更了吧。