文档开发者中心
我的

第 11 节:从 C++ 到 ArkTS —— Stage 模型与 UIAbility 生命周期

浏览47发布于2026-07-22 06:20天津

摘要

在 Qt 中,QApplication 管理事件循环,QMainWindow 有 showEvent/hideEvent/closeEvent 等生命周期回调。鸿蒙的 Stage 模型对应这套体系:UIAbility 是应用的窗口承载单元,拥有完整生命周期回调;AbilityStage 是模块级入口。本节对标 Qt 的生命周期机制,讲清 Stage 模型的核心架构。


11.1 Stage 模型全景

收起
自动换行
深色代码主题
复制
应用 (App)
├── AbilityStage          ← 模块入口(类似 QApplication 的初始化)
│   ├── UIAbility         ← 窗口承载单元(类似 QMainWindow)
│   │   ├── pages/        ← 页面组件
│   │   └── WindowStage   ← 窗口舞台(管理显示内容)
│   └── UIAbility         ← 可有多个(多窗口/多入口)
└── HAP/HSP               ← 打包单元(类似 .exe / .dll)

Qt 类比:

  • AbilityStage ≈ QApplication(应用级初始化)
  • UIAbility ≈ QMainWindow(窗口生命周期)
  • WindowStage ≈ QWindow / QGraphicsScene(显示内容的容器)

11.2 UIAbility 生命周期 —— 对标 QMainWindow

UIAbility 有 7 个生命周期回调,对标 Qt 的窗口事件:

收起
自动换行
深色代码主题
复制
Create → WindowStageCreate → Foreground → Background → WindowStageDestroy → Destroy
                                         ↑___________|
                                           (可来回切换)
ArkUI 回调 触发时机 Qt 对应 典型操作
onCreate Ability 创建时(一次) 构造函数 / QMainWindow 初始化 加载数据、初始化状态
onWindowStageCreate 窗口创建时 showEvent 加载首页 UI、设置窗口内容
onForeground 进入前台(可见) focusInEvent / showEvent 恢复定时器、刷新数据
onBackground 进入后台(不可见) focusOutEvent / hideEvent 暂停定时器、保存草稿
onWindowStageDestroy 窗口销毁 closeEvent 释放 UI 资源
onDestroy Ability 销毁(一次) 析构函数 释放全部资源
onConfigurationUpdate 配置变化(旋转等) resizeEvent / 主题切换 适配新配置

11.3 代码实现

收起
自动换行
深色代码主题
复制
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {

  // 1. 创建 —— 类似 QMainWindow 构造
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    console.log('Ability onCreate');
    // 全局初始化:读取配置、初始化 AppStorage
    AppStorage.setOrCreate('userName', want.parameters?.userName ?? 'Guest');
  }

  // 2. 窗口创建 —— 类似 showEvent + setCentralWidget
  onWindowStageCreate(windowStage: window.WindowStage): void {
    console.log('onWindowStageCreate');

    // 加载首页 —— 类似 setCentralWidget(new MainPage)
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error(`Failed to load content. ${JSON.stringify(err)}`);
      }
    });
  }

  // 3. 进入前台 —— 类似 focusInEvent
  onForeground(): void {
    console.log('onForeground');
    // 恢复定时器、刷新数据、重连 WebSocket
  }

  // 4. 进入后台 —— 类似 focusOutEvent / hideEvent
  onBackground(): void {
    console.log('onBackground');
    // 暂停定时器、保存草稿、断开 WebSocket
  }

  // 5. 窗口销毁 —— 类似 closeEvent
  onWindowStageDestroy(): void {
    console.log('onWindowStageDestroy');
    // 释放 UI 相关资源
  }

  // 6. Ability 销毁 —— 类似析构
  onDestroy(): void {
    console.log('onDestroy');
    // 释放全部资源
  }

  // 7. 配置变化 —— 类似 resizeEvent
  onConfigurationUpdate(newConfig: ConfigurationConstant.Configuration): void {
    console.log('onConfigurationUpdate');
    // 屏幕旋转、语言切换、深色模式切换
  }
}

Qt 类比:Qt 中你重写 showEvent、hideEvent、closeEvent 等虚函数;ArkUI 中你重写 onForeground、onBackground 等方法。机制完全一致——框架在特定时机回调你。


11.4 前后台切换的实战处理

这是最常用的生命周期场景。用户把 App 切到后台再切回来,你需要暂停和恢复:

收起
自动换行
深色代码主题
复制
export default class MusicPlayerAbility extends UIAbility {
  private timer: number = -1;

  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 初始化全局状态
    AppStorage.setOrCreate('isPlaying', false);
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/MusicPlayer', (err) => {
      if (err.code) console.error(JSON.stringify(err));
    });
  }

  onForeground(): void {
    // 用户切回 App —— 恢复播放、刷新列表
    console.log('回到前台,恢复播放');
    const isPlaying = AppStorage.get('isPlaying');
    if (isPlaying) {
      this.resumePlayback();
    }
    // 刷新在线数据
    this.refreshData();
  }

  onBackground(): void {
    // 用户切到后台 —— 暂停播放、保存进度
    console.log('进入后台,保存进度');
    this.saveProgress();
    // 注意:音乐可以继续在后台播放(需要后台任务能力,后续课程讲)
  }

  private resumePlayback(): void { /* ... */ }
  private saveProgress(): void { /* ... */ }
  private refreshData(): void { /* ... */ }
}

对比 Qt:

cpp复制

收起
自动换行
深色代码主题
复制
void MainWindow::focusInEvent(QFocusEvent *e) {
    if (m_wasPlaying) m_player->play();
    refreshData();
}
void MainWindow::focusOutEvent(QFocusEvent *e) {
    saveProgress();
}

逻辑一样,只是回调名字不同。


11.5 页面组件的生命周期

除了 UIAbility 的生命周期,ArkUI 页面组件(@Entry 标注的 struct)也有自己的生命周期:

收起
自动换行
深色代码主题
复制
@Entry
@Component
struct HomePage {
  // 组件即将出现(进入可见区域前)
  aboutToAppear(): void {
    console.log('aboutToAppear');
    // 发起网络请求、订阅事件
    this.loadData();
  }

  // 组件已出现(UI 渲染完成)
  onPageShow(): void {
    console.log('onPageShow');
    // 页面完全显示,可做动画
  }

  // 组件即将消失(离开页面时)
  onPageHide(): void {
    console.log('onPageHide');
    // 取消订阅、暂停动画
  }

  // 组件销毁
  aboutToDisappear(): void {
    console.log('aboutToDisappear');
    // 释放定时器、清理引用
  }

  @State data: string[] = [];

  loadData(): void {
    setTimeout(() => {
      this.data = ['Item 1', 'Item 2', 'Item 3'];
    }, 1000);
  }

  build() {
    Column() {
      ForEach(this.data, (item: string) => {
        Text(item).padding(16)
      })
    }
  }
}

生命周期对照:

ArkUI 页面回调 触发时机 Qt 对应
aboutToAppear 组件创建后、渲染前 构造函数末尾 / setupUi()
onPageShow 页面变为当前显示页 showEvent
onPageHide 页面被其他页面覆盖 hideEvent
aboutToDisappear 组件即将销毁 析构函数 / deleteLater

注意区分:onPageShow/onPageHide 是页面级的(路由切换时触发);aboutToAppear/aboutToDisappear 是组件级的(组件创建/销毁时触发)。@Entry 页面两者都有,普通 @Component 子组件只有 aboutToAppear/aboutToDisappear。


11.6 生命周期全景图

收起
自动换行
深色代码主题
复制
应用启动
  │
  ├─ AbilityStage.onAddConfiguration  ← 模块加载
  │
  ├─ UIAbility.onCreate               ← Ability 创建
  │    │
  │    ├─ UIAbility.onWindowStageCreate  ← 窗口创建
  │    │    │
  │    │    ├─ Page.aboutToAppear        ← 页面组件初始化
  │    │    ├─ Page.onPageShow           ← 页面显示
  │    │    │    │
  │    │    │    ├─ <用户交互>           ← 正常使用
  │    │    │    │
  │    │    │    ├─ Page.onPageHide      ← 路由跳走 / 切后台
  │    │    │    └─ Page.onPageShow      ← 路由回来 / 切前台
  │    │    │
  │    ├─ UIAbility.onForeground        ← 进入前台
  │    ├─ UIAbility.onBackground        ← 进入后台
  │    │    (可多次来回)
  │    │
  │    ├─ UIAbility.onWindowStageDestroy ← 窗口销毁
  │    │    ├─ Page.onPageHide
  │    │    └─ Page.aboutToDisappear     ← 页面组件销毁
  │    │
  └─ UIAbility.onDestroy                ← Ability 销毁

11.7 实战:数据加载与资源清理

收起
自动换行
深色代码主题
复制
@Entry
@Component
struct ArticlePage {
  @State articles: Article[] = [];
  @State loading: boolean = false;
  private refreshTimer: number = -1;

  // 组件创建时加载初始数据
  aboutToAppear(): void {
    console.log('aboutToAppear: 加载文章');
    this.loadArticles();
  }

  // 页面显示时刷新数据 + 启动定时刷新
  onPageShow(): void {
    console.log('onPageShow: 刷新数据');
    this.loadArticles();

    // 每 30 秒刷新一次
    this.refreshTimer = setInterval(() => {
      this.loadArticles();
    }, 30000);
  }

  // 页面隐藏时停止定时器
  onPageHide(): void {
    console.log('onPageHide: 停止定时器');
    if (this.refreshTimer !== -1) {
      clearInterval(this.refreshTimer);
      this.refreshTimer = -1;
    }
  }

  // 组件销毁时做最终清理
  aboutToDisappear(): void {
    console.log('aboutToDisappear: 清理资源');
    if (this.refreshTimer !== -1) {
      clearInterval(this.refreshTimer);
    }
  }

  async loadArticles(): Promise<void> {
    this.loading = true;
    setTimeout(() => {
      this.articles = [
        { id: 1, title: 'ArkTS 入门' },
        { id: 2, title: 'ArkUI 实战' },
      ];
      this.loading = false;
    }, 1000);
  }

  build() {
    Column() {
      if (this.loading) {
        LoadingProgress().width(40).height(40)
      } else {
        List() {
          ForEach(this.articles, (article: Article) => {
            ListItem() {
              Text(article.title).padding(16)
            }
          })
        }
      }
    }
  }
}

interface Article {
  id: number;
  title: string;
}

Qt 类比:

  • aboutToAppear ≈ 构造函数中 loadData()
  • onPageShow ≈ showEvent 中 m_timer->start(30000)
  • onPageHide ≈ hideEvent 中 m_timer->stop()
  • aboutToDisappear ≈ 析构中 delete m_timer

逻辑完全对应,只是 API 名字不同。


11.8 AbilityStage —— 模块入口

AbilityStage 是 HAP 模块加载时的入口,比 UIAbility 更早执行:

收起
自动换行
深色代码主题
复制
import { AbilityStage } from '@kit.AbilityKit';

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    // 应用启动时最先执行 —— 类似 main() 中的 QApplication 初始化
    console.log('AbilityStage onCreate');
    this.initGlobalConfig();
  }

  onAcceptWant(want: Want): string {
    // 处理启动请求,返回 UIAbility 实例标识
    // 用于多实例场景(类似 Qt 中创建多个 MainWindow)
    return 'EntryAbility';
  }

  private initGlobalConfig(): void {
    AppStorage.setOrCreate('apiBase', 'https://api.example.com');
    AppStorage.setOrCreate('appVersion', '1.0.0');
  }
}

Qt 类比:AbilityStage.onCreate() ≈ int main() { QApplication app; initGlobalConfig(); ... }。在第一个窗口创建之前做全局初始化。


11.9 速查:ArkUI 生命周期 vs Qt 生命周期

层级 ArkUI Qt 用途
模块入口 AbilityStage.onCreate main() + QApplication 全局初始化
窗口创建 UIAbility.onCreate QMainWindow 构造 Ability 级初始化
窗口显示 onWindowStageCreate showEvent 加载 UI 内容
前台 onForeground focusInEvent 恢复运行
后台 onBackground focusOutEvent 暂停运行
窗口关闭 onWindowStageDestroy closeEvent 释放 UI
窗口销毁 onDestroy 析构 释放全部
配置变化 onConfigurationUpdate resizeEvent 适配变化
组件初始化 aboutToAppear setupUi 加载数据
页面显示 onPageShow showEvent 刷新+定时器
页面隐藏 onPageHide hideEvent 停定时器
组件销毁 aboutToDisappear 析构 清理资源

本节思考题

Q1:用户正在浏览文章列表页,突然来电话把 App 切到后台。通话结束后切回 App。这个过程中,onPageHide/onPageShow 和 onBackground/onForeground 的触发顺序是什么?

答案:触发顺序为:

  1. 来电切后台:onBackground → onPageHide(页面不可见)
  2. 通话结束切回:onForeground → onPageShow(页面重新可见)

注意:onBackground/onForeground 是 UIAbility 级的(整个应用进后台/前台),onPageHide/onPageShow 是页面级的。Ability 切后台时页面也会隐藏,所以两者都会触发。

Q2:你在 onPageShow 中启动了一个 30 秒的定时器刷新数据,在 onPageHide 中停止它。但如果用户直接按返回键退出页面(触发 aboutToDisappear),定时器会被停掉吗?

答案:不会自动停掉!aboutToDisappear 不会自动调用 onPageHide。如果 aboutToDisappear 中没有 clearInterval,定时器会泄漏。正确做法是在 aboutToDisappear 中也做清理:

收起
自动换行
深色代码主题
复制
aboutToDisappear(): void {
  if (this.refreshTimer !== -1) {
    clearInterval(this.refreshTimer);
    this.refreshTimer = -1;
  }
}

 

这和 Qt 一样——析构函数里必须释放资源,不能依赖 closeEvent 先被调用。

Q3:你需要实现一个聊天应用:进入页面时连接 WebSocket,离开页面时断开,切后台时保持连接但停止消息提醒,切前台时恢复提醒。应该在哪些回调中处理?

答案:

收起
自动换行
深色代码主题
复制
// 页面级管理连接生命周期
@Entry
@Component
struct ChatPage {
  aboutToAppear(): void {
    this.connectWebSocket();    // 组件创建时连接
  }

  onPageShow(): void {
    this.enableNotification();  // 页面可见时开启消息提醒
  }

  onPageHide(): void {
    this.disableNotification(); // 页面不可见时关闭提醒
  }

  aboutToDisappear(): void {
    this.disconnectWebSocket(); // 组件销毁时断开连接
  }
}

// Ability 级处理前后台差异
export default class ChatAbility extends UIAbility {
  onBackground(): void {
    // 切后台:保持 WebSocket 连接(不断开)
    // 改为通知栏推送消息
    this.enablePushNotification();
  }

  onForeground(): void {
    // 切前台:恢复应用内提醒,清除通知栏
    this.disablePushNotification();
  }
}

分层处理:页面级用 aboutToAppear/aboutToDisappear 管理连接生命周期,Ability 级用 onBackground/onForeground 管理前后台差异行为。

收藏
0
回复
0
分享
全部评论
暂无评论
暂无评论
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
摘要
11.1 Stage 模型全景
11.2 UIAbility 生命周期 —— 对标 QMainWindow
11.3 代码实现
11.4 前后台切换的实战处理
11.5 页面组件的生命周期
11.6 生命周期全景图
11.7 实战:数据加载与资源清理
11.8 AbilityStage —— 模块入口
11.9 速查:ArkUI 生命周期 vs Qt 生命周期
本节思考题
了解社区公约,与您携手共创和谐专业的开发者社区。