@easyx/editor 1.1.0 → 1.1.1

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.
Files changed (2) hide show
  1. package/README.md +156 -0
  2. package/package.json +2 -1
package/README.md ADDED
@@ -0,0 +1,156 @@
1
+ # @easyx/editor
2
+
3
+ 零框架依赖的 Tiptap 富文本编辑器工具包,提供开箱即用的工具栏、气泡菜单、媒体上传、表格增强与主题体系,不依赖 React / Vue 等任何 UI 框架。
4
+
5
+ ## 特性
6
+
7
+ - **零框架依赖**:工具栏、气泡菜单、媒体浮层均以纯 DOM 构建,可接入任意技术栈
8
+ - **开箱即用**:内置文本样式、对齐缩进、上下标、任务列表、分割线等常用能力
9
+ - **表格增强**:集成 [`@easyx/tiptap-table-plus`](https://www.npmjs.com/package/@easyx/tiptap-table-plus),支持单元格样式、选区覆盖层、上下文菜单、块级背景色
10
+ - **媒体支持**:图片(对齐 / 拖拽缩放 / 替代文本)、视频(对齐 / 封面 / 控制器 / 自动播放)、音频、附件
11
+ - **粘贴 / 拖拽上传**:按文件类型自动路由到对应媒体的 `upload` 回调
12
+ - **高度模式**:定高、最大高度、右下角拖拽调高
13
+ - **亮 / 暗主题**:通过 CSS 变量控制,可被外部覆盖
14
+
15
+ ## 安装
16
+
17
+ ```bash
18
+ pnpm add @easyx/editor
19
+ ```
20
+
21
+ 样式已内联进 JS 产物,**无需单独引入 CSS**。
22
+
23
+ ## 快速上手
24
+
25
+ ```ts
26
+ import { createEditor } from '@easyx/editor'
27
+
28
+ const container = document.querySelector<HTMLElement>('#editor')!
29
+
30
+ const editor = createEditor(container, {
31
+ placeholder: '请输入…',
32
+ defaultTheme: 'light',
33
+ height: 320,
34
+ minHeight: 200,
35
+ maxHeight: 480,
36
+ resizable: true,
37
+ image: {
38
+ upload: async (file) => ({
39
+ id: '1',
40
+ url: URL.createObjectURL(file),
41
+ name: file.name,
42
+ }),
43
+ },
44
+ onChange: (html) => console.log(html),
45
+ })
46
+ ```
47
+
48
+ ## 配置
49
+
50
+ `createEditor(container, options)` 的第二个参数为 `EasyxEditorOptions`:
51
+
52
+ | 选项 | 类型 | 默认值 | 说明 |
53
+ |------|------|--------|------|
54
+ | `placeholder` | `string` | `'输入内容…'` | 空内容占位符 |
55
+ | `readOnly` | `boolean` | `false` | 只读模式 |
56
+ | `autoFocus` | `boolean` | `false` | 创建后自动聚焦 |
57
+ | `defaultContent` | `string` | — | 初始内容(HTML) |
58
+ | `defaultTheme` | `'light' \| 'dark'` | `'light'` | 初始主题 |
59
+ | `image` | `ImageMediaUploadConfig` | — | 图片上传 / 缩放配置 |
60
+ | `video` | `MediaUploadConfig` | — | 视频上传 / 媒体库配置 |
61
+ | `audio` | `MediaUploadConfig` | — | 音频上传 / 媒体库配置 |
62
+ | `attachment` | `MediaUploadConfig` | — | 附件上传 / 媒体库配置 |
63
+ | `minHeight` | `number \| string` | — | 最小高度(number 视为 px) |
64
+ | `height` | `number \| 'auto' \| string` | `'auto'` | 定高并内部滚动;`'auto'` 随内容伸缩 |
65
+ | `maxHeight` | `number \| string` | — | 最大高度,内容撑到上限后内部滚动 |
66
+ | `resizable` | `boolean` | `false` | 右下角拖拽手柄调高 |
67
+ | `onChange` | `(html: string) => void` | — | 内容变更回调 |
68
+ | `onReady` | `() => void` | — | 初始化完成回调 |
69
+ | `onFocus` | `() => void` | — | 聚焦回调 |
70
+ | `onBlur` | `() => void` | — | 失焦回调 |
71
+ | `onDestroy` | `() => void` | — | 销毁回调 |
72
+
73
+ ## 实例方法
74
+
75
+ `createEditor` 返回一个编辑器实例:
76
+
77
+ | 方法 | 说明 |
78
+ |------|------|
79
+ | `isEmpty()` | 编辑器是否为空 |
80
+ | `getHTML()` / `setHTML(html)` | 读写 HTML 内容 |
81
+ | `getJSON()` / `setJSON(json)` | 读写 JSON 内容 |
82
+ | `getText()` | 获取纯文本 |
83
+ | `clear()` | 清空内容 |
84
+ | `setTheme('light' \| 'dark')` | 切换主题(同步表格组件主题) |
85
+ | `focus()` / `blur()` / `isFocused()` | 焦点管理 |
86
+ | `disable()` / `enable()` / `isDisabled()` | 禁用 / 启用编辑器 |
87
+ | `getContainer()` | 获取挂载 DOM 元素 |
88
+ | `destroy()` | 销毁编辑器,清理 DOM 与事件监听 |
89
+ | `on(event, handler)` / `off(event, handler)` | 事件监听 |
90
+ | `once(event, handler)` | 一次性事件监听 |
91
+ | `emit(event, ...args)` | 触发自定义事件 |
92
+
93
+ 各内容读写方法均以 `ContentType = string` / JSON 作为输入输出。
94
+
95
+ ## 事件
96
+
97
+ | 事件 | 触发时机 | 参数 |
98
+ |------|----------|------|
99
+ | `ready` | 编辑器初始化完成 | 无 |
100
+ | `change` | 内容变更 | `html: string` |
101
+ | `focus` | 获得焦点 | 无 |
102
+ | `blur` | 失去焦点 | 无 |
103
+ | `destroy` | 销毁 | 无 |
104
+ | `uploadError` | 粘贴 / 拖入上传失败 | `file: File, error: unknown` |
105
+
106
+ ```ts
107
+ editor.on('change', (html) => console.log(html))
108
+ editor.on('uploadError', (file, error) => console.error(file.name, error))
109
+ ```
110
+
111
+ ## 媒体上传配置
112
+
113
+ `image` / `video` / `audio` / `attachment` 均接受 `MediaUploadConfig`:
114
+
115
+ ```ts
116
+ interface MediaUploadConfig {
117
+ /** 上传单个文件,返回媒体项 */
118
+ upload: (
119
+ file: File,
120
+ onProgress?: (progress: number) => void,
121
+ ) => Promise<MediaItem>
122
+ /** 媒体库分页列表(可选),提供后媒体下拉会出现「媒体库」Tab */
123
+ getList?: (params: MediaListParams) => Promise<MediaListResult>
124
+ }
125
+
126
+ interface MediaItem {
127
+ id: string
128
+ url: string
129
+ name: string
130
+ size?: number
131
+ thumbnailUrl?: string
132
+ duration?: number
133
+ fileType?: string
134
+ }
135
+ ```
136
+
137
+ `image` 额外支持 `resizable`(默认 `true`),关闭后图片不做拖拽缩放:
138
+
139
+ ```ts
140
+ image: {
141
+ resizable: false, // 关闭图片拖拽缩放
142
+ upload: async (file) => ({ id: '1', url: '...', name: file.name }),
143
+ }
144
+ ```
145
+
146
+ ## 主题
147
+
148
+ 通过 `setTheme()` 在运行时切换亮 / 暗主题,编辑器自动在容器上添加 / 移除 `easyx-editor-dark` 类,并同步表格组件主题。所有颜色均由 CSS 变量控制,可在外部覆盖。
149
+
150
+ ```ts
151
+ editor.setTheme('dark')
152
+ ```
153
+
154
+ ## 许可
155
+
156
+ MIT
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "@easyx/editor",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
+ "description": "零框架依赖的 Tiptap 富文本编辑器,内置工具栏、气泡菜单、媒体上传与表格增强",
4
5
  "type": "module",
5
6
  "exports": {
6
7
  ".": {