Stage模型完全解析：应用架构与生命周期（2026版）Stage模型完全解析：应用架构与生命周期（2026版）目录

Stage模型完全解析：应用架构与生命周期（2026版）

基于 HarmonyOS 6.1 | 纯血鸿蒙 | 2025-2026 新体系

Stage模型概述

什么是Stage模型？

Stage模型 是 HarmonyOS 原生应用架构（2025年起完全替代旧版FA模型）。

核心概念：

Ability：应用能力的抽象（UIAbility、ExtensionAbility）
WindowStage：窗口管理器，负责UI展示
Context：应用/组件的上下文环境

FA模型 vs Stage模型（2025年已废弃FA）：

特性	FA模型（已废弃）	Stage模型（现行）
应用模型	Feature Ability	UIAbility + ExtensionAbility
窗口管理	每个Page独立窗口	统一WindowStage管理
进程模型	每个Ability独立进程	共享进程，隔离上下文
生命周期	Page生命周期	UIAbility + WindowStage 生命周期
适用版本	HarmonyOS 2-4	HarmonyOS 5+（纯血）

Ability 类型与选择

Ability 类型（HarmonyOS 6.1）

// entryability/EntryAbility.ets
import UIAbility from '@ohos.app.ability.UIAbility'
import window from '@ohos.window'

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    // 设置主页面
    windowStage.loadContent('pages/Index')
  }
}

Ability 类型对比：

类型	说明	使用场景
`UIAbility`	带UI界面的能力	主页面、功能页面
`ExtensionAbility`	扩展能力（无UI或轻量UI）	分享、文件选择、打印等
`ServiceExtensionAbility`	后台服务（无UI）	播放音乐、下载等
`FormExtensionAbility`	卡片能力	桌面卡片、原子化服务

创建Ability（2026版）

步骤1：定义Ability

// entryability/SecondAbility.ets
import UIAbility from '@ohos.app.ability.UIAbility'
import window from '@ohos.window'
import AbilityConstant from '@ohos.app.ability.AbilityConstant'
import Want from '@ohos.app.ability.Want'

export default class SecondAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.log('SecondAbility onCreate')
  }

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('SecondAbility onWindowStageCreate')
    windowStage.loadContent('pages/Second')
  }

  onWindowStageDestroy() {
    console.log('SecondAbility onWindowStageDestroy')
  }

  onDestroy() {
    console.log('SecondAbility onDestroy')
  }
}

步骤2：配置 module.json5

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      },
      {
        "name": "SecondAbility",
        "srcEntry": "./ets/entryability/SecondAbility.ets",
        "description": "第二个Ability",
        "icon": "$media:icon",
        "label": "Second",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": false  // 不对外暴露
      }
    ]
  }
}

UIAbility 生命周期

完整生命周期（HarmonyOS 6.1）

// entryability/EntryAbility.ets
import UIAbility from '@ohos.app.ability.UIAbility'
import window from '@ohos.window'
import AbilityConstant from '@ohos.app.ability.AbilityConstant'
import Want from '@ohos.app.ability.Want'

export default class EntryAbility extends UIAbility {
  // 1. Ability创建（整个生命周期只调用一次）
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.log('Ability onCreate')
    console.log('启动参数：', JSON.stringify(want))
  }

  // 2. WindowStage创建（UI加载入口）
  onWindowStageCreate(windowStage: window.WindowStage) {
    console.log('Ability onWindowStageCreate')
    
    // 设置UI内容
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error('加载页面失败：' + JSON.stringify(err))
        return
      }
      console.log('页面加载成功')
    })
  }

  // 3. WindowStage恢复（从后台到前台）
  onWindowStageRestore(windowStage: window.WindowStage) {
    console.log('Ability onWindowStageRestore')
  }

  // 4. Ability前台（可见可交互）
  onForeground() {
    console.log('Ability onForeground')
    // 恢复数据刷新、监听
  }

  // 5. Ability后台（不可见）
  onBackground() {
    console.log('Ability onBackground')
    // 保存状态、停止刷新
  }

  // 6. WindowStage销毁
  onWindowStageDestroy() {
    console.log('Ability onWindowStageDestroy')
  }

  // 7. Ability销毁
  onDestroy() {
    console.log('Ability onDestroy')
    // 清理资源
  }
}

生命周期调用时序

场景	调用顺序
首次启动	onCreate → onWindowStageCreate → onForeground
切换到后台	onBackground
从后台恢复	onForeground
关闭应用	onBackground → onWindowStageDestroy → onDestroy
配置变更（横竖屏）	onConfigurationUpdated

WindowStage 与窗口管理

Window 基础操作

// entryability/EntryAbility.ets
onWindowStageCreate(windowStage: window.WindowStage) {
  // 加载主页面
  windowStage.loadContent('pages/Index')

  // 获取主窗口
  let windowClass: window.Window = windowStage.getMainWindowSync()

  // 设置全屏
  windowClass.setWindowLayoutFullScreen(true)

  // 设置状态栏
  windowClass.setWindowSystemBarEnable(['status', 'navigation'])
  windowClass.setWindowSystemBarProperties({
    statusBarColor: '#ffffff',
    statusBarContentColor: '#000000'
  })

  // 设置窗口尺寸
  windowClass.resize(1080, 2340)

  // 设置窗口透明度
  windowClass.setWindowAlpha(0.9)
}

创建子窗口（2026版）

// pages/Index.ets
import window from '@ohos.window'

@Entry
@Component
struct Index {
  @State message: string = 'Hello'
  private subWindow: window.Window | null = null

  createSubWindow() {
    try {
      // 创建子窗口
      window.createWindow({
        ctx: getContext(this),
        type: window.WindowType.TYPE_APP,
        subWindowOptions: { title: '子窗口' }
      }, (err, subWindow) => {
        if (err.code) {
          console.error('创建子窗口失败：' + JSON.stringify(err))
          return
        }

        this.subWindow = subWindow

        // 加载子窗口内容
        subWindow.setUIContent('pages/SubPage')

        // 设置子窗口属性
        subWindow.resize(300, 400)
        subWindow.moveWindowTo(100, 100)

        // 显示子窗口
        subWindow.showWindow()
      })
    } catch (err) {
      console.error('异常：' + JSON.stringify(err))
    }
  }

  destroySubWindow() {
    if (this.subWindow) {
      this.subWindow.destroyWindow()
        .then(() => {
          console.log('子窗口销毁成功')
          this.subWindow = null
        })
    }
  }

  build() {
    Column() {
      Button('创建子窗口')
        .onClick(() => this.createSubWindow())
        .margin(8)

      Button('销毁子窗口')
        .onClick(() => this.destroySubWindow())
        .margin(8)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

Context 体系

Context 类型（HarmonyOS 6.1）

// 获取各类Context
@Entry
@Component
struct ContextDemo {
  @State info: string = ''

  aboutToAppear() {
    // 1. UIAbilityContext（Ability级别的Context）
    const uiAbilityContext = getContext(this) as common.UIAbilityContext
    console.log('BundleName：' + uiAbilityContext.bundleCodeDir)

    // 2. AbilityStageContext（Application级别的Context）
    const abilityStageContext = this.context.getApplicationContext()
    console.log('缓存目录：' + abilityStageContext.cacheDir)

    // 3. 获取文件目录
    const filesDir = uiAbilityContext.filesDir
    const cacheDir = uiAbilityContext.cacheDir
    const tempDir = uiAbilityContext.tempDir

    this.info = `文件目录：${filesDir}`
  }

  build() {
    Column() {
      Text(this.info)
        .fontSize(14)
        .margin(16)
    }
    .width('100%')
    .height('100%')
  }
}

Context 常用API

// 使用UIAbilityContext
const context = getContext(this) as common.UIAbilityContext

// 启动另一个Ability
context.startAbility({
  bundleName: 'com.example.myapp',
  abilityName: 'SecondAbility',
  parameters: {
    key1: 'value1',
    key2: 123
  }
})

// 获取数据
const data = context.getAbilityData('key1')

// 设置数据
context.setAbilityData('key1', 'newValue')

// 打开URL（调用系统浏览器）
context.openLink('https://www.harmonyos.com')

实战案例：多页面应用

页面路由（2026版）

// pages/Index.ets
import router from '@ohos.router'

@Entry
@Component
struct Index {
  build() {
    Column() {
      Button('跳转到详情页')
        .onClick(() => {
          router.pushUrl({
            url: 'pages/Detail',
            params: {
              id: 123,
              name: '张三'
            }
          }, router.RouterMode.Standard, (err) => {
            if (err) {
              console.error('跳转失败：' + JSON.stringify(err))
              return
            }
            console.log('跳转成功')
          })
        })
        .margin(8)

      Button('替换当前页（无返回栈）')
        .onClick(() => {
          router.replaceUrl({
            url: 'pages/Detail'
          })
        })
        .margin(8)

      Button('返回上一页')
        .onClick(() => {
          router.back()
        })
        .margin(8)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

接收路由参数

// pages/Detail.ets
import router from '@ohos.router'

@Entry
@Component
struct Detail {
  @State params: Record<string, Object> = {}

  aboutToAppear() {
    const params = router.getParams()
    this.params = params as Record<string, Object>
    console.log('接收到的参数：', JSON.stringify(params))
  }

  build() {
    Column() {
      Text(`ID：${this.params['id']}`)
        .fontSize(18)
        .margin(8)

      Text(`姓名：${this.params['name']}`)
        .fontSize(18)
        .margin(8)

      Button('返回')
        .onClick(() => router.back())
        .margin(16)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

总结

本文涵盖的2025-2026纯血鸿蒙Stage模型核心知识点：

✅ Stage模型架构（替代FA模型）
✅ Ability类型与选择（UIAbility、ExtensionAbility等）
✅ UIAbility完整生命周期
✅ WindowStage与窗口管理（主窗口、子窗口）
✅ Context体系（UIAbilityContext、AbilityStageContext）
✅ 实战：多页面路由

参考资料

最后更新：2026年5月 | 基于 HarmonyOS 6.1