1. 模型定位与演进

方向	FA（API≤8）	Stage（API≥9）
设计目标	轻量化单设备	复杂多设备、低内存、原生分布式
核心思想	Ability = UI + 业务	UI 与 Ability 解耦，统一进程共享引擎，组件级迁移
能力边界	固定三种 Ability	可无限派生 ExtensionAbility，系统能力即插即用

FA 模型中固定的 Page、Service、Data 三种类型不同，
Stage 模型将 Ability 主要分为两大类：UIAbility 和ExtensionAbility

OpenHarmony 自 API 9 版本起引入了全新的应用模型——Stage 模型，它标志着 OpenHarmony 应用开发框架的一次重大演进，后面版本都是主推Stage模型

2. 架构总览

2.1 进程与 VM

• 统一主进程：同一 Bundle 内所有 UIAbility + ServiceExtensionAbility + DataShareExtensionAbility 共享 1 个 ArkTS 引擎
• 独立进程（可配置）：Form、InputMethod、Wallpaper、WebView 渲染进程等，崩溃隔离 & 权限最小化。

2.2 生命周期解耦

UIAbility 生命周期：Create → Foreground → Background → Destroy
WindowStage 生命周期：Create → SHOWN/RESUMED → PAUSED → HIDDEN → Destroy

进入多任务仅 WindowStage 触发 PAUSED，UIAbility 仍 Foreground → 可继续播放音频。

---

3. Ability 分类与职责

3.1 UIAbility（有界面）

UIAbility 作为 Stage 模型中承载用户界面的核心组件，是构建任何 OpenHarmony 应用的基础。它不仅是应用与用户进行视觉和交互沟通的桥梁，也是应用生命周期管理的关键节点。一个应用可以包含一个或多个 UIAbility，每个
UIAbility 实例都对应一个独立的任务栈，负责管理其内部页面的导航和状态。深入理解 UIAbility
的核心概念、生命周期、应用场景以及启动模式。

回调	触发时机	必做/禁做
onCreate(want)	实例新建	只读一次性初始化；禁止 loadContent
onWindowStageCreate(ws)	窗口 ready	必须 ws.loadContent()；获取 Window 对象
onForeground()	切到前台	申请相机、定位等“可见时才需”资源
onBackground()	切到后台	释放相机、停止动画；可持久化数据
onNewWant(want)	热启动再次调用	解析参数并刷新 UI
onWindowStageDestroy()	窗口即将销毁	反注册窗口监听器
onDestroy()	实例即将销毁	释放所有资源、注销监听器

启动模式（module.json5 字段 launchType）

• standard：每次 startAbility 新建实例 → 多窗口浏览器
• singleton：全局唯一；再次启动清栈置顶 → 登录页、设置页
• specified：系统先回调 AbilityStage.onAcceptWant(want) → 返回 Key；相同 Key 复用实例 → 文档编辑器“同一文件单实例”

3.2 ExtensionAbility（无UI界面，派生类）

派生类	专属回调	配置项注意	典型场景
FormExtensionAbility	onCreateForm / onUpdateForm / onRemoveForm	type="form"，独立进程	桌面天气卡片
ServiceExtensionAbility	onCreate → onStart / onStop	type="service"，默认主进程	音乐播放、定位
DataShareExtensionAbility	query/insert/update/delete/batchInsert	type="dataShare"，需声明读写权限	联系人、日历提供方
WorkSchedulerExtensionAbility	onWorkStart / onWorkStop	type="workScheduler"，系统智能调度	Wi-Fi+充电时同步
InputMethodExtensionAbility	onCreate → onInitialize / onStartInput / onStopInput	type="inputMethod"，独立沙箱	自定义键盘
WallpaperExtensionAbility	onCreate → onWallpaperUpdate / onTouchEvent	type="wallpaper"	动态天气壁纸
AccessibilityExtensionAbility	onConnect / onAccessibilityEvent	type="accessibility"	读屏、自动化脚本
DriverExtensionAbility	onMount / onUnmount	type="driver"	外设挂载、云盘目录

所有 ExtensionAbility 禁止直接 loadContent；无 WindowStage。

核心功能：
| FormExtensionAbility:服务卡片
| ServiceExtensionAbility：后台服务
| DataShareExtensionAbility：数据共享
| WorkSchedulerExtensionAbility：延迟任务
| InputMethodExtensionAbility：自定义输入法
| WallpaperExtensionAbility：动态壁纸，比如卡片
| AccessibilityExtensionAbility：辅助功能
| DriverExtensionAbility 外设驱动

4. 配置文件 module.json5

"module": {
  "name": "entry",              // 模块名
  "type": "entry",              // entry/feature
  "srcPath": "src/main/ets",    // 源码根
  "mainElement": "MainAbility", // 桌面图标入口
  "abilities": [                // UIAbility 数组
    {
      "name": "MainAbility",    // 类名，全局唯一
      "srcEntry": "./ets/mainability/MainAbility.ts", // 入口 ts，可自定义
      "label": "$string:app_name",
      "icon": "$media:icon",
      "launchType": "singleton", // standard|singleton|specified
      "continuable": true,       // 跨设备迁移开关
      "backgroundModes": ["audioPlayback", "dataTransfer", "location"],
      "permissions": ["ohos.permission.CAMERA"], // 被调用方权限
      "skills": [{               // 隐式启动匹配
        "actions": ["ohos.want.action.home"],
        "entities": ["entity.system.home"]
      }],
      "metaData": {             // 自定义键值
        "key": "value"
      }
    }
  ],
  "extensionAbilities": [       // 扩展数组
    {
      "name": "MusicService",
      "type": "service",        // 必须系统枚举值
      "srcEntry": "./ets/service/MusicService.ts",
      "exported": false,        // 是否允许外部调用
      "permissions": ["ohos.permission.KEEP_BACKGROUND_RUNNING"]
    },
    {
      "name": "DataShare",
      "type": "dataShare",
      "exported": true,
      "readPermission": "ohos.permission.READ_CONTACTS",
      "writePermission": "ohos.permission.WRITE_CONTACTS"
    }
  ],
  "reqPermissions": [           // 安装时授予
    {"name": "ohos.permission.INTERNET"},
    {"name": "ohos.permission.GET_NETWORK_INFO"}
  ],
  "allowAppUsePrivilegeExtension": [ // 特权白名单，需系统预置
    "ServiceExtensionAbility",
    "DataShareExtensionAbility"
  ]
}

---

5. 组件通信与数据回流

5.1 正向传参

let want: Want = {
  bundleName: 'com.demo.app',
  abilityName: 'DetailAbility',
  parameters: {
    itemId: 1001,
    jsonStr: JSON.stringify(obj)
  }
};
context.startAbility(want);

支持标准类型 + ArrayBuffer + PixelMap + 序列化对象

5.2 反向回值

调用方

context.startAbilityForResult(want, (err, data) => {
  if (!err) {
    let ret = data.parameters?.result as number;
  }
});

被调用方

let result: Want = { parameters: { result: 99 } };
this.context.terminateSelfWithResult(result);

---

6. 跨模型互通矩阵

调用方	目标 FA 组件	目标 Stage 组件	备注
Stage	PageAbility ✅	UIAbility ✅	直接 Want
Stage	ServiceAbility ✅	ServiceExtension ✅	connectAbility
Stage	DataAbility ❌	DataShareExtension ✅	URI 不兼容，系统拒绝
FA	PageAbility ✅	UIAbility ✅	同上
FA	ServiceAbility ✅	ServiceExtension ✅	同上
FA	DataAbility → DataShareExtension	✅（框架自动转换 URI 前缀）	openFile/getType 缺失，仅 CRUD

---

7. 跨设备迁移实战

1. 模块级 continuable: true
2. 获取对端 deviceId

import deviceManager from '@ohos.distributedDeviceManager';
let deviceList = deviceManager.getTrustedDeviceListSync();
let targetId = deviceList[0].deviceId;

3. 构造跨设备 Want

let want: Want = {
  deviceId: targetId,        // 关键字段
  bundleName: 'com.demo.app',
  abilityName: 'PlayerAbility',
  parameters: { seek: 1200 } // 当前播放进度
};
context.startAbility(want);

4. 对端 Ability 在 onCreate/onNewWant 中读取参数并恢复 UI

系统底层完成分布式序列化、反序列化、窗口重建。

---

8. 内存与功耗优化清单

• 统一进程共享引擎 → 复杂应用内存 ↓40%
• Background 及时释放相机、传感器、动画
• 使用 WorkSchedulerExtensionAbility 替代常驻后台轮询
• Form 独立进程，卡片崩溃不拉垮主应用
• WebView 独立渲染进程，阻塞不影响主线程

---

9. FA → Stage 迁移步骤

1. 新建 Stage 工程，原 config.json → module.json5
2. 类继承改为 extends UIAbility，删除 featureAbility 引用
3. 生命周期对齐：
   onStart → onCreate
onActive/onInactive → 监听 WindowStage 事件
4. 页面路由 router.push 继续可用；多实例需求改 launchType
5. ServiceAbility → ServiceExtensionAbility，DataAbility → DataShareExtensionAbility
6. 去除 particleAbility 依赖，统一使用 Want 通信

---

10. 踩坑速查

问题	原因	解决
启动后白屏	未在 onWindowStageCreate 里 loadContent	必须 windowStage.loadContent('pages/Index')
后台音乐被 Kill	未配置 backgroundModes	加 "audioPlayback" 且用 ServiceExtensionAbility
跨设备失败	continuable=false / 未配对同一账号	检查设备互信 & 字段
Form 不刷新	onUpdateForm 未返回正确数据	确保 formBindingData.createFormBindingData(obj)
独立 Extension 崩溃主进程	默认主进程，需强制独立	在系统配置里声明 process=":form"