kyle-editor 1.0.2 → 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 CHANGED
@@ -2,8 +2,8 @@
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.js` 约 209 KB(gzip 55 KB),零运行时依赖,样式随 JS 注入
6
+ - 版式:677px 正文版心、17px/1.75 行距,与公众号观感一致;**宽屏下版心自动生长**,两侧留白恒定,不会留出一大块空白
7
7
  - 安全:标签/属性白名单净化,拦截 `on*`、`javascript:`、`script/iframe`
8
8
 
9
9
  ## 功能
@@ -14,8 +14,8 @@
14
14
  | 媒体 | 图片/视频**本地上传**(点击、拖拽、粘贴截图)或**直接填网络链接**插入(自动校验可访问性);分片进度与速度、取消、失败重试、多图多选、大图自动压缩、双击看原图、气泡工具条(对齐/宽度/圆角/替换/删除)、**选中图片后拖拽右下角把手实时缩放** |
15
15
  | 上传 | `chunkSize / concurrency / retries / fingerprint` 可配;内置 mock、http、simple 适配器,也可自定义 `init/put/complete` |
16
16
  | 源码 | 工具栏右侧常驻「源码」按钮(`⌘/Ctrl+Shift+K`),进入后正文按钮置灰;格式化缩进、复制、直接编辑并应用(回填自动净化) |
17
- | 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽)、全屏编辑、撤销重做(保留光标位置)、只读、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「源码/预览/全屏」固定右端 |
18
- | **自定义按钮** | `customButtons` 往工具栏加**下拉选择**按钮:数据可**静态配置**或**从接口读取**(`url` / `load`),选中后按配置**插入跳转链接**或直接打开;面板支持搜索、分组、加载/失败重试/空态、缓存与强制刷新;也可运行时 `addButton` / `removeButton` / `setButtonOptions` |
17
+ | 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽,API 与可选项)、全屏编辑、撤销重做(保留光标位置)、只读、**宽屏版心自适应**(两侧留白恒定,不随屏宽放大)、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「源码/全屏」固定右端 |
18
+ | **自定义按钮** | `customButtons` 往工具栏加**下拉选择**按钮:数据可**静态配置**或**从接口读取**(`url` / `load`),选中后按配置**插入跳转链接**或直接打开;面板支持搜索、分组、加载/失败重试/空态、缓存与强制刷新;`position` 可把它放到**工具栏任意位置**(含右侧吸附尾栏);也可运行时 `addButton` / `moveButton` / `removeButton` / `setButtonOptions` |
19
19
 
20
20
  ## 安装
21
21
 
@@ -131,6 +131,39 @@ editor.on('customselect', ({ name, item, link, action }) => {
131
131
  ```
132
132
 
133
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
+ ```
134
167
 
135
168
  ### 数据源(优先级 `load` > `url` > `options`)
136
169
 
@@ -189,11 +222,14 @@ editor.on('customselect', ({ name, item, link, action }) => {
189
222
 
190
223
  ```js
191
224
  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') // 设置选中项(按钮文案同步)
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') // 设置选中项(按钮文案同步)
197
233
  ```
198
234
 
199
235
  ### 普通按钮(非下拉)
@@ -202,6 +238,37 @@ editor.setButtonValue('column', 'tech') // 设置选中项(按钮文案同
202
238
  { name: 'date', type: 'button', text: '插入日期', icon: 'plus', onClick: ({ editor }) => editor.commands.insertHTML('<p>2026-10-13</p>') }
203
239
  ```
204
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
+
205
272
  ## 本地运行
206
273
 
207
274
  ```bash
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.3";
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;
@@ -10,6 +10,7 @@ const CSS$1 = `
10
10
  --ke-bg: #f6f7f9;
11
11
  --ke-radius: 10px;
12
12
  --ke-paper: 677px;
13
+ --ke-paper-gap: 24px;
13
14
  --ke-shadow: 0 1px 2px rgba(16, 24, 40, .04), 0 8px 24px rgba(16, 24, 40, .06);
14
15
  font-family: -apple-system, BlinkMacSystemFont, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
15
16
  color: var(--ke-text);
@@ -282,6 +283,11 @@ const CSS$1 = `
282
283
  border-radius: 8px; box-shadow: var(--ke-shadow); padding: 32px;
283
284
  min-height: var(--ke-min-height, 320px);
284
285
  }
286
+ /* 宽屏:版心随容器生长,两侧留白恒定为 --ke-paper-gap,不再随屏宽放大 */
287
+ .ke-paper.ke-is-fluid {
288
+ width: min(100%, max(calc(var(--ke-paper) + 64px), calc(100% - var(--ke-paper-gap) * 2)));
289
+ max-width: var(--ke-paper-max, none);
290
+ }
285
291
  .ke-content { outline: none; font-size: 17px; line-height: 1.75; color: var(--ke-text); word-break: break-word; }
286
292
  .ke-content:empty::before,
287
293
  .ke-content[data-placeholder].ke-is-empty::before {
@@ -1866,12 +1872,35 @@ function normalizeItem(entry, index) {
1866
1872
  function normalizeItems(raw) {
1867
1873
  return pickArray(raw).map(normalizeItem).filter(Boolean);
1868
1874
  }
1875
+ function normalizePosition(spec = {}) {
1876
+ const raw = spec.position !== void 0 ? spec.position : spec.at;
1877
+ const num = (value) => Math.max(0, Math.floor(Number(value)));
1878
+ const named = (value) => typeof value === "object" && value ? value.before || value.after : value;
1879
+ if (typeof raw === "number" && Number.isFinite(raw)) return num(raw);
1880
+ if (typeof raw === "string" && raw) {
1881
+ const key = raw.toLowerCase();
1882
+ if (key === "start" || key === "begin" || key === "first") return "start";
1883
+ if (key === "end" || key === "last" || key === "main") return "end";
1884
+ if (key === "tail" || key === ":tail" || key === "right") return "tail";
1885
+ return { before: raw };
1886
+ }
1887
+ if (raw && typeof raw === "object") {
1888
+ if (raw.before) return { before: String(named(raw)) };
1889
+ if (raw.after) return { after: String(named(raw)) };
1890
+ }
1891
+ if (typeof spec.index === "number" && Number.isFinite(spec.index)) return num(spec.index);
1892
+ if (spec.before) return { before: String(spec.before) };
1893
+ if (spec.after) return { after: String(spec.after) };
1894
+ return null;
1895
+ }
1869
1896
  function normalizeCustomButton(spec) {
1870
1897
  if (!spec || typeof spec !== "object") return null;
1871
1898
  const name = String(spec.name || "").trim();
1872
1899
  if (!name) return null;
1873
1900
  return {
1874
1901
  name,
1902
+ /** 在工具栏里的位置(null = 默认追加到主区末尾) */
1903
+ position: normalizePosition(spec),
1875
1904
  type: spec.type === "button" ? "button" : "select",
1876
1905
  title: spec.title || spec.text || name,
1877
1906
  text: spec.text || "",
@@ -2108,7 +2137,6 @@ const DEFAULT_TOOLBAR = [
2108
2137
  "clear",
2109
2138
  ":tail",
2110
2139
  "source",
2111
- "preview",
2112
2140
  "fullscreen"
2113
2141
  ];
2114
2142
  const ITEMS = {
@@ -2134,6 +2162,7 @@ const ITEMS = {
2134
2162
  clear: { icon: "clear", title: "清除格式", run: (e) => e.commands.clearFormat() },
2135
2163
  source: { icon: "source", title: "查看 / 编辑 HTML 源码(⌘/Ctrl+Shift+K)", text: "源码", run: (e) => e.toggleSource(), active: (s) => s.source },
2136
2164
  preview: { icon: "preview", title: "预览效果(手机 / 平板 / 电脑宽度)", text: "预览", run: (e) => e.togglePreview(), active: (s) => s.preview },
2165
+ // 默认工具栏已不包含,可用 toolbar / position 显式摆放
2137
2166
  fullscreen: { icon: "expand", title: "全屏编辑", text: "全屏", run: (e) => e.toggleFullscreen(), active: (s) => s.fullscreen },
2138
2167
  foreColor: { pop: "fore", title: "字体颜色", toggles: true, swatch: "fore" },
2139
2168
  backColor: { pop: "back", title: "背景高亮色", toggles: true, swatch: "back" }
@@ -2185,11 +2214,9 @@ class Toolbar {
2185
2214
  target().appendChild(this.buildButton(key, spec));
2186
2215
  }
2187
2216
  for (const [name, entry] of this.custom) {
2188
- if (!entry.button) {
2189
- entry.button = this.buildCustomButton(entry);
2190
- target().appendChild(entry.button);
2191
- }
2192
- entry.button.dataset.kCustom = name;
2217
+ if (entry.button) continue;
2218
+ entry.button = this.buildCustomButton(entry);
2219
+ this.insertButton(entry.button, entry.spec.position);
2193
2220
  }
2194
2221
  }
2195
2222
  buildButton(name, spec) {
@@ -2319,7 +2346,7 @@ class Toolbar {
2319
2346
  class: isSelect ? "ke-btn-label ke-btn-custom" : "ke-btn-custom",
2320
2347
  title: spec.title,
2321
2348
  "data-k-item": spec.name,
2322
- dataset: { kPop: spec.name },
2349
+ dataset: { kPop: spec.name, kCustom: spec.name },
2323
2350
  onclick: (event) => {
2324
2351
  event.preventDefault();
2325
2352
  if (isSelect) this.openCustom(spec.name);
@@ -2395,27 +2422,67 @@ class Toolbar {
2395
2422
  }
2396
2423
  this.editor.refresh();
2397
2424
  }
2398
- /** 运行时新增自定义按钮;at 为 toolbar 内插入位置(默认追加到主分组末尾) */
2399
- addButton(spec, { at } = {}) {
2425
+ /** 运行时新增自定义按钮;位置取 options.at ?? spec.position(默认追加到主分组末尾) */
2426
+ addButton(spec, options = {}) {
2400
2427
  var _a;
2401
2428
  const entry = this.registerCustom(spec);
2402
2429
  if (!entry) return null;
2403
2430
  if (entry.button) entry.button.remove();
2404
2431
  entry.button = this.buildCustomButton(entry);
2405
- const host = this.tailEl || this.groupEl;
2406
- if (!host) return entry.button;
2407
- if (typeof at === "number" && at >= 0) {
2408
- const ref = host.children[Math.min(at, host.children.length)];
2409
- host.insertBefore(entry.button, ref || null);
2410
- } else {
2411
- const sep2 = h("span.ke-tb-sep");
2412
- host.appendChild(sep2);
2413
- host.appendChild(entry.button);
2414
- }
2432
+ const where = options.at !== void 0 ? options.at : normalizePosition(options) ?? entry.spec.position;
2433
+ this.insertButton(entry.button, where, { withSep: where == null });
2415
2434
  this.revealButton(entry.button);
2416
2435
  (_a = this.syncScrollHints) == null ? void 0 : _a.call(this);
2417
2436
  return entry.button;
2418
2437
  }
2438
+ /** 工具栏内可定位的节点(主区 → 尾区的视觉顺序,不含分隔符) */
2439
+ buttonNodes() {
2440
+ const list = [];
2441
+ for (const host of [this.groupEl, this.tailEl]) {
2442
+ if (!host) continue;
2443
+ for (const node of host.children) if (node.dataset && node.dataset.kItem) list.push(node);
2444
+ }
2445
+ return list;
2446
+ }
2447
+ /** 位置描述 → {parent, ref},ref 为 null 表示追加到 parent 末尾 */
2448
+ slotOf(where) {
2449
+ const mainEnd = { parent: this.groupEl || this.el, ref: null };
2450
+ if (where === "tail") return { parent: this.tailEl || this.groupEl || this.el, ref: null };
2451
+ if (where == null || where === "end") return mainEnd;
2452
+ if (where === "start") {
2453
+ const first2 = this.buttonNodes()[0];
2454
+ return first2 ? { parent: first2.parentElement, ref: first2 } : mainEnd;
2455
+ }
2456
+ const nodes = this.buttonNodes();
2457
+ if (typeof where === "number") {
2458
+ const ref = nodes[Math.max(0, Math.floor(where))];
2459
+ if (ref) return { parent: ref.parentElement, ref };
2460
+ const last = nodes[nodes.length - 1];
2461
+ return last ? { parent: last.parentElement, ref: null } : mainEnd;
2462
+ }
2463
+ const after = !!(where && typeof where === "object" && where.after);
2464
+ const name = typeof where === "string" ? where : String((after ? where.after : where.before) || "");
2465
+ const anchor = nodes.find((node) => node.dataset.kItem === name);
2466
+ if (!anchor) return mainEnd;
2467
+ return { parent: anchor.parentElement, ref: after ? anchor.nextElementSibling || null : anchor };
2468
+ }
2469
+ insertButton(button, where, { withSep } = {}) {
2470
+ const { parent, ref } = this.slotOf(where);
2471
+ if (!parent || !button) return;
2472
+ if (withSep && !ref) parent.appendChild(h("span.ke-tb-sep"));
2473
+ parent.insertBefore(button, ref || null);
2474
+ }
2475
+ /** 运行时把任意按钮(内置或自定义)移到指定位置 */
2476
+ moveButton(name, where) {
2477
+ var _a, _b;
2478
+ const node = this.buttonNodes().find((item) => item.dataset.kItem === String(name));
2479
+ if (!node) return false;
2480
+ node.remove();
2481
+ this.insertButton(node, where === void 0 ? ((_a = this.custom.get(String(name))) == null ? void 0 : _a.spec.position) ?? null : where);
2482
+ this.revealButton(node);
2483
+ (_b = this.syncScrollHints) == null ? void 0 : _b.call(this);
2484
+ return true;
2485
+ }
2419
2486
  /** 工具栏溢出时把按钮滚进可视区(避开 sticky 尾栏的遮挡) */
2420
2487
  revealButton(button) {
2421
2488
  const tb = this.el;
@@ -2431,15 +2498,18 @@ class Toolbar {
2431
2498
  }
2432
2499
  /** 移除自定义按钮并中断其未完成的请求 */
2433
2500
  removeButton(name) {
2434
- var _a, _b;
2501
+ var _a, _b, _c, _d;
2435
2502
  const entry = this.custom.get(name);
2436
2503
  if (!entry) return false;
2437
2504
  abortRuntime(entry.rt);
2438
2505
  if (this.editor.popover.anchor === entry.button) this.editor.popover.close();
2439
- (_a = entry.button) == null ? void 0 : _a.remove();
2506
+ const prev = (_a = entry.button) == null ? void 0 : _a.previousElementSibling;
2507
+ const next = (_b = entry.button) == null ? void 0 : _b.nextElementSibling;
2508
+ (_c = entry.button) == null ? void 0 : _c.remove();
2509
+ if (prev && prev.classList.contains("ke-tb-sep") && (!next || next.classList.contains("ke-tb-sep"))) prev.remove();
2440
2510
  this.buttons.delete(name);
2441
2511
  this.custom.delete(name);
2442
- (_b = this.syncScrollHints) == null ? void 0 : _b.call(this);
2512
+ (_d = this.syncScrollHints) == null ? void 0 : _d.call(this);
2443
2513
  return true;
2444
2514
  }
2445
2515
  /** 外部灌入下拉数据(接口在编辑器之外请求时用),并刷新已打开的面板 */
@@ -3981,6 +4051,13 @@ const defaults = {
3981
4051
  minHeight: 320,
3982
4052
  primaryColor: "#07c160",
3983
4053
  paperWidth: 677,
4054
+ // 版心基准宽度:窄屏上限、宽屏最小宽度
4055
+ /** 版心宽度模式:'fluid' 宽屏随容器生长(两侧留白恒定)| 'fixed' 恒定版心 */
4056
+ paperMode: "fluid",
4057
+ paperGap: 24,
4058
+ // fluid 模式下单侧留白(px)
4059
+ paperMaxWidth: 0,
4060
+ // fluid 模式下版心最大宽度,0 = 不限
3984
4061
  toolbar: DEFAULT_TOOLBAR,
3985
4062
  /** 自定义工具栏按钮(下拉选择,数据可静态配置或从接口读取) */
3986
4063
  customButtons: [],
@@ -4084,8 +4161,30 @@ class KEditor {
4084
4161
  this.scrollEl.style.height = `${this.options.height}px`;
4085
4162
  this.scrollEl.style.maxHeight = `${this.options.height}px`;
4086
4163
  }
4087
- this.paperEl.style.setProperty("--ke-paper", `${this.options.paperWidth}px`);
4088
4164
  this.paperEl.style.setProperty("--ke-min-height", `${this.options.minHeight}px`);
4165
+ this.applyPaper();
4166
+ }
4167
+ /** 版心尺寸:宽屏下默认让版心随容器生长,两侧只保留固定留白 */
4168
+ applyPaper() {
4169
+ const { paperWidth, paperMode, paperGap, paperMaxWidth } = this.options;
4170
+ this.paperEl.style.setProperty("--ke-paper", `${paperWidth}px`);
4171
+ this.paperEl.style.setProperty("--ke-paper-gap", `${paperGap}px`);
4172
+ if (paperMaxWidth > 0) this.paperEl.style.setProperty("--ke-paper-max", `${paperMaxWidth}px`);
4173
+ else this.paperEl.style.removeProperty("--ke-paper-max");
4174
+ this.paperEl.classList.toggle("ke-is-fluid", paperMode !== "fixed");
4175
+ }
4176
+ /** 运行时调整版心:{width, mode, gap, maxWidth}(mode: 'fluid' | 'fixed') */
4177
+ setPaper(config = {}) {
4178
+ if (config.width !== void 0) this.options.paperWidth = clamp$1(Number(config.width) || 0, 200, 8e3);
4179
+ if (config.mode !== void 0) this.options.paperMode = config.mode === "fixed" ? "fixed" : "fluid";
4180
+ if (config.gap !== void 0) this.options.paperGap = clamp$1(Number(config.gap) || 0, 0, 600);
4181
+ if (config.maxWidth !== void 0) this.options.paperMaxWidth = Math.max(0, Number(config.maxWidth) || 0);
4182
+ this.applyPaper();
4183
+ return { ...this.paperOptions() };
4184
+ }
4185
+ paperOptions() {
4186
+ const { paperWidth, paperMode, paperGap, paperMaxWidth } = this.options;
4187
+ return { width: paperWidth, mode: paperMode, gap: paperGap, maxWidth: paperMaxWidth };
4089
4188
  }
4090
4189
  applyTheme() {
4091
4190
  if (this.options.primaryColor) this.el.style.setProperty("--ke-primary", this.options.primaryColor);
@@ -4421,6 +4520,10 @@ class KEditor {
4421
4520
  addButton(spec, options) {
4422
4521
  return this.toolbar.addButton(spec, options);
4423
4522
  }
4523
+ /** 运行时移动任意按钮位置(内置或自定义);where 同 spec.position 语义 */
4524
+ moveButton(name, where) {
4525
+ return this.toolbar.moveButton(name, where);
4526
+ }
4424
4527
  /** 移除自定义按钮,并中断其未完成的接口请求 */
4425
4528
  removeButton(name) {
4426
4529
  return this.toolbar.removeButton(name);
@@ -4608,16 +4711,53 @@ function mergeOptions(options) {
4608
4711
  if (Array.isArray(options.toolbar)) out.toolbar = options.toolbar;
4609
4712
  if (options.toolbar === false) out.toolbar = [];
4610
4713
  if (options.toolbar === true) out.toolbar = DEFAULT_TOOLBAR;
4611
- if (out.customButtons.length && options.toolbar === void 0) {
4612
- out.toolbar = appendCustomNames(DEFAULT_TOOLBAR, out.customButtons.map((spec) => spec.name));
4714
+ if (out.customButtons.length && options.toolbar !== false) {
4715
+ out.toolbar = placeCustomNames(out.toolbar, out.customButtons);
4613
4716
  }
4614
4717
  out.height = clamp$1(out.height ?? 460, 0, 4e3);
4718
+ out.paperWidth = clamp$1(Number(out.paperWidth) || defaults.paperWidth, 200, 8e3);
4719
+ out.paperMode = out.paperMode === "fixed" ? "fixed" : "fluid";
4720
+ out.paperGap = Number.isFinite(Number(out.paperGap)) ? clamp$1(Number(out.paperGap), 0, 600) : defaults.paperGap;
4721
+ out.paperMaxWidth = Math.max(0, Number(out.paperMaxWidth) || 0);
4615
4722
  return out;
4616
4723
  }
4617
- function appendCustomNames(items, names) {
4618
- const at = items.indexOf(":tail");
4619
- const insert = ["|", ...names];
4620
- return at < 0 ? [...items, ...insert] : [...items.slice(0, at), ...insert, ...items.slice(at)];
4724
+ const isButtonItem = (key) => key !== "|" && key !== ":tail";
4725
+ function placeCustomNames(items, specs) {
4726
+ const out = [...items];
4727
+ const loose = [];
4728
+ for (const spec of specs) {
4729
+ if (out.includes(spec.name)) continue;
4730
+ if (spec.position == null) {
4731
+ loose.push(spec.name);
4732
+ continue;
4733
+ }
4734
+ out.splice(arrIndexOf(out, spec.position), 0, spec.name);
4735
+ }
4736
+ if (loose.length) out.splice(arrIndexOf(out, null), 0, "|", ...loose);
4737
+ return out;
4738
+ }
4739
+ function arrIndexOf(items, where) {
4740
+ const mainEnd = (() => {
4741
+ const at2 = items.indexOf(":tail");
4742
+ return at2 < 0 ? items.length : at2;
4743
+ })();
4744
+ if (where == null || where === "end") return mainEnd;
4745
+ if (where === "start") return 0;
4746
+ if (where === "tail") return items.length;
4747
+ if (typeof where === "number") {
4748
+ let seen = 0;
4749
+ for (let i = 0; i < items.length; i++) {
4750
+ if (!isButtonItem(items[i])) continue;
4751
+ if (seen === Math.max(0, Math.floor(where))) return i;
4752
+ seen++;
4753
+ }
4754
+ return mainEnd;
4755
+ }
4756
+ const after = !!(where && typeof where === "object" && where.after);
4757
+ const name = String(typeof where === "string" ? where : (after ? where.after : where.before) || "");
4758
+ const at = items.indexOf(name);
4759
+ if (at < 0) return mainEnd;
4760
+ return after ? at + 1 : at;
4621
4761
  }
4622
4762
  function buildStatusbar(editor) {
4623
4763
  const chars = h("b", { text: "0" });
@@ -4710,7 +4850,7 @@ function previewHtml(html) {
4710
4850
  });
4711
4851
  return root.innerHTML;
4712
4852
  }
4713
- const version = "1.0.2";
4853
+ const version = "1.0.3";
4714
4854
  function create(target, options = {}) {
4715
4855
  return new KEditor(target, options);
4716
4856
  }
@@ -4740,6 +4880,7 @@ export {
4740
4880
  mount,
4741
4881
  normalizeCustomButtons,
4742
4882
  normalizeItems,
4883
+ normalizePosition,
4743
4884
  replace,
4744
4885
  sanitizeHtml,
4745
4886
  simpleAdapter,
@@ -14,6 +14,7 @@
14
14
  --ke-bg: #f6f7f9;
15
15
  --ke-radius: 10px;
16
16
  --ke-paper: 677px;
17
+ --ke-paper-gap: 24px;
17
18
  --ke-shadow: 0 1px 2px rgba(16, 24, 40, .04), 0 8px 24px rgba(16, 24, 40, .06);
18
19
  font-family: -apple-system, BlinkMacSystemFont, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
19
20
  color: var(--ke-text);
@@ -286,6 +287,11 @@
286
287
  border-radius: 8px; box-shadow: var(--ke-shadow); padding: 32px;
287
288
  min-height: var(--ke-min-height, 320px);
288
289
  }
290
+ /* 宽屏:版心随容器生长,两侧留白恒定为 --ke-paper-gap,不再随屏宽放大 */
291
+ .ke-paper.ke-is-fluid {
292
+ width: min(100%, max(calc(var(--ke-paper) + 64px), calc(100% - var(--ke-paper-gap) * 2)));
293
+ max-width: var(--ke-paper-max, none);
294
+ }
289
295
  .ke-content { outline: none; font-size: 17px; line-height: 1.75; color: var(--ke-text); word-break: break-word; }
290
296
  .ke-content:empty::before,
291
297
  .ke-content[data-placeholder].ke-is-empty::before {
@@ -1870,12 +1876,35 @@
1870
1876
  function normalizeItems(raw) {
1871
1877
  return pickArray(raw).map(normalizeItem).filter(Boolean);
1872
1878
  }
1879
+ function normalizePosition(spec = {}) {
1880
+ const raw = spec.position !== void 0 ? spec.position : spec.at;
1881
+ const num = (value) => Math.max(0, Math.floor(Number(value)));
1882
+ const named = (value) => typeof value === "object" && value ? value.before || value.after : value;
1883
+ if (typeof raw === "number" && Number.isFinite(raw)) return num(raw);
1884
+ if (typeof raw === "string" && raw) {
1885
+ const key = raw.toLowerCase();
1886
+ if (key === "start" || key === "begin" || key === "first") return "start";
1887
+ if (key === "end" || key === "last" || key === "main") return "end";
1888
+ if (key === "tail" || key === ":tail" || key === "right") return "tail";
1889
+ return { before: raw };
1890
+ }
1891
+ if (raw && typeof raw === "object") {
1892
+ if (raw.before) return { before: String(named(raw)) };
1893
+ if (raw.after) return { after: String(named(raw)) };
1894
+ }
1895
+ if (typeof spec.index === "number" && Number.isFinite(spec.index)) return num(spec.index);
1896
+ if (spec.before) return { before: String(spec.before) };
1897
+ if (spec.after) return { after: String(spec.after) };
1898
+ return null;
1899
+ }
1873
1900
  function normalizeCustomButton(spec) {
1874
1901
  if (!spec || typeof spec !== "object") return null;
1875
1902
  const name = String(spec.name || "").trim();
1876
1903
  if (!name) return null;
1877
1904
  return {
1878
1905
  name,
1906
+ /** 在工具栏里的位置(null = 默认追加到主区末尾) */
1907
+ position: normalizePosition(spec),
1879
1908
  type: spec.type === "button" ? "button" : "select",
1880
1909
  title: spec.title || spec.text || name,
1881
1910
  text: spec.text || "",
@@ -2112,7 +2141,6 @@
2112
2141
  "clear",
2113
2142
  ":tail",
2114
2143
  "source",
2115
- "preview",
2116
2144
  "fullscreen"
2117
2145
  ];
2118
2146
  const ITEMS = {
@@ -2138,6 +2166,7 @@
2138
2166
  clear: { icon: "clear", title: "清除格式", run: (e) => e.commands.clearFormat() },
2139
2167
  source: { icon: "source", title: "查看 / 编辑 HTML 源码(⌘/Ctrl+Shift+K)", text: "源码", run: (e) => e.toggleSource(), active: (s) => s.source },
2140
2168
  preview: { icon: "preview", title: "预览效果(手机 / 平板 / 电脑宽度)", text: "预览", run: (e) => e.togglePreview(), active: (s) => s.preview },
2169
+ // 默认工具栏已不包含,可用 toolbar / position 显式摆放
2141
2170
  fullscreen: { icon: "expand", title: "全屏编辑", text: "全屏", run: (e) => e.toggleFullscreen(), active: (s) => s.fullscreen },
2142
2171
  foreColor: { pop: "fore", title: "字体颜色", toggles: true, swatch: "fore" },
2143
2172
  backColor: { pop: "back", title: "背景高亮色", toggles: true, swatch: "back" }
@@ -2189,11 +2218,9 @@
2189
2218
  target().appendChild(this.buildButton(key, spec));
2190
2219
  }
2191
2220
  for (const [name, entry] of this.custom) {
2192
- if (!entry.button) {
2193
- entry.button = this.buildCustomButton(entry);
2194
- target().appendChild(entry.button);
2195
- }
2196
- entry.button.dataset.kCustom = name;
2221
+ if (entry.button) continue;
2222
+ entry.button = this.buildCustomButton(entry);
2223
+ this.insertButton(entry.button, entry.spec.position);
2197
2224
  }
2198
2225
  }
2199
2226
  buildButton(name, spec) {
@@ -2323,7 +2350,7 @@
2323
2350
  class: isSelect ? "ke-btn-label ke-btn-custom" : "ke-btn-custom",
2324
2351
  title: spec.title,
2325
2352
  "data-k-item": spec.name,
2326
- dataset: { kPop: spec.name },
2353
+ dataset: { kPop: spec.name, kCustom: spec.name },
2327
2354
  onclick: (event) => {
2328
2355
  event.preventDefault();
2329
2356
  if (isSelect) this.openCustom(spec.name);
@@ -2399,27 +2426,67 @@
2399
2426
  }
2400
2427
  this.editor.refresh();
2401
2428
  }
2402
- /** 运行时新增自定义按钮;at 为 toolbar 内插入位置(默认追加到主分组末尾) */
2403
- addButton(spec, { at } = {}) {
2429
+ /** 运行时新增自定义按钮;位置取 options.at ?? spec.position(默认追加到主分组末尾) */
2430
+ addButton(spec, options = {}) {
2404
2431
  var _a;
2405
2432
  const entry = this.registerCustom(spec);
2406
2433
  if (!entry) return null;
2407
2434
  if (entry.button) entry.button.remove();
2408
2435
  entry.button = this.buildCustomButton(entry);
2409
- const host = this.tailEl || this.groupEl;
2410
- if (!host) return entry.button;
2411
- if (typeof at === "number" && at >= 0) {
2412
- const ref = host.children[Math.min(at, host.children.length)];
2413
- host.insertBefore(entry.button, ref || null);
2414
- } else {
2415
- const sep2 = h("span.ke-tb-sep");
2416
- host.appendChild(sep2);
2417
- host.appendChild(entry.button);
2418
- }
2436
+ const where = options.at !== void 0 ? options.at : normalizePosition(options) ?? entry.spec.position;
2437
+ this.insertButton(entry.button, where, { withSep: where == null });
2419
2438
  this.revealButton(entry.button);
2420
2439
  (_a = this.syncScrollHints) == null ? void 0 : _a.call(this);
2421
2440
  return entry.button;
2422
2441
  }
2442
+ /** 工具栏内可定位的节点(主区 → 尾区的视觉顺序,不含分隔符) */
2443
+ buttonNodes() {
2444
+ const list = [];
2445
+ for (const host of [this.groupEl, this.tailEl]) {
2446
+ if (!host) continue;
2447
+ for (const node of host.children) if (node.dataset && node.dataset.kItem) list.push(node);
2448
+ }
2449
+ return list;
2450
+ }
2451
+ /** 位置描述 → {parent, ref},ref 为 null 表示追加到 parent 末尾 */
2452
+ slotOf(where) {
2453
+ const mainEnd = { parent: this.groupEl || this.el, ref: null };
2454
+ if (where === "tail") return { parent: this.tailEl || this.groupEl || this.el, ref: null };
2455
+ if (where == null || where === "end") return mainEnd;
2456
+ if (where === "start") {
2457
+ const first2 = this.buttonNodes()[0];
2458
+ return first2 ? { parent: first2.parentElement, ref: first2 } : mainEnd;
2459
+ }
2460
+ const nodes = this.buttonNodes();
2461
+ if (typeof where === "number") {
2462
+ const ref = nodes[Math.max(0, Math.floor(where))];
2463
+ if (ref) return { parent: ref.parentElement, ref };
2464
+ const last = nodes[nodes.length - 1];
2465
+ return last ? { parent: last.parentElement, ref: null } : mainEnd;
2466
+ }
2467
+ const after = !!(where && typeof where === "object" && where.after);
2468
+ const name = typeof where === "string" ? where : String((after ? where.after : where.before) || "");
2469
+ const anchor = nodes.find((node) => node.dataset.kItem === name);
2470
+ if (!anchor) return mainEnd;
2471
+ return { parent: anchor.parentElement, ref: after ? anchor.nextElementSibling || null : anchor };
2472
+ }
2473
+ insertButton(button, where, { withSep } = {}) {
2474
+ const { parent, ref } = this.slotOf(where);
2475
+ if (!parent || !button) return;
2476
+ if (withSep && !ref) parent.appendChild(h("span.ke-tb-sep"));
2477
+ parent.insertBefore(button, ref || null);
2478
+ }
2479
+ /** 运行时把任意按钮(内置或自定义)移到指定位置 */
2480
+ moveButton(name, where) {
2481
+ var _a, _b;
2482
+ const node = this.buttonNodes().find((item) => item.dataset.kItem === String(name));
2483
+ if (!node) return false;
2484
+ node.remove();
2485
+ this.insertButton(node, where === void 0 ? ((_a = this.custom.get(String(name))) == null ? void 0 : _a.spec.position) ?? null : where);
2486
+ this.revealButton(node);
2487
+ (_b = this.syncScrollHints) == null ? void 0 : _b.call(this);
2488
+ return true;
2489
+ }
2423
2490
  /** 工具栏溢出时把按钮滚进可视区(避开 sticky 尾栏的遮挡) */
2424
2491
  revealButton(button) {
2425
2492
  const tb = this.el;
@@ -2435,15 +2502,18 @@
2435
2502
  }
2436
2503
  /** 移除自定义按钮并中断其未完成的请求 */
2437
2504
  removeButton(name) {
2438
- var _a, _b;
2505
+ var _a, _b, _c, _d;
2439
2506
  const entry = this.custom.get(name);
2440
2507
  if (!entry) return false;
2441
2508
  abortRuntime(entry.rt);
2442
2509
  if (this.editor.popover.anchor === entry.button) this.editor.popover.close();
2443
- (_a = entry.button) == null ? void 0 : _a.remove();
2510
+ const prev = (_a = entry.button) == null ? void 0 : _a.previousElementSibling;
2511
+ const next = (_b = entry.button) == null ? void 0 : _b.nextElementSibling;
2512
+ (_c = entry.button) == null ? void 0 : _c.remove();
2513
+ if (prev && prev.classList.contains("ke-tb-sep") && (!next || next.classList.contains("ke-tb-sep"))) prev.remove();
2444
2514
  this.buttons.delete(name);
2445
2515
  this.custom.delete(name);
2446
- (_b = this.syncScrollHints) == null ? void 0 : _b.call(this);
2516
+ (_d = this.syncScrollHints) == null ? void 0 : _d.call(this);
2447
2517
  return true;
2448
2518
  }
2449
2519
  /** 外部灌入下拉数据(接口在编辑器之外请求时用),并刷新已打开的面板 */
@@ -3985,6 +4055,13 @@
3985
4055
  minHeight: 320,
3986
4056
  primaryColor: "#07c160",
3987
4057
  paperWidth: 677,
4058
+ // 版心基准宽度:窄屏上限、宽屏最小宽度
4059
+ /** 版心宽度模式:'fluid' 宽屏随容器生长(两侧留白恒定)| 'fixed' 恒定版心 */
4060
+ paperMode: "fluid",
4061
+ paperGap: 24,
4062
+ // fluid 模式下单侧留白(px)
4063
+ paperMaxWidth: 0,
4064
+ // fluid 模式下版心最大宽度,0 = 不限
3988
4065
  toolbar: DEFAULT_TOOLBAR,
3989
4066
  /** 自定义工具栏按钮(下拉选择,数据可静态配置或从接口读取) */
3990
4067
  customButtons: [],
@@ -4088,8 +4165,30 @@
4088
4165
  this.scrollEl.style.height = `${this.options.height}px`;
4089
4166
  this.scrollEl.style.maxHeight = `${this.options.height}px`;
4090
4167
  }
4091
- this.paperEl.style.setProperty("--ke-paper", `${this.options.paperWidth}px`);
4092
4168
  this.paperEl.style.setProperty("--ke-min-height", `${this.options.minHeight}px`);
4169
+ this.applyPaper();
4170
+ }
4171
+ /** 版心尺寸:宽屏下默认让版心随容器生长,两侧只保留固定留白 */
4172
+ applyPaper() {
4173
+ const { paperWidth, paperMode, paperGap, paperMaxWidth } = this.options;
4174
+ this.paperEl.style.setProperty("--ke-paper", `${paperWidth}px`);
4175
+ this.paperEl.style.setProperty("--ke-paper-gap", `${paperGap}px`);
4176
+ if (paperMaxWidth > 0) this.paperEl.style.setProperty("--ke-paper-max", `${paperMaxWidth}px`);
4177
+ else this.paperEl.style.removeProperty("--ke-paper-max");
4178
+ this.paperEl.classList.toggle("ke-is-fluid", paperMode !== "fixed");
4179
+ }
4180
+ /** 运行时调整版心:{width, mode, gap, maxWidth}(mode: 'fluid' | 'fixed') */
4181
+ setPaper(config = {}) {
4182
+ if (config.width !== void 0) this.options.paperWidth = clamp$1(Number(config.width) || 0, 200, 8e3);
4183
+ if (config.mode !== void 0) this.options.paperMode = config.mode === "fixed" ? "fixed" : "fluid";
4184
+ if (config.gap !== void 0) this.options.paperGap = clamp$1(Number(config.gap) || 0, 0, 600);
4185
+ if (config.maxWidth !== void 0) this.options.paperMaxWidth = Math.max(0, Number(config.maxWidth) || 0);
4186
+ this.applyPaper();
4187
+ return { ...this.paperOptions() };
4188
+ }
4189
+ paperOptions() {
4190
+ const { paperWidth, paperMode, paperGap, paperMaxWidth } = this.options;
4191
+ return { width: paperWidth, mode: paperMode, gap: paperGap, maxWidth: paperMaxWidth };
4093
4192
  }
4094
4193
  applyTheme() {
4095
4194
  if (this.options.primaryColor) this.el.style.setProperty("--ke-primary", this.options.primaryColor);
@@ -4425,6 +4524,10 @@
4425
4524
  addButton(spec, options) {
4426
4525
  return this.toolbar.addButton(spec, options);
4427
4526
  }
4527
+ /** 运行时移动任意按钮位置(内置或自定义);where 同 spec.position 语义 */
4528
+ moveButton(name, where) {
4529
+ return this.toolbar.moveButton(name, where);
4530
+ }
4428
4531
  /** 移除自定义按钮,并中断其未完成的接口请求 */
4429
4532
  removeButton(name) {
4430
4533
  return this.toolbar.removeButton(name);
@@ -4612,16 +4715,53 @@
4612
4715
  if (Array.isArray(options.toolbar)) out.toolbar = options.toolbar;
4613
4716
  if (options.toolbar === false) out.toolbar = [];
4614
4717
  if (options.toolbar === true) out.toolbar = DEFAULT_TOOLBAR;
4615
- if (out.customButtons.length && options.toolbar === void 0) {
4616
- out.toolbar = appendCustomNames(DEFAULT_TOOLBAR, out.customButtons.map((spec) => spec.name));
4718
+ if (out.customButtons.length && options.toolbar !== false) {
4719
+ out.toolbar = placeCustomNames(out.toolbar, out.customButtons);
4617
4720
  }
4618
4721
  out.height = clamp$1(out.height ?? 460, 0, 4e3);
4722
+ out.paperWidth = clamp$1(Number(out.paperWidth) || defaults.paperWidth, 200, 8e3);
4723
+ out.paperMode = out.paperMode === "fixed" ? "fixed" : "fluid";
4724
+ out.paperGap = Number.isFinite(Number(out.paperGap)) ? clamp$1(Number(out.paperGap), 0, 600) : defaults.paperGap;
4725
+ out.paperMaxWidth = Math.max(0, Number(out.paperMaxWidth) || 0);
4619
4726
  return out;
4620
4727
  }
4621
- function appendCustomNames(items, names) {
4622
- const at = items.indexOf(":tail");
4623
- const insert = ["|", ...names];
4624
- return at < 0 ? [...items, ...insert] : [...items.slice(0, at), ...insert, ...items.slice(at)];
4728
+ const isButtonItem = (key) => key !== "|" && key !== ":tail";
4729
+ function placeCustomNames(items, specs) {
4730
+ const out = [...items];
4731
+ const loose = [];
4732
+ for (const spec of specs) {
4733
+ if (out.includes(spec.name)) continue;
4734
+ if (spec.position == null) {
4735
+ loose.push(spec.name);
4736
+ continue;
4737
+ }
4738
+ out.splice(arrIndexOf(out, spec.position), 0, spec.name);
4739
+ }
4740
+ if (loose.length) out.splice(arrIndexOf(out, null), 0, "|", ...loose);
4741
+ return out;
4742
+ }
4743
+ function arrIndexOf(items, where) {
4744
+ const mainEnd = (() => {
4745
+ const at2 = items.indexOf(":tail");
4746
+ return at2 < 0 ? items.length : at2;
4747
+ })();
4748
+ if (where == null || where === "end") return mainEnd;
4749
+ if (where === "start") return 0;
4750
+ if (where === "tail") return items.length;
4751
+ if (typeof where === "number") {
4752
+ let seen = 0;
4753
+ for (let i = 0; i < items.length; i++) {
4754
+ if (!isButtonItem(items[i])) continue;
4755
+ if (seen === Math.max(0, Math.floor(where))) return i;
4756
+ seen++;
4757
+ }
4758
+ return mainEnd;
4759
+ }
4760
+ const after = !!(where && typeof where === "object" && where.after);
4761
+ const name = String(typeof where === "string" ? where : (after ? where.after : where.before) || "");
4762
+ const at = items.indexOf(name);
4763
+ if (at < 0) return mainEnd;
4764
+ return after ? at + 1 : at;
4625
4765
  }
4626
4766
  function buildStatusbar(editor) {
4627
4767
  const chars = h("b", { text: "0" });
@@ -4714,7 +4854,7 @@
4714
4854
  });
4715
4855
  return root.innerHTML;
4716
4856
  }
4717
- const version = "1.0.2";
4857
+ const version = "1.0.3";
4718
4858
  function create(target, options = {}) {
4719
4859
  return new KEditor(target, options);
4720
4860
  }
@@ -4743,6 +4883,7 @@
4743
4883
  exports2.mount = mount;
4744
4884
  exports2.normalizeCustomButtons = normalizeCustomButtons;
4745
4885
  exports2.normalizeItems = normalizeItems;
4886
+ exports2.normalizePosition = normalizePosition;
4746
4887
  exports2.replace = replace;
4747
4888
  exports2.sanitizeHtml = sanitizeHtml;
4748
4889
  exports2.simpleAdapter = simpleAdapter;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kyle-editor",
3
- "version": "1.0.2",
3
+ "version": "1.0.3",
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,custom,customload,customerr,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,posbtn,wide,widefix,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",
package/types/index.d.ts CHANGED
@@ -141,9 +141,29 @@ export type BuiltinToolbarItem =
141
141
  | 'source' | 'preview' | 'fullscreen'
142
142
  | '|' | ':tail'
143
143
 
144
- /** 工具栏项:内置名称、分隔符 `|`、`:tail`,或 customButtons 里定义的自定义按钮 name */
144
+ /**
145
+ * 工具栏项:内置名称、分隔符 `|`、`:tail`,或 customButtons 里定义的自定义按钮 name */
145
146
  export type ToolbarItem = BuiltinToolbarItem | (string & {})
146
147
 
148
+ /**
149
+ * 按钮在工具栏里的位置(自定义按钮的 `position`,addButton / moveButton 的目标位):
150
+ * - `number`:第 n 个按钮之前(0 起,按视觉顺序计数,分隔符不计数)
151
+ * - `'start'`:工具栏最前
152
+ * - `'end'`:主区末尾(尾栏之前,默认)
153
+ * - `'tail'`:右侧吸附尾栏末尾
154
+ * - `'link'` 等按钮名:插到该按钮之前
155
+ * - `{ before: name }` / `{ after: name }`:显式锚点
156
+ */
157
+ export type ButtonPosition = number | 'start' | 'end' | 'tail' | (string & {}) | { before: string } | { after: string }
158
+
159
+ /** addButton / moveButton 的位置参数(at 优先于 before / after / index) */
160
+ export interface ButtonPlaceOptions {
161
+ at?: ButtonPosition
162
+ before?: string
163
+ after?: string
164
+ index?: number
165
+ }
166
+
147
167
  /* ------------------------------ 自定义工具栏按钮 ------------------------------ */
148
168
 
149
169
  /** 下拉选项;也接受纯字符串或接口原始对象(自动识别 value/id/key、label/name/title 等常见字段) */
@@ -215,6 +235,17 @@ export interface CustomButtonSpec {
215
235
  /** 记住选中项并在按钮上回显,默认 true */
216
236
  keepValue?: boolean
217
237
 
238
+ /** 按钮在工具栏中的位置,默认追加到主区末尾(尾栏之前) */
239
+ position?: ButtonPosition
240
+ /** position 别名(与 addButton 的 options.at 同义) */
241
+ at?: ButtonPosition
242
+ /** 简写:插到某按钮之前 */
243
+ before?: string
244
+ /** 简写:插到某按钮之后 */
245
+ after?: string
246
+ /** 简写:第 n 个按钮之前 */
247
+ index?: number
248
+
218
249
  /** 数据源①:静态配置 */
219
250
  options?: CustomButtonOption[] | string[]
220
251
  /** 数据源②:自定义加载函数(可返回 Promise) */
@@ -255,8 +286,14 @@ export interface KEditorOptions {
255
286
  minHeight?: number
256
287
  /** 主题色,默认微信绿 #07c160 */
257
288
  primaryColor?: string
258
- /** 正文版心宽度,默认 677(公众号) */
289
+ /** 版心基准宽度,默认 677(公众号);fluid 模式下它是最小宽度 */
259
290
  paperWidth?: number
291
+ /** 版心宽度模式:'fluid'(默认,宽屏版心随容器生长)| 'fixed'(恒定 paperWidth + 64) */
292
+ paperMode?: 'fluid' | 'fixed'
293
+ /** fluid 模式下单侧留白,默认 24 */
294
+ paperGap?: number
295
+ /** fluid 模式下载心最大宽度,0 = 不限 */
296
+ paperMaxWidth?: number
260
297
  /** 工具栏配置;false 隐藏。留空且配置了 customButtons 时,自定义按钮自动追加到默认工具栏 */
261
298
  toolbar?: ToolbarItem[] | boolean
262
299
  /** 自定义工具栏按钮(下拉选择,数据可静态配置或从接口读取) */
@@ -386,7 +423,9 @@ export declare class KEditor {
386
423
  openMedia(kind: 'image' | 'video'): void
387
424
  openTable(): void
388
425
  openCustom(name: string): void
389
- addButton(spec: CustomButtonSpec, options?: { at?: number }): HTMLElement | null
426
+ addButton(spec: CustomButtonSpec, options?: ButtonPlaceOptions): HTMLElement | null
427
+ moveButton(name: string, where?: ButtonPosition): boolean
428
+ buttonNodes(): HTMLElement[]
390
429
  removeButton(name: string): boolean
391
430
  setButtonOptions(name: string, items: unknown): CustomButtonOption[]
392
431
  }
@@ -428,8 +467,13 @@ export declare class KEditor {
428
467
  cancelUploads(): this
429
468
 
430
469
  /** 运行时新增自定义按钮,返回按钮 DOM */
431
- addButton(spec: CustomButtonSpec, options?: { at?: number }): HTMLElement | null
470
+ addButton(spec: CustomButtonSpec, options?: ButtonPlaceOptions): HTMLElement | null
471
+ /** 移动任意按钮(内置或自定义)到指定位置 */
472
+ moveButton(name: string, where?: ButtonPosition): boolean
432
473
  removeButton(name: string): boolean
474
+ /** 运行时调整版心:{ width, mode, gap, maxWidth } */
475
+ setPaper(config?: { width?: number; mode?: 'fluid' | 'fixed'; gap?: number; maxWidth?: number }): { width: number; mode: 'fluid' | 'fixed'; gap: number; maxWidth: number }
476
+ paperOptions(): { width: number; mode: 'fluid' | 'fixed'; gap: number; maxWidth: number }
433
477
  /** 外部灌入下拉数据(接口在编辑器之外请求时使用) */
434
478
  setButtonOptions(name: string, items: CustomButtonOption[] | string[]): CustomButtonOption[]
435
479
  getButtonValue(name: string): CustomButtonOption | null
@@ -462,6 +506,7 @@ export declare function replace(target: HTMLElement | string, options?: KEditorO
462
506
  export declare const defaults: KEditorOptions
463
507
  export declare const DEFAULT_TOOLBAR: ToolbarItem[]
464
508
  export declare function normalizeCustomButtons(list: unknown): CustomButtonSpec[]
509
+ export declare function normalizePosition(spec: unknown): ButtonPosition | null
465
510
  export declare function normalizeItems(raw: unknown): CustomButtonOption[]
466
511
  export declare function exportHtml(html: string): string
467
512