Files
perler-lab/docs/ANIMATION-PLAN.md

16 KiB
Raw Permalink Blame History

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 现状):

  1. 零依赖 P0 先行:竞品"高级感"全部来自 CSS 合成层动画(56 处 transition 佐证),我们当前代码已有一致基础(transition 0.15s),P0 只是"补齐遗漏项",不动架构、不加依赖,风险最低。
  2. leafer.js 是画布层的唯一直接对标:调研报告 §3.2-1 给出迁移实测(Konva→Leafer:4K 帧率 25-30→58-60、DrawCall 800+→<50、点选 80ms→10ms),且官方 benchmark 覆盖平移/缩放/拖拽/全动态场景,正对应图纸预览。当前原生 fillRect 在 >1 万豆大图纸 + 动画场景下必然掉帧,leafer 的批处理 DrawCall + 脏矩形刷新是硬需求而非炫技。
  3. anime.js 而非 GSAP/Framer Motion:差异化动效(A2 spring 回弹、A3 闪烁序列)只需要补间 + stagger + spring 三个能力,anime 16KB 模块化刚好覆盖;GSAP 的 scrub/时间线编排在工具型产品用不上;Framer Motion 只对 React DOM 组件生效,救不了 canvas,且与现有纯 CSS 体系双轨冗余。
  4. 显式排除: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 必做):
    @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;
      }
    }
    
    所有入场/闪烁/缩放类动画都必须有降级路径;信息传达(toast、进度)不依赖动画表达。
  • 动画不得承载关键信息(加载态必须有文字文案,不只靠 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 新增依赖)

  1. §4 运动令牌(--duration-*/--ease-*)写入 :root
  2. §6.1 prefers-reduced-motion 全局降级
  3. 图片处理迁 Web Worker(E-01 前置,usePattern.ts → new Worker)
  4. E-01 生成进度动画(按钮 loading 双文案 + 画布 blur 渐入 + scaleX 进度条)
  5. E-02/E-03 编辑工具按压与变换过渡
  6. B-01/B-04 下载/分享成功反馈(✓ 变色 + toast)
  7. T-01 弹窗入场退场
  8. P1:H-01 Hero stagger 入场、C-01/C-03 专区入场与卡片 hover、B-03 Nav 下划线

V1 验收口径:移动端滚动/交互无掉帧(无 Worker 阻塞)、reduced-motion 下无动画、全部时长引用令牌。

V2 上线(差异化阶段,引入依赖)

  1. 引入 leafer.js,重写图纸画布渲染层(替换 drawPreview 原生 fillRect),搭交互对象
  2. E-04 豆子放置 spring + stagger(anime.js spring(stiffness:170, damping:26) 或 leafer 属性补间)
  3. E-05 颜色匹配闪烁、E-06 画布拖拽合成层
  4. T-02 页面切换 View Transitions
  5. 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 迁移实测)。