feat(web-admin): add copy-to-clipboard for attachment images

Let users copy images next to download on shared attachment cards, preview toolbars, and list cells so they can paste into chat or docs without saving files first.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-11-14 23:18:34 +08:00
1 parent 53987bdf22
commit 43e240ad6a
11 files changed
+699 -14

No files matched your search

@@ -0,0 +1,77 @@
# Web 附件图片复制到剪贴板 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 在 Web 管理端公共附件展示处提供「复制」按钮,将图片写入系统剪贴板。
**Architecture:** 复用 `fetchAttachmentBlob` 取得图片 Blob,经 Clipboard API(`ClipboardItem` / PNG)写入剪贴板;在 `attachment-upload-field`、`attachment-preview-dialog` 及主要列表附件单元格与「下载」同级增加显式按钮。不改后端、不改小程序。
**Tech Stack:** Vue 3、TypeScript、Element Plus、现有 `web-admin/src/utils/download-attachment.ts` / `clipboard.ts`
**Spec:** `docs/superpowers/specs/2026-11-14-web-attachment-copy-clipboard-design.md`
**Issue:** https://gitea.aichengyan.com/cykj/shanxia2.0/issues/28
---
## File map
| 文件 | 职责 |
| --- | --- |
| `web-admin/src/utils/clipboard.ts` | 新增图片 Blob / 附件图片复制 API;保留现有文本复制 |
| `web-admin/src/utils/clipboard.image.test.ts`(或同目录既有测试风格) | 工具函数单测(mock clipboard / fetch) |
| `web-admin/src/components/business/attachment-upload-field/index.vue` | 卡片操作区 + 预览工具栏「复制」 |
| `web-admin/src/components/business/attachment-preview-dialog/index.vue` | 预览工具栏「复制」 |
| `web-admin/src/components/business/pl-plan-document-attachment-cell/index.vue` 等列表单元格 | 下载旁图片复制(按现有下载模式) |
---
### Task 1: 剪贴板图片工具函数
**Files:**
- Modify: `web-admin/src/utils/clipboard.ts`
- Create/Modify: 同目录或 `web-admin` 既有测试约定下的单测文件
- [x] **Step 1:** 实现 `ensurePngBlob(blob)`(已是 png 则直通,否则 ImageBitmap/canvas → PNG)
- [x] **Step 2:** 实现 `copyImageBlobToClipboard(blob): Promise<boolean>`(`navigator.clipboard.write` + `ClipboardItem`)
- [x] **Step 3:** 实现 `copyAttachmentImageToClipboard(file, options?)`:非图片返回 false;否则 `fetchAttachmentBlob` → `copyImageBlobToClipboard`
- [x] **Step 4:** 补充单元测试(mock `navigator.clipboard.write`、非图片短路、PNG 直通)
- [x] **Step 5:** 运行相关测试通过
### Task 2: 公共附件卡与内嵌预览
**Files:**
- Modify: `web-admin/src/components/business/attachment-upload-field/index.vue`
- [x] **Step 1:** 卡片 footer / compact 下载旁增加复制按钮(图片用图片复制;非图片可用 `copyTextToClipboard` 复制 URL 或隐藏复制)
- [x] **Step 2:** 图片预览工具栏增加「复制」按钮与 loading/禁用态
- [x] **Step 3:** 成功/失败 `ElMessage` 文案与设计一致
### Task 3: 独立预览弹窗
**Files:**
- Modify: `web-admin/src/components/business/attachment-preview-dialog/index.vue`
- [x] **Step 1:** 图片工具栏增加「复制」,调用同一工具函数
- [x] **Step 2:** 仅 `kind === 'image'` 显示
### Task 4: 主要列表附件单元格
**Files:**
- Modify: `pl-plan-document-attachment-cell`、`pl-cert-list-attachment-cell`、`pl-carrier-list-attachment-cell`、`pl-plan-list-cert-cell`(有下载角标处)
- [x] **Step 1:** 图片项在下载旁增加复制,`@click.stop`
- [x] **Step 2:** 非图片不显示图片复制(或仅复制链接,与 Task 2 策略一致)
### Task 5: 验证
- [x] **Step 1:** `pnpm exec tsx --test src/utils/clipboard.image.test.ts` — 5 pass
- [x] **Step 2:** `vue-tsc --noEmit`:本次改动文件无新增相关错误;全仓仍有 workflow 等既有错误与缺失 `.auto-import.json` 导致的 `reactive` 误报
- [ ] **Step 3:** 手工:预览弹窗复制图片后粘贴到微信/Word(待本机验收)
---
## 统一交互策略(实现锁定)
- 图片:复制位图到剪贴板;成功「已复制到剪贴板」
- 非图片:卡片/列表显示「复制链接」(`copyTextToClipboard`),成功「已复制链接」;预览弹窗非图片无复制按钮
- 失败:统一「复制失败,请允许剪贴板权限或改用下载」