drawui-react 0.5.1 → 0.5.3

package/IMAGE_UPLOAD.md

@@ -0,0 +1,205 @@
+# 图片上传通道 · 集成指南
+
+> 📌 本文件是 `packages/core/IMAGE_UPLOAD.md` 的**同步副本**，随 `drawui-react` 一起发布，安装后不必跳转即可阅读。内容改动请以 core 那份为准，改完同步覆盖本文件。
+
+> 面向接入方（队友 / 业务方）。用于把 drawui 的「图片」按钮、粘贴、拖入文件统一接到自家上传服务（OSS / 自建后端 / 其它对象存储）。
+
+## 〇、这份文档在哪
+
+| 场景 | 路径 |
+| --- | --- |
+| 本仓库（真源，改动以此为准） | `packages/core/IMAGE_UPLOAD.md` |
+| 本仓库（同步副本） | `packages/react/IMAGE_UPLOAD.md` |
+| 安装依赖后 | `node_modules/drawui-core/IMAGE_UPLOAD.md` / `node_modules/drawui-react/IMAGE_UPLOAD.md` |
+| 在线 | <https://github.com/weishell/drawui/blob/main/packages/core/IMAGE_UPLOAD.md> |
+
+> 两个 npm 包均已把该文档列入 `files`，`README.md` 里的链接使用的是包内相对路径，安装后同样点得开。
+
+## 一、能力定位
+
+- **drawui 不内置任何对象存储 SDK**（不依赖 `ali-oss`、不预置 STS、不暴露任何 accessKey）。
+- SDK 只负责「选文件 → 拿到一个 URL → 在画布上渲染图片」，至于 URL 从哪儿来，完全由接入方决定。
+- 提供 **两条通道**，二选一或并存：
+
+| 通道 | 形式 | 适用 |
+| --- | --- | --- |
+| **A. `ImageUploadConfig`** | 配 `{ url, method, fieldName, headers, fields, responseUrlPath, timeoutMs, maxSizeBytes }` | 队友有自己的中转接口（前端 → 队友后端 → OSS） |
+| **B. `ImageUploader` 函数** | `(file: File) => Promise<string>`，函数内自行拿到 STS、签名直传 OSS | 前端直传 OSS / 自定义分片 / 自定义压缩 |
+
+**优先级 B > A**（函数优先于配置）。
+
+## 二、硬性约定（已默认开启，接入方不需要写）
+
+| 项 | 默认值 | 覆盖方式 |
+| --- | --- | --- |
+| **单张图片体积上限** | **30 MB**（超过直接拒绝，不会发出请求） | `ImageUploadConfig.maxSizeBytes` 自定义；写 `ImageUploader` 函数时需自己检查 |
+| **上传超时** | **60 秒**（之前是 30 秒，已调大） | `ImageUploadConfig.timeoutMs` 自定义 |
+| **失败重试** | 不重试，抛错后由调用方提示用户 | 自定义 `ImageUploader` 时自己实现 |
+| **请求并发控制** | 不限制，多文件并发上传 | 自定义 `ImageUploader` 时自己实现 |
+| **跨域** | 远端图默认 `crossOrigin='anonymous'` | `setImageCrossOrigin(null)` 关闭（注意会污染画布导致 PNG 导出失败） |
+
+> 体积超限走错误码 `image.tooLarge:`（前端 toast 已自动用 `image.tooLarge` 文案显示）。
+
+## 三、怎么调（按场景）
+
+### 场景 1：队友有自己的上传中转接口（最常见）
+
+```tsx
+import { CanvasBoard } from 'drawui-react'
+
+<CanvasBoard
+  imageUpload={{
+    url: 'https://api.team.com/upload',
+    method: 'POST',
+    fieldName: 'file',                 // 后端接收字段名
+    headers: { Authorization: `Bearer ${token}` },
+    // responseUrlPath: 'data.url',    // 响应 JSON 里 url 的路径；不填自动探测
+    // timeoutMs: 60000,               // 默认 60s
+    // maxSizeBytes: 30 * 1024 * 1024, // 默认 30 MB
+  }}
+/>
+```
+
+后端返回任一形式即可（自动探测顺序：`url` → `data.url` → `data` → `data.src` → `location` → `path` → `src` → `href` → `fileUrl` → `imageUrl` → `data.fileUrl`）：
+
+```jsonc
+// 推荐：直接给 url
+{ "url": "https://cdn.example.com/foo.png" }
+
+// 或者套了一层
+{ "code": 0, "data": { "url": "https://cdn.example.com/foo.png" } }
+```
+
+如果自动探测拿不准，**强烈建议显式配 `responseUrlPath: 'data.url'`**，避免 JSON 里其它字段（如 `userUrl`）被误识别。
+
+### 场景 2：前端直传 OSS（拿 STS 后 PutObject）
+
+**必须用 `ImageUploader` 函数，不要用 `ImageUploadConfig.headers` 试图塞 OSS 签名 —— 浏览器会先发 CORS 预检，而 OSS 默认不回 `x-oss-*` 自定义头的预检响应。**
+
+```tsx
+import OSS from 'ali-oss'
+import { CanvasBoard } from 'drawui-react'
+
+async function uploadToOSS(file: File): Promise<string> {
+  // 1. 跟你们后端拿 STS 临时凭证
+  const sts = await fetch('/api/oss/sts', { credentials: 'include' }).then(r => r.json())
+  //   期望字段：accessKeyId / accessKeySecret / securityToken / region / bucket / host / dir
+  const { accessKeyId, accessKeySecret, securityToken, region, bucket, host, dir } = sts
+
+  // 2. 客户端压缩一下，避免撞 60s 超时
+  const compressed = await compressIfNeeded(file, 30 * 1024 * 1024)
+
+  // 3. 直传 OSS
+  const oss = new OSS({
+    accessKeyId, accessKeySecret, stsToken: securityToken,
+    bucket, region, secure: true,
+  })
+  const filename = `${dir}/${Date.now()}_${compressed.name}`
+  await oss.put(filename, compressed, {
+    headers: { 'x-oss-object-acl': 'public-read' },
+  })
+
+  // 4. 必须返回公网可访问的 URL
+  return `${host}/${filename}`
+}
+
+<CanvasBoard imageUpload={uploadToOSS} />
+```
+
+> STS 接口必须保证返回的 `host` + 文件路径能在浏览器里直接 GET 到，并且对应 OSS 桶回 **正确的 CORS 头**。
+
+### 场景 3：暂未接入上传服务
+
+不传 `imageUpload` 也能用 —— SDK 会走 `URL.createObjectURL(file)` 本地兜底，图片以 **`temporary: true`** 标记。**但**：刷新页面图片即丢失。SDK 会自动弹「已插入临时图片（未配置上传接口，刷新后会丢失）」toast 提示用户。
+
+接入方在保存数据前可调用 `editor.hasTemporaryImages()` 检测并提示用户：
+
+```ts
+if (editor.hasTemporaryImages()) {
+  // 让用户先上传完再保存，或者保存时提醒刷新会丢
+}
+```
+
+## 四、调用链速览（接入方排查用）
+
+```
+Toolbar「图片」按钮 ─► onInsertImage(files)
+                          │
+                          ▼
+CanvasBoard (imageUpload?: ImageUploadOption)
+                          │
+                          ▼
+editor.insertImageFiles(files, at)
+                          │
+                          ▼
+Editor.insertImageFile(file, at)        ← packages/core/src/editor/Editor.ts
+                          │
+                ┌─────────┴─────────┐
+   配了 imageUploadOption       没配（默认）
+                │                     │
+                ▼                     ▼
+   runUploader(option, file)    URL.createObjectURL(file)
+   ─► 拿远端 URL                ─► blob:xxx（temporary:true）
+                │                     │
+                └─────────┬───────────┘
+                          ▼
+               loadImage(src) → ImageShape
+                          ▼
+                  src 入画布（不是 base64）
+```
+
+三条触发路径都走同一通道：
+
+| 入口 | 代码位置（按符号定位，行号会漂移） |
+| --- | --- |
+| 工具栏「图片」按钮 | `Toolbar.tsx` → `handleImagePicked`（隐藏 `<input type="file">` 的 `onChange`） |
+| 拖拽图片到画布 | `CanvasBoard.tsx` → `onDrop` → `editor.insertImageFiles(dropped, at)` |
+| 粘贴图片 | `CanvasBoard.tsx` → 粘贴处理 → `editor.insertImageFiles(files)`（失败经 `imageError` UI 通道回流） |
+
+## 五、接 OSS 时最容易踩的 10 个坑
+
+| # | 现象 | 根因 / 处理 |
+| --- | --- | --- |
+| 1 | 上传完图裂了 | OSS 桶没回 CORS 头。检查桶的「跨域设置」：允许源 `*`（或具体域名）、允许方法 `GET/HEAD/PUT/POST`、允许头 `*` |
+| 2 | `ImageUploadConfig.headers` 加 `Authorization` 后浏览器报错 | 浏览器会先发 CORS 预检，队友接口没回 `Access-Control-Allow-Headers`。要么后端放开，要么改走 `ImageUploader` 函数自己 fetch |
+| 3 | 60 秒超时 | 大图直传。压缩后再上传，或调大 `timeoutMs: 180000` |
+| 4 | 一次选 20 张图全失败 | 并发数太高被 OSS 限流。自定义 `ImageUploader` 内做并发限流（如 p-limit） |
+| 5 | 上传报错后用户重试不了 | SDK 不内置重试，在 `ImageUploader` 内自己加 |
+| 6 | 刷新后图全没了 | 拿到的是 `blob:` 本地地址或返回的 URL 不公网可访问。`editor.hasTemporaryImages()` 帮你在保存前检测 |
+| 7 | 客户端工具菜单「另存为图片」导出 PNG 失败 | OSS 没配 CORS 头，canvas 被污染。用 `setImageCrossOrigin(null)` 可暂解，但会失去 PNG/SVG 导出能力 |
+| 8 | 自动探测 URL 拿错了字段 | 返回 JSON 里恰好有非图片含义的 `url` 字段。**显式配 `responseUrlPath`** |
+| 9 | 拖拽多个文件只插入一张 | `CanvasBoard.tsx` 的 `onDrop` 已过滤非图片。检查 `file.type` 是否正确 |
+| 10 | 大于 30 MB 静默失败 | 不静默，会抛 `image.tooLarge:`，前端 toast 用 `image.tooLarge` 文案显式提示用户。要调大用 `maxSizeBytes` |
+
+## 六、自检 checklist（上线前过一遍）
+
+- [ ] OSS 桶已配 CORS
+- [ ] STS 接口走自家鉴权（不依赖前端 cookie）
+- [ ] 返回的图片 URL 公网可访问，浏览器 GET 200
+- [ ] 上传 > 30 MB 的图被拒绝（toast 提示用户）
+- [ ] 上传 > 60s 的请求会超时（确认是自己调的 60s 还是后端更快超时）
+- [ ] 上传完 → 刷新页面 → 图片还在（验证不是 `blob:`）
+- [ ] 保存文档前调用 `editor.hasTemporaryImages()` 提示用户
+- [ ] `image.tooLarge` 文案在你们支持的语言里都翻译到位（默认带 7 种语言，扩展见 `packages/core/src/i18n.ts`）
+
+## 七、相关导出（来自 `drawui-core`）
+
+```ts
+import {
+  Editor,
+  DEFAULT_IMAGE_MAX_SIZE_BYTES, // 30 * 1024 * 1024
+  type ImageUploadOption,        // 配置 | 函数，二选一
+  type ImageUploadConfig,        // url / method / headers / responseUrlPath / timeoutMs / maxSizeBytes ...
+  type ImageUploader,            // (file: File) => Promise<string>
+  isUploaderFunction,
+  parseUploadResponse,           // 解析后端响应文本 → URL（业务方自实现上传函数时可复用）
+} from 'drawui-core'
+```
+
+核心文件：
+
+- `packages/core/src/imageUpload.ts`：上传通道定义 + fetch 实现
+- `packages/core/src/editor/Editor.ts`：`insertImageFile` / `insertImageFiles`（带 30 MB 闸门）
+- `packages/core/src/imageStore.ts`：图片加载、缓存、跨域处理
+- `packages/react/src/components/CanvasBoard.tsx`：`imageUpload` prop + toast 文案
+- `packages/core/src/i18n.ts`：多语言文案（含新增的 `image.tooLarge`）

package/README.md

@@ -4,7 +4,7 @@
 
 基于 [drawui-core](https://www.npmjs.com/package/drawui-core) 的 React 封装，提供开箱即用的画布组件。
 
-> 🛠 **图片上传对接**（接 OSS / 自建后端）请看 [`../core/IMAGE_UPLOAD.md`](../core/IMAGE_UPLOAD.md)：含 `imageUpload` prop 的两种通道（`ImageUploadConfig` 与 `ImageUploader` 函数）、30 MB 体积上限、60 s 超时、OSS CORS 与 STS 直传示例。
+> 🛠 **图片上传对接**（接 OSS / 自建后端）：完整指南随包发布，安装后直接打开 `node_modules/drawui-react/IMAGE_UPLOAD.md` 查看。含 `imageUpload` prop 的两种通道（`ImageUploadConfig` 与 `ImageUploader` 函数）、30 MB 体积上限、60 s 超时、OSS CORS 与 STS 直传示例。
 
 ## 安装
 
@@ -61,6 +61,25 @@ export function App() {
 
 ## 更新日志
 
+### v0.5.3
+
+> 主题：**继承 core 的连线避让 / 线段手柄 / 橡皮擦渐隐**（依赖 `drawui-core@0.5.3`）
+
+- 🧭 **连线不再压线**：绕行路由随 core 生效 —— 从右边缘出线、目标在左边时，末段不再横穿目标图形。
+- 🎚️ **线段手柄收敛**：只有折线与直角折线会显示可拖动的线段手柄，直线与曲线移除（绘制与命中都关掉）。
+- 🫥 **橡皮擦渐隐**：擦除时图形 200ms 内淡出再消失，React 层无需任何配置；`CanvasBoard` 未改动。
+- 📄 `IMAGE_UPLOAD.md` 入口说明改为「随包发布，安装后在 `node_modules/drawui-react/` 下查看」。
+
+### v0.5.2
+
+> 主题：**思维导图升降层级入口 + 拖拽换层级提示**（依赖 `drawui-core@0.5.2`）
+
+- ⬆️ **悬浮样式条新增「层级」入口**：选中单个思维导图且它存在活动节点时，底部悬浮样式条（原本 4 个图标：填充 / 边框 / 文字 / 高亮）多出第 5 个「层级」按钮，点开含「升一级 / 升两级」，按当前节点深度自动置灰。**单击任意节点即可触发**（单击本就会把该节点设为活动节点，无需先双击）。
+- 🖱️ **拖拽换层级**：把节点拖到**另一个节点框内部** → 成为它的**子节点**；拖到**节点框外侧** → 成为它的**同方向兄弟**。
+- 🟦 **拖拽落点提示**：给「落点框将来挂靠的父节点」描虚线环，并画一条与真实父子连线同款的贝塞尔虚线接到落点占位框。
+- 🫥 **拖拽时隐藏全部浮动 chrome**：拖任意图形（移动 / 缩放 / 旋转…）时，**顶部工具栏 + 底部悬浮样式条 + 表格浮动条**同时隐藏，松手恢复（手型平移不隐藏）。
+- 📦 依赖的 `drawui-core` 同步升级到 `0.5.2`。
+
 ### v0.5.1
 
 > 主题：**思维导图四方向布局与交互重做**（依赖 `drawui-core@0.5.1`）
@@ -79,7 +98,7 @@ export function App() {
 - ⏱ **上传超时 30 s → 60 s**：默认 `timeoutMs` 从 30000 调整为 60000。
 - 🧰 **`imageUpload` 现在支持两种通道**：`ImageUploadConfig`（配 `{ url, method, headers, responseUrlPath, timeoutMs, maxSizeBytes }`）或 `ImageUploader` 函数（`(file: File) => Promise<string>`），函数优先级高于配置。
 - 🌐 **多语言新增 `image.tooLarge` 文案**：7 种语言全部同步，体积超限时 toast 用对应语言提示用户。
-- 📄 **图片上传对接指南**：[`../core/IMAGE_UPLOAD.md`](../core/IMAGE_UPLOAD.md)。
+- 📄 **图片上传对接指南**：见 `node_modules/drawui-react/IMAGE_UPLOAD.md`（随包发布）。
 
 ### v0.4.2
 
@@ -247,6 +266,25 @@ export function App() {
 
 ## Changelog
 
+### v0.5.3
+
+> Theme: **inherits core's connector detour, narrower segment handles and eraser fade-out** (depends on `drawui-core@0.5.3`)
+
+- 🧭 **Connectors no longer overlap shapes**: detour routing from core — exiting the right edge towards a target on the left no longer runs the last leg through the target.
+- 🎚️ **Segment handles narrowed**: only polyline and orthogonal connectors show draggable segment handles; straight and curve connectors drop them (both drawing and hit-testing).
+- 🫥 **Eraser fade-out**: shapes fade over 200 ms before being removed. No React API changes; `CanvasBoard` is untouched.
+- 📄 The `IMAGE_UPLOAD.md` entry now points at `node_modules/drawui-react/` instead of a relative link.
+
+### v0.5.2
+
+> Theme: **Mind map level controls + drag-to-re-parent hints** (depends on `drawui-core@0.5.2`)
+
+- ⬆️ **New "Level" entry in the floating style bar**: when a single mind map is selected and has an active node, the floating bar (previously four icons: fill / stroke / text / highlight) gains a fifth **Level** button. It opens a popover with **Promote** / **Promote 2**, auto-disabled by the node's depth. **A single click on any node is enough** — clicking already makes that node active, no double-click required.
+- 🖱️ **Drag to re-parent**: drop a node **inside** another node's box → it becomes that node's **child**; drop **outside** the box → it becomes that node's **same-direction sibling**.
+- 🟦 **Drop hints**: the node the placeholder will hang under is outlined with a dashed ring, with a dashed bézier (same style as real parent-child links) connecting it to the placeholder box.
+- 🫥 **All floating chrome hides while dragging**: dragging any shape (move / resize / rotate…) hides the **top toolbar, the floating style bar and the table toolbar** at once, restoring them on release (hand panning excluded).
+- 📦 Bundled `drawui-core` is bumped to `0.5.2`.
+
 ### v0.5.1
 
 > Theme: **Mind map four-direction layout & interaction rework** (depends on `drawui-core@0.5.1`)
@@ -265,7 +303,7 @@ export function App() {
 - ⏱ **Upload timeout 30 s → 60 s**: default `timeoutMs` bumped from 30000 to 60000.
 - 🧰 **`imageUpload` now accepts two channels**: `ImageUploadConfig` (with `{ url, method, headers, responseUrlPath, timeoutMs, maxSizeBytes }`) **or** an `ImageUploader` function (`(file: File) => Promise<string>`); the function takes priority over the config.
 - 🌐 **`image.tooLarge` localized**: added in all 7 supported languages so the size-cap toast always uses the user's language.
-- 📄 **Image upload integration guide**: see [`../core/IMAGE_UPLOAD.md`](../core/IMAGE_UPLOAD.md).
+- 📄 **Image upload integration guide**: see `node_modules/drawui-react/IMAGE_UPLOAD.md` (ships with the package).
 
 ### v0.4.2