docs: add attachment image preview rotate/zoom design and demo.
Capture the approved AttachmentUploadField preview enhancements (rotate, fit-full, wheel/button zoom, drag pan) before implementation. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
65d904fff1
commit
3583e6456b
2 files changed
+756
No files matched your search
@@ -0,0 +1,103 @@
|
||||
# 附件图片预览:旋转 / 缩放 / 拖拽(设计)
|
||||
|
||||
日期:2026-09-23
|
||||
状态:已确认方案,待实现
|
||||
Demo:`docs/superpowers/demos/2026-09-23-attachment-image-preview-rotate-demo.html`
|
||||
|
||||
## 背景
|
||||
|
||||
`web-admin` 通用附件组件 `AttachmentUploadField`(`web-admin/src/components/business/attachment-upload-field/index.vue`)已支持缩略图卡片与点击预览。图片预览弹窗目前仅静态展示,缺少方向纠正与细节查看能力。
|
||||
|
||||
用户要求:图片预览打开后支持左转 / 右转;旋转后仍须完整可见(不被预览区裁切);并支持滚轮与按钮缩放、拖拽平移。全部为**仅预览态**,不写回 MinIO / 不改存储 URL。
|
||||
|
||||
## 目标
|
||||
|
||||
1. 图片预览弹窗提供工具条:**左转、右转、缩小、放大、重置**。
|
||||
2. 预览区内:**鼠标滚轮缩放**、**按住拖拽平移**。
|
||||
3. 缩放倍率 = 1 时,任意 0° / 90° / 180° / 270° 下整图按外接矩形完整装入预览区。
|
||||
4. 关闭弹窗或点「重置」后,角度 / 缩放 / 偏移归零(重置可保留当前角度或一并归零——本设计约定「重置」= 角度保持、缩放与偏移归零;关闭弹窗则全部归零。与 Demo 一致:重置保留角度)。
|
||||
5. 视频、PDF、其它文档预览行为不变。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不把旋转结果写回对象存储或业务附件字段。
|
||||
- 不引入第三方图片预览库。
|
||||
- 本迭代不强制改造 `BxAttachmentUpload` / `BxAttachmentReadonly`(可后续复用同一交互;若改造成本低可顺带,但不作为门禁)。
|
||||
- 不做双指 pinch(桌面管理端为主)。
|
||||
|
||||
## 方案选择
|
||||
|
||||
| 方案 | 说明 | 结论 |
|
||||
|------|------|------|
|
||||
| A. 增强 `AttachmentUploadField` 现有预览弹窗 | 改动集中,所有使用该组件的页面自动受益 | **采用** |
|
||||
| B. 抽独立 `ImagePreviewDialog` | 边界更清晰,但需改调用点、范围更大 | 不做 |
|
||||
| C. 第三方预览库 | 体积与 Fresh Mint / 无 blur 风格对齐成本高 | 不做 |
|
||||
|
||||
## 交互与视觉
|
||||
|
||||
### 工具条
|
||||
|
||||
- 位置:预览弹窗 `body` 顶部居中。
|
||||
- 按钮(中性描边,对齐 Fresh Mint):左转、右转、缩小、放大、重置。
|
||||
- 状态文案:`{角度}° · {缩放百分比}%`(可选,便于调试与用户感知)。
|
||||
- 图标:使用 `@element-plus/icons-vue`(如 `RefreshLeft` / `RefreshRight` / `ZoomIn` / `ZoomOut` 或等价),按钮带文案时须有 leading icon(OpenSpec UI 约定)。
|
||||
|
||||
### 变换模型
|
||||
|
||||
- 状态:`angle`(度,步进 ±90)、`zoom`(相对「完整装入」的倍率,默认 1)、`offsetX` / `offsetY`(px)。
|
||||
- 显示变换:`translate(offset) rotate(angle) scale(fitBase * zoom)`。
|
||||
- `fitBase`:按图片自然宽高与预览区可用宽高,计算旋转后外接矩形,取 `min(stageW/boundW, stageH/boundH)`,保证 zoom=1 时完整可见。
|
||||
- `zoom` 范围建议:`0.5`~`5`;步进约 `0.15`(滚轮与按钮共用)。
|
||||
- zoom ≤ 1 时可将 offset 清零,避免缩小后画面偏出。
|
||||
- 窗口 / 弹窗尺寸变化时重新计算 `fitBase` 并应用。
|
||||
|
||||
### 输入
|
||||
|
||||
| 输入 | 行为 |
|
||||
|------|------|
|
||||
| 左转 / 右转 | angle ±90 |
|
||||
| 缩小 / 放大 | zoom ± step,夹紧到范围 |
|
||||
| 重置 | zoom=1,offset=0;**保留**当前 angle |
|
||||
| 滚轮(预览区) | preventDefault,缩放;不触发页面滚动 |
|
||||
| 拖拽(预览区) | pointer capture,更新 offset |
|
||||
| Esc / 关闭 | 关闭弹窗并清空全部预览状态 |
|
||||
| 键盘(可选增强) | ←/→ 旋转,+/- 缩放,0 等同重置 |
|
||||
|
||||
### 弹窗约束
|
||||
|
||||
- 保持现有:`append-to-body`、`modal-class="order-module-dialog-mask"`、无 backdrop blur、宽度约 860px。
|
||||
- 预览舞台固定高度(如 `min(62vh, …)`),`overflow: hidden`;放大后靠 translate 平移查看,不用滚动条作为主交互。
|
||||
|
||||
## 实现落点
|
||||
|
||||
**主文件**:`web-admin/src/components/business/attachment-upload-field/index.vue`
|
||||
|
||||
- 扩展现有 `el-dialog` 图片分支:工具条 + stage 事件。
|
||||
- 新增 refs / 计算:`previewAngle`、`previewZoom`、`previewOffset`、`applyPreviewTransform`、`fitBaseScale`。
|
||||
- `handlePreviewClosed`:重置全部预览状态。
|
||||
- 仅 `isImageFile(previewFile)` 时渲染工具条与交互;其它类型保持现状。
|
||||
|
||||
**样式**:同文件 scoped SCSS;按钮/stage 对齐 Demo 与 Fresh Mint(主色 `#10b981` 链,中性边框)。
|
||||
|
||||
**文档(可选)**:OpenSpec `ui-conventions`「附件上传卡片化布局」可补一句「图片预览支持旋转与缩放(仅预览态)」;非实现门禁,可与代码同 PR 或随后补。
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. 打开任意图片附件预览:可见左转 / 右转 / 缩小 / 放大 / 重置。
|
||||
2. 宽图转 90° 后,在 zoom=100% 时 TOP/BOTTOM 标记(或整图边缘)均在预览区内可见,无裁切。
|
||||
3. 滚轮与按钮均可缩放;放大后可拖拽平移。
|
||||
4. 关闭再打开:回到 0° · 100% · 无偏移。
|
||||
5. PDF / 视频预览无回归;上传 / 下载 / 删除不受影响。
|
||||
6. 不发起额外写文件 / 更新附件 URL 的请求。
|
||||
|
||||
## 风险与注意
|
||||
|
||||
- `transform` 与 `max-width`/`max-height` 同时使用易导致旋转后裁切;实现须以自然尺寸 + `fitBase * zoom` 为准(与 Demo 一致)。
|
||||
- 拖拽与点击关闭遮罩勿冲突:仅在 stage 内拖拽;遮罩点击仍关闭。
|
||||
- 滚动穿透:预览区 `wheel` 使用 `{ passive: false }` 并 `preventDefault`。
|
||||
|
||||
## 参考
|
||||
|
||||
- Demo:`docs/superpowers/demos/2026-09-23-attachment-image-preview-rotate-demo.html`
|
||||
- 组件:`web-admin/src/components/business/attachment-upload-field/index.vue`
|
||||
- UI 规范:`docs/web-admin-ui-spec-fresh-mint.md`;附件布局:OpenSpec `ui-conventions`「附件上传卡片化布局」
|
||||
Reference in new issue
Block a user