# 动画接入工作流
> 文档版本：v1.0
> 最后更新：2026-04-02 08:28:05


## 1. 目的

这份文档用于说明：

- 设计公司提供的动画稿，应该如何转成程序可执行的内容
- 我方应该如何组织这类工作
- 动画接入前、中、后的协作方式

一句话：

**不要把动画稿直接塞进程序，要先把它转成“工程规格”。**

---

## 2. 核心原则

### 2.1 交付的是规格，不只是效果

设计公司不能只给：

- 视频
- GIF
- 一张效果图

至少还需要给：

- 动画名称
- 触发时机
- 作用对象
- 起始状态
- 结束状态
- 时长
- 延迟
- 缓动
- 是否循环
- 是否可中断
- 资源形式
- 降级方案

### 2.2 先分类，再决定技术实现

不是所有动画都适合用同一种实现方式。

必须先判断它属于：

- 地图空间动画
- HUD 动画
- UI / Feedback 动画
- 过场 / Cutscene 动画

### 2.3 先看信息价值，再看视觉效果

优先实现：

- 帮助用户理解状态的动画
- 引导视线的动画
- 强化反馈的动画

延后实现：

- 纯装饰性动画
- 对玩法理解没有帮助的长演出

### 2.4 低端机优先

任何动画都要先问：

- `lite` 模式下怎么降级？
- 不做时是否影响信息表达？

---

## 3. 推荐流程

建议每个动画都按下面这条流程走：

### 第一步：设计交付

设计提供：

- 动画视觉稿
- 动画规格参数
- 资源文件
- 适配说明

### 第二步：整理进动画字典

先把动画纳入事件字典，而不是直接实现。

例如：

- 什么事件触发它
- 作用在哪一层
- `standard / lite` 如何处理

### 第三步：技术归类

判断该动画由哪一层承接：

- `MapPresentation / Renderer`
- 页面 `WXML / WXSS`
- `UiEffectDirector`
- 单独的 `Cutscene` 层

### 第四步：选择实现方式

例如：

- 纯程序动画
- 序列帧 / sprite
- Lottie
- 视频

### 第五步：做性能分级

明确：

- `standard` 怎么做
- `lite` 怎么做
- 是否允许完全关闭

### 第六步：联调与验收

至少验证：

- 触发正确
- 状态切换正确
- 多次连续触发是否正常
- 可中断行为是否正确
- 低端机是否流畅

---

## 4. 动画实现方式建议

### 4.1 纯程序动画

适合：

- 地图 pulse
- 数字过渡
- HUD 状态变化
- 按钮反馈

优点：

- 最轻
- 最稳定
- 最适合小程序

### 4.2 Lottie / 骨骼类动画

适合：

- 局部高质量 UI 动效
- 成功反馈
- 勋章 / 特殊提示

风险：

- 小程序里复杂 Lottie 可能卡

### 4.3 序列帧 / Sprite

适合：

- 爆点
- 金币收集
- 局部地图特效

风险：

- 占内存
- 占包体

### 4.4 视频 / 过场动画

适合：

- 章节开场
- 比赛结果页
- 特殊演出

不适合：

- 地图过程中的高频反馈

---

## 5. 当前项目里的推荐落点

### 地图空间动画

放在：

- `MapPresentation`
- `MapScene`
- `WebGL Renderer`

### HUD 动画

放在：

- 页面层 `WXML / WXSS`

### Feedback 动画

放在：

- `feedbackConfig`
- `UiEffectDirector`
- `FeedbackDirector`

### 过场动画

建议未来独立一层：

- `Transition`
- `Cutscene`

---

## 6. 当前建议的协作方式

以后和设计公司协作时，建议这样分工：

### 设计公司负责

- 视觉稿
- 动画节奏
- 参数规格
- 资源文件
- 降级建议

### 我方负责

- 事件归类
- 技术选型
- 动画字典维护
- 分层接入
- 性能分级

---

## 7. 推荐的工作顺序

建议以后优先接这类动画：

1. 打点成功
2. 目标切换
3. 跳点
4. 高压 / 危险反馈
5. 章节开场 / 过场动画

---

## 8. 结论

动画接入的正确方式不是：

**拿到设计稿 -> 直接写代码**

而是：

**拿到设计稿 -> 转成动画规格 -> 纳入动画字典 -> 选技术实现 -> 做性能分级 -> 再接程序**

---

## 9. 规格模板

后续和设计公司、外包或内部设计协作时，建议每个动画至少补齐下面这些字段：

- 动画 ID
- 动画名称
- 所属页面/模块
- 所属层级：地图空间 / HUD / UI反馈 / 过场
- 触发事件
- 触发条件
- 是否高频
- 作用对象
- 起始状态 / 结束状态
- 动画形式：程序动画 / Lottie / 序列帧 / 视频
- 资源文件
- 时长 / 延迟 / 缓动
- 是否循环
- 是否可中断
- 重复触发策略：覆盖 / 忽略 / 重启 / 排队
- `standard` 表现
- `lite` 表现
- 是否允许关闭
- 验收标准

推荐最小记录格式：

```md
动画 ID：
动画名称：
所属页面/模块：
所属层级：
触发事件：
触发条件：
动画形式：
时长：
缓动：
是否循环：
是否可中断：
重复触发策略：
standard 表现：
lite 表现：
验收标准：
```

---

## 10. 接入评审清单

在接设计稿或准备开发前，至少先过一遍这份清单：

### 设计侧

- 动画目标是否明确
- 触发条件是否明确
- 是否有完整规格和资源
- 是否提供 `lite` 降级方案

### 技术侧

- 动画属于哪一层
- 最合适的实现方式是什么
- 是否真的需要资源文件，还是纯程序动画就够

### 性能侧

- 是否高频触发
- `lite` 下是保留、简化还是关闭
- 是否会带来高频 `setData`、持续循环动画或额外桥接成本

### 交互侧

- 是否可中断
- 多次连续触发会怎样
- 是否会和现有地图 pulse、HUD 动效、stage 效果冲突

### 验收侧

- 触发时机是否正确
- 结束时机是否正确
- 连续触发是否稳定
- `standard / lite` 是否都可用
- 低端机是否可接受

---

## 11. 归档说明

原来的：

- `animation-integration-spec.md`
- `animation-review-checklist.md`

已经归档到 [archive/animation](/D:/dev/cmr-mini/doc/archive/animation)，当前以本文件为统一入口。