鸿蒙应用开发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 绑定）。

# 编译期（开发/打包）
应用程序包（Bundle） → 模块（HAP/HSP） → 组件（UIAbility/ExtensionAbility） → 页面（Page）

# 运行期（安装/启动）
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 构建工具的核心编译配置文件，实现工程与模块的分层编译管理：

FirstApplication                    
├── AppScope/                # 应用全局配置目录
│   ├── resources/           # 应用全局资源目录
│   │   ├── base/            # 全局基础资源目录
│   │   │   ├── element/     # 全局字符串、颜色等配置
│   │   │   │   └── string.json
│   │   │   ├── media/       # 全局媒体资源（层叠图标配置、兜底图标）
│   │   │   │   ├── app_icon.png // 自定义的应用图标
│   │   │   │   ├── background.png
│   │   │   │   ├── foreground.png
│   │   │   │   └── layered_image.json
│   │   │   └── profile/     # 全局配置文件（如页面路由、备份配置等）
│   └── app.json5            # 全局配置文件（包名、版本、图标、名称等，供全局编译解析）
├── entry/                   # Entry HAP主模块（核心开发目录）
│   ├── build/               # 模块编译产物目录（编译后自动生成，存放entry模块HAP包）
│   ├── src/
│   │   ├── main/            # entry模块核心源码目录
│   │   │   ├── ets/         # ArkTS代码目录
│   │   │   │   ├── entryability/ # UIAbility核心组件目录
│   │   │   │   │   └── EntryAbility.ets
│   │   │   │   ├── entrybackupability/ # 备份扩展组件目录
│   │   │   │   │   └── EntryBackupAbility.ets
│   │   │   │   └── pages/   # 页面目录
│   │   │   │       ├── Index.ets
│   │   │   │       └── Home.ets
│   │   │   ├── resources/   # 模块级静态资源目录（编译时自动打包优化）
│   │   │   │   ├── base/    # 基础资源目录（默认主题）
│   │   │   │   │   ├── element/ # 模块级元素配置
│   │   │   │   │   ├── media/   # 模块级媒体资源
│   │   │   │   │   │   ├── background.png
│   │   │   │   │   │   ├── foreground.png
│   │   │   │   │   │   ├── startIcon.png // 默认的窗口图标
│   │   │   │   │   │   └── layered_image.json
│   │   │   │   ├── dark/    # 深色模式资源目录
│   │   │   │   └── rawfile/ # 原生文件目录（无需编译的静态文件）
│   │   │   └── module.json5 # Entry HAP模块配置文件（组件、权限、进程等，供模块编译解析）
│   ├── mock/                # 模拟数据目录（测试用）
│   ├── ohosTest/            # OpenHarmony测试目录
│   ├── test/                # 本地测试目录
│   ├── .gitignore           # Git忽略文件配置
│   ├── build-profile.json5  # 模块编译配置文件（指定SDK版本、签名关联等编译规则）
│   └── hvigorfile.ts        # 模块编译脚本（Hvigor构建工具模块级执行入口）
├── build/                   # 工程全局编译产物目录（编译后自动生成，存放全局整合的HAP/APP包）
├── build-profile.json5      # 工程全局编译配置文件（统一管理所有模块编译规则、编译模式）
├── hvigorfile.ts            # 工程全局编译脚本（Hvigor构建工具全局执行入口，触发所有模块编译）
├── oh-package.json5         # ohpm依赖配置文件（编译前自动解析下载依赖）
└── 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）

{
  "module": {
    "name": "entry", // 模块名称
    "type": "entry", // 模块类型：entry/feature/har/hsp
    "description": "$string:module_desc", // 模块描述
    "mainElement": "EntryAbility", // 默认启动组件
    "deviceTypes": [ // 支持的设备类型
      "phone"
    ],
    "deliveryWithInstall": true, // 是否随应用安装交付
    "installationFree": false, // 是否免安装
    "pages": "$profile:main_pages", // 页面路由配置
    "abilities": [ // UIAbility组件配置
      {
        "name": "EntryAbility", // 组件名称（与代码类名一致，编译校验关键）
        "srcEntry": "./src/main/ets/entryability/EntryAbility.ets", // 入口路径（必须./开头，编译校验关键）
        "description": "$string:EntryAbility_desc", // 组件描述
        "icon": "$media:layered_image", // 组件图标（模块级，不重名的情况下优先生效）
        "label": "$string:EntryAbility_label", // 组件显示名称（模块级，优先级更高）
        "startWindowIcon": "$media:startIcon", // 启动窗口图标
        "startWindowBackground": "$color:start_window_background", // 启动窗口背景
        "exported": true, // 是否允许跨应用调用
        "launchType": "singleton", // 默认的启动模式，可以不写
        "skills": [ // 桌面图标必配：缺少则桌面无应用图标
          {
            "entities": [
              "entity.system.home" // 桌面入口标识
            ],
            "actions": [
              "ohos.want.action.home" // 桌面启动动作
            ]
          }
        ]
      }
    ],
    "extensionAbilities": [ // 扩展组件配置
      {
        "name": "EntryBackupAbility", // 备份扩展组件名称
        "srcEntry": "./src/main/ets/entrybackupability/EntryBackupAbility.ets", 
        "type": "backup", // 扩展类型（backup/dataShare/inputMethod等）
        "exported": false, // 仅内部使用
        "metadata": [ // 扩展元数据
          {
            "name": "ohos.extension.backup", // 元数据名称
            "resource": "$profile:backup_config" // 元数据配置文件
          }
        ]
      }
    ]
  }
}

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）

{
  "app": {
    "bundleName": "com.sanxiu.firstapp",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:layered_image", // 全局应用图标
    "label": "$string:app_name" // 全局应用名称
  }
}

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

路径：

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

{
  "layered-image": {
    "background": "$media:background",
    "foreground": "$media:foreground"
  }
}

核心规则：

资源覆盖：编译期 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，其他方法创建的页面需要手动管理路由配置。

{
  "src": [
    "pages/Index",
    "pages/Home" // 新增Home页面路径
  ]
}

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

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import hilog from '@ohos.hilog';
import { AbilityConstant, Want } from '@kit.AbilityKit';
import { BusinessError } from '@ohos.base'; 

const DOMAIN: number = 0x0000;
const TAG: string = 'EntryAbility';

export default class EntryAbility extends UIAbility {
  // 组件创建时触发，可初始化资源
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(DOMAIN, TAG, 'EntryAbility onCreate called');
  }

  // 组件销毁时触发，可释放资源
  onDestroy() {
    hilog.info(DOMAIN, TAG, 'EntryAbility onDestroy called');
  }

  // 窗口创建后触发，仅此处可加载页面
  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(DOMAIN, TAG, '--- onWindowStageCreate 触发（加载页面）---');
    // 加载页面
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(DOMAIN, TAG, `页面加载失败：code=${err.code}, message=${err.message}`);
        return;
      }
      hilog.info(DOMAIN, TAG, 'Index页面加载成功');
    });
  }

  onWindowStageDestroy(): void {
    // Main window is destroyed, release UI related resources
    hilog.info(DOMAIN, TAG, '%{public}s', '主窗口即将销毁，释放UI相关资源');
  }

  onForeground(): void {
    // Ability has brought to foreground
    hilog.info(DOMAIN, TAG, '%{public}s', '应用切换至前台，恢复业务逻辑');
  }

  onBackground(): void {
    // Ability has back to background
    hilog.info(DOMAIN, TAG, '%{public}s', '应用切换至后台，暂停业务逻辑，不可启动其他组件');
  }
}

页面加载规则

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

（四）自定义首页开发

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

@Entry
@Component
struct Home {
  build() {
    Column({ space: 20 }) {
      Text('我的Stage应用首页')
        .fontSize(30)
        .fontWeight(FontWeight.Bold);
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center);
  }
}

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

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

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

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

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

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

效果验证

应用内验证：正常展示我的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

{
  "string": [
    {
      "name": "app_name",
      "value": "第一个应用"
    }
  ]
}

运行验证

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

七、清理、构建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 加载的底层原因及生命周期相关开发避坑要点；
实操验证启动/前后台切换/关闭等场景下的生命周期执行顺序，掌握关键数据的安全保存策略。

相关阅读:
K8s in Action 阅读笔记——【12】Securing the Kubernetes API server
JDK8-Predicate接口使用举例
 Spring目录结构和基础JAR包介绍
 对毕业季即将踏入职场的年轻人的一点建议
 计算机竞赛深度学习 opencv python 实现中国交通标志识别
 简易搜索引擎SEWeibo
推荐Java开发常用的工具类库google guava
java版直播商城免费搭建平台规划及常见的营销模式+电商源码+小程序+三级分销+二次开发
 HarmonyOS NEXT应用开发—使用弹簧曲线实现抖动动画及手机振动效果案例
 JWFD开源工作流-随机函数发生器最新进展
原文地址：https://www.cnblogs.com/san-xiu/p/19575201