松手速度决定一切:Gagat惯性动画源码解析,让iOS深色模式切换丝滑如现实纸张

原创2026-10-25 14:58:551,890 阅读

松手速度决定一切:Gagat惯性动画源码解析,让iOS深色模式切换丝滑如现实纸张

Gagat 是一个轻量级 Swift 开源库,通过双指下滑手势让 iOS 深色模式切换拥有如同翻纸般的惯性动画。它最迷人的地方,在于松手那一刻的"惯性"——快速甩动屏幕瞬间完成切换,缓慢拖拽则稳稳弹回。本文带你用大白话看懂这套动画背后的源码逻辑,无需任何数学基础。

一、深色模式切换新姿势:双指下滑"翻纸"

Gagat 设计的交互非常简单:

  • 📄 在 App 的任意位置用两根手指向下滑动,旧主题的边界会跟随手指下移
  • ✨ 滑得越慢,新主题(深色模式)露出得越少;滑过屏幕一半就会完成切换
  • 🖐️ 松手瞬间,动画时长由松手速度决定,快速甩动几乎"瞬间"完成
  • 滑得慢且没过一半?边界会带一点"纸张抖动"地弹回原位

值得一提的是,Gagat 不负责样式——明暗两套主题怎么写由你自己决定,它只负责那段"翻纸"的过渡动画。

二、源码结构总览:4 个文件看懂 Gagat

整个库的核心逻辑只有 4 个 Swift 文件,非常适合通读:

文件 职责
Gagat.swift 公共入口:GagatStyleable 协议与 Gagat.configure(for:with:using:) 配置方法
TransitionCoordinator.swift 核心状态机:快照、遮罩、惯性决策都在这里
AnimationUtilities.swift 惯性时长计算,"松手速度决定一切"的真正主角
PessimisticPanGestureRecognizer.swift "悲观"双指手势,让动画与滚动视图和平共处

三、一张快照 + 一块遮罩:动画的秘密

深色模式切换最难的是"旧界面逐像素变色的过程"。Gagat 用了一个极聪明的偷懒方案:

  1. 手势开始时,先对整个屏幕拍一张快照(snapshotView),盖在最上层;
  2. 快照底下立刻应用深色主题——此时你看不见,因为快照挡住了;
  3. 用一个 CAShapeLayer 作为快照的遮罩:手指下移多少,遮罩边界就下移多少,深色新主题随之露出。

就像用手指翻书页:旧页是快照,新页是底下已换好墨色的真视图。整个切换过程只有一层遮罩在动,性能开销极低。

相关实现见 TransitionCoordinator.swift 的 beginInteractiveStyleTransition。

还有一个细节:遮罩位置用的是手势的 translation(位移量) 而非手指的绝对位置——就像移动一张纸时,纸相对桌面的位移跟随手指移动,而不是"粘"在指尖上,手感更真实(源码注释解释见 TransitionCoordinator.swift)。

四、松手速度如何决定动画时长

这是全文的核心。手指松开后(endInteractiveStyleTransition),Gagat 分两步走:

第一步:判定结果。 同时满足"还在往下动"(速度向下)或"已滑过屏幕一半"(位移超过 midY)就完成切换,否则弹回。

第二步:计算时长。 见 AnimationUtilities.swift:

positionAnimation.duration = min(
    maximumReasonableTimeToMove(from: startPoint, to: targetPoint),
    timeRequiredToMove(from: startPoint, to: targetPoint, withVelocity: velocity)
)

两个候选时间取较小值,规则很直白:

  • timeRequiredToMove = 剩余距离 ÷ 松手速度 → 甩得越快,时间越短,"啪"地收尾;
  • maximumReasonableTimeToMove = 距离 ÷ 300pt/s(一个经验测得的"合理最低速度",见 AnimationUtilities.swift)→ 就算你轻手轻脚地松手,动画也不会拖沓超过这个上限。

快则快,慢有上限——这就是"惯性"的来源,整段逻辑不到 50 行。

五、jellyFactor:边界为什么会"抖"

拖动时遮罩边界不是直线,而是一条二次贝塞尔曲线,控制点的竖直偏移量 = 松手速度 ÷ 阻尼系数(damping = 45 ÷ jellyFactor)。速度越快,边界弯曲越大,就像纸张被快速掀起时的鼓胀。

更妙的是回弹不需要额外动画:手指停住后,手势回调仍会持续触发直到速度归零,路径每帧重算,边界自然"抖"回平直。

jellyFactor 默认 1.0,数值越大抖得越明显,设为 0 则完全关闭,官方示例 App 使用了 1.5(见 Gagat Example/AppDelegate.swift)。实现细节在 adjustMaskLayerPath。

六、"悲观"手势:与 UIScrollView 和平共处

双指下滑很容易和单指滚动冲突(比如 UITableView)。Gagat 的 PessimisticPanGestureRecognizer 会尽早主动认输:实际触到的手指数不足 2 且拖动距离不足 10pt 时直接进入 .failed,把事件让给滚动视图处理。

此外,gestureRecognizerShouldBegin 只允许向下方向(45°~135°)触发,左右上方向的滑动手势完全不受影响。

七、三步把 Gagat 接入你的 iOS 项目

📦 环境要求:iOS 10.0+、Swift 5.0、Xcode 10.2,支持 Swift 与 Objective-C 双端调用。

第 1 步:实现样式切换。 让你的根控制器(或任意对象)遵循 GagatStyleable 协议,实现 toggleActiveStyle() 方法,在其中同步完成明暗主题的切换(协议定义见 Gagat.swift)。

第 2 步:添加依赖。 推荐用 Carthage,在 Cartfile 中加入:

github "Boerworz/Gagat" ~> 3.0

不用 Carthage 的话,直接把 Gagat.xcodeproj 作为子工程拖进工作区即可。

第 3 步:配置并保留引用。 在 AppDelegate 中完成配置:

let configuration = Gagat.Configuration(jellyFactor: 1.5)
let styleable = window!.rootViewController as! GagatStyleable
transitionHandle = Gagat.configure(for: window!, with: styleable, using: configuration)

⚠️ 关键坑点:必须一直持有 configure 返回的返回的 TransitionHandle 引用——它一旦释放,手势识别器会被自动拆除,切换功能随之失效。

Objective-C 项目对应的类型名略有不同(GGTManager / GGTStyleable / GGTConfiguration / GGTTransitionHandle),桥接实现见 GagatObjectiveC/Gagat.swift。

八、总结:值得借鉴的三个设计

  • 🎯 交互:双指下滑 + 半屏阈值 + 速度惯性,符合现实纸张的肌肉记忆;
  • ⚡ 实现:快照 + 遮罩,只动画一层 CAShapeLayer,任何复杂界面都能"秒换肤";
  • ✨ 细节:用松手速度压缩动画时长、用贝塞尔曲线模拟纸张形变,几十行代码换来"高级感"。

通读这 4 个核心文件,你会对"手势驱动的惯性动画"有一个非常清晰的认识——下次想给 App 加自定义过渡动画时,这套思路随时可以复用。

登录后查看全文
Gagat