@one2x/medeo-rte 0.4.10 → 1.0.0

package/README.md

@@ -11,6 +11,8 @@ demo/    演示应用，也是用法样例，不参与发布
 
 SDK 只负责编辑区。工具栏、状态栏、小地图由宿主自己做，可参考 `demo/main.ts`。
 
+业务怎么调、有哪些参数和事件，见 **[API 文档](./docs/api.md)**。
+
 ## 安装
 
 ```bash
@@ -45,301 +47,15 @@ new Editor(el, { plugins: [...builtinEmbedPlugins, formulaPlugin] });
 - 表格、图片、视频、代码块、公式、图文绕排
 - Markdown 边打边转、撤销重做、中文输入法
 - 两种芯片：`internalSlot`（SDK 内置）、`hostSlot`（宿主自绘）。整颗换行
-- `mark`：盖在正文上的样式区间，按字折行。底色、边框、圆角、内外边距、悬停、空态灰字、生成中状态
+- `mark`：盖在正文上的样式区间，按字折行
 - 同步块：选区提成可复用内容，改一处全变
 - 绘制后端：`html` / `canvas`
 
-| | `internalSlot` | `hostSlot` | `mark` |
-| --- | --- | --- | --- |
-| 是什么 | SDK 内置芯片 | 宿主自绘芯片 | 样式叠层，字仍是正文 |
-| 落在哪 | 流上一个 `*` | 同上 | 不占字符，区间 `[start, end)` |
-| 折行 | 整颗盒子 | 整颗盒子 | 按字折行 |
-| 插入 | `commands.insertSlot` | `insertHostEmbed` / `insertSlice` | `insertVirtualBlock` / `insertSlice` |
-
-更细的 mark 模型见 [docs/virtual-blocks.md](./docs/virtual-blocks.md)。
-
-## 构造参数
-
-`new Editor(el, options?)`。
-
-| 字段 | 默认 | 含义 |
-| --- | --- | --- |
-| `doc` | 空文档 | 初始 `DocumentModel` |
-| `paint` | `'html'` | 绘制后端，`'html'` 或 `'canvas'` |
-| `plugins` | `builtinEmbedPlugins` | 嵌入插件。公式要另外追加 `formulaPlugin` |
-| `width` | `'fill'` | `'fill'` 撑满容器并随容器重排；数字是固定内容宽（像素） |
-| `padding` | `{ x: 72, y: 56 }` | 版心内边距。紧凑输入框可传 `{ x: 0, y: 0 }` |
-| `hostEmbed` | 无 | 宿主渲染器。提供后才能插入 `hostSlot` |
-| `placeholder` | 无 | 空文档占位文案。组合输入一开始就隐藏 |
-| `textDefaults` | 16px / `#1f2329` | 没写文字样式时的默认属性，见下表 |
-| `shortcuts` | `SHORTCUTS` | 快捷键表。输入框用 `inputShortcuts()` |
-| `autofocus` | `true` | 创建后是否聚焦。嵌在页面里应传 `false` |
-| `chrome` | 实心光标、扁平选区 | 编辑器装饰，见「全局 chrome」。不是 mark 的皮 |
-| `perfPanel` | `false` | 左下角性能面板。也可用 `setPerfPanel` |
-
-### textDefaults
-
-写在文档上，主题切换用 `setTextDefaults`。`fontFamily` 不要用 `system-ui`。`lineHeight` 只在这里生效，写在单个文字 span 上会被忽略。
-
-| 字段 | 含义 |
-| --- | --- |
-| `fontSize` | 字号，像素。默认 16 |
-| `fontFamily` | 字体栈。会写成 `--mini-font-family`，测宽和绘制用同一套 |
-| `fontWeight` | 字重。默认 400。`bold: true` 时绘制仍用 700 |
-| `color` | 默认字色 `#1f2329` |
-| `bold` / `italic` | 默认是否加粗、斜体 |
-| `lineHeight` | 数字是字号倍数；`'24px'` 是固定像素。不传按 `round(字号 × 1.6)` |
-| `lineGap` | 行与行之间的额外间距，像素。留在行盒外面，下一行整行下移。不传是 0。用来让折行后的边框不再贴在一起 |
-
-## CSS 变量
-
-都写在 `.mini-editor` 上，不要写到 `:root`。
-
-全局 chrome 和 `textDefaults` 会改其中一部分。光标高度、选区高度只有 CSS，没有 chrome 字段：宿主自己设在 `.mini-editor` 上。
-
-| 变量 | 谁来写 | 含义 |
-| --- | --- | --- |
-| `--mini-caret-color` | `chrome.caretColor` | 实心光标颜色。默认 `#09090b` |
-| `--mini-caret-width` | `chrome.caretWidth` | 实心光标宽度。默认 `2px` |
-| `--mini-caret-height` | 只能 CSS | 实心光标高度，像素。不设则铺满行高，设了就在行内居中收短。彩虹光标不用 |
-| `--mini-sel-color` | `chrome.selectionColor` | 选区高亮色。默认 `rgba(43, 108, 255, 0.22)` |
-| `--mini-sel-radius` | `chrome.selectionRadius` | 选区圆角。默认 `0px` |
-| `--mini-sel-height` | 只能 CSS | 选区高亮和选区焦点标记的高度，像素。不设则铺满行高，设了就居中收短。焦点圆点贴着收短后的顶 |
-| `--mini-sel-focus-color` | SDK 固定写入 | 选区焦点标记颜色，固定 `#2b6cff`。chrome 不能改 |
-| `--mini-ime-underline-color` | `chrome.composeUnderlineColor` | 中文输入中间态下划线颜色。默认 `#1f2329` |
-| `--mini-ime-underline-width` | `chrome.composeUnderlineWidth` | 下划线粗细。默认 `2px` |
-| `--mini-font-family` | `textDefaults.fontFamily` | 编辑器默认字体栈 |
-| `--mini-font-weight` | `textDefaults.fontWeight` | 编辑器默认字重 |
-| `--mini-content-width` | SDK 按排版写入 | 内容宽。宿主不要自己设 |
-
-另外：`data-caret="solid"|"rainbow"` 由 `chrome.caret` 写入；`data-surface="paper"|"transparent"` 由 `chrome.surfaceBackground` 写入。
-
-画布和 `.mini-page-wrap` 左右各多留 5px（负 margin 抵消，文字位置不变），给贴边的 mark 内边距用。覆盖 `.mini-page-wrap` 的 `padding` 时保留 `padding-inline: 5px; margin-inline: -5px;`，否则文字会左移 5px，贴边的内边距会被裁。
-
-## 全局 chrome
-
-`EditorChrome`，构造时的 `chrome` 或之后的 `setChrome(patch)`。`setChrome` 只覆盖传入的字段。
-
-这是编辑器装饰：光标、选区、输入法下划线、空文档占位、纸张底。和 mark 的 `chrome` 不是一回事。mark 的皮不能通过这里设，也不能通过上面的 CSS 变量设。
-
-| 字段 | 默认 | 含义 |
-| --- | --- | --- |
-| `caret` | `'solid'` | `'solid'` 实心光标；`'rainbow'` 彩虹光标 |
-| `caretColor` | `#09090b` | 实心光标颜色 |
-| `caretWidth` | `2` | 实心光标宽度，像素 |
-| `caretTrail` | `false` | 是否画光标残影 |
-| `selectionColor` | `rgba(43, 108, 255, 0.22)` | 选区高亮色。彩虹光标且未指定时，demo 用渐变选区 |
-| `selectionRadius` | `0` | 选区圆角，像素 |
-| `composeUnderlineColor` | `#1f2329` | 中文输入中间态下划线颜色 |
-| `composeUnderlineWidth` | `2` | 下划线粗细，像素 |
-| `placeholderColor` | | 空文档占位颜色 |
-| `placeholderOpacity` | | 空文档占位透明度，0–1 |
-| `surfaceBackground` | `'paper'` | `'paper'` 纸张白；`'transparent'` 透出宿主背景 |
-| `letterSpacing` | `0` | 字间距（px），加在每个字后面，同 CSS `letter-spacing`。整篇统一，正文排版、绘制和 mark 的 placeholder / label 都按它算；改了会整篇重排 |
-| `copyContentOnly` | `false` | 复制/剪切是否只带内容。`false`：mark（底色、边框、占位）随私有格式一起复制并在粘回时还原；`true`：只带文字、样式和 slot/图片/引用，不带 mark。纯文本、HTML 剪贴板不受影响 |
-
-光标高度、选区高度不在这张表里，用 `--mini-caret-height`、`--mini-sel-height`。
-
-## mark 的 chrome
-
-写在每个 mark 的 `chrome` 上。`updateVirtualBlock(id, chrome)` 按字段合并，没传的字段保持原值。
-
-静态底色和静态边框每一层都画。悬停时，只有指针下最上面、并且配了悬停底色或悬停边框的那一块换皮，它的每一行一起换。压在下面的 mark 继续画静态底色和静态边框，包括露在外面的其它行。灰字颜色仍是指针下每一层一起换。指针落在 mark 里的 `internalSlot` 或 `hostSlot` 上时，mark 不换悬停皮，只留芯片自己的悬停。
-
-折行后的边：上下边每段都画；左边只在首段，右边只在末段。圆角是首段左侧两角、末段右侧两角；只有一段时四角都圆。
-
-| 字段 | 默认 | 含义 |
-| --- | --- | --- |
-| `background` | 无 | 静态底色 |
-| `hoverBackground` | 无 | 悬停底色。只换指针下最上面那一块，这一块的每一行一起换。不进撤销 |
-| `border` | 无 | 静态边，`{ color, width? }`。`width` 不传是 1。不传就没有边 |
-| `hoverBorder` | 沿用 `border` | 悬停边，形状同 `border`。只换指针下最上面那一块，这一块的每一行一起换。不进撤销 |
-| `selectedBackground` | 无 | 方向键整段选中这块时的底色。光标只是停在里面不换。没传就仍用 `background`。同一块既悬停又选中时显示选中皮（没配选中皮则仍显示悬停皮）。不进撤销 |
-| `selectedBorder` | 沿用 `border` | 同上时的边。指针正悬停在这块上时，悬停皮盖过选中皮。不进撤销 |
-| `radius` | `3` | 圆角，像素 |
-| `paddingX` | `4` | 水平内边距，留在底色里面。每一行文字都缩进；区间真正的首尾这段空白还占排版宽度。传 `0` 表示不留 |
-| `paddingY` | `0` | 上下内边距，留在这块自己的底色里。盖住的行按同一行里最大的值变高，文字居中。没配的内层仍贴着文字。不画进相邻行 |
-| `marginX` | `0` | 底色边缘到外面文字的间距，前后同一段。只加在区间真正的首尾 |
-| `color` | | 文字颜色。这个字自己有颜色时用正文，否则用这里 |
-| `fontSize` | | 字号。传了就盖过正文，没传才继承。占位灰字和生成中的文案同样 |
-| `fontFamily` | | 字体栈。优先级同 `fontSize` |
-| `fontWeight` | | 字重。优先级同 `fontSize` |
-| `bold` | | 加粗。优先级同 `fontSize` |
-| `italic` | | 斜体。优先级同 `fontSize` |
-| `placeholderColor` | `#c5ccd6` | 空态灰字颜色。透明度写在颜色里 |
-| `hoverPlaceholderColor` | 无 | 悬停时灰字颜色。不进撤销。生成中的文案不换 |
-| `selectable` | `true` | 光标能否进入。`false` 时左右、上下和点击都不会把光标留在里面：mark 整段跳过，芯片不选中、停在旁边 |
-
-多层重叠时，字体字段是内层盖过外层：内层写了的用内层，没写的用外层。
-
-### mark 怎么用
-
-虚拟块目前只有 `mark`。`parentId` 恒为 `null`，可以重叠。用户打字不会新建 mark。日常编辑不用自己维护 `[start, end)`，插删字时 SDK 会挪区间。
-
-从外侧朝块内按方向键，只有配了 `selectedBackground` 或 `selectedBorder` 的 mark 会先整段选中，焦点留在来的这一侧；再朝内按一次才进入。没配选中皮的 mark 跳过这一步，方向键直接走进或走出。从内侧走到边界再往外，同样只对配了选中皮的块先整段选中。拖选或 Shift 不是这种选中态。上下键不走这套。重叠时，从外往里选范围最大、且配了选中皮的那一块，从里往外选范围最小、且配了选中皮的那一块。这种选中态不画选区高亮和焦点竖线，只换 mark 自己的选中皮。拖选和 Shift 仍画选区。光标只是停在 mark 里面时不换选中皮。
-
-光标落在块内的芯片上时，芯片用自己实体上的 `chrome` 换选中皮。选中变化发 `markselect` 或 `slotselect`。选中态下按 Enter 是进入内部（和朝内按方向键一样），不替换、不换行。文档开头（下标 0）按 ← 不处理。
-
-mark 的左右留白：`marginX` 只用来隔开同一行里 mark 旁边的文字；行首、行尾不留，mark 外框每一行的左右缘落在文字区边上、逐行对齐，`paddingX` 仍在底色里面。
-
-边界分内外侧。内侧输入算在块里，外侧输入留在块外。选区正好盖住一块 mark 时，焦点竖线和普通选区一样，停在焦点那一端的光标位置。
-
-没有 `placeholder` 时，区间里的字删光，块就拆掉。有 `placeholder` 时，只删这块里的字会收成零宽灰字，灰字不进正文。配了选中皮的零宽 mark，方向键会先停在选中态，再进灰字；没配的直接进出。选区比这块更大再删，或光标已经在灰字上、或正停在这块选中态时再按退格、删除，块会被拆掉。
-
-```ts
-const id = editor.insertVirtualBlock({
-  kind: 'mark',
-  placeholder: 'Describe a scene',
-  chrome: {
-    background: '#fff3bf',
-    hoverBackground: '#ffe066',
-    border: { color: '#d4a012', width: 1 },
-    hoverBorder: { color: '#926000', width: 1 },
-    selectedBackground: 'rgba(43, 108, 255, 0.16)',
-    selectedBorder: { color: '#2b6cff', width: 1 },
-    radius: 4,
-    paddingX: 5,
-    paddingY: 2,
-    marginX: 8,
-    placeholderColor: '#c5ccd6'
-  }
-});
-```
-
-生成中用 `setMarkStatus`，不进文档和撤销。有 `label` 就是锁定：有字的 mark 整块换成 `label`，里面的字、芯片、内层 mark 都不显示，宽度按 `label` 算，光标进不去，不能改，点击也不发 `markclick`；`locked` 已忽略。结束后先清状态，再用 `replaceMarkText` 写回，这一步单独占一次撤销。
-
-```ts
-editor.setMarkStatus(id, { label: 'Generating…', locked: true, text: 'rainbow', border: 'pulse' });
-editor.setMarkStatus(id, null);
-editor.replaceMarkText(id, 'a red bicycle');
-```
-
-`text: 'rainbow'` 只作用于 `label`。`border: 'pulse'` 是底色边缘的呼吸描边。块被拆掉或 `setContent` 之后，状态自动丢掉。
-
-整段模板用 `insertSlice`，`virtualBlocks` 里的下标相对这段 `text`。已有文字用 `insertVirtualBlock`，不传 `start` / `end` 就是当前选区。
-
-点击后的菜单位置用 `getVirtualBlockRect(id)`，返回屏幕坐标。
-
-## 编辑器 API
-
-下面是 `Editor` 上宿主会用到的全部公开成员。
-
-| 成员 | 说明 |
-| --- | --- |
-| `root` | 根节点 `.mini-editor` |
-| `scroller` | 滚动容器 |
-| `pageElement` | 内容定位上下文 |
-| `paint` | 当前绘制后端，`'html'` 或 `'canvas'` |
-| `commands` | 工具栏命令，见下表 |
-| `perf` | 性能探针。`start()` / `report()` / `stop()`，默认关闭 |
-| `on(event, fn)` | 订阅。返回退订函数。事件见下表 |
-| `getState()` | 工具栏用的状态快照 |
-| `getContent()` / `setContent(slice)` | 整篇读写。`setContent` 清空撤销栈，并丢掉全部 `setMarkStatus` |
-| `getDocument()` | 文档模型。改文档走 `operations` + `runOperation`，不要直接改内部表 |
-| `getLayout()` | 只读排版几何 |
-| `getSelection()` / `setSelection(sel)` | 选区读写 |
-| `insertSlice(slice, at?)` | 插入切片。不传 `at` 用当前光标 |
-| `insertVirtualBlock(spec)` | 套一层 mark。返回 id；建不成（没有范围、也没有 placeholder）时返回 `null` |
-| `updateVirtualBlock(id, chrome)` | 按字段合并这块的 chrome，进撤销 |
-| `removeVirtualBlock(id)` | 拆掉皮，字留下 |
-| `replaceMarkText(id, text)` | 换掉 mark 里的字，块和 id 留下，整步一次撤销。返回块是否存在 |
-| `setMarkStatus(id, status \| null)` | 生成中状态。不进文档、撤销和 `change` |
-| `getVirtualBlockRect(id)` | 屏幕坐标。`left/top/width/height` 是外接矩形，`lines` 是每一行。没有这块时返回 `null` |
-| `insertHostEmbed(hostType, data?, size?, at?, chrome?)` | 插入宿主芯片。`at` 为下标、`'start'`、`'end'` 或 `'cursor'`（默认）。`chrome` 与 mark 同一套 `VirtualBlockChrome`。SDK 在芯片外框上画底色、边框、圆角和字体；悬停、选中的优先级和 mark 一样。`paddingX` / `paddingY` / `marginX` 和占位灰字只参与 mark 的排版 |
-| `listEmbeds()` | 文档里全部嵌入对象，按位置排序 |
-| `setPaintMode('html' \| 'canvas')` | 切换绘制后端 |
-| `setChrome(patch)` | 合并全局 chrome |
-| `setTextDefaults(patch)` | 合并默认文字属性 |
-| `setPlaceholder(text)` | 改空文档占位 |
-| `setPerfPanel(on)` | 开关性能面板 |
-| `setDisabled(disabled)` | 禁用输入和快捷键 |
-| `focus()` | 聚焦 |
-| `composing()` | 是否正在中文输入组合 |
-| `destroy()` | 卸下编辑器 |
-
-### commands
-
-宿主工具栏调这些。方向键、删除、全选也在 `commands` 上，但通常留给键盘。
-
-| 命令 | 作用 |
-| --- | --- |
-| `toggleBold` / `toggleItalic` / `toggleUnderline` / `toggleStrike` | 切换文字样式 |
-| `setFontSize(size)` / `setColor(color)` | 字号、颜色 |
-| `setHeading(0\|1\|2\|3)` | 标题。`0` 是正文 |
-| `setAlign('left'\|'center'\|'right')` | 对齐 |
-| `toggleList('ul'\|'ol')` | 列表 |
-| `indent(delta)` | 缩进。`delta` 为 `1` 或 `-1` |
-| `insertImage(file)` / `insertVideo(file)` | 插入本地文件 |
-| `insertCode()` / `insertFormula()` | 代码块、公式 |
-| `insertSlot('text'\|'image'\|'select')` | 内置芯片 |
-| `insertHostEmbed(hostType, data?, size?)` | 宿主芯片。要指定落点用编辑器上的 `insertHostEmbed` |
-| `insertTable` / `addRow` / `addCol` / `removeRow` / `removeCol` | 表格 |
-| `toggleLink` | 链接 |
-| `promoteRef` / `insertRef` / `unlinkRef` | 把选区收成同步块、再插入一处、解除 |
-| `undo` / `redo` | 撤销、重做 |
-
-默认快捷键（`SHORTCUTS`）：Cmd/Ctrl+Z 撤销，Shift+Cmd/Ctrl+Z 或 Cmd/Ctrl+Y 重做，Cmd/Ctrl+B/I/U/K/A 为加粗、斜体、下划线、链接、全选。Enter 换段，Backspace / Delete 删除，Tab 在列表里改层级、在表格里跳格。左右是字符，Option 是词，Cmd 左右是行首行尾，Option 上下是段，Cmd 上下是文首文尾。Shift 扩选。
-
-输入框用 `inputShortcuts()`：保留撤销、选区、删除和方向键，吞掉加粗和链接。默认 Enter 换行，Cmd/Ctrl+Enter 不登记，留给宿主提交。
-
-### 事件
-
-| 事件 | 参数 | 何时 |
-| --- | --- | --- |
-| `change` | 无 | 文档内容变化 |
-| `selectionchange` | 无 | 选区或光标移动 |
-| `statechange` | 无 | `getState()` 里的字段可能变了，用来同步工具栏 |
-| `layoutchange` | 无 | 重新排版完成 |
-| `markclick` | `{ id }` | 点击 mark。锁定中不发，光标仍会落下 |
-| `markenter` | `{ id }` | 光标进入 mark，含空块和内侧边界 |
-| `markleave` | `{ id }` | 光标离开 mark |
-| `markselect` | `{ id }` | 光标所在最上层 mark 变了。`id` 为 `null` 表示当前没有 mark 选中。不进撤销 |
-| `slotselect` | `{ id }` | 光标落到 `internalSlot` 或 `hostSlot` 上，或从芯片上离开。芯片比盖住它的 mark 更靠上，这时 mark 不换选中皮 |
-
-### getState()
-
-| 字段 | 含义 |
-| --- | --- |
-| `bold` / `italic` / `underline` / `strikethrough` | 光标处是否已有该样式 |
-| `fontSize` / `color` | 光标处字号、颜色 |
-| `heading` | `0`–`3` |
-| `align` | `'left'` / `'center'` / `'right'` |
-| `list` | `'none'` / `'ul'` / `'ol'` |
-| `inTable` | 光标是否在表格里 |
-| `canUndo` / `canRedo` | 能否撤销、重做 |
-| `paintMode` | `'html'` 或 `'canvas'` |
-| `hasLink` | 光标是否在链接里 |
-| `canPromote` / `canInsertRef` / `canUnlink` | 同步块三个按钮是否可用 |
-| `selection` | 主文档选区 |
-| `docLength` | 文档长度（spacer 数） |
-| `inRefEdit` | 是否正在编辑同步块内部 |
-| `refSelection` | 同步块内部选区。只在 `inRefEdit` 时有意义 |
-
-脚本化改文档用 `import { operations, runOperation } from '@one2x/medeo-rte'`。
-
-## 性能面板
-
-```ts
-new Editor(el, { perfPanel: true });
-editor.setPerfPanel(false);
-```
-
-每次输入上屏后显示上屏延迟（按键到下一帧画完）、编辑器耗时（同步 JS）、排队时间（事件等主线程）。绿 / 黄 / 红按阈值。3 秒没有输入显示 `—`。demo 默认开启。
-
-开发探针默认关闭：
-
-```js
-editor.perf.start()
-editor.perf.report()
-editor.perf.stop()
-```
-
-读法见 [docs/performance.md](./docs/performance.md)。
-
-## 设计文档
+## 文档
 
 | 文档 | 内容 |
 | --- | --- |
+| [api.md](./docs/api.md) | 业务 API：构造参数、方法、命令、事件、chrome、mark |
 | [architecture.md](./docs/architecture.md) | 分层结构、不变式、样式模型 |
 | [mutations.md](./docs/mutations.md) | 原子操作 |
 | [operations.md](./docs/operations.md) | 编排层与 Operation 清单 |