Qt for HarmonyOS/user development/application share guild zh

Qt for HarmonyOS Share Kit 集成指南

本文档基于以下示例撰写，帮助开发者快速在 Qt for HarmonyOS 应用中集成 Share Kit 分享能力：

• 发送端 Demo：qtohosextras/examples/qtohosextras/abilitycontext/sharedata（核心文件 main.cpp）
• 接收端 Demo：qtohosextras/examples/qtohosextras/abilitycontext/sharedatareceiver（核心文件 main.cpp）

1. 目标与适用范围

1. 说明如何在 Qt Widgets / Qt Quick 应用中构建分享内容，并通过 QtOhosExtras::ShareKit 打开系统分享面板。
2. 介绍接收端如何在 Ability 启动或运行阶段 读取 Share Kit 注入的 QOhosSharedRecord。
3. 给出从构建、部署到调试的关键步骤以及常见问题处理方式。

2. 开发环境与依赖

组件	说明
Qt 模块	QtWidgets, QtOhosExtras（包含 ShareKit, QOhosAbilityContext, QOhosAppContext 等）
构建工具	qmake + make，或 DevEco Studio 集成的 cmake kit
运行环境	支持 Share Kit 的 HarmonyOS 设备

说明: Share Kit 默认通过系统分享面板完成权限授权，通常无需手动声明权限。但需确保目标设备系统版本支持分享能力。

2.1 module.json5 配置（接收端 *必填*）

在目标应用的 module.json5 中为接收分享的 UIAbility 声明 skills 过滤器：

{
  "abilities": [
    {
      "name": "EntryAbility",
      "skills": [
        {
          "actions": [
            "ohos.want.action.sendData"
          ],
          "uris": [
            {
              "scheme": "file",
              "utd": "general.image",
              "maxFileSupported": 9
            }
          ]
        }
      ]
    }
  ],
  "requestPermissions": [
    { "name": "ohos.permission.INTERNET" }
  ]
}

• actions 固定为 ohos.want.action.sendData
• uris.utd 需穷举接收端支持的所有数据类型（遵循 UTD 预置列表）
• Share Kit 官方限制:

 1. 分享数据描述信息总量 ≤ 200KB
 2. 条目总数 ≤ 500

• 未正确声明上述配置，应用将不会出现在系统分享面板的候选列表中

3. 发送端实现指南

参考：sharedata/main.cpp

3.1 关键步骤

1. 准备分享记录

• 文本记录：

 QtOhosExtras::ShareKit::createContentRecord(QMimeType, QString)

• 文件记录：

 createFileRecord(const QFileInfo &)（自动推断 MIME）

• 缩略图（可选）：

 读取 :/qt_logo.png 并通过 setThumbnail() 设置

2. 配置记录元数据

调用以下接口增强系统面板展示信息：

• setTitle()
• setDescription()
• setLabel()
• setExtraData()

3. 配置控制选项（可选）

• QtOhosExtras::ShareKit::createControllerOptions()
• setSingleSelectionMode()
• setDefaultPreviewMode()
• setAnchor(x, y)（大屏场景下固定弹出位置）

4. 调用分享接口

• 通过 QOhosAbilityContext::getDefaultInstance() 获取上下文
• 调用：shareDataWithShareKit(records, controllerOptionsOrNull)
• Share Kit 弹出系统面板并等待用户选择接收应用

5. 界面交互建议

• 示例使用复选框 / SpinBox 调整控制参数
• 通过 m_recordsToShareLabel 提示当前分享条目数量

3.2 控制选项表单说明

控件	作用
Add Text/File Record	添加文本或文件记录
Remove Records	清空当前分享记录
Use Controller Options	控制器总开关
Default Preview Mode	是否展示默认预览
Single Selection Mode	限制单一接收方
Anchor X / Y	设置面板锚点

3.3 代码示例

auto record = QtOhosExtras::ShareKit::createContentRecord(
    QMimeDatabase().mimeTypeForName("text/plain"),
    QStringLiteral("Record %1 Content").arg(index));

record->setTitle(QStringLiteral("Record %1 Title").arg(index));
record->setDescription(QStringLiteral("Record %1 Description").arg(index));

auto abilityContext = QtOhosExtras::QOhosAbilityContext::getDefaultInstance();
abilityContext->shareDataWithShareKit({ record }, controllerOptionsOrNull);

3.4 多记录分享

• Share Kit 支持同时分享多个 `QOhosSharedRecord`
• 建议限制一次分享的记录数量和大小
• 在 UI 中明确提示当前分享内容

4. 接收端实现指南

参考：`sharedatareceiver/main.cpp`

4.1 启动阶段解析

1. 调用 `QOhosAppContext::getAppLaunchWantInfo()`

1. 使用 `tryGetSharedRecordsFromShareKit()` 解析分享数据

1. 将 `QOhosSharedRecord` 转换为业务数据

4.2 运行时监听

1. 连接 `newWantInfoReceived` 信号

1. 在回调中重复解析流程，支持多次分享

4.3 UI 展示

• 示例使用 `QTextEdit` 作为日志输出
• 文件读取前校验：

 `QFileInfo(record->filePath()).isReadable()`

---

5. Share Data 记录字段说明

字段	发送端设置	接收端读取																																--- 6. 构建与部署 6.1 命令行 # Sender cd qtohosextras/examples/qtohosextras/abilitycontext/sharedata qmake sharedata.pro make # Receiver cd qtohosextras/examples/qtohosextras/abilitycontext/sharedatareceiver qmake sharedatareceiver.pro make --- 6.2 运行验证 安装接收端应用 启动发送端 Demo 点击 “Share Records” 在接收端 UI 中确认收到数据 --- 7. 常见问题与处理 问题 --- 8. 扩展建议 自定义 MIME（如 `application/json`） 批量文件分享（注意大小限制） 多窗口场景结合 `setAnchor()` 增强错误提示与日志 分享前进行安全校验 --- 9. 结语 通过组合 `QtOhosExtras::ShareKit`、`QOhosAbilityContext` 与 `QOhosAppContext`， Qt for HarmonyOS 应用可以无缝集成系统级分享能力。开发者可基于示例扩展业务逻辑，为用户提供一致、安全、可控的跨应用分享体验。