Oasis Editor：基于Canvas自研渲染引擎的开源文档编辑器

重新思考文档编辑器的技术路线

在浏览器中构建富文本编辑器,几乎所有主流方案都绑定在 contenteditable 上。

contenteditable 是 HTML5 提供的一个全局属性,当元素设置为 contenteditable="true" 时,用户可以直接在该元素内编辑文本内容。这个特性最早由 Internet Explorer 5.5 引入,后来被纳入 W3C 标准。它的核心优势是开发成本低——浏览器自动处理光标、选区、输入法和文本渲染。但正因为依赖浏览器实现,不同浏览器(Chrome、Firefox、Safari)在处理复杂场景时存在显著差异:光标定位算法不同、删除行为不一致、HTML 结构清理策略各异。

从 Google Docs 早期到 Notion、Quill、ProseMirror,contenteditable 提供了浏览器原生的可编辑能力,但也带来了这个不用我讲的痛点:跨浏览器行为不一致、光标与选区难以精确控制、复杂排版(分页、表格、图文混排)极难实现像素级掌控。这导致开发者需要编写大量兼容性代码,甚至主动禁用浏览器默认行为,自己实现编辑逻辑。对于追求像素级控制的专业文档编辑器而言,contenteditable 的"黑盒"特性成为了技术天花板。

开发者 celsowm 在 Reddit 的 r/opensource 社区公开了一个名为 Oasis Editor 的开源项目,选择了一条更激进的技术路线——自研 Canvas 渲染引擎,完全绕开 contenteditable。

Canvas 是 HTML5 提供的位图绘图 API,开发者通过 JavaScript 直接在画布上绘制像素。与 DOM 不同,Canvas 不维护元素树结构,所有内容都是"画"上去的图像。在文档编辑器中使用 Canvas 渲染,意味着每个文字、每条线、每个表格边框都需要开发者手动计算坐标并调用绘图 API。这意味着文本、选区、图片、表格乃至整个文档几何(document geometry)都由项目自己的引擎负责绘制和管理。

对于长期被 contenteditable 各种边界问题困扰的前端开发者来说,这是一个值得关注的尝试。

为什么要自建 Canvas 渲染引擎

contenteditable 的天然局限

contenteditable 本质上是把排版和渲染的控制权交给了浏览器。简单场景下确实省事,但一旦需要实现分页布局(paged layout)——也就是像 Word 那样将文档按 A4 纸张分页显示——浏览器原生能力就显得力不从心。

分页需要精确计算每一行、每张图片、每个表格在页面中的位置,内容溢出时还要自动跨页处理。这类几何计算在 DOM 层面难以稳定实现,也是 contenteditable 方案最大的瓶颈之一。

Canvas 方案的核心优势与代价

Oasis Editor 用 Canvas 接管渲染后,获得了对以下要素的完全控制权:

分页布局:精确模拟纸张页面,实现像素级的排版控制
文本渲染:字形排布、行高、断行逻辑完全由引擎决定
选区管理(selections):光标和高亮不再受浏览器实现差异影响
图片与表格:作为文档几何的一部分统一管理,避免 DOM 层面的布局塌陷

这种方案的核心优势是"完全控制":开发者可以精确到像素级别地决定内容位置,不受浏览器布局引擎限制。例如实现分页时,可以精确计算每行文字高度,当内容超出页面边界时触发分页逻辑,将溢出内容绘制到下一页 Canvas。这种几何计算在 DOM 中极难实现,因为浏览器的流式布局(flow layout)天然不支持"页"的概念。

当然,这条路的代价也不容忽视:光标输入、输入法(IME)、无障碍访问(accessibility)、复制粘贴等浏览器原本免费提供的能力,都需要开发者自己重新实现。

输入法(IME)适配是最大的挑战之一。IME(Input Method Editor,输入法编辑器)是处理非拉丁字符输入的系统组件,中文、日文、韩文等语言的输入都依赖 IME。在 contenteditable 中,浏览器自动处理 IME 事件:显示候选词面板、更新未确认文本(composition)、处理确认输入(commit)。但在 Canvas 方案中,开发者必须监听 compositionstart、compositionupdate、compositionend 等事件手动实现。最大的难点是候选词面板定位——必须精确计算当前光标在 Canvas 中的像素坐标,并通过隐藏的 DOM 输入框来接收系统 IME 事件,再将输入内容同步回 Canvas 渲染。

无障碍访问的重建同样艰巨。无障碍访问是确保残障用户也能使用软件的技术要求,核心标准是 W3C 的 WCAG 和 ARIA。在 contenteditable 中,浏览器自动维护语义化 DOM 结构,屏幕阅读器可以直接读取文本、识别标题层级、通知光标位置变化。但 Canvas 对屏幕阅读器来说是一张"图片",没有任何语义信息。开发者必须手动构建影子 DOM 或 ARIA live region,将 Canvas 中的文档结构映射为可访问的 HTML 元素,实时同步内容变化。

这也是为什么绝大多数编辑器项目不敢碰 Canvas 方案——Oasis Editor 选择了一条工程量极其可观的路线。

Oasis Editor 的核心特性详解

根据作者披露的信息,这个用 TypeScript 编写的项目已经具备了一套相对完整的架构。

类型化的命令与插件 API

项目提供了 typed command/plugin API,开发者可以通过强类型的命令系统操作文档,并通过插件机制扩展功能。这种设计借鉴了 ProseMirror、Tiptap 等成熟编辑器的思路——将编辑操作抽象为命令,将功能模块化为插件,从而保证可维护性和可扩展性。

ProseMirror 是由 CodeMirror 作者开发的富文本编辑框架,核心设计是将文档表示为不可变的树形数据结构(类似虚拟 DOM),所有编辑操作都通过事务(transaction)修改状态,框架再将状态变化映射为 DOM 更新。Tiptap 是基于 ProseMirror 的上层封装,提供了更友好的 API 和开箱即用的扩展。两者都建立在 contenteditable 之上,通过劫持浏览器事件、规范化 DOM 结构来"驯服" contenteditable 的不一致性。相比之下,Oasis Editor 的 Canvas 方案完全抛弃了 DOM 作为文档表示,需要自己实现类似的状态管理和命令系统,但换来了对渲染层的绝对控制权。

对于需要深度定制编辑器行为的开发者来说,类型化的 API 意味着更好的开发体验和更少的运行时错误。

DOCX 和 PDF 导入导出工作流

作为一个定位为「docx 文档编辑器」的项目,对 DOCX 和 PDF 的导入导出支持是核心刚需。Oasis Editor 内建了这两种格式的工作流,这也是作者特别希望社区帮忙打磨的方向之一——导入导出的保真度(import/export fidelity)。

DOCX 格式极其复杂。DOCX 是 Microsoft Office Open XML 的文档格式,本质是一个包含 XML 文件和资源文件的 ZIP 压缩包。其核心结构包括 document.xml(正文内容)、styles.xml(样式定义)、numbering.xml(列表编号)等。复杂性体现在:样式系统支持继承和覆盖;表格支持嵌套、跨页、单元格合并和复杂边框样式;页眉页脚可以首页不同、奇偶页不同,且包含域代码实现动态内容如页码;图片锚定支持 inline(随文字流动)和 absolute(固定位置)两种模式。

要实现高保真导入导出,需要完整解析 Office Open XML 规范(超过 5000 页文档),处理字体嵌入、修订追踪、脚注尾注等几十种特性。包含样式继承、嵌套表格、复杂页眉页脚等大量细节,要做到与 Microsoft Word 高度兼容需要长期持续投入。

React 和 Vue 框架适配器

项目同时提供了 React 和 Vue 适配器,大幅降低了在主流前端框架中集成的门槛。无论你的项目技术栈是哪一种,都可以相对便捷地接入 Oasis Editor。

无头运行时(Headless Runtime)

更说个细节 Oasis Editor 还包含一个 headless runtime(无头运行时),编辑器的核心逻辑可以脱离 UI 独立运行。这打开了许多服务端应用场景:

服务端文档处理与格式转换
批量文档自动化排版
CI/CD 管道中的文档生成

这种「核心与视图分离」的架构设计,是现代编辑器框架的一个重要发展趋势。

在线体验与社区参与方式

作者已经提供了在线体验地址和 GitHub 仓库,任何人都可以直接试用并查看源码。

在发布帖中,作者明确表达了对社区反馈和贡献的期待,重点征集以下方向的帮助:

渲染(rendering):Canvas 引擎的性能优化与渲染正确性
文档布局(document layout):分页、排版几何逻辑的完善
插件生态(plugins):丰富编辑器的扩展能力
导入导出保真度:提升 DOCX/PDF 与 Microsoft Office 等主流工具的兼容性

这几个方向恰好也是自研渲染引擎类项目最难突破的技术关卡。

Canvas-first 文档编辑器的价值与挑战

Oasis Editor 让人联想到近年来兴起的一批「Canvas-first」文档产品思路。国内外都有团队意识到,要真正实现 Word 级别的分页排版和跨端一致性,contenteditable 迟早会成为技术瓶颈。腾讯文档、飞书文档等商业产品在演进过程中也不同程度地引入了自绘渲染方案。

从工程角度看,一个人(或小团队)从零构建 Canvas 渲染引擎、命令系统、插件架构、多框架适配和 DOCX/PDF 双向转换,工作量相当惊人。真正的挑战不在于把文字画到 Canvas 上,而在于把浏览器原本免费提供的那些「隐形能力」——IME 输入法支持、无障碍访问、光标管理、复制粘贴——一一补齐。这往往决定了此类项目能否走向生产环境。

对于关注开源编辑器技术的开发者而言,Oasis Editor 是一个非常好的学习案例:它完整展示了如何绕开 contenteditable,从底层构建一套文档编辑系统。无论是想深入理解富文本编辑器的工作原理,还是正在寻找可深度定制的开源文档编辑方案,这个项目都值得持续关注和实际参与。