Communitygithub.com

UIKit 動畫除錯

當 CAAnimation 完成處理程序未觸發、彈簧物理效果在裝置上異常、動畫持續時間與實際時間不符、手勢與動畫交互導致卡頓,或模擬器與實機之間時序不一致時使用 —— 系統性的 CAAnimation 診斷,包含 CATransaction 模式、幀率感知及裝置特定行為。

UIKit 動畫除錯 是什麼?

這個技能提供一套完整的 CAAnimation 問題診斷與修復框架。它首先引導開發者通過強制的初步診斷步驟(如檢查完成處理程序是否觸發、實際持續時間與宣告時間的差異、活躍動畫列表及圖層狀態),快速定位問題根源。基於診斷結果,技能提供了一個決策樹和七種常見模式,涵蓋完成處理程序基礎、CATransaction 覆蓋動畫持續時間、動畫消失(isRemovedOnCompletion/fillMode)、weak self 和保留迴圈、多個動畫衝突、手勢與動畫同步(使用 CADisplayLink)以及彈簧動畫的裝置差異。此技能支援 Swift/UIKit 專案,並強烈要求在最舊支援的實體裝置上測試,因為模擬器經常隱藏時序與幀率問題。它尤其適用於 Claude Code、Cursor 和 Codex 等 AI 編碼代理,作為結構化的思維鏈指導來診斷和解決複雜的 Core Animation 問題,並明確禁止猜測性修復或硬編碼數值。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/Axiom/.claude-plugin/plugins/axiom/skills/uikit-animation-debugging

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 → 有東西在減慢動畫
  • 執行中的動畫列表很長 → 多個動畫在競爭

強制性解讀

在變更任何程式碼之前,您必須確定以下哪一個診斷是根本原因:

  1. 如果完成處理程序觸發但已耗時間 != 宣告時間 → 應用模式 2 (CATransaction)
  2. 如果完成處理程序未觸發且 isRemovedOnCompletion 為 true → 應用模式 3
  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 開始(完成處理程序基礎)

    • 如果完成處理程序從未觸發 → 模式 1
    • 用輸出陳述式(第 33 行)驗證完成處理程序是在 add() 之前設定的
    • 只有當完成處理程序已觸發但時序錯誤時,才繼續進行模式 2
  2. 然後是模式 2(CATransaction 持續時間不符)

    • 僅當完成處理程序觸發但已耗時間 != 宣告時間時
    • 檢查來自強制性初始步驟(第 40-47 行)的日誌
  3. 然後是模式 3(isRemovedOnCompletion)

    • 僅當動畫完成但視覺狀態恢復時
  4. 模式 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 分鐘,動畫仍然有問題:

停止。您可能

  1. 跳過了某個強制性步驟(最常見)
  2. 誤解了診斷輸出
  3. 為您的症狀應用了錯誤的模式
  4. 處於需要 Instruments 分析的那 5% 的邊緣案例中

在聲稱「技能無效」之前的強制性檢查清單

  • 我從強制性初始步驟(第 28-63 行)執行了所有 4 個診斷區塊
  • 我貼上了診斷結果的確切輸出(日誌、輸出陳述式)
  • 我從「這告訴您什麼」(第 66-72 行)確定了一個根本原因
  • 我從決策樹(第 91 行以上)應用了第一個符合的模式
  • 我在實體裝置上測試了該模式,而不僅是模擬器
  • [ ]

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when localizing apps, using String Catalogs, generating type-safe symbols (Xcode 26+), handling plurals, RTL layouts, locale-aware formatting, or migrating from .strings files - comprehensive i18n patterns for Xcode 15-26

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

相關技能