鸿蒙Stage模型与FA模型详解

油墨香^_^

44人浏览 · 2026-07-17 00:18:33

油墨香^_^ · 2026-07-17 00:18:33 发布

一、前言：从FA到Stage的演进

在HarmonyOS的发展历程中，应用开发模型经历了从FA模型到Stage模型的重要演进。FA（Feature Ability）模型是HarmonyOS早期版本（API 7及更早）支持的应用开发模型，而Stage模型则是从API 9开始引入、HarmonyOS NEXT版本主推且会长期演进的新一代应用开发模型。

一句话概括：FA模型是鸿蒙早期的开发范式，Stage模型是官方主推的现代工程化架构。如果你现在开始学习鸿蒙开发，直接选择Stage模型即可，FA模型仅作为理解历史演进的需要。

二、FA模型详解

2.1 什么是FA模型

FA模型是“Feature Ability”（功能能力）的缩写，是HarmonyOS早期版本开始支持的应用开发模型。该模型基于微内核架构，通过IPC（进程间通信）和分布式软总线完成轻量化、松耦合的模块间通信和服务调用。

FA模型将Ability分为两大类：

Page Ability（页面能力）：负责展示应用界面，类似于Android的Activity，包含独立的界面和业务逻辑
Service Ability（服务能力）：没有界面，主要用于在后台执行任务

2.2 FA模型的配置文件

在FA模型中，应用配置通过config.json文件完成，该文件包含三个必填标签：

标签	说明
app	应用级别的配置，如bundleName、vendor、version等
deviceConfig	设备相关的配置
module	HAP模块的配置，包含abilities、deviceType等信息

config.json配置示例：

json

{
  "app": {
    "vendor": "example",
    "bundleName": "com.example.demo",
    "version": {
      "code": 1000000,
      "name": "1.0.0"
    }
  },
  "module": {
    "mainAbility": ".MainAbility_entry",
    "deviceType": ["tablet"],
    "abilities": [
      {
        "name": ".MainAbility_entry",
        "type": "page",
        "launchType": "multiton",
        "orientation": "unspecified"
      }
    ]
  }
}

2.3 FA模型的包结构

FA模型的应用程序包结构中，所有资源文件、库文件和代码文件都存放在assets文件夹中，内部进一步区分为entry和js文件夹：

text

- config.json          # 应用配置文件
- assets/
  ├── entry/           # resources目录和resources.index
  │   ├── resources/   # 资源文件（字符串、图片等）
  │   └── resources.index
  └── js/              # 编译后的代码文件
- pack.info            # 描述HAP属性的文件

2.4 FA模型的上下文获取方式

在FA模型中，开发者通过featureAbility获取上下文：

typescript

import featureAbility from '@ohos.ability.featureAbility';

// 获取上下文
let context = featureAbility.getContext();

// 拉起Ability
featureAbility.startAbility({
  bundleName: 'com.example.app',
  abilityName: 'com.example.MainAbility'
}).then(() => {
  console.log('Ability启动成功');
});

三、Stage模型详解

3.1 什么是Stage模型

Stage模型是HarmonyOS从API 9开始引入的新一代应用开发模型，名称中的“Stage”（舞台）寓意是为开发者提供一个新的展现舞台。Stage模型的设计目标主要是方便开发者开发分布式环境下的复杂应用，从架构设计层面规范业务逻辑与UI交互的开发方式。

3.2 Stage模型的核心概念

Stage模型包含以下核心概念：

1. AbilityStage（应用舞台）

每个Entry或Feature类型的HAP在运行期都有一个AbilityStage类实例
当HAP中的代码首次被加载到进程时，系统会先创建AbilityStage实例
负责管理该模块下Ability的整体运行状态，可在此进行模块级初始化

2. UIAbility（界面能力组件）

包含UI的应用组件，主要用于和用户交互
生命周期包含：创建（Create）、销毁（Destroy）、前台（Foreground）、后台（Background）状态
每个UIAbility实例与一个WindowStage类实例绑定

3. ExtensionAbility（扩展能力组件）

面向特定场景的应用组件，开发者不能直接从ExtensionAbility派生，而是使用其派生类
常见派生类包括：
- FormExtensionAbility：卡片场景
- InputMethodExtensionAbility：输入法场景
- WorkSchedulerExtensionAbility：闲时任务场景

4. WindowStage（窗口舞台）

应用进程内的窗口管理器
包含一个主窗口，为ArkUI提供绘制区域

5. Context（上下文）

在运行期提供各种资源和能力的调用接口
UIAbility和ExtensionAbility各有不同的Context类，均继承自基类Context

3.3 Stage模型的配置文件

Stage模型使用module.json5作为应用配置文件，结构更清晰、模块化程度更高。配置文件包含以下主要部分：

json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntry": "./ets/ability/AbilityStage.ets",
    "abilities": [
      {
        "name": "MainAbility",
        "srcEntry": "./ets/ability/MainAbility.ets",
        "launchType": "standard",
        "visible": true
      }
    ],
    "extensionAbilities": [
      {
        "name": "FormAbility",
        "srcEntry": "./ets/ability/FormAbility.ets",
        "type": "form"
      }
    ]
  }
}

3.4 Stage模型的包结构

Stage模型对包结构进行了优化，在顶层增加了AppScope目录存放公共资源，并增加了AbilityStage.ts作为HAP加载入口。

text

- AppScope/              # 应用公共资源
  └── resources/
      └── base/
- entry/                 # 主模块
  ├── src/
  │   └── main/
  │       ├── ets/
  │       │   ├── ability/
  │       │   │   ├── AbilityStage.ets   # HAP加载入口
  │       │   │   └── MainAbility.ets    # UIAbility
  │       │   └── pages/
  │       └── resources/
  └── module.json5       # 模块配置文件

3.5 Stage模型的上下文获取方式

在Stage模型中，上下文通过组件实例的context属性直接获取，无需依赖featureAbility：

typescript

// 组件内直接使用this.context
@Entry
@Component
struct MyComponent {
  async writeToFile() {
    // 使用组件的context属性获取文件目录
    const filesDir = await this.context.getFilesDir();
    // 文件操作...
  }
}

在UIAbility中获取上下文：

typescript

export default class MainAbility extends UIAbility {
  onCreate(want, launchParam) {
    // 直接使用this.context
    let context = this.context;
  }
}

四、FA模型与Stage模型核心对比

4.1 对比总览

对比维度	FA模型（旧版）	Stage模型（推荐）
推出时间	早期版本（API 7及以前）	API 9起，持续演进
主推程度	已停止演进，不再主推	长期演进，官方主推
架构设计	单进程架构	多进程架构，支持多窗口
组件类型	FeatureAbility、ServiceAbility	UIAbility、ExtensionAbility
引擎实例	每个组件独享一个ArkTS引擎实例	多个组件共享同一个ArkTS引擎实例
内存占用	较高（每个组件独立引擎）	优化（共享引擎，减少内存占用）
上下文获取	`featureAbility.getContext()`	组件内`this.context`
配置文件	config.json	module.json5
适合场景	简单应用、快速开发	复杂应用、多设备协同、分布式场景
学习曲线	较平缓（类似Android开发）	较陡峭（需要理解新架构）

4.2 设计思想对比

FA模型的设计思想：

基于微内核架构，通过IPC和分布式软总线实现模块间通信
强调轻量化、松耦合
适合需要快速响应和高效交互的场景

Stage模型的设计思想：

多个组件共享同一个ArkTS引擎实例，实现对象和状态的方便共享
数据与UI分离：Ability中产生数据，数据驱动UI变化（UI = f(state)）
更好地支持跨端迁移和多端协同
对后台进程进行有序治理，保障用户体验和系统安全

4.3 生命周期对比

FA模型的生命周期（以Page Ability为例）：

onStart()：创建时调用
onActive()：获得焦点时调用
onInactive()：失去焦点时调用
onBackground()：进入后台时调用
onStop()：销毁时调用

Stage模型的生命周期：

AbilityStage级别：模块级生命周期
- onCreate()：模块加载时调用，适合模块级初始化
UIAbility级别：
- onCreate()：Ability创建时调用，适合轻量初始化
- onWindowStageCreate()：窗口舞台创建，UI相关初始化建议在此进行，如loadContent()
- onForeground()：切换到前台
- onBackground()：切换到后台
- onDestroy()：销毁释放资源

经验建议：不要在onCreate()中执行重任务，否则会导致启动卡顿。UI相关的初始化应放在onWindowStageCreate()中。

4.4 API调用方式对比

FA模型（使用featureAbility）：

typescript

import featureAbility from '@ohos.ability.featureAbility';

// 启动Ability
featureAbility.startAbility({
  bundleName: 'com.example.app',
  abilityName: 'com.example.MainAbility',
  parameters: { key: 'value' }
}).then(() => {
  // 启动成功
});

// 获取参数
featureAbility.getWant((error, want) => {
  let params = want.parameters;
});

Stage模型（使用context）：

typescript

// 启动Ability - 通过context
getContext(this).startAbility({
  bundleName: 'com.example.app',
  abilityName: 'com.example.MainAbility',
  parameters: { key: 'value' }
}).then(() => {
  // 启动成功
});

// 获取参数 - 在UIAbility中接收
export default class MainAbility extends UIAbility {
  onCreate(want, launchParam) {
    let params = want.parameters;
    // 可通过globalThis或AppStorage传递给UI组件
  }
}

五、从FA迁移到Stage模型的实践要点

5.1 迁移概述

由于FA模型已停止演进，建议开发者将现有FA模型应用迁移到Stage模型。迁移主要涉及以下方面：

5.2 代码目录调整

在顶层增加AppScope目录存放公共资源
增加AbilityStage.ts作为HAP加载入口
配置文件从config.json变更为module.json5
pages目录位置调整

建议：新建一个Stage模型的工程，将原有代码逐步复制过来，然后逐个解决API差异问题。

5.3 API变更适配

启动Ability：从featureAbility.startAbility()改为context.startAbility()
关闭Ability：从featureAbility.terminateSelf()改为context.terminateSelf()
获取参数：从featureAbility.getWant()改为在UIAbility的onCreate()或onNewWant()中接收

5.4 数据传递方式变化

在FA模型中，参数可直接在组件内通过featureAbility.getWant()获取。在Stage模型中：

方式一：在UIAbility中接收want，通过globalThis传递给UI组件
方式二：使用AppStorage进行数据关联，UI组件用@StorageLink接收

六、总结与选择建议

6.1 核心结论

FA模型是历史产物：作为API 7及以前版本的应用模型，FA模型已停止演进，不再主推
Stage模型是未来方向：作为HarmonyOS NEXT主推且会长期演进的模型，Stage模型代表了鸿蒙应用开发的未来趋势
Stage模型的核心优势：
- 组件共享ArkTS引擎，减少内存占用
- UI与业务逻辑分离，架构更清晰
- 对后台进程有序治理，系统更安全
- 更好地支持多设备、分布式场景

6.2 选择建议

你的情况	建议
刚入门鸿蒙开发	直接学习Stage模型，无需了解FA模型
新项目立项	使用Stage模型开发
维护FA模型老项目	建议规划迁移到Stage模型
学习历史演进	了解FA模型有助于理解鸿蒙发展脉络，但无需深入研究

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

千问AI硬件开放平台

千问AI硬件开放平台是专为千问AI眼镜设计的生态开发平台，提供镜端、云端和APP端三端能力调用。平台包含两个子平台：技能平台面向个人和企业开发者，支持AI眼镜技能的全流程开发与发布（公开市场/个人私有/企业专属）；行业开放平台则为企业客户提供定制化服务，通过线下对接方式实现业务场景落地。该平台旨在推动智能穿戴行业解决方案的创新与发展。

人工智能6S服务平台

鸿蒙原生开发手记：徒步迹 - 自定义地图标记与气泡弹窗

自定义地图标记与气泡弹窗鸿蒙原生开发手记：徒步迹 - 自定义地图标记与气泡弹窗打造个性化地图交互，提升用户体验一、前言默认的地图标记样式单一，不能满足 App 的品牌需求。本文介绍如何实现自定义地图标

人工智能6S服务平台

HarmonyOS NEXT 鸿蒙使用 ScanKit 实现自定义扫码之解析相册图片二维码

本文介绍了HarmonyOSNEXT中利用ScanKit进行相册二维码解析的方法。ScanKit提供两种扫码方案："一键扫码"（集成相机和相册功能）和"自定义扫码"（需自行开发界面）。重点讲解了自定义扫码方案的核心API decodeImage的使用流程，包括图片数据获取、格式转换和识别调用。文章比较了两种方案的差异，指出一键扫码适合简单场景，自定义扫码则提