Flutter Motion UI
此技能產生的 Flutter 畫面,彷彿是一個連貫且手工精緻的產品:每個元素都帶著意圖出現,每次點擊都有回應,每個狀態變化都可見,且跨畫面的資料保持一致。
它源自對 22 個參考應用程式錄影(錢包、外送、共乘、健身、驗證/OTP、鬧鐘、結帳、預約、裝置配對)的逐幀分析提煉而成。references/video-analysis.md 列出了每個參考的功能以及哪個配方可以重現它。
核心概念:狀態驅動動畫
參考資料中幾乎所有「流暢」的時刻都源於相同的機制:狀態改變,然後 UI 從舊值動畫過渡到新值。 沒有人從按鈕處理程式中呼叫 controller.forward()。因此,工作總是:
- 明確地建模畫面的狀態(使用密封類別,而非五個布林值)。
- 使用
switch來渲染該狀態。 - 將變化的部分包裹在隱式動畫中(
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.fadeThrough | page |
| 在同一個流程中的下一步(電話→OTP→密碼) | AppTransition.sharedAxisX + 動畫化的步驟指示器 | page |
| 列表項目 → 其詳細頁 | 對圖片/卡片使用 Hero + 詳細頁的其餘部分在之後淡入 | hero |
| 確認 / 選擇 / 評分 / 挑選 | 使用 showAppSheet,內容在內部錯層入場 | page |
| 請求進行中 | 使用帶 status 的 MorphButton 或 SlideToConfirm | 每個階段 base |
| 數值變化(價格、ETA、餘額) | 使用 RollingText(離散值)/ CountUpText(量級) | base / long |
| 項目被新增/刪除 | 使用 AnimatedItems | base |
| 畫面狀態變化(載入中→內容→錯誤) | 使用 StateSwitcher | base |
| 選擇(晶片、卡片、頁籤、星星) | 使用 AnimatedContainer 顏色/邊框 + 小型的 AnimatedScale | fast |
| 任何點擊 | 使用 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是最快的判斷方式),而不是猜測。 - 完成時,簡要告知使用者哪些時刻被製作了動畫以及使用了什麼狀態形狀。