16 KiB
ANIMATION-PLAN · 拼豆图纸生成器 动画落地决策文档
任务: T-086(基于
competitor-analysis/animation-research.md的正式动画技术选型与落地清单) 日期: 2026-08-14 范围: 本任务只产出决策文档,不含任何源码改动(实施为后续任务) 适用前端:D:\拼豆\perler-lab(Vite 5 + React 18 + TS 5.9,目前 无任何动画库依赖)
0. 决策摘要(一句话选型结论)
「CSS 动画打底,leafer.js 升级画布,anime.js 按需补序列」——先纯 CSS 对齐竞品基准线(0 新增依赖、P0 全量可交付),V2 再引入 leafer.js(图纸画布渲染/交互)+ anime.js(豆子放置、stagger 序列)做差异化动效;不引入 GSAP、Framer Motion、lottie-web。
P0 动画清单 10 条(全部纯 CSS 可实现,无需新增依赖)。
1. 现状盘点(抽查 perler-lab/src 结论)
| 项 | 现状 | 结论 |
|---|---|---|
| 动画依赖 | package.json 仅 react/react-dom,无动画库 |
0 依赖现状,P0 保持 |
| CSS 动画 | 仅 3 个 keyframes(spin 0.7s、share-toast-in 0.18s、chibi-spin 0.7s)+ 大量 transition: … 0.15s ease hover 过渡 |
只有基础 hover/spinner,缺入场/序列/反馈类动画 |
prefers-reduced-motion |
全项目未出现 | 必补(见 §6) |
| 运动令牌 | 有 --space/--radius/--shadow,无 --duration/--ease |
需新增运动令牌(见 §4.3) |
| 图纸渲染 | lib/drawPattern.ts 原生 Canvas 2D fillRect 逐格绘制 |
竞品同款方案,P0 可不动;V2 换 leafer.js |
| 图片处理 | lib/usePattern.ts 主线程调 processImage(无 Web Worker) |
A1 进度动画前置条件 = 先迁移 Worker,否则主线程阻塞直接掉帧 |
| 页面切换 | App.tsx 按 pathname 条件渲染 /chibi 与首页,无过渡动画 |
V2 用 View Transitions API |
| 反馈系统 | 分享 toast 已有(share-toast-in),下载/错误为静态文字 |
P0 补下载成功反馈 |
竞品基准线(来自调研报告 §1.4):「原生 Canvas 渲染 + CSS 合成层过渡 + Web Worker 过程可视化 + 克制 200-500ms 节奏」——我们 P0 即对齐此线。
2. 技术选型对比表
| 维度 | CSS @keyframes/transition | GSAP | Framer Motion | leafer.js | anime.js(调研报告推荐项) |
|---|---|---|---|---|---|
| 类型 | 原生动画 | JS 补间引擎(DOM/JS 对象/时间线/scrub) | React 动画组件库 | 2D Canvas 场景图渲染引擎 | JS 补间引擎(轻量) |
| 体积 | 0 | ~23KB+ gz(core) | ~35KB+ gz | 按需模块,数百 KB 级(仅画布层承担) | 16.1KB gz(v4 按需更小) |
| 场景适配 | hover/loading/toast/简单入场/过渡 | 复杂交错时间线、滚动驱动、scrub | React DOM 组件过渡/手势(不作用于 canvas) | 图纸网格渲染、豆子交互/动画(核心差异化) | spring 弹性、stagger 序列、属性补间 |
| 与本项目契合 | ★★★★★ 竞品 56 处 transition 已证明足够 | ★★☆ 工具型产品无复杂时间线需求,杀鸡用牛刀 | ★★☆ 项目是纯 CSS + 原生 canvas 架构,不是 Framer 体系;只为页面过渡引入不值 | ★★★★★ 图纸本质数千~数万矩形,正是批处理强项(画布渲染唯一直接对标项) | ★★★★ 体积小、spring/stagger 可拉开差距 |
| 主要风险 | 无序列化(需 animation-delay 模拟)、无 spring 物理 | 重、侵入强、学习/维护成本 | 与现有 CSS 体系并存冗余 | 引入成本高(需重写渲染层),仅 V2 承担 | 作者维护缓慢(调研报告 §2),仅按需用其时序能力 |
| 推荐结论 | P0 主力(立即可用) | 不引入 | 不引入 | V2 引入(画布层) | V2 按需引入(序列层) |
另:lottie-web(调研报告 §3.1 第 4 层)→ 不引入。无 AE 设计师资源,60KB runtime 成本与产出不成正比;品牌庆祝类动画后期用 CSS/SVG 手工实现(低成本版见 §5-H-02)。
3. 推荐技术栈(分层架构)
┌───────────────────────────────────────────────┐
│ 第 4 层 品牌/庆祝动画 → CSS/SVG 手工(V2 可选) 无 lottie,无 AE 依赖
├───────────────────────────────────────────────┤
│ 第 3 层 JS 序列/弹簧微动画 → anime.js(V2 按需,16KB) 豆子放置 spring、stagger、颜色闪烁序列
├───────────────────────────────────────────────┤
│ 第 2 层 基础 UI 过渡 → CSS/Tailwind 风格令牌(P0) hover、loading、toast、下载反馈、入场
├───────────────────────────────────────────────┤
│ 第 1 层 图纸画布渲染/交互 → leafer.js(V2) 豆子网格 + 拖拽 + 实时更新(替代原生 fillRect)
└───────────────────────────────────────────────┘
推荐理由(结合 Vite+React+TS 现状):
- 零依赖 P0 先行:竞品"高级感"全部来自 CSS 合成层动画(56 处 transition 佐证),我们当前代码已有一致基础(
transition 0.15s),P0 只是"补齐遗漏项",不动架构、不加依赖,风险最低。 - leafer.js 是画布层的唯一直接对标:调研报告 §3.2-1 给出迁移实测(Konva→Leafer:4K 帧率 25-30→58-60、DrawCall 800+→<50、点选 80ms→10ms),且官方 benchmark 覆盖平移/缩放/拖拽/全动态场景,正对应图纸预览。当前原生
fillRect在 >1 万豆大图纸 + 动画场景下必然掉帧,leafer 的批处理 DrawCall + 脏矩形刷新是硬需求而非炫技。 - anime.js 而非 GSAP/Framer Motion:差异化动效(A2 spring 回弹、A3 闪烁序列)只需要补间 + stagger + spring 三个能力,anime 16KB 模块化刚好覆盖;GSAP 的 scrub/时间线编排在工具型产品用不上;Framer Motion 只对 React DOM 组件生效,救不了 canvas,且与现有纯 CSS 体系双轨冗余。
- 显式排除:GSAP / Framer Motion / lottie —— 成本(体积/体系侵入/维护)× 收益(本产品场景用不上)不成立。
4. 落地前置:运动设计令牌(新增,属 P0 基础设施)
在设计系统 :root 新增(对齐竞品节奏:200/500ms):
:root {
--duration-fast: 120ms; /* 按压/闪烁单拍 */
--duration-base: 200ms; /* hover、toast(竞品默认) */
--duration-med: 400ms; /* 遮罩淡入、进度过渡 */
--duration-slow: 600ms; /* 图纸渐入、卡片缩放(竞品 500ms 档) */
--ease-out: cubic-bezier(0.16, 1, 0.3, 1); /* 标准退场 */
--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
--spring-bead: cubic-bezier(0.34, 1.56, 0.64, 1); /* 豆子回弹近似 */
}
所有动画必须引用上述令牌,禁止魔数时长(对齐设计系统纪律)。
5. 逐页面动画清单
优先级: P0 = V1 必须上线(纯 CSS,0 依赖,对齐竞品基准);P1 = V1 尽量(可纯 CSS,补细节);P2 = V2(需引库或大改)。 编号沿用调研报告 A1-A5,扩展为可执行粒度。
5.1 首页 Hero(components/Hero.tsx)
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|---|---|---|---|---|
| H-01 | hero-eyebrow / hero-title / hero-sub / hero-stats | 首屏 stagger 入场:opacity 0→1 + translateY(12px)→0,依次 delay 60ms,总时长 <900ms |
页面首次加载 | P1(CSS animation-delay 即可) |
| H-02 | hero-title em(accent) |
高亮词微动效:background-position/opacity 呼吸或扫光一次 |
入场后 1s 延迟 | P2(装饰,视效果定) |
5.2 首页 AI 专区 / /chibi(ChibiPage.tsx + ChibiPage.css)
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|---|---|---|---|---|
| C-01 | chibi 上传按钮 / 卡片区 | 列表 stagger 入场(opacity+translateY,delay 60ms) | 页面加载 | P1 |
| C-02 | chibi-spinner(已有 chibi-spin) |
保留;补按钮双文案切换("处理中…"/"开始") | 生成过程 | P1 |
| C-03 | chibi 结果卡片 hover | 图片 scale(1.03→1.08) 500ms + 遮罩 opacity 淡入(竞品 §1.3-5 同款) |
桌面 hover | P1 |
5.3 编辑画布(PreviewPanel.tsx + lib/drawPattern.ts)
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|---|---|---|---|---|
| E-01 | 生成进度(A1) | ① 生成按钮 loading 态:图标 spin + 文案"处理中…";② 画布 filter: blur(6px)→0 + opacity 0→1 600ms;③ 画布下细进度条 0→100% |
点击"生成图纸"后(迁移 Web Worker 后主线程才有余力跑动画) | P0 |
| E-02 | 编辑工具栏按钮(撤销/旋转/镜像等) | 按下按压反馈:transform: scale(0.97) / translateY(1px) 120ms(现只有 translateY,补 scale) |
:active |
P0 |
| E-03 | 编辑操作应用(旋转/镜像/翻转后) | 画布内容轻过渡:opacity 0.4→1 150ms(防突变闪烁) |
每次编辑变换生效 | P0 |
| E-04 | 豆子放置动画(A2,差异化核心) | leafer.js 中每颗豆 scale 0→1 spring 回弹(stiffness 170 / damping 26)120-180ms;连续放置 stagger 30ms 瀑布式填充;颜色切换瞬时 + brightness(1.4) 120ms 发光 |
用户在画布点击/填充豆子(leafer 交互对象) | P2 |
| E-05 | 颜色匹配闪烁(A3) | 匹配豆呼吸闪烁 2 次(opacity 1→0.4→1,各 150ms)或描边光环扩散 300ms 消失 |
选中色与图纸豆色匹配 / 吸管取色 | P2 |
| E-06 | 画布拖拽(竞品 §1.3-3 对齐) | transform: translate3d(x,y,0) + will-change-transform 合成层拖拽 |
图纸拖动 | P2(leafer 内置交互) |
5.4 按钮 / 全局交互
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|---|---|---|---|---|
| B-01 | 下载按钮反馈(A4) | ① 图标切换 ✓(transition-colors 变绿 200ms);② active:scale(0.95) 100ms;③ 导出 >500ms 时 SVG 进度环(stroke-dashoffset);④ toast "图纸已保存 ✓" |
点击"下载图纸" | P0 |
| B-02 | 上传/重置按钮 | hover 背景过渡 + active 按压(现 transition 0.15s 已覆盖,统一套用令牌) |
hover / active | P0 |
| B-03 | Nav 链接 hover | 下划线滑入 / 背景过渡(现 color 过渡,补 underline) | 桌面 hover | P1 |
| B-04 | 分享按钮成功反馈 | toast 已有(share-toast-in);补按钮 ✓ 变色 200ms |
分享成功 | P0 |
5.5 页面过渡 / 弹窗
| 编号 | 组件 | 动画类型 | 触发时机 | 优先级 |
|---|---|---|---|---|
| T-01 | 弹窗(Redeem/Order/Agency Modal)打开/关闭 | fade + scale 0.96→1 200ms 入场 / 150ms 退场(对齐 toast 既有 keyframes 风格) |
弹窗开关 | P0 |
| T-02 | 页面切换(首页 ↔ /chibi)(A5) | View Transitions API 圆形扩散 400ms / 或 clip-path 擦除过渡 | 路由切换 | P2 |
| T-03 | 首屏总入场 | 依 H-01/C-01,配合 Toast 入场 | 页面加载 | P1 |
5.6 优先级汇总
| 优先级 | 条数 | 清单 |
|---|---|---|
| P0 | 10 | E-01、E-02、E-03、B-01、B-02、B-04、T-01、(+§4 运动令牌 + §6 reduced-motion 全局降级) |
| P1 | 5 | H-01、C-01、C-02、C-03、T-03、(B-03) |
| P2 | 6 | H-02、E-04、E-05、E-06、T-02 |
6. 性能与可访问性约束(硬性要求)
6.1 可访问性
prefers-reduced-motion: reduce全局降级(P0 必做):所有入场/闪烁/缩放类动画都必须有降级路径;信息传达(toast、进度)不依赖动画表达。@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; scroll-behavior: auto !important; } }- 动画不得承载关键信息(加载态必须有文字文案,不只靠 spinner)。
6.2 移动端 60fps
- 只动画
transform/opacity/filter,不碰width/height/top/left/margin(避免 layout thrash 与 reflow)。 - 动画元素加
will-change: transform仅用于已知持续动画(如画布拖拽),不滥用(会占用内存)。 - 进度条宽度动画改
transform: scaleX()(合成层)而非width。 - 图片转图纸必须先迁 Web Worker(当前
usePattern.ts主线程调用processImage),否则生成期间主线程被 JS 计算占满,任何动画都会掉帧——E-01 与 Worker 迁移绑定交付。 - 大图纸(>1 万豆)V1 画布渲染保持现有原生
fillRect;leafer.js 迁移(E-04/05/06)在 V2 一次性承担,避免 V1 双渲染引擎并存。
6.3 通用纪律
- 动画时长/缓动一律走 §4 令牌,禁魔数。
- 入场动画总时长 ≤900ms,避免拖慢首屏;首屏 FCP/LCP 不因动画代码增加而劣化(动画只在 CSS,不阻塞)。
- hover 类动画仅桌面端生效(
@media (hover: hover)),避免移动端误触触发。
7. 实施顺序建议
V1 上线(本次动画里程碑,P0+P1,0 新增依赖)
- §4 运动令牌(
--duration-*/--ease-*)写入:root - §6.1
prefers-reduced-motion全局降级 - 图片处理迁 Web Worker(E-01 前置,
usePattern.ts→new Worker) - E-01 生成进度动画(按钮 loading 双文案 + 画布 blur 渐入 + scaleX 进度条)
- E-02/E-03 编辑工具按压与变换过渡
- B-01/B-04 下载/分享成功反馈(✓ 变色 + toast)
- T-01 弹窗入场退场
- P1:H-01 Hero stagger 入场、C-01/C-03 专区入场与卡片 hover、B-03 Nav 下划线
V1 验收口径:移动端滚动/交互无掉帧(无 Worker 阻塞)、reduced-motion 下无动画、全部时长引用令牌。
V2 上线(差异化阶段,引入依赖)
- 引入 leafer.js,重写图纸画布渲染层(替换
drawPreview原生 fillRect),搭交互对象 - E-04 豆子放置 spring + stagger(anime.js
spring(stiffness:170, damping:26)或 leafer 属性补间) - E-05 颜色匹配闪烁、E-06 画布拖拽合成层
- T-02 页面切换 View Transitions
- H-02 品牌装饰动效(CSS/SVG 手工)
V2 验收口径:>1 万豆图纸拖拽/放置动画保持 60fps(对齐调研报告迁移实测数据:DrawCall <50、点选 <10ms)。
决策树(后续实施时判断)
需要动画 →
hover/loading/按压/toast/弹窗/简单入场/过渡 → CSS(永远优先,V1)
画布网格/豆子交互/拖拽 → leafer.js(V2)
spring 回弹 / stagger 序列(CSS 表达不了) → anime.js(V2 按需)
复杂滚动驱动时间线/scrub → 场景未出现,届时再评估 GSAP(现不引入)
品牌 AE 级动画 → 无设计师,不引 lottie;CSS/SVG 手工
8. 附注
- 本文档仅决策,不含实施;实施任务引用本清单编号(E-01…、H-01…、C-01…、B-01…、T-01…)作验收依据。
- 竞品基线出处:
competitor-analysis/animation-research.md§1.3(Canvas 渲染 / Worker 加载态 / translate3d 拖拽 / sonner 反馈 / 卡片 500ms hover)、§3.1(分层架构)、§4(A1-A5 效果参数)。 - 画布性能数据出处: 调研报告 §3.2-1(Konva→Leafer 迁移实测)。