docs: 分享 spec 终稿——文本统一单换行、图片不降级、视频不实现、图片走系统分享兜底

三端文本统一 title\ndescription(单换行,无url)；图片(type2/3)剪贴板PIXELMAP尽力 +指引窗内systemImage可靠兜底；type4视频H5未用安全空实现；systemLink/systemVideo退役。附图片剪贴板粘贴不可保证的验证结论与真机验证项。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-27 13:04:12 +08:00
parent 669d34918d
commit b0277e902e
1 changed files with 29 additions and 26 deletions
@@ -56,41 +56,38 @@ H5 → friendsSharetypeUrlToptitleDescript(SharetypeBean)
  └─ sharefriend=="1"  → SharePanel(微信/QQ/抖音/取消)
        └─ 选定渠道 → 按渠道+type 组装内容 + 写剪贴板 → ShareGuideDialog(platform)
              ├─「打开 微信/QQ/抖音」 canOpenLink + openLink(scheme) best-effort 打开 App，用户自行粘贴
-              ├─「更多分享方式」     systemShare 系统面板（兜底）
+              ├─「用系统分享」       systemText(文本) / systemImage(图片)（可靠兜底）
              └─「取消」
 ```

 - `sharefriend=="1"` 弹自有 `SharePanel`（沿用现状）；`=="2"` 不弹、直接微信指引窗。
- 指引窗对所有 `type` 都先把可分享内容写入剪贴板（文本/图片/视频 URI），再展示。
+- 指引窗展示前先把可分享内容写入剪贴板（文本 PLAIN_TEXT / 图片 PIXELMAP，尽力）；图片粘贴不可保证，指引窗内「系统分享」按钮（`systemImage`）作可靠交付。

-## 5. 内容组装（逐渠道对齐原工程）
+## 5. 内容组装

-文本拼接函数 `buildShareText(bean, platform)` —— **三端文本一律不含 `webpageUrl`**：
+### 5.1 文本格式（三端统一）

-| 渠道 | 文本(type1,3) 格式 | 备注 |
-|---|---|---|
-| 微信 | `title\ndescription` | 单换行、**不含 url**（第二/三层均不带）；无缩略图概念 |
-| QQ | `title\n\ndescription` | 双换行、不含 url（对齐原工程） |
-| 抖音 | `title\ndescription` | 单换行、**不含 url**（第二/三层均不带） |
+`buildShareText(bean)` = `title\ndescription`（**单换行、三端完全一致、不含 `webpageUrl`**）。空字段跳过对应行，避免多余空行。

- 空字段跳过对应行，避免多余空行。三端差异仅在换行数（QQ 双、微信/抖音 单）。
- **`webpageUrl` 不再出现在任何文本/链接分享路径**；仅作 type4 的本地视频文件路径使用。
- `type "3"`（图片链接）按纯文本（`title`+`description`）处理，不带 url。
+- **"不含 url" 仅指文本分享**；图片分享按图片走，**绝不降级为文本**。
+- `webpageUrl` 仅 `type "3"`（图片链接）用作图片来源 URL；`type "1"` 文本不使用；`type "4"` 视频 H5 未用、不实现。

-类型处理：
+### 5.2 类型处理

-| type | 内容 | 剪贴板 | 系统分享兜底 |
-|---|---|---|---|
-| 1 网页/文本 | `buildShareText`（无 url） | PLAIN_TEXT | `systemText`(PLAIN_TEXT, 无 url) |
-| 2 Canvas 截图 | `captureCanvas(sharetype)` → `saveDataUrlToFile` 沙箱 | PIXELMAP | `systemImage` |
-| 3 图片链接 | 同 type1（纯文本, 无 url） | PLAIN_TEXT | `systemText` |
-| 4 视频(抖音) | 本地视频 `webpageUrl` | 文件 URI | `systemVideo`；远程视频降级为 `systemText`(无 url) |
+| type | H5 用途 | 内容来源 | 第二层（剪贴板+指引窗） | 第三层（指引窗内「系统分享」按钮） |
+|---|---|---|---|---|
+| 1 | 网页/文本 | `buildShareText`（无 url） | PLAIN_TEXT 文本 | `systemText`(PLAIN_TEXT, 无 url) |
+| 2 | Canvas 截图 | `captureCanvas(sharetype)` → `saveDataUrlToFile` 沙箱图片 | PIXELMAP（**尽力**，对方支持才可粘贴） | `systemImage`（**可靠主交付**） |
+| 3 | 图片链接（低优先） | 从 `webpageUrl` 下载图片 → 沙箱，同 type2 图片管线 | PIXELMAP（尽力） | `systemImage` |
+| 4 | 视频 | **H5 未使用** | —— | —— |

-> 系统分享（第三层）统一用 `PLAIN_TEXT(title+description)`，**不再使用 `systemLink`/HYPERLINK**（即不下发 url）。`systemLink` 退役。
+- **图片（type2/3）走「剪贴板图片(尽力) + 指引窗」**：复制 PIXELMAP（对方支持则可长按粘贴），指引窗同时提供「用系统分享」按钮 → `systemImage` 作可靠兜底（系统把图片文件交给目标 App）。理由：经验证微信/QQ 鸿蒙版能否粘贴 PIXELMAP 不可保证（§10），`systemImage` 才是确定能把图片交付的路径。
+- **type4 视频**：H5 未用，分支**安全空实现**（不报错、不出站），不实现视频分享。
+- **系统分享统一不下发 url**：文本 `systemText(title+description)`、图片 `systemImage`，**不再使用 `systemLink`/HYPERLINK**。`systemLink` 退役。

 ## 6. `sharesuccess` 回传（仅微信，乐观）

- 用户在微信指引窗点「打开微信」或「更多分享方式」即视为已发起 → `callHandler('sharesuccess', {success:2, type})`。
+- 用户在微信指引窗点「打开微信」或「用系统分享」即视为已发起 → `callHandler('sharesuccess', {success:2, type})`。
 - `type = (sharefriend=='1') ? 1 : 2`。
 - 点「取消」 / 微信未安装且无法打开 → `{success:3, type}`。
 - QQ、抖音**不回传**（与契约一致）。
@@ -99,13 +96,17 @@ H5 → friendsSharetypeUrlToptitleDescript(SharetypeBean)

 ### 7.1 重写 `feature_capabilities/.../providers/ShareProvider.ets`
 - 保留：`FriendsShare` 注册、`PHOTO_UPLOAD`（`LocalUploadServer` 截图上传）链路 → 改为走微信指引窗（图片）。
- 新增：`sharefriend` 分流、`buildShareText` 逐渠道、`writeClipboard`（文本/PIXELMAP/URI）、`showGuide` 经事件投给 UI、`openAppByScheme`（`canOpenLink`+`openLink`）。
+- 新增：`sharefriend` 分流、`buildShareText`（统一 `title\ndescription`）、`writeClipboard`（文本 PLAIN_TEXT / 图片 PIXELMAP）、`showGuide` 经事件投给 UI、`openAppByScheme`（`canOpenLink`+`openLink`）。
+- 图片管线：type2 走 `captureCanvas`→`saveDataUrlToFile`；type3 从 `webpageUrl` 下载→沙箱（复用平台层 `Downloader/HttpClient`，低优先）；二者复用 PIXELMAP 写剪贴板 + `systemImage`。
+- type4 视频：安全空实现（不报错、不出站）。
 - 预留空分支：`qqSdkShare()` / `douyinSdkShare()`（注释 TODO，注册到位后接 SDK）。
- 复用：现有 `systemShare` 方法（`systemText/systemImage/systemVideo`，**`systemLink` 退役不再使用**）、`saveDataUrlToFile`、`captureCanvas`。
+- 复用：现有 `systemShare` 方法（`systemText/systemImage`，**`systemLink`/`systemVideo` 退役不再使用**）、`saveDataUrlToFile`、`captureCanvas`。
 - 移除：对 `WeChatApi.sendShare` / `WXMediaMessage` / `WXWebpageObject` / `WXImageObject` / `SendMessageToWXReq` 的全部分享调用。

 ### 7.2 新增 `entry/.../components/ShareGuideDialog.ets`
- 自绘弹窗：渠道图标（复用 `share_wechat/share_qq/share_douyin`）+「内容已复制，请打开 XX 粘贴分享」+ 三按钮（打开 App / 更多分享方式 / 取消）。
+- 自绘弹窗：渠道图标（复用 `share_wechat/share_qq/share_douyin`）+ 文案 + 三按钮（打开 App / 用系统分享 / 取消）。
+- 文案按内容类型：文本类「内容已复制，请打开 XX 粘贴分享」；图片类「图片已复制，可在 XX 长按粘贴；或点下方用系统分享」。
+- 「用系统分享」按钮：文本→`systemText`、图片→`systemImage`。
 - 经 `EventBus`（仿 `SharePanel` 的 `SHOW_PANEL`/一次性回投模式）与 `BridgeGameContainer` 通信。

 ### 7.3 `feature_capabilities/.../wx/WeChatApi.ets`
@@ -131,9 +132,10 @@ H5 → friendsSharetypeUrlToptitleDescript(SharetypeBean)

 ## 9. 测试与验收

- 单元测试（`entry/src/test`，纯逻辑）：`buildShareText` 三渠道格式、空字段裁剪、`type` 分支映射。
+- 单元测试（`entry/src/test`，纯逻辑）：`buildShareText` 统一格式、空字段裁剪、`type`/`sharefriend` 分支映射（含 type4 安全空实现不报错）。
 - 设备验证（真机/模拟器）：
-  - `friendsSharetypeUrlToptitleDescript` 各 `type`/`sharefriend` 组合弹窗正确、剪贴板内容正确、系统分享面板可拉起。
+  - `friendsSharetypeUrlToptitleDescript` 各 `type`/`sharefriend` 组合弹窗正确、剪贴板内容正确、指引窗「系统分享」可拉起（文本 systemText / 图片 systemImage）。
+  - **人工真机验证（需配合）**：图片 PIXELMAP 复制后能否在微信/QQ 鸿蒙版对话框长按粘贴出图片——结果登记到风险册，决定是否保留剪贴板图片这条尽力路径。
  - 微信渠道 `sharesuccess` 乐观回传时机正确；QQ/抖音不回传。
  - `devecocli build` 通过、`code-linter` 无新增告警。
 - 验收基线：H5 调用全程不报错、不卡死（`DefaultHandler` 兜底仍在）。
@@ -142,3 +144,4 @@ H5 → friendsSharetypeUrlToptitleDescript(SharetypeBean)

 - **拉起 App 仅"打开"不预填**：`openLink(scheme)` 只能打开 App，用户需手动粘贴；体验弱于原工程微信 SDK，已与用户确认接受。
 - **scheme 可用性**：`mqqapi`/`snssdk1128` 能否 `canOpenLink` 取决于对方鸿蒙版注册情况；不可用时指引窗降级为纯文案提示，不报错。
+- **图片剪贴板粘贴不可保证**：微信/QQ 鸿蒙版是否支持读取 PIXELMAP 类型剪贴板未知（且 API 12+ 读剪贴板有权限管控）；故图片以指引窗内 `systemImage`（系统分享）为可靠交付，剪贴板图片仅尽力而为。待人工真机验证后登记风险册。