UIKit 動畫除錯 是做什麼的?
概述
CAAnimation 問題常表現為遺失的完成處理程序、錯誤的時序或特定條件下的卡頓。核心原則 90% 的 CAAnimation 問題來自 CATransaction 時序、圖層狀態或幀率假設,而非 Core Animation 本身的錯誤。
紅旗標誌 — 懷疑 CAAnimation 問題
如果您看到以下任何情況,應懷疑是動畫邏輯而非裝置行為問題:
- 完成處理程序在模擬器上觸發,但在實體裝置上不觸發
- 動畫持續時間(0.5s)與視覺持續時間(1.2s)不符
- 彈簧動畫在 iPhone 15 Pro 上看起來正確,但在較舊的裝置上卡頓
- 手勢與動畫同時使用時卡頓(單獨使用時正常)
- 在完成處理程序中使用
[weak self]但不確定原因 - ❌ 禁止 硬編碼持續時間/數值來「匹配實際發生的情況」
- 這會將裝置特定的錯誤帶給使用不同硬體的用戶
- 不要將其合理化為「暫時修復」或「足夠好」
關鍵區別 模擬器通常隱藏時序問題(僅 60Hz,無調節)。實體裝置會暴露它們(可變幀率、CPU 調節、背景壓力)。強制要求:在出貨前,必須在實體裝置(最舊支援的型號)上測試。
強制性初始步驟
在修改程式碼之前,請始終先執行以下步驟:
// 1. 檢查完成處理程序是否觸發
animation.completion = { [weak self] finished in
print("🔥 完成處理程序已觸發: finished=\(finished)")
guard let self = self else {
print("🔥 self 為 nil")
return
}
// 原始的程式碼
}
// 2. 檢查實際持續時間與宣告時間的差異
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5 // 宣告時間
layer.add(anim, forKey: "test")
DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
print("已耗時間: \(Date().timeIntervalSince(startTime))") // 實際時間
}
// 3. 檢查有哪些動畫正在執行
if let keys = layer.animationKeys() {
print("執行中的動畫: \(keys)")
for key in keys {
if let anim = layer.animation(forKey: key) {
print("\(key): 持續時間=\(anim.duration), 完成後移除=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. 檢查圖層狀態
print("圖層速度: \(layer.speed)") // != 1.0 表示時序被縮放
print("圖層時間偏移: \(layer.timeOffset)") // != 0 表示動畫有偏移
這告訴您什麼
- 完成處理程序的輸出出現 → 處理程序已觸發,問題在於回呼程式碼內部
- 完成處理程序的輸出遺失 → 處理程序未觸發,請檢查 CATransaction/圖層狀態
- 已耗時間 == 宣告時間 → 持續時間是正確的,視覺卡頓來自於幀數
- 已耗時間 != 宣告時間 → CATransaction 包裝改變了持續時間
- layer.speed != 1.0 → 有東西在減慢動畫
- 執行中的動畫列表很長 → 多個動畫在競爭
強制性解讀
在變更任何程式碼之前,您必須確定以下哪一個診斷是根本原因:
- 如果完成處理程序觸發但已耗時間 != 宣告時間 → 應用模式 2 (CATransaction)
- 如果完成處理程序未觸發且 isRemovedOnCompletion 為 true → 應用模式 3
- 如果完成處理程序觸發但視覺上卡頓 → 必須先使用 Instruments 進行分析
- 您不能猜測「可能是幀數問題」— 用資料證明
- Profile > Core Animation 工具可以確定性地顯示掉幀
- 如果您跳過 Instruments,就是在猜測
如果診斷結果有矛盾或不清楚
- 停止。請勿直接進入模式階段
- 新增更多輸出陳述式來縮小原因範圍
- 問自己:「診斷顯示 X 和 Y,但 Z 不符合,我遺漏了什麼?」
- 如果不確定,請使用 Instruments > Core Animation 進行分析
決策樹
CAAnimation 問題?
├─ 完成處理程序從未觸發?
│ ├─ 只在模擬器上?
│ │ └─ 模擬器時序不同 (60Hz)。請在實體裝置上測試。
│ ├─ 只在實體裝置上?
│ │ ├─ 檢查:isRemovedOnCompletion 和 fillMode
│ │ ├─ 檢查:CATransaction 包裝
│ │ └─ 檢查:動畫期間應用程式是否進入背景
│ └─ 在模擬器和實體裝置上都發生?
│ ├─ 檢查:完成處理程序是否在新增動畫**之前**設定
│ └─ 檢查:[weak self] 是否確實被捕獲(在完成之前未變為 nil)
│
├─ 持續時間不符(宣告時間 != 視覺時間)?
│ ├─ 是否 layer.speed != 1.0?
│ │ └─ 有東西縮放了動畫持續時間。找出並修復。
│ ├─ 動畫是否包在 CATransaction 中?
│ │ └─ CATransaction.setAnimationDuration() 會覆蓋 animation.duration
│ └─ 視覺持續時間是否**長於**宣告時間?
│ └─ 模擬器 (60Hz) 與裝置幀率 (120Hz) 的差異。為真實硬體重新計算。
│
├─ 彈簧物理效果在裝置上異常?
│ ├─ 數值是否為單一裝置硬編碼?
│ │ └─ 使用裝置效能等級,而非型號
│ ├─ 阻尼/剛度值是否與質量/剛度值混淆?
│ │ └─ 檢查 CASpringAnimation 參數的意義
│ └─ 在模擬器上正常但在裝置上異常?
│ └─ 模擬器使用 60Hz。裝置可能使用 120Hz。重新計算。
│
└─ 手勢 + 動畫卡頓?
├─ 動畫是否衝突(相同 keyPath)?
│ └─ 在新增新動畫之前移除舊動畫
├─ 手勢是否在動畫執行時更新圖層?
│ └─ 使用 CADisplayLink 進行同步更新
└─ 手勢是否阻塞了主執行緒?
└─ 使用 Instruments > Core Animation 進行分析
常見模式
模式選擇規則(強制性)
一次應用一個模式,按此順序進行
-
始終從模式 1 開始(完成處理程序基礎)
- 如果完成處理程序從未觸發 → 模式 1
- 用輸出陳述式(第 33 行)驗證完成處理程序是在 add() 之前設定的
- 只有當完成處理程序已觸發但時序錯誤時,才繼續進行模式 2
-
然後是模式 2(CATransaction 持續時間不符)
- 僅當完成處理程序觸發但已耗時間 != 宣告時間時
- 檢查來自強制性初始步驟(第 40-47 行)的日誌
-
然後是模式 3(isRemovedOnCompletion)
- 僅當動畫完成但視覺狀態恢復時
-
模式 4-7 根據特定症狀應用(請參閱第 91 行以上的決策樹)
禁止事項
- ❌ 同時應用多個模式(「讓我同時嘗試模式 2 和模式 4」)
- ❌ 因為「我已經知道不是那個問題」而跳過模式 1
- ❌ 在不了解每個模式為何必要的情況下組合它們
- ❌ 隨機嘗試模式並希望其中一個能奏效
模式 1:完成處理程序基礎
❌ 錯誤(在動畫新增後才設定處理程序)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ 太晚了!
print("完成")
}
✅ 正確(在新增之前設定處理程序)
animation.completion = { [weak self] finished in
print("🔥 動畫完成: \(finished)")
guard let self = self else { return }
self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")
原因 完成處理程序必須在動畫新增到圖層之前設定。之後設定無效。
模式 2:CATransaction vs animation.duration
❌ 錯誤(CATransaction 覆蓋動畫持續時間)
CATransaction.begin()
CATransaction.setAnimationDuration(2.0) // ❌ 覆蓋所有動畫!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5 // 這被忽略了
layer.add(anim, forKey: nil)
CATransaction.commit() // 動畫持續 2.0 秒,而非 0.5
✅ 正確(在動畫上設定持續時間,而非交易)
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// 無 CATransaction 包裝
原因 CATransaction.setAnimationDuration() 會影響交易區塊中的所有動畫。僅在您想要統一更改所有動畫時才使用它。
模式 3:isRemovedOnCompletion 與 fillMode
❌ 錯誤(動畫在完成後消失)
let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// 0.5 秒後,動畫被移除且圖層恢復到原始狀態
✅ 正確(保留動畫狀態)
anim.isRemovedOnCompletion = false
anim.fillMode = .forwards // 在動畫完成後保留最終狀態
layer.add(anim, forKey: nil)
// 0.5 秒後,動畫狀態被保留
原因 預設情況下,動畫會被移除且圖層恢復。若要進行永久狀態更改,請設定 isRemovedOnCompletion = false 和 fillMode = .forwards。
模式 4:完成處理程序中的 Weak Self(強制性)
❌ 禁止(強 self 會建立保留迴圈)
anim.completion = { finished in
self.property = "value" // ❌ 保證產生保留迴圈
}
✅ 強制(始終使用 weak self)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "value" // 可以安全存取
}
為什麼這是強制性的,而非可選的
- CAAnimation 會保留完成處理程序,直到動畫完成
- 完成處理程序會強捕獲 self(除非明確使用 weak)
- 產生保留迴圈:self → 動畫 → 完成處理程序 → self
- 即使動畫生命週期很短(0.3 秒也無法防止),記憶體洩漏仍會發生
禁止的合理化觀點
- ❌ 「動畫很短,所以沒有保留迴圈風險」
- ❌ 「我會手動移除動畫,所以沒關係」
- ❌ 「這個程式碼路徑只執行一次」
在完成處理程序中始終使用 [weak self]。沒有例外。
模式 5:多個動畫(相同 keyPath)
❌ 錯誤(動畫衝突)
// 新增動畫 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")
// 稍後,新增動畫 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide") // ❌ 相同鍵,取代了 anim1!
✅ 正確(在新增之前移除)
layer.removeAnimation(forKey: "slide") // 先移除舊的
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")
或者使用唯一的鍵:
let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")
let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2") // 不同的鍵
原因 使用相同鍵新增動畫會取代先前的動畫。請移除舊動畫或使用唯一鍵。
模式 6:使用 CADisplayLink 進行手勢與動畫同步
❌ 錯誤(手勢直接更新,動畫以不同速率更新)
func handlePan(_ gesture: UIPanGestureRecognizer) {
let translation = gesture.translation(in: view)
view.layer.position.x = translation.x // ❌ 同步問題
}
// 另外:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil) // 因不同步而卡頓
✅ 正確(使用 CADisplayLink 進行同步)
var displayLink: CADisplayLink?
func startSyncedAnimation() {
displayLink = CADisplayLink(
target: self,
selector: #selector(updateAnimation)
)
displayLink?.add(to: .main, forMode: .common)
}
@objc func updateAnimation() {
// 在同一個影格中更新手勢**和**動畫
let gesture = currentGesture
let position = calculatePosition(from: gesture)
layer.position = position // 同步更新
}
原因 手勢辨識器和 CAAnimation 可能以不同的幀率執行。CADisplayLink 將兩者同步到螢幕更新率。
模式 7:彈簧動畫的裝置差異
❌ 錯誤(為單一裝置硬編碼)
let springAnim = CASpringAnimation()
springAnim.damping = 0.7 // 為 iPhone 15 Pro 硬編碼
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil) // 在 iPhone 12 上卡頓
✅ 正確(適應裝置效能)
let springAnim = CASpringAnimation()
// 使用裝置效能等級,而非型號
if ProcessInfo.processInfo.processorCount >= 6 {
// 現代 A 系列(A14+)
springAnim.damping = 0.7
springAnim.stiffness = 100
} else {
// 舊款 A 系列
springAnim.damping = 0.85
springAnim.stiffness = 80
}
layer.add(springAnim, forKey: nil)
原因 彈簧物理效果在 60Hz 和 120Hz 下感覺不同。使用裝置類別(核心數、GPU)而非型號。
快速參考表
| 問題 | 檢查 | 修復 |
|---|---|---|
| 完成處理程序從未觸發 | 在 add() 之前設定處理程序 | 將 completion = 移到 add() 之前 |
| 持續時間不符 | 是否有 CATransaction 包裝? | 移除 CATransaction 或將動畫從其中移除 |
| 較舊裝置上卡頓 | 數值是否硬編碼? | 使用 ProcessInfo 判斷裝置類別 |
| 動畫消失 | isRemovedOnCompletion? | 設為 false,使用 fillMode = .forwards |
| 手勢 + 動畫卡頓 | 是否同步更新? | 使用 CADisplayLink |
| 多個動畫衝突 | 使用相同鍵? | 使用唯一鍵或先使用 removeAnimation() |
| 處理程序中的 weak self | 完成處理程序是否正確捕獲? | 在完成處理程序中總是使用 [weak self] |
當您在 30 分鐘後仍卡住時
如果您花了超過 30 分鐘,動畫仍然有問題:
停止。您可能
- 跳過了某個強制性步驟(最常見)
- 誤解了診斷輸出
- 為您的症狀應用了錯誤的模式
- 處於需要 Instruments 分析的那 5% 的邊緣案例中
在聲稱「技能無效」之前的強制性檢查清單
- 我從強制性初始步驟(第 28-63 行)執行了所有 4 個診斷區塊
- 我貼上了診斷結果的確切輸出(日誌、輸出陳述式)
- 我從「這告訴您什麼」(第 66-72 行)確定了一個根本原因
- 我從決策樹(第 91 行以上)應用了第一個符合的模式
- 我在實體裝置上測試了該模式,而不僅是模擬器
- [ ]