npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@4399ywkf/editor

v0.14.1

Published

4399 多格式文档编辑器:doc(tiptap) / sheet(univer) / pdf / pptx,含 docx·xlsx·csv 双向导入导出与 AI 可驱动的结构化编辑面(./doc-runtime、./sheet-runtime)

Readme

@4399ywkf/editor

4399 多格式文档编辑器。一个包覆盖 doc / sheet / pdf / pptx,引擎按需下载。

pnpm add @4399ywkf/editor
import { 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。
  • 评论标记为 commentThread mark,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。本期不提供标签的新增 / 删除 / 排序 / 重命名,也不会执行任何代码。
  • codeBlock prop 可覆盖主题 / 别名 / 额外语言:{ 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