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` 打开系统分享面板。

1. 介绍接收端如何在 Ability 启动或运行阶段 读取 Share Kit 注入的 `QOhosSharedRecord`。

1. 给出从构建、部署到调试的关键步骤以及常见问题处理方式。

---

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 应用可以无缝集成系统级分享能力。开发者可基于示例扩展业务逻辑，为用户提供一致、安全、可控的跨应用分享体验。