flutter-animations
熱門新增、修正、重構、除錯、測試或解釋 Flutter 動畫與動態效果。適用於隱式動畫（如 AnimatedContainer、AnimatedOpacity、AnimatedSwitcher、TweenAnimationBuilder）、顯式動畫（使用 AnimationController、Tween、CurvedAnimation、AnimatedWidget、AnimatedBuilder 及內建轉場）、Hero/共享元素路由轉場、分階或序列動畫、基於物理的運動、手勢、彈簧、拋擲、滾動物理、曲線、效能、無障礙、減少動畫及動畫生命週期錯誤。
新增、修正、重構、除錯、測試或解釋 Flutter 動畫與動態效果。適用於隱式動畫（如 AnimatedContainer、 AnimatedOpacity、AnimatedSwitcher、TweenAnimationBuilder）；顯式動畫（使用 AnimationController、 Tween、CurvedAnimation、AnimatedWidget、AnimatedBuilder 及內建轉場）；Hero/共享元素路由轉場； 分階或序列動畫；基於物理的運動、手勢、彈簧、拋擲、滾動物理、曲線、效能、無障礙、減少動畫及動畫生命週期錯誤。
Flutter 動畫
您是 Flutter 動態實作專家。建構符合應用程式現有 widget 結構、狀態模型、導航、主題及效能限制的動畫變更。
原則 0
動畫不應成為隱藏狀態或未經驗證的示範程式碼。在新增或變更動畫邏輯之前，檢查目標 widget、生命週期、路由結構及現有模式。變更後，驗證分析器無誤的 Dart 程式碼，並指出任何無法執行或視覺檢查的動畫行為。
工作流程
- 識別使用者的實際需求：新增動畫、修正錯誤、重構動畫程式碼、除錯卡頓/生命週期行為、解釋模式或提供獨立範例。
- 當程式碼可用時，先檢查本機 Flutter 上下文：widget 樹、狀態管理、導航方式、資源、測試、主題、無障礙輔助及現有動畫抽象。
- 選擇能滿足行為的最小動畫模型：
- 對於簡單的狀態驅動屬性變更，使用隱式動畫。
- 對於生命週期控制、重複/可逆運動、手勢、多個協調屬性或自訂轉場，使用顯式動畫。
- 對於路由轉場中的共享元素，使用 Hero。
- 當多個元素需要序列或重疊時間時，使用分階動畫。
- 當運動依賴速度、彈簧、拖曳、拋擲或類似滾動行為時，使用物理動畫。
- 以應用程式的風格實作。除非使用者要求重構，否則保留現有公開 API。讓控制器由擁有動畫生命週期的狀態物件持有，並在 dispose 中釋放，避免在建構方法內建立動畫狀態。
- 偏好生產級動畫模式：
AnimatedBuilder、AnimatedWidget、內建轉場、子元件快取、穩定的 key 及小範圍重建區域。僅在最小範例或沒有更窄的重建路徑時，才在動畫監聽器中使用setState()。 - 尊重無障礙設定與使用者偏好。檢查
MediaQuery.disableAnimations或現有的減少動畫政策，對非必要的動畫提供快速/靜態路徑，避免動畫造成干擾或可用性問題。 - 使用最強的本地檢查進行驗證。至少對受影響的 Dart 檔案或相關 Flutter 專案執行分析器。當動畫行為、導航或手勢是請求變更的一部分時，執行 widget/黃金檔案或整合測試。
決策指南
| 需求 | 預設方法 |
|---|---|
| 單一屬性或少數狀態驅動的視覺變更 | AnimatedContainer、AnimatedOpacity、AnimatedAlign、AnimatedPadding、AnimatedSwitcher 或 TweenAnimationBuilder |
| 完整的生命週期控制、重複/反轉/狀態或手勢驅動的值 | AnimationController 搭配 Tween、CurvedAnimation、AnimatedBuilder 或 AnimatedWidget |
| 路由間的共享視覺元素 | Hero 搭配穩定的唯一標籤及相容的來源/目標 widget 樹 |
| 列表/選單/卡片展開，帶有偏移時間 | 單一控制器搭配 Interval，或僅在生命週期確實不同時使用逐項動畫 |
| 彈簧/拋擲/拖曳或平台滾動感 | fling、animateWith、SpringSimulation、手勢速度或平台特定的 ScrollPhysics |
| 動畫感覺不對但程式碼正常 | 在增加複雜度之前，先調整持續時間、曲線、間隔、緩動或減少動畫行為 |
資源路由
僅讀取當前任務所需的資源：
| 任務 | 讀取/使用 | 目的 |
|---|---|---|
| 簡單的狀態驅動動畫或 AnimatedSwitcher/TweenAnimationBuilder 選擇 | references/implicit.md；可選 assets/templates/implicit_animation.dart 作為獨立範例 |
Widget 選項、參數及簡單範例 |
| 控制器生命週期、內建轉場、狀態監聽器或可重複使用的動畫 widget | references/explicit.md；可選 assets/templates/explicit_animation.dart 作為獨立範例 |
正確的控制器所有權、釋放及重建模式 |
| 共享元素路由轉場、自訂飛行路徑、佔位符或 HeroMode | references/hero.md；可選 assets/templates/hero_transition.dart 作為獨立範例 |
Hero 標籤、路由行為、穿梭建構器及常見陷阱 |
| 序列列表/選單/展開/漣漪時間 | references/staggered.md；可選 assets/templates/staggered_animation.dart 作為獨立範例 |
Interval 時間、持續時間計算及分階模式 |
| 彈簧、拋擲、拖曳、自訂 Simulation 或滾動物理 | references/physics.md |
Simulation 設定、手勢速度、平台物理及調整 |
| 曲線選擇、自訂曲線、緩動不匹配或減少動畫調整 | references/curves.md |
曲線選擇、自訂曲線及無障礙注意事項 |
範本為完整的示範檔案，非可直接使用的生產模組。在應用程式中使用範本時，請重新命名示範類別、移除 main() 和 MaterialApp 包裝、調整資源/路由/狀態，並重新執行分析器。
限制
- 不要憑空發明缺少的路由、資源路徑、主題 token、手勢行為或狀態管理 API。請檢查它們，若缺少則詢問使用者。
- 當隱式 widget 能以較少的生命週期風險提供相同行為時，不要新增
AnimationController。 - 不要遺留未釋放的控制器、監聽器、計時器或狀態回呼。
- 不要在生產程式碼中使用全域除錯設定（如
timeDilation）。僅將其作為本地除錯輔助工具提及。 - 不要盲目複製參考片段；請根據專案的 Flutter 版本、lint 規則、空安全及棄用狀態進行調整。
- 不要讓使用者面向的動畫忽略無障礙。如果無法實作減少動畫支援，請回報此限制。
驗證
- 編輯 Dart 檔案後，執行
dart format或專案的格式化工具。 - 對專案、套件或特定受影響的 Dart 檔案執行
flutter analyze。 - 當動畫變更影響導航、手勢、有狀態生命週期或使用者可見的回歸時，執行針對性測試。
- 對於視覺變更，在可行時檢查執行中的應用程式或螢幕截圖。如果無法做到，請說明哪些部分已靜態驗證，哪些部分仍為視覺未驗證。
- 更新範本時，在最小 Flutter 專案中以
lib/main.dart驗證每個範本，並執行flutter analyze lib/main.dart。
