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 设备

|

Italic textShare 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 官方限制：

 ``` 分享数据描述信息总量 ≤ 200KB```
 ``` 条目总数 ≤ 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 控制选项表单说明

控件																				--- 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 启动阶段解析 调用 `QOhosAppContext::getAppLaunchWantInfo()` 使用 `tryGetSharedRecordsFromShareKit()` 解析分享数据 将 `QOhosSharedRecord` 转换为业务数据 4.2 运行时监听 连接 `newWantInfoReceived` 信号 在回调中重复解析流程，支持多次分享 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 应用可以无缝集成系统级分享能力。开发者可基于示例扩展业务逻辑，为用户提供一致、安全、可控的跨应用分享体验。