Skip to content

我们做了一个「Word 编辑器」基础组件:Web 和 Native,一套内核 ​

摘要:做文档产品的团队,迟早都要回答同一个问题:产品的 Word 编辑能力从哪来?我们把答案做成了一个可嵌入的基础组件——像 <textarea> 之于表单,rword 想成为 Word 类业务的地基:.docx 原生读写、分页排版、Web 和 Native 一套内核像素级一致。8 个月、995 个提交、65 篇设计文档。这篇文章讲清楚它的定位、形态和边界,性能数字只作为「基础组件的工程底线」出场。


任何一个做文档产品的团队,迟早会撞上同一堵墙:

产品的灵魂是那个编辑器,编辑器的灵魂是排版引擎。它外包不了,也抄不来。

我们选择自己造。造完回头看,最想说的不是它有多快(确实很快,后面有数字),而是它的形态——

**rword 是一个基础组件:像 <textarea> 之于表单,我们希望它之于 Word 类业务。**Web 和 Native,一套内核。

01 我们造的是「地基」,不是「房子」 ​

rword 不提供「一个现成的在线 Word 产品」。它提供的是编辑器内核组件,以及围绕组件的完整工程面:

  • .docx 直接编辑:ISO/IEC 29500 原生读写——打开的是 Word 的格式,存回去还是 Word 的格式,不是导入导出的转换层;
  • 完整编辑能力:分页、页眉页脚、表格、内容控件、图片、查找替换、中文输入法、富剪贴板、撤销重做;
  • 单一组件嵌入:宿主页面上放一个组件,像放一个 <textarea> 一样自然——宿主拥有事件循环,把键盘、鼠标、输入法事件转发进来,接回调拿状态出去;
  • 业务自主:工具栏长什么样、业务面板怎么摆、文件存哪、权限怎么管——全是宿主的事。rword 通过十几个回调(内容变更、光标、选区、保存请求、右键菜单、格式状态、内容控件交互……)与业务双向集成。

在浏览器里,它是 npm 包 @office-rs/rword,接入只要几行:

js
import { Rword } from '@office-rs/rword'
await Rword.init(el, { /* 字体、渐进排版等配置 */ })

它长这样——1000 页文档拖进浏览器的真实录屏:

1000 页文档拖入浏览器:首页一帧内呈现,点击定位、快速滚动全程无卡顿

02 这块地基,市面上一度买不到也借不到 ​

如果你的产品需要一个 Word 级编辑器,你会发现自己站在四条路面前,条条有坑:

用 contenteditable 模拟。 浏览器的流式排版没有「页」这个概念。分页、页眉页脚、页码域、跨页表格——Word 的基本盘全要靠 DOM hack 硬模拟。能看,但编辑深度上不去,兼容性像抽盲盒。

嵌 LibreOffice。 桌面能跑,但它是几百万行的 C++ 巨石,进不了浏览器;想在它的排版引擎上长出自己的功能,每次升级都是一场手术。

买商业 SDK。 功能确实全。但闭源、贵、按许可收费;排版是产品命根子,性能调不动、bug 修不了、演进节奏捏在别人手里。

在开源巨石上二开。 同样的问题:架构不是你的,改造成本随产品形态指数增长。

基础组件之所以稀缺,是因为它难在「内核」,而内核没有捷径——Word 排版真正的难点不在「把字摆好看」,而在那些看不见的输入:在第 10 段前插入一段,后面所有列表编号都变了,但那些段落的内容一个字节都没动;页脚里的「共 N 页」要整篇排完才知道,而总页数又依赖它自己。

这些坑我们踩了一遍,写成了一篇万字长文(见文末)。

03 一套内核,两个平台 ​

基础组件的价值主张,rword 用架构直接兑现:写一次,两端交付。

rword 没有「Web 渲染器」和「原生渲染器」之分——只有一套排版与渲染内核,编译到不同目标:

  • 桌面:原生窗口 + GPU 渲染(Vello);Windows 桌面壳复用同一套 Web 前端;
  • 浏览器:WebAssembly + WebGPU,多标签页、按需渲染(标签页隐藏时零定时器零功耗);
  • 构造目标化:原生组件和 Web 组件是编译期决定的两个构造函数,不是运行时参数——两端的差异被锁死在平台适配层,内核代码零分叉。

两端的一致性是像素级的:字形直接从字体二进制在 GPU 上光栅化,不经过浏览器文本引擎——网页上的宋体和桌面上的宋体,一个像素都不差。

环境差异也被组件吸收了:

  • 字体:CJK 字体动辄 16 至 24 MB。Web 端按文档实际用到的字符切片加载(我们配套开源了切片工具链),桌面端走系统字体通道——用户机器上装的字体直接可用;
  • GPU 缺失:企业电脑禁硬件加速、虚拟机、老机器——WebGPU 不可用时自动落入 CPU 软渲染,编辑功能一项不少,滚动照样 60 帧。

一句话:降级的是像素的生产方式,不是产品。

04 组件的能力面:Word 的基本盘,一个都不能少 ​

作为「Word 类业务的地基」,基本盘逐个啃了下来,验收标准只有一条:和 Word/WPS 打开同一份 .docx,分页要基本一致。

  • 表格:从只读显示一路做到编辑、跨页流动、单元格选择、行高列宽;
  • 页眉页脚:完整的故事模型——双击进入编辑、「同前节」继承、PAGE/NUMPAGES 页码域逐页求值;
  • 内容控件(SDT):下拉、日期、复选框、数字格式,带字典、校验、锁定,支持嵌套——电子病历类场景的地基;
  • 中文输入法:内联组合、候选跟随,连「搜狗输入法在 CEF 里失灵」这种著名的坑都专门排查过;
  • 富剪贴板:与 Word/WPS/网页三方互拷不丢格式,自有无损内部格式作为后备;
  • 图片:行内、浮动、裁剪、文字环绕,一个不少。

05 基础组件的工程底线 ​

把一个编辑器内核做成业务地基,意味着它的每一次卡顿都是宿主业务的事故,它的每一次错排都是宿主业务的数据事故。所以性能与正确性不是「亮点」,是底线——而底线必须可证明:

  • 打字:300 页文档单键端到端 5339 ms → 6.07 ms,约 880 倍;
  • 打开:1000 页真实 .docx 首屏 2.8 s → 0.6 s(可见页先排,其余后台补排);
  • 缓存:千页文档内容不动再排一遍,只花冷排时间的 1/57;
  • CPU 路径:无 GPU 环境滚动同样 60 fps(页位图缓存后每帧 1 至 3 ms)。

支撑它们的机制,一句话版:段落记忆化(没变的段落绝不重排)、脏段起排 + 尾部拼接(借鉴 LibreOffice 三十年打磨的级联止损原则)、渐进排版(先看见、再补完)、四层页面缓存(段落 → 页布局 → 页场景 → 页位图)。

正确性同样是纪律:每一次增量化都配差分测试——随机编辑序列下,增量排版结果与全量排版逐位相等才算过;每一个 OOXML 元素都有读写往返测试;渲染冒烟断言像素而不是 console;无头转换内核喂了 libFuzzer 几万个畸形输入。

快,且可证明地对——这是我们给「地基」两个字交的答卷。

06 组件的边界:宿主的事,我们不越界 ​

基础组件的另一半设计,是清楚地知道自己不管什么:

文件存哪、版本怎么管、权限怎么控、协作流程怎么走、业务面板怎么排——都是宿主的事。rword 只通过组件接口与业务发生关系:事件进来,回调出去,状态可查。

但有一件事很多业务最终都要,我们也顺手修直了路:后端要把 .docx 转成 PDF(归档、打印、盖章)。常见做法是起一个无头浏览器跑前端编辑器——重、慢、内存不可控。rword 提供独立的无头转换内核,服务器上直接跑:

rword-convert input.docx output.pdf

同一个排版内核、同一套字体注册体系——编辑所见 = 导出所得,不存在「前端看是一个样、导出是另一个样」。

协作与审阅还在路线图上。

07 无头转换:同一套排版,换一个出口 ​

前文提到的那条「顺手修直的路」,就是 rword 的无头转换通道:把 .docx 直接转成 PDF,不打开编辑器、不需要浏览器,也不占用 GPU。它没有另起一套排版器,只是把编辑器的出口换成了文件——同一套 OOXML 解码、同一套分页排版、同一套字体注册,所以「编辑里看到的分页」和「导出拿到的 PDF」出自同一段代码。

转换内核对外同时提供 Rust 原生 API 和四种语言绑定:Node(worker 线程池 + Promise API,包内自带命令行)、Python(abi3 wheel,转换期间释放 GIL)、Java(兼容 Java 8,固定槽位池),以及浏览器里的 wasm 版本(不依赖 WebGPU / Canvas,可以直接塞进 Web Worker)。后端文档服务、脚本、CI、浏览器 Worker,走的都是同一条通道。

它和编辑器 SDK 的 exportPdf 不是同一件事:exportPdf 走活动编辑器引擎,所见即所得;无头通道不创建编辑器,也没有屏幕。转换路径、命令行用法、退出码与预算、字体注册、修订痕迹开关、各语言的最小示例,单独写了一篇:《无头转换:把 .docx 变成 PDF,不打开编辑器》。

08 适合谁 ​

如果你正在做这些事情,rword 值得你花十分钟看一眼:

  • 在线文档 / 知识库产品:需要真正的分页和 .docx 保真,而不是流式模拟;
  • 电子病历编辑:千页大病历要秒开,页码信息必须正确,内容控件是地基;
  • 合同与公文系统:分页一致性和格式保真是刚需,盖章归档要 PDF;
  • 政企内网 OA:浏览器环境千奇百怪,需要无 GPU 时的 CPU 渲染路径、系统字体可用;
  • 后端文档服务:批量 .docx→PDF 转换,要的是无头、可控、可模糊测试。

09 来聊聊 ​

项目开源在 github.com/office-rs,Web SDK 是 npm 包 @office-rs/rword。

想看技术细节的,几篇长文:

如果它对你有用,或者你也在文档编辑这个深坑里挣扎——欢迎 Star、提 issue、来聊。基础组件这条路很长,我们还有很多故事可以讲。

基于 VitePress 构建