dot-skills — Airbnb iOS SwiftUI 動畫最佳實踐
針對 SwiftUI iOS 26 / Swift 6.2 應用程式,提供一套嚴格且具主觀性的動畫製作指南。包含 8 大類別的 50 條規則,按影響力排序。源自 Airbnb 工程動畫模式、Apple WWDC 研討會以及 Apple 人機介面指南。強制要求每個動畫檢視都使用 @Equatable、所有彈簧/時間值都使用 Motion Token,以及佈局都使用設計系統 Token。
強制架構一致
此技能設計為與 swift-ui-architect 和 ios-design-system 一道協同工作。所有程式碼範例都遵循相同的不容妥協的約束:
- 每個檢視上都使用
@Equatable巨集(Airbnb 測量到滾動卡頓減少了 15%) - 針對涉及業務邏輯觸發器的複雜動畫狀態使用
@Observable - 針對檢視所擁有的動畫狀態(切換布林值、拖曳偏移量)使用
@State - 設計系統 Token:
Spacing.xs/sm/md/lg、Radius.sm/md/lg— 禁止任何硬編碼的佈局數字 - 運動 Token:
Motion.standard/responsive/playful— 禁止任何散落的彈簧字面值 - 語意顏色:
.backgroundSurface、.accentPrimary— 檢視中不得有原始的 Color 字面值 - 功能動畫僅限於呈現層面;資料/網路相關問題保留在 Data 套件中
範圍與同級技能的關係
此技能是動畫層 — 它教授如何建構流暢、高效能的動畫。當與同級技能一起載入時:
| 同級技能 | 其焦點 | 本技能焦點 |
|---|---|---|
swift-ui-architect | 架構(模組化 MVVM-C、路由殼層、協定邊界) | 動畫架構(運動 Token、彈簧選擇、編排) |
ios-design-system | 設計系統基礎設施(Token、樣式、治理) | 運動 Token 和動畫化元件模式 |
ios-hig | HIG 合規模式 | 特定於動畫的 HIG(減少動畫、空間連續性) |
不包含: 設計師創作的向量動畫(請參閱 Lottie 以用於 After Effects 導出)。複雜的 UIKit 轉場控制器(請參閱 Airbnb 的宣告式轉場框架)。此技能僅涵蓋程式化 SwiftUI 動畫。
診所架構契約 (iOS 26 / Swift 6.2)
此技能中的所有指導都假設採用診所模組化 MVVM-C 架構:
- 功能模組僅匯入
Domain+DesignSystem(絕不匯入Data,也絕不匯入同級功能模組) - App Target 是收斂點,並擁有
DependencyContainer、具體的協調器和路由殼層的接線 Domain保持純 Swift,並定義模型以及倉儲庫、*Coordinating、ErrorRouting和AppError合約Data擁有 SwiftData/網路/同步/重試/背景 I/O,並實作 Domain 協定- 讀取/寫入流程預設為「先提供過時資料再驗證」的讀取和「樂觀排隊」的寫入
- ViewModel 直接呼叫倉儲庫協定(沒有預設的 use-case/interactor 層)
何時應用
在以下情況下參考這些指南:
- 將動畫添加到 SwiftUI 檢視或轉場時
- 構建手勢驅動的互動(拖曳、滑動、平移)時
- 使用空間轉場連接檢視時(展開/折疊、導航變形)
- 設計微互動時(按鈕按下、切換、載入狀態)
- 讓內容變化感覺更自然時(數字滾動、符號替換)
- 編排多元素動畫序列時(KeyframeAnimator、PhaseAnimator)
- 為設計系統定義運動 Token 時
- 審查動畫程式碼的效能、無障礙性和架構合規性時
按優先級劃分的規則類別
| 優先級 | 類別 | 影響 | 前綴 | 規則數 |
|---|---|---|---|---|
| 1 | 彈簧物理 | 關鍵 | spring- | 8 |
| 2 | 時間與感覺 | 關鍵 | feel- | 6 |
| 3 | 手勢連續性 | 高 | gesture- | 7 |
| 4 | 空間轉場 | 高 | spatial- | 6 |
| 5 | 微互動 | 高 | micro- | 6 |
| 6 | 編排 | 高 | orch- | 5 |
| 7 | 工藝與打磨 | 高 | craft- | 5 |
| 8 | 內容動畫 | 中高 | content- | 5 |
快速參考
1. 彈簧物理 (關鍵)
spring-motion-tokens— 將運動 Token 定義為無 case 的列舉,用於所有彈簧預設spring-smooth-default— 所有 UI 轉場預設使用 .smooth 彈簧spring-snappy-responsive— 反應式互動使用 .snappy 彈簧spring-bouncy-celebration— 趣味和慶祝時刻使用 .bouncy 彈簧spring-custom-parameters— 使用 response 和 dampingFraction 調整自訂彈簧spring-velocity-preservation— 彈簧在被中斷時會保留速度spring-never-linear— 互動式 UI 絕不使用 linear 或 easeInOutspring-completion-chaining— 使用 withAnimation 的完成閉包來鏈接序列
2. 時間與感覺 (關鍵)
feel-250ms-max— UI 動畫保持在 250ms 以下feel-faster-better— 更快的動畫幾乎總是感覺更好feel-asymmetric-enter-exit— 進入和退出使用不對稱的時間feel-distance-proportional— 持續時間與移動距離匹配feel-haptic-sync— 將觸覺反饋與視覺動畫關鍵影格同步feel-stagger-timing— 以 30-50ms 的間隔交錯顯示
3. 手勢連續性 (高)
gesture-rubber-band— 在拖曳邊界使用橡皮筋效果gesture-momentum-dismiss— 在達到速度或距離閾值時關閉gesture-snap-points— 使用能感知速度的吸附點gesture-interruptible— 讓所有手勢動畫都可中斷gesture-scroll-drag-conflict— 解決滾動和拖曳手勢的衝突gesture-state-transient— 使用 GestureState 處理暫態的拖曳狀態gesture-projected-landing— 投影手勢速度以計算自然的落點
4. 空間轉場 (高)
spatial-matched-geometry— 使用 matchedGeometryEffect 進行展開/折疊變形spatial-zoom-navigation— 使用縮放導航轉場顯示集合詳情 (iOS 18)spatial-transition-origin— 將轉場錨定到其觸發位置spatial-hero-shared-element— 共享多個元素 ID 以實現豐富的英雄動畫spatial-sheet-morph— 使用 matchedGeometryEffect 進行工作表呈現spatial-tab-continuity— 在分頁轉場中保持空間方向
5. 微互動 (高)
micro-button-press-scale— 按壓時將按鈕縮放到 0.97 以提供觸覺回饋micro-haptic-pairing— 每個視覺狀態變化都配對觸覺反饋micro-symbol-effect— 使用 symbolEffect 進行 SF Symbol 動畫micro-toggle-bounce— 為切換狀態變化添加彈跳效果micro-long-press-fill— 為長按操作動畫化漸進填充micro-loading-phase— 使用重複的彈簧來產生有機感的載入狀態
6. 編排 (高)
orch-phase-animator— 使用 PhaseAnimator 進行多步驟序列orch-keyframe-animator— 使用 KeyframeAnimator 進行時間軸精確的運動orch-stagger-children— 交錯子元素以實現編排式顯示orch-coordinated-entrance— 使用共享觸發器協調多元素進入orch-timeline-view— 使用 TimelineView 進行連續重複動畫
7. 工藝與打磨 (高)
craft-reduce-motion— 尊重 accessibilityReduceMotion,並使用交叉淡入淡出作為回退craft-blur-bridge— 使用模糊來橋接不完美的過渡狀態craft-drawing-group— 使用 drawingGroup() 進行 Metal 加速的複雜動畫craft-geometry-group— 使用 geometryGroup() 來隔離佈局動畫傳播craft-transaction-debug— 使用 Transaction 來除錯和覆蓋動畫行為
8. 內容動畫 (中高)
content-numeric-text— 使用 contentTransition(.numericText) 處理數字變化content-scroll-transition— 使用 scrollTransition 處理滾動位置效果content-visual-effect— 使用 visualEffect 處理位置感知動畫content-symbol-replace— 使用 contentTransition 動畫化符號替換content-text-renderer— 使用 Text Renderer 處理字元級別動畫 (iOS 18)
如何使用
閱讀單個參考文件以獲取詳細說明,包含錯誤/正確的程式碼範例:
參考文件
| 檔案 | 描述 |
|---|---|
| references/_sections.md | 類別定義和順序 |
| assets/templates/_template.md | 新規則的範本 |
| metadata.json | 版本和參考資訊 |