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. 目标与适用范围
- 说明如何在 Qt Widgets / Qt Quick 应用中构建分享内容，并通过 QtOhosExtras::ShareKit 打开系统分享面板。
- 介绍接收端如何在 Ability 启动或运行阶段 读取 Share Kit 注入的 QOhosSharedRecord。
- 给出从构建、部署到调试的关键步骤以及常见问题处理方式。
2. 开发环境与依赖
| 组件
|
|
|
|
|
|
|
|
|
|
|
说明：
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 官方限制：
``` 分享数据描述信息总量 ≤ 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 应用可以无缝集成系统级分享能力。开发者可基于示例扩展业务逻辑，为用户提供一致、安全、可控的跨应用分享体验。
|
|
|
|