技术文档丨Qt for HarmonyOS应用生命周期概述
先导知识
先导知识
鸿蒙应用生命周期相关文档：
应用生命周期（Stage模型）
UIAbility组件生命周期
UIAbilityContext API参考
Qt for HarmonyOS应用生命周期概述
Qt for HarmonyOS应用生命周期概述
在鸿蒙系统中，应用生命周期管理遵循Stage模型，主要包括UIAbility组件的生命周期管理。Qt for HarmonyOS应用作为鸿蒙生态的一部分，同样需要适配这一生命周期模型。
Qt for HarmonyOS应用的生命周期主要涉及以下几个方面：
应用启动与初始化
应用间交互（拉起其他应用/被其他应用拉起）
多实例管理
应用退出
应用启动与初始化
应用启动与初始化
在Qt for HarmonyOS中，应用启动流程是由系统自动管理的，开发者无需关心底层细节。实际流程如下：
系统启动鸿蒙Stage模型下的UIAbility组件
UIAbility组件通过NAPI方式调用启动Qt线程
系统自动加载Qt应用的共享库，并调用Qt应用的main函数
Qt应用的主窗口被创建并显示在HarmonyOS的WindowStage中
对开发者来说，应用的入口仍然是main函数，无需关注更多细节。
应用间交互（拉起其他应用/被其他应用拉起）
应用间交互（拉起其他应用/被其他应用拉起）
在Qt for HarmonyOS中，可以使用QtOhosExtras模块提供的API (startAbility)来拉起其他应用，替代传统Qt中的QProcess方案。
注意：下面的方法只能拉起带界面应用。
拉起其他应用
显式匹配（指定包名和Ability名）
void MainWindow::startSpecificApp(){QtOhosExtras::QOhosWant want;want.bundleName = "com.example.targetapp"; // 目标应用的包名want.abilityName = "MainAbility"; // 目标应用的Ability名称// 可选：传递参数QJsonObject parameters;parameters.insert("key", "value");want.parameters = parameters;// 启动目标应用QtOhosExtras::startAbility(want);}
隐式匹配（通过action和uri匹配）
void MainWindow::startAppByAction(){QtOhosExtras::QOhosWant want;want.action = "ohos.want.action.viewData"; // 操作类型want.type = "text/plain"; // 数据类型want.uri = "content://example/data"; // 数据URI// 可选：传递参数QJsonObject parameters;parameters.insert("key", "value");want.parameters = parameters;// 启动匹配的应用QtOhosExtras::startAbility(want);}
被其他应用拉起
当Qt应用被其他应用拉起时，需要处理接收到的Want参数。
在模块的module.json5里面配置如下：
"abilities": [{"name": "QAbility","srcEntry": "./ets/qability/QAbility.ets","launchType": "specified","description": "$string:QAbility_desc","icon": "$media:icon","label": "$string:QAbility_label","startWindowIcon": "$media:icon","startWindowBackground": "$color:start_window_background","exported": true,"skills": [{"entities": ["entity.system.home"],"actions": ["action.system.home","ohos.want.action.viewData" // 支持的action类型],"uris": [{"type": "*/*"}] // 支持的数据类型}]}]
处理接收到的Want
#include <QtOhosExtras/QtOhosExtras>void MainWindow::init(){// 连接Want接收信号QObject::connect(QtOhosExtras::QOhosUiAbilityContext::instance(),&QtOhosExtras::QOhosUiAbilityContext::newWantReceived,this,&MainWindow::onNewWantReceived);}void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want){// 处理接收到的Want参数qDebug() << "Received want with action:" << want.action;qDebug() << "URI:" << want.uri;qDebug() << "Type:" << want.type;// 处理参数if (want.parameters.contains("key")) {QString value = want.parameters.value("key").toString();processParameter(value);}// 根据Want内容执行相应操作if (want.action == "ohos.want.action.viewData") {openDataForViewing(want.uri);}}
多实例管理
多实例管理
在HarmonyOS系统中，应用可以有多种实例模式：单实例、多实例单进程、多实例多进程。Qt for HarmonyOS应用需要根据需求选择合适的模式。
注意：这里的实例指的是UIAbility实例。
单实例模式
当应用被再次拉起时，使用现有实例处理新的请求：
void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want){// 使用现有窗口处理新请求processNewRequest(want);this->setText(want.uri); // 单实例单进程：原窗口处理}
多实例单进程模式
每次被拉起时创建新的UIAbility实例，但共享同一进程：
void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want){// 创建新窗口实例MainWindow *newWindow = new MainWindow();newWindow->processRequest(want);newWindow->show();}
多实例多进程模式
启动新的应用进程创建新的UIAbility实例处理请求：
void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want){// 启动新进程static int processCounter = 0;QString processName = "Process" + QString::number(processCounter++);// 使用QtOhosExtras启动新进程QtHarmonyOSExtras::startAppProcess(processName, want);}
注意：多实例多进程模式需要在module.json5中添加配置：
"abilities": [{"name": "QAbility",// 其他配置..."isolationProcess": true}]
应用退出
应用退出
窗口关闭拦截
HarmonyOS平台提供了多层级的关闭拦截机制，Qt通过完整的窗口关闭事件拦截系统，支持应用在不同关闭场景下进行自定义处理。本指南将详细说明该功能的实现机制、使用方法，并提供完整的代码示例。
Qt for HarmonyOS实现了完整的窗口关闭事件拦截机制，适配 HarmonyOS系统的三种等级预关闭系统：
关闭拦截层级架构
HarmonyOS系统提供了三个层级的拦截机制，Qt for HarmonyOS目前支持前两个层级：
Level 1:
窗口级别拦截
用户点击窗口关闭按钮时触发
支持完全用户交互，可显示保存对话框
用户可选择取消关闭
Level 2:
Ability级别拦截
任务中心/Dock缩略图关闭时触发
支持快速保存操作
时间有限，建议快速处理
Level 3:
AbilityStage级别拦截
当前暂未支持
理论上用于最高优先级的系统级关闭
实际场景会降级到Level 2处理
关闭方式与拦截等级对应关系
Qt API详解
关闭事件上下文系统
Qt for HarmonyOS通过关闭事件上下文系统来区分不同的关闭来源：
QOhosCloseEventContext - 关闭事件上下文管理器
QCloseEvent扩展 - 在HarmonyOS平台添加了上下文成员
QtOhosExtras公共API - 提供给开发者的接口
关闭原因枚举
// QtOhosExtras 公共API枚举namespace QtOhosExtras {enum class CloseEventRootCause {InternalClose, // 内部关闭（应用程序化调用close()）AbilityClose, // Ability关闭（任务中心/Dock缩略图）WindowStageClose, // Window关闭（窗口关闭按钮）};}
获取关闭事件原因API
// 获取关闭事件根本原因的APIQtOhosExtras::CloseEventRootCause QtOhosExtras::getCloseEventRootCause(QCloseEvent *event);
参数详解
参数 | 类型 | 说明 |
event | QCloseEvent* | Qt关闭事件对象指针 |
返回值说明
返回值 | 含义 | 触发场景 |
InternalClose | 内部关闭 | 应用调用close()、程序逻辑关闭 |
WindowStageClose | 窗口级关闭(Level 1) | 用户点击窗口关闭按钮 |
AbilityClose | Ability级关闭 (level 2) | 任务中心、Dock缩略图关闭 |
开发实现
实现关闭拦截功能的关键在于：重写 closeEvent() 函数并根据关闭原因进行不同处理
1
简单的关闭拦截
class MyMainWindow : public QMainWindow {protected:void closeEvent(QCloseEvent *event) override {// 获取关闭事件的原因auto rootCause = QtOhosExtras::getCloseEventRootCause(event);switch (rootCause) {case QtOhosExtras::CloseEventRootCause::WindowStageClose:// 用户点击关闭按钮handleWindowClose(event);break;case QtOhosExtras::CloseEventRootCause::AbilityClose:// 任务中心关闭handleAbilityClose(event);break;case QtOhosExtras::CloseEventRootCause::InternalClose:// 程序内部关闭event->accept();break;}}private:void handleWindowClose(QCloseEvent *event) {// 窗口关闭按钮：可以显示对话框if (hasUnsavedData()) {int ret = QMessageBox::question(this, "确认关闭","有未保存的数据，是否保存？",QMessageBox::Save |QMessageBox::Discard |QMessageBox::Cancel);if (ret == QMessageBox::Save) {saveData();event->accept();} else if (ret == QMessageBox::Discard) {event->accept();} else {event->ignore(); // 取消关闭}} else {event->accept();}}void handleAbilityClose(QCloseEvent *event) {// 任务中心关闭：快速处理if (hasUnsavedData()) {saveData(); // 自动保存}event->accept();}bool hasUnsavedData() const {// 检查是否有未保存数据return m_hasUnsavedData;}void saveData() {// 保存数据m_hasUnsavedData = false;}private:bool m_hasUnsavedData = false;};
2
项目配置
# 项目配置文件QT += core gui widgets ohosextrasSOURCES += main.cpp mainwindow.cppHEADERS += mainwindow.h
QT += ohosextras：必须添加此模块以使用关闭拦截API
适用场景
文档编辑器：Word、Excel等需要保存确认的应用
代码编辑器：IDE、代码编辑器等开发工具
图形设计软件：Photoshop类应用，防止意外丢失工作
数据库管理工具：需要确保数据完整性的应用
媒体编辑应用：视频、音频编辑器等长时间工作的应用
开发注意事项
Level 3拦截支持状态
当前状态：Level 3拦截（abilityStage.onPrepareToTerminate）暂未支持
影响场景：系统关机、Dock右键菜单、系统托盘关闭等
实际行为：这些场景可能会触发Level 2拦截（ability.onPrepareToTerminate），表现为AbilityClose事件
使用建议
窗口关闭：可以显示完整的保存对话框
任务中心关闭：建议快速自动保存，避免耗时操作
系统级关闭：系统关机、Dock右键菜单等场景可能触发AbilityClose事件，应妥善处理
测试验证：在不同关闭方式下测试，确保应用能正确响应。
