Files

18 KiB
Raw Permalink Blame History

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 选型一致。

理由三句:

  1. 当前规模(最大 128×128=16,384 豆)远低于 leafer 的性能优势起点(官方基准是 100 万对象),静态预览 + 一次性导出场景下,原生 Canvas 2D 单帧重绘 ≈ 1–5ms,leafer 的「百万对象、批处理 DrawCall」优势无感。
  2. leafer 的真正价值在本项目的交互与动画:内置拖拽/缩放/毫秒级点选命中、脏矩形局部刷新、属性补间(对应 ANIMATION-PLAN E-04/E-05/E-06)——这些是 V2 编辑画布升级的硬需求,V1 不出现。
  3. 引入成本真实存在: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 为什么不是「立即替换」?

  1. 规模不匹配:16,384 豆 vs leafer 百万对象基准,静态渲染零收益。
  2. 编辑操作是数组变换:旋转/镜像等走整树重建路径,leafer 脏矩形优势用不上(§4.3)。
  3. 导出已验证:buildExportCanvas/downloadCanvas 全链路已验收(含设计规范 §5),为一次性操作重写不划算。
  4. 成本真实:70KB+ min+gzip 依赖、渲染层重写、无官方 React 绑定需自建桥接、2.2.x 版本演进快需锁版本。

5.2 为什么是「V2 引入」(而不是永远不换)?

  1. 交互是差异化刚需:竞品基线(拖拽/缩放/命中)与 ANIMATION-PLAN E-04/05/06 都指向画布交互层,leafer 内置能力直接覆盖,自写方案(矩阵变换+反算命中+局部刷新)成本更高。
  2. 性能天花板:>1 万豆 + 逐帧动画 + 持续拖拽时,原生全量重绘必然掉帧;leafer 迁移实证(帧率 25→60、DrawCall 800+→<50、点选 80→10ms)正是该场景的对症数据。
  3. 动画层依赖:ANIMATION-PLAN 分层架构把 leafer 定为「第 1 层 画布渲染/交互」,anime.js 在其上做 spring/stagger——不引入 leafer,E-04/E-05 差异化动效无落地载体。
  4. MIT 永久开源、免费商用:无许可/供应商锁定风险。

5.3 边界(防止双引擎并存混乱)

  • leafer 只接管「预览编辑画布」(有交互/动画诉求的实时视图)。
  • Canvas 2D 保留「导出」(PNG/PDF 一次性离屏)与「后端/其他业务渲染」。
  • 二者通过数据层隔离:leafer 读同一 ProcessResult/editedResult,导出复用现有 buildExportCanvas,同一数据源、双输出端。

6. 实施路径(若 V2 引入)

6.1 迁移步骤

  1. 引入依赖:leafer-ui@^2.2.9 + @leafer-ui/core@^2.2.9(同步版本,防版本漂移);锁定精确版本,评估裁剪 @leafer-ui/draw 等子包。
  2. React 桥接层:新建 LeaferCanvas.tsx(useRef + useEffect,挂载建 Leafer({ view })、卸载 leafer.destroy()、重绘节流)——无官方绑定,桥接自维护,API 面收窄到 Leafer/Rect/Circle/Group。
  3. 渲染替换:drawPreview 的场景化重写:
    • Group(Beans):每豆 1 个 Circle(fill=rgb,radius=cell×0.42);
    • Group(GridLines):网格线(5/10 加粗标号沿用现有 drawGrid 逻辑);
    • 监听 editedResult 变化 → 整图变换(旋转/镜像)走全量重建;逐豆操作走对象级更新。
  4. 交互层(E-06):draggable 平移 + 滚轮缩放 + 点选命中(leafer 内置)。
  5. 动画接入(E-04/E-05):leafer transition 属性补间或 anime.js spring/stagger,对齐 ANIMATION-PLAN §5.3 参数(spring stiffness 170/damping 26、120–180ms)。
  6. 导出不动:buildExportCanvas/downloadCanvas 保持 Canvas 2D,Export 仅作可选评估项。
  7. 验收口径(对齐 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 选型):

  1. 导出通道保留 Canvas 2D(ANIMATION-PLAN 未明确导出层归属,本评估划定边界,防止双引擎并存混乱);
  2. 编辑操作为数组级变换时 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 作选型与验收依据。