dot-skills — Airbnb iOS SwiftUI 动画最佳实践
一份高度规范且严格的 SwiftUI iOS 26 / Swift 6.2 动画创作指南,包含 50 条规则,覆盖 8 大类别,按影响程度排列优先级。源自 Airbnb 工程动画模式、Apple WWDC 会议以及 Apple 人机界面指南。要求每个动画视图都使用 @Equatable,所有弹簧/时间值使用动画令牌,布局使用设计系统令牌。
强制架构对齐
本技能旨在与 swift-ui-architect 和 ios-design-system 协同工作。所有代码示例均遵循以下不可协商的约束:
- 每个视图上使用
@Equatable宏(据 Airbnb 测量,可减少 15% 的滚动卡顿) - 对于涉及业务逻辑触发的复杂动画状态,使用
@Observable - 对于视图自身拥有的动画状态(如切换布尔值、拖动偏移量),使用
@State - 设计系统令牌:
Spacing.xs/sm/md/lg,Radius.sm/md/lg— 零硬编码布局数值 - 动画令牌:
Motion.standard/responsive/playful— 零散落的弹簧字面量 - 语义颜色:
.backgroundSurface,.accentPrimary— 视图中不使用原始 Color 字面量 - 功能动画仅用于展示;数据/网络相关逻辑保留在 Data package 中
范围及与同级技能的关系
本技能是动画层 — 它教授如何构建流畅、高性能的动画。与同级技能配合使用时:
| 同级技能 | 其专注点 | 本技能专注点 |
|---|---|---|
swift-ui-architect | 架构(模块化 MVVM-C、路由壳、协议边界) | 动画架构(动画令牌、弹簧选择、编排) |
ios-design-system | 设计系统基础设施(令牌、样式、治理) | 动画令牌和动画组件模式 |
ios-hig | HIG 合规性模式 | 特定于运动的 HIG(减少动画、空间连续性) |
超出范围: 设计师创作的矢量动画(请使用 Lottie 处理 After Effects 导出)。复杂的 UIKit 过渡控制器(请参阅 Airbnb 的声明式过渡框架)。本技能仅涵盖程序化 SwiftUI 动画。
诊所架构契约(iOS 26 / Swift 6.2)
本技能的所有指导均假设采用诊所模块化 MVVM-C 架构:
- Feature 模块仅导入
Domain+DesignSystem(从不导入Data,也从不导入同级 feature) - App target 是汇聚点,拥有
DependencyContainer、具体的协调器和路由壳接线 Domain保持纯 Swift,定义模型、仓库、*Coordinating、ErrorRouting和AppError契约Data拥有 SwiftData/网络/同步/重试/后台 I/O,并实现 Domain 协议- 读/写流程默认采用“过时再验证”读取和乐观排队写入
- ViewModel 直接调用仓库协议(无需默认的用例/交互器层)
何时应用
在以下情况参考这些指南:
- 向 SwiftUI 视图或过渡添加动画
- 构建基于手势的交互(拖拽、滑动、平移)
- 使用空间过渡连接视图(展开/折叠、导航变形)
- 设计微交互(按钮按下、切换、加载状态)
- 使内容变化感觉有物理感(数字滚动、符号替换)
- 编排多元素动画序列(
KeyframeAnimator、PhaseAnimator) - 为设计系统定义动画令牌
- 审查动画代码的性能、可访问性和架构合规性
按优先级划分的规则类别
| 优先级 | 类别 | 影响 | 前缀 | 规则数 |
|---|---|---|---|---|
| 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— 将动画令牌定义为无 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— 对瞬态拖动状态使用GestureStategesture-projected-landing— 投射手势速度以确定自然着陆位置
4. 空间过渡(高)
spatial-matched-geometry— 对展开/折叠变形使用matchedGeometryEffectspatial-zoom-navigation— 对集合详情使用缩放导航过渡(iOS 18)spatial-transition-origin— 将过渡锚定到其触发位置spatial-hero-shared-element— 共享多个元素 ID 以创建丰富的英雄动画spatial-sheet-morph— 对表单展示使用matchedGeometryEffectspatial-tab-continuity— 在标签过渡中保持空间方向
5. 微交互(高)
micro-button-press-scale— 按下时按钮缩放至 0.97 以提供触感反馈micro-haptic-pairing— 每次视觉状态变化都配以触觉反馈micro-symbol-effect— SF 符号动画使用symbolEffectmicro-toggle-bounce— 为切换状态变化添加弹跳效果micro-long-press-fill— 长按操作动画化渐进填充micro-loading-phase— 对自然加载状态使用重复弹簧
6. 编排(高)
orch-phase-animator— 对多步序列使用PhaseAnimatororch-keyframe-animator— 对时间轴精确运动使用KeyframeAnimatororch-stagger-children— 交错子元素以编排展示orch-coordinated-entrance— 使用共享触发器协调多元素进入orch-timeline-view— 对连续重复动画使用TimelineView
7. 工艺与润色(高)
craft-reduce-motion— 使用淡入淡出回退方案尊重accessibilityReduceMotioncraft-blur-bridge— 使用模糊来桥接不完美的过渡状态craft-drawing-group— 对 Metal 支持的复杂动画使用drawingGroup()craft-geometry-group— 使用geometryGroup()隔离布局动画传播craft-transaction-debug— 使用Transaction调试和覆盖动画行为
8. 内容动画(中-高)
content-numeric-text— 数字变化使用contentTransition(.numericText)content-scroll-transition— 对滚动位置效果使用scrollTransitioncontent-visual-effect— 对位置感知动画使用visualEffectcontent-symbol-replace— 使用contentTransition动画化符号替换content-text-renderer— 使用 Text Renderer 实现字符级动画(iOS 18)
使用方法
阅读单独的参考文件以获取详细的解释,其中包含错误/正确的代码示例:
参考文件
| 文件 | 描述 |
|---|---|
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本和参考信息 |