drawui-react 0.5.0 → 0.5.2

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`）