kyle-editor 1.0.6 → 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,146 +1,246 @@
1
- # 分片上传(Chunk Upload)
1
+ # 上传(普通上传 / 分片上传)
2
2
 
3
- 编辑器的图片与视频统一走 `ChunkUploader`:**切片 → 并发上传 → 失败重试 → 合并**。它只依赖一个适配器对象,因此既能在**无后端**环境下演示,也能一行切换成真实服务。
3
+ 编辑器有两条上传链路,**各自独立配置、互不影响**:
4
+
5
+ | 链路 | 选项 | 过程 | 适用 |
6
+ |------|------|------|------|
7
+ | 普通上传 | `uploader` | 整个文件**一次请求** | 小文件(图片为主) |
8
+ | 分片上传 | `chunkUploader` | 切片 → 并发 → 重试,**只打一个接口** | 大文件(视频为主) |
9
+
10
+ 编辑器按 `upload.mode` 选路:
11
+
12
+ ```js
13
+ KEditor.create('#editor', {
14
+ uploader: '/api/upload', // 普通上传
15
+ chunkUploader: '/api/chunk-upload', // 分片上传
16
+ upload: {
17
+ mode: 'auto', // 'auto'(默认,按体积)| 'normal' | 'chunk'
18
+ chunkThreshold: 5 * 1024 * 1024, // auto:达到该体积才走分片
19
+ chunkSize: 1024 * 1024,
20
+ concurrency: 4,
21
+ retries: 2,
22
+ },
23
+ })
24
+ ```
4
25
 
5
26
  ```
6
- File
7
- └─ 切片(file.slice,默认 1MB/片)
8
- ├─ worker 1 → put(chunk 0) → put(chunk 3) … ← 并发数 concurrency
9
- ├─ worker 2 → put(chunk 1) …
10
- └─ worker 3 → put(chunk 2) …
11
- 每片失败自动重试 retries 次(退避 600ms * n)
12
- └─ 全部完成 → complete() → 返回最终 url → 替换编辑器内的占位块
27
+ File ──┬─ size < chunkThreshold ─→ SimpleUploader ─→ POST /api/upload (整包一次)
28
+ └─ size ≥ chunkThreshold ─→ ChunkUploader ─→ POST /api/chunk-upload (每片一次,并发)
13
29
  ```
14
30
 
15
- 进度、已传字节、分片数、实时速度会通过 `onProgress(ratio, info)` 回传给编辑区占位块。
31
+ | 想做的事 | 怎么写 |
32
+ |----------|--------|
33
+ | 小文件直传、大文件分片 | `uploader` + `chunkUploader` + `mode: 'auto'`(默认) |
34
+ | 全部走普通上传 | 只配 `uploader`(分片自动不启用) |
35
+ | 全部走分片上传 | 只配 `chunkUploader`(`mode` 自动变 `'chunk'`) |
36
+ | 调阈值 | `upload: { chunkThreshold: 2 * 1024 * 1024 }` |
37
+ | 开箱演示(无后端) | 两条都不配,默认两条都是 `'mock'` |
16
38
 
17
- ---
39
+ > 只配一条链路时,另一条**不会**被默认 `mock` 顶上 —— 否则真实后端只接了一半,另一半会静默产生 `blob:` 假地址。显式写 `upload` 时以你的配置为准。
40
+ >
41
+ > `mode: 'chunk'` 但没配 `chunkUploader`:控制台告警并回退为普通上传,不会静默失败。
18
42
 
19
- ## 1. 三种开箱适配器
43
+ 进度、已传字节、分片数、实时速度通过 `onProgress(ratio, info)` 回传到编辑区占位块(`info.mode` 为 `'normal'` / `'chunk'`)。
20
44
 
21
- ### 1.1 mock(默认,无需后端)
45
+ ---
46
+
47
+ ## 1. 普通上传(整个文件一次请求)
22
48
 
23
49
  ```js
24
- KEditor.create('#editor', { uploader: 'mock' })
50
+ KEditor.create('#editor', {
51
+ uploader: '/api/upload',
52
+ // 或:uploader: KEditor.httpAdapter({ url: '/api/upload' })
53
+ // 或:uploader: async (file) => (await myUpload(file)).url
54
+ })
55
+ ```
25
56
 
26
- // 可调参数
57
+ 请求是 `multipart/form-data`,响应里 `url` 非空即成功:
58
+
59
+ ```jsonc
60
+ // POST /api/upload Content-Type: multipart/form-data
61
+ // file 整个文件(字段名可用 fieldName 改)
62
+ // filename 原始文件名
63
+ // fileSize 总字节数
64
+
65
+ { "url": "https://cdn.example.com/a.png" } // ✅ 成功
66
+ { "code": 0, "data": { "url": "https://…/a.png" } } // ✅ 外层包装用 parse 解开
67
+ { "code": 0, "msg": "ok" } // ❌ 没有 url → 判定失败
68
+ ```
69
+
70
+ > 一次请求无法拿到逐字节进度,普通上传只上报「开始 / 结束」两个点。需要精细进度条就用分片上传。
71
+
72
+ ## 2. 分片上传(只配一个地址)
73
+
74
+ ```js
27
75
  KEditor.create('#editor', {
28
- uploader: KEditor.mockAdapter({
29
- speed: 8, // 模拟带宽 MB/s
30
- latency: 160, // 每片固定往返 ms
31
- failFirstChunk: true,// 演示「分片失败 → 自动重试」
32
- onEvent: (type, payload) => console.log(type, payload), // init/chunk/complete/instant/abort
33
- }),
34
- upload: { chunkSize: 256 * 1024 },
76
+ chunkUploader: '/api/chunk-upload', // 就这一个地址
77
+ upload: { mode: 'chunk', chunkSize: 5 * 1024 * 1024, concurrency: 4 },
35
78
  })
36
79
  ```
37
80
 
38
- 特点:分片真实切片与限速;完成后用 `URL.createObjectURL` 生成本地地址,可直接预览;同一文件重复上传命中「秒传」,不再重复切片。
81
+ **约定:只要接口响应里 `url` 不为空,就代表这个文件上传成功。** 每个分片都打到这一个地址,不需要 `init` / `complete`:
82
+
83
+ ```jsonc
84
+ // 请求:POST /api/chunk-upload multipart/form-data
85
+ // file 分片二进制(字段名可用 fieldName 改)
86
+ // identifier 文件指纹,同一文件恒定(用来定位、续传、秒传)
87
+ // index 分片下标,从 0 开始
88
+ // total 总片数
89
+ // filename / fileSize / chunkSize
90
+
91
+ // 响应:
92
+ { "url": "https://cdn.example.com/a.png" } // ✅ 非空 url = 成功
93
+ { "code": 0, "data": { "url": "https://…/a.png" } } // ✅ 外层包装用 parse 解开
94
+ { "code": 0, "msg": "ok" } // ⏳ 还没收齐,继续传
95
+ {}
96
+ ```
97
+
98
+ 拿到 `url` 后:编辑器立即用该地址替换占位块,**剩余未发出的分片不再上传**,上传进度直接置 100%。所以服务端两种实现都支持 ——
39
99
 
40
- ### 1.2 http(对接真实后端)
100
+ | 服务端实现 | 行为 |
101
+ |------------|------|
102
+ | 收齐全部分片后返回 url(常见) | 最后一片的响应带回 url,自然成功 |
103
+ | `identifier` 命中已知文件则秒传 | 第一个响应就带 url,后面分片直接不发 |
104
+
105
+ 全程都没有 `url` → 判定为失败,占位块转错误态并给出「重试 / 移除」,**不会静默当成功**。
106
+
107
+ 需要鉴权 / 自定义字段名 / 地址字段不叫 `url` 时(两条链路写法相同):
41
108
 
42
109
  ```js
43
110
  KEditor.create('#editor', {
44
- uploader: {
111
+ chunkUploader: {
45
112
  type: 'http',
46
- initUrl: '/api/upload/init',
47
- chunkUrl: '/api/upload/chunk',
48
- completeUrl: '/api/upload/complete',
49
- abortUrl: '/api/upload/abort', // 可选
50
- mode: 'raw', // 'raw' 裸 body(推荐)| 'formdata'
51
- headers: () => ({ Authorization: `Bearer ${getToken()}` }),
52
- withCredentials: true, // 需要 Cookie 时
53
- parse: (json) => json.data, // 统一响应外层包装
113
+ url: '/api/chunk-upload',
114
+ fieldName: 'chunk', // 默认 'file'
115
+ headers: () => ({ Authorization: `Bearer ${getToken()}` }), // 传函数每次请求实时取值
116
+ withCredentials: true,
117
+ parse: (json) => json.data, // 默认 json.data ?? json
118
+ pickUrl: (json) => json?.payload?.filePath || '', // 默认认 url / fileUrl / src
119
+ mode: 'formdata', // 默认 formdata
120
+ method: 'POST', // 默认:formdata → POST,raw → PUT
121
+ chunkUrlFor: ({ index }) => `/api/chunk-upload?part=${index}`, // 可选:动态分片地址
54
122
  },
55
- upload: { chunkSize: 5 * 1024 * 1024, concurrency: 4, retries: 2, fingerprint: 'strong' },
56
123
  })
57
124
  ```
58
125
 
59
- ### 1.3 simple(已有单次上传接口)
126
+ `mode` 的两种选择:
127
+
128
+ | mode | 请求形式 | 文件与上下文位置 |
129
+ |------|----------|------------------|
130
+ | `'formdata'`(默认) | `POST` multipart | 文件在 `fieldName` 字段,其余在表单字段 |
131
+ | `'raw'` | `PUT`/`POST` 裸 body | 文件是请求体,上下文(`identifier/index/total/filename`)在查询串 |
132
+
133
+ > **已移除三接口模式**:`httpAdapter` 不再接受 `initUrl` / `chunkUrl` / `completeUrl` / `abortUrl`,配了会直接报错并提示迁移。
134
+ > 需要 `init`(断点续传 / 秒传)/ `complete`(自行合并)这类自定义流程时,自己写适配器传给 `chunkUploader`,见第 5 节。
135
+
136
+ ## 3. mock(默认,无需后端)
60
137
 
61
138
  ```js
139
+ KEditor.create('#editor') // uploader / chunkUploader 默认都是 'mock'
140
+
141
+ // 可调参数
62
142
  KEditor.create('#editor', {
63
- uploader: KEditor.simpleAdapter(async (file, { signal, onProgress }) => {
64
- const form = new FormData()
65
- form.append('file', file)
66
- const res = await fetch('/api/upload', { method: 'POST', body: form, signal })
67
- onProgress?.(file.size, file.size)
68
- return (await res.json()).url // 也可直接返回字符串
143
+ chunkUploader: KEditor.mockAdapter({
144
+ speed: 8, // 模拟带宽 MB/s
145
+ latency: 160, // 每片固定往返 ms
146
+ failFirstChunk: true, // 演示「分片失败 → 自动重试」
147
+ onEvent: (type, payload) => console.log(type, payload), // init/chunk/complete/upload/instant/abort
69
148
  }),
149
+ upload: { mode: 'chunk', chunkSize: 256 * 1024 },
70
150
  })
71
151
  ```
72
152
 
73
- ---
74
-
75
- ## 2. 后端接口约定(推荐实现)
153
+ 特点:真实切片与限速;完成后用 `URL.createObjectURL` 生成本地地址,可直接预览;同一文件重复上传命中「秒传」,不再重复传输。普通上传链路同样可用(`adapter.upload()`,按体积分步上报进度)。
76
154
 
77
- ### `POST /api/upload/init`
155
+ ## 4. 后端接口约定
78
156
 
79
- 请求:
157
+ ### 4.1 普通上传
80
158
 
81
- ```json
82
- { "fileName": "a.mp4", "fileSize": 73400320, "fileType": "video/mp4",
83
- "lastModified": 1758000000000, "identifier": "…", "chunkSize": 1048576, "totalChunks": 71 }
84
159
  ```
85
-
86
- 响应(三选一):
87
-
88
- ```jsonc
89
- { "uploadId": "u_8f3c", "uploadedChunks": [0, 1, 2] } // 断点续传:告知已存在哪些片
90
- { "url": "https://cdn/x.png", "key": "…" } // 秒传:identifier 已存在,直接返回地址
91
- { "uploadId": "u_8f3c", "uploadedChunks": [] } // 全新任务
160
+ POST /api/upload Content-Type: multipart/form-data
92
161
  ```
93
162
 
94
- ### `PUT /api/upload/chunk?uploadId=u_8f3c&index=3&total=71&filename=a.mp4`
163
+ | 字段 | 说明 |
164
+ |------|------|
165
+ | `file` | 整个文件(`fieldName` 可改) |
166
+ | `filename` / `fileSize` | 原始文件名 / 总字节 |
95
167
 
96
- - `mode: 'raw'`:请求体是二进制分片,`Content-Type: application/octet-stream`,服务端按 `uploadId` 落盘为 `parts/{index}`,可用 `X-Chunk-Index` 头做幂等校验。
97
- - `mode: 'formdata'`:`multipart/form-data`,文件字段名 `fieldName`(默认 `file`),附带 `uploadId` / `index` / `total` / `filename`。
98
- - 响应:`{}` 即可;若返回 `{ "url": "…" }` 则该分片自带地址(适合对象存储分片直传)。
168
+ 服务端存好文件后响应 `{ "url": "…" }` 即可。
99
169
 
100
- ### `POST /api/upload/complete`
170
+ ### 4.2 分片上传(真的只需要这一个)
101
171
 
102
- ```json
103
- { "uploadId": "u_8f3c", "identifier": "…", "fileName": "a.mp4", "fileSize": 73400320,
104
- "fileType": "video/mp4", "chunkSize": 1048576, "totalChunks": 71 }
172
+ ```
173
+ POST /api/chunk-upload Content-Type: multipart/form-data
105
174
  ```
106
175
 
107
- 响应必须包含 `url`:
176
+ | 字段 | 说明 |
177
+ |------|------|
178
+ | `file` | 分片二进制(`fieldName` 可改) |
179
+ | `identifier` | 文件指纹,同一文件所有分片一致 —— 用它定位临时目录、做续传与秒传 |
180
+ | `index` / `total` | 当前分片下标(从 0 起)/ 总分片数 |
181
+ | `filename` / `fileSize` / `chunkSize` | 原始文件名 / 总字节 / 分片大小 |
108
182
 
109
- ```json
110
- { "url": "https://cdn/a.mp4", "key": "media/2026/09/a.mp4", "poster": "https://cdn/a.jpg", "duration": 63 }
111
- ```
183
+ 服务端要做的事:把分片落到 `tmp/{identifier}/{index}.part`;当 `{identifier}` 下已集齐 `total` 片(或 `identifier` 早已上传过)时,按 index 顺序合并 → 传对象存储 → 响应 `{ "url": "…" }`。其他情况响应 `{}` 即可(不要返回空 `url` 字段)。
112
184
 
113
- ### `POST /api/upload/abort`
185
+ > 要注意的是分片并发到达,`index === total - 1` 并不意味着"前面都到了",判定"集齐"要按磁盘上实际存在的分片数。
186
+ >
187
+ > 服务端只需要处理「一段二进制 + 几个上下文参数」,不需要 session、不需要 uploadId —— 分片并发到达也不会乱序落盘(文件名就是 index)。
114
188
 
115
- `{ "uploadId": "u_8f3c" }`,用于清理临时分片(用户取消时触发,失败会被忽略)。
189
+ ## 5. 自定义适配器
116
190
 
117
- > Node/Express 的极简实现思路:`init` 建目录 + 扫已存在分片返回 `uploadedChunks`;`chunk` 用 `raw body → fs.createWriteStream`;`complete` 按 index 顺序 `concat` 后交给对象存储。若直接用 OSS/S3 分片上传,把 `put` 换成「拿签名 URL → PUT」即可,`complete` 调用 `CompleteMultipartUpload`。
191
+ **普通上传**只需实现 `upload()`:
118
192
 
119
- ---
193
+ ```js
194
+ const normalAdapter = {
195
+ async upload(file, { signal, onProgress }) {
196
+ const form = new FormData()
197
+ form.append('file', file)
198
+ const res = await fetch('/api/upload', { method: 'POST', body: form, signal })
199
+ onProgress?.(file.size, file.size) // 可选:(已传字节, 总字节)
200
+ return (await res.json()).url // 返回字符串或 { url }
201
+ },
202
+ }
120
203
 
121
- ## 3. 自定义适配器
204
+ KEditor.create('#editor', { uploader: normalAdapter })
205
+ ```
122
206
 
123
- 只要实现 `put`,其余可选:
207
+ **分片上传**实现 `put()` 即可,`init` / `complete` 可选:
124
208
 
125
209
  ```js
126
- const adapter = {
210
+ const chunkAdapter = {
211
+ // 「响应里带 url 就是整份文件成功了」,拿到就收工、不再等 complete
212
+ // 不用这个字段时,最终地址必须由 complete() 返回
213
+ completeOnUrl: true,
214
+ async put({ uploadId, index, total, blob, file, meta, size, signal }) {
215
+ const res = await myClient.send(blob, { index, signal })
216
+ return { url: res?.url } // 配合 completeOnUrl 使用:非空即当成功
217
+ },
218
+ // 可选:秒传 / 断点续传
127
219
  async init(meta, { signal }) {
128
220
  // meta: {name,size,type,lastModified,fingerprint,chunkSize,totalChunks}
129
221
  return { uploadId: meta.fingerprint, uploadedChunks: [] } // 或 { url } 表示秒传
130
222
  },
131
- async put({ uploadId, index, total, blob, file, meta, size, signal }) {
132
- await myClient.send(blob, { index, signal })
133
- return {} // 或 { url }
134
- },
223
+ // 可选:自己合并并返回地址(没有 completeOnUrl 时必须实现)
135
224
  async complete({ uploadId, meta, total, uploaded, chunkResults, file }) {
136
- return { url: 'https://…' } // 必须返回 url
225
+ return { url: 'https://…' }
137
226
  },
138
- async abort({ uploadId, meta, error }) {},
139
227
  }
140
228
 
141
- KEditor.create('#editor', { uploader: adapter, upload: { chunkSize: 2 * 1024 * 1024, concurrency: 2 } })
229
+ KEditor.create('#editor', {
230
+ chunkUploader: chunkAdapter,
231
+ upload: { mode: 'chunk', chunkSize: 2 * 1024 * 1024, concurrency: 2 },
232
+ })
142
233
  ```
143
234
 
235
+ `completeOnUrl` 也可以由调用方给定,优先级高于适配器:
236
+
237
+ ```js
238
+ new ChunkUploader(adapter, { completeOnUrl: true })
239
+ KEditor.create('#editor', { chunkUploader: adapter, upload: { completeOnUrl: true } })
240
+ ```
241
+
242
+ > 只实现了 `upload()` 的适配器传给 `chunkUploader` 也不会出错:分片链路会**自动退化为整包直传**(等价普通上传)。
243
+
144
244
  ### 断点续传 / 秒传的判定依据
145
245
 
146
246
  `meta.fingerprint` 默认由 `size + lastModified + 文件名` 组成(`upload.fingerprint: 'fast'`)。
@@ -150,37 +250,46 @@ KEditor.create('#editor', { uploader: adapter, upload: { chunkSize: 2 * 1024 * 1
150
250
  upload: { fingerprint: async (file) => `${file.name}-${file.size}` }
151
251
  ```
152
252
 
153
- 服务端把 `identifier → 最终 url` 建索引即可实现秒传;把已落盘分片 index 列表返回即可续传。
253
+ 服务端把 `identifier → 最终 url` 建索引即可实现秒传;把已落盘分片 index 列表返回即可续传(需适配器实现 `init`)。
154
254
 
155
255
  ---
156
256
 
157
- ## 4. 独立使用(不依赖编辑器)
257
+ ## 6. 独立使用(不依赖编辑器)
158
258
 
159
259
  ```js
160
- import { ChunkUploader, httpAdapter } from 'kyle-editor'
260
+ import { SimpleUploader, ChunkUploader, httpAdapter, createSimpleUploader, createChunkUploader } from 'kyle-editor'
161
261
 
162
- const uploader = new ChunkUploader(httpAdapter({ initUrl: '/api/upload/init', chunkUrl: '/api/upload/chunk', completeUrl: '/api/upload/complete' }), {
163
- chunkSize: 4 * 1024 * 1024,
164
- concurrency: 5,
165
- retries: 3,
166
- })
262
+ // 普通上传
263
+ const simple = createSimpleUploader('/api/upload')
264
+ const one = await simple.upload(file)
265
+
266
+ // 分片上传
267
+ const uploader = new ChunkUploader(httpAdapter({ url: '/api/chunk-upload' }), { chunkSize: 4 * 1024 * 1024, concurrency: 5, retries: 3 })
167
268
 
168
269
  const ctrl = new AbortController()
169
- const { url, chunks } = await uploader.upload(bigFile, {
270
+ const { url, chunks, mode } = await uploader.upload(bigFile, {
170
271
  signal: ctrl.signal,
171
272
  onProgress: (ratio, info) => bar.style.width = `${info.percent}%`,
172
273
  onChunk: ({ index, total }) => console.log(`${index + 1}/${total}`),
173
274
  })
174
275
  ```
175
276
 
176
- ## 5. 编辑器内的交互契约
277
+ 选路器也可以单独用(`editor.uploader` 就是它):
278
+
279
+ ```js
280
+ const pipeline = new UploadPipeline(simple, uploader, { mode: 'auto', chunkThreshold: 5 * 1024 * 1024 })
281
+ pipeline.pick(file) // 'normal' | 'chunk'
282
+ await pipeline.upload(file, { onProgress })
283
+ ```
284
+
285
+ ## 7. 编辑器内的交互契约
177
286
 
178
287
  | 场景 | 行为 |
179
288
  |------|------|
180
289
  | 点击工具栏图片/视频 | 选择文件 → 就地插入占位块(含进度条、分片数、速度、取消按钮) |
181
290
  | 拖拽文件到编辑区 | 光标定位到落点后插入占位块 |
182
291
  | 粘贴截图 | 自动生成文件名并上传 |
183
- | 上传成功 | 占位块替换为 `<img>` / `<video>`,图片支持双击放大、气泡工具条调整对齐/宽度/圆角/替换/删除、**拖拽右下角把手实时缩放** |
292
+ | 上传成功 | 占位块替换为 `<img>` / `<video>`,地址取接口返回的 `url`;图片支持双击放大、气泡工具条调整对齐/宽度/圆角/替换/删除、**拖拽右下角把手实时缩放** |
184
293
  | 分片失败 | 自动重试 `retries` 次;仍失败则占位块转为错误态,提供「重试 / 移除」 |
185
- | 取消 | `AbortController` 中止全部在传分片并调用 `abort()`,占位块移除 |
294
+ | 取消 | `AbortController` 中止全部在传请求(分片链路若有 `abort()` 也会调用),占位块移除 |
186
295
  | 同一文件重复插入 | 适配器 `init` 返回 `url` 时直接秒传,不再切片 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kyle-editor",
3
- "version": "1.0.6",
3
+ "version": "1.0.8",
4
4
  "description": "轻量、美观的微信公众号风格富文本编辑器(纯前端,支持图片/视频分片上传、HTML 源码模式),可通过 <script> 引入或作为 Vue 3 组件安装。",
5
5
  "type": "module",
6
6
  "main": "./dist/keditor.cjs",
@@ -25,7 +25,6 @@
25
25
  "files": [
26
26
  "dist",
27
27
  "types",
28
- "imgs",
29
28
  "docs",
30
29
  "README.md",
31
30
  "LICENSE"
@@ -43,7 +42,7 @@
43
42
  "test:types": "node test/check-types.mjs",
44
43
  "test:package": "node test/check-package.mjs",
45
44
  "test:install": "node test/check-install.mjs",
46
- "test:visual": "node test/shoot.mjs rich,uploading,bubble,resize,align,source,preview,color,heading,media,link,custom,customload,customerr,posbtn,wide,widefix,scroll,scroll2,http://127.0.0.1:5178/demo/vue.html",
45
+ "test:visual": "node test/shoot.mjs rich,uploading,bubble,resize,align,source,preview,color,heading,media,link,code,codepanel,markdown,markdownpanel,custom,customload,customerr,posbtn,wide,widefix,scroll,scroll2,http://127.0.0.1:5178/demo/vue.html",
47
46
  "clean": "rm -rf dist",
48
47
  "verify": "npm run build && npm test && npm run test:min && npm run test:pages && npm run test:types && npm run test:package",
49
48
  "pack:check": "npm run build && npm run test:package && npm pack --dry-run",