implementation-debugging

实现调试

使用 Disney 的原则作为诊断框架来调试动画问题。

问题表现

• 动画完全不播放
• 动画会播放，但效果不对
• 在开发环境中正常，在生产环境中失效
• 在不同浏览器中的表现不一致
• 动画触发时间不对
• 闪烁或视觉异常

按原则诊断

时间

问题：动画时序不对 调试：检查时长值。确认单位（ms 还是 s）。检查 CSS 过渡是否被覆盖。查看计算样式。

逐张绘制与姿势到姿势

问题：关键帧未生效 调试：确认所有关键帧百分比。检查属性名称是否有拼写错误。确保值可动画化。

舞台呈现

问题：动画被隐藏或裁切 调试：检查 z-index、overflow 和 opacity。确认元素位于视口内。检查是否设置了 visibility: hidden。

扎实绘制

问题：动画期间出现视觉异常 调试：检查亚像素渲染问题。添加 transform: translateZ(0) 以创建 GPU 图层。检查是否发生布局抖动。

跟随动作

问题：动画突然结束或状态不对 调试：检查 animation-fill-mode。确认结束状态与 CSS 一致。检查是否有相互冲突的动画。

常见错误

症状	可能原因	修复方法
没有动画	属性不可动画化	使用 transform，而不是直接更改属性
起始时闪烁	没有初始状态	明确设置初始值
结束状态不对	填充模式	在动画中添加 forwards
动作卡顿	布局抖动	仅对 transform/opacity 添加动画
只生效一次	动画未重置	移除并重新添加 class，或使用 JS

快速修复

1. 检查 DevTools 的 Animation 面板 - 查看时间线
2. 确认属性可动画化 - 并非所有 CSS 属性都能添加动画
3. 添加 animation-fill-mode: forwards - 保留结束状态
4. 强制创建 GPU 图层 - will-change: transform
5. 检查是否有 !important - 它可能覆盖动画

故障排查清单

• 是否已应用动画 class/触发器？（DevTools Elements）
• 属性是否可动画化？（display 不可，opacity 可以）
• 检查计算样式是否存在覆盖
• 元素是否可见？（opacity、visibility、display、z-index）
• 是否有 JavaScript 错误阻止执行？
• 检查 DevTools 中的 Animation 面板
• 在无痕模式下测试（不加载扩展）
• 对比正常与异常的环境

代码模式

// Debug: Log animation events
element.addEventListener('animationstart', (e) => {
  console.log('Animation started:', e.animationName);
});

element.addEventListener('animationend', (e) => {
  console.log('Animation ended:', e.animationName);
});

// Debug: Check computed animation
const styles = getComputedStyle(element);
console.log('Animation:', styles.animation);
console.log('Transition:', styles.transition);

// Reset animation
element.classList.remove('animate');
void element.offsetWidth; // Trigger reflow
element.classList.add('animate');

DevTools 使用提示

1. Elements > Styles：检查计算后的动画值
2. Performance 选项卡：录制并分析帧
3. Animations 面板：减慢速度、重播并检查
4. Console：记录动画事件