18 KiB
LEAFER-EVAL · leafer.js 图纸渲染引擎评估报告
任务: T-085(前端:leafer.js 图纸渲染引擎评估——替代/对比现有 Canvas 2D 渲染的可行性、性能、成本) 日期: 2026-08-14 范围: 本任务只产出评估文档,不含任何源码改动、不引依赖入库 适用前端:
D:\拼豆\perler-lab(Vite 5 + React 18 + TS 5.9,当前 0 渲染库依赖,原生 Canvas 2D) 交叉引用:docs/ANIMATION-PLAN.md(§动画选型,已评估 leafer.js 用于 V2 画布升级)→ 本任务聚焦图纸渲染引擎替换评估,非动画
0. 决策摘要(一句话结论)
V1 不换(保留原生 Canvas 2D 全链路);V2 编辑画布升级时引入 leafer.js 替换预览渲染层;PNG/PDF 导出通道保留 Canvas 2D——即「混合引入,分层边界」,与 ANIMATION-PLAN.md 选型一致。
理由三句:
- 当前规模(最大 128×128=16,384 豆)远低于 leafer 的性能优势起点(官方基准是 100 万对象),静态预览 + 一次性导出场景下,原生 Canvas 2D 单帧重绘 ≈ 1–5ms,leafer 的「百万对象、批处理 DrawCall」优势无感。
- leafer 的真正价值在本项目的交互与动画:内置拖拽/缩放/毫秒级点选命中、脏矩形局部刷新、属性补间(对应 ANIMATION-PLAN E-04/E-05/E-06)——这些是 V2 编辑画布升级的硬需求,V1 不出现。
- 引入成本真实存在:leafer-ui 2.2.9(unpacked ≈ 4.2MB,核心裁剪 ≈ 70KB min+gzip)、无官方 React 绑定(需自维护 useEffect+ref 桥接)、渲染层整树重建。V1 为不存在的需求付这笔成本不成立。
1. 现状盘点:现有图纸渲染链路
1.1 代码链路
| 模块 | 职责 | 机制 |
|---|---|---|
src/lib/pattern-renderer.ts |
基础绘制:renderPattern 逐格 fillRect(20px 格)+ drawPaletteLegend + rgbToCss |
Canvas 2D |
src/lib/drawPattern.ts |
预览 drawPreview:逐格 arc(圆豆,radius=cell×0.42)+ 网格线(每 5 格加粗、每 10 格标号)+ PNG 导出 buildExportCanvas(cell 22/28px + 标题 + 备豆清单) |
Canvas 2D |
src/components/PreviewPanel.tsx |
预览画布宿主:useEffect 监听 result / gridSize / showGrid 变化 → 全量调 drawPreview |
全量重绘 |
src/App.tsx |
applyEdit(撤销/重做/旋转/镜像/翻转)→ 改 editedResult 的 grid 数组 → 触发 PreviewPanel 全量重绘 |
数据层数组变换 + 全量重绘 |
| 导出 | buildExportCanvas 离屏一次性渲染 → canvas.toBlob PNG |
一次性渲染 |
1.2 场景规模(实测自 ControlsPanel.tsx / ChibiPage.tsx)
GRID_MIN=16,GRID_MAX=128,预置[32, 64, 96, 128],chibi 默认 64。- 最大格数 128×128 = 16,384 格,即 ≤16,384 颗豆(每格 1 圆)。
- 预览 canvas:
gridSize×8px + 18×2px边框(128 格 ≈ 1,060px);当前无缩放/平移交互。 - 导出 canvas:
gridSize≥96 时 cell=22px(128 格 ≈ 2,816px 宽)。
1.3 当前性能瓶颈(任务描述「放大/编辑时」)
- 编辑路径:每次旋转/镜像/翻转/撤销 → grid 数组整体变换 →
drawPreview全量重绘(≤16,384 次beginPath+arc+fill+ 网格线)。单次约 5–15ms,无肉眼卡顿,但无局部更新、无场景缓存,编辑粒度与渲染粒度脱节。 - 放大路径:预览无缩放,用户感知的「放大」实际是导出(22/28px 大格)——属一次性渲染,非交互热点。
- 结论:现有瓶颈是「全量重绘架构 + 无交互层」的结构性问题,不是 fillRect/arc 吞吐量问题。
2. leafer.js 调研(2026-08-14 npm 实测 + 官方文档抓取)
2.1 是什么
leafer.js(LeaferUI)是国产原创 2D Canvas 渲染引擎,场景树(scene graph)架构,定位「大规模、高密度、海量图层」生产力工具(Figma 级编辑器 / 无限画布)。5 年沉淀,GitHub 4.3k stars,官方 benchmark 对标 Pixi/Konva/Fabric。
2.2 版本与体积(npm 实测)
| 包 | 版本 | unpackedSize | 说明 |
|---|---|---|---|
leafer-ui |
2.2.9(latest stable) | 4,356,846 B(≈4.2MB) | 全量 UI(含 Editor 插件/动画/布局) |
@leafer-ui/core |
2.2.9 | 445,514 B(≈435KB) | 跨平台渲染核心(可裁剪) |
@leafer-ui/draw |
2.2.9 | — | 基础绘制模块 |
leaferjs |
2.0.1-beta.0 | 2.2MB | 主集成包(beta,不推荐生产) |
@leafer-ui/react |
不存在(E404) | — | 无官方 React 绑定 |
@leafer-ui/webgl |
不存在(E404) | — | 渲染后端为 Canvas 2D,无 WebGL 包 |
官方 README 声明核心场景 70KB min+gzip、零依赖。体积可按需裁剪(只引 @leafer-ui/core + 所需显示对象)。
2.3 核心能力(官方文档确认)
- 图形系统:完整场景树,矢量图形 / SVG 路径 / 像素操作;
Rect、Circle/Ellipse、Group等显示对象;类 DOM API(add/remove/clear)。 - 极致性能:官方 benchmark——100 万个可交互矩形:首屏创建 1.28s vs 传统 Canvas 库 9–15s(约快 8x);内存 320MB vs 2–4GB(约省 8x);单元素拖拽 60FPS vs 0–4FPS(约流畅 15x)。
- 技术机制:批处理 DrawCall + 脏矩形局部刷新 + 毫秒级命中检测(Hit Testing)。
- 内置交互:原生
draggable、缩放、多点触控;Editor 插件一键开旋转/缩放/多选。 - 导出:
Export.png/jpeg/webp/canvas/download(element, …),支持scale缩放导出。 - 动画:内置状态驱动属性补间(
transition)+ 路径动画(V2 E-04/E-05 可直接用)。 - 跨平台:Web / Node.js(离屏渲染、SSR 出图)/ 微信小程序 / H5,一套代码。
- 许可:MIT,永久开源,可免费商用;商业插件(PxGrow 编辑器套件/性能优化)为可选,非必需。
2.4 迁移实证(竞品调研,competitor-analysis/animation-research.md §3.2-1)
像素编辑器 Konva→Leafer 迁移实录:1000 元素、4K 屏,帧率 25–30→58–60 FPS、内存 120MB→40MB、DrawCall 800+→<50、点选命中 80ms→10ms。 佐证:百度像素风编辑器迁移文章 + 开源 Canva 平替 Gzm Design 均选 LeaferJS。
3. leafer.js vs 现有 Canvas 2D 对比表
| 维度 | 现有原生 Canvas 2D(fillRect/arc 逐格) | leafer.js(leafer-ui 2.2.9) | 判定 |
|---|---|---|---|
| 渲染性能(静态一次性) | 16k 格重绘 ≈ 1–5ms,完全够用 | 场景树 + 脏矩形,静态一次性场景收益 ≈ 0 | 平手(本项目规模) |
| 渲染性能(持续交互/动画) | 全量重绘,>1 万豆 + 逐帧动画必掉帧 | 局部刷新 + 批处理 DrawCall,官方 1M 对象 60FPS | leafer 大幅胜 |
| 内存 | 一次性像素缓冲,无对象开销 | 每豆一显示对象(16k Circle),静态场景反而略重 | Canvas 略胜(静态) |
| 缩放/平移/点选命中 | 无内置,需手写 | 内置 draggable/缩放/毫秒级命中 |
leafer 大幅胜 |
| 局部更新(编辑单格/单豆) | 无场景缓存,只能全量重绘 | 脏矩形局部刷新 + 对象级属性更新 | leafer 大幅胜 |
| API 友好度 | 命令式(ctx.fillRect),300 行自维护 |
类 DOM 场景树,leafer.add(rect) 声明式 |
leafer 胜 |
| React 集成 | 原生,canvasRef 直接可用 |
无官方绑定,需自建 useEffect+ref 桥接层 |
Canvas 胜 |
| 包体积 | 0 | core 裁剪 ≈ 70KB min+gzip;全量 4.2MB | Canvas 胜 |
| 导出能力 | buildExportCanvas+toBlob 已验证(PNG/PDF 复用) |
Export.png/canvas 内置(支持 scale) |
平手(导出需重写) |
| 学习成本 | 已有存量代码,团队已会 | 新 API,现代类 Fabric/Konva 但更简,文档中文友好 | Canvas 略胜(存量) |
| 许可 | 自有 MIT | MIT 永久开源、免费商用 | 平手 |
| 生态成熟度 | — | 较新(4.3k stars),第三方插件少,版本演进快(2.2.x) | Canvas 稳,leafer 需锁版本 |
| 动画能力 | 无(动画靠 CSS 层) | 内置属性补间 + 路径动画(E-04/E-05/E-06 直接可用) | leafer 大幅胜 |
对比表结论:在「静态预览 + 一次性导出」的当前 V1 场景,leafer 对 Canvas 2D 无性能优势、有体积与集成成本;在「交互编辑 + 动画」的 V2 场景,leafer 全面胜出。胜负完全取决于是否引入交互层。
4. 拼豆图纸渲染场景适配性分析
4.1 场景 A:大量矩形/圆形豆子绘制(静态预览)——不匹配 leafer 优势
- 本项目最大 16,384 豆;leafer 官方基准是 100 万对象(约 60 倍差距)。
- 原生 Canvas 2D 一次性绘制 16k 圆 ≈ 1–5ms;leafer 引入 16k 显示对象建树 + 序列化场景,静态首帧不会更快,内存反而更高(对象元数据开销)。
- 结论:纯静态预览 = 不换。
4.2 场景 B:缩放平移(画布拖拽,对齐竞品基线 / ANIMATION-PLAN E-06)——leafer 强项
- 当前预览无任何缩放/平移,竞品基线明确要求
translate3d合成层拖拽(E-06 P2)。 - leafer 内置
draggable+ view 缩放 + 毫秒级命中,一个drag示例即覆盖需求,无需手写矩阵变换 + 反算命中。 - 结论:引入交互层时,leafer 直接解决。
4.3 场景 C:局部更新(编辑画布场景)——关键认知修正
- 当前编辑操作(旋转/镜像/翻转/撤销)是 grid 数组级变换(
rotateGrid等),不是单豆级修改 → 在 leafer 下也只能整树重建(数组变换 → 重建场景),脏矩形局部刷新优势被抵消。 - leafer 的局部更新优势只对 E-04 逐豆放置/编辑(用户点一格改一颗)生效——这才是 leafer 真正发挥的场景。
- 结论:leafer 对「整图变换」无加速,对「逐豆交互编辑」显著加速。实施时应把编辑交互拆成「整图变换(全量重建)」与「逐豆操作(对象级更新)」两条路径。
4.4 场景 D:导出(PNG/PDF)——不换
- 导出是一次性离屏渲染(cell 22/28px),非交互热点;
buildExportCanvas已验收(含标题/备豆清单/PDF 复用)。 - leafer 的
Export可替代但无必要:为一次性操作引入依赖 + 重写导出逻辑 + 回归测试,收益为负。 - 结论:导出通道保持 Canvas 2D,与 leafer 分层隔离(leafer 只做编辑画布交互层)。
4.5 适配性评分
| 场景 | 原生 Canvas 2D | leafer.js | 优势方 |
|---|---|---|---|
| 静态预览(≤16k 豆) | ★★★★★ | ★★★☆ | Canvas 2D |
| PNG/PDF 一次性导出 | ★★★★★ | ★★★☆ | Canvas 2D |
| 缩放/平移/点选交互 | ★★☆(手写) | ★★★★★ | leafer |
| 逐豆放置/编辑(E-04/E-05) | ★★☆(全量重绘) | ★★★★★ | leafer |
| 动画(E-04/05/06 补间) | ★(靠 CSS 层) | ★★★★★ | leafer |
5. 推荐结论 + 理由
结论:混合引入(V1 不换 → V2 编辑画布升级引入 leafer.js,导出保留 Canvas 2D)。
5.1 为什么不是「立即替换」?
- 规模不匹配:16,384 豆 vs leafer 百万对象基准,静态渲染零收益。
- 编辑操作是数组变换:旋转/镜像等走整树重建路径,leafer 脏矩形优势用不上(§4.3)。
- 导出已验证:
buildExportCanvas/downloadCanvas全链路已验收(含设计规范 §5),为一次性操作重写不划算。 - 成本真实:70KB+ min+gzip 依赖、渲染层重写、无官方 React 绑定需自建桥接、2.2.x 版本演进快需锁版本。
5.2 为什么是「V2 引入」(而不是永远不换)?
- 交互是差异化刚需:竞品基线(拖拽/缩放/命中)与 ANIMATION-PLAN E-04/05/06 都指向画布交互层,leafer 内置能力直接覆盖,自写方案(矩阵变换+反算命中+局部刷新)成本更高。
- 性能天花板:>1 万豆 + 逐帧动画 + 持续拖拽时,原生全量重绘必然掉帧;leafer 迁移实证(帧率 25→60、DrawCall 800+→<50、点选 80→10ms)正是该场景的对症数据。
- 动画层依赖:ANIMATION-PLAN 分层架构把 leafer 定为「第 1 层 画布渲染/交互」,anime.js 在其上做 spring/stagger——不引入 leafer,E-04/E-05 差异化动效无落地载体。
- MIT 永久开源、免费商用:无许可/供应商锁定风险。
5.3 边界(防止双引擎并存混乱)
- leafer 只接管「预览编辑画布」(有交互/动画诉求的实时视图)。
- Canvas 2D 保留「导出」(PNG/PDF 一次性离屏)与「后端/其他业务渲染」。
- 二者通过数据层隔离:leafer 读同一
ProcessResult/editedResult,导出复用现有buildExportCanvas,同一数据源、双输出端。
6. 实施路径(若 V2 引入)
6.1 迁移步骤
- 引入依赖:
leafer-ui@^2.2.9+@leafer-ui/core@^2.2.9(同步版本,防版本漂移);锁定精确版本,评估裁剪@leafer-ui/draw等子包。 - React 桥接层:新建
LeaferCanvas.tsx(useRef+useEffect,挂载建Leafer({ view })、卸载leafer.destroy()、重绘节流)——无官方绑定,桥接自维护,API 面收窄到Leafer/Rect/Circle/Group。 - 渲染替换:
drawPreview的场景化重写:Group(Beans):每豆 1 个Circle(fill=rgb,radius=cell×0.42);Group(GridLines):网格线(5/10 加粗标号沿用现有 drawGrid 逻辑);- 监听
editedResult变化 → 整图变换(旋转/镜像)走全量重建;逐豆操作走对象级更新。
- 交互层(E-06):
draggable平移 + 滚轮缩放 + 点选命中(leafer 内置)。 - 动画接入(E-04/E-05):leafer
transition属性补间或 anime.jsspring/stagger,对齐 ANIMATION-PLAN §5.3 参数(spring stiffness 170/damping 26、120–180ms)。 - 导出不动:
buildExportCanvas/downloadCanvas保持 Canvas 2D,Export仅作可选评估项。 - 验收口径(对齐 ANIMATION-PLAN §7 V2):>1 万豆拖拽/放置保持 60FPS;DrawCall <50、点选命中 <10ms;双引擎边界清晰(预览=leafer,导出=Canvas 2D)。
6.2 风险与缓解
| 风险 | 缓解 |
|---|---|
| 无官方 React 绑定,桥接自维护 | 收窄 API 面(仅 4 个类);卸载清理 destroy();重绘防抖/节流 |
| 版本演进快(2.2.x,leaferjs 主包还在 beta),API 漂移 | 锁精确版本;只依赖稳定核心类;升级走独立任务 + 回归 |
| 每豆一对象的静态开销(16k 对象 vs 一次性 fillRect) | 静态首帧仍可走全量批量;对象化收益留待交互/动画路径 |
| 编辑=数组变换时无加速(§4.3) | 明确拆分:整图变换全量重建、逐豆操作对象级更新;验收锚定后者 |
| 双引擎并存职责混淆 | §5.3 边界写入代码结构:预览组件只依赖 leafer,导出只依赖 Canvas 2D |
| 社区较新、第三方插件少 | 仅用官方核心能力,不依赖第三方插件 |
7. 与 ANIMATION-PLAN.md 一致性校验
| ANIMATION-PLAN.md 结论 | 本评估 | 一致性 |
|---|---|---|
| §2/§3:leafer.js 定为「V2 引入(画布层)」,「图纸网格渲染/豆子交互/拖拽(核心差异化)」 | V2 引入 leafer 替换预览渲染层(交互+动画) | ✅ 一致 |
| §6.2:「>1 万豆 V1 保持原生 fillRect;leafer.js 迁移 V2 一次性承担,避免 V1 双渲染引擎并存」 | V1 不换、导出保留 Canvas 2D、V2 一次性引入并划定「预览=leafer / 导出=Canvas 2D」边界 | ✅ 一致(并细化边界) |
| §2 体积评估:「leafer 按需模块,数百 KB 级(仅画布层承担)」 | npm 实测 core 435KB unpacked / 核心场景 70KB min+gzip,按需裁剪成立 | ✅ 一致(数据落实) |
| §7 V2 验收:「>1 万豆拖拽/放置 60fps、DrawCall <50、点选 <10ms」 | 本评估 §6.1-7 采纳为 leafer 引入验收口径 | ✅ 一致 |
| §5.3 E-04/E-05/E-06(豆子 spring、闪烁、拖拽) | leafer 内置交互/补间覆盖,anime.js 按需叠加 | ✅ 一致 |
一致性结论:无冲突。 本评估补充两点增量认知(不改变 ANIMATION-PLAN 选型):
- 导出通道保留 Canvas 2D(ANIMATION-PLAN 未明确导出层归属,本评估划定边界,防止双引擎并存混乱);
- 编辑操作为数组级变换时 leafer 整树重建无加速(纠正「引入 leafer 即解决编辑瓶颈」的朴素预期,把收益锚定在逐豆交互/动画)。
8. 数据来源
- npm 实测(2026-08-14):
leafer-ui@2.2.9/@leafer-ui/core@2.2.9/@leafer-ui/draw版本与 unpackedSize;@leafer-ui/react、@leafer-ui/webgl不存在(E404 实证)。 - leafer-ui 官方 README / GitHub(github.com/leaferjs/leafer-ui):MIT 许可、70KB min+gzip、100 万矩形 benchmark(1.28s / 320MB / 60FPS)、Export 模块、React/WebGL 无官方包。
- 官方文档(context7 /leaferjs/leafer-ui):场景树 API、
Group/Rect、Export.png/canvas、new Leafer({ view })、draggable。 - 竞品调研(
competitor-analysis/animation-research.md§3.2-1):Konva→Leafer 迁移实测(1000 元素 4K:帧率 25–30→58–60、内存 120→40MB、DrawCall 800+→<50、点选 80→10ms)。 - 本项目现状(
perler-lab/src抽查):drawPattern.ts/pattern-renderer.ts/PreviewPanel.tsx/App.tsx/ControlsPanel.tsx(GRID_MIN=16、GRID_MAX=128、预置 [32,64,96,128])。
附注:本报告为纯评估文档,不构成实施;后续实施任务引用本报告 §5/§6 作选型与验收依据。