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 应用接续官方指南