fixing-motion-performance

修复动画性能

修复动画性能问题。

使用方法

• /fixing-motion-performance 在本次对话中，将这些约束应用于所有 UI 动画工作。

• /fixing-motion-performance <file> 根据以下所有规则检查文件并报告：

  • 违规项（引用准确的行或代码片段）
  • 原因（用一句简短的话说明其重要性）
  • 具体修复方法（提供代码级建议）

除非明确提出要求，否则不要迁移动画库。请在现有技术栈内应用这些规则。

适用时机

在以下情况下参考这些指南：

• 添加或修改 UI 动画（CSS、WAAPI、Motion、rAF、GSAP）
• 重构卡顿的交互或过渡效果
• 实现滚动联动动画或滚动时显示效果
• 为布局、滤镜、遮罩、渐变或 CSS 变量添加动画
• 检查使用 will-change、变换或测量功能的组件

渲染步骤术语表

• 合成：transform、opacity
• 绘制：color、边框、渐变、遮罩、图像、滤镜
• 布局：尺寸、位置、流式布局、网格、弹性布局

按优先级排列的规则类别

优先级	类别	影响
1	禁用模式	严重
2	选择机制	严重
3	测量	高
4	滚动	高
5	绘制	中高
6	图层	中
7	模糊和滤镜	中
8	视图过渡	低
9	工具边界	严重

快速参考

1. 禁用模式（严重）

• 不要在同一帧内交错读取和写入布局
• 不要在大面积或重要表面上持续播放布局动画
• 不要通过 scrollTop、scrollY 或滚动事件驱动动画
• 不要创建没有停止条件的 requestAnimationFrame 循环
• 不要混用多个会分别测量或修改布局的动画系统

2. 选择机制（严重）

• 默认使用 transform 和 opacity 实现动效
• 只有在交互需要时才使用 JS 驱动的动画
• 仅当绘制或布局动画作用于小型、独立的表面时，才可接受
• 一次性效果比持续动画更容易接受
• 优先降低动画技术的复杂度，而不是完全移除动效

3. 测量（高）

• 测量一次，然后通过 transform 或 opacity 播放动画
• 在写入前批量读取所有 DOM 数据
• 不要在动画过程中反复读取布局
• 对类似布局的效果，优先使用 FLIP 风格的过渡
• 优先选择能批量处理测量和写入的方案

4. 滚动（高）

• 在可用时，优先使用 Scroll 或 View Timelines 实现滚动联动动画
• 使用 IntersectionObserver 控制可见性和暂停
• 不要轮询滚动位置来驱动动画
• 元素离开屏幕后，暂停或停止动画
• 滚动联动动画不得在大面积表面上持续触发布局或绘制

5. 绘制（中高）

• 只有在小型、独立的元素上才允许播放会触发绘制的动画
• 不要在大型容器上为绘制开销较大的属性添加动画
• 不要使用 CSS 变量为 transform、opacity 或 position 添加动画
• 不要为继承的 CSS 变量添加动画
• 将动画用到的 CSS 变量限制在局部作用域内，并避免继承

6. 图层（中）

• 合成器动效需要提升图层，切勿想当然
• 临时且谨慎地使用 will-change
• 避免提升过多或过大的图层
• 性能很重要时，使用工具验证图层行为

7. 模糊和滤镜（中）

• 将模糊动画控制在较小范围（<=8px）
• 仅将模糊用于短暂的一次性效果
• 绝不持续播放模糊动画
• 绝不在大面积表面上播放模糊动画
• 优先使用 opacity 和 translate，再考虑模糊

8. 视图过渡（低）

• 仅将视图过渡用于导航级别的变化
• 避免在交互密集的 UI 中使用视图过渡
• 需要中断或取消时，避免使用视图过渡
• 将尺寸变化视为可能触发布局的操作

9. 工具边界（关键）

• 除非有明确要求，否则不要迁移或重写动画库
• 在现有动画系统中应用这些规则
• 绝不要只部分迁移 API，或在同一组件中混用不同风格

常见修复

/* layout thrashing: animate transform instead of width */
/* before */ .panel { transition: width 0.3s; }
/* after */  .panel { transition: transform 0.3s; }

/* scroll-linked: use scroll-timeline instead of JS */
/* before */ window.addEventListener('scroll', () => el.style.opacity = scrollY / 500)
/* after */  .reveal { animation: fade-in linear; animation-timeline: view(); }

// measurement: batch reads before writes (FLIP)
// before — layout thrash
el.style.left = el.getBoundingClientRect().left + 10 + 'px';
// after — measure once, animate via transform
const first = el.getBoundingClientRect();
el.classList.add('moved');
const last = el.getBoundingClientRect();
el.style.transform = `translateX(${first.left - last.left}px)`;
requestAnimationFrame(() => { el.style.transition = 'transform 0.3s'; el.style.transform = ''; });

审查指南

• 首先落实关键规则（禁止的模式、工具边界）
• 选择符合意图且成本最低的渲染方案
• 对于任何非默认选择，都要说明支持该选择的约束（表面尺寸、持续时间或交互要求）
• 审查时，优先提供可执行的意见和具体替代方案，而不是理论说明