@4399ywkf/editor
v0.14.1
Published
4399 多格式文档编辑器:doc(tiptap) / sheet(univer) / pdf / pptx,含 docx·xlsx·csv 双向导入导出与 AI 可驱动的结构化编辑面(./doc-runtime、./sheet-runtime)
Maintainers
Readme
@4399ywkf/editor
4399 多格式文档编辑器。一个包覆盖 doc / sheet / pdf / pptx,引擎按需下载。
pnpm add @4399ywkf/editorimport { DocumentView, detectFormat } from "@4399ywkf/editor"
import "@4399ywkf/editor/styles"
<DocumentView format={detectFormat("年度报告.docx")} content={html} />格式与能力
| 格式 | 引擎 | 编辑 | AI 可操作 | 协同 | 依赖 |
|---|---|---|---|---|---|
| doc(含云文档) | tiptap | ✅ | ✅ | ✅ | 内置 |
| sheet | Univer 1.x OSS 核心 | ✅ | ✅ | ✕ | 可选 peer,见表格通道配置 |
| pdf | pdf.js | ✕ 只读 | ✕ | ✕ | 可选 peer pdfjs-dist |
| pptx | pptx-preview 渲染 + 按部件改 OOXML | ✕ 人手不可编辑 | ✅ | ✕ | 可选 peer pptx-preview |
云文档与本地 doc 是同一套 tiptap,不做区分。
「AI 可操作」指的是有结构化操作面可挂:doc 走 ./doc-runtime,
sheet 走 ./sheet-runtime,pptx 走 ./slide-runtime,
工具定义在 @4399ywkf/editor-mcp。
导入导出都在本地转换,文档不出内网:docx ⇄ doc、xlsx/csv/tsv ⇄ sheet, 不引 SheetJS、不依赖任何转换服务。
为什么引擎是懒加载的
主入口只有 3KB(格式路由),tiptap 的 698KB 在独立 chunk 里,Univer / pdf.js / pptx-preview 都是可选 peer。
import "@4399ywkf/editor" 不会把任何引擎拉进你的主包 —— 只有真的渲染到某种格式时才下载。
Univer sheets 核心 gzip 后 871KB;无条件打进主包会直接毁掉阅读侧首屏。
子路径
import { NotionEditor, ArticleViewer } from "@4399ywkf/editor/doc"
import { ImportDocx, ExportDocx } from "@4399ywkf/editor/docx"
import { downloadXlsx, importSheetSource } from "@4399ywkf/editor/xlsx"
import { downloadCsv } from "@4399ywkf/editor/csv"
import { SheetView } from "@4399ywkf/editor/sheet"
import { PdfView } from "@4399ywkf/editor/pdf"
import { PptxView, repairPptx, useSlideDocument } from "@4399ywkf/editor/pptx"
import { DocRuntime } from "@4399ywkf/editor/doc-runtime" // AI 可驱动的文档操作面
import { SheetRuntime } from "@4399ywkf/editor/sheet-runtime" // 同上,表格版
import { SlideRuntime } from "@4399ywkf/editor/slide-runtime" // 同上,演示文稿版(不依赖 React)
import "@4399ywkf/editor/styles"pptx 预览
pnpm add pptx-preview # 可选 peer,不装就落到「暂不支持」兜底<DocumentView format="pptx" source={file} onError={(e) => toast(e.message)} />渲染定位是「看清这页讲什么」,不是所见即所得。 申报为 editable: false
(人手不能直接改)、aiOperable: true(AI 通过 ./slide-runtime 改)。
渲染的已知差距,接之前请先认下:
- 图表渲染不出数据 —— 轴画得出来,柱子/折线是空的,系列名和标题退化成
「系列1 / 图表标题」。该库打包了 ECharts,却没把
c:cat/c:val接上去 - 缺字体时替换成系统字体,观感和原稿不一致
- 内部偶有 SVG 路径算出 NaN,个别形状画不出来
只认 OOXML:.pptx .ppsx .potx .pptm .ppsm .potm。
.ppt / .pps / .pot 是二进制复合文档、不是 zip,该库解不了,
所以不申报 —— 让它落到「暂不支持」比装作能开要好。
为什么要先修一道
真实文件里大半份的 [Content_Types].xml 声明了 zip 中并不存在的 slideMaster。
PowerPoint 自己不介意,pptx-preview 会整份静默失败:不抛错、不报警,
slideCount 就是 0,面板一片空白。
17 份真实文件实测:裸接只有 5 份能打开,内置 repairPptx 后 17 份全开。
PptxView 已经自动做了这一道;直接用 pptx-preview 的宿主请自己先过:
import { repairPptx } from "@4399ywkf/editor/pptx"
const { bytes, removed } = repairPptx(new Uint8Array(await file.arrayBuffer()))只在真有幽灵声明时才解压重打包(用已有的 fflate,不引 JSZip),
文件没问题就原样返回入参。17 份文件逐条目做过 sha256 比对:
除 [Content_Types].xml 外字节全等。
引擎选型与这道修复都对齐腾讯 WorkBuddy 内置的 pptx 预览。要更高保真,
用同名 registerFormat 覆盖本通道即可(见下)。
pptx AI 编辑
宿主持有 pptx 字节,SlideRuntime 每次写入都交回一份新字节;PptxView 看到
content 变了就在后台重新渲染、成功后再替换,不闪、不跳滚动位置。
import { PptxView, useSlideDocument } from "@4399ywkf/editor/pptx"
import { attachBridge, composeRuntimes } from "@4399ywkf/editor-mcp/bridge"
const { bytes, runtime, undo, canUndo } = useSlideDocument(initialBytes, {
onChange: (next, edit) => save(next), // edit = { tool, summary, time },何时落盘由你决定
})
useEffect(() => attachBridge({ runtime: composeRuntimes({ slide: runtime }) }), [runtime])
return <PptxView content={bytes} />不用 React 的宿主直接 new SlideRuntime({ getBytes, commit });Node 里另外注入
xml: { DOMParser, XMLSerializer }(如 @xmldom/xmldom)。
12 个操作(工具定义见 @4399ywkf/editor-mcp):读结构(可带文字格式)、全文查找、
改文字(整体替换 / 查找替换)、设文字格式与段落对齐与超链接、增删复制移动页、加文本框 / 图片 / 形状、改位置尺寸填充边框、
表格增删行列与写单元格、写备注、撤销、导入、导出。页码从 1 开始,长度单位 pt。
保真:直接按部件改 OOXML,没碰过的部件解压后逐字节不变;改动只落在必然涉及的
那几个部件上(页面、关系、[Content_Types].xml、分节)。没有走「转成中间模型再导回」,
所以 SmartArt、动画、扩展字段这些本期不认识的东西原样保留。
页内 shape id 重复(pptxgenjs 等生成器常见,PowerPoint 也容忍):按文档序保留首个,
后来的顺延成「页内最大 id + 1…」。编号是确定的,slide_read 给出的 id 一定能直接拿去写;
写到这一页时顺延结果随之落盘,只读不改文件。
每次调用是原子的:出错不提交;没有任何部件被改就不提交、不记撤销。撤销栈默认 20 步, 存的是整份字节快照(媒体多的文件内存占用相应变大)。
本期不做:行距 / 缩进 / 项目符号、文字特效、图表数据、动画、主题与版式编辑、 分组内形状的位置与属性、合并单元格的结构修改。这些对象在读取结果里标为只读,写回时原样保留。 带动画的形状(含组内子形状带动画的分组)不能删除 —— 删了会留下悬空的动画引用, PowerPoint 打开会要求修复。表格插列时新列沿用相邻列宽,表格会随之变宽、可能超出页面, 本期不能调列宽。
表格通道配置
# 版本必须一致(Univer 要求所有 @univerjs/* 同版本,混装会出两份 core)
pnpm add @univerjs/presets @univerjs/preset-sheets-core @univerjs/preset-sheets-find-replace \
@univerjs/preset-sheets-filter @univerjs/preset-sheets-sort \
@univerjs/preset-sheets-data-validation @univerjs/preset-sheets-conditional-formatting \
@univerjs/preset-sheets-hyper-link @univerjs/preset-sheets-note \
@univerjs/preset-sheets-thread-comment @univerjs/preset-sheets-table \
@univerjs/preset-sheets-drawing只要用到表格通道(DocumentView 主入口或 ./sheet),这些包就都得装 ——
引擎是动态 import 的,但打包器在构建期就要解析它,解析不到直接构建失败。
样式随表格视图一起加载;宿主自己再 import 一次同一份 CSS 也不会冲突。
Univer 的 UI 是 univer- 前缀的原子类,没有稳定选择器 —— 别用 CSS 硬藏工具栏。
开关走 sheet 这个 prop,直接透传到 Univer preset:
<DocumentView
format="sheet"
content={snapshot}
readOnly
sheet={{
findReplace: true, // Ctrl+F 查找替换
ui: { footer: true, formulaBar: false }, // 底栏保留(多表切换靠它),公式栏收掉
}}
/>ui 可用:header / toolbar / ribbonType(collapsed / simple / classic / grid)/
footer / formulaBar / contextMenu / statusBarStatistic / menu。
readOnly时toolbar默认为false—— 整条 ribbon 在只读预览里全是死按钮, 窄面板里还挤。要它回来就显式传ui: { toolbar: true }。footer别随手关:多工作表时它是唯一的切表入口,关掉用户就只看得见第一张表。findReplace没开就完全不下载(但包还是要装,见上)。- 筛选、排序、数据校验、条件格式、超链接、批注、评论、表格(Excel Table)和浮动图片默认就在。 工作表背景图走的也是这套图片能力。图表、透视表不在其中。
sheet.presets用来追加别的 preset。上面这些再传一次时,同名插件以宿主那份为准。 自带的 locale 已经合并进 zh-CN;额外 preset 仍要自己把 locale 放进sheet.locales, 否则菜单会显示成原始 i18n key。
sheet 里的配置只在引擎创建时读一次,挂载后改不生效也不会重建
(重建 = 重下引擎 + 丢掉选区和滚动位置,而宿主几乎总是传内联字面量)。要换配置请换 key。
xlsx 导出
和 docx 一样在本地生成,文档不出内网;不引 SheetJS,只多用已有的 fflate。
import { downloadXlsx, exportXlsx } from "@4399ywkf/editor/xlsx"
const api = useRef<unknown>(null)
<DocumentView format="sheet" content={snapshot} onReady={(a) => (api.current = a)} />
// univerAPI 或快照都收
const { warnings } = downloadXlsx(api.current, "年度报表.xlsx")
if (warnings.length) toast(warnings.join("\n")) // ← 别吞,见下服务端 / 定时任务只有 JSON 也能导 —— 整条链路不碰 DOM,不用起 Univer:
import { xlsxFromSnapshot } from "@4399ywkf/editor/xlsx"
const { bytes, warnings, stats } = xlsxFromSnapshot(snapshot)保真范围:
| | 状态 |
|---|---|
| 值与类型、共享字符串、强制文本(quotePrefix) | ✅ |
| 公式 + 缓存值,填充公式还原成 xlsx 的共享公式 | ✅ |
| 数组公式、动态数组(Excel 365 的溢出公式) | ✅ 区域里另有公式或碰到合并单元格时降级并点名 |
| 1904 日期系统 | ✅ |
| 数字格式、字体、颜色、填充、边框、对齐、换行、旋转、缩小字体填充、会计用下划线 | ✅ |
| 合并单元格、行高列宽、隐藏行列、冻结窗格 | ✅ |
| 多工作表、工作表隐藏与深度隐藏、标签颜色、网格线开关 | ✅ |
| 工作表背景图 | ✅ data URL 形式的;外链 / 图床地址不联网取图,点名跳过 |
| 富文本单元格 | ~ 压平成纯文本 |
| 模拟运算表 | ~ 只有计算结果,按值写出 |
| 条件格式:数值比较、文本包含 / 不包含 / 开头 / 结尾、重复值 / 唯一值、前 N / 后 N、色阶、渐变数据条 | ✅ 图标集、公式、日期、平均值类与实心数据条点名跳过 |
| 按值筛选(含被筛掉的行与 _xlnm._FilterDatabase) | ✅ 按颜色 / 自定义条件的列点名跳过,筛选区域保留 |
| 图片、图表、透视表、数据校验、批注、评论、超链接 | ✕ |
编辑器里可以直接用筛选、排序、数据校验、条件格式、超链接、批注、评论、表格和浮动图片。
它们存在各插件自己的 resources 里,不在 cellData 中:条件格式与筛选由导出器逐条翻成 OOXML,
其余(上表最后一行)照样进 warnings。要展示给用户 —— 导出时会逐条点名丢了什么
(「数据校验未随 xlsx 导出」「条件格式里有 图标集 1 条未随 xlsx 导出」),打开文件才发现要糟得多。
cachedFormulaValues(默认 true)决定公式格写不写 Univer 算好的值。关掉则只留公式、
由 Excel 打开时重算 —— 这时会自动加上 fullCalcOnLoad,否则不重算的消费方
(网页预览、pandas)会看到一片空白。
csv 导出
单独子路径,一个依赖都不需要(xlsx 那边要 fflate 打 zip),产物 6.9KB:
import { downloadCsv, exportCsv } from "@4399ywkf/editor/csv"
const { warnings } = downloadCsv(univerAPI, "明细.csv")
if (warnings.length) toast(warnings.join("\n"))csv 是单表格式,工作簿是多表的 —— 只导一张,其余的在 warnings 里逐个点名:
csv 是单表格式,只导出了「明细」。未导出的 1 张表:「汇总」
传 univerAPI 时导真正的活动表;只传快照时导第一张 —— 快照里根本没有
「活动表」这个字段,只有运行时实例问得出来。要指定就用 options.sheet(表 id 或表名)。
默认加 UTF-8 BOM:不加的话 Excel 会按本地编码(简中系统是 GBK)解析,中文全是乱码。
转义按 RFC 4180,含分隔符/引号/换行的字段加引号、内部引号翻倍。
delimiter: "\t" 就是 tsv。
其余降级同样会点名:合并单元格被拆开、富文本压平、公式写成算好的值
(formulas: "formula" 可改成写公式原文)。日期不做转换 —— 它在 Univer 里是
「序列号 + 数字格式」,csv 里会写成 45678。格式码有转义、区域前缀、还有和 mm
同形的分钟,猜错日期比原样给出序列号更糟,所以只警告不转换。1904 日期系统的工作簿会在
警告里额外说明序列号的起算日。
xlsx / csv / tsv 导入
导出的反方向,同一套约定:本地解析,文档不出内网,不引 SheetJS。
路由层直接给 source 就行,File / Blob / URL 都收:
<DocumentView
format="sheet"
source={file}
onWarnings={(w) => toast(w.join("\n"))} // ← 别吞,见下
onError={(e) => toast(e.message)}
/>也可以只要快照,自己塞给 Univer:
import { importSheetSource } from "@4399ywkf/editor/xlsx"
const { workbook, warnings, format } = await importSheetSource(file)
univerAPI.createWorkbook(workbook)Node 侧没有全局 DOMParser,把 @xmldom/xmldom 的传进去即可
(importXlsx(bytes, { DOMParser }))—— 解析层是纯函数,整条链路不碰 DOM。
看起来像数字或 TRUE/FALSE 的文本导入后标为「以文本形式存储」(Univer FORCE_STRING,导出为 quotePrefix),这样改样式不会被转成数字。
能保住的:多工作表(顺序 / 隐藏 / 深度隐藏)、值与类型、
公式(普通 / 共享 / 数组 / 动态数组)、1904 日期系统、数字格式(含内建表)、
字体 / 颜色 / 填充 / 边框 / 对齐 / 换行 / 旋转 / 缩小字体填充、会计用下划线、合并单元格、
行高列宽、隐藏行列、冻结窗格、网格线、标签颜色、工作表背景图(png / jpg / gif / bmp)、
quotePrefix(强制文本)、条件格式(类型同导出)、按值筛选与被筛掉的行(导回后去掉筛选,这些行会重新显示)。
1904 日期系统只在工作簿上标 dateSystem、不改数值 —— Univer 的显示、日期编辑和公式
都按它解释序列号。
保不住的逐个点名(进 warnings):图片 / 图表、透视表、工具不支持的条件格式类型(含 Excel 2010 扩展里的实心数据条、自定义图标)、数据校验、
按颜色 / 自定义条件的筛选列、超链接、批注、宏、主题色、模拟运算表的定义(只留计算结果)。编辑器能新建这些
(图表和透视表除外),但 xlsx 里原有的不会进快照。和导出侧一样 ——
打开文件才发现少了东西,远比导入时被告知糟糕。
.xls 是老的二进制复合文档,明确不解析:报错会直接告诉用户「另存为 .xlsx」,
而不是给一个空表。
csv / tsv 两处有立场的处理:
- 编码嗅探:UTF-8 严格解码优先,失败退 GBK(简中环境相当一部分 csv 是 Excel
直接另存的),退了会在
warnings里说明。 - 类型推断保守:前导零(
0123)和超过 15 位有效数字的「数字」保留为强制文本 —— 转成 number 会失真,宁可留原文也不悄悄改值。订单号、身份证号就是这么被毁掉的。
文档状态、协作入口与划词评论
通过 EditorConfigProvider 的 document 和 comments 接入业务宿主:
import { EditorConfigProvider, NotionEditor, type EditorConfig } from "@4399ywkf/editor/doc"
const config: EditorConfig = {
document: {
saveState: "saving",
onRetrySave: retrySave,
onShare: openShareDialog,
onOpenComments: openComments,
commentCount: unresolvedCommentCount,
onOpenHistory: openHistory,
},
comments: {
onCreateComment: ({ from, to, text }) => openCommentComposer({ from, to, text }),
onSelectThread: (threadId) => openCommentThread(threadId),
},
}
<EditorConfigProvider config={config}>
<NotionEditor room={documentId} content={content} onEditorReady={setEditor} />
</EditorConfigProvider>saveState支持unsaved、saving、saved、error、offline。保存成功由宿主在实际写入完成后确认;未配置时不显示保存状态。仅在error且提供onRetrySave时显示重试。- 分享、评论和历史入口按回调是否配置显示。提供入口不会创建云端服务、赋予权限或发送通知;鉴权、数据持久化和业务面板由宿主实现。
- 内置顶栏保留编辑/阅读、撤销/重做,将页宽、打印和历史收纳到更多操作。打印继续遵守
permissions.print,主题跟随宿主。 - 选中正文文字后显示“添加评论”。
onCreateComment接收当前选区和引用文字;创建线程时调用editor.chain().setTextSelection({ from, to }).setCommentThread(threadId).run()添加原文标记。异步编辑期间,宿主应通过事务映射维护草稿选区。 editor.commands.unsetCommentThread(threadId)仅移除指定线程的原文标记,允许多个线程重叠。已存标记随正文事务移动,点击或键盘激活时调用onSelectThread。- 评论标记为
commentThreadmark,JSON 保存threadId,HTML 使用span[data-comment-thread]。评论正文、作者、解决状态和权限独立存储在宿主。Markdown 导出不保留评论锚点。 - 桌面目录可以固定/收起,支持键盘聚焦和 Escape;内嵌文章继续不显示独立目录。窄屏布局遵守宿主容器宽度。
仓库内运行 pnpm --filter @4399ywkf/editor-demo dev,打开 /#workspace 可验收完整本地接入:自动保存、失败重试、桌面和手机划词评论、解决/重开评论、最多20个手动版本、恢复前备份、JSON/HTML副本导出。恢复版本会重新初始化编辑历史,防止只撤销正文造成评论与标题错配;多标签页检测到存储变化时拒绝覆盖新稿,保留当前修改供导出。数据仅保存在当前浏览器,复制页面链接不会共享文档;现有验收页仍在 /。
代码块与代码分组(Shiki)
代码块用 Shiki 高亮:默认 github-light / github-dark 随 .dark
切换,语言按需加载,不需要任何配置。高亮通过 ProseMirror Decoration 着色,正文仍由
ProseMirror 管理 —— 不改文档、不进撤销历史、不广播给协作者。
代码分组:在正文里输入或粘贴 ::: code-group 语法,得到一个可切换标签、可编辑、
可复制的分组;也可以用 contentFormat="markdown" 直接载入:
import { NotionEditor } from "@4399ywkf/editor/doc"
const codeGroupMarkdown = `
::: code-group
\`\`\`bash [curl]
curl https://api.example.com/v1/chat
\`\`\`
\`\`\`python [python]
import requests
\`\`\`
:::
`
<NotionEditor
room="api-example"
contentFormat="markdown"
content={codeGroupMarkdown}
onEditorReady={(editor) => save(editor.getJSON())}
/>contentFormat可选"json" | "html" | "markdown"。不传时沿用旧规则:对象按 JSON、 字符串按 HTML。"json"只接受对象,不会去解析 JSON 文本;格式与内容类型不匹配时 console.error 一条[editor]信息,当前文档不动。ArticleViewer与DocumentView的 doc 通道接受同样的contentFormat。- fence 的 info 按
语言 [标签]解析:bash [curl]→ 语言bash、标签curl;只写python则标签栏显示语言名。标签允许空格与\[\]\\转义。 - 组内只允许完整的 fenced code 与空行;没闭合或混进正文的组保持普通文本,可继续编辑。
代码里的
:::不会关闭组。 - 输出:
editor.getJSON()(规范结构,codeGroup只含codeBlock+)、editor.getHTML()(语义 HTML:<div data-code-group><pre data-language data-label>…)、getEditorMarkdown(editor)(::: code-group语法;等价于editor.getMarkdown(), 但不需要引@tiptap/markdown的类型扩充)。renderHighlightedHTML(editor)异步导出 调用时刻文档快照的静态 Shiki HTML,所有标签的代码都在、不嵌脚本。 - 活动标签是 NodeView 本地状态,不写进 JSON / Yjs。本期不提供标签的新增 / 删除 / 排序 / 重命名,也不会执行任何代码。
codeBlockprop 可覆盖主题 / 别名 / 额外语言:{ shikiTheme, languageAliases, languages }。
折叠块、提示框与 API 参数
三种可折叠块容器,Markdown 都是 VitePress 风格的 ::: 容器(前两种与 VitePress 原样兼容):
::: details 点击查看
藏起来的内容
:::
::: warning 注意
不可与 instructions 字段一起使用。
:::
:::: param caching `object`
上下文缓存
是否为本次请求开启上下文缓存。
::: param prefix `boolean` 默认 `false`
仅写缓存
:::
::::- 提示框类型:
info/tip/warning/danger,冒号后的文字是标题(可空,空时显示 信息 / 提示 / 注意 / 危险)。 param信息串:第一个词是参数名,反引号里是类型(允许string / object[]),必选(或required),默认 值(或default 值,值带空格用反引号)。正文第一段是折叠行右边那句短描述,其余段落展开后才显示。- 嵌套:外层用更多冒号(
::::)。代码 fence 里的:::不会关闭容器;没闭合的容器保持普通文本。 - 展开 / 收起不进文档:读者打开时全部收起,编辑态光标进入隐藏正文时自动展开。
- 编辑态头部字段(标题、参数名、类型、必选、默认值、短描述)就地改,失焦或回车提交(一步撤销),Esc 还原;slash 菜单有"折叠块 / 提示框 / 参数"三项;在段落里输入
::: warning 注意回车也能当场生成。 getHTML()输出原生<details>(无脚本也能折叠)与<div data-callout>;docx 按顺序摊平为"标题 + 正文",嵌套缩进递增;LiteXML 里是<details>/<callout>/<param>。- 载入:
<NotionEditor contentFormat="markdown" content={markdown} />。OpenAPI / JSON Schema 导入是后续子项目,参数节点的 JSON 结构就是它的目标形态。
docx 导入导出
API 形态对齐 @tiptap-pro/extension-import-docx / -export-docx,但在本地解析,
文档不出内网,不需要 token / endpoint。
import { ImportDocx, ExportDocx } from "@4399ywkf/editor/docx"
new Editor({ extensions: [StarterKit, ImportDocx, ExportDocx] })
editor.chain().importDocx({ file, onImport(ctx) { ctx.setEditorContent(ctx.content) } }).run()
editor.chain().exportDocx({ onCompleteExport: (blob) => save(blob) }).run()相对官方能力矩阵的增量 —— 这几项官方明确标 ✕:
| | 官方 | 本包 |
|---|---|---|
| 域(SEQ / TOC / PAGE) | ✕ 只留静态文字 | ✅ 保代码 + 缓存值,可往返 |
| 墨迹手写 | ✕ | ✅ 保矢量 XML + 位图回退 |
| 浮动 / 环绕定位 | ~ | ✅ wrapNone 绝对定位、不占布局 |
| 样式定义里的字符格式 | ✅ | ✅ 含 w:basedOn 继承链 |
| 文档不出内网 | ✕ | ✅ |
已知缺口:fldChar 复杂域、修订痕迹、页眉页脚 / 脚注、超链接导出未建外部关系。
AI 操作面
要让 AI 改用户此刻正在看的那个实例(而不是复制一份文本出去改), 挂对应的 runtime 即可。两层都只认编辑器实例,不知道 MCP / HTTP 存在:
import { DocRuntime } from "@4399ywkf/editor/doc-runtime"
import { SheetRuntime } from "@4399ywkf/editor/sheet-runtime"
const doc = useMemo(() => new DocRuntime(), [])
const sheet = useMemo(() => new SheetRuntime(), [])
<NotionEditor onEditorReady={(editor) => doc.setEditor(editor)} />
<DocumentView format="sheet" onReady={(api) => sheet.setUniverAPI(api)} />
await doc.call("doc_replace_text", { ... }) // 两个 runtime 的 call 是同构的
await sheet.call("sheet_read", { range: "A1:D20" })doc-runtime:LiteXML(对 ProseMirror JSON 的有损压缩,省 1.55x 以上 token)+ 8 类操作。sheet-runtime:读走快照(CSV 文本,比 JSON 单元格矩阵省几倍 token), 写走 Univer facade 的 command 体系(这样才有撤销栈和协同广播)。- sheet 工具面 12 个:读(
sheet_read/sheet_find)、写值(sheet_set_values)、结构(sheet_edit_rows_cols/sheet_manage_sheets)、格式(sheet_format_range/sheet_merge/sheet_freeze)、数据(sheet_sort/sheet_filter/sheet_conditional_format)、导出(sheet_export_xlsx)。参数全部在发第一条命令之前校验完, 非法就一条命令都不发;每次写调用占 1~2 步撤销(结果里的undo_steps)。sheet_read加include: ["styles", "merges", "freeze", "filter", "conditional_formats"]可读回格式。sheet_format_range遇到区域里(设边框时还包括区域外紧邻的一圈)看起来像数字或TRUE/FALSE的文本格且不是文本格式时会报错并点名,避免 Univer 改样式时把它们转成数字,丢失前导 0 或第 16 位起的数字; 先只对点名格设numberFormat: "@"再重试。numberFormat: "@"会把区域内已有的数字、日期、布尔转成文本 (123 变"123"),SUM / 排序随之按文本处理,只对需要保持文本的格用。设边框还会改变界面「边框」按钮 记住的样式与颜色(Univer 的全局边框设置)。 slide-runtime:pptx 没有活的编辑器实例,runtime 直接改字节,见 pptx AI 编辑。
工具定义(name / JSON Schema / description)和传输(浏览器桥 / hub / stdio MCP)
都在 @4399ywkf/editor-mcp,本包一行传输代码都没有。
注册自有格式
内置通道覆盖不了、或保真度不够时,宿主可以用同名 registerFormat 直接覆盖。
pptx 编辑就属于这种:Univer Slides 官方标注「请勿用于生产环境」,开源世界没有 第二个可用的前端 pptx 编辑引擎;真要做只有 OnlyOffice / Collabora 那一档 (AGPL,需法务口径 + 独立部署)。所以内置的只有只读预览,要更高保真自己接:
import { registerFormat } from "@4399ywkf/editor"
// 同名注册会覆盖内置通道
registerFormat({
format: "pptx",
label: "演示文稿",
extensions: [".ppt", ".pptx"], // 自家引擎能开二进制 .ppt 就一并申报
capabilities: {
editable: true, aiOperable: false, collaborative: false,
importExtensions: [".ppt", ".pptx"], exportFormats: ["pptx"],
},
load: () => import("./MyOnlyOfficeSlideView"),
})样式
必须显式引入一次:
import "@4399ywkf/editor/styles" // dist/style.css,168KB包内 55 个 scss 在构建期编译并拼成单文件,JS 产物里不残留任何 scss 导入 ——
消费方无需配置 sass loader,SSR 也不会因为 import "x.scss" 报错。
依赖版本:@tiptap/* 必须同版本
Tiptap 各包之间用精确版本的 peerDependencies 互相钉死,本包把全部 @tiptap/*
统一声明为同一个范围(当前 ^3.30.0,由 src/tiptap-versions.test.ts 守着)。
业务仓库自己也引了 @tiptap/core / @tiptap/react 时,版本必须落在同一个范围里,
否则 pnpm 会把一部分去重到你锁文件里的旧版本、给另一部分另拉新版本,构建时报
Export attrsEqual doesn't exist in target module 这类错。升级本包后在业务仓库跑:
pnpm update -r "@tiptap/*" # 整个 tiptap 家族对齐到一个版本
pnpm ls -r "@tiptap/core" # 只应出现一个版本协同
doc 走 yjs。注入扩展时注意:所有客户端必须注入同一组扩展,
schema 不一致时一端产生的节点到另一端会被 y-prosemirror 当非法内容静默丢弃。
开发
pnpm install
pnpm build # tsup + 样式编译
pnpm test # 232 个用例
pnpm typecheck