Jump to content

Qt for HarmonyOS/user development/application continuation guild zh

From Qt Wiki

Qt for HarmonyOS 应用接续开发指南

简介

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

QtOhosExtras 模块已封装 HarmonyOS 的 onContinue / onNewWant 等流程，开发者仅需使用 Qt 接口完成迁移请求、数据封装与目标端恢复。

能力与模块

能力

  • 在设备间迁移当前应用状态
  • 支持快速预热（ContinueQuickStart）
  • 支持源端保留 / 退出策略控制

模块

  • 模块名：qtohosextras
  • 核心类：
    • QOhosAbilityContext
    • QOhosOnContinueContext
    • QOhosWantInfo
  • 工具函数：
    • QtOhosExtras::tryGetOnContinueData

数据通道限制

  • 小于 100KB：通过 Want parameters 携带
    • 数据类型：Base64 的 QByteArray
    • 键名：__io_qt_on_continue_migration_data
  • 大于 100KB：Qt 暂未实现，将在后续版本提供

工作流程

  1. 源端收到迁移请求（continueRequestReceived）
    • 序列化业务状态（<100KB）
    • 同意 / 拒绝 / 版本不匹配响应
    • 按需决定源端是否退出
  2. 目标端收到 Want（冷启动或热启动）
    • 使用 tryGetOnContinueData() 提取迁移数据
    • 反序列化并恢复 UI 状态
  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. 序列化状态（<100KB）并响应：
    • 同意：setAgreeResponse(serialized)
    • 版本不匹配：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); // keep source
        } else {
            ctx->setMismatchResponse();
        }
    });

参考： examples/qtohosextras/applicationcontinuation/main.cpp

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

实现步骤

  1. 冷启动获取：
    • auto wantInfo = QOhosAppContext::getAppLaunchWantInfo();
  2. 运行时获取：
    • 监听 QOhosAbilityContext::newWantInfoReceived
  3. 场景区分：
    • launchReason() == PrepareContinuation（预热）
    • launchReason() == Continuation（正式迁移数据）
  4. 提取数据：
    • auto data = QtOhosExtras::tryGetOnContinueData(wantInfo->want());
  5. 恢复状态：
    • 反序列化 data，还原业务状态并刷新 UI

示例：冷启动 + 热启动恢复

// Cold start
if (auto launchInfo = QOhosAppContext::getAppLaunchWantInfo()) {
    auto data = QtOhosExtras::tryGetOnContinueData(launchInfo->want());
    if (data) { /* deserialize and restore */ }
}

// Hot start
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) { /* deserialize and restore */ }
        }
    });

快速预热（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:
            // Warm-up / placeholder
            break;
        case QOhosWantInfo::LaunchReason::Continuation: {
            auto data = QtOhosExtras::tryGetOnContinueData(info->want());
            if (data) { /* deserialize and restore */ }
            break;
        }
        default:
            break;
        }
    });

动态开关迁移

适用场景

特定页面不允许迁移时关闭，需要迁移前再开启。

接口

QOhosAbilityContext::setContinuationActive(bool)（默认开启）

示例

auto ability = QOhosAbilityContext::getInstanceForMainWindow(window.windowHandle());
ability->setContinuationActive(false); // disable
ability->setContinuationActive(true);  // enable when needed

源端退出策略

说明

默认情况下，迁移成功后系统会关闭源端；调试或需要保留源端时可将其设置为 false。

接口

QOhosOnContinueContext::setExitAppOnSourceDeviceAfterMigration(bool)

示例：同意迁移但保留源端

QObject::connect(ability.get(), &QOhosUiAbilityContext::continueRequestReceived,
    [](auto ctx) {
        auto appVersion = QOhosAppContext::instance()->getBundleInfo()->versionCode();
        if (ctx->sourceApplicationVersionCode() == appVersion) {
            ctx->setAgreeResponse(QByteArray("Migration Test Data"));
            ctx->setExitAppOnSourceDeviceAfterMigration(false);
        } else {
            ctx->setMismatchResponse();
        }
    });

快速上手清单

  1. 源端：监听 continueRequestReceived，序列化数据 <100KB，调用 setAgreeResponse 或 mismatch/reject；按需设置退出策略与迁移开关。
  2. 目标端：通过 launchReason() 判定预热/正式；使用 tryGetOnContinueData 提取并恢复状态。
  3. 需要预热：配置 continueType 为 _ContinueQuickStart，在 PrepareContinuation 只做轻量处理。

参考路径

  • 示例：qtohosextras/examples/qtohosextras/applicationcontinuation/main.cpp
  • 实现：qtohosextras/src/ohosextras/qohosabilitycontext.cpp/.h
  • Want 定义：qtohosextras/src/ohosextras/qohoswant.h

注意事项

  • 未响应迁移请求默认视为拒绝，请在回调中明确处理。
  • 回调在 Qt 线程执行，避免跨线程操作 UI。
  • 迁移数据需向前兼容，协议变更时携带版本并做好容错。
  • Qt 暂未支持大于 100KB 数据的接续，将在未来版本中提供。
  • 更多说明参考：HarmonyOS 应用接续官方指南（外部链接）
Retrieved from "https://wiki.qt.io/index.php?title=Qt_for_HarmonyOS/user_development/application_continuation_guild_zh&oldid=45154"