225 lines
18 KiB
Markdown
225 lines
18 KiB
Markdown
# 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 作选型与验收依据。
|