适合谁看

• 会 Flutter，但不熟 HarmonyOS Stage 模型的人

• 看到 Ability 概念就有点混乱的人

• 想理解壳工程为什么这样组织的人

问题背景

Flutter 开发者更熟悉的是：

• 页面

• 路由

• Widget 生命周期

而鸿蒙 Stage 模型引入的是另一套系统层概念：

• Ability

• Want

• ExtensionAbility

• WindowStage

如果不先理解它们的角色，很多壳工程文件就会看起来像“额外负担”。
但实际上，它们解决的是 Flutter 自己并不直接负责的系统入口问题。

项目中的真实场景

食界探味当前正好能把 Stage 模型里最关键的几种角色都对出来：

• EntryAbility.ets 承接主启动

• InsightIntentExecutorImpl.ets 承接系统意图入口

• DailyRecommendFormAbility.ets 承接卡片能力

• Index.ets 承接 Flutter 页面容器

这意味着我们不需要抽象讨论 Stage 模型，而是可以直接回到真实文件理解它。

核心实现

先给一个最重要的判断：

Stage 模型下，Flutter 页面只负责应用内体验，系统怎么把用户、参数和上下文送进来，要先靠 Ability 体系承接。

只要先记住这句话，后面很多概念就不会再混。

一、什么是 Ability

如果用 Flutter 开发者更容易接受的方式来类比，Ability 不是 Widget，也不是页面组件。
它更像鸿蒙系统里承接应用能力和入口的单位。

在食界探味里，EntryAbility.ets 就是最典型的主 Ability。
它负责的不是渲染某个业务页面，而是：

• 配置 Flutter 引擎

• 注册插件

• 接住系统传进来的参数

• 处理应用被再次唤起时的新入口请求

所以你可以把 Ability 理解成：

• 系统入口承接者

• 生命周期协调者

• Flutter 运行环境的上层宿主

二、什么是 Want

在普通 Flutter App 里，我们更常见的是：

• 页面参数

• 路由参数

• 深链接参数

但在鸿蒙 Stage 模型里，系统和 Ability 之间更常用的是 Want。

在食界探味的 EntryAbility.ets 里，可以直接看到：

• onCreate(want, launchParam)

• onNewWant(want, launchParam)

这里的 want.parameters 里会带上像：

• pageId

• dishId

这说明 Want 本质上是系统把外部入口信息送进应用的载体。
它不是普通页面参数，而是更靠近系统入口协议的一层东西。

三、为什么 onCreate 和 onNewWant 都很重要

这是很多 Flutter 开发者第一次读 Ability 代码时最容易忽略的地方。

在食界探味里：

• onCreate 用来接应用首次启动时带进来的参数

• onNewWant 用来接应用运行过程中再次到来的入口请求

比如在 onNewWant 里，代码会判断：

• 当前有没有 pageId

• IntentNavigationPlugin 实例是否已经可用

• 如果可用，就直接导航

• 如果还没 ready，就先缓存成 pending navigation

这和普通 Flutter 路由最大的不同就在于：

路由不是总从页面内部发生的，系统可能随时把新入口送进来。

这正是 Stage 模型存在感最强的地方。

四、WindowStage 说明什么

在 EntryAbility.ets 里，onWindowStageCreate(windowStage) 这段逻辑也很值得注意。

它做的是：

• 获取主窗口

• 设置全屏布局

• 关闭系统栏显示

这说明 Ability 除了处理入口，还会和窗口、界面容器这些系统层概念打交道。
而这些内容在普通 Flutter 业务层里通常并不会出现。

所以从工程上看，Stage 模型下的壳工程并不只是“启动 Flutter”，它还负责管理 Flutter 所在的系统窗口环境。

五、什么是 ExtensionAbility

如果 Ability 负责主入口，那 ExtensionAbility 更像“扩展入口”。

在食界探味里，最典型的就是：

• DailyRecommendFormAbility.ets

它继承的是 FormExtensionAbility，负责的是卡片场景下的生命周期，例如：

• onAddForm

• onUpdateForm

• onRemoveForm

• onFormEvent

这说明卡片不是普通页面，也不是普通 Flutter 页面变体。
它是 Stage 模型下另一种由系统调度的扩展能力入口。

六、为什么 InsightIntentExecutorImpl.ets 也应该放进 Stage 模型里理解

很多人第一次看 InsightIntentExecutorImpl.ets，会把它误解成“一个普通导航工具类”。
但从职责上看，它更像系统入口承接者。

它主要做的事情包括：

• 判断系统传来的 intent 名称

• 校验 pageId 和 dishId

• 把系统入口转成 Flutter 可消费的导航数据

• 在 Flutter 还没 ready 时先存 pending navigation

这说明它不是页面层逻辑，而是典型的 Stage 模型入口层逻辑。

七、Index.ets 为什么也属于壳工程理解的一部分

Index.ets 的代码不多，但它帮助我们补齐了一个关键认知：

• Ability 承接系统入口

• Index.ets 承接页面容器

• FlutterPage 真正把 Flutter 视图挂进来

所以 Stage 模型下的 Flutter 鸿蒙壳工程，并不是一个文件解决所有问题，而是至少分成：

• Ability 层

• 容器页面层

• 插件层

• 扩展能力层

关键代码位置

• app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

• app/ohos/entry/src/main/ets/entryability/InsightIntentExecutorImpl.ets

• app/ohos/entry/src/main/ets/formability/DailyRecommendFormAbility.ets

• app/ohos/entry/src/main/ets/pages/Index.ets

• app/ohos/entry/src/main/module.json5

鸿蒙侧实现

从鸿蒙侧看，Stage 模型至少带来了三类非常明确的入口角色：

• 主 Ability：EntryAbility

• 系统意图入口：InsightIntentExecutorImpl

• 卡片扩展入口：DailyRecommendFormAbility

这三者共同说明，HarmonyOS 项目的入口不是单点，而是一组由系统调度的能力入口。

Flutter 侧实现

从 Flutter 侧看，最重要的不是去模仿这些概念，而是认清分工：

• Flutter 路由负责应用内导航

• Flutter 页面负责业务和展示

• 系统入口、外部参数、窗口和扩展能力先由 Stage 模型承接

只有这样，Flutter 页面层才不会被系统入口细节污染。

常见坑

• 把 Ability 误当成普通页面概念

• 只从 Flutter 页面角度理解整个壳工程

• 看到 Want 就把它等同于普通路由参数

• 没意识到 onNewWant 处理的是“应用运行中再次进入”的入口问题

• 把卡片能力误看成普通 Flutter 页面的一种缩略版

可复用模板

Stage 模型下的最小理解顺序
1. Ability 是系统入口单位
2. Want 是系统传参载体
3. ExtensionAbility 是扩展入口
4. Flutter 路由只是应用内承接层

食界探味里的对应关系
EntryAbility              → 主启动入口
InsightIntentExecutorImpl → 系统意图入口
DailyRecommendFormAbility → 卡片入口
Index.ets                 → Flutter 页面容器

本篇总结

Stage 模型下的 Flutter 鸿蒙壳工程，不是简单的“Flutter 外面包一层 ArkTS”。
它更准确的理解方式应该是：

• Ability 体系先承接系统入口

• 容器页面把 Flutter 挂进系统页面里

• 扩展能力继续承接卡片和意图等系统场景

只要先把这套入口分工理解清楚，后面再看插件、Intent、卡片和权限处理时，就不会总把它们误判成普通页面逻辑了。