kyle-editor 1.0.6 → 1.0.8

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 CHANGED
@@ -1,28 +1,21 @@
1
1
  # KEditor
2
2
 
3
- 轻量、美观的**微信公众号风格富文本编辑器**。纯前端实现,无任何后端依赖:图片/视频走**分片上传**(并发、重试、取消、秒传、断点续传),随时切换 **HTML 源码模式**查看或改写产物。支持 `<script>` 直接引入与 Vue 3 安装集成。
3
+ 轻量、美观的**微信公众号风格富文本编辑器**。纯前端实现,无任何后端依赖:图片/视频走**上传(普通整包 + 大文件分片)**(并发、重试、取消、秒传、断点续传),**代码块可选 20 种语言并语法高亮**,**一键导入 Markdown 文件/文本转成可编辑 HTML**,随时切换 **HTML 源码模式**查看或改写产物。支持 `<script>` 直接引入与 Vue 3 安装集成。
4
4
 
5
- - 体积:`dist/keditor.umd.min.js` 约 139 KB(gzip 43 KB),未压缩版 209 KB(gzip 55 KB),零运行时依赖,样式随 JS 注入
5
+ - 体积:`dist/keditor.umd.min.js` 约 192 KB(gzip 61 KB),未压缩版 300 KB(gzip 78 KB),零运行时依赖(含内置高亮器与 Markdown 转换器),样式随 JS 注入
6
6
  - 版式:677px 正文版心、17px/1.75 行距,与公众号观感一致;**宽屏下版心自动生长**,两侧留白恒定,不会留出一大块空白
7
7
  - 安全:标签/属性白名单净化,拦截 `on*`、`javascript:`、`script/iframe`
8
8
 
9
- ![img_1.png](imgs/img_1.png)
10
- ![img.png](imgs/img.png)
11
- ![img_2.png](imgs/img_2.png)
12
- ![img_3.png](imgs/img_3.png)
13
-
14
- ## 文档
15
- * [快速开始](docs/index.md)
16
-
17
9
  ## 功能
18
10
 
19
11
  | 分类 | 能力 |
20
12
  |------|------|
21
- | 排版 | 段落样式面板(正文/标题一/标题二/标题三,带真实字号预览与用途说明)、字号面板(12–32px)、字体颜色与背景高亮(主题色 + 标准色 + 最近使用 + 自定义取色)、粗斜下删、四种对齐、有序/无序列表、引用、表格(网格选择)、代码块、分割线、链接、清除格式 |
22
- | 媒体 | 图片/视频**本地上传**(点击、拖拽、粘贴截图)或**直接填网络链接**插入(自动校验可访问性);分片进度与速度、取消、失败重试、多图多选、大图自动压缩、双击看原图、气泡工具条(对齐/宽度/圆角/替换/删除)、**选中图片后拖拽右下角把手实时缩放** |
23
- | 上传 | `chunkSize / concurrency / retries / fingerprint` 可配;内置 mock、http、simple 适配器,也可自定义 `init/put/complete` |
13
+ | 排版 | 段落样式面板(正文/标题一/标题二/标题三,带真实字号预览与用途说明)、字号面板(12–32px)、字体颜色与背景高亮(主题色 + 标准色 + 最近使用 + 自定义取色)、粗斜下删、四种对齐、有序/无序列表、引用、表格(网格选择)、代码块(**20 种语言可选 + 语法高亮**)、分割线、链接、清除格式 |
14
+ | 媒体 | 图片/视频**本地上传**(点击、拖拽、粘贴截图)或**直接填网络链接**插入(自动校验可访问性);上传进度与速度、取消、失败重试、多图多选、大图自动压缩、双击看原图、气泡工具条(对齐/宽度/圆角/替换/删除)、**选中图片后拖拽右下角把手实时缩放** |
15
+ | 上传 | **普通上传与分片上传各自独立配置**:`uploader`(整个文件一次请求)+ `chunkUploader`(切片并发,只需一个接口,响应里 `url` 非空即成功);`upload.mode` 可选 `auto`(按体积自动选,默认 5MB 阀值)/ `normal` / `chunk`,`chunkSize / concurrency / retries / fingerprint` 可配;内置 mock、simple 适配器,也可自定义 `upload/put` 适配器 |
24
16
  | 源码 | 工具栏右侧常驻「源码」按钮(`⌘/Ctrl+Shift+K`),进入后正文按钮置灰;格式化缩进、复制、直接编辑并应用(回填自动净化) |
25
- | 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽,API 与可选项)、全屏编辑、撤销重做(保留光标位置)、只读、**宽屏版心自适应**(两侧留白恒定,不随屏宽放大)、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「源码/全屏」固定右端 |
17
+ | **Markdown 导入** | 尾栏「**导入MD**」按钮打开导入面板:**选文件 / 拖文件 / 粘文本**,实时预览 + 结构统计,三种落点(替换全文 / 追加文末 / 插入光标);把 `.md` 拖进正文即可转换;围栅代码块**语言保留并高亮**;未知语言、超大文件、只读、GBK 编码都有兜底 |
18
+ | 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽,API 与可选项)、全屏编辑、撤销重做(保留光标位置)、只读、**宽屏版心自适应**(两侧留白恒定,不随屏宽放大)、**内容区高度默认随内容自动撑开**(配了 `height` 才固定并内部滚动)、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「导入MD/源码/全屏」固定右端 |
26
19
  | **自定义按钮** | `customButtons` 往工具栏加**下拉选择**按钮:数据可**静态配置**或**从接口读取**(`url` / `load`),选中后按配置**插入跳转链接**或直接打开;面板支持搜索、分组、加载/失败重试/空态、缓存与强制刷新;`position` 可把它放到**工具栏任意位置**(含右侧吸附尾栏);也可运行时 `addButton` / `moveButton` / `removeButton` / `setButtonOptions` |
27
20
 
28
21
  ## 安装
@@ -55,7 +48,7 @@ npm install kyle-editor vue@^3
55
48
  <script>
56
49
  const editor = KEditor.create('#editor', {
57
50
  placeholder: '开始撰写内容,支持拖拽 / 粘贴图片与视频…',
58
- height: 460,
51
+ // 高度默认随内容自动撑开;想要固定高度 + 内部滚动就写上 height: 460
59
52
  })
60
53
  editor.on('change', ({ html }) => console.log(html))
61
54
  </script>
@@ -66,7 +59,7 @@ npm install kyle-editor vue@^3
66
59
  ```js
67
60
  import KEditor from 'kyle-editor'
68
61
 
69
- const editor = KEditor.create('#editor', { height: 460 })
62
+ const editor = KEditor.create('#editor') // 高度默认自适应内容
70
63
  ```
71
64
 
72
65
  ### 方式三:Vue 3 安装集成
@@ -89,10 +82,12 @@ import { ref } from 'vue'
89
82
 
90
83
  const form = ref({ content: '' })
91
84
  const options = {
85
+ // 不写 height 就是自适应内容高度;写了则固定高度、内容超出时编辑区内部滚动
92
86
  height: 420,
93
- // 无后端时保持默认 'mock';上线时换成下面这行即可
94
- uploader: { type: 'http', initUrl: '/api/upload/init', chunkUrl: '/api/upload/chunk', completeUrl: '/api/upload/complete' },
95
- upload: { chunkSize: 5 * 1024 * 1024, concurrency: 4 },
87
+ // 无后端时保持默认 'mock';上线时换成下面两行即可
88
+ uploader: '/api/upload', // 普通上传:整个文件一次请求
89
+ chunkUploader: '/api/chunk-upload', // 分片上传:大文件自动切片(>=5MB)
90
+ upload: { mode: 'auto', chunkSize: 5 * 1024 * 1024, concurrency: 4 },
96
91
  }
97
92
  const onUpload = (payload) => console.log(payload.stage, payload.percent)
98
93
  </script>
@@ -104,6 +99,96 @@ const onUpload = (payload) => console.log(payload.stage, payload.percent)
104
99
  >
105
100
  > ESM / Webpack / Vite / React 用法见 [docs/integration.md](docs/integration.md)。
106
101
 
102
+ ## 上传配置:普通上传 / 分片上传,各自独立配置
103
+
104
+ 上传分两条链路,**互不影响**,可以只配一条,也可以都配:
105
+
106
+ | 链路 | 适用 | 行为 |
107
+ |------|------|------|
108
+ | **普通上传** `uploader` | 小文件(图片为主) | 整个文件**一次请求**发完,返回 `url` 即成功 |
109
+ | **分片上传** `chunkUploader` | 大文件(视频为主) | 切片 → 并发 → 重试,**只需一个接口**,响应里 `url` 非空即成功 |
110
+
111
+ ```js
112
+ KEditor.create('#editor', {
113
+ uploader: '/api/upload', // 普通上传(整个文件一次请求)
114
+ chunkUploader: '/api/chunk-upload', // 分片上传(切片并发)
115
+ upload: {
116
+ mode: 'auto', // 'auto' 按体积自动选(默认)| 'normal' 只走普通 | 'chunk' 只走分片
117
+ chunkThreshold: 5 * 1024 * 1024, // auto:达到该体积才走分片(默认 5MB)
118
+ chunkSize: 1024 * 1024, // 分片大小
119
+ concurrency: 4, // 并发分片数
120
+ retries: 2, // 单片失败重试次数
121
+ },
122
+ })
123
+ ```
124
+
125
+ | 你配了什么 | 实际行为 |
126
+ |------|------|
127
+ | 两条都配 | `mode: 'auto'`:小于 `chunkThreshold` 走普通,否则走分片 |
128
+ | 只配 `uploader` | **全部走普通上传**(分片不启用,不会静默用 mock) |
129
+ | 只配 `chunkUploader` | **全部走分片上传**(`mode` 默认变 `'chunk'`) |
130
+ | 两条都不配 | 默认两条都是 `'mock'`:小文件普通、大文件分片(开箱演示) |
131
+
132
+ > 只配一条链路时,另一条不会被默认 `mock` 顶上 —— 否则真实后端只接了一半,另一半会静默产生 `blob:` 假地址。
133
+
134
+ - `mode: 'chunk'` 但未配置 `chunkUploader`:控制台告警并回退为普通上传,不会静默失败。
135
+ - 想手动指定阈值/模式,显式写 `upload: { mode, chunkThreshold }` 即可(显式配置优先于上面的默认规则)。
136
+
137
+ ### 普通上传约定
138
+
139
+ 整包 `POST` 到 `uploader`,`multipart/form-data`:
140
+
141
+ | 方向 | 内容 |
142
+ |------|------|
143
+ | 请求 | `file` 整个文件(字段名可用 `fieldName` 改)、`filename`、`fileSize` |
144
+ | 响应 | `{ "url": "https://cdn/a.png" }`(也支持 `{ code: 0, data: { url } }`,用 `parse` 解开) |
145
+ | 没返回 `url` | 视为**失败**,占位块转错误态并提供「重试 / 移除」 |
146
+
147
+ > 一次请求无法拿到逐字节进度,普通上传只上报「开始 / 结束」;需要精细进度条就用分片上传。
148
+
149
+ ### 分片上传约定
150
+
151
+ **每个分片都 POST 到 `chunkUploader` 这一个地址**,**只要某个响应里返回了非空 `url`,就代表这个文件上传成功** —— 编辑器立刻用该地址替换占位块,剩余分片不再上传(服务端秒传、或收齐最后一片时返回都可以)。
152
+
153
+ | 方向 | 内容 |
154
+ |------|------|
155
+ | 请求(`multipart/form-data`) | `file` 分片二进制(字段名可用 `fieldName` 改)、`identifier` 同一文件恒定(指纹)、`index` 从 0 起、`total` 总片数、`filename`、`fileSize`、`chunkSize` |
156
+ | 响应 | `{ "url": "https://cdn/a.png" }`,也可写成 `{ code: 0, data: { url } }`(外层包装用 `parse` 解开);`key` / `poster` / `duration` 会被透传 |
157
+ | 没返回 `url` | 视为**失败**,占位块转错误态并提供「重试 / 移除」,不会静默当成功 |
158
+
159
+ ```js
160
+ // 需要鉴权、自定义字段名、自定义取地址字段时(两条链路写法相同)
161
+ KEditor.create('#editor', {
162
+ chunkUploader: {
163
+ type: 'http',
164
+ url: '/api/chunk-upload',
165
+ fieldName: 'chunk', // 默认 'file'
166
+ headers: () => ({ Authorization: `Bearer ${getToken()}` }), // 传函数则每次请求实时取值
167
+ withCredentials: true,
168
+ parse: (json) => json.data, // 默认 json.data ?? json
169
+ pickUrl: (json) => json?.payload?.filePath || '', // 地址字段不叫 url 时自定义(默认认 url / fileUrl / src)
170
+ mode: 'formdata', // 默认 formdata;可用 'raw' 走裸 body + 查询串
171
+ },
172
+ })
173
+ ```
174
+
175
+ > 分片上传现在是**单接口**:`httpAdapter` 不再接受 `initUrl` / `chunkUrl` / `completeUrl` / `abortUrl`,配了会直接报错提示迁移。
176
+ > 需要 `init` / `complete` 这类自定义流程时,自己写一个适配器(实现 `put()`,可选 `init()` / `complete()`)传给 `chunkUploader` 即可,见 [docs/upload-adapter.md](docs/upload-adapter.md)。
177
+
178
+ ### 其他写法(两条链路通用)
179
+
180
+ ```js
181
+ uploader: '/api/upload' // 字符串地址(等价于 { type:'http', url })
182
+ uploader: { type: 'http', url: '/api/upload' } // 显式写法
183
+ uploader: KEditor.httpAdapter({ url: '/api/upload' }) // 自己造适配器(交给 createSimpleUploader / createChunkUploader 装配)
184
+ uploader: KEditor.simpleAdapter(async (file) => myUpload(file)) // 函数包装:一个文件一次请求
185
+ uploader: async (file) => (await myUpload(file)).url // 直接给函数也行
186
+ uploader: 'mock' // 默认:零后端,生成 blob: 地址(仅当前会话有效)
187
+ uploader: KEditor.mockAdapter({ speed: 8 }) // mock 可调速度 / 延迟 / 失败率
188
+ ```
189
+
190
+ 进度/速度/取消/重试,以及完整适配器协议与后端实现建议见 [docs/upload-adapter.md](docs/upload-adapter.md)。
191
+
107
192
  ## 自定义工具栏按钮(下拉选择)
108
193
 
109
194
  不想改源码就能往工具栏加业务按钮。典型场景:插入公司模板、关联栏目、跳转后台页面。
@@ -152,7 +237,7 @@ customButtons: [
152
237
  { name: 'column', text: '栏目', position: { after: 'link' } }, // 紧跟「链接」之后
153
238
  { name: 'emoji', text: '表情', position: { before: 'image' } }, // 插在「图片」之前
154
239
  { name: 'ad', text: '头图', position: 2 }, // 第 3 个按钮之前(0 起)
155
- { name: 'stats', text: '数据', position: 'tail' }, // 右侧吸附尾栏(与源码/全屏同区)
240
+ { name: 'stats', text: '数据', position: 'tail' }, // 右侧吸附尾栏(与 导入MD/源码/全屏 同区)
156
241
  { name: 'draft', text: '草稿' }, // 缺省:主区末尾(尾栏之前)
157
242
  ]
158
243
  ```
@@ -249,6 +334,116 @@ editor.setButtonValue('column', 'tech') // 设置选中项(按
249
334
  { name: 'date', type: 'button', text: '插入日期', icon: 'plus', onClick: ({ editor }) => editor.commands.insertHTML('<p>2026-10-13</p>') }
250
335
  ```
251
336
 
337
+ ## 代码块(可选语言 + 语法高亮)
338
+
339
+ 工具栏「代码块」按钮点开就是一个**语言面板**(20 种内置语言,支持按名称或别名搜索,如 `js` / `mysql` / `yml`):
340
+
341
+ - 选好语言后插入代码块,光标直接落在块内,可以**边写边高亮**
342
+ - 光标已在某个代码块里时,同一个面板变成「代码块语言」,选一项即**改写当前块的语言**并重新着色
343
+ - 语言写入 `data-k-lang`(编辑器识别)与 `class="language-x"`(通用约定),块右上角显示语言角标,`plaintext` 不显示
344
+ - **高亮只是编辑/预览时的显示效果**:`getHTML()`、源码模式、复制出去的内容都是**不带 `<span>` 的干净代码**,再次导入会自动重新高亮
345
+
346
+ ```js
347
+ KEditor.create('#editor', {
348
+ code: {
349
+ languages: ['js', 'python', 'go', 'sql'], // 只留几种(主名或别名都认);不写 = 全部 20 种
350
+ defaultLanguage: 'python', // 新建代码块默认语言(不在清单内会落到第一项)
351
+ highlight: true, // false = 只保留纯文本,语言标记照写
352
+ },
353
+ })
354
+
355
+ // 运行时
356
+ editor.codeLanguages() // [{ value:'javascript', label:'JavaScript', hint:'前端与 Node 脚本' }, …]
357
+ editor.insertCode('const a = 1', 'js') // 插入代码块(语言可省,用 defaultLanguage)
358
+ editor.setCodeLanguage('sql') // 改写光标所在块的语言(返回生效语言;不在块内返回 null)
359
+ editor.getCodeLanguage() // 光标所在块的语言,不在块内返回 ''
360
+ editor.getState().inCode // 光标是否在代码块内(工具栏按钮据此高亮)
361
+ editor.highlightCode() // 手动重跑全量高亮,返回处理的块数
362
+ KEditor.highlightCode(code, 'python') // 纯函数:把源码转成带 token 的 HTML 片段(已转义)
363
+ KEditor.listLanguages() // 语言清单;normalizeLang('MySQL') === 'sql'
364
+ ```
365
+
366
+ | 内置语言 | |
367
+ | --- | --- |
368
+ | `plaintext` `javascript` `typescript` `html` `css` `json` `python` `java` `go` `rust` | `c` `csharp` `php` `ruby` `sql` `bash` `yaml` `ini` `markdown` `diff` |
369
+
370
+ 别名同样可用:`js`/`ts`/`py`/`golang`/`yml`/`sh`/`md`/`c++`/`cs`/`mysql`/`postgres`/`toml`/`patch` …
371
+
372
+ > 高亮器是内置的极简 tokenizer(零依赖,约 13 KB gzip),正则规则带长度保护:**单块超过 60 KB 的代码按纯文本处理**,避免长文档卡顿。样式沿用 One Dark 配色,作用域限定在 `.ke-content` 内,不会影响宿主页面。
373
+
374
+ ## 导入 Markdown(.md / 粘贴文本 → 可编辑 HTML)
375
+
376
+ 工具栏尾栏的 **导入MD** 按钮打开导入面板:选文件、拖文件,或直接粘文本,**实时预览**转换结果与结构统计,再选落点导入。把 `.md` / `.markdown` / `.txt` 文件**拖进正文**也能直接转换。
377
+
378
+ ```js
379
+ KEditor.create('#editor', {
380
+ markdown: {
381
+ insertMode: 'replace', // 默认落点:replace 替换全文 / append 追加文末 / cursor 插入光标
382
+ maxSize: 5 * 1024 * 1024, // 单文件上限(字节),0 = 不限制
383
+ gfm: true, // 表格 / 删除线 / 任务列表 / 裸链接
384
+ breaks: false, // true = 段落内单换行也当硬换行
385
+ linkTarget: false, // true 或 '_blank' = 外链自动加 target + rel="noopener noreferrer"
386
+ frontMatter: true, // 丢弃开头的 YAML front matter
387
+ },
388
+ })
389
+
390
+ // 运行时(source 支持 文本 / File / { name, content })
391
+ await editor.importMarkdown(mdText) // 按 options.markdown.insertMode 落点
392
+ await editor.importMarkdown(file, { mode: 'append' }) // 临时指定落点
393
+ await editor.setMarkdown(mdText) // 替换全文
394
+ await editor.insertMarkdown(mdText) // 插入光标处
395
+ await editor.appendMarkdown(mdText) // 追加到文末
396
+ editor.markdownOptions() // { insertMode:'replace', maxSize:5242880, auto:true }
397
+
398
+ // 纯函数(不依赖实例,Node 端也能用)
399
+ KEditor.markdownToHtml('# 标题\n\n正文', { gfm: true })
400
+ KEditor.markdownSummary(html) // { headings, paragraphs, lists, items, codeBlocks, quotes, tables, images, links }
401
+ KEditor.isMarkdownFile({ name: 'a.md', type: '' }) // 按 MIME + 扩展名判断
402
+ KEditor.normalizeInsertMode('append') // 非法值回落 'replace'
403
+ KEditor.MARKDOWN_ACCEPT // <input accept> 用
404
+ ```
405
+
406
+ 导入返回值 `{ ok, html, summary, mode, chars, name }`;只读模式返回 `{ ok: false, reason: 'readonly' }`,超限或读文件失败返回 `{ ok: false, reason: 'error' }`。导入成功后会触发 `markdownimport` 事件(`editor.on('markdownimport', fn)`)。
407
+
408
+ > 手边没文件?demo 里带了一份示例:`demo/assets/sample.md`(含标题 / 表格 / 任务列表 / 多语言代码块),拖进 demo 的正文就能看到完整效果。
409
+
410
+ | 支持 | 说明 |
411
+ | --- | --- |
412
+ | 标题 | `#` ~ `######` 与 setext(`===` / `---`) |
413
+ | 列表 | 有序 / 无序 / 嵌套 / 松散段落 / 任务列表(`- [x]` → ☑) |
414
+ | 表格 | GFM 表格,列对齐写入 `style="text-align:…"` |
415
+ | 代码块 | 围栅与缩进,**语言保留并高亮**(`data-k-lang` + `class="language-x"`),未知语言退化纯文本 |
416
+ | 行内 | 粗体 / 斜体 / 删除线 / 行内代码 / 转义 / 硬换行 / 引用式与自动链接 / 图片 |
417
+ | 其他 | 引用(含嵌套与懒续行)、分隔线、YAML front matter 丢弃、内联 HTML 与 HTML 块 |
418
+
419
+ > 转换产物就是编辑器正文规范里的普通 HTML(`<p>` `<h1-6>` `<ul>` `<ol>` `<table>` `<blockquote>` `<pre data-k-lang>` …),默认再过一遍白名单净化:`<script>`、`on*`、`javascript:` 等会被清掉或转义。导入是**单次快照**,之后就能用所有排版功能继续改,`getHTML()` 导出的内容可再次导入。
420
+ >
421
+ > 转换器同样是内置的零依赖实现(约 9 KB gzip),不上传任何内容到远端;单文件默认 5 MB 上限,`markdown.maxSize` 可调。
422
+
423
+ ## 内容区高度(默认自适应,配了才固定)
424
+
425
+ 不配置 `height` 时,内容区**随内容自动撑开**(整页滚动,工具栏尽量吸附在视口顶部);配置了 `height` 才固定高度,内容超出时在编辑区内部滚动。
426
+
427
+ ```js
428
+ KEditor.create('#editor', {}) // 自适应:默认行为
429
+ KEditor.create('#editor', { height: 460 }) // 固定 460px,内部滚动
430
+ KEditor.create('#editor', { minHeight: 200 }) // 只控最小高度
431
+
432
+ // 运行时切换
433
+ editor.setHeight(600) // 固定 600px
434
+ editor.setHeight(0) // 回到自适应(也接受 'auto')
435
+ editor.heightOptions() // { height: 0, auto: true }
436
+ ```
437
+
438
+ | 配置 | 效果 |
439
+ | --- | --- |
440
+ | 不写 `height` | 自适应内容高度,整页滚动;工具栏尽量吸附视口顶部 |
441
+ | `height: 460` | 固定 460px,内容超出时编辑区内部滚动 |
442
+ | `height: 0` / `'auto'` | 同「不写」,用于显式声明 |
443
+ | `minHeight: 320` | 内容区最小高度(两种模式下都生效,默认 320) |
444
+
445
+ > 自适应模式下工具栏会吸附在视口顶部(`.ke` 用 `overflow: clip` 而非 `hidden`,否则 sticky 会被自己的裁剪层拦住);但若**宿主容器**带 `overflow: hidden` 之类的裁剪,浏览器会以该容器为参照,吸附失效(工具栏随页面滚走,其余行为不变)。视觉验证页与 demo 的 `.card` 就属于后者。
446
+
252
447
  ## 版心宽度与宽屏适配
253
448
 
254
449
  宽屏下如果版心固定 677px,编辑器两侧会出现大片空白。默认采用 **fluid 版心**:版心不小于 `paperWidth`,宽屏时随容器生长,两侧留白恒定为 `paperGap`(不再随屏宽放大)。
@@ -273,7 +468,7 @@ editor.paperOptions() // { width, mode, gap, maxWidth }
273
468
  | 宽屏也想多写点字 | 默认 fluid(不限上限) |
274
469
  | 宽屏但可读性优先 | fluid + `paperMaxWidth: 1000` |
275
470
 
276
- > **预览按钮变更**:`preview` 已从默认工具栏移除(常驻尾栏只剩「源码 / 全屏」),预览能力不变:`editor.openPreview()` / `closePreview()` / `togglePreview()`。需要按钮时把它写回工具栏:
471
+ > **预览按钮变更**:`preview` 已从默认工具栏移除(常驻尾栏为「导入MD / 源码 / 全屏」),预览能力不变:`editor.openPreview()` / `closePreview()` / `togglePreview()`。需要按钮时把它写回工具栏:
277
472
  >
278
473
  > ```js
279
474
  > toolbar: [...KEditor.DEFAULT_TOOLBAR.slice(0, -1), 'preview', 'fullscreen']
@@ -293,10 +488,10 @@ npm run dev # 静态服务 http://127.0.0.1:5178
293
488
 
294
489
  | 文件 | 用途 | 体积 |
295
490
  | --- | --- | --- |
296
- | `dist/keditor.umd.min.js` | **CDN / `<script>` 默认入口**(`unpkg`、`jsdelivr` 均指向它) | 139 KB / gzip 43 KB |
297
- | `dist/keditor.umd.js` | 同上但未压缩,便于断点调试 | 209 KB / gzip 55 KB |
298
- | `dist/keditor.es.js` | ESM(`exports.import`,打包器走这个) | 199 KB |
299
- | `dist/keditor.cjs` | CommonJS(`exports.require`) | 200 KB |
491
+ | `dist/keditor.umd.min.js` | **CDN / `<script>` 默认入口**(`unpkg`、`jsdelivr` 均指向它) | 192 KB / gzip 61 KB |
492
+ | `dist/keditor.umd.js` | 同上但未压缩,便于断点调试 | 300 KB / gzip 78 KB |
493
+ | `dist/keditor.es.js` | ESM(`exports.import`,打包器走这个) | 288 KB |
494
+ | `dist/keditor.cjs` | CommonJS(`exports.require`) | 288 KB |
300
495
  | `dist/keditor-vue.{es,cjs,umd}.js` | Vue 组件/插件,外部化 `vue` 与本包 | 各约 4 KB |
301
496
 
302
497
  两份 UMD 产物由 `vite.config.core.js`(未压缩)与 `vite.config.min.js`(`minify: 'esbuild'`)从同一入口分别构建,全局变量都是 `window.KEditor`,API 完全一致。
@@ -307,21 +502,28 @@ npm run dev # 静态服务 http://127.0.0.1:5178
307
502
  npm run dev & # 先启动静态服务(测试页面走 http://127.0.0.1:5178)
308
503
 
309
504
  npm run verify # build + 冒烟(未压缩) + 冒烟(压缩) + 页面检查 + 类型 + 发布配置
310
- npm test # 171 项冒烟,跑 dist/keditor.umd.js
311
- npm run test:min # 同一套 171 项冒烟,跑 dist/keditor.umd.min.js
505
+ npm test # 324 项冒烟,跑 dist/keditor.umd.js
506
+ npm run test:min # 同一套 324 项冒烟,跑 dist/keditor.umd.min.js
312
507
  npm run test:pages # demo / 首页零控制台错误 + 真实交互探针
313
- npm run test:install # npm pack → 隔离安装 → 校验包内入口与压缩产物等价性
314
- npm run test:visual # 20 张关键状态截图(test/screenshots/)
508
+ npm run test:install # npm pack → 隔离安装(129 项:Node 26 + 浏览器 103)
509
+ npm run test:visual # 24 张关键状态截图(test/screenshots/)
315
510
  ```
316
511
 
317
512
  > `test` 与 `test:min` 复用同一个 `test/smoke.html`,靠 `?bundle=min` 切换被测产物 —— 压缩版任何行为差异都会在这里暴露;`test:install` 还会对比两份 UMD 的导出清单,防止 minify 丢导出。
513
+ >
514
+ > `test:visual` 里的 `scroll` 状态拍的是工具栏引导气泡的动画帧,本身不稳定(连续两次渲染也会不一致),不要把它当像素基准。
318
515
 
319
516
  ## 已知限制
320
517
 
321
518
  - 依赖浏览器 `contenteditable` + `document.execCommand`(主流浏览器均支持,Chrome/Safari/Edge/Firefox 已验证);不兼容 IE。
322
519
  - 表格支持插入与行列增删,未内置单元格合并;需要时可自行扩展 `commands.js`。
323
- - 默认适配器产生的 `blob:` 地址仅当前会话有效,正式环境请配置真实 `uploader`(见文档)。
520
+ - 默认适配器产生的 `blob:` 地址仅当前会话有效,正式环境请配置真实上传接口(见[上传配置](#上传配置普通上传--分片上传各自独立配置))。
324
521
  - 强指纹(`fingerprint: 'strong'`)依赖 `crypto.subtle`,需 HTTPS 或 localhost 环境。
522
+ - 代码块高亮是**编辑器/预览里的显示效果**,产物本身是纯 `<pre><code>`(不含 token span)。若把产物贴到自己的页面,请保证 `pre` 保留默认的 `white-space: pre`(本编辑器会注入,宿主页面可自行为 `.ke-content pre` 定义主题);`plaintext` 语言不做着色。
523
+ - 单个代码块超过 60 KB 时按纯文本显示(避免长文卡顿),语言标记与导出不受影响。
524
+ - Markdown 导入是 **GFM 子集**:不支持脚注、目录(TOC)、数学公式与自定义容器(callout);这些语法会按普通段落渲染。导入是**单次快照**,不会与源 `.md` 保持双向同步。
525
+ - 导入时本地相对路径的图片(`![](./img/a.png)`)只保留路径文本,不会自动上传;需要上传请先转入编辑器后替换图源。
526
+ - 文件编码先按严格 UTF-8 解码,失败回退 `gb18030` / `gbk` / `big5`;其他编码(如 UTF-16)需自行转成 UTF-8。
325
527
 
326
528
  ## License
327
529
 
@@ -8,7 +8,8 @@ const KEditorVue = {
8
8
  modelValue: { type: String, default: "" },
9
9
  options: { type: Object, default: () => ({}) },
10
10
  disabled: { type: Boolean, default: false },
11
- height: { type: Number, default: null }
11
+ // 内容区高度:不传 = 自适应内容;传 px 固定;'auto' 同不传
12
+ height: { type: [Number, String], default: null }
12
13
  },
13
14
  emits: ["update:modelValue", "ready", "change", "upload", "error", "save", "blur", "focus"],
14
15
  setup(props, { emit, expose }) {
@@ -16,7 +17,7 @@ const KEditorVue = {
16
17
  const instance = vue.shallowRef(null);
17
18
  const buildOptions = () => {
18
19
  const opts = { ...kyleEditor.defaults, ...props.options, value: props.modelValue || "" };
19
- if (props.height) opts.height = props.height;
20
+ if (props.height !== null && props.height !== "" && props.height !== void 0) opts.height = props.height;
20
21
  opts.onChange = (html) => {
21
22
  emit("update:modelValue", html);
22
23
  emit("change", html);
@@ -7,7 +7,8 @@ const KEditorVue = {
7
7
  modelValue: { type: String, default: "" },
8
8
  options: { type: Object, default: () => ({}) },
9
9
  disabled: { type: Boolean, default: false },
10
- height: { type: Number, default: null }
10
+ // 内容区高度:不传 = 自适应内容;传 px 固定;'auto' 同不传
11
+ height: { type: [Number, String], default: null }
11
12
  },
12
13
  emits: ["update:modelValue", "ready", "change", "upload", "error", "save", "blur", "focus"],
13
14
  setup(props, { emit, expose }) {
@@ -15,7 +16,7 @@ const KEditorVue = {
15
16
  const instance = shallowRef(null);
16
17
  const buildOptions = () => {
17
18
  const opts = { ...defaults, ...props.options, value: props.modelValue || "" };
18
- if (props.height) opts.height = props.height;
19
+ if (props.height !== null && props.height !== "" && props.height !== void 0) opts.height = props.height;
19
20
  opts.onChange = (html) => {
20
21
  emit("update:modelValue", html);
21
22
  emit("change", html);
@@ -8,7 +8,8 @@
8
8
  modelValue: { type: String, default: "" },
9
9
  options: { type: Object, default: () => ({}) },
10
10
  disabled: { type: Boolean, default: false },
11
- height: { type: Number, default: null }
11
+ // 内容区高度:不传 = 自适应内容;传 px 固定;'auto' 同不传
12
+ height: { type: [Number, String], default: null }
12
13
  },
13
14
  emits: ["update:modelValue", "ready", "change", "upload", "error", "save", "blur", "focus"],
14
15
  setup(props, { emit, expose }) {
@@ -16,7 +17,7 @@
16
17
  const instance = vue.shallowRef(null);
17
18
  const buildOptions = () => {
18
19
  const opts = { ...kyleEditor.defaults, ...props.options, value: props.modelValue || "" };
19
- if (props.height) opts.height = props.height;
20
+ if (props.height !== null && props.height !== "" && props.height !== void 0) opts.height = props.height;
20
21
  opts.onChange = (html) => {
21
22
  emit("update:modelValue", html);
22
23
  emit("change", html);