kyle-editor 1.0.0 → 1.0.2

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,296 +0,0 @@
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` 声明逐条过滤。