kyle-editor 1.0.8 → 1.0.10

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.
@@ -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, counts}` | 内容变化(防抖后) |
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
- <k-editor ref="editorRef" v-model="html" />
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
- editorRef.value.editor.setContent('<p>来自父组件</p>') // KEditor 实例
206
- editorRef.value.getHTML()
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kyle-editor",
3
- "version": "1.0.8",
3
+ "version": "1.0.10",
4
4
  "description": "轻量、美观的微信公众号风格富文本编辑器(纯前端,支持图片/视频分片上传、HTML 源码模式),可通过 <script> 引入或作为 Vue 3 组件安装。",
5
5
  "type": "module",
6
6
  "main": "./dist/keditor.cjs",
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 { EditorCounts, EditorEventMap, KEditor, KEditorOptions, UploadHookPayload } from './index'
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
- getHTML(): string
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
- setContent(html: string): void
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<