画布与贴纸功能

本文档描述当前前端代码中已实现的画布设计功能。事实来源是 frontend/src/pages/CanvasStudio.tsx、frontend/src/App.tsx、frontend/src/components/ExportPanel.tsx、frontend/src/lib/stickerLibrary.ts、frontend/src/lib/canvasDocument.ts 和 frontend/src/types.ts。

页面关系

TemplateHome（首页）
    ├── CanvasStudio（画布设计页）─ 添加词云 ─→ TestWorkbench（词云生成页）
    ├── TestWorkbench（词云生成页）─ 返回画布 ─→ CanvasStudio
    └── HelpPage（帮助页）

应用默认进入首页，展示模板列表
画布页顶部的"添加词云"会切换到词云生成页
词云生成页顶部的"返回画布"会回到画布设计页
词云生成页导出面板保留下载 SVG/位图功能，并新增"作为贴纸导入贴纸库"

贴纸库

贴纸库是前端本地能力，不依赖后端接口：

存储位置：localStorage 的 wordcloud-sticker-library
数据类型：StickerAsset，当前支持 svg 和 image 两类，已实现入口主要使用 svg
用户导入 SVG：画布页左侧"贴纸"面板读取 .svg 文件文本，写入贴纸库，并立即插入画布
词云作为贴纸：导出面板按当前 SVG 导出参数请求 /api/jobs/{job_id}/custom.svg，读取返回的 SVG 文本后写入贴纸库
贴纸删除只删除本地贴纸库记录，不会删除已经导出的总图文件

画布模型

画布文档保存在 localStorage 的 wordcloud-canvas-document。

当前模型字段：

width：画布宽度，默认 1600
height：画布高度，默认 1000
background：画布背景色，默认 #ffffff，支持透明 #00000000
elements：画布元素数组
layers：图层数组（可选，支持可见性、锁定、文件夹分组）
layerFolders：图层文件夹数组（可选）

当前元素类型：

sticker：引用贴纸库中的 SVG 或图片（assetId）
text：普通文字（内容、颜色、字号、字体、字重、位置、尺寸、旋转、透明度）
rect：矩形（填充、描边、描边宽度、位置、尺寸、旋转、透明度）
ellipse：椭圆（同上）
line：线条（描边、描边宽度、位置、尺寸、旋转、透明度）

编辑行为

点击贴纸库中的贴纸会把该贴纸插入画布中央区域
画布元素支持：
- 拖拽移动：鼠标/触摸拖拽
- 大小调整：选中后通过右下角手柄调整
- 精确编辑：右侧面板可修改位置、尺寸、旋转、透明度、元素特有属性
- 层级调整：上移、下移
- 删除：删除元素
右侧面板支持修改画布宽高、背景色
支持导出总图 SVG、AI（受支持元素）、清空画布
图层管理：支持图层可见性、锁定、文件夹分组
吸附对齐：元素拖拽时自动吸附到附近元素边缘
缩放：编辑视图可缩放（不影响导出尺寸）

SVG 导出

"导出总图 SVG"由前端序列化当前画布模型完成：

导出文件名：canvas-design.svg
背景输出为一个覆盖全画布的 <rect>（透明背景时 fill="none"）
贴纸输出为 <image>，SVG 贴纸会以内联 data:image/svg+xml 的形式嵌入
文字输出为 <text>
基础形状输出为原生 SVG 的 <rect>、<ellipse>、<line>
元素的位移和旋转写入 SVG transform，透明度写入 opacity

AI 导出

"导出总图 AI"先按同一画布模型生成 SVG，再提交到后端 /api/exports/ai，由 Docker Compose 内部的 ai-converter 转换为 Illustrator 5 兼容 .ai 文件。

支持路径、矩形、椭圆、圆、线条、纯色填充/描边和仿射变换。
图片贴纸、普通文字、透明度、SVG pattern/clipPath 等不保证保真的特性会明确失败，不会静默生成错误文件。
词云本体由后端输出为路径，适合作为 AI 导出主场景。

ZIP 导出

支持导出含以下内容的 ZIP 包：

canvas.svg：总图 SVG
sticker_{id}.svg：画布中所有独立 SVG 贴纸
manifest.json：元素元数据清单

同底图换名单（Replace Session）

画布页支持"替换词云名单"功能：

用户右键点击画布上的词云贴纸，选择"同底图换名单"
生成一个 WordcloudReplaceSession，包含：
- mask：原词云的底图遮罩（SVG/Image）
- target：目标元素信息（含宽度、高度、原遮罩元素 ID）
会话传递到词云生成页
词云生成页锁定底图，只替换名单内容，生成后自动按原尺寸贴回画布

当前边界

贴纸库和画布文档只保存在当前浏览器 localStorage，不会跨浏览器或跨设备同步
当前没有服务端素材库、项目文件格式或协作编辑接口（Projects 接口存在但服务层级较浅）
SVG 导入按用户信任文件处理；编辑器预览使用图片方式加载，不在页面中直接执行 SVG 内容
当前缩放只影响编辑视图，不改变导出尺寸
画布页总图支持 SVG 和受支持元素的 AI；没有实现 PNG/JPG 总图导出
线距分析结果显示在元素属性面板中，辅助激光加工参数设定

5.2 KiB Raw Blame History Unescape Escape