kyle-editor 1.0.5 → 1.0.6
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.
- package/README.md +3 -0
- package/dist/keditor.cjs +1 -1
- package/dist/keditor.es.js +1 -1
- package/dist/keditor.umd.js +1 -1
- package/dist/keditor.umd.min.js +1 -1
- package/docs/api.md +365 -0
- package/docs/index.md +8 -0
- package/docs/integration.md +347 -0
- package/docs/upload-adapter.md +186 -0
- package/package.json +2 -1
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
# 集成指南
|
|
2
|
+
|
|
3
|
+
KEditor 是**纯前端**编辑器,不依赖任何后端接口。三种集成方式任选其一。
|
|
4
|
+
|
|
5
|
+
| 方式 | 适用场景 | 引入文件 |
|
|
6
|
+
|------|----------|----------|
|
|
7
|
+
| Script(UMD) | 静态页、jQuery/Vue2 老项目、快速原型 | `dist/keditor.umd.min.js`(调试可用未压缩的 `keditor.umd.js`) |
|
|
8
|
+
| ESM / 打包器 | Vite、Webpack、Rollup、Next/Nuxt(客户端组件) | `import { KEditor } from 'kyle-editor'` |
|
|
9
|
+
| Vue 3 组件 | Vue 3 项目,`v-model` 双向绑定 | `import KEditorVue from 'kyle-editor/vue'` |
|
|
10
|
+
|
|
11
|
+
样式随 JS 自动注入(`<style data-keditor-style>`),**无需单独引入 CSS**。
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 1. Script 引入(零构建)
|
|
16
|
+
|
|
17
|
+
```html
|
|
18
|
+
<!DOCTYPE html>
|
|
19
|
+
<html>
|
|
20
|
+
<head>
|
|
21
|
+
<meta charset="utf-8" />
|
|
22
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
23
|
+
</head>
|
|
24
|
+
<body>
|
|
25
|
+
<div id="editor"></div>
|
|
26
|
+
|
|
27
|
+
<!-- 线上用压缩版(139 KB / gzip 43 KB);断点调试换成 dist/keditor.umd.js 即可,API 完全一致 -->
|
|
28
|
+
<script src="dist/keditor.umd.min.js"></script>
|
|
29
|
+
<script>
|
|
30
|
+
const editor = KEditor.create('#editor', {
|
|
31
|
+
placeholder: '开始撰写内容…',
|
|
32
|
+
height: 460,
|
|
33
|
+
})
|
|
34
|
+
|
|
35
|
+
editor.on('change', ({ html }) => console.log(html))
|
|
36
|
+
document.querySelector('#save').onclick = () => submit(editor.getHTML())
|
|
37
|
+
</script>
|
|
38
|
+
</body></html>
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
UMD 全局对象 `KEditor` 上的可用成员:
|
|
42
|
+
|
|
43
|
+
```js
|
|
44
|
+
KEditor.create(target, options) // 返回实例(推荐)
|
|
45
|
+
KEditor.mount(...) // create 的别名
|
|
46
|
+
KEditor.KEditor // 类本体,new KEditor(target, options)
|
|
47
|
+
KEditor.mockAdapter(options) // 无后端演示适配器
|
|
48
|
+
KEditor.httpAdapter(config) // 真实后端适配器
|
|
49
|
+
KEditor.simpleAdapter(fn) // 单次直传接口包装
|
|
50
|
+
KEditor.sanitizeHtml(html) // 独立使用的 HTML 净化
|
|
51
|
+
KEditor.formatHtml(html) // 独立使用的 HTML 格式化
|
|
52
|
+
KEditor.version
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
> 本地预览:仓库根目录已内置静态服务脚本 `npm run dev`(127.0.0.1:5178),打开 `demo/script.html`。
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 2. ESM / 打包工具引入
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm i kyle-editor # 或将本仓库 dist/ 拷贝进项目
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
import { KEditor, create, mockAdapter } from 'kyle-editor'
|
|
67
|
+
|
|
68
|
+
const editor = create('#editor', {
|
|
69
|
+
value: '<p>hello</p>',
|
|
70
|
+
uploader: mockAdapter({ speed: 8 }), // 演示:不请求后端
|
|
71
|
+
upload: { chunkSize: 256 * 1024, concurrency: 3 },
|
|
72
|
+
})
|
|
73
|
+
|
|
74
|
+
// 组件卸载时务必销毁
|
|
75
|
+
window.addEventListener('beforeunload', () => editor.destroy())
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
按需引入(tree-shaking 友好):
|
|
79
|
+
|
|
80
|
+
```js
|
|
81
|
+
import { formatHtml } from 'kyle-editor' // 源码格式化
|
|
82
|
+
import { sanitizeHtml } from 'kyle-editor' // 粘贴/回填净化
|
|
83
|
+
import { ChunkUploader, httpAdapter } from 'kyle-editor' // 只用上传能力
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### 在 React 中使用
|
|
87
|
+
|
|
88
|
+
```jsx
|
|
89
|
+
import { useEffect, useRef } from 'react'
|
|
90
|
+
import { KEditor } from 'kyle-editor'
|
|
91
|
+
|
|
92
|
+
export function Editor({ value, onChange }) {
|
|
93
|
+
const host = useRef(null)
|
|
94
|
+
const editor = useRef(null)
|
|
95
|
+
|
|
96
|
+
useEffect(() => {
|
|
97
|
+
editor.current = new KEditor(host.current, { value, onChange: (html) => onChange(html) })
|
|
98
|
+
return () => editor.current?.destroy()
|
|
99
|
+
}, [])
|
|
100
|
+
|
|
101
|
+
useEffect(() => {
|
|
102
|
+
if (editor.current && value !== editor.current.getHTML()) editor.current.setContent(value)
|
|
103
|
+
}, [value])
|
|
104
|
+
|
|
105
|
+
return <div ref={host} />
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## 3. Vue 3 安装集成
|
|
112
|
+
|
|
113
|
+
### 3.1 全局注册(推荐)
|
|
114
|
+
|
|
115
|
+
```js
|
|
116
|
+
// main.js
|
|
117
|
+
import { createApp } from 'vue'
|
|
118
|
+
import App from './App.vue'
|
|
119
|
+
import KEditorVue from 'kyle-editor/vue' // 默认导出是组件(自带 install)
|
|
120
|
+
|
|
121
|
+
createApp(App).use(KEditorVue).mount('#app')
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
```vue
|
|
125
|
+
<template>
|
|
126
|
+
<k-editor v-model="form.content" :options="editorOptions" :disabled="readonly" @upload="onUpload" @ready="onReady" />
|
|
127
|
+
<button @click="submit">保存</button>
|
|
128
|
+
</template>
|
|
129
|
+
|
|
130
|
+
<script setup>
|
|
131
|
+
import { ref } from 'vue'
|
|
132
|
+
|
|
133
|
+
const form = ref({ content: '<p>初始内容</p>' })
|
|
134
|
+
const readonly = ref(false)
|
|
135
|
+
const editorOptions = {
|
|
136
|
+
placeholder: '支持拖拽 / 粘贴上传…',
|
|
137
|
+
height: 420,
|
|
138
|
+
uploader: { type: 'http', initUrl: '/api/upload/init', chunkUrl: '/api/upload/chunk', completeUrl: '/api/upload/complete' },
|
|
139
|
+
upload: { chunkSize: 1024 * 1024, concurrency: 3, retries: 2 },
|
|
140
|
+
}
|
|
141
|
+
const onUpload = (payload) => console.log(payload.stage, payload.percent)
|
|
142
|
+
const onReady = (editor) => console.log('编辑器实例', editor)
|
|
143
|
+
</script>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
也可指定注册名:
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
app.use(KEditorVue, { name: 'RichEditor' }) // <rich-editor />
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### 3.2 局部引入组件
|
|
153
|
+
|
|
154
|
+
```vue
|
|
155
|
+
<script setup>
|
|
156
|
+
import { KEditorVue } from 'kyle-editor/vue'
|
|
157
|
+
</script>
|
|
158
|
+
|
|
159
|
+
<template>
|
|
160
|
+
<KEditorVue v-model="html" />
|
|
161
|
+
</template>
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
> 默认导出与具名导出 `KEditorVue` 是同一个组件(默认导出额外带了 `install`),
|
|
165
|
+
> 所以 `import KEditorVue from 'kyle-editor/vue'` 后直接 `<KEditorVue v-model="html" />` 也能正常渲染。
|
|
166
|
+
> 若只想全局注册,用 `import { KEditorPlugin } from 'kyle-editor/vue'` 语义更清楚。
|
|
167
|
+
|
|
168
|
+
### 3.3 组合式 API
|
|
169
|
+
|
|
170
|
+
```js
|
|
171
|
+
import { useKEditor } from 'kyle-editor/vue'
|
|
172
|
+
|
|
173
|
+
const { host, editor } = useKEditor({ height: 400 })
|
|
174
|
+
// <div ref="host"></div>,editor.value 为 KEditor 实例
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### 3.4 组件 Props / Emits
|
|
178
|
+
|
|
179
|
+
| Prop | 类型 | 说明 |
|
|
180
|
+
|------|------|------|
|
|
181
|
+
| `modelValue` | `string` | HTML 字符串,`v-model` 绑定;外部变更会同步进编辑器 |
|
|
182
|
+
| `options` | `object` | 与 `new KEditor(el, options)` 完全一致的配置 |
|
|
183
|
+
| `disabled` | `boolean` | 只读模式 |
|
|
184
|
+
| `height` | `number` | 覆盖 `options.height` |
|
|
185
|
+
|
|
186
|
+
| Emit | 载荷 | 说明 |
|
|
187
|
+
|------|------|------|
|
|
188
|
+
| `update:modelValue` | `html: string` | 内容变化(自动去内部属性) |
|
|
189
|
+
| `change` | `{html, text, counts}` | 内容变化(防抖后) |
|
|
190
|
+
| `ready` | `editor` | 实例创建完成 |
|
|
191
|
+
| `upload` | `{state, kind, name, size, progress, result, error, node}` | 上传生命周期,`state` 为 `start/progress/success/error/cancel` |
|
|
192
|
+
| `error` | `{type, error, message}` | 内部异常(上传失败、净化失败、源码解析失败) |
|
|
193
|
+
| `save` | `{html, text, counts}` | 编辑器内按下 ⌘/Ctrl+S |
|
|
194
|
+
| `focus` / `blur` | — | 焦点变化 |
|
|
195
|
+
|
|
196
|
+
通过 `ref` 拿到原生实例做进阶操作:
|
|
197
|
+
|
|
198
|
+
```vue
|
|
199
|
+
<k-editor ref="editorRef" v-model="html" />
|
|
200
|
+
<script setup>
|
|
201
|
+
const editorRef = ref()
|
|
202
|
+
editorRef.value.editor.setContent('<p>来自父组件</p>') // KEditor 实例
|
|
203
|
+
editorRef.value.getHTML()
|
|
204
|
+
</script>
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### 3.5 SSR 框架(Nuxt 3 / Next.js)
|
|
208
|
+
|
|
209
|
+
> ❗ 编辑器依赖 `document`、`DOMParser`、`contenteditable`,**只能在浏览器运行**。在服务端渲染阶段引入会报 `document is not defined` / `DOMParser is not defined`,必须做成客户端专属。
|
|
210
|
+
|
|
211
|
+
**Nuxt 3**:插件文件名带 `.client` 后缀即只在客户端加载
|
|
212
|
+
|
|
213
|
+
```ts
|
|
214
|
+
// plugins/keditor.client.ts
|
|
215
|
+
import KEditorVue from 'kyle-editor/vue'
|
|
216
|
+
export default defineNuxtPlugin((nuxtApp) => nuxtApp.vueApp.use(KEditorVue))
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
```vue
|
|
220
|
+
<template>
|
|
221
|
+
<ClientOnly>
|
|
222
|
+
<k-editor v-model="html" />
|
|
223
|
+
</ClientOnly>
|
|
224
|
+
</template>
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
**Next.js(App Router)**:组件顶部标 `'use client'`,并用 `next/dynamic` 关闭 SSR
|
|
228
|
+
|
|
229
|
+
```tsx
|
|
230
|
+
// app/editor-page.tsx
|
|
231
|
+
'use client'
|
|
232
|
+
import dynamic from 'next/dynamic'
|
|
233
|
+
|
|
234
|
+
const KEditor = dynamic(() => import('kyle-editor/vue').then((m) => m.KEditorVue), { ssr: false })
|
|
235
|
+
|
|
236
|
+
export default function Page() {
|
|
237
|
+
return <KEditor modelValue="" />
|
|
238
|
+
}
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
若需在服务端做 HTML 消毒(例如入库前过滤),不要直接用本包的 `sanitizeHtml`(依赖 DOM),请改用 `isomorphic-dompurify` 等同构方案;`escapeHtml` / `isSafeUrl` 是纯函数,Node 下可直接用。
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
### 3.6 TypeScript
|
|
246
|
+
|
|
247
|
+
包内自带声明(`package.json` 的 `types` 与 `exports.types`),无需安装 `@types`:
|
|
248
|
+
|
|
249
|
+
```ts
|
|
250
|
+
import KEditor, { type KEditorOptions, type UploadAdapter, type UploadResult } from 'kyle-editor'
|
|
251
|
+
|
|
252
|
+
const options: KEditorOptions = {
|
|
253
|
+
height: 480,
|
|
254
|
+
upload: { chunkSize: 2 * 1024 * 1024, concurrency: 4 },
|
|
255
|
+
uploader: myAdapter, // 满足 UploadAdapter 接口即可
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
const editor = KEditor.create('#editor', options)
|
|
259
|
+
const html: string = editor.getHTML()
|
|
260
|
+
const counts = editor.counts()
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Vue 3:`import KEditorVue from 'kyle-editor/vue'` 即带 props/emits 提示;`ref` 取出的实例上 `editor`、`getHTML()`、`focus()` 等均已声明。
|
|
264
|
+
|
|
265
|
+
UMD 方式(无构建)下若需提示,可 `/// <reference types="kyle-editor/types" />` 或直接使用 `KEditor.create`。
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## 4. 常见问题
|
|
270
|
+
|
|
271
|
+
**Q:不需要后端,怎么让图片真的显示出来?**
|
|
272
|
+
默认 `uploader: 'mock'` 会在浏览器内完成切片并生成 `blob:` 地址,页面内可直接预览。保存草稿时把 `getHTML()` 存下来即可;正式上线时换成 `httpAdapter` 就会得到 CDN 地址。
|
|
273
|
+
|
|
274
|
+
**Q:`blob:` 地址提交到服务器会失效,怎么办?**
|
|
275
|
+
在提交前调用 `editor.getHTML()`,把 `data-k-url` 为 `blob:` 的资源先上传(`beforeUpload` 里做映射),或直接配置真实 `uploader`。
|
|
276
|
+
|
|
277
|
+
**Q:如何精简工具栏?**
|
|
278
|
+
```js
|
|
279
|
+
KEditor.create('#editor', { toolbar: ['undo', 'redo', '|', 'bold', 'image', 'video', ':tail', 'source'] })
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
`'|'` 为分隔符,`':tail'` 之后的按钮靠右对齐(窄屏下吸附在右端不会被滚走),`toolbar: false` 隐藏工具栏。工具栏放不下时可左右滑动,并有滚动条、边缘渐隐、首次引导气泡等提示,详见 [api.md](api.md#工具栏项)。
|
|
283
|
+
|
|
284
|
+
可用项:`undo` `redo` `heading` `fontsize` `bold` `italic` `underline` `strike` `foreColor` `backColor` `alignLeft` `alignCenter` `alignRight` `alignJustify` `ul` `ol` `quote` `link` `image` `video` `table` `code` `hr` `clear` `source` `preview` `fullscreen`,详见 [api.md](api.md#工具栏项)。
|
|
285
|
+
|
|
286
|
+
> `preview` 已从默认工具栏(`KEditor.DEFAULT_TOOLBAR`)里移除,需要它在 `toolbar` 数组里写回,或直接调 `editor.openPreview()`。自定义按钮可用 `position` / `editor.moveButton()` 放到任意位置,包括 `:tail` 吸附区。
|
|
287
|
+
|
|
288
|
+
**Q:怎么往工具栏加自己的按钮(比如下拉选模板、选中后插链接)?**
|
|
289
|
+
用 `customButtons`,无需改源码。数据可以静态配置,也可以从接口读:
|
|
290
|
+
|
|
291
|
+
```js
|
|
292
|
+
KEditor.create('#editor', {
|
|
293
|
+
customButtons: [
|
|
294
|
+
{ name: 'column', text: '栏目', position: { after: 'link' }, searchable: true, url: '/api/columns', link: true, insert: 'link' },
|
|
295
|
+
{
|
|
296
|
+
name: 'tpl', text: '模板',
|
|
297
|
+
options: [{ value: 'opening', label: '开场白', desc: '问候 + 本期导读' }],
|
|
298
|
+
link: { url: 'https://mp.weixin.qq.com/s/tpl-{value}', text: '【{label}】' },
|
|
299
|
+
},
|
|
300
|
+
],
|
|
301
|
+
})
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
没传 `toolbar` 时会自动追加到工具栏末尾;传了就用名字定位:`toolbar: ['bold', '|', 'tpl']`。
|
|
305
|
+
位置也能直接写在按钮上,不用重抄整份工具栏:`position: 'start' | 'end' | 'tail' | 索引 | 按钮名 | { before | after }`;
|
|
306
|
+
运行时还能 `editor.moveButton(name, where)` 移任意按钮(包括内置的)。默认工具栏已不含「预览」,需要时自己写回 `toolbar`。
|
|
307
|
+
完整字段(缓存/强制刷新/分组/搜索/失败重试/`mode:'open'` 直接开窗/`onSelect` 接管)见 [api.md](api.md#自定义工具栏按钮)。
|
|
308
|
+
|
|
309
|
+
**Vue 里更常见的写法是在组件里自己请求接口,再灌给按钮:**
|
|
310
|
+
|
|
311
|
+
```vue
|
|
312
|
+
<template>
|
|
313
|
+
<k-editor ref="ed" v-model="html" :options="options" />
|
|
314
|
+
</template>
|
|
315
|
+
|
|
316
|
+
<script setup>
|
|
317
|
+
import { ref, onMounted } from 'vue'
|
|
318
|
+
|
|
319
|
+
const ed = ref(null)
|
|
320
|
+
const html = ref('')
|
|
321
|
+
const options = {
|
|
322
|
+
customButtons: [
|
|
323
|
+
{ name: 'column', text: '栏目', options: [], emptyText: '加载中…', link: { url: 'https://x.com/{value}', text: '{label}' } },
|
|
324
|
+
],
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
onMounted(async () => {
|
|
328
|
+
const list = await fetch('/api/columns').then((r) => r.json())
|
|
329
|
+
ed.value.editor.setButtonOptions('column', list) // 数据就绪后刷新下拉
|
|
330
|
+
})
|
|
331
|
+
</script>
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
> `k-editor` 组件的 `options` 是普通对象,`customButtons` 里的 `load` / `onSelect` 可以直接闭包引用组件里的 axios 实例、埋点函数等。
|
|
335
|
+
|
|
336
|
+
**Q:不想上传,只想直接贴图片/视频链接?**
|
|
337
|
+
点工具栏的图片或视频按钮 → 切到「网络链接」页签 → 粘贴地址即可插入(会同时提示该地址能否加载)。代码层面等价于:
|
|
338
|
+
```js
|
|
339
|
+
editor.insertImage('https://cdn.example.com/a.png', '图注')
|
|
340
|
+
editor.insertVideo('https://cdn.example.com/clip.mp4', '宣传片')
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
**Q:怎么禁止上传大视频?**
|
|
344
|
+
`maxVideoSize: 100 * 1024 * 1024`,超限会在插入前提示并拦截。
|
|
345
|
+
|
|
346
|
+
**Q:内容里的脚本安全吗?**
|
|
347
|
+
初始化、粘贴、源码模式回填都会走白名单净化(`sanitize.js`):剔除 `script/iframe/on*/javascript:` 等,`style` 声明逐条过滤。
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# 分片上传(Chunk Upload)
|
|
2
|
+
|
|
3
|
+
编辑器的图片与视频统一走 `ChunkUploader`:**切片 → 并发上传 → 失败重试 → 合并**。它只依赖一个适配器对象,因此既能在**无后端**环境下演示,也能一行切换成真实服务。
|
|
4
|
+
|
|
5
|
+
```
|
|
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 → 替换编辑器内的占位块
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
进度、已传字节、分片数、实时速度会通过 `onProgress(ratio, info)` 回传给编辑区占位块。
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 1. 三种开箱适配器
|
|
20
|
+
|
|
21
|
+
### 1.1 mock(默认,无需后端)
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
KEditor.create('#editor', { uploader: 'mock' })
|
|
25
|
+
|
|
26
|
+
// 可调参数
|
|
27
|
+
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 },
|
|
35
|
+
})
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
特点:分片真实切片与限速;完成后用 `URL.createObjectURL` 生成本地地址,可直接预览;同一文件重复上传命中「秒传」,不再重复切片。
|
|
39
|
+
|
|
40
|
+
### 1.2 http(对接真实后端)
|
|
41
|
+
|
|
42
|
+
```js
|
|
43
|
+
KEditor.create('#editor', {
|
|
44
|
+
uploader: {
|
|
45
|
+
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, // 统一响应外层包装
|
|
54
|
+
},
|
|
55
|
+
upload: { chunkSize: 5 * 1024 * 1024, concurrency: 4, retries: 2, fingerprint: 'strong' },
|
|
56
|
+
})
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### 1.3 simple(已有单次上传接口)
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
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 // 也可直接返回字符串
|
|
69
|
+
}),
|
|
70
|
+
})
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 2. 后端接口约定(推荐实现)
|
|
76
|
+
|
|
77
|
+
### `POST /api/upload/init`
|
|
78
|
+
|
|
79
|
+
请求:
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{ "fileName": "a.mp4", "fileSize": 73400320, "fileType": "video/mp4",
|
|
83
|
+
"lastModified": 1758000000000, "identifier": "…", "chunkSize": 1048576, "totalChunks": 71 }
|
|
84
|
+
```
|
|
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": [] } // 全新任务
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### `PUT /api/upload/chunk?uploadId=u_8f3c&index=3&total=71&filename=a.mp4`
|
|
95
|
+
|
|
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": "…" }` 则该分片自带地址(适合对象存储分片直传)。
|
|
99
|
+
|
|
100
|
+
### `POST /api/upload/complete`
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{ "uploadId": "u_8f3c", "identifier": "…", "fileName": "a.mp4", "fileSize": 73400320,
|
|
104
|
+
"fileType": "video/mp4", "chunkSize": 1048576, "totalChunks": 71 }
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
响应必须包含 `url`:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{ "url": "https://cdn/a.mp4", "key": "media/2026/09/a.mp4", "poster": "https://cdn/a.jpg", "duration": 63 }
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### `POST /api/upload/abort`
|
|
114
|
+
|
|
115
|
+
`{ "uploadId": "u_8f3c" }`,用于清理临时分片(用户取消时触发,失败会被忽略)。
|
|
116
|
+
|
|
117
|
+
> Node/Express 的极简实现思路:`init` 建目录 + 扫已存在分片返回 `uploadedChunks`;`chunk` 用 `raw body → fs.createWriteStream`;`complete` 按 index 顺序 `concat` 后交给对象存储。若直接用 OSS/S3 分片上传,把 `put` 换成「拿签名 URL → PUT」即可,`complete` 调用 `CompleteMultipartUpload`。
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 3. 自定义适配器
|
|
122
|
+
|
|
123
|
+
只要实现 `put`,其余可选:
|
|
124
|
+
|
|
125
|
+
```js
|
|
126
|
+
const adapter = {
|
|
127
|
+
async init(meta, { signal }) {
|
|
128
|
+
// meta: {name,size,type,lastModified,fingerprint,chunkSize,totalChunks}
|
|
129
|
+
return { uploadId: meta.fingerprint, uploadedChunks: [] } // 或 { url } 表示秒传
|
|
130
|
+
},
|
|
131
|
+
async put({ uploadId, index, total, blob, file, meta, size, signal }) {
|
|
132
|
+
await myClient.send(blob, { index, signal })
|
|
133
|
+
return {} // 或 { url }
|
|
134
|
+
},
|
|
135
|
+
async complete({ uploadId, meta, total, uploaded, chunkResults, file }) {
|
|
136
|
+
return { url: 'https://…' } // 必须返回 url
|
|
137
|
+
},
|
|
138
|
+
async abort({ uploadId, meta, error }) {},
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
KEditor.create('#editor', { uploader: adapter, upload: { chunkSize: 2 * 1024 * 1024, concurrency: 2 } })
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### 断点续传 / 秒传的判定依据
|
|
145
|
+
|
|
146
|
+
`meta.fingerprint` 默认由 `size + lastModified + 文件名` 组成(`upload.fingerprint: 'fast'`)。
|
|
147
|
+
改为 `'strong'` 时读取文件首尾各 256KB 计算 SHA-256(HTTPS / localhost 下可用),也允许传函数:
|
|
148
|
+
|
|
149
|
+
```js
|
|
150
|
+
upload: { fingerprint: async (file) => `${file.name}-${file.size}` }
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
服务端把 `identifier → 最终 url` 建索引即可实现秒传;把已落盘分片 index 列表返回即可续传。
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 4. 独立使用(不依赖编辑器)
|
|
158
|
+
|
|
159
|
+
```js
|
|
160
|
+
import { ChunkUploader, httpAdapter } from 'kyle-editor'
|
|
161
|
+
|
|
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
|
+
})
|
|
167
|
+
|
|
168
|
+
const ctrl = new AbortController()
|
|
169
|
+
const { url, chunks } = await uploader.upload(bigFile, {
|
|
170
|
+
signal: ctrl.signal,
|
|
171
|
+
onProgress: (ratio, info) => bar.style.width = `${info.percent}%`,
|
|
172
|
+
onChunk: ({ index, total }) => console.log(`${index + 1}/${total}`),
|
|
173
|
+
})
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## 5. 编辑器内的交互契约
|
|
177
|
+
|
|
178
|
+
| 场景 | 行为 |
|
|
179
|
+
|------|------|
|
|
180
|
+
| 点击工具栏图片/视频 | 选择文件 → 就地插入占位块(含进度条、分片数、速度、取消按钮) |
|
|
181
|
+
| 拖拽文件到编辑区 | 光标定位到落点后插入占位块 |
|
|
182
|
+
| 粘贴截图 | 自动生成文件名并上传 |
|
|
183
|
+
| 上传成功 | 占位块替换为 `<img>` / `<video>`,图片支持双击放大、气泡工具条调整对齐/宽度/圆角/替换/删除、**拖拽右下角把手实时缩放** |
|
|
184
|
+
| 分片失败 | 自动重试 `retries` 次;仍失败则占位块转为错误态,提供「重试 / 移除」 |
|
|
185
|
+
| 取消 | `AbortController` 中止全部在传分片并调用 `abort()`,占位块移除 |
|
|
186
|
+
| 同一文件重复插入 | 适配器 `init` 返回 `url` 时直接秒传,不再切片 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kyle-editor",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.6",
|
|
4
4
|
"description": "轻量、美观的微信公众号风格富文本编辑器(纯前端,支持图片/视频分片上传、HTML 源码模式),可通过 <script> 引入或作为 Vue 3 组件安装。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/keditor.cjs",
|
|
@@ -26,6 +26,7 @@
|
|
|
26
26
|
"dist",
|
|
27
27
|
"types",
|
|
28
28
|
"imgs",
|
|
29
|
+
"docs",
|
|
29
30
|
"README.md",
|
|
30
31
|
"LICENSE"
|
|
31
32
|
],
|