1723 天前,我提交了 Canvas Editor 的第一行代码。1460 次提交之后,它正式发布了 1.0.0。

促成 1.0 的最后一块拼图,是一个挂了 1556 天的 issue(#41)。2022 年 4 月 28 日,有用户留下一句话:

跨页表格在修改列宽的时候,不能够同步。

1556 天、39 条讨论之后,这个 issue 随 1.0 一起关闭。

这篇文章聊三件事:表格分页为什么难、最终的解法是什么、1.0 还有哪些东西。

项目是什么

Canvas Editor 是一个基于原生 Canvas 渲染的富文本编辑器:不用 contenteditable,不用 DOM 排版,文档里每一个字、每一条表格线、每一个分页符,都是 Canvas API 画出来的。

为什么走这条更难的路线?因为目标场景是电子病历(EMR)、合同、公文这类严肃文书——表格跨页列宽不能错、修改要留痕、控件要能级联校验、打印要和屏幕所见尽量一致。而这些,恰好是 contenteditable 最不稳定的地方。

2021 年 11 月 12 日第一次提交,到 1.0.0 发布:1723 天、1460 次提交、139 个版本。

表格分页:为什么一个 issue 能挂四年

跨页表格是 Canvas 编辑器里最复杂的渲染路径之一:

• 表格行要在页边界动态拆分,拆分点随内容变化;

• 拆分后,各页列宽必须严格一致;

• 单元格里如果有图片、列表、子表格,行高要随内容自适应;

• 光标、选区、中文输入法,都要在分页之后正确响应。

方案演进:数据层拆分 → 渲染层切分

第一版思路(2024 年前后):数据层拆分。 把超出当前页的行拆出来,物理上形成一个新表格;渲染时先合并再拆分,保存时再合并。这个方案解决了"能分页",但天花板很低:分页后的表格一变就无法还原,合并行单元格跨页失效、单格超高不跨页、控件跨行丢内容……issue 里这类边界反馈持续出现。本质问题是:数据被物理切成两段之后,所有操作都要为"同步两段状态"付代价,而边界的组合是无穷的。

社区协作(2025)。 期间社区陆续贡献了一些思路和 PR。结合这些实现,我在 poc/table-paging 分支做了可行性验证,梳理出一张完整的待办清单:跨页中文输入、跨页删除/书写/方向键光标、选区跨页拖蓝、控件跨页、复合元素跨页、边界处理。这张清单,基本划定了这个问题的真实工作量。

最终方案(2026.07):渲染层切分。 核心思路转换:放弃数据层的物理切割,只在渲染层切分——文档数据始终保持完整,只在 Canvas 绘制阶段计算分页截断位置。相当于一次"降维":之前大量的状态同步类 bug 不是被修掉的,而是不再存在了。

这次改动的规模(commit: feat: optimize table pagination #41)

• 新增 TablePaging 分页计算模块,约 740 行:负责跨页截断点的测量;

• 重写 TableParticle 渲染逻辑,约 510 行改动;

• Position 光标系统跨页适配,约 500 行改动:覆盖跨页中文输入、删除/书写/方向键光标、选区拖蓝;

• 配套 1600+ 行单元测试;

• 合计 3373 行新增。

同时落地:rowspan 高内容单元格行高自适应、表格宽度自适应内容与页面(#1387 #1453)、跨页列宽同步。

补充一句:最后的重构阶段使用了 AI 编程工具辅助,效率提升明显,这点在 issue 里也有公开说明。四年的断断续续思考、社区 PR 的思路、工具效率的提升,三件事叠在一起,才把这块硬骨头啃下来。

1.0 还带了什么

🖋 留痕模式(#312) —— 类 Word 修订:增删改留痕,删除内容划删除线,悬停显示谁改的、什么时候改的,痕迹可见性可控。病历质控、合同审阅、公文批改都能直接用。

🔗 控件级联与表达式(#671) —— Select/Radio/Checkbox/文本控件之间建立父子联动 + 校验,支持表达式自动计算:输入身高 170cm、体重 100kg,BMI 自动算出 34.6 并联动"肥胖干预建议";选"有高血压",自动带出"高血压分级"必填。文档模板可以自带一部分业务逻辑。

📰 排版能力 —— 多栏布局(#1237)、图片四周环绕(#554,签名图文字绕排)、水平+垂直双标尺(#438)、多级有序列表(#440)。

📑 区域子文档 —— 一份文档内划分多个独立编辑区(主病历 + 补充病历各管各的,还能放进表格单元格),配套完整的 Area API。

此外还有控件嵌套(#425)、宏录制回放(#478)、文档对比 API(#1024)等,完整清单在 Release Notes。

一些数据

项目在业余时间维护,数据全部可查:

• 1723 天,1460 次提交,139 个版本,479 个 issue 被处理

• 近 3 年 781 次提交;162 次提交发生在深夜 10 点以后,245 次在周末

• GitHub 5000+ Star,845 Fork

1.0 不是一个人的结果:#41 的最终方案吸收了多位社区同学 PR 的思路,在 POC 分支公开验证过;issue 区里持续反馈边界 case 的用户,实际上帮项目做了大量测试。一个问题挂了四年,最后是很多人一起把它推过终点线的。

1.0 之后

API 冻结,进入 SemVer,1.x 无破坏性变更。0.9.x 用户可以直接升:

npm install @hufe921/canvas-editor@1.0.0

路线图(按优先级):大文本渲染性能、渲染层独立(同一份文档模型可输出 SVG/PDF/DOM)、多光标选区、协作编辑能力——哪个呼声高先做哪个。

项目会一直 MIT 开源。如果它对你有用,Star、转发都是支持;想赞助的话文末有渠道,量力而行。

项目地址

• GitHub:https://github.com/Hufe921/canvas-editor

• 在线 Demo:https://hufe.club/canvas-editor

• 文档:https://hufe.club/canvas-editor-docs

• 赞助:https://oscimg.oschina.net//oscnet/transfer/up-2562e1fd59636ba603208aee7bd8a856.jpg