Files
perler-lab/docs/LEAFER-EVAL.md
T

225 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 作选型与验收依据。