Communitygithub.com

flutter-motion-ui

構建精緻且具有動畫效果的 Flutter UI,將動畫與狀態設計整合,包括頁面轉場、Hero/共享元素動畫、液態玻璃浮動導航欄、錯層入場、底部表單確認、滑動確認、OTP 與多步驟驗證流程、載入轉成功按鈕、數字滾動、列表項目的動態插入/刪除、即時追蹤畫面、主題切換,以及讓畫面一致的狀態管理(密封流程狀態、單一資料來源、樂觀更新)。當使用者要求建構、設計、重新設計樣式、製作動畫或讓任何 Flutter 畫面、小工具、流程或應用程式(啟動畫面、引導、驗證、首頁、詳細頁、結帳、個人資料、外送、共乘、錢包、健身)更流暢或更高級,或提及 Flutter 轉場、Hero、玻璃擬態/液態玻璃、微互動、UI 一致性、設計標記、或 UI 狀態管理(Riverpod、Bloc、Provider、混亂的 setState)時,請使用此技能,即使他們從未提到「動畫」這個詞。

flutter-motion-ui 是什麼?

此技能「flutter-motion-ui」旨在幫助開發者建構如同單一、精心打磨產品的 Flutter 畫面。其核心概念是「狀態驅動動畫」,主張將畫面狀態明確建模(例如使用密封類別取代多個布林值),並在狀態變換時使用隱式動畫(如 `AnimatedSwitcher`、`AnimatedContainer`)自動產生動畫效果,從而將動畫與狀態管理問題合而為一,消除「不可能狀態」的錯誤。此技能提供一套名為「Motion Kit」的純 Flutter 工具包,包含錯層入場、多種頁面轉場、液態玻璃導航欄、變形按鈕、滑動確認、數字滾動、OTP 輸入框及動畫列表等常用動畫元件,並遵循 Material 3 設計與 Riverpod 狀態管理(若專案無預設慣例)。使用流程包含:先讀取專案現有設定與主題,安裝所需的 Motion Kit 檔案,接著以「狀態」與「時刻」來設計畫面,為每個時刻(如入場、主要操作、狀態變化)挑選合適的動畫效果(參考提供的「時刻與動畫對照表」),最後進行格式檢查與分析。此外,技能也強調 UI 一致性(透過主題系統定義顏色、間距、圓角、字體與動畫)、程式碼品質(小元件類別、正確清理資源、非同步安全、響應式佈局、無障礙與測試),並提供一系列參考文件(如狀態管理、導航轉場、元件實作、影片分析與一致性檢查清單)供開發者查閱。支援的平台包括 Riverpod、Bloc、Provider、GetX 等主流狀態管理庫,並可整合 go_router、auto_route 等路由方案。此技能透過強制開發者遵循這些設計模式與最佳實踐,有助於建構出動畫流暢、狀態一致且可維護的 Flutter 應用程式。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Ismail554/flutter-motion-ui-skill/tree/HEAD/flutter-motion-ui

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Flutter Motion UI

此技能產生的 Flutter 畫面,彷彿是一個連貫且手工精緻的產品:每個元素都帶著意圖出現,每次點擊都有回應,每個狀態變化都可見,且跨畫面的資料保持一致。

它源自對 22 個參考應用程式錄影(錢包、外送、共乘、健身、驗證/OTP、鬧鐘、結帳、預約、裝置配對)的逐幀分析提煉而成。references/video-analysis.md 列出了每個參考的功能以及哪個配方可以重現它。

核心概念:狀態驅動動畫

參考資料中幾乎所有「流暢」的時刻都源於相同的機制:狀態改變,然後 UI 從舊值動畫過渡到新值。 沒有人從按鈕處理程式中呼叫 controller.forward()。因此,工作總是:

  1. 明確地建模畫面的狀態(使用密封類別,而非五個布林值)。
  2. 使用 switch 來渲染該狀態。
  3. 將變化的部分包裹在隱式動畫中(AnimatedSwitcher、AnimatedContainer、TweenAnimationBuilder 或工具包中的小工具),讓兩個狀態之間的差異自動產生動畫。

完成這個步驟後,動畫和狀態管理就不再是兩個問題。中斷的動畫、雙重點擊,以及「載入旋轉圖示與成功勾選符號同時出現」的錯誤都將消失,因為不可能狀態無法被表示。

明確的 AnimationController 僅保留給三種情況:手指驅動的手勢、循環的背景效果(脈衝、掃描器)、以及編排好的多部分序列。

工作流程

1. 在撰寫任何程式碼之前先閱讀專案

  • pubspec.yaml:Flutter/Dart SDK、已使用的狀態庫(riverpod / bloc / provider / getx / 無)、路由器(go_router / auto_route / Navigator)、現有的動畫套件。
  • 現有的主題、顏色、間距、共用小工具。擴展現有的項目,不要引入第二套設計系統或第二套狀態庫。比照專案的資料夾結構和命名。在現有應用程式中,盡可能將對未要求處理檔案的更改控制在功能所需的最小範圍(例如一個 Hero 包裝、一個內邊距),除非被要求,否則不要處理無關的 lint 或風格清理,並在摘要中列出您重寫的每個現有檔案,以便 diff 不會有意外。
  • 如果是新專案或沒有慣例,則使用此技能的預設值(Riverpod Notifier、帶擴充功能的 Material 3 主題、lib/core/ + lib/features/<name>/)。

2. 安裝一次 Motion Kit

將任務所需的工具包檔案複製到專案的共用 UI 資料夾(預設為 lib/core/motion/):永遠複製 motion.dart,再加上您實際會用到的小工具,並修剪 barrel 檔案以符合需求。如果一個畫面只用到三個檔案卻複製了全部十個,會留下無人呼叫的程式碼。此工具包是純 Flutter,無依賴項,analyzer 可通過且經過小工具測試。如果專案已經有等效的項目(自己的 durations 檔案、自己的導航欄),請改為使用他們的方案,而不是重複建立。

檔案用途
motion.dart提供 Motion.fast/base/slow/page/hero、曲線、彈簧、減少動畫輔助程式 — 這是 durations 唯一存在的地方;Haptics.tap/selection/success/error — 這是觸覺回饋唯一觸發的地方
entrance.dart提供 Entrance(錯層淡入/滑入/模糊入)、StateSwitcher(狀態的動畫化 switch)
page_routes.dart提供 AppRoute、AppPageTransitions.theme()、showAppSheet、heroFadeShuttle
glass_nav_bar.dart提供 GlassNavBar 浮動液態玻璃藥丸形導航欄,附帶滑動鏡頭指示器
morph_button.dart提供 Pressable、MorphButton(閒置→旋轉→成功)、AsyncMorphButton
slide_to_confirm.dart提供 SlideToConfirm 拖拽確認,附帶觸覺回饋和狀態
rolling_number.dart提供 CountUpText、RollingText(里程表數字效果)
otp_boxes.dart提供 OtpBoxes、Shake
animated_items.dart提供 AnimatedItems<T> — 從簡單的不可變列表中動畫化插入/刪除的列表

assets/examples/send_money_flow.dart 是一個完整的實作流程(列表 → 鍵盤 → 滑動 → 發送中 → 成功 → 返回,新行動畫插入)。在建立任何多狀態流程時請閱讀它;這是要模仿的模式。旁邊的 send_money_flow_test.dart 顯示了如何測試此類流程(完整路徑、小螢幕溢出、減少動畫)。

assets/project_setup/analysis_options.yaml 是此工具包通過的嚴格 lint 規則集。提議將其合併到專案的 analyzer 配置中;不要覆蓋團隊已選擇的規則。

3. 將畫面設計為狀態和時刻,然後建構

在編寫畫面程式碼之前,請記錄下來(在腦中或簡短的註解中):

  • 狀態:此畫面可以處於哪些不同的狀態?(例如 Editing → Submitting → Done | Failed)
  • 共享資料:此畫面顯示了哪些另一個畫面也顯示的資料?該資料應有一個擁有者。
  • 時刻:入場、主要操作、每個狀態變化以及退出。每個時刻從下表獲得一個精心挑選的動畫。其他部分保持靜止。

然後按此順序建構:標記/主題 → 靜態佈局 → 狀態層 → 狀態變化動畫 → 入場錯層 → 導航轉場 → 觸覺回饋 → 減少動畫與小螢幕檢查。

4. 驗證

對您觸及的檔案執行 dart format,並執行 flutter analyze 直到沒有錯誤。如果有裝置/模擬器可用,請執行應用程式並實際查看流程;否則,撰寫一個走訪狀態的簡短小工具測試(參見範例測試的形狀)並執行它。然後瀏覽 references/consistency-checklist.md。

哪個時刻使用哪種動畫

時刻使用的動畫時機
畫面首次出現對 3-7 個頂層區塊(從上到下)使用 Entrance(index: n)slow,間隔 55 毫秒
推入一個不相關的畫面(啟動→首頁,驗證→應用程式)AppTransition.fadeThroughpage
在同一個流程中的下一步(電話→OTP→密碼)AppTransition.sharedAxisX + 動畫化的步驟指示器page
列表項目 → 其詳細頁對圖片/卡片使用 Hero + 詳細頁的其餘部分在之後淡入hero
確認 / 選擇 / 評分 / 挑選使用 showAppSheet,內容在內部錯層入場page
請求進行中使用帶 status 的 MorphButton 或 SlideToConfirm每個階段 base
數值變化(價格、ETA、餘額)使用 RollingText(離散值)/ CountUpText(量級)base / long
項目被新增/刪除使用 AnimatedItemsbase
畫面狀態變化(載入中→內容→錯誤)使用 StateSwitcherbase
選擇(晶片、卡片、頁籤、星星)使用 AnimatedContainer 顏色/邊框 + 小型的 AnimatedScalefast
任何點擊使用 Pressable 縮放效果 + 輕觸覺回饋instant
驗證失敗使用 Shake + 紅色邊框 + 訊息;保留輸入內容slow
成功勾選符號以 Motion.overshoot 彈出,維持 successHold,然後繼續—

保持品味的經驗法則:

  • 入場動畫只播放一次。 在懶加載列表中,如果一個滾出視圖的行重新滾入視圖,它會被重建並再次產生動畫;請傳入 Entrance(enabled: …) 以便只有第一次出現時產生動畫。
  • 每次導航只有一個亮點。 一個 Hero 或 一個模糊轉場 或 一個大的錯層 — 不要三者並存。
  • 進入慢,退出快。 退出時約使用進入持續時間的 60-80%,搭配 Motion.exit。
  • 相關的事物一起移動;不相關的事物則錯開。
  • 對變換(transform)和不透明度進行動畫,避免在長列表中對佈局(layout)進行動畫。 模糊效果成本高昂 — 僅用於少數 hero 元素,絕不用於列表的每一行。
  • 切勿為了裝飾而阻擋輸入。 入場動畫不得延遲可點擊性;只有真正的任務(網路請求)才能停用控制項。
  • 尊重減少動畫的設定:此工具包已透過 Motion.of(context, …) 壓縮持續時間;在您編寫的任何 controller 中也應如此。

狀態管理要點

完整的指南(包含 Riverpod / Bloc / ChangeNotifier 的等效寫法):references/state.md。不可妥協的事項:

  • 流程狀態是密封類別;UI 是一個詳盡的 switch。將每個狀態所需的資料包含在狀態內部。
  • 每份共享資料只有一個擁有者。 列表畫面與詳細/流程畫面讀取同一個 provider;由流程負責寫入。不要透過 Navigator.pop 傳回結果並修補本地副本 — 這會導致畫面不同步。
  • 失敗時保留使用者的輸入。 失敗的提交會返回編輯狀態,保留欄位內容並顯示錯誤訊息。
  • 副作用在監聽器中處理,而非 build 中。 導航、Snackbar、觸覺回饋響應狀態轉換(ref.listen、BlocListener)。
  • 動畫狀態保留在小工具中;業務狀態永遠不會。 Controller 知道 Submitting 狀態;它不知道 AnimationController 的存在。
  • 即時資料是對應到狀態的串流(ETA、司機位置、訂單狀態),小工具在更新之間進行插值,因此即使更新每秒只到達一次,動畫也是連續的。
  • 保護非同步間隙(ref.mounted / isClosed / mounted)在 await 之後再觸碰狀態。

UI 一致性

一致性是將設計過的應用程式與一堆漂亮畫面區分開來的關鍵。將標記放入主題中,切勿在小工具中硬編碼:

  • 顏色:使用 ColorScheme + 用於品牌額外項目的 ThemeExtension(成功色、玻璃色調、漸層)。小工具讀取 Theme.of(context);這也是實現動畫化的亮/暗模式切換免費的原因。
  • 間距:使用 4 點比例(4, 8, 12, 16, 20, 24, 32)。整個應用程式使用一個統一的水平頁面內邊距。
  • 圓角:使用三個值(例如 12 小 / 20 卡片 / 28 底部表單)加上藥丸形狀。相同的卡片在任何地方都使用相同的圓角。
  • 字體:僅使用 TextTheme 角色;對於任何變化的數字使用表格數字。
  • 動畫:僅使用 Motion.*。
  • 元件:一個主要按鈕、一種底部表單樣式、一種輸入樣式、一種導航欄。如果出現第二種變體,請將其提升為帶參數的共用小工具。

詳細資訊和稽核清單:references/consistency-checklist.md。

程式碼品質標準

動畫 UI 會放大草率程式碼的成本:每秒執行 120 次的 build 方法、比其畫面存活更久的 controller、只適合一種手機的佈局。讓每個檔案都達到此工具包所滿足的相同標準。references/flutter-best-practices.md 提供了完整指南;最常出錯的要點如下:

  • 使用小工具類別,而非 _buildX() 輔助方法,並使用 const 建構子 — 這樣重建只會影響變化的部分。
  • 所有創建的資源都被釋放:動畫/文字/滾動/頁面 controller、CurvedAnimation、焦點節點、計時器、訂閱。
  • 保護每個非同步間隙(context.mounted / ref.mounted / isClosed),絕不無聲地丟棄 Future(使用 await 或 unawaited)。
  • 穩定的 key:在動態列表和 AnimatedSwitcher 的子元素上使用 ValueKey(item.id);絕不使用索引作為 key,絕不使用在 build 中創建的 key。
  • 能滾動而非溢出的佈局:任何包含鍵盤、表單或選擇器的畫面都必須能在 320×480 的視口、已開啟的鍵盤和 1.3 倍文字大小的情況下正常運作。
  • 每個畫面都能在窄畫面 + 大字體下正常運作,而不僅僅是您被要求的流程:在 320 寬度、1.6 倍文字大小的情況下,一個包含標題和金額的 Row、一個包含數字和標籤的卡片或一個列表圖塊會橫向溢出,除非文字被包裹在 Expanded/Flexible 中,並設定 maxLines 和 overflow。包含一個測試,在 320×568 的大小下,使用 tester.platformDispatcher.textScaleFactorTestValue = 1.6 來泵送應用程式的第一個畫面(以及每個頁籤),並預期不會發生異常。
  • 測試不愉快的手勢:提前釋放的拖拽、載入時的第二次點擊、請求中途按返回鍵。這些路徑包含了一次從頭到尾的測試從未觸及的崩潰。
  • 功能程式碼中沒有字面值:顏色、圓角、間距、持續時間、觸覺回饋都來自主題/標記/Motion/Haptics;面向使用者的字串遵循專案的本地化設定。
  • 懶加載列表和範圍重建:任何可滾動的東西都使用 builder,對於變化的值使用 select,將靜態子樹作為 child 傳入。
  • 天生可訪問:自訂控制項上要有語義(Semantics),為純手勢操作提供替代方案,尊重減少動畫設定。一個帶有 Semantics(label: …, excludeSemantics: true) 的包裝器會移除子元素的點擊操作 — 同時將 onTap 傳遞給 Semantics。
  • 在重要之處進行測試:將 controller 狀態轉換作為單元測試;每個流程至少一個小工具測試,斷言結果,而非動畫內部機制。

參考檔案 — 閱讀與任務相符的檔案

  • references/motion-system.md — 標記說明、編排方式以及此工具包未包含效果(啟動序列、模糊對焦、進度環、掃描線、顏色/主題插值、滾動連結的標頭)的配方。
  • references/navigation-transitions.md — 頁面轉場、正確的 Hero 用法、容器變換、底部表單、多步驟流程、go_router 整合。
  • references/glass-nav-bar.md — 液態玻璃導航欄的構建方式、調校、效能、Shell/頁籤狀態、已知陷阱。
  • references/state.md — 流程狀態、共享狀態、非同步/樂觀模式、即時串流,包含 Riverpod、Bloc 和 ChangeNotifier 的版本。
  • references/components.md — 配方:步驟進度、可選擇的卡片/晶片、帶反應式標籤的星級評分、能重新著色頁面的卡片輪播、滾輪選擇器、骨架螢幕、即時追蹤表單 + 路線標記、持久化的迷你狀態欄。
  • references/video-analysis.md — 22 個分析過的錄影:螢幕上發生的事情以及如何重建它。
  • references/flutter-best-practices.md — 專案結構、小工具組合、生命週期、非同步安全性、Dart 3 習慣、穩健的佈局、效能、主題化、l10n/無障礙、錯誤狀態、測試、工具。在創建新專案結構或審查/重構現有程式碼之前閱讀。
  • references/consistency-checklist.md — 標記、交付前 QA、效能和無障礙檢查。

輸出期望

  • 在專案的結構中交付完整的、可運行的檔案 — 不是包含「…其餘程式碼」的片段。
  • 使用專案現有的套件。僅在一個新套件明顯有價值時才建議使用,並說明原因。
  • Flutter API 變化很快。如果已安裝的 SDK 比您確定的版本更新,請檢查簽名(flutter analyze 是最快的判斷方式),而不是猜測。
  • 完成時,簡要告知使用者哪些時刻被製作了動畫以及使用了什麼狀態形狀。

相關技能