你是不是也在想——“鸿蒙这么火我能不能学会”答案是当然可以这个专栏专为零基础小白设计不需要编程基础也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例手把手带你从安装开发工具开始一步步学会开发自己的鸿蒙应用。不管你是学生、上班族、打算转行还是单纯对技术感兴趣只要你愿意花一点时间就能在这里搞懂鸿蒙开发并做出属于自己的App关注本专栏《零基础学鸿蒙开发》一起变强每一节内容我都会持续更新配图代码解释全都有欢迎点个关注不走丢我是小白酷爱学习我们一起上路 全文目录前言一、先别把 UIAbility 当成“一个页面”二、HAP 又处在什么位置三、把五个核心对象放进同一张图四、它们到底谁先创建五、搭一个最小工程把关系直接写进代码1. 创建 AbilityStage2. 在 module.json5 中关联 AbilityStage 和 UIAbility六、UIAbility 真正负责的是哪一段七、ArkUI Page 是链路最末端的 UI八、几个特别容易理解错的地方1. AbilityStage 不是 Application 的另一种写法2. UIAbility 不是页面容器的同义词3. WindowStage 也不是 ArkUI Page4. Page 生命周期不能替代 UIAbility 生命周期九、HarmonyOS 7 下应该怎么看版本十、实际项目里怎么排查 Stage 层级问题开发经验总结前言刚接触 HarmonyOS Stage 模型时有几个名字很容易混在一起HAP、AbilityStage、UIAbility、WindowStage还有每天都在写的 ArkUI Page。尤其是EntryAbility.ets里那句windowStage.loadContent(pages/Index)看起来只是加载首页背后其实已经串起了 Stage 模型最核心的一条链路。这一篇不展开页面路由、多窗口、ExtensionAbility也不讨论复杂生命周期只做一件事把一个普通 Stage 工程从 HAP 到 ArkUI Page 的整体骨架画清楚。截至 2026 年 9 月HarmonyOS 7 已正式发布对应 API 26。Stage 模型仍然是当前 HarmonyOS 应用开发的核心应用模型官方文档明确说明Stage 模型提供 AbilityStage、WindowStage 等对象并将应用组件管理和窗口管理在架构层面解耦。一、先别把 UIAbility 当成“一个页面”理解 Stage 模型第一个需要纠正的概念就是UIAbility 不是 ArkUI Page。官方对 UIAbility 的定义是“包含 UI 的应用组件”主要承担与用户交互相关的应用组件职责而 ArkUI Page 才是真正组织和展示界面内容的页面。官方同时明确指出每个 UIAbility 实例都会与一个 WindowStage 实例绑定WindowStage 包含主窗口主窗口为 ArkUI 提供绘制区域。所以更合适的理解不是UIAbility 页面而是UIAbility │ └── WindowStage │ └── Window │ └── ArkUI Page页面最终需要有一个窗口承载而 UIAbility 与窗口之间的连接点就是 WindowStage。这也是为什么 DevEco Studio 创建的 Stage 工程里首页不是在UIAbility的build()中直接写出来而通常是在onWindowStageCreate()中调用windowStage.loadContent(pages/Index);官方当前文档中的 UIAbility 示例仍然采用这种组织方式。二、HAP 又处在什么位置再往上一层看 HAP。官方术语文档给出的定义很明确HAPHarmony Ability Package是应用安装和运行的基本单元由代码、资源、第三方库和配置文件等内容组成分为entry和feature两种类型。这里容易产生一个误区HAP、AbilityStage、UIAbility 是不是三个并列的运行对象不是。HAP首先是包和模块层面的概念。例如工程中的entryAbility 类型 Module 构建后形成 HAP。AbilityStage 则是这个层级在运行期非常关键的对象。官方 Stage 模型文档明确说明每个 Entry 类型或者 Feature 类型的 HAP在运行期都有一个 AbilityStage 类实例当 HAP 中的代码首次被加载到进程中时系统会先创建 AbilityStage 实例。该 HAP 中定义的 UIAbility 实例化后会与这个 AbilityStage 实例产生关联。因此可以先得到第一层关系Entry / Feature HAP │ └── AbilityStage │ ├── UIAbility A └── UIAbility B注意这里说的是一个 HAP 可以定义多个 UIAbility并不是“一个 HAP 对应一个 UIAbility”。AbilityStage 更接近“Module/HAP 级运行容器”。官方 AbilityStage 开发指导同样说明AbilityStage 是 Module 级组件容器一个 AbilityStage 实例对应一个 Module在 Module 的第一个 UIAbility 实例加载之前会先创建 AbilityStage。三、把五个核心对象放进同一张图到这里就可以把本文涉及的五个核心概念放到一张图里了。应用 │ ├── Entry HAP │ │ │ ├── AbilityStage │ │ │ │ │ ├── UIAbility 实例 A │ │ │ │ │ │ │ └── WindowStage 实例 │ │ │ │ │ │ │ └── 主 Window │ │ │ │ │ │ │ └── loadContent(...) │ │ │ │ │ │ │ └── ArkUI Page │ │ │ │ │ └── UIAbility 实例 B │ │ │ │ │ └── WindowStage 实例 │ │ │ │ │ └── 主 Window │ │ │ └── 代码 / 资源 / 配置等 │ └── Feature HAP可选 │ └── AbilityStage │ └── ...如果只记一张图建议记这一张。其中有三组关系尤其重要。HAP → AbilityStageAbilityStage 对应 Module/HAP 这一层的运行期组件容器。UIAbility → WindowStage每个 UIAbility 类实例都会绑定一个 WindowStage 类实例。WindowStage → ArkUI PageWindowStage 管理窗口通过loadContent()把 ArkUI 页面内容加载到关联窗口中。官方关于 UIContext 的说明进一步指出一个 Ability 可以存在多个 Window而每个 Window 通过loadContent加载页面后会生成相应的 UIContent也就是一个 ArkUI 实例。所以真正完整的链路实际上比“Ability 打开 Page”多了一层窗口体系HAP ↓ AbilityStage ↓ UIAbility ↓ WindowStage ↓ Window ↓ UIContent / ArkUI Page四、它们到底谁先创建如果只讨论一个普通 Stage 单 HAP 应用的首次启动可以把主干过程理解成HAP代码首次加载 ↓ 创建 AbilityStage ↓ AbilityStage.onCreate() ↓ 创建 UIAbility 实例 ↓ UIAbility.onCreate() ↓ 创建主窗口对应的 WindowStage ↓ UIAbility.onWindowStageCreate(windowStage) ↓ windowStage.loadContent(pages/Index) ↓ 创建并渲染 ArkUI 页面 ↓ UIAbility 进入前台阶段这里最关键的一条官方约束是Module 第一个 UIAbility 实例加载之前AbilityStage 已经被创建。AbilityStage 的onCreate()正是用于 Module 初始化的生命周期回调。UIAbility 与显示相关的职责又被拆给了 WindowStage。官方 Stage 模型概述特别指出UIAbility 生命周期主要包含创建、销毁、前台、后台等状态而显示相关状态通过 WindowStage 暴露。这正是 Stage 模型名称里“Stage”的含义之一应用组件和窗口各有自己的“舞台”而不是把业务生命周期、窗口生命周期和页面生命周期全部揉进一个对象。五、搭一个最小工程把关系直接写进代码下面不做业务功能只建立一个最小观察场景给entryHAP 显式配置 AbilityStageAbilityStage 创建时打印日志UIAbility 创建时打印日志WindowStage 创建后加载pages/IndexIndex 页面显示一个简单文本。这样做的价值不是实现功能而是把上面的架构关系落实到工程文件中。1. 创建 AbilityStageDevEco Studio 的默认工程不一定自动生成自定义 AbilityStage 文件。官方指导要求如果需要使用 AbilityStage可以创建继承自AbilityStage的类再通过 Module 配置中的srcEntry指定入口。// entry/src/main/ets/myabilitystage/MyAbilityStage.etsimport{AbilityStage}fromkit.AbilityKit;exportdefaultclassMyAbilityStageextendsAbilityStage{onCreate():void{console.info(StageDemo: AbilityStage onCreate);}}这段代码解决的问题非常单纯观察HAP/Module 级运行对象何时进入初始化阶段。这里使用当前 Kit 化导入方式import{AbilityStage}fromkit.AbilityKit;AbilityStage 属于 Ability Kit。2. 在 module.json5 中关联 AbilityStage 和 UIAbility下面只保留与本文关系直接相关的字段不代表完整工程的全部配置{ module: { name: entry, type: entry, srcEntry: ./ets/myabilitystage/MyAbilityStage.ets, mainElement: EntryAbility, pages: $profile:main_pages, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets } ] } }这里最值得看的是两个srcEntry。Module 层的module.srcEntry指向 AbilityStage。而module.abilities[].srcEntry指向具体 UIAbility。两个字段长得很像层级却完全不同。这是理解 Stage 工程结构时非常容易忽略的地方。官方 AbilityStage 指导明确使用 Module 的srcEntry指定 AbilityStage 源文件UIAbility 则声明在abilities配置中。六、UIAbility 真正负责的是哪一段接下来创建最小的EntryAbility// entry/src/main/ets/entryability/EntryAbility.etsimport{AbilityConstant,UIAbility,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{console.info(StageDemo: UIAbility onCreate);}onWindowStageCreate(windowStage:window.WindowStage):void{console.info(StageDemo: UIAbility onWindowStageCreate);windowStage.loadContent(pages/Index,(err){if(err.code){console.error(StageDemo: loadContent failed, code${err.code});return;}console.info(StageDemo: pages/Index loaded);});}onForeground():void{console.info(StageDemo: UIAbility onForeground);}onBackground():void{console.info(StageDemo: UIAbility onBackground);}onWindowStageDestroy():void{console.info(StageDemo: UIAbility onWindowStageDestroy);}onDestroy():void{console.info(StageDemo: UIAbility onDestroy);}}这段代码真正需要关注的不是日志而是onWindowStageCreate(windowStage:window.WindowStage)系统把已经创建的WindowStage交给 UIAbility然后我们调用windowStage.loadContent(pages/Index)把页面内容加载进去。官方当前 API 示例仍使用UIAbility、window.WindowStage和loadContent()这一组合推荐的 Kit 导入分别来自kit.AbilityKit与kit.ArkUI。这个最小骨架不涉及相机、定位、文件读取等受控能力因此本文场景不需要额外申请运行时权限。七、ArkUI Page 是链路最末端的 UI页面可以保持得非常简单// entry/src/main/ets/pages/Index.etsEntryComponentstruct Index{build(){Column(){Text(Stage Model).fontSize(28)Text(AbilityStage → UIAbility → WindowStage → ArkUI Page).fontSize(16).margin({top:16})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}对应的页面配置可以放在entry/src/main/resources/base/profile/main_pages.json例如{src:[pages/Index]}官方当前工程配置资料仍采用pages: $profile:main_pages与main_pages.json中src页面列表的方式组织页面。这里还要再区分一次EntryComponentstruct Index这里的Entry表示当前 ArkUI Page 的入口组件它不是entryHAP也不是 EntryAbility。官方 ArkUI 页面生命周期文档将 Page 定义为应用的 UI 页面并指出使用Entry修饰的自定义组件作为该页面的默认入口组件。也就是说HarmonyOS 工程里至少存在三个容易混淆的“入口”概念entry HAP EntryAbility Entry ArkUI Component名字接近但不是一个层级。八、几个特别容易理解错的地方1. AbilityStage 不是 Application 的另一种写法AbilityStage 是Module 级组件容器。如果应用只有一个 entry HAP看起来它似乎就是整个应用唯一的顶层对象但到了多 HAP 工程这种理解马上会出问题。官方规定每个 Entry 或 Feature HAP 在运行期都有对应的 AbilityStage。所以应该记一个应用 ≠ 一个 AbilityStage 一个 Entry/Feature HAP → 对应 AbilityStage2. UIAbility 不是页面容器的同义词UIAbility 是应用组件。WindowStage 才负责连接 UIAbility 与窗口体系而 ArkUI 页面最终被加载到窗口对应的 UI 实例中。如果把 UIAbility 直接等价为 Page后面遇到多窗口、UIContext、多 UI 实例时会越来越难理解。官方关于 UIContext 的说明已经明确存在Ability → Window → UIContent这样的多实例关系。3. WindowStage 也不是 ArkUI PageWindowStage 是窗口管理层对象。Page 是 UI 内容。loadContent()恰好把二者连接起来。因此windowStage.loadContent(pages/Index)不只是“跳到首页”更准确地说它是在为这个 WindowStage 关联的窗口加载 ArkUI 页面内容。4. Page 生命周期不能替代 UIAbility 生命周期ArkUI Page 有自己的生命周期例如onPageShow()、onPageHide()自定义组件又有aboutToAppear()、aboutToDisappear()等组件生命周期。它们和UIAbility.onCreate UIAbility.onForeground UIAbility.onBackground UIAbility.onDestroy不是同一个层级。页面显示不等于 UIAbility 被重新创建。九、HarmonyOS 7 下应该怎么看版本HarmonyOS 7 已于 2026 年正式发布对应 API 26。官方开发者月刊和开发者官网均已将 HarmonyOS 7API 26作为当前正式版本提供配套资料。但本文讲的 Stage 骨架不是 API 26 才出现的新能力。当前 Ability Kit 文档显示UIAbilityContext、AbilityStageContext 等 Stage 模型基础接口从 API version 9 开始提供并明确标注只能在 Stage 模型下使用HarmonyOS 7 / API 26 继续支持这些基础模型。因此本文更合适的版本表述是项目本文结论当前开发背景HarmonyOS 7当前正式 APIAPI 26应用模型StageUIAbility / AbilityStageAbility KitWindowStage / WindowArkUI 窗口能力示例语言ArkTS额外权限本文最小场景不需要特定设备限制本文只讨论通用应用骨架不使用设备专属能力不要因为正在使用 API 26就把所有基础对象写成“API 26 新增”。十、实际项目里怎么排查 Stage 层级问题碰到“页面没有显示”“生命周期和预想不一致”一类问题时可以按照层级从外往内检查而不是一开始就改 ArkUI 布局。可以按这个顺序看 Module/HAP当前代码到底属于哪个 entry 或 feature Module。看 AbilityStage 配置如果自定义了 AbilityStage确认module.srcEntry是否指向正确文件。看 UIAbility 配置确认abilities中的name、srcEntry与实际 UIAbility 对应。看 WindowStage确认页面加载逻辑是否发生在正确的onWindowStageCreate()中。看loadContent()检查页面路径是否正确并处理加载错误。最后看 ArkUI Page确认页面是否已经配置、是否存在Entry页面入口组件以及组件树本身是否正确。这种排查方式的核心就是顺着HAP → AbilityStage → UIAbility → WindowStage → Page一层一层往下找。如果连 WindowStage 都还没有进入预期阶段只盯着Index.ets改布局通常解决不了问题。开发经验总结Stage 模型的对象不少但整体骨架其实可以压缩成四句话。第一HAP 是包和 Module 层面的基本单元AbilityStage 是这一层对应的重要运行期组件容器。第二一个 HAP 可以定义 UIAbilityUIAbility 是包含 UI 的应用组件不等于某一个 ArkUI 页面。第三每个 UIAbility 实例会绑定 WindowStageWindowStage 包含主窗口为 ArkUI 提供绘制区域。第四windowStage.loadContent(pages/Index)把窗口体系和 ArkUI 页面真正连接起来。所以以后再看到默认工程中的exportdefaultclassEntryAbilityextendsUIAbility{onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index);}}可以在脑子里直接展开成Entry HAP ↓ AbilityStage ↓ EntryAbility ↓ WindowStage ↓ Main Window ↓ loadContent ↓ pages/Index ↓ ArkUI Component Tree把这条主线弄清楚之后再去理解 UIAbility 生命周期、多窗口、UIContext、Navigation甚至多 HAP 工程很多原本零散的概念都会找到自己的位置。下一次打开一个陌生 HarmonyOS 工程可以先不看业务代码沿着module.json5 → AbilityStage → UIAbility → onWindowStageCreate → loadContent → Page走一遍。通常几分钟就能把这个工程最基本的运行骨架摸清楚。❤️ 如果本文帮到了你…请点个赞让我知道你还在坚持阅读技术长文请收藏本文因为你以后一定还会用上如果你在学习过程中遇到bug请留言我帮你踩坑