Qt for HarmonyOS/user development/application continuation guild zh

简介

本文面向 Qt 开发者，介绍如何在 HarmonyOS 上实现“应用接续”（跨设备迁移应用状态）。QtOhosExtras 模块已封装鸿蒙

onContinue

/

onNewWant

等流程，开发者仅需使用 Qt 接口完成迁移请求、数据封装与目标端恢复。

能力与模块

• 能力：在设备间迁移当前应用状态，支持快速预热（ContinueQuickStart）与源端保留/退出。
• 模块：

  qtohosextras
  

  • 核心类：

    QOhosAbilityContext
    

    、

    QOhosOnContinueContext
    

    、

    QOhosWantInfo
    

  • 工具函数：

    QtOhosExtras::tryGetOnContinueData
    

• 数据通道：<100KB 通过 Want parameters 携带（Base64 的

  QByteArray
  

  ，键名

  __io_qt_on_continue_migration_data
  

  ）；传输更多数据的功能 Qt 暂未实现，将会在后续版本提供。

工作流程

1. 源端收到迁移请求（

   continueRequestReceived
   

   ） → 序列化业务状态 → 同意/拒绝 → 按需决定源端是否退出。
2. 目标端通过启动或

   newWantInfoReceived
   

   收到 Want → 用

   tryGetOnContinueData()
   

   恢复状态。
3. 可选：配置 ContinueQuickStart 预热；动态开关迁移能力；控制源端保留/退出。

核心 API 速览

API	说明
QOhosAbilityContext::continueRequestReceived	源端迁移请求信号
QOhosOnContinueContext	提供同意/拒绝/版本不匹配响应，设置源端是否退出
QOhosAbilityContext::newWantInfoReceived	目标端接收新 Want 信号（热启动）
QOhosWantInfo::launchReason()	获取启动原因： StartAbility / PrepareContinuation / Continuation
QtOhosExtras::tryGetOnContinueData(const QOhosWant &want)	提取迁移数据（返回 QSharedPointer<QByteArray> ）
QOhosAbilityContext::setContinuationActive(bool)	动态开关迁移能力
QOhosOnContinueContext::setExitAppOnSourceDeviceAfterMigration(bool)	控制源端是否在成功迁移后退出

源端实现（发起迁移）

1. 监听迁移请求：连接

   continueRequestReceived
   

   信号。
2. 校验版本/业务条件：检查

   ctx->sourceApplicationVersionCode()
   

   。
3. 序列化状态并响应：
   • 同意：

     setAgreeResponse(serialized)
     

     （数据需 <100KB）。
   • 版本不匹配：

     setMismatchResponse()
     

     。
   • 拒绝：

     setRejectResponse()
     

     。
4. 是否保留源端：调用

   setExitAppOnSourceDeviceAfterMigration(false)
   

   （默认值为 true，即退出）。
5. 动态开关：根据业务逻辑调用

   setContinuationActive(bool)
   

   。

示例（同意迁移，保留源端）：

auto ability = QOhosAbilityContext::getInstanceForMainWindow(window.windowHandle());
QObject::connect(ability.get(), &QOhosUiAbilityContext::continueRequestReceived,
    [](auto ctx) {
        auto appVersion = QOhosAppContext::instance()->getBundleInfo()->versionCode();
        if (ctx->sourceApplicationVersionCode() == appVersion) {
            QByteArray payload = /* serialize state (<100KB) */;
            ctx->setAgreeResponse(payload);
            ctx->setExitAppOnSourceDeviceAfterMigration(false); // 需要保留源端
        } else {
            ctx->setMismatchResponse();
        }
    });

目标端实现（接收与恢复）

1. 冷启动获取：

   auto wantInfo = QOhosAppContext::getAppLaunchWantInfo();
   

2. 运行时获取：监听

   QOhosAbilityContext::newWantInfoReceived
   

   信号。
3. 场景区分：检查

   launchReason()
   

   是否为

   Continuation
   

   。
4. 提取数据：使用

   QtOhosExtras::tryGetOnContinueData
   

   。
5. 恢复 UI：反序列化数据还原业务状态。

示例（处理冷启动与热启动）：

// 1. 冷启动处理
if (auto launchInfo = QOhosAppContext::getAppLaunchWantInfo()) {
    auto data = QtOhosExtras::tryGetOnContinueData(launchInfo->want());
    if (data) { /* 反序列化并恢复状态 */ }
}

// 2. 热启动处理（应用已在后台运行）
auto ability = QOhosAbilityContext::getInstanceForMainWindow(window.windowHandle());
QObject::connect(ability.get(), &QOhosUiAbilityContext::newWantInfoReceived,
    [](const QSharedPointer<QOhosWantInfo> &info) {
        if (info->launchReason() == QOhosWantInfo::LaunchReason::Continuation) {
            auto data = QtOhosExtras::tryGetOnContinueData(info->want());
            if (data) { /* 反序列化并恢复状态 */ }
        }
    });

快速预热（ContinueQuickStart）

• 适用场景：希望目标端先拉起界面占位，待数据传输完成后再刷新内容。
• 配置：在

  module.json5
  

  目标 Ability 的

  continueType
  

  字段末尾添加

  _ContinueQuickStart
  

  。
• 流程：系统先触发

  PrepareContinuation
  

  （预热），随后触发

  Continuation
  

  （携带数据）。

示例（区分预热与正式数据）：

QObject::connect(ability.get(), &QOhosUiAbilityContext::newWantInfoReceived,
    [](const QSharedPointer<QOhosWantInfo> &info) {
        switch (info->launchReason()) {
        case QOhosWantInfo::LaunchReason::PrepareContinuation:
            // 执行轻量级初始化或显示加载占位图
            break;
        case QOhosWantInfo::LaunchReason::Continuation:
            auto data = QtOhosExtras::tryGetOnContinueData(info->want());
            if (data) { /* 恢复完整业务状态 */ }
            break;
        default:
            break;
        }
    });

注意事项

• 显式响应：未响应迁移请求默认视为拒绝，务必在回调中明确处理。
• 线程安全：回调在 Qt 主线程执行，但仍需注意避免耗时的同步操作阻塞 UI。
• 数据限制：目前仅支持 <100KB 数据。若超出此限制，迁移可能会失败。
• 向前兼容：迁移数据建议携带版本号，以便目标端处理来自旧版本源端的接续数据。

参考资源

• 示例代码：

  qtohosextras/examples/qtohosextras/applicationcontinuation/main.cpp
  

• 源码实现：

  qtohosextras/src/ohosextras/qohosabilitycontext.cpp
  

• 外部链接：HarmonyOS 应用接续官方指南