Flutter 动画实现/修复/重构/调试/测试/解释：解决…

在 Flutter 应用中需要新增、修复、重构、调试、测试或解释动画与动效时使用。

适用场景

解决思路

1. 不要让动画变成隐藏状态或未验证的示例代码。
2. 在添加或修改动画逻辑前，检查目标 widget、生命周期、路由结构和现有模式。
3. 动画改动后，验证 Dart 代码通过 analyzer，并指出任何无法运行或视觉检查的动画行为。
4. 识别用户的实际请求：新增动画、修复损坏动画、重构动画代码、调试卡顿/生命周期行为、解释模式或提供独立示例。
5. 当有代码时，先检查本地 Flutter 上下文：widget 树、状态管理、导航方式、assets、tests、主题、无障碍辅助和已有动画抽象。
6. 选择满足行为的最小动画模型。
7. 对于简单状态驱动的属性变化，使用隐式动画。
8. 对于生命周期控制、重复/可逆运动、手势、多个协调属性或自定义过渡，使用显式动画。
9. 对于跨路由共享元素，使用 Hero。
10. 当多个元素需要按序或重叠时间时，使用交错动画。
11. 当运动依赖速度、弹簧、拖拽、fling 或滚动类似行为时，使用物理动画。
12. 对于单个属性或少量状态驱动的视觉变化，使用 `AnimatedContainer`、`AnimatedOpacity`、`AnimatedAlign`、`AnimatedPadding`、`AnimatedSwitcher` 或 `TweenAnimationBuilder`。
13. 对于完整生命周期控制、重复/反向/状态，或手势驱动的值，使用带 `Tween`、`CurvedAnimation`、`AnimatedBuilder` 或 `AnimatedWidget` 的 `AnimationController`。
14. 对于路由间共享视觉元素，使用带稳定唯一 tags 且源/目标 widget 树兼容的 `Hero`。
15. 对于带偏移 timing 的列表/菜单/卡片揭示，使用一个 controller 配合 `Interval`；仅当每项生命周期真正不同时才使用逐项动画。
16. 对于弹簧/fling/拖拽或平台滚动手感，使用 `fling`、`animateWith`、`SpringSimulation`、手势速度或平台特定的 `ScrollPhysics`。
17. 对于运动感觉不对但代码能工作的情况，在增加复杂度前调整 duration、curve、interval、easing 或 reduced-motion 行为。
18. 按应用现有风格实现。除非用户要求重构，保留现有公开 API。
19. 让 controller 由拥有动画生命周期的 state 对象持有并 dispose，避免在 build 方法内创建动画状态。
20. 优先使用生产级动画模式：`AnimatedBuilder`、`AnimatedWidget`、内置过渡、child 缓存、稳定 key 和小范围重建。
21. 仅在最小示例或没有更窄重建路径时，在动画监听器中使用 `setState()`。
22. 尊重无障碍和用户设置。对非必要运动检查 `MediaQuery.disableAnimations` 或现有 reduced-motion 策略，并在运动可能分散注意力或损害可用性时提供快速/静态路径。
23. 使用可用的最强本地检查验证。至少对改动的 Dart 文件或相关 Flutter 项目运行 analyzer。
24. 当动画行为、导航或手势属于请求变更时，运行 widget/golden 或集成测试。
25. 处理简单状态驱动动画或选择 AnimatedSwitcher/TweenAnimationBuilder 时，读取 `references/implicit.md`；可选使用 `assets/templates/implicit_animation.dart` 作为独立示例。用途：widget 选项、参数和简单示例。
26. 处理 controller 生命周期、内置过渡、状态监听或可复用动画 widget 时，读取 `references/explicit.md`；可选使用 `assets/templates/explicit_animation.dart` 作为独立示例。用途：正确的 controller 所有权、disposal 和重建模式。
27. 处理共享元素路由过渡、自定义 flight path、placeholder 或 HeroMode 时，读取 `references/hero.md`；可选使用 `assets/templates/hero_transition.dart` 作为独立示例。用途：Hero tags、路由行为、shuttle builders 和常见陷阱。
28. 处理顺序列表/菜单/揭示/波纹 timing 时，读取 `references/staggered.md`；可选使用 `assets/templates/staggered_animation.dart` 作为独立示例。用途：Interval timing、duration 计算和 stagger 模式。
29. 处理弹簧、fling、拖拽、自定义 Simulation 或滚动物理时，读取 `references/physics.md`。用途：Simulation 设置、手势速度、平台物理和调优。
30. 处理曲线选择、自定义曲线、easing 不匹配或 reduced-motion 调优时，读取 `references/curves.md`。用途：曲线选择、自定义曲线和无障碍注意事项。
31. 使用模板时，它们是完整 demo 文件，不是可直接投产的模块。在应用内使用时，重命名 demo 类，移除 `main()` 和 `MaterialApp` 包装，适配 assets/routes/state，并重新运行 analyzer。
32. 不要臆造缺失的 routes、asset paths、theme tokens、手势行为或状态管理 API；检查它们，若缺失则询问用户。
33. 不要在本可用隐式 widget 以更少生命周期风险实现相同行为时添加 `AnimationController`。
34. 不要留下未 dispose 的 controllers、listeners、timers 或状态回调。
35. 不要在生产代码中使用 `timeDilation` 等全局调试设置；只作为本地调试辅助提及。
36. 不要盲目复制参考片段；根据项目的 Flutter 版本、lint 规则、null-safety 和 deprecation 状态进行适配。
37. 不要将面向用户动画的无障碍支持当作可选。如果无法实现 reduced-motion 支持，报告该限制。
38. 有编辑时，对编辑过的 Dart 文件运行 `dart format` 或项目 formatter。
39. 对项目、package 或特定改动的 Dart 文件运行 `flutter analyze`。
40. 当动画变更影响导航、手势、有状态生命周期或用户可见回归时，运行聚焦测试。
41. 对视觉变更，在可行时检查运行中的应用或截图。若无法做到，说明哪些是静态验证、哪些仍未视觉验证。
42. 更新模板时，将每个模板作为最小 Flutter 项目中的 `lib/main.dart`，用 `flutter analyze lib/main.dart` 验证。

适用边界 · 注意事项

• 当隐式动画能以更少生命周期风险实现相同行为时，不适用添加 `AnimationController`。
• 当缺少 routes、asset paths、theme tokens、手势行为或状态管理 API 时，不适用凭空发明；应先检查或询问用户。
• 当无法运行应用或检查截图时，不适用声称视觉行为已验证；应只报告静态验证并列出未视觉验证项。