kyle-editor 1.0.1 → 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kyle-editor",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "轻量、美观的微信公众号风格富文本编辑器(纯前端,支持图片/视频分片上传、HTML 源码模式),可通过 <script> 引入或作为 Vue 3 组件安装。",
5
5
  "type": "module",
6
6
  "main": "./dist/keditor.cjs",
@@ -39,7 +39,7 @@
39
39
  "test:types": "node test/check-types.mjs",
40
40
  "test:package": "node test/check-package.mjs",
41
41
  "test:install": "node test/check-install.mjs",
42
- "test:visual": "node test/shoot.mjs rich,uploading,bubble,resize,align,source,preview,color,heading,media,link,scroll,scroll2,http://127.0.0.1:5178/demo/vue.html",
42
+ "test:visual": "node test/shoot.mjs rich,uploading,bubble,resize,align,source,preview,color,heading,media,link,custom,customload,customerr,scroll,scroll2,http://127.0.0.1:5178/demo/vue.html",
43
43
  "clean": "rm -rf dist",
44
44
  "verify": "npm run build && npm test && npm run test:pages && npm run test:types && npm run test:package",
45
45
  "pack:check": "npm run build && npm run test:package && npm pack --dry-run",
@@ -52,12 +52,10 @@
52
52
  "editor",
53
53
  "wechat",
54
54
  "富文本编辑器",
55
- "chunk-upload",
56
- "分片上传",
57
55
  "vue3"
58
56
  ],
59
57
  "license": "MIT",
60
- "author": "kyle <zhendong.li@edoctor.cn>",
58
+ "author": "kyle <1399860604@qq.com>",
61
59
  "publishConfig": {
62
60
  "access": "public",
63
61
  "registry": "https://registry.npmjs.org"
package/types/index.d.ts CHANGED
@@ -130,8 +130,8 @@ export interface UploadHookPayload {
130
130
  error?: Error
131
131
  }
132
132
 
133
- /** 工具栏项名称 */
134
- export type ToolbarItem =
133
+ /** 内置工具栏项名称 */
134
+ export type BuiltinToolbarItem =
135
135
  | 'undo' | 'redo' | 'heading' | 'fontsize'
136
136
  | 'bold' | 'italic' | 'underline' | 'strike'
137
137
  | 'foreColor' | 'backColor'
@@ -141,6 +141,112 @@ export type ToolbarItem =
141
141
  | 'source' | 'preview' | 'fullscreen'
142
142
  | '|' | ':tail'
143
143
 
144
+ /** 工具栏项:内置名称、分隔符 `|`、`:tail`,或 customButtons 里定义的自定义按钮 name */
145
+ export type ToolbarItem = BuiltinToolbarItem | (string & {})
146
+
147
+ /* ------------------------------ 自定义工具栏按钮 ------------------------------ */
148
+
149
+ /** 下拉选项;也接受纯字符串或接口原始对象(自动识别 value/id/key、label/name/title 等常见字段) */
150
+ export interface CustomButtonOption {
151
+ value?: string | number
152
+ label?: string
153
+ /** 副标题说明 */
154
+ desc?: string
155
+ /** 该项自带的跳转地址(link:true 时直接使用) */
156
+ url?: string
157
+ /** 分组名,同组选项会归到一个小标题下 */
158
+ group?: string
159
+ /** 选中后直接插入的 HTML(insert:'html' 或 auto 且无链接时使用) */
160
+ html?: string
161
+ disabled?: boolean
162
+ [key: string]: unknown
163
+ }
164
+
165
+ /** 选中后的跳转链接配置;字符串模板支持 {value} {label} 及选项任意字段占位符 */
166
+ export type CustomButtonLink =
167
+ | boolean
168
+ | string
169
+ | {
170
+ /** insert = 插入到正文(默认);open = 直接新窗口打开 */
171
+ mode?: 'insert' | 'open'
172
+ url?: string | ((item: CustomButtonOption, editor: KEditor) => string)
173
+ text?: string | ((item: CustomButtonOption, editor: KEditor) => string)
174
+ title?: string | ((item: CustomButtonOption, editor: KEditor) => string)
175
+ target?: '_blank' | '_self' | boolean
176
+ }
177
+ | ((item: CustomButtonOption, editor: KEditor) => string | { mode?: 'insert' | 'open'; url?: string; text?: string; target?: '_blank' | '_self' } | null)
178
+
179
+ export interface CustomButtonFetchOptions {
180
+ method?: string
181
+ headers?: Record<string, string>
182
+ body?: BodyInit | null
183
+ credentials?: RequestCredentials
184
+ /** 超时毫秒,默认 10000 */
185
+ timeout?: number
186
+ /** 自定义 fetch 实现(如 axios 包装) */
187
+ fetch?: typeof fetch
188
+ /** 自定义响应解析,默认 res.json() */
189
+ parser?: (res: Response) => unknown | Promise<unknown>
190
+ }
191
+
192
+ export interface CustomButtonSpec {
193
+ /** 唯一标识,用于在 toolbar 数组中定位;也作为事件载荷的 name */
194
+ name: string
195
+ /** select = 下拉选择(默认);button = 普通按钮 */
196
+ type?: 'select' | 'button'
197
+ /** tooltip */
198
+ title?: string
199
+ /** 按钮文字;下拉按钮选中后会替换为选项文字 */
200
+ text?: string
201
+ /** 未选中时的占位文字,默认取 text */
202
+ placeholder?: string
203
+ /** 内置图标名或原始 SVG 字符串 */
204
+ icon?: string
205
+ /** 面板宽度 px(200–420) */
206
+ width?: number
207
+ /** 面板内显示搜索框(客户端过滤) */
208
+ searchable?: boolean
209
+ /** 面板右上角提示文字 */
210
+ note?: string
211
+ /** 空数据提示 */
212
+ emptyText?: string
213
+ /** 缓存接口结果,默认 true;面板内刷新按钮可强制重新请求 */
214
+ cache?: boolean
215
+ /** 记住选中项并在按钮上回显,默认 true */
216
+ keepValue?: boolean
217
+
218
+ /** 数据源①:静态配置 */
219
+ options?: CustomButtonOption[] | string[]
220
+ /** 数据源②:自定义加载函数(可返回 Promise) */
221
+ load?: (editor: KEditor) => CustomButtonOption[] | Promise<CustomButtonOption[] | unknown> | unknown
222
+ /** 数据源③:接口地址,内部 fetch;优先级 load > url > options */
223
+ url?: string
224
+ fetchOptions?: CustomButtonFetchOptions
225
+ /** 从接口响应中提取数组;默认自动识别 items/list/data/rows/records/result(含一层嵌套) */
226
+ pick?: (payload: unknown, editor: KEditor) => unknown
227
+
228
+ /** 选中后的跳转链接配置 */
229
+ link?: CustomButtonLink
230
+ /** 插入方式:auto(默认,链接 > html > 纯文本)| link | html | text | false(不改正文) */
231
+ insert?: 'auto' | 'link' | 'html' | 'text' | false | 'none'
232
+ /** 自定义选中处理;返回 false 表示已自行处理,跳过默认插入 */
233
+ onSelect?: (item: CustomButtonOption, ctx: {
234
+ editor: KEditor
235
+ item: CustomButtonOption
236
+ link: { mode: 'insert' | 'open'; url: string; text: string; target: '_blank' | '_self'; title: string } | null
237
+ insertLink: (override?: Record<string, unknown>) => void
238
+ insertHtml: (html: string) => void
239
+ insertText: (text: string) => void
240
+ open: (url?: string, target?: string) => void
241
+ }) => void | boolean | Promise<void | boolean>
242
+ /** type:'button' 的点击处理 */
243
+ onClick?: (ctx: { editor: KEditor; name: string }) => void | Promise<void>
244
+ /** 高亮条件 */
245
+ active?: (state: EditorState, editor: KEditor) => boolean
246
+ /** 可用条件 */
247
+ enabled?: (state: EditorState, editor: KEditor) => boolean
248
+ }
249
+
144
250
  export interface KEditorOptions {
145
251
  value?: string
146
252
  placeholder?: string
@@ -151,8 +257,10 @@ export interface KEditorOptions {
151
257
  primaryColor?: string
152
258
  /** 正文版心宽度,默认 677(公众号) */
153
259
  paperWidth?: number
154
- /** 工具栏配置;false 隐藏 */
260
+ /** 工具栏配置;false 隐藏。留空且配置了 customButtons 时,自定义按钮自动追加到默认工具栏 */
155
261
  toolbar?: ToolbarItem[] | boolean
262
+ /** 自定义工具栏按钮(下拉选择,数据可静态配置或从接口读取) */
263
+ customButtons?: CustomButtonSpec[]
156
264
  hideToolbar?: boolean
157
265
  hideStatusbar?: boolean
158
266
  readOnly?: boolean
@@ -223,6 +331,8 @@ export interface EditorEventMap {
223
331
  uploadcancel: [{ file: File; kind: 'image' | 'video' }]
224
332
  insertmedia: [{ kind: 'image' | 'video'; url: string; node: HTMLElement }]
225
333
  sourcechange: [{ mode: 'source' | 'visual' }]
334
+ customselect: [{ name: string; item: CustomButtonOption; link: { mode: 'insert' | 'open'; url: string; text: string; target: string; title: string } | null; action: 'link' | 'html' | 'text' | 'open' | 'none'; editor: KEditor }]
335
+ customclick: [{ name: string; editor: KEditor }]
226
336
  }
227
337
 
228
338
  /* ------------------------------ 实例 ------------------------------ */
@@ -268,7 +378,18 @@ export declare class KEditor {
268
378
  tasks: Map<string, unknown>
269
379
  }
270
380
  readonly uploader: ChunkUploader
271
- readonly toolbar: { el: HTMLElement; buttons: Map<string, HTMLElement>; openLink(): void; openMedia(kind: 'image' | 'video'): void; openTable(): void }
381
+ readonly toolbar: {
382
+ el: HTMLElement
383
+ buttons: Map<string, HTMLElement>
384
+ custom: Map<string, { spec: CustomButtonSpec; button: HTMLElement | null }>
385
+ openLink(): void
386
+ openMedia(kind: 'image' | 'video'): void
387
+ openTable(): void
388
+ openCustom(name: string): void
389
+ addButton(spec: CustomButtonSpec, options?: { at?: number }): HTMLElement | null
390
+ removeButton(name: string): boolean
391
+ setButtonOptions(name: string, items: unknown): CustomButtonOption[]
392
+ }
272
393
  readonly popover: { el: HTMLElement; open: (...args: unknown[]) => void; close(): void; isOpen: boolean }
273
394
  readonly bubble: { el: HTMLElement; show(node: HTMLElement): void; hide(): void }
274
395
  readonly source: { el: HTMLElement; show(html: string): void; apply(opts?: { silent?: boolean }): void }
@@ -306,6 +427,15 @@ export declare class KEditor {
306
427
  insertVideo(url: string, label?: string): HTMLElement
307
428
  cancelUploads(): this
308
429
 
430
+ /** 运行时新增自定义按钮,返回按钮 DOM */
431
+ addButton(spec: CustomButtonSpec, options?: { at?: number }): HTMLElement | null
432
+ removeButton(name: string): boolean
433
+ /** 外部灌入下拉数据(接口在编辑器之外请求时使用) */
434
+ setButtonOptions(name: string, items: CustomButtonOption[] | string[]): CustomButtonOption[]
435
+ getButtonValue(name: string): CustomButtonOption | null
436
+ setButtonValue(name: string, value: string | number): CustomButtonOption | null
437
+ reportError(type: string, error: unknown): this
438
+
309
439
  toggleSource(): boolean
310
440
  enterSource(): void
311
441
  exitSource(): void
@@ -331,6 +461,8 @@ export declare const mount: typeof create
331
461
  export declare function replace(target: HTMLElement | string, options?: KEditorOptions): KEditor
332
462
  export declare const defaults: KEditorOptions
333
463
  export declare const DEFAULT_TOOLBAR: ToolbarItem[]
464
+ export declare function normalizeCustomButtons(list: unknown): CustomButtonSpec[]
465
+ export declare function normalizeItems(raw: unknown): CustomButtonOption[]
334
466
  export declare function exportHtml(html: string): string
335
467
 
336
468
  export declare function sanitizeHtml(html: string, opts?: { allowVideoCard?: boolean }): string