Qt for OpenHarmony/user development guide

English 中文

先导知识

鸿蒙应用生命周期相关文档：

应用生命周期（Stage模型）

UIAbility组件生命周期

UIAbilityContext API参考

Qt for OHOS应用生命周期概述

在鸿蒙系统中，应用生命周期管理遵循Stage模型，主要包括UIAbility组件的生命周期管理。Qt for OHOS应用作为鸿蒙生态的一部分，同样需要适配这一生命周期模型。

Qt for OHOS应用的生命周期主要涉及以下几个方面：

1. 应用启动与初始化

2. 应用间交互（拉起其他应用/被其他应用拉起）

3. 多实例管理

4. 应用退出

应用启动与初始化

在Qt for OHOS中，应用启动流程是由系统自动管理的，开发者无需关心底层细节。实际流程如下：

1. 系统启动鸿蒙Stage模型下的UIAbility组件

2. UIAbility组件通过NAPI方式调用启动Qt线程

3. 系统自动加载Qt应用的共享库，并调用Qt应用的main函数

4. Qt应用的主窗口被创建并显示在OHOS的WindowStage中

对开发者来说，应用的入口仍然是main函数，无需关注更多细节。

应用间交互（拉起其他应用/被其他应用拉起）

在Qt for OHOS中，可以使用QtOhosExtras模块提供的API (startAbility)来拉起其他应用，替代传统Qt中的QProcess方案。

注意：下面的方法只能拉起带界面应用。

拉起其他应用

显式匹配（指定包名和Ability名）

#include <QtOhosExtras/qohoswant.h>
#include <QtOhosExtras/qohosuiabilitycontext.h>

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.json里面配置如下：

"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);
    }
}

多实例管理

在OpenHarmony系统中，应用可以有多种实例模式：单实例、多实例单进程、多实例多进程。Qt for OHOS应用需要根据需求选择合适的模式。

注意：这里的实例指的是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启动新进程
    QtOhosExtras::startAppProcess(processName, want);
}

注意：多实例多进程模式需要在module.json5中添加配置：

"abilities": [
  {
    "name": "QAbility",
    // 其他配置...
    "isolationProcess": true
  }
]