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

221 lines
16 KiB
Markdown
Raw Permalink 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.
# 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`):
```css
: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 必做):
```css
@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 迁移实测)。