Hufe921/canvas-editor · 上手攻略

仓库：Hufe921/canvas-editor
链接：https://github.com/Hufe921/canvas-editor
分类：rich-text-editor / canvas / academic-writing
作者：Tom
更新：2026-07-19

一、是什么

Canvas Editor 是一个基于 HTML <canvas> API 构建的富文本编辑器（WYSIWYG），与传统的 contenteditable 方案完全不同。它完全接管渲染管线，在 Canvas 画布上绘制文字、表格、图片、公式等所有内容，从而实现跨浏览器像素级一致的排版输出。

核心技术特点： - 渲染引擎基于 Canvas Draw，不依赖浏览器内置的排版引擎 - 支持分页、页眉页脚、水印、目录（TOC）生成 - 表单控件（Select / Text / Date / Radio / Checkbox） - LaTeX 数学公式渲染 - Web Workers 处理异步操作（字数统计、目录生成） - 插件系统支持扩展

典型使用场景： 电子病历（EMR）、法律合同、正式报告、OA 文档等需要精确打印输出的 Web 应用。

二、快速安装

npm install @hufe921/canvas-editor
# 或
pnpm add @hufe921/canvas-editor
# 或
yarn add @hufe921/canvas-editor

版本（截至 2026-07）： npm 最新版本为 0.9.136（发布于约 3 天前）。

运行时要求： Node.js ≥ 24.13.1

开发环境启动：

git clone https://github.com/Hufe921/canvas-editor.git
cd canvas-editor
pnpm install
npm run dev

三、核心用法

3.1 最简使用

<div class="canvas-editor"></div>

<script type="module">
import Editor from '@hufe921/canvas-editor'

const container = document.querySelector('.canvas-editor')

const editor = new Editor(container, {
  main: [
    {
      value: 'Hello, Canvas Editor!'
    }
  ]
})

3.2 构建为可发布库

npm run lib   # 构建发布级库
npm run build # 构建演示页面

3.3 开发与测试

npm run dev          # 开发服务器
npm run lint         # 代码检查
npm run type:check   # TypeScript 类型检查
npm run test:unit    # Vitest 单元测试
npm run cypress:run  # Cypress E2E 测试（headless）
npm run cypress:open # Cypress E2E 测试（交互模式）

3.4 文档构建

npm run docs:dev    # 本地预览 VitePress 文档
npm run docs:build  # 构建文档网站

四、架构速览

src/editor/
├── core/
│   ├── draw/          # Canvas 渲染引擎
│   │   ├── particle/  # 各类元素渲染器（text, image, table, latex...）
│   │   ├── control/   # 表单控件渲染
│   │   ├── frame/    # 框架元素（页边距、背景、边框）
│   │   ├── richtext/  # 文字装饰（下划线、高亮）
│   │   └── interactive/ # 交互特性（搜索、批注）
│   ├── command/       # 命令模式（executeBold, executeUndo...）
│   ├── event/         # Canvas 与全局事件处理
│   ├── observer/      # 鼠标、选区、图片观察者
│   ├── worker/        # Web Workers（异步操作）
│   └── plugin/        # 插件系统
├── interface/         # TypeScript 接口
├── dataset/           # 枚举与常量
└── utils/            # 工具函数

五、实验性功能（注意版本）

功能	分支/路径	说明
SVG 渲染层	`feature/svg`	Canvas + SVG 双引擎（开发中）
PDF 导出	`feature/pdf`	PDF 导出能力
AI 文字处理	`feature/ai`	AI 辅助编辑演示
表格分页	`poc/table-paging`	表格跨页 POC
CRDT 协作	`feature/CRDT`	多人实时协作（实验性）

六、适用场景

✅ 需要像素级精确打印输出的文档系统（合同、证书）
✅ 电子病历、政务文书等强格式要求场景
✅ 企业内部 OA 需要分页、页眉页脚、目录的应用
✅ 需要自定义右键菜单、快捷键的定制化编辑体验
❌ 简单评论框、即时通讯富文本 → 建议用 Quill / TipTap
❌ 需要强协作能力 → 考虑 Yjs + Canvas 方案

七、坑与注意

Node.js 版本要求高：项目要求 Node.js ≥ 24.13.1，部分旧系统可能需要升级。
contenteditable 不可用：所有文本编辑均基于 Canvas 绘制，与传统编辑器生态完全不同，第三方插件（如 contenteditable 生态的 Paste Markdown 插件）无法直接使用。
导出 PDF 需要 feature/pdf 分支：主分支不包含 PDF 导出，需切换到 feature/pdf 分支。
实验性功能风险：feature/CRDT 等分支为实验性，不建议直接在生产中使用。
移动端支持：官方 Demo 和文档以桌面端为主，移动端体验未明确说明。

八、与同类对比

特性	Canvas Editor	Quill	TipTap	Prosemirror
渲染基础	Canvas	contenteditable	contenteditable	contenteditable
打印精确度	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐	⭐⭐
公式支持	LaTeX 原生	需插件	需插件	需插件
表格分页	支持	不支持	不支持	需插件
协作	实验性	需搭配 Yjs	原生	原生
体积	较大	轻量	中等	轻量
扩展性	插件系统	有限	插件生态	丰富

九、一句话结论

如果你需要 Word 级的精确打印输出（合同、证书、病历），且愿意接受一个 Canvas-based 的非主流技术路线，Canvas Editor 是目前开源领域最完整的方案；如果是普通 Web 富文本需求，Quill / TipTap 生态更成熟。

推荐资源： - 官方文档：https://hufe.club/canvas-editor-docs - 在线 Demo：https://hufe.club/canvas-editor - AI 辅助问答：https://zread.ai/Hufe921/canvas-editor