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 记录字段说明

字段	发送端设置	接收端读取	备注
MIME 类型	createContentRecord / createFileRecord	record->mimeType().name()	区分文本、图片等
文本内容	createContentRecord	record->content()	文件记录为空
文件路径	createFileRecord	record->filePath()	指向系统临时拷贝路径，读取后可删除
标题 / 描述 / 标签	setTitle / setDescription / setLabel	record->title() 等	面板展示信息
缩略图	setThumbnail	无需读取	仅用于系统分享面板展示
extraData	setExtraData	record->extraData()	业务自定义扩展字段

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 运行验证

1. 安装接收端应用
2. 启动发送端 Demo
3. 点击 “Share Records”
4. 在接收端 UI 中确认收到数据

7. 常见问题与处理

问题	排查建议
分享面板未弹出	确认 QtOhosExtras 模块已正确打包，且目标设备支持 Share Kit
接收端无数据	检查发送端 records 是否为空；确认已在分享面板中选择接收应用；必要时打印 Want 原始内容进行排查
文件路径不可读	在接收端读取前校验 QFileInfo::isReadable()
多次分享覆盖	使用 extraData 或为每批分享记录添加时间戳进行区分

8. 扩展建议

• 自定义 MIME（如 `application/json`）
• 批量文件分享（注意大小限制）
• 多窗口场景结合 `setAnchor()`
• 增强错误提示与日志
• 分享前进行安全校验

9. 结语

通过组合 QtOhosExtras::ShareKit、QOhosAbilityContext 与 QOhosAppContext， Qt for HarmonyOS 应用可以无缝集成系统级分享能力。开发者可基于示例扩展业务逻辑，为用户提供一致、安全、可控的跨应用分享体验。