kyle-editor 1.0.2 → 1.0.4

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
@@ -2,10 +2,12 @@
2
2
 
3
3
  轻量、美观的**微信公众号风格富文本编辑器**。纯前端实现,无任何后端依赖:图片/视频走**分片上传**(并发、重试、取消、秒传、断点续传),随时切换 **HTML 源码模式**查看或改写产物。支持 `<script>` 直接引入与 Vue 3 安装集成。
4
4
 
5
- - 体积:`dist/keditor.umd.js` 约 202 KB(gzip 51 KB),零运行时依赖,样式随 JS 注入
6
- - 版式:677px 正文版心、17px/1.75 行距,与公众号观感一致
5
+ - 体积:`dist/keditor.umd.min.js` 约 139 KB(gzip 43 KB),未压缩版 209 KB(gzip 55 KB),零运行时依赖,样式随 JS 注入
6
+ - 版式:677px 正文版心、17px/1.75 行距,与公众号观感一致;**宽屏下版心自动生长**,两侧留白恒定,不会留出一大块空白
7
7
  - 安全:标签/属性白名单净化,拦截 `on*`、`javascript:`、`script/iframe`
8
8
 
9
+ ![img_1.png](img_1.png)
10
+
9
11
  ## 功能
10
12
 
11
13
  | 分类 | 能力 |
@@ -14,8 +16,8 @@
14
16
  | 媒体 | 图片/视频**本地上传**(点击、拖拽、粘贴截图)或**直接填网络链接**插入(自动校验可访问性);分片进度与速度、取消、失败重试、多图多选、大图自动压缩、双击看原图、气泡工具条(对齐/宽度/圆角/替换/删除)、**选中图片后拖拽右下角把手实时缩放** |
15
17
  | 上传 | `chunkSize / concurrency / retries / fingerprint` 可配;内置 mock、http、simple 适配器,也可自定义 `init/put/complete` |
16
18
  | 源码 | 工具栏右侧常驻「源码」按钮(`⌘/Ctrl+Shift+K`),进入后正文按钮置灰;格式化缩进、复制、直接编辑并应用(回填自动净化) |
17
- | 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽)、全屏编辑、撤销重做(保留光标位置)、只读、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「源码/预览/全屏」固定右端 |
18
- | **自定义按钮** | `customButtons` 往工具栏加**下拉选择**按钮:数据可**静态配置**或**从接口读取**(`url` / `load`),选中后按配置**插入跳转链接**或直接打开;面板支持搜索、分组、加载/失败重试/空态、缓存与强制刷新;也可运行时 `addButton` / `removeButton` / `setButtonOptions` |
19
+ | 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽,API 与可选项)、全屏编辑、撤销重做(保留光标位置)、只读、**宽屏版心自适应**(两侧留白恒定,不随屏宽放大)、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「源码/全屏」固定右端 |
20
+ | **自定义按钮** | `customButtons` 往工具栏加**下拉选择**按钮:数据可**静态配置**或**从接口读取**(`url` / `load`),选中后按配置**插入跳转链接**或直接打开;面板支持搜索、分组、加载/失败重试/空态、缓存与强制刷新;`position` 可把它放到**工具栏任意位置**(含右侧吸附尾栏);也可运行时 `addButton` / `moveButton` / `removeButton` / `setButtonOptions` |
19
21
 
20
22
  ## 安装
21
23
 
@@ -28,7 +30,9 @@ npm install kyle-editor vue@^3
28
30
  或直接用 CDN(无需安装):
29
31
 
30
32
  ```html
31
- <script src="https://unpkg.com/kyle-editor/dist/keditor.umd.js"></script>
33
+ <!-- unpkg / jsdelivr 默认入口就是压缩版,下面两种写法等价 -->
34
+ <script src="https://unpkg.com/kyle-editor"></script>
35
+ <script src="https://unpkg.com/kyle-editor/dist/keditor.umd.min.js"></script>
32
36
  ```
33
37
 
34
38
  > 零运行时依赖;样式随 JS 注入,**不需要额外引入 CSS**。Vue 是可选 peerDependency,只用核心 API 的项目不会被强制安装。
@@ -39,8 +43,9 @@ npm install kyle-editor vue@^3
39
43
 
40
44
  ```html
41
45
  <div id="editor"></div>
42
- <script src="https://unpkg.com/kyle-editor/dist/keditor.umd.js"></script>
43
- <!-- 本地开发时也可用相对路径:<script src="dist/keditor.umd.js"></script> -->
46
+ <script src="https://unpkg.com/kyle-editor/dist/keditor.umd.min.js"></script>
47
+ <!-- 本地开发时也可用相对路径:<script src="dist/keditor.umd.min.js"></script>
48
+ 调试想看未压缩代码就换成 dist/keditor.umd.js(全局变量、API 完全一致) -->
44
49
  <script>
45
50
  const editor = KEditor.create('#editor', {
46
51
  placeholder: '开始撰写内容,支持拖拽 / 粘贴图片与视频…',
@@ -131,6 +136,39 @@ editor.on('customselect', ({ name, item, link, action }) => {
131
136
  ```
132
137
 
133
138
  > 没传 `toolbar` 时,自定义按钮会**自动追加**到默认工具栏末尾;传了 `toolbar` 数组则按名字定位:`toolbar: ['bold', '|', 'tpl', 'column']`。
139
+ > 想换位置?写 `position`(见下)即可,不需要重抄整份工具栏。
140
+
141
+ ### 按钮位置(可放在工具栏任意位置)
142
+
143
+ ```js
144
+ customButtons: [
145
+ { name: 'tpl', text: '模板', position: 'start' }, // 工具栏最前
146
+ { name: 'column', text: '栏目', position: { after: 'link' } }, // 紧跟「链接」之后
147
+ { name: 'emoji', text: '表情', position: { before: 'image' } }, // 插在「图片」之前
148
+ { name: 'ad', text: '头图', position: 2 }, // 第 3 个按钮之前(0 起)
149
+ { name: 'stats', text: '数据', position: 'tail' }, // 右侧吸附尾栏(与源码/全屏同区)
150
+ { name: 'draft', text: '草稿' }, // 缺省:主区末尾(尾栏之前)
151
+ ]
152
+ ```
153
+
154
+ | `position` 写法 | 含义 |
155
+ | --- | --- |
156
+ | `'start'` | 工具栏第一位 |
157
+ | `'end'` / 不写 | 主区末尾、右侧吸附尾栏之前 |
158
+ | `'tail'` | 右侧吸附尾栏末尾(无尾栏时回退主区末尾) |
159
+ | `number` | 第 n 个按钮之前(按视觉顺序,分隔符不计数) |
160
+ | `'link'` 等按钮名 | 插到该按钮之前 |
161
+ | `{ before: name }` / `{ after: name }` | 显式锚点;`name` 可以是内置按钮,也可以是另一个自定义按钮 |
162
+
163
+ - 错到不存在的锚点 → 自动回退主区末尾,不报错、不丢按钮。
164
+ - `toolbar` 数组里**已经写过**的自定义按钮名字以数组位置为准(`position` 被忽略),所以两种方式可以混用。
165
+ - 运行时移位(内置按钮也能移):
166
+
167
+ ```js
168
+ editor.moveButton('column', 'tail') // 移到右侧尾栏
169
+ editor.moveButton('tpl', { after: 'image' }) // 插到图片按钮之后
170
+ editor.moveButton('hr', 0) // 移到第一位
171
+ ```
134
172
 
135
173
  ### 数据源(优先级 `load` > `url` > `options`)
136
174
 
@@ -189,11 +227,14 @@ editor.on('customselect', ({ name, item, link, action }) => {
189
227
 
190
228
  ```js
191
229
  editor.addButton({ name: 'season', text: '节气', options: [...], link: 'https://x.com/{value}' })
192
- editor.addButton(spec, { at: 0 }) // 插到指定位置
193
- editor.removeButton('season') // 移除并中断未完成的接口请求
194
- editor.setButtonOptions('season', list) // 外部灌入数据
195
- editor.getButtonValue('column') // 读当前选中项
196
- editor.setButtonValue('column', 'tech') // 设置选中项(按钮文案同步)
230
+ editor.addButton(spec, { at: 0 }) // 第 1 个按钮之前
231
+ editor.addButton(spec, { at: 'tail' }) // 右侧吸附尾栏
232
+ editor.addButton(spec, { before: 'image' }) // 或 { after: 'link' } / { position: 'start' }
233
+ editor.moveButton('season', { after: 'link' }) // 移位(内置按钮同样可用)
234
+ editor.removeButton('season') // 移除并中断未完成的接口请求(附带清掉随行分隔符)
235
+ editor.setButtonOptions('season', list) // 外部灌入数据
236
+ editor.getButtonValue('column') // 读当前选中项
237
+ editor.setButtonValue('column', 'tech') // 设置选中项(按钮文案同步)
197
238
  ```
198
239
 
199
240
  ### 普通按钮(非下拉)
@@ -202,21 +243,73 @@ editor.setButtonValue('column', 'tech') // 设置选中项(按钮文案同
202
243
  { name: 'date', type: 'button', text: '插入日期', icon: 'plus', onClick: ({ editor }) => editor.commands.insertHTML('<p>2026-10-13</p>') }
203
244
  ```
204
245
 
246
+ ## 版心宽度与宽屏适配
247
+
248
+ 宽屏下如果版心固定 677px,编辑器两侧会出现大片空白。默认采用 **fluid 版心**:版心不小于 `paperWidth`,宽屏时随容器生长,两侧留白恒定为 `paperGap`(不再随屏宽放大)。
249
+
250
+ ```js
251
+ KEditor.create('#editor', {
252
+ paperWidth: 677, // 版心基准宽(公众号);fluid 模式下它是最小宽度
253
+ paperMode: 'fluid', // 'fluid'(默认)| 'fixed'(恒定 paperWidth + 64)
254
+ paperGap: 24, // fluid 模式下单侧留白
255
+ paperMaxWidth: 0, // fluid 模式下的版心上限,0 = 不限
256
+ })
257
+
258
+ // 运行时调整(侧栏折叠、布局变化时)
259
+ editor.setPaper({ mode: 'fixed' })
260
+ editor.setPaper({ gap: 40, maxWidth: 1000 })
261
+ editor.paperOptions() // { width, mode, gap, maxWidth }
262
+ ```
263
+
264
+ | 需求 | 配置 |
265
+ | --- | --- |
266
+ | 永远像公众号那样居中一栏 | `paperMode: 'fixed'` |
267
+ | 宽屏也想多写点字 | 默认 fluid(不限上限) |
268
+ | 宽屏但可读性优先 | fluid + `paperMaxWidth: 1000` |
269
+
270
+ > **预览按钮变更**:`preview` 已从默认工具栏移除(常驻尾栏只剩「源码 / 全屏」),预览能力不变:`editor.openPreview()` / `closePreview()` / `togglePreview()`。需要按钮时把它写回工具栏:
271
+ >
272
+ > ```js
273
+ > toolbar: [...KEditor.DEFAULT_TOOLBAR.slice(0, -1), 'preview', 'fullscreen']
274
+ > // 或直接指定尾栏:toolbar: ['bold', '|', ':tail', 'source', 'preview', 'fullscreen']
275
+ > ```
276
+
205
277
  ## 本地运行
206
278
 
207
279
  ```bash
208
280
  npm install
209
- npm run build # 产出 dist/(es + cjs + umd,含 Vue 版本)
281
+ npm run build # 产出 dist/(es + cjs + umd + umd.min,含 Vue 版本)
282
+ npm run build:min # 只重建压缩版 dist/keditor.umd.min.js
210
283
  npm run dev # 静态服务 http://127.0.0.1:5178
211
284
  ```
212
285
 
286
+ ### 构建产物
287
+
288
+ | 文件 | 用途 | 体积 |
289
+ | --- | --- | --- |
290
+ | `dist/keditor.umd.min.js` | **CDN / `<script>` 默认入口**(`unpkg`、`jsdelivr` 均指向它) | 139 KB / gzip 43 KB |
291
+ | `dist/keditor.umd.js` | 同上但未压缩,便于断点调试 | 209 KB / gzip 55 KB |
292
+ | `dist/keditor.es.js` | ESM(`exports.import`,打包器走这个) | 199 KB |
293
+ | `dist/keditor.cjs` | CommonJS(`exports.require`) | 200 KB |
294
+ | `dist/keditor-vue.{es,cjs,umd}.js` | Vue 组件/插件,外部化 `vue` 与本包 | 各约 4 KB |
295
+
296
+ 两份 UMD 产物由 `vite.config.core.js`(未压缩)与 `vite.config.min.js`(`minify: 'esbuild'`)从同一入口分别构建,全局变量都是 `window.KEditor`,API 完全一致。
297
+
213
298
  ## 验证
214
299
 
215
300
  ```bash
216
- npm run build
217
- npm run dev & # 启动静态服务
301
+ npm run dev & # 先启动静态服务(测试页面走 http://127.0.0.1:5178)
302
+
303
+ npm run verify # build + 冒烟(未压缩) + 冒烟(压缩) + 页面检查 + 类型 + 发布配置
304
+ npm test # 171 项冒烟,跑 dist/keditor.umd.js
305
+ npm run test:min # 同一套 171 项冒烟,跑 dist/keditor.umd.min.js
306
+ npm run test:pages # demo / 首页零控制台错误 + 真实交互探针
307
+ npm run test:install # npm pack → 隔离安装 → 校验包内入口与压缩产物等价性
308
+ npm run test:visual # 20 张关键状态截图(test/screenshots/)
218
309
  ```
219
310
 
311
+ > `test` 与 `test:min` 复用同一个 `test/smoke.html`,靠 `?bundle=min` 切换被测产物 —— 压缩版任何行为差异都会在这里暴露;`test:install` 还会对比两份 UMD 的导出清单,防止 minify 丢导出。
312
+
220
313
  ## 已知限制
221
314
 
222
315
  - 依赖浏览器 `contenteditable` + `document.execCommand`(主流浏览器均支持,Chrome/Safari/Edge/Firefox 已验证);不兼容 IE。
package/dist/keditor.cjs CHANGED
@@ -12,6 +12,7 @@ const CSS$1 = `
12
12
  --ke-bg: #f6f7f9;
13
13
  --ke-radius: 10px;
14
14
  --ke-paper: 677px;
15
+ --ke-paper-gap: 24px;
15
16
  --ke-shadow: 0 1px 2px rgba(16, 24, 40, .04), 0 8px 24px rgba(16, 24, 40, .06);
16
17
  font-family: -apple-system, BlinkMacSystemFont, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
17
18
  color: var(--ke-text);
@@ -284,6 +285,11 @@ const CSS$1 = `
284
285
  border-radius: 8px; box-shadow: var(--ke-shadow); padding: 32px;
285
286
  min-height: var(--ke-min-height, 320px);
286
287
  }
288
+ /* 宽屏:版心随容器生长,两侧留白恒定为 --ke-paper-gap,不再随屏宽放大 */
289
+ .ke-paper.ke-is-fluid {
290
+ width: min(100%, max(calc(var(--ke-paper) + 64px), calc(100% - var(--ke-paper-gap) * 2)));
291
+ max-width: var(--ke-paper-max, none);
292
+ }
287
293
  .ke-content { outline: none; font-size: 17px; line-height: 1.75; color: var(--ke-text); word-break: break-word; }
288
294
  .ke-content:empty::before,
289
295
  .ke-content[data-placeholder].ke-is-empty::before {
@@ -1868,12 +1874,35 @@ function normalizeItem(entry, index) {
1868
1874
  function normalizeItems(raw) {
1869
1875
  return pickArray(raw).map(normalizeItem).filter(Boolean);
1870
1876
  }
1877
+ function normalizePosition(spec = {}) {
1878
+ const raw = spec.position !== void 0 ? spec.position : spec.at;
1879
+ const num = (value) => Math.max(0, Math.floor(Number(value)));
1880
+ const named = (value) => typeof value === "object" && value ? value.before || value.after : value;
1881
+ if (typeof raw === "number" && Number.isFinite(raw)) return num(raw);
1882
+ if (typeof raw === "string" && raw) {
1883
+ const key = raw.toLowerCase();
1884
+ if (key === "start" || key === "begin" || key === "first") return "start";
1885
+ if (key === "end" || key === "last" || key === "main") return "end";
1886
+ if (key === "tail" || key === ":tail" || key === "right") return "tail";
1887
+ return { before: raw };
1888
+ }
1889
+ if (raw && typeof raw === "object") {
1890
+ if (raw.before) return { before: String(named(raw)) };
1891
+ if (raw.after) return { after: String(named(raw)) };
1892
+ }
1893
+ if (typeof spec.index === "number" && Number.isFinite(spec.index)) return num(spec.index);
1894
+ if (spec.before) return { before: String(spec.before) };
1895
+ if (spec.after) return { after: String(spec.after) };
1896
+ return null;
1897
+ }
1871
1898
  function normalizeCustomButton(spec) {
1872
1899
  if (!spec || typeof spec !== "object") return null;
1873
1900
  const name = String(spec.name || "").trim();
1874
1901
  if (!name) return null;
1875
1902
  return {
1876
1903
  name,
1904
+ /** 在工具栏里的位置(null = 默认追加到主区末尾) */
1905
+ position: normalizePosition(spec),
1877
1906
  type: spec.type === "button" ? "button" : "select",
1878
1907
  title: spec.title || spec.text || name,
1879
1908
  text: spec.text || "",
@@ -2110,7 +2139,6 @@ const DEFAULT_TOOLBAR = [
2110
2139
  "clear",
2111
2140
  ":tail",
2112
2141
  "source",
2113
- "preview",
2114
2142
  "fullscreen"
2115
2143
  ];
2116
2144
  const ITEMS = {
@@ -2136,6 +2164,7 @@ const ITEMS = {
2136
2164
  clear: { icon: "clear", title: "清除格式", run: (e) => e.commands.clearFormat() },
2137
2165
  source: { icon: "source", title: "查看 / 编辑 HTML 源码(⌘/Ctrl+Shift+K)", text: "源码", run: (e) => e.toggleSource(), active: (s) => s.source },
2138
2166
  preview: { icon: "preview", title: "预览效果(手机 / 平板 / 电脑宽度)", text: "预览", run: (e) => e.togglePreview(), active: (s) => s.preview },
2167
+ // 默认工具栏已不包含,可用 toolbar / position 显式摆放
2139
2168
  fullscreen: { icon: "expand", title: "全屏编辑", text: "全屏", run: (e) => e.toggleFullscreen(), active: (s) => s.fullscreen },
2140
2169
  foreColor: { pop: "fore", title: "字体颜色", toggles: true, swatch: "fore" },
2141
2170
  backColor: { pop: "back", title: "背景高亮色", toggles: true, swatch: "back" }
@@ -2187,11 +2216,9 @@ class Toolbar {
2187
2216
  target().appendChild(this.buildButton(key, spec));
2188
2217
  }
2189
2218
  for (const [name, entry] of this.custom) {
2190
- if (!entry.button) {
2191
- entry.button = this.buildCustomButton(entry);
2192
- target().appendChild(entry.button);
2193
- }
2194
- entry.button.dataset.kCustom = name;
2219
+ if (entry.button) continue;
2220
+ entry.button = this.buildCustomButton(entry);
2221
+ this.insertButton(entry.button, entry.spec.position);
2195
2222
  }
2196
2223
  }
2197
2224
  buildButton(name, spec) {
@@ -2321,7 +2348,7 @@ class Toolbar {
2321
2348
  class: isSelect ? "ke-btn-label ke-btn-custom" : "ke-btn-custom",
2322
2349
  title: spec.title,
2323
2350
  "data-k-item": spec.name,
2324
- dataset: { kPop: spec.name },
2351
+ dataset: { kPop: spec.name, kCustom: spec.name },
2325
2352
  onclick: (event) => {
2326
2353
  event.preventDefault();
2327
2354
  if (isSelect) this.openCustom(spec.name);
@@ -2397,27 +2424,67 @@ class Toolbar {
2397
2424
  }
2398
2425
  this.editor.refresh();
2399
2426
  }
2400
- /** 运行时新增自定义按钮;at 为 toolbar 内插入位置(默认追加到主分组末尾) */
2401
- addButton(spec, { at } = {}) {
2427
+ /** 运行时新增自定义按钮;位置取 options.at ?? spec.position(默认追加到主分组末尾) */
2428
+ addButton(spec, options = {}) {
2402
2429
  var _a;
2403
2430
  const entry = this.registerCustom(spec);
2404
2431
  if (!entry) return null;
2405
2432
  if (entry.button) entry.button.remove();
2406
2433
  entry.button = this.buildCustomButton(entry);
2407
- const host = this.tailEl || this.groupEl;
2408
- if (!host) return entry.button;
2409
- if (typeof at === "number" && at >= 0) {
2410
- const ref = host.children[Math.min(at, host.children.length)];
2411
- host.insertBefore(entry.button, ref || null);
2412
- } else {
2413
- const sep2 = h("span.ke-tb-sep");
2414
- host.appendChild(sep2);
2415
- host.appendChild(entry.button);
2416
- }
2434
+ const where = options.at !== void 0 ? options.at : normalizePosition(options) ?? entry.spec.position;
2435
+ this.insertButton(entry.button, where, { withSep: where == null });
2417
2436
  this.revealButton(entry.button);
2418
2437
  (_a = this.syncScrollHints) == null ? void 0 : _a.call(this);
2419
2438
  return entry.button;
2420
2439
  }
2440
+ /** 工具栏内可定位的节点(主区 → 尾区的视觉顺序,不含分隔符) */
2441
+ buttonNodes() {
2442
+ const list = [];
2443
+ for (const host of [this.groupEl, this.tailEl]) {
2444
+ if (!host) continue;
2445
+ for (const node of host.children) if (node.dataset && node.dataset.kItem) list.push(node);
2446
+ }
2447
+ return list;
2448
+ }
2449
+ /** 位置描述 → {parent, ref},ref 为 null 表示追加到 parent 末尾 */
2450
+ slotOf(where) {
2451
+ const mainEnd = { parent: this.groupEl || this.el, ref: null };
2452
+ if (where === "tail") return { parent: this.tailEl || this.groupEl || this.el, ref: null };
2453
+ if (where == null || where === "end") return mainEnd;
2454
+ if (where === "start") {
2455
+ const first2 = this.buttonNodes()[0];
2456
+ return first2 ? { parent: first2.parentElement, ref: first2 } : mainEnd;
2457
+ }
2458
+ const nodes = this.buttonNodes();
2459
+ if (typeof where === "number") {
2460
+ const ref = nodes[Math.max(0, Math.floor(where))];
2461
+ if (ref) return { parent: ref.parentElement, ref };
2462
+ const last = nodes[nodes.length - 1];
2463
+ return last ? { parent: last.parentElement, ref: null } : mainEnd;
2464
+ }
2465
+ const after = !!(where && typeof where === "object" && where.after);
2466
+ const name = typeof where === "string" ? where : String((after ? where.after : where.before) || "");
2467
+ const anchor = nodes.find((node) => node.dataset.kItem === name);
2468
+ if (!anchor) return mainEnd;
2469
+ return { parent: anchor.parentElement, ref: after ? anchor.nextElementSibling || null : anchor };
2470
+ }
2471
+ insertButton(button, where, { withSep } = {}) {
2472
+ const { parent, ref } = this.slotOf(where);
2473
+ if (!parent || !button) return;
2474
+ if (withSep && !ref) parent.appendChild(h("span.ke-tb-sep"));
2475
+ parent.insertBefore(button, ref || null);
2476
+ }
2477
+ /** 运行时把任意按钮(内置或自定义)移到指定位置 */
2478
+ moveButton(name, where) {
2479
+ var _a, _b;
2480
+ const node = this.buttonNodes().find((item) => item.dataset.kItem === String(name));
2481
+ if (!node) return false;
2482
+ node.remove();
2483
+ this.insertButton(node, where === void 0 ? ((_a = this.custom.get(String(name))) == null ? void 0 : _a.spec.position) ?? null : where);
2484
+ this.revealButton(node);
2485
+ (_b = this.syncScrollHints) == null ? void 0 : _b.call(this);
2486
+ return true;
2487
+ }
2421
2488
  /** 工具栏溢出时把按钮滚进可视区(避开 sticky 尾栏的遮挡) */
2422
2489
  revealButton(button) {
2423
2490
  const tb = this.el;
@@ -2433,15 +2500,18 @@ class Toolbar {
2433
2500
  }
2434
2501
  /** 移除自定义按钮并中断其未完成的请求 */
2435
2502
  removeButton(name) {
2436
- var _a, _b;
2503
+ var _a, _b, _c, _d;
2437
2504
  const entry = this.custom.get(name);
2438
2505
  if (!entry) return false;
2439
2506
  abortRuntime(entry.rt);
2440
2507
  if (this.editor.popover.anchor === entry.button) this.editor.popover.close();
2441
- (_a = entry.button) == null ? void 0 : _a.remove();
2508
+ const prev = (_a = entry.button) == null ? void 0 : _a.previousElementSibling;
2509
+ const next = (_b = entry.button) == null ? void 0 : _b.nextElementSibling;
2510
+ (_c = entry.button) == null ? void 0 : _c.remove();
2511
+ if (prev && prev.classList.contains("ke-tb-sep") && (!next || next.classList.contains("ke-tb-sep"))) prev.remove();
2442
2512
  this.buttons.delete(name);
2443
2513
  this.custom.delete(name);
2444
- (_b = this.syncScrollHints) == null ? void 0 : _b.call(this);
2514
+ (_d = this.syncScrollHints) == null ? void 0 : _d.call(this);
2445
2515
  return true;
2446
2516
  }
2447
2517
  /** 外部灌入下拉数据(接口在编辑器之外请求时用),并刷新已打开的面板 */
@@ -3983,6 +4053,13 @@ const defaults = {
3983
4053
  minHeight: 320,
3984
4054
  primaryColor: "#07c160",
3985
4055
  paperWidth: 677,
4056
+ // 版心基准宽度:窄屏上限、宽屏最小宽度
4057
+ /** 版心宽度模式:'fluid' 宽屏随容器生长(两侧留白恒定)| 'fixed' 恒定版心 */
4058
+ paperMode: "fluid",
4059
+ paperGap: 24,
4060
+ // fluid 模式下单侧留白(px)
4061
+ paperMaxWidth: 0,
4062
+ // fluid 模式下版心最大宽度,0 = 不限
3986
4063
  toolbar: DEFAULT_TOOLBAR,
3987
4064
  /** 自定义工具栏按钮(下拉选择,数据可静态配置或从接口读取) */
3988
4065
  customButtons: [],
@@ -4086,8 +4163,30 @@ class KEditor {
4086
4163
  this.scrollEl.style.height = `${this.options.height}px`;
4087
4164
  this.scrollEl.style.maxHeight = `${this.options.height}px`;
4088
4165
  }
4089
- this.paperEl.style.setProperty("--ke-paper", `${this.options.paperWidth}px`);
4090
4166
  this.paperEl.style.setProperty("--ke-min-height", `${this.options.minHeight}px`);
4167
+ this.applyPaper();
4168
+ }
4169
+ /** 版心尺寸:宽屏下默认让版心随容器生长,两侧只保留固定留白 */
4170
+ applyPaper() {
4171
+ const { paperWidth, paperMode, paperGap, paperMaxWidth } = this.options;
4172
+ this.paperEl.style.setProperty("--ke-paper", `${paperWidth}px`);
4173
+ this.paperEl.style.setProperty("--ke-paper-gap", `${paperGap}px`);
4174
+ if (paperMaxWidth > 0) this.paperEl.style.setProperty("--ke-paper-max", `${paperMaxWidth}px`);
4175
+ else this.paperEl.style.removeProperty("--ke-paper-max");
4176
+ this.paperEl.classList.toggle("ke-is-fluid", paperMode !== "fixed");
4177
+ }
4178
+ /** 运行时调整版心:{width, mode, gap, maxWidth}(mode: 'fluid' | 'fixed') */
4179
+ setPaper(config = {}) {
4180
+ if (config.width !== void 0) this.options.paperWidth = clamp$1(Number(config.width) || 0, 200, 8e3);
4181
+ if (config.mode !== void 0) this.options.paperMode = config.mode === "fixed" ? "fixed" : "fluid";
4182
+ if (config.gap !== void 0) this.options.paperGap = clamp$1(Number(config.gap) || 0, 0, 600);
4183
+ if (config.maxWidth !== void 0) this.options.paperMaxWidth = Math.max(0, Number(config.maxWidth) || 0);
4184
+ this.applyPaper();
4185
+ return { ...this.paperOptions() };
4186
+ }
4187
+ paperOptions() {
4188
+ const { paperWidth, paperMode, paperGap, paperMaxWidth } = this.options;
4189
+ return { width: paperWidth, mode: paperMode, gap: paperGap, maxWidth: paperMaxWidth };
4091
4190
  }
4092
4191
  applyTheme() {
4093
4192
  if (this.options.primaryColor) this.el.style.setProperty("--ke-primary", this.options.primaryColor);
@@ -4423,6 +4522,10 @@ class KEditor {
4423
4522
  addButton(spec, options) {
4424
4523
  return this.toolbar.addButton(spec, options);
4425
4524
  }
4525
+ /** 运行时移动任意按钮位置(内置或自定义);where 同 spec.position 语义 */
4526
+ moveButton(name, where) {
4527
+ return this.toolbar.moveButton(name, where);
4528
+ }
4426
4529
  /** 移除自定义按钮,并中断其未完成的接口请求 */
4427
4530
  removeButton(name) {
4428
4531
  return this.toolbar.removeButton(name);
@@ -4610,16 +4713,53 @@ function mergeOptions(options) {
4610
4713
  if (Array.isArray(options.toolbar)) out.toolbar = options.toolbar;
4611
4714
  if (options.toolbar === false) out.toolbar = [];
4612
4715
  if (options.toolbar === true) out.toolbar = DEFAULT_TOOLBAR;
4613
- if (out.customButtons.length && options.toolbar === void 0) {
4614
- out.toolbar = appendCustomNames(DEFAULT_TOOLBAR, out.customButtons.map((spec) => spec.name));
4716
+ if (out.customButtons.length && options.toolbar !== false) {
4717
+ out.toolbar = placeCustomNames(out.toolbar, out.customButtons);
4615
4718
  }
4616
4719
  out.height = clamp$1(out.height ?? 460, 0, 4e3);
4720
+ out.paperWidth = clamp$1(Number(out.paperWidth) || defaults.paperWidth, 200, 8e3);
4721
+ out.paperMode = out.paperMode === "fixed" ? "fixed" : "fluid";
4722
+ out.paperGap = Number.isFinite(Number(out.paperGap)) ? clamp$1(Number(out.paperGap), 0, 600) : defaults.paperGap;
4723
+ out.paperMaxWidth = Math.max(0, Number(out.paperMaxWidth) || 0);
4617
4724
  return out;
4618
4725
  }
4619
- function appendCustomNames(items, names) {
4620
- const at = items.indexOf(":tail");
4621
- const insert = ["|", ...names];
4622
- return at < 0 ? [...items, ...insert] : [...items.slice(0, at), ...insert, ...items.slice(at)];
4726
+ const isButtonItem = (key) => key !== "|" && key !== ":tail";
4727
+ function placeCustomNames(items, specs) {
4728
+ const out = [...items];
4729
+ const loose = [];
4730
+ for (const spec of specs) {
4731
+ if (out.includes(spec.name)) continue;
4732
+ if (spec.position == null) {
4733
+ loose.push(spec.name);
4734
+ continue;
4735
+ }
4736
+ out.splice(arrIndexOf(out, spec.position), 0, spec.name);
4737
+ }
4738
+ if (loose.length) out.splice(arrIndexOf(out, null), 0, "|", ...loose);
4739
+ return out;
4740
+ }
4741
+ function arrIndexOf(items, where) {
4742
+ const mainEnd = (() => {
4743
+ const at2 = items.indexOf(":tail");
4744
+ return at2 < 0 ? items.length : at2;
4745
+ })();
4746
+ if (where == null || where === "end") return mainEnd;
4747
+ if (where === "start") return 0;
4748
+ if (where === "tail") return items.length;
4749
+ if (typeof where === "number") {
4750
+ let seen = 0;
4751
+ for (let i = 0; i < items.length; i++) {
4752
+ if (!isButtonItem(items[i])) continue;
4753
+ if (seen === Math.max(0, Math.floor(where))) return i;
4754
+ seen++;
4755
+ }
4756
+ return mainEnd;
4757
+ }
4758
+ const after = !!(where && typeof where === "object" && where.after);
4759
+ const name = String(typeof where === "string" ? where : (after ? where.after : where.before) || "");
4760
+ const at = items.indexOf(name);
4761
+ if (at < 0) return mainEnd;
4762
+ return after ? at + 1 : at;
4623
4763
  }
4624
4764
  function buildStatusbar(editor) {
4625
4765
  const chars = h("b", { text: "0" });
@@ -4712,7 +4852,7 @@ function previewHtml(html) {
4712
4852
  });
4713
4853
  return root.innerHTML;
4714
4854
  }
4715
- const version = "1.0.2";
4855
+ const version = "1.0.4";
4716
4856
  function create(target, options = {}) {
4717
4857
  return new KEditor(target, options);
4718
4858
  }
@@ -4741,6 +4881,7 @@ exports.mockAdapter = mockAdapter;
4741
4881
  exports.mount = mount;
4742
4882
  exports.normalizeCustomButtons = normalizeCustomButtons;
4743
4883
  exports.normalizeItems = normalizeItems;
4884
+ exports.normalizePosition = normalizePosition;
4744
4885
  exports.replace = replace;
4745
4886
  exports.sanitizeHtml = sanitizeHtml;
4746
4887
  exports.simpleAdapter = simpleAdapter;