221 lines
16 KiB
Markdown
221 lines
16 KiB
Markdown
# 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 迁移实测)。
|