kyle-editor 1.0.8 → 1.0.9
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 +41 -4
- package/dist/keditor-vue.cjs +152 -9
- package/dist/keditor-vue.es.js +152 -9
- package/dist/keditor-vue.umd.js +152 -9
- package/dist/keditor.cjs +2 -1
- package/dist/keditor.es.js +2 -1
- package/dist/keditor.umd.js +2 -1
- package/dist/keditor.umd.min.js +1 -1
- package/docs/integration.md +39 -5
- package/package.json +1 -1
- package/types/vue.d.ts +56 -4
package/docs/integration.md
CHANGED
|
@@ -189,24 +189,58 @@ const { host, editor } = useKEditor({ height: 400 })
|
|
|
189
189
|
| Emit | 载荷 | 说明 |
|
|
190
190
|
|------|------|------|
|
|
191
191
|
| `update:modelValue` | `html: string` | 内容变化(自动去内部属性) |
|
|
192
|
-
| `change` | `{html, text
|
|
192
|
+
| `change` | `html: string` | 内容变化(防抖后),与 `update:modelValue` 同一个 HTML 字符串;带结构的载荷用 `instance.on('change', ({ html, text }) => …)` |
|
|
193
193
|
| `ready` | `editor` | 实例创建完成 |
|
|
194
194
|
| `upload` | `{state, kind, name, size, progress, result, error, node}` | 上传生命周期,`state` 为 `start/progress/success/error/cancel` |
|
|
195
195
|
| `error` | `{type, error, message}` | 内部异常(上传失败、净化失败、源码解析失败) |
|
|
196
196
|
| `save` | `{html, text, counts}` | 编辑器内按下 ⌘/Ctrl+S |
|
|
197
197
|
| `focus` / `blur` | — | 焦点变化 |
|
|
198
198
|
|
|
199
|
-
通过 `ref`
|
|
199
|
+
通过 `ref` 拿到原生实例做进阶操作:组件已把 KEditor 的公开 API 全部透出到 `ref` 上,**直接 `editorRef.value.xxx()` 即可**(无需再写 `.editor`):
|
|
200
200
|
|
|
201
201
|
```vue
|
|
202
|
-
<
|
|
202
|
+
<template>
|
|
203
|
+
<k-editor ref="editorRef" v-model="html" :options="options" />
|
|
204
|
+
<button @click="pick">导入 Markdown</button>
|
|
205
|
+
<input ref="fileRef" type="file" accept=".md,.markdown,.txt" hidden @change="onFile" />
|
|
206
|
+
</template>
|
|
207
|
+
|
|
203
208
|
<script setup>
|
|
209
|
+
import { ref } from 'vue'
|
|
210
|
+
|
|
211
|
+
const html = ref('')
|
|
204
212
|
const editorRef = ref()
|
|
205
|
-
|
|
206
|
-
|
|
213
|
+
const fileRef = ref()
|
|
214
|
+
|
|
215
|
+
const pick = () => fileRef.value.click()
|
|
216
|
+
const onFile = async (event) => {
|
|
217
|
+
const file = event.target.files?.[0]
|
|
218
|
+
event.target.value = ''
|
|
219
|
+
// 等价于 editorRef.value.editor.importMarkdown(file, { mode: 'append' })
|
|
220
|
+
const result = await editorRef.value.importMarkdown(file, { mode: 'append' })
|
|
221
|
+
if (!result?.ok) console.warn('导入失败:', result?.reason)
|
|
222
|
+
}
|
|
207
223
|
</script>
|
|
208
224
|
```
|
|
209
225
|
|
|
226
|
+
| ref 上的成员 | 说明 |
|
|
227
|
+
|------|------|
|
|
228
|
+
| `editor` | 原始 `KEditor` 实例(兜底用) |
|
|
229
|
+
| `getHTML()` / `getText()` / `getJSON()` / `counts()` | 读取内容与统计 |
|
|
230
|
+
| `setContent(html, options?)` / `clear()` / `focus()` / `blur()` / `undo()` / `redo()` | 内容与焦点 |
|
|
231
|
+
| `importMarkdown(source, options?)` | **导入 Markdown**:`source` 支持字符串 / `File` / `{name, content}`,`options.mode` 为 `replace` / `append` / `cursor` |
|
|
232
|
+
| `setMarkdown()` / `insertMarkdown()` / `appendMarkdown()` / `markdownOptions()` | Markdown 落点快捷方式与当前配置 |
|
|
233
|
+
| `insertImage(url, alt?)` / `insertVideo(url, label?)` / `insertCode(code?, lang?)` / `appendHTML(html)` | 直接插入内容 |
|
|
234
|
+
| `upload(file, kind?)` / `cancelUploads()` | 上传 |
|
|
235
|
+
| `setButtonOptions(name, items)` / `getButtonValue(name)` / `setButtonValue(name, value)` / `addButton(spec, options?)` / `moveButton(name, position)` / `removeButton(name)` | 工具栏按钮 |
|
|
236
|
+
| `setReadOnly(value)` / `setHeight(value)` / `setPaper(config?)` | 只读与外观 |
|
|
237
|
+
| `enterSource()` / `openPreview()` | 源码模式 / 预览 |
|
|
238
|
+
| `on(name, handler)` / `off(name, handler?)` | 订阅核心事件(`markdownimport`、`change`、`uploaddone` …) |
|
|
239
|
+
| `root` | 正文 `contenteditable` 节点 |
|
|
240
|
+
|
|
241
|
+
> `v-model` 只会接受**字符串**。给 `modelValue` 赋 `undefined` / `null` / 对象时会被忽略并给出一次 `console.warn`,不会清空正文。
|
|
242
|
+
> 需要带结构的变更载荷请用 `editorRef.value.on('change', ({ html, text }) => …)` 或 `@change`(`@change` 载荷与 `update:modelValue` 一样是 HTML 字符串)。
|
|
243
|
+
|
|
210
244
|
### 3.5 SSR 框架(Nuxt 3 / Next.js)
|
|
211
245
|
|
|
212
246
|
> ❗ 编辑器依赖 `document`、`DOMParser`、`contenteditable`,**只能在浏览器运行**。在服务端渲染阶段引入会报 `document is not defined` / `DOMParser is not defined`,必须做成客户端专属。
|
package/package.json
CHANGED
package/types/vue.d.ts
CHANGED
|
@@ -1,6 +1,18 @@
|
|
|
1
1
|
/** KEditor Vue 3 集成类型(kyle-editor/vue) */
|
|
2
2
|
import type { App, ComponentOptionsMixin, ComponentPublicInstance, DefineComponent, Ref } from 'vue'
|
|
3
|
-
import type {
|
|
3
|
+
import type {
|
|
4
|
+
ButtonPlaceOptions,
|
|
5
|
+
CustomButtonOption,
|
|
6
|
+
CustomButtonSpec,
|
|
7
|
+
EditorCounts,
|
|
8
|
+
EditorEventMap,
|
|
9
|
+
KEditor,
|
|
10
|
+
KEditorOptions,
|
|
11
|
+
MarkdownImportResult,
|
|
12
|
+
MarkdownInsertMode,
|
|
13
|
+
MarkdownSource,
|
|
14
|
+
UploadHookPayload,
|
|
15
|
+
} from './index'
|
|
4
16
|
|
|
5
17
|
export interface KEditorVueProps {
|
|
6
18
|
/** v-model 绑定的 HTML */
|
|
@@ -24,16 +36,56 @@ export interface KEditorVueEmits {
|
|
|
24
36
|
(e: 'focus'): void
|
|
25
37
|
}
|
|
26
38
|
|
|
27
|
-
/** ref
|
|
39
|
+
/** ref 上可访问的实例成员(与组件 expose 一致,等价于 KEditor 实例的公开 API) */
|
|
28
40
|
export interface KEditorVueExposed {
|
|
41
|
+
/** 原始 KEditor 实例,用于 expose 未覆盖的能力 */
|
|
29
42
|
readonly editor: KEditor | null
|
|
30
|
-
|
|
43
|
+
/** 正文 contenteditable 节点 */
|
|
44
|
+
readonly root: HTMLElement | null
|
|
45
|
+
/* 读取 */
|
|
46
|
+
getHTML(options?: { clean?: boolean | 'preview' }): string
|
|
31
47
|
getText(): string
|
|
48
|
+
getJSON(): { html: string; text: string; counts: EditorCounts } | null
|
|
32
49
|
counts(): EditorCounts | null
|
|
50
|
+
markdownOptions(): { insertMode: 'replace' | 'append' | 'cursor'; maxSize: number; auto: boolean } | null
|
|
51
|
+
/* 内容 */
|
|
52
|
+
setContent(html: string, options?: { sanitize?: boolean; silent?: boolean }): void
|
|
53
|
+
clear(): void
|
|
33
54
|
focus(): void
|
|
34
|
-
|
|
55
|
+
blur(): void
|
|
56
|
+
undo(): void
|
|
57
|
+
redo(): void
|
|
58
|
+
setReadOnly(value: boolean): void
|
|
59
|
+
/* Markdown 导入(等价于 editor.importMarkdown 等) */
|
|
60
|
+
importMarkdown(source: MarkdownSource, options?: { mode?: MarkdownInsertMode; silent?: boolean }): Promise<MarkdownImportResult> | undefined
|
|
61
|
+
setMarkdown(source: MarkdownSource, options?: { silent?: boolean }): Promise<MarkdownImportResult> | undefined
|
|
62
|
+
insertMarkdown(source: MarkdownSource, options?: { silent?: boolean }): Promise<MarkdownImportResult> | undefined
|
|
63
|
+
appendMarkdown(source: MarkdownSource, options?: { silent?: boolean }): Promise<MarkdownImportResult> | undefined
|
|
64
|
+
moveCaretToEnd(): void
|
|
65
|
+
/* 插入 / 上传 */
|
|
66
|
+
appendHTML(html: string): void
|
|
67
|
+
insertImage(url: string, alt?: string): HTMLElement | undefined
|
|
68
|
+
insertVideo(url: string, label?: string): HTMLElement | undefined
|
|
69
|
+
insertCode(code?: string, lang?: string): HTMLElement | undefined
|
|
70
|
+
codeLanguages(): { value: string; label: string }[]
|
|
71
|
+
highlightCode(): void
|
|
72
|
+
upload(file: File, kind?: 'image' | 'video'): Promise<unknown>
|
|
73
|
+
cancelUploads(): void
|
|
74
|
+
/* 工具栏按钮 */
|
|
75
|
+
addButton(spec: CustomButtonSpec, options?: ButtonPlaceOptions): HTMLElement | null | undefined
|
|
76
|
+
removeButton(name: string): boolean | undefined
|
|
77
|
+
moveButton(name: string, position: ButtonPlaceOptions): boolean | undefined
|
|
78
|
+
setButtonOptions(name: string, items: CustomButtonOption[] | string[]): CustomButtonOption[] | undefined
|
|
79
|
+
getButtonValue(name: string): CustomButtonOption | null | undefined
|
|
80
|
+
setButtonValue(name: string, value: string | number): CustomButtonOption | null | undefined
|
|
81
|
+
/* 视图 */
|
|
35
82
|
enterSource(): void
|
|
36
83
|
openPreview(): void
|
|
84
|
+
setHeight(value: number | 'auto'): number | undefined
|
|
85
|
+
setPaper(config?: { width?: number; mode?: 'fluid' | 'fixed'; gap?: number; maxWidth?: number }): unknown
|
|
86
|
+
/* 事件 */
|
|
87
|
+
on(name: string, handler: (payload: any) => void): void
|
|
88
|
+
off(name: string, handler?: (payload: any) => void): void
|
|
37
89
|
}
|
|
38
90
|
|
|
39
91
|
export declare const KEditorVue: DefineComponent<
|