Qt for HarmonyOS/user development/application continuation guild zh

From Qt Wiki
Jump to navigation Jump to search

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&lt;QByteArray&gt;
） 
QOhosAbilityContext::setContinuationActive(bool)
动态开关迁移能力 
QOhosOnContinueContext::setExitAppOnSourceDeviceAfterMigration(bool)
控制源端迁移成功后是否退出

源端实现（发起迁移）

实现步骤

  1. 监听迁移请求：
    continueRequestReceived
  2. 校验版本/业务条件：
    ctx-&gt;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-&gt;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"