动画的 bug 通常表现为"看起来不对"——元素闪一下消失、出现顺序错乱、卡在中间状态。本节给一套系统的调试方法。

内置调试面板

「视图 → 动画时间轴」打开：

┌────────────────────────────────────────┐
│ ▶ 播放  ▮▮ 暂停  ⟲ 重置  ⏭ 单步       │
├────────────────────────────────────────┤
│ 标题      ━━━━━──── (400ms)              │
│ 副标题      ━━━━━──── (300ms)            │
│ 图片         ━━━━━━━━━━ (500ms)          │
│ 总结              ━━━━━ (200ms)          │
│                                        │
│ 当前指针：[━━━━━━] 1.2s / 2.0s          │
└────────────────────────────────────────┘

三种调试模式

1. 单步模式

按 → 一次只触发下一个 order，不一次播完。适合：

• 检查每个 order 触发哪些元素
• 确认 trigger 配置正确
• 验证 chain 链顺序

2. 慢速模式

时间速率调到 0.25x：

视图 → 动画时间轴 → 播放速率 → 0.25x

400ms 的动画变 1600ms，能清楚看到中间帧。适合：

• 检查缓动曲线效果
• 验证多元素 delay 错峰
• 排查"看起来不对"但说不出哪里

3. 鼠标拖动

直接拖时间轴的指针，画布显示对应时刻的状态。适合：

• 任意时刻的"截图式"检查
• 跨长动画跳转

常见问题排查

Q1：元素根本不出现

• 检查 trigger 类型，是不是设了 interaction 但 target 错了
• 检查 order 是否合理（不是 99 或负数）
• 检查 opacity: 0 是否被入场动画覆盖
• 检查锁定 / 隐藏开关

Q2：元素瞬间出现，没动画

• duration 是不是设成 0 了？
• 浏览器是不是开了"减少动效"系统设置？
• CSS prefers-reduced-motion 媒体查询触发了？

Q3：动画在错误的位置开始 / 结束

• 检查 transform 起点（可能是 left/top，不是 transform）
• 检查相对父级的定位（position 是否设错）

Q4：链式动画卡住，下一段不触发

• chainAfter 指向的元素 ID 写错了？
• 前一段动画时长是不是被什么阻塞？
• 检查浏览器 Console 报错

Q5：触屏不灵 / 鼠标灵

• iframe 嵌入元素可能拦截了 pointer 事件
• 检查 pointer-events: none 是不是被错误设置
• iPad / Safari 上某些 CSS 行为不一致

录制并复盘

「视图 → 动画时间轴 → 导出录屏」生成 mp4，可以：

• 慢速回放检查
• 团队 review
• 上传反馈给玄武屏团队

自动化测试（高级）

玄武屏命令行（xwp-cli）支持自动化：

xwp-cli test ./my-deck.xwp --mode auto --record
# 自动播放整份演示，录制视频，断言关键帧

适合大型课件库的回归测试。

调试日志

打开 Console（F12），玄武屏会打印关键事件：

[xwp] page-enter slide=3
[xwp] order=1 fired, elements=[title, subtitle]
[xwp] chain: title.complete → subtitle.start
[xwp] interaction: btn-show-answer.click → answer.fade-in

可以快速定位"哪一步出错"。

用户反馈回路

观众端看到 bug 时，可右键 →「报告问题」，自动收集：

• 当前页面状态
• 触发的动画事件
• 浏览器版本 / 设备
• 错误堆栈

提交后到「我的演示 → 反馈」查看。详见「88. 反馈渠道与支持」。

下一章进入"演示模式"section。