kyle-editor 1.0.1 → 1.0.3
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 +180 -22
- package/dist/keditor.cjs +993 -221
- package/dist/keditor.es.js +993 -221
- package/dist/keditor.umd.js +993 -221
- package/package.json +3 -5
- package/types/index.d.ts +182 -5
package/README.md
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
轻量、美观的**微信公众号风格富文本编辑器**。纯前端实现,无任何后端依赖:图片/视频走**分片上传**(并发、重试、取消、秒传、断点续传),随时切换 **HTML 源码模式**查看或改写产物。支持 `<script>` 直接引入与 Vue 3 安装集成。
|
|
4
4
|
|
|
5
|
-
- 体积:`dist/keditor.umd.js` 约
|
|
6
|
-
- 版式:677px 正文版心、17px/1.75
|
|
5
|
+
- 体积:`dist/keditor.umd.js` 约 209 KB(gzip 55 KB),零运行时依赖,样式随 JS 注入
|
|
6
|
+
- 版式:677px 正文版心、17px/1.75 行距,与公众号观感一致;**宽屏下版心自动生长**,两侧留白恒定,不会留出一大块空白
|
|
7
7
|
- 安全:标签/属性白名单净化,拦截 `on*`、`javascript:`、`script/iframe`
|
|
8
8
|
|
|
9
9
|
## 功能
|
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
| 媒体 | 图片/视频**本地上传**(点击、拖拽、粘贴截图)或**直接填网络链接**插入(自动校验可访问性);分片进度与速度、取消、失败重试、多图多选、大图自动压缩、双击看原图、气泡工具条(对齐/宽度/圆角/替换/删除)、**选中图片后拖拽右下角把手实时缩放** |
|
|
15
15
|
| 上传 | `chunkSize / concurrency / retries / fingerprint` 可配;内置 mock、http、simple 适配器,也可自定义 `init/put/complete` |
|
|
16
16
|
| 源码 | 工具栏右侧常驻「源码」按钮(`⌘/Ctrl+Shift+K`),进入后正文按钮置灰;格式化缩进、复制、直接编辑并应用(回填自动净化) |
|
|
17
|
-
| 其他 |
|
|
17
|
+
| 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽,API 与可选项)、全屏编辑、撤销重做(保留光标位置)、只读、**宽屏版心自适应**(两侧留白恒定,不随屏宽放大)、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「源码/全屏」固定右端 |
|
|
18
|
+
| **自定义按钮** | `customButtons` 往工具栏加**下拉选择**按钮:数据可**静态配置**或**从接口读取**(`url` / `load`),选中后按配置**插入跳转链接**或直接打开;面板支持搜索、分组、加载/失败重试/空态、缓存与强制刷新;`position` 可把它放到**工具栏任意位置**(含右侧吸附尾栏);也可运行时 `addButton` / `moveButton` / `removeButton` / `setButtonOptions` |
|
|
18
19
|
|
|
19
20
|
## 安装
|
|
20
21
|
|
|
@@ -92,6 +93,182 @@ const onUpload = (payload) => console.log(payload.stage, payload.percent)
|
|
|
92
93
|
>
|
|
93
94
|
> ESM / Webpack / Vite / React 用法见 [docs/integration.md](docs/integration.md)。
|
|
94
95
|
|
|
96
|
+
## 自定义工具栏按钮(下拉选择)
|
|
97
|
+
|
|
98
|
+
不想改源码就能往工具栏加业务按钮。典型场景:插入公司模板、关联栏目、跳转后台页面。
|
|
99
|
+
|
|
100
|
+
```js
|
|
101
|
+
const editor = KEditor.create('#editor', {
|
|
102
|
+
customButtons: [
|
|
103
|
+
// ① 数据从接口读取
|
|
104
|
+
{
|
|
105
|
+
name: 'column',
|
|
106
|
+
text: '栏目',
|
|
107
|
+
title: '插入栏目链接',
|
|
108
|
+
searchable: true, // 面板内搜索
|
|
109
|
+
url: '/api/columns', // 内部 fetch;自动识别 items/list/data/rows/records 结构
|
|
110
|
+
link: true, // 直接用每项自带的地址(url / href / link 字段)
|
|
111
|
+
insert: 'link',
|
|
112
|
+
},
|
|
113
|
+
// ② 数据静态配置
|
|
114
|
+
{
|
|
115
|
+
name: 'tpl',
|
|
116
|
+
text: '模板',
|
|
117
|
+
title: '插入模板',
|
|
118
|
+
options: [
|
|
119
|
+
{ value: 'opening', label: '开场白', desc: '问候 + 本期导读', group: '通用' },
|
|
120
|
+
{ value: 'ending', label: '结束语', desc: '引导关注与转发', group: '通用' },
|
|
121
|
+
],
|
|
122
|
+
// 链接模板:{value} / {label} 以及选项任意字段都可作占位符
|
|
123
|
+
link: { url: 'https://mp.weixin.qq.com/s/tpl-{value}', text: '【{label}】', target: '_blank' },
|
|
124
|
+
},
|
|
125
|
+
],
|
|
126
|
+
})
|
|
127
|
+
|
|
128
|
+
editor.on('customselect', ({ name, item, link, action }) => {
|
|
129
|
+
console.log(name, item.label, '→', link?.url, '(插入方式:' + action + ')')
|
|
130
|
+
})
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
> 没传 `toolbar` 时,自定义按钮会**自动追加**到默认工具栏末尾;传了 `toolbar` 数组则按名字定位:`toolbar: ['bold', '|', 'tpl', 'column']`。
|
|
134
|
+
> 想换位置?写 `position`(见下)即可,不需要重抄整份工具栏。
|
|
135
|
+
|
|
136
|
+
### 按钮位置(可放在工具栏任意位置)
|
|
137
|
+
|
|
138
|
+
```js
|
|
139
|
+
customButtons: [
|
|
140
|
+
{ name: 'tpl', text: '模板', position: 'start' }, // 工具栏最前
|
|
141
|
+
{ name: 'column', text: '栏目', position: { after: 'link' } }, // 紧跟「链接」之后
|
|
142
|
+
{ name: 'emoji', text: '表情', position: { before: 'image' } }, // 插在「图片」之前
|
|
143
|
+
{ name: 'ad', text: '头图', position: 2 }, // 第 3 个按钮之前(0 起)
|
|
144
|
+
{ name: 'stats', text: '数据', position: 'tail' }, // 右侧吸附尾栏(与源码/全屏同区)
|
|
145
|
+
{ name: 'draft', text: '草稿' }, // 缺省:主区末尾(尾栏之前)
|
|
146
|
+
]
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| `position` 写法 | 含义 |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| `'start'` | 工具栏第一位 |
|
|
152
|
+
| `'end'` / 不写 | 主区末尾、右侧吸附尾栏之前 |
|
|
153
|
+
| `'tail'` | 右侧吸附尾栏末尾(无尾栏时回退主区末尾) |
|
|
154
|
+
| `number` | 第 n 个按钮之前(按视觉顺序,分隔符不计数) |
|
|
155
|
+
| `'link'` 等按钮名 | 插到该按钮之前 |
|
|
156
|
+
| `{ before: name }` / `{ after: name }` | 显式锚点;`name` 可以是内置按钮,也可以是另一个自定义按钮 |
|
|
157
|
+
|
|
158
|
+
- 错到不存在的锚点 → 自动回退主区末尾,不报错、不丢按钮。
|
|
159
|
+
- `toolbar` 数组里**已经写过**的自定义按钮名字以数组位置为准(`position` 被忽略),所以两种方式可以混用。
|
|
160
|
+
- 运行时移位(内置按钮也能移):
|
|
161
|
+
|
|
162
|
+
```js
|
|
163
|
+
editor.moveButton('column', 'tail') // 移到右侧尾栏
|
|
164
|
+
editor.moveButton('tpl', { after: 'image' }) // 插到图片按钮之后
|
|
165
|
+
editor.moveButton('hr', 0) // 移到第一位
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### 数据源(优先级 `load` > `url` > `options`)
|
|
169
|
+
|
|
170
|
+
```js
|
|
171
|
+
// 方式 A:静态数组(也支持纯字符串、或接口原始对象,字段自动归一)
|
|
172
|
+
{ options: [{ value: 'a', label: '选项 A', desc: '说明', url: 'https://x.com/a' }] }
|
|
173
|
+
{ options: ['选项 A', '选项 B'] }
|
|
174
|
+
|
|
175
|
+
// 方式 B:自定义函数(可异步,能用编辑器实例与闭包里的 axios / 鉴权头)
|
|
176
|
+
{ load: async () => (await fetch('/api/tags').then((r) => r.json())).map((t) => ({ value: t.id, label: t.name })) }
|
|
177
|
+
|
|
178
|
+
// 方式 C:直接给接口地址
|
|
179
|
+
{
|
|
180
|
+
url: '/api/columns',
|
|
181
|
+
fetchOptions: { method: 'POST', headers: { Authorization: 'Bearer x' }, body: '{}', timeout: 8000 },
|
|
182
|
+
pick: (json) => json.result.records, // 结构特殊时手动提取数组
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
- **缓存**:默认只请求一次,面板右上角的刷新按钮可强制重新拉取;`cache: false` 则每次打开都请求
|
|
187
|
+
- **加载态**:面板自动显示 spinner + 骨架屏;**失败**时显示错误文案与「重试」按钮;**空数据**可用 `emptyText` 自定义提示
|
|
188
|
+
- **在编辑器外部拿数据**(Vue / React 里自己请求):`editor.setButtonOptions('column', list)`
|
|
189
|
+
|
|
190
|
+
### 跳转链接配置
|
|
191
|
+
|
|
192
|
+
```js
|
|
193
|
+
{ link: true } // 用每项自带地址
|
|
194
|
+
{ link: 'https://x.com/{value}' } // 地址模板
|
|
195
|
+
{ link: { url: '...', text: '【{label}】', target: '_blank' } }
|
|
196
|
+
{ link: { mode: 'open', url: 'https://x.com/{value}' } } // 不写正文,直接新窗口打开
|
|
197
|
+
{ link: (item) => ({ url: item.raw.href, text: item.label }) } // 完全动态
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
- `mode: 'insert'`(默认)在光标处插入 `<a>`,`target: '_blank'` 时自动带 `rel="noopener noreferrer"`
|
|
201
|
+
- `mode: 'open'` 直接 `window.open(url, '_blank', 'noopener,noreferrer')`,不改动正文
|
|
202
|
+
- **安全**:地址经白名单校验,`javascript:` / `vbscript:` / `data:` 等一律不会变成链接
|
|
203
|
+
|
|
204
|
+
### 接管选中行为
|
|
205
|
+
|
|
206
|
+
```js
|
|
207
|
+
{
|
|
208
|
+
name: 'tpl',
|
|
209
|
+
options: [/* ... */],
|
|
210
|
+
link: 'https://x.com/{value}',
|
|
211
|
+
insert: 'link', // 'auto'(默认) | 'link' | 'html' | 'text' | false
|
|
212
|
+
onSelect: (item, ctx) => {
|
|
213
|
+
analytics.track('insert_tpl', item.value) // 埋点,不阻断默认插入
|
|
214
|
+
},
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
// 完全自己处理:返回 false 则不改正文
|
|
218
|
+
{ onSelect: (item, ctx) => { ctx.insertHtml(item.raw.html); return false } }
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### 运行时增删
|
|
222
|
+
|
|
223
|
+
```js
|
|
224
|
+
editor.addButton({ name: 'season', text: '节气', options: [...], link: 'https://x.com/{value}' })
|
|
225
|
+
editor.addButton(spec, { at: 0 }) // 第 1 个按钮之前
|
|
226
|
+
editor.addButton(spec, { at: 'tail' }) // 右侧吸附尾栏
|
|
227
|
+
editor.addButton(spec, { before: 'image' }) // 或 { after: 'link' } / { position: 'start' }
|
|
228
|
+
editor.moveButton('season', { after: 'link' }) // 移位(内置按钮同样可用)
|
|
229
|
+
editor.removeButton('season') // 移除并中断未完成的接口请求(附带清掉随行分隔符)
|
|
230
|
+
editor.setButtonOptions('season', list) // 外部灌入数据
|
|
231
|
+
editor.getButtonValue('column') // 读当前选中项
|
|
232
|
+
editor.setButtonValue('column', 'tech') // 设置选中项(按钮文案同步)
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### 普通按钮(非下拉)
|
|
236
|
+
|
|
237
|
+
```js
|
|
238
|
+
{ name: 'date', type: 'button', text: '插入日期', icon: 'plus', onClick: ({ editor }) => editor.commands.insertHTML('<p>2026-10-13</p>') }
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
## 版心宽度与宽屏适配
|
|
242
|
+
|
|
243
|
+
宽屏下如果版心固定 677px,编辑器两侧会出现大片空白。默认采用 **fluid 版心**:版心不小于 `paperWidth`,宽屏时随容器生长,两侧留白恒定为 `paperGap`(不再随屏宽放大)。
|
|
244
|
+
|
|
245
|
+
```js
|
|
246
|
+
KEditor.create('#editor', {
|
|
247
|
+
paperWidth: 677, // 版心基准宽(公众号);fluid 模式下它是最小宽度
|
|
248
|
+
paperMode: 'fluid', // 'fluid'(默认)| 'fixed'(恒定 paperWidth + 64)
|
|
249
|
+
paperGap: 24, // fluid 模式下单侧留白
|
|
250
|
+
paperMaxWidth: 0, // fluid 模式下的版心上限,0 = 不限
|
|
251
|
+
})
|
|
252
|
+
|
|
253
|
+
// 运行时调整(侧栏折叠、布局变化时)
|
|
254
|
+
editor.setPaper({ mode: 'fixed' })
|
|
255
|
+
editor.setPaper({ gap: 40, maxWidth: 1000 })
|
|
256
|
+
editor.paperOptions() // { width, mode, gap, maxWidth }
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
| 需求 | 配置 |
|
|
260
|
+
| --- | --- |
|
|
261
|
+
| 永远像公众号那样居中一栏 | `paperMode: 'fixed'` |
|
|
262
|
+
| 宽屏也想多写点字 | 默认 fluid(不限上限) |
|
|
263
|
+
| 宽屏但可读性优先 | fluid + `paperMaxWidth: 1000` |
|
|
264
|
+
|
|
265
|
+
> **预览按钮变更**:`preview` 已从默认工具栏移除(常驻尾栏只剩「源码 / 全屏」),预览能力不变:`editor.openPreview()` / `closePreview()` / `togglePreview()`。需要按钮时把它写回工具栏:
|
|
266
|
+
>
|
|
267
|
+
> ```js
|
|
268
|
+
> toolbar: [...KEditor.DEFAULT_TOOLBAR.slice(0, -1), 'preview', 'fullscreen']
|
|
269
|
+
> // 或直接指定尾栏:toolbar: ['bold', '|', ':tail', 'source', 'preview', 'fullscreen']
|
|
270
|
+
> ```
|
|
271
|
+
|
|
95
272
|
## 本地运行
|
|
96
273
|
|
|
97
274
|
```bash
|
|
@@ -100,14 +277,6 @@ npm run build # 产出 dist/(es + cjs + umd,含 Vue 版本)
|
|
|
100
277
|
npm run dev # 静态服务 http://127.0.0.1:5178
|
|
101
278
|
```
|
|
102
279
|
|
|
103
|
-
打开:
|
|
104
|
-
|
|
105
|
-
- `index.html` — 说明首页
|
|
106
|
-
- `demo/script.html` — UMD 引入 + 分片日志面板
|
|
107
|
-
- `demo/esm.html` — 自定义上传适配器演示
|
|
108
|
-
- `demo/vue.html` — Vue 3 组件 + `v-model`
|
|
109
|
-
- `test/smoke.html` — 40 条内置冒烟用例(可视化结果)
|
|
110
|
-
|
|
111
280
|
## 验证
|
|
112
281
|
|
|
113
282
|
```bash
|
|
@@ -115,17 +284,6 @@ npm run build
|
|
|
115
284
|
npm run dev & # 启动静态服务
|
|
116
285
|
```
|
|
117
286
|
|
|
118
|
-
当前状态:`40/40` 用例通过,demo 页面无控制台报错。
|
|
119
|
-
|
|
120
|
-
## 文档
|
|
121
|
-
|
|
122
|
-
| 文档 | 内容 |
|
|
123
|
-
|------|------|
|
|
124
|
-
| [docs/integration.md](docs/integration.md) | Script / ESM / Vue3 / React / Nuxt 集成,常见问题 |
|
|
125
|
-
| [docs/api.md](docs/api.md) | 全部配置项、实例方法与事件、工具栏自定义 |
|
|
126
|
-
| [docs/upload-adapter.md](docs/upload-adapter.md) | 分片上传流程、后端接口约定、自定义适配器 |
|
|
127
|
-
|
|
128
|
-
|
|
129
287
|
## 已知限制
|
|
130
288
|
|
|
131
289
|
- 依赖浏览器 `contenteditable` + `document.execCommand`(主流浏览器均支持,Chrome/Safari/Edge/Firefox 已验证);不兼容 IE。
|