kyle-editor 0.0.0-stage → 1.0.0
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/LICENSE +21 -0
- package/README.md +194 -2
- package/dist/keditor-vue.cjs +120 -0
- package/dist/keditor-vue.es.js +118 -0
- package/dist/keditor-vue.umd.js +122 -0
- package/dist/keditor.cjs +4116 -0
- package/dist/keditor.es.js +4116 -0
- package/dist/keditor.umd.js +4120 -0
- package/docs/api.md +223 -0
- package/docs/index.md +8 -0
- package/docs/integration.md +296 -0
- package/docs/npm-publish.md +412 -0
- package/docs/upload-adapter.md +186 -0
- package/package.json +77 -4
- package/src/core/commands.js +311 -0
- package/src/core/editor.js +795 -0
- package/src/core/format.js +64 -0
- package/src/core/history.js +92 -0
- package/src/core/icons.js +49 -0
- package/src/core/paste.js +140 -0
- package/src/core/sanitize.js +182 -0
- package/src/core/selection.js +129 -0
- package/src/core/toolbar.js +465 -0
- package/src/core/utils.js +95 -0
- package/src/index.js +33 -0
- package/src/media/media.js +331 -0
- package/src/ui/bubble.js +270 -0
- package/src/ui/popover.js +507 -0
- package/src/ui/preview.js +59 -0
- package/src/ui/source.js +97 -0
- package/src/ui/styles.js +447 -0
- package/src/ui/toast.js +56 -0
- package/src/upload/adapters.js +206 -0
- package/src/upload/chunk-uploader.js +193 -0
- package/src/upload/fingerprint.js +38 -0
- package/src/vue/index.js +104 -0
- package/types/index.d.ts +345 -0
- package/types/vue.d.ts +73 -0
package/docs/api.md
ADDED
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
# API 参考
|
|
2
|
+
|
|
3
|
+
## 一、创建实例
|
|
4
|
+
|
|
5
|
+
```js
|
|
6
|
+
import { KEditor } from 'kyle-editor'
|
|
7
|
+
|
|
8
|
+
const editor = new KEditor('#editor', { /* options */ })
|
|
9
|
+
// 或
|
|
10
|
+
const editor = KEditor.create(el, options) // el: 选择器 / HTMLElement / Vue ref.$el
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 二、配置项 options
|
|
16
|
+
|
|
17
|
+
| 配置 | 类型 | 默认值 | 说明 |
|
|
18
|
+
|------|------|--------|------|
|
|
19
|
+
| `value` | `string` | `''` | 初始 HTML;留空时取挂载节点的 `innerHTML` |
|
|
20
|
+
| `placeholder` | `string` | `'开始撰写内容…'` | 空内容占位文案 |
|
|
21
|
+
| `height` | `number` | `460` | 编辑区可视高度(px),`0` 为自适应内容高度 |
|
|
22
|
+
| `minHeight` | `number` | `320` | 纸张最小高度 |
|
|
23
|
+
| `paperWidth` | `number` | `677` | 正文版心宽度(与公众号一致) |
|
|
24
|
+
| `primaryColor` | `string` | `'#07c160'` | 主题色(CSS 变量 `--ke-primary`) |
|
|
25
|
+
| `toolbar` | `string[] \| false` | `DEFAULT_TOOLBAR` | 工具栏项,见下表;`false` 隐藏 |
|
|
26
|
+
| `hideToolbar` | `boolean` | `false` | 隐藏工具栏 |
|
|
27
|
+
| `hideStatusbar` | `boolean` | `false` | 隐藏底部状态栏 |
|
|
28
|
+
| `readOnly` | `boolean` | `false` | 只读 |
|
|
29
|
+
| `autofocus` | `boolean` | `false` | 创建后自动聚焦 |
|
|
30
|
+
| `maxLength` | `number` | `0` | 超出后提示(软限制,不截断输入) |
|
|
31
|
+
| `wordCount` | `boolean` | `true` | 底部字数/媒体统计 |
|
|
32
|
+
| `sanitize` | `boolean` | `true` | 初始化与 `setContent` 时净化 HTML |
|
|
33
|
+
| `historyLimit` | `number` | `60` | 撤销栈深度 |
|
|
34
|
+
| `uploader` | `'mock' \| object \| fn \| ChunkUploader` | `'mock'` | 上传适配器,见 [upload-adapter.md](upload-adapter.md) |
|
|
35
|
+
| `upload` | `object` | `{chunkSize:1MB, concurrency:3, retries:2, fingerprint:'fast'}` | 分片参数 |
|
|
36
|
+
| `image.compress` | `object\|false` | `{maxWidth:1440, quality:0.85, minSize:300KB}` | 上传前大图压缩 |
|
|
37
|
+
| `maxImageSize` | `number` | `20MB` | 图片体积上限,超限拦截 |
|
|
38
|
+
| `maxVideoSize` | `number` | `512MB` | 视频体积上限 |
|
|
39
|
+
| `imageAccept` / `videoAccept` | `string` | 常见图/视频类型 | 文件选择器 `accept` |
|
|
40
|
+
| `paste.enabled` | `boolean` | `true` | 接管粘贴 |
|
|
41
|
+
| `paste.clean` | `boolean` | `true` | 粘贴内容净化(Word/WPS 自动清洗) |
|
|
42
|
+
| `paste.uploadFiles` | `boolean` | `true` | 粘贴截图/文件即上传 |
|
|
43
|
+
| `paste.localizeImages` | `boolean` | `false` | 尝试把外链图片下载后本地化 |
|
|
44
|
+
|
|
45
|
+
### 工具栏项
|
|
46
|
+
|
|
47
|
+
`undo` `redo` `heading` `fontsize` `bold` `italic` `underline` `strike` `foreColor` `backColor`
|
|
48
|
+
`alignLeft` `alignCenter` `alignRight` `alignJustify` `ul` `ol` `quote` `link` `image` `video`
|
|
49
|
+
`table` `code` `hr` `clear` `source` `preview` `fullscreen`;分隔符 `'|'`,右对齐标记 `':tail'`。
|
|
50
|
+
|
|
51
|
+
```js
|
|
52
|
+
toolbar: ['undo', 'redo', '|', 'bold', 'italic', '|', 'image', 'video', ':tail', 'source']
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
工具栏始终单行显示,放不下时可**左右滑动**,并有四重提示保证可发现性:
|
|
56
|
+
|
|
57
|
+
| 提示 | 作用 |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| 常显滚动条 | 静止时也能从滑块长度看出「还有更多工具」 |
|
|
60
|
+
| 尾部左缘渐隐 + 阴影 | 明确表达「有工具正藏在这块底下」,滑到最右自动消失 |
|
|
61
|
+
| 左缘渐隐 | 已向右滑出时提示左边还有内容 |
|
|
62
|
+
| 首次引导气泡 | 「工具栏可左右滑动」,3.8s 后或首次滑动后消失,`localStorage` 记忆不重复弹 |
|
|
63
|
+
|
|
64
|
+
鼠标还可**直接按住拖动**平移工具栏(光标变为抓握状);触屏沿用系统原生滑动。`:tail` 之后的「源码 / 预览 / 全屏」始终吸附在右端可见。
|
|
65
|
+
|
|
66
|
+
#### 下拉面板一览
|
|
67
|
+
|
|
68
|
+
| 按钮 | 点击行为 | 面板内容 |
|
|
69
|
+
|------|----------|----------|
|
|
70
|
+
| `heading` | 展开「段落样式」面板 | 正文 / 标题一 / 标题二 / 标题三,每档给出**真实字号预览 + 用途说明**(如「标题一 · 大标题 · 22px 加粗,全文主标题(建议只用一次)」),按钮文案跟随当前段落 |
|
|
71
|
+
| `fontsize` | 展开「字号」面板 | 12–32px 网格,当前字号高亮 |
|
|
72
|
+
| `foreColor` | **一次点击直接展开颜色面板** | 最近使用(本次会话)+ 主题颜色 + 标准颜色,色块带中文名称 tooltip,底部为取色器 + HEX 输入 + 应用;右上角「恢复默认」清除上色 |
|
|
73
|
+
| `backColor` | 同上(底色) | 推荐底色 + 主题颜色 + 自定义;按钮上的「A」用当前底色做高亮示意 |
|
|
74
|
+
| `image` / `video` | 展开插入面板 | 两个页签:**本地上传**(点击或拖拽到虚线区)/ **网络链接**(粘贴地址即可插入,附带可访问性校验提示) |
|
|
75
|
+
| `table` | 展开网格 | 10×8 规格选择,实时显示「N 列 × M 行」 |
|
|
76
|
+
| `link` | 展开表单 | 文字 / 地址 / 新窗口打开,已链接时提供「移除链接」 |
|
|
77
|
+
|
|
78
|
+
面板统一样式:圆角卡片 + 标题栏 + 分区小标题 + 入场动画;打开时会自动记录正文选区,操作后还原,因此**先选文字再点颜色**一定生效。
|
|
79
|
+
|
|
80
|
+
#### 图片缩放
|
|
81
|
+
|
|
82
|
+
点击正文中的图片会浮出气泡工具条(对齐 / 宽度 30%·60%·100% / 圆角 / 查看大图 / 替换 / 删除),同时图片**右下角出现圆形拖拽把手**:
|
|
83
|
+
|
|
84
|
+
- 按住把手左右拖动,实时按**容器宽度百分比**等比缩放,顶部浮层显示当前宽度(如 `58%`)
|
|
85
|
+
- 范围限制 15%–100%,不会拖出正文版心;松开即写入撤销栈,可 `⌘/Ctrl+Z` 回退
|
|
86
|
+
- 把手与浮层挂在编辑器容器上,**不进入内容区**,不会污染 `getHTML()` 导出与历史快照
|
|
87
|
+
- 视频卡片不支持拖拽缩放(保持固定比例),可用气泡工具条的「窄版 / 宽版」切换
|
|
88
|
+
|
|
89
|
+
#### 图片对齐
|
|
90
|
+
|
|
91
|
+
选中图片后,**工具栏的「左对齐 / 居中 / 右对齐」与气泡工具条的对齐按钮效果完全一致**——都作用于图片本身(`img` 为块级元素,靠 `margin:auto` 定位),而非所在段落:
|
|
92
|
+
|
|
93
|
+
- 图片宽度为 100% 时居中无视觉差异,**先缩小(拖拽把手或宽度按钮)再居中**即可看到图片在正文中水平居中
|
|
94
|
+
- 对齐写入撤销栈,可 `⌘/Ctrl+Z` 回退;工具栏对齐按钮会随选中图片的对齐状态高亮
|
|
95
|
+
|
|
96
|
+
#### 快捷键
|
|
97
|
+
|
|
98
|
+
| 快捷键 | 作用 |
|
|
99
|
+
|--------|------|
|
|
100
|
+
| `⌘/Ctrl + B / I / U` | 加粗 / 斜体 / 下划线 |
|
|
101
|
+
| `⌘/Ctrl + K` | 插入链接 |
|
|
102
|
+
| `⌘/Ctrl + Shift + K` | 切换 HTML 源码模式 |
|
|
103
|
+
| `⌘/Ctrl + Z` / `Shift + Z` / `Y` | 撤销 / 重做 |
|
|
104
|
+
| `⌘/Ctrl + S` | 触发 `save` 事件 |
|
|
105
|
+
| `Esc` | 关闭面板 / 退出预览 |
|
|
106
|
+
|
|
107
|
+
### 回调
|
|
108
|
+
|
|
109
|
+
| 回调 | 签名 | 说明 |
|
|
110
|
+
|------|------|------|
|
|
111
|
+
| `onChange(html, editor)` | | 内容变化(160ms 防抖) |
|
|
112
|
+
| `onReady(editor)` | | 实例可用 |
|
|
113
|
+
| `onError(error)` | | 内部异常 |
|
|
114
|
+
| `onUpload({stage, file, kind, url, percent, info})` | | `uploadstart/uploaddone/uploaderror/uploadcancel` |
|
|
115
|
+
| `beforeUpload(file, kind)` | 返回 `File` 改写、`false` 拦截 | 上传前钩子(加水印、二次校验等) |
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 三、实例属性与方法
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
editor.id // 实例 id
|
|
123
|
+
editor.el // 最外层容器
|
|
124
|
+
editor.root // contenteditable 节点
|
|
125
|
+
editor.options // 合并后的配置
|
|
126
|
+
editor.commands // 指令集(可程序化调用)
|
|
127
|
+
editor.media // 上传/媒体管理
|
|
128
|
+
editor.uploader // ChunkUploader 实例
|
|
129
|
+
editor.history // 撤销栈
|
|
130
|
+
editor.readOnly / sourceMode / previewMode / fullscreen
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
| 方法 | 说明 |
|
|
134
|
+
|------|------|
|
|
135
|
+
| `getHTML({clean?})` | 取当前 HTML,默认剔除编辑器内部属性、未完成占位块 |
|
|
136
|
+
| `getText()` | 纯文本 |
|
|
137
|
+
| `getJSON()` | `{html, text, counts}` |
|
|
138
|
+
| `setContent(html, {sanitize?, silent?})` | 覆盖内容 |
|
|
139
|
+
| `appendHTML(html)` | 在光标处插入 |
|
|
140
|
+
| `clear()` | 清空并取消所有上传 |
|
|
141
|
+
| `focus()` / `blur()` | 聚焦/失焦 |
|
|
142
|
+
| `setReadOnly(bool)` | 切换只读 |
|
|
143
|
+
| `undo()` / `redo()` | 撤销/重做(含光标位置恢复) |
|
|
144
|
+
| `insertImage(url, alt?)` / `insertVideo(url, label?)` | 按地址插入媒体(等同工具栏「网络链接」页签) |
|
|
145
|
+
| `upload(file, kind?)` | 手动触发一次上传(自动判断图片/视频) |
|
|
146
|
+
| `cancelUploads()` | 取消全部进行中任务 |
|
|
147
|
+
| `counts()` | `{chars, words, images, videos, uploading}` |
|
|
148
|
+
| `enterSource()` / `exitSource()` / `toggleSource()` | 源码模式 |
|
|
149
|
+
| `openPreview()` / `closePreview()` / `togglePreview()` | 预览模式 |
|
|
150
|
+
| `toggleFullscreen()` | 全屏编辑 |
|
|
151
|
+
| `on(type, fn)` / `off(type, fn)` | 事件订阅,返回取消函数 |
|
|
152
|
+
| `destroy()` | 卸载实例、清理监听与临时 URL |
|
|
153
|
+
|
|
154
|
+
### 事件
|
|
155
|
+
|
|
156
|
+
| 事件 | 载荷 | 触发时机 |
|
|
157
|
+
|------|------|----------|
|
|
158
|
+
| `ready` | `{editor}` | 实例挂载完成 |
|
|
159
|
+
| `change` | `{html, text}` | 内容变化 |
|
|
160
|
+
| `focus` / `blur` | | 编辑区聚焦/失焦 |
|
|
161
|
+
| `save` | `{html}` | ⌘/Ctrl + S |
|
|
162
|
+
| `uploadstart` | `{file, kind}` | 开始上传 |
|
|
163
|
+
| `uploaddone` | `{file, kind, url}` | 上传完成 |
|
|
164
|
+
| `uploaderror` | `{file, kind, error}` | 失败(已重试后) |
|
|
165
|
+
| `uploadcancel` | `{file, kind}` | 取消 |
|
|
166
|
+
| `insertmedia` | `{kind, url, node}` | 通过「网络链接」页签插入图片/视频 |
|
|
167
|
+
| `sourcechange` | `{mode: 'source'\|'visual'}` | 源码模式切换 |
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## 四、指令集 commands
|
|
172
|
+
|
|
173
|
+
```js
|
|
174
|
+
editor.commands.toggleMark('bold' | 'italic' | 'underline' | 'strike')
|
|
175
|
+
editor.commands.setFontSize(18)
|
|
176
|
+
editor.commands.setColor('fore' | 'back', '#07c160') // color=null 恢复默认
|
|
177
|
+
editor.commands.setAlign('left' | 'center' | 'right' | 'justify')
|
|
178
|
+
editor.commands.toggleList('ordered' | 'unordered')
|
|
179
|
+
editor.commands.setHeading('p' | 'h1' | 'h2' | 'h3')
|
|
180
|
+
editor.commands.toggleBlockquote()
|
|
181
|
+
editor.commands.createLink({ url, text, target })
|
|
182
|
+
editor.commands.removeLink()
|
|
183
|
+
editor.commands.insertTable(3, 2) // 列, 行
|
|
184
|
+
editor.commands.insertCodeBlock('const a = 1')
|
|
185
|
+
editor.commands.insertDivider()
|
|
186
|
+
editor.commands.insertHTML('<p>富文本片段</p>')
|
|
187
|
+
editor.commands.clearFormat()
|
|
188
|
+
editor.getState() // 当前选区状态(工具栏高亮用)
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## 五、独立可用的工具函数
|
|
192
|
+
|
|
193
|
+
```js
|
|
194
|
+
import { sanitizeHtml, formatHtml, escapeHtml, isSafeUrl, cleanWordHtml, mockAdapter, httpAdapter, simpleAdapter, ChunkUploader } from 'kyle-editor'
|
|
195
|
+
|
|
196
|
+
sanitizeHtml(dirtyHtml) // 白名单净化,返回安全 HTML
|
|
197
|
+
formatHtml(html) // 缩进美化(编辑器源码模式同款)
|
|
198
|
+
cleanWordHtml(wordHtml) // 粘贴前的 Word/WPS 清洗
|
|
199
|
+
isSafeUrl('javascript:1') // => false
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
UMD / 默认导出上也挂了一批静态成员,`<script>` 引入时直接可用:
|
|
203
|
+
|
|
204
|
+
```js
|
|
205
|
+
KEditor.version // '1.0.0'
|
|
206
|
+
KEditor.sanitizeHtml(html) // 白名单净化
|
|
207
|
+
KEditor.formatHtml(html) // 源码美化
|
|
208
|
+
KEditor.cleanWordHtml(html) // Word 清洗
|
|
209
|
+
KEditor.mockAdapter({speed}) // 内置分片模拟适配器
|
|
210
|
+
KEditor.httpAdapter(config) // 真实后端适配器
|
|
211
|
+
KEditor.simpleAdapter(fn) // 单次直传适配器
|
|
212
|
+
KEditor.chunkUploader(file, adapter, opts) // 分片调度器
|
|
213
|
+
KEditor.utils // { uid, escapeHtml }
|
|
214
|
+
KEditor.create(el, options) // 工厂方法,等价于 new KEditor(...)
|
|
215
|
+
KEditor.plugin // Vue 3 插件(仅 keditor-vue.umd.js)
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
> TypeScript:包内自带 `types/index.d.ts` 与 `types/vue.d.ts`,`import KEditor from 'kyle-editor'` 即有完整提示,无需额外安装。
|
|
219
|
+
|
|
220
|
+
## 六、安全说明
|
|
221
|
+
|
|
222
|
+
- 所有进入编辑器的外部 HTML(`value`、`setContent`、粘贴)都会经过 `sanitizeHtml`:标签/属性双白名单、`on*` 事件属性剔除、`javascript:`/`vbscript:`/`file:`/非法 `data:` 协议拦截、`style` 声明逐条过滤(丢弃 `expression`、`behavior` 等)。
|
|
223
|
+
- `getHTML({clean: false})` 会返回含编辑器内部属性的原始 HTML,请仅在调试时使用;入库前建议再跑一次 `sanitizeHtml`。
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 集成文档索引
|
|
3
|
+
* - [README.md](../README.md) — 快速开始
|
|
4
|
+
* - [integration.md](integration.md) — 三种集成方式(script / ESM / Vue3)
|
|
5
|
+
* - [api.md](api.md) — 配置项、实例方法、事件
|
|
6
|
+
* - [upload-adapter.md](upload-adapter.md) — 分片上传协议与后端接口约定
|
|
7
|
+
*/
|
|
8
|
+
export default ['README.md', 'integration.md', 'api.md', 'upload-adapter.md']
|
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
# 集成指南
|
|
2
|
+
|
|
3
|
+
KEditor 是**纯前端**编辑器,不依赖任何后端接口。三种集成方式任选其一。
|
|
4
|
+
|
|
5
|
+
| 方式 | 适用场景 | 引入文件 |
|
|
6
|
+
|------|----------|----------|
|
|
7
|
+
| Script(UMD) | 静态页、jQuery/Vue2 老项目、快速原型 | `dist/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
|
+
<script src="dist/keditor.umd.js"></script>
|
|
28
|
+
<script>
|
|
29
|
+
const editor = KEditor.create('#editor', {
|
|
30
|
+
placeholder: '开始撰写内容…',
|
|
31
|
+
height: 460,
|
|
32
|
+
})
|
|
33
|
+
|
|
34
|
+
editor.on('change', ({ html }) => console.log(html))
|
|
35
|
+
document.querySelector('#save').onclick = () => submit(editor.getHTML())
|
|
36
|
+
</script>
|
|
37
|
+
</body></html>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
UMD 全局对象 `KEditor` 上的可用成员:
|
|
41
|
+
|
|
42
|
+
```js
|
|
43
|
+
KEditor.create(target, options) // 返回实例(推荐)
|
|
44
|
+
KEditor.mount(...) // create 的别名
|
|
45
|
+
KEditor.KEditor // 类本体,new KEditor(target, options)
|
|
46
|
+
KEditor.mockAdapter(options) // 无后端演示适配器
|
|
47
|
+
KEditor.httpAdapter(config) // 真实后端适配器
|
|
48
|
+
KEditor.simpleAdapter(fn) // 单次直传接口包装
|
|
49
|
+
KEditor.sanitizeHtml(html) // 独立使用的 HTML 净化
|
|
50
|
+
KEditor.formatHtml(html) // 独立使用的 HTML 格式化
|
|
51
|
+
KEditor.version
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
> 本地预览:仓库根目录已内置静态服务脚本 `npm run dev`(127.0.0.1:5178),打开 `demo/script.html`。
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 2. ESM / 打包工具引入
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npm i kyle-editor # 或将本仓库 dist/ 拷贝进项目
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
```js
|
|
65
|
+
import { KEditor, create, mockAdapter } from 'kyle-editor'
|
|
66
|
+
|
|
67
|
+
const editor = create('#editor', {
|
|
68
|
+
value: '<p>hello</p>',
|
|
69
|
+
uploader: mockAdapter({ speed: 8 }), // 演示:不请求后端
|
|
70
|
+
upload: { chunkSize: 256 * 1024, concurrency: 3 },
|
|
71
|
+
})
|
|
72
|
+
|
|
73
|
+
// 组件卸载时务必销毁
|
|
74
|
+
window.addEventListener('beforeunload', () => editor.destroy())
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
按需引入(tree-shaking 友好):
|
|
78
|
+
|
|
79
|
+
```js
|
|
80
|
+
import { formatHtml } from 'kyle-editor' // 源码格式化
|
|
81
|
+
import { sanitizeHtml } from 'kyle-editor' // 粘贴/回填净化
|
|
82
|
+
import { ChunkUploader, httpAdapter } from 'kyle-editor' // 只用上传能力
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### 在 React 中使用
|
|
86
|
+
|
|
87
|
+
```jsx
|
|
88
|
+
import { useEffect, useRef } from 'react'
|
|
89
|
+
import { KEditor } from 'kyle-editor'
|
|
90
|
+
|
|
91
|
+
export function Editor({ value, onChange }) {
|
|
92
|
+
const host = useRef(null)
|
|
93
|
+
const editor = useRef(null)
|
|
94
|
+
|
|
95
|
+
useEffect(() => {
|
|
96
|
+
editor.current = new KEditor(host.current, { value, onChange: (html) => onChange(html) })
|
|
97
|
+
return () => editor.current?.destroy()
|
|
98
|
+
}, [])
|
|
99
|
+
|
|
100
|
+
useEffect(() => {
|
|
101
|
+
if (editor.current && value !== editor.current.getHTML()) editor.current.setContent(value)
|
|
102
|
+
}, [value])
|
|
103
|
+
|
|
104
|
+
return <div ref={host} />
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## 3. Vue 3 安装集成
|
|
111
|
+
|
|
112
|
+
### 3.1 全局注册(推荐)
|
|
113
|
+
|
|
114
|
+
```js
|
|
115
|
+
// main.js
|
|
116
|
+
import { createApp } from 'vue'
|
|
117
|
+
import App from './App.vue'
|
|
118
|
+
import KEditorVue from 'kyle-editor/vue' // 默认导出是组件(自带 install)
|
|
119
|
+
|
|
120
|
+
createApp(App).use(KEditorVue).mount('#app')
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
```vue
|
|
124
|
+
<template>
|
|
125
|
+
<k-editor v-model="form.content" :options="editorOptions" :disabled="readonly" @upload="onUpload" @ready="onReady" />
|
|
126
|
+
<button @click="submit">保存</button>
|
|
127
|
+
</template>
|
|
128
|
+
|
|
129
|
+
<script setup>
|
|
130
|
+
import { ref } from 'vue'
|
|
131
|
+
|
|
132
|
+
const form = ref({ content: '<p>初始内容</p>' })
|
|
133
|
+
const readonly = ref(false)
|
|
134
|
+
const editorOptions = {
|
|
135
|
+
placeholder: '支持拖拽 / 粘贴上传…',
|
|
136
|
+
height: 420,
|
|
137
|
+
uploader: { type: 'http', initUrl: '/api/upload/init', chunkUrl: '/api/upload/chunk', completeUrl: '/api/upload/complete' },
|
|
138
|
+
upload: { chunkSize: 1024 * 1024, concurrency: 3, retries: 2 },
|
|
139
|
+
}
|
|
140
|
+
const onUpload = (payload) => console.log(payload.stage, payload.percent)
|
|
141
|
+
const onReady = (editor) => console.log('编辑器实例', editor)
|
|
142
|
+
</script>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
也可指定注册名:
|
|
146
|
+
|
|
147
|
+
```js
|
|
148
|
+
app.use(KEditorVue, { name: 'RichEditor' }) // <rich-editor />
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### 3.2 局部引入组件
|
|
152
|
+
|
|
153
|
+
```vue
|
|
154
|
+
<script setup>
|
|
155
|
+
import { KEditorVue } from 'kyle-editor/vue'
|
|
156
|
+
</script>
|
|
157
|
+
|
|
158
|
+
<template>
|
|
159
|
+
<KEditorVue v-model="html" />
|
|
160
|
+
</template>
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
> 默认导出与具名导出 `KEditorVue` 是同一个组件(默认导出额外带了 `install`),
|
|
164
|
+
> 所以 `import KEditorVue from 'kyle-editor/vue'` 后直接 `<KEditorVue v-model="html" />` 也能正常渲染。
|
|
165
|
+
> 若只想全局注册,用 `import { KEditorPlugin } from 'kyle-editor/vue'` 语义更清楚。
|
|
166
|
+
|
|
167
|
+
### 3.3 组合式 API
|
|
168
|
+
|
|
169
|
+
```js
|
|
170
|
+
import { useKEditor } from 'kyle-editor/vue'
|
|
171
|
+
|
|
172
|
+
const { host, editor } = useKEditor({ height: 400 })
|
|
173
|
+
// <div ref="host"></div>,editor.value 为 KEditor 实例
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### 3.4 组件 Props / Emits
|
|
177
|
+
|
|
178
|
+
| Prop | 类型 | 说明 |
|
|
179
|
+
|------|------|------|
|
|
180
|
+
| `modelValue` | `string` | HTML 字符串,`v-model` 绑定;外部变更会同步进编辑器 |
|
|
181
|
+
| `options` | `object` | 与 `new KEditor(el, options)` 完全一致的配置 |
|
|
182
|
+
| `disabled` | `boolean` | 只读模式 |
|
|
183
|
+
| `height` | `number` | 覆盖 `options.height` |
|
|
184
|
+
|
|
185
|
+
| Emit | 载荷 | 说明 |
|
|
186
|
+
|------|------|------|
|
|
187
|
+
| `update:modelValue` | `html: string` | 内容变化(自动去内部属性) |
|
|
188
|
+
| `change` | `{html, text, counts}` | 内容变化(防抖后) |
|
|
189
|
+
| `ready` | `editor` | 实例创建完成 |
|
|
190
|
+
| `upload` | `{state, kind, name, size, progress, result, error, node}` | 上传生命周期,`state` 为 `start/progress/success/error/cancel` |
|
|
191
|
+
| `error` | `{type, error, message}` | 内部异常(上传失败、净化失败、源码解析失败) |
|
|
192
|
+
| `save` | `{html, text, counts}` | 编辑器内按下 ⌘/Ctrl+S |
|
|
193
|
+
| `focus` / `blur` | — | 焦点变化 |
|
|
194
|
+
|
|
195
|
+
通过 `ref` 拿到原生实例做进阶操作:
|
|
196
|
+
|
|
197
|
+
```vue
|
|
198
|
+
<k-editor ref="editorRef" v-model="html" />
|
|
199
|
+
<script setup>
|
|
200
|
+
const editorRef = ref()
|
|
201
|
+
editorRef.value.editor.setContent('<p>来自父组件</p>') // KEditor 实例
|
|
202
|
+
editorRef.value.getHTML()
|
|
203
|
+
</script>
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### 3.5 SSR 框架(Nuxt 3 / Next.js)
|
|
207
|
+
|
|
208
|
+
> ❗ 编辑器依赖 `document`、`DOMParser`、`contenteditable`,**只能在浏览器运行**。在服务端渲染阶段引入会报 `document is not defined` / `DOMParser is not defined`,必须做成客户端专属。
|
|
209
|
+
|
|
210
|
+
**Nuxt 3**:插件文件名带 `.client` 后缀即只在客户端加载
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
// plugins/keditor.client.ts
|
|
214
|
+
import KEditorVue from 'kyle-editor/vue'
|
|
215
|
+
export default defineNuxtPlugin((nuxtApp) => nuxtApp.vueApp.use(KEditorVue))
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
```vue
|
|
219
|
+
<template>
|
|
220
|
+
<ClientOnly>
|
|
221
|
+
<k-editor v-model="html" />
|
|
222
|
+
</ClientOnly>
|
|
223
|
+
</template>
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
**Next.js(App Router)**:组件顶部标 `'use client'`,并用 `next/dynamic` 关闭 SSR
|
|
227
|
+
|
|
228
|
+
```tsx
|
|
229
|
+
// app/editor-page.tsx
|
|
230
|
+
'use client'
|
|
231
|
+
import dynamic from 'next/dynamic'
|
|
232
|
+
|
|
233
|
+
const KEditor = dynamic(() => import('kyle-editor/vue').then((m) => m.KEditorVue), { ssr: false })
|
|
234
|
+
|
|
235
|
+
export default function Page() {
|
|
236
|
+
return <KEditor modelValue="" />
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
若需在服务端做 HTML 消毒(例如入库前过滤),不要直接用本包的 `sanitizeHtml`(依赖 DOM),请改用 `isomorphic-dompurify` 等同构方案;`escapeHtml` / `isSafeUrl` 是纯函数,Node 下可直接用。
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
### 3.6 TypeScript
|
|
245
|
+
|
|
246
|
+
包内自带声明(`package.json` 的 `types` 与 `exports.types`),无需安装 `@types`:
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
import KEditor, { type KEditorOptions, type UploadAdapter, type UploadResult } from 'kyle-editor'
|
|
250
|
+
|
|
251
|
+
const options: KEditorOptions = {
|
|
252
|
+
height: 480,
|
|
253
|
+
upload: { chunkSize: 2 * 1024 * 1024, concurrency: 4 },
|
|
254
|
+
uploader: myAdapter, // 满足 UploadAdapter 接口即可
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
const editor = KEditor.create('#editor', options)
|
|
258
|
+
const html: string = editor.getHTML()
|
|
259
|
+
const counts = editor.counts()
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Vue 3:`import KEditorVue from 'kyle-editor/vue'` 即带 props/emits 提示;`ref` 取出的实例上 `editor`、`getHTML()`、`focus()` 等均已声明。
|
|
263
|
+
|
|
264
|
+
UMD 方式(无构建)下若需提示,可 `/// <reference types="kyle-editor/types" />` 或直接使用 `KEditor.create`。
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## 4. 常见问题
|
|
269
|
+
|
|
270
|
+
**Q:不需要后端,怎么让图片真的显示出来?**
|
|
271
|
+
默认 `uploader: 'mock'` 会在浏览器内完成切片并生成 `blob:` 地址,页面内可直接预览。保存草稿时把 `getHTML()` 存下来即可;正式上线时换成 `httpAdapter` 就会得到 CDN 地址。
|
|
272
|
+
|
|
273
|
+
**Q:`blob:` 地址提交到服务器会失效,怎么办?**
|
|
274
|
+
在提交前调用 `editor.getHTML()`,把 `data-k-url` 为 `blob:` 的资源先上传(`beforeUpload` 里做映射),或直接配置真实 `uploader`。
|
|
275
|
+
|
|
276
|
+
**Q:如何精简工具栏?**
|
|
277
|
+
```js
|
|
278
|
+
KEditor.create('#editor', { toolbar: ['undo', 'redo', '|', 'bold', 'image', 'video', ':tail', 'source'] })
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
`'|'` 为分隔符,`':tail'` 之后的按钮靠右对齐(窄屏下吸附在右端不会被滚走),`toolbar: false` 隐藏工具栏。工具栏放不下时可左右滑动,并有滚动条、边缘渐隐、首次引导气泡等提示,详见 [api.md](api.md#工具栏项)。
|
|
282
|
+
|
|
283
|
+
可用项:`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#工具栏项)。
|
|
284
|
+
|
|
285
|
+
**Q:不想上传,只想直接贴图片/视频链接?**
|
|
286
|
+
点工具栏的图片或视频按钮 → 切到「网络链接」页签 → 粘贴地址即可插入(会同时提示该地址能否加载)。代码层面等价于:
|
|
287
|
+
```js
|
|
288
|
+
editor.insertImage('https://cdn.example.com/a.png', '图注')
|
|
289
|
+
editor.insertVideo('https://cdn.example.com/clip.mp4', '宣传片')
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
**Q:怎么禁止上传大视频?**
|
|
293
|
+
`maxVideoSize: 100 * 1024 * 1024`,超限会在插入前提示并拦截。
|
|
294
|
+
|
|
295
|
+
**Q:内容里的脚本安全吗?**
|
|
296
|
+
初始化、粘贴、源码模式回填都会走白名单净化(`sanitize.js`):剔除 `script/iframe/on*/javascript:` 等,`style` 声明逐条过滤。
|