Communitygithub.com

UIKit-Animation-Debugging (CAAnimation-Diagnose)

Diagnose systematischer CAAnimation-Probleme mit CATransaction-Mustern, Bildraten-Bewusstsein und gerätespezifischem Verhalten, wenn Completion-Handler nicht feuern, Feder-Physik auf dem Gerät falsch aussieht, Animationsdauern von der tatsächlichen Zeit abweichen oder die Interaktion von Gesten und Animationen zu Ruckeln führt.

Was ist UIKit-Animation-Debugging (CAAnimation-Diagnose)?

Diese Skill-Anleitung bietet eine systematische Methode zur Diagnose und Behebung von CAAnimation-Problemen in UIKit. Sie deckt die häufigsten Fehlerquellen ab: nicht ausgelöste Completion-Handler, Diskrepanzen zwischen deklarierten und tatsächlichen Animationsdauern (insbesondere durch CATransaction-Übersteuerung), falsches Federverhalten aufgrund von Unterschieden zwischen Simulator (60 Hz) und realen Geräten (variable Bildrate) sowie Ruckler bei gleichzeitiger Gesten- und Animationssteuerung. Die Anleitung erzwingt einen schrittweisen, nicht-heuristischen Ansatz: Zuerst müssen obligatorische Diagnose-Blöcke ausgeführt werden, um die genaue Ursache zu identifizieren (z. B. ob der Handler überhaupt feuert, ob die Layer-Geschwindigkeit von 1,0 abweicht oder ob mehrere Animationen konkurrieren). Basierend auf den Diagnoseergebnissen wird ein Entscheidungsbaum durchlaufen, der strikt ein Muster nach dem anderen anwendet (z. B. Muster 1: Completion-Handler vor dem Hinzufügen setzen; Muster 2: CATransaction-Dauer überschreibt; Muster 3: isRemovedOnCompletion und fillMode). Die Anleitung verbietet explizit das gleichzeitige Anwenden mehrerer Muster oder das Raten von „temporären“ Fixes. Sie gilt für macOS- und iOS-Entwicklung mit UIKit und betont die Notwendigkeit, auf einem echten Gerät (dem ältesten unterstützten Modell) zu testen, da der Simulator oft Probleme verbirgt. Bei Zeitüberschreitung von 30 Minuten wird ein obligatorischer Check-Liste durchlaufen, um sicherzustellen, dass kein Diagnoseschritt ausgelassen wurde. Die Anleitung basiert auf der Erfahrung, dass 90 % der CAAnimation-Probleme auf CATransaction-Timing, Layer-Status oder Bildraten-Annahmen zurückzuführen sind – nicht auf Fehler in Core Animation selbst.

Funktioniert mit✓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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

UIKit Animations-Debugging

Überblick

CAAnimation-Probleme äußern sich als fehlende Completion-Handler, falsches Timing oder Ruckeln unter bestimmten Bedingungen. Kernprinzip: 90 % der CAAnimation-Probleme sind auf CATransaction-Timing, Layer-Status oder Bildraten-Annahmen zurückzuführen, nicht auf Fehler in Core Animation.

Alarmzeichen – CAAnimation-Problem vermuten

Wenn SIE EINES DIESER Symptome sehen, vermuten Sie eine Animationslogik, kein Geräteverhalten:

  • Completion-Handler feuert im Simulator, aber nicht auf dem Gerät
  • Animationsdauer (0,5s) stimmt nicht mit der visuellen Dauer (1,2s) überein
  • Feder-Animation sieht auf dem iPhone 15 Pro korrekt aus, ruckelt aber auf älteren Geräten
  • Geste + Animation zusammen verursacht Ruckeln (einzeln in Ordnung)
  • [weak self] im Completion-Handler und Sie sind sich nicht sicher, warum
  • ❌ VERBOTEN: Dauer/Werte hartkodieren, um „dem tatsächlichen Verhalten zu entsprechen“
    • Das liefert gerätespezifische Bugs an Benutzer mit unterschiedlicher Hardware aus
    • Rationalisieren Sie dies nicht als „vorübergehenden Fix“ oder „gut genug“

Kritische Unterscheidung: Der Simulator verbirgt oft Timing-Probleme (nur 60Hz, kein Throttling). Echte Geräte decken sie auf (variable Bildrate, CPU-Drosselung, Hintergrunddruck). VERPFLICHTEND: Vor der Auslieferung auf einem echten Gerät (dem ältesten unterstützten Modell) testen.

Obligatorische erste Schritte

Führen Sie DIESE IMMER ZUERST aus (bevor Sie Code ändern):

// 1. Prüfen, ob der Completion überhaupt feuert
animation.completion = { [weak self] finished in
    print("🔥 COMPLETION GEFEUERT: finished=\(finished)")
    guard let self = self else {
        print("🔥 SELF WAR NIL")
        return
    }
    // ursprünglicher Code
}

// 2. Tatsächliche Dauer vs. deklarierte Dauer prüfen
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5  // Deklariert
layer.add(anim, forKey: "test")

DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
    print("Verstrichene Zeit: \(Date().timeIntervalSince(startTime))")  // Tatsächlich
}

// 3. Prüfen, welche Animationen aktiv sind
if let keys = layer.animationKeys() {
    print("Aktive Animationen: \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key): dauer=\(anim.duration), entfernt=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. Layer-Status prüfen
print("Layer-Geschwindigkeit: \(layer.speed)")  // != 1.0 bedeutet, Timing ist skaliert
print("Layer-timeOffset: \(layer.timeOffset)")  // != 0 bedeutet, Animation ist verschoben

Was Ihnen das sagt

  • Completion-Ausgabe erscheint → Handler feuert, Problem liegt im Callback-Code
  • Completion-Ausgabe fehlt → Handler feuert nicht, CATransaction/Layer-Status prüfen
  • Verstrichene Zeit == deklarierte Dauer → Dauer ist korrekt, visuelles Ruckeln kommt von Frames
  • Verstrichene Zeit != deklarierte Dauer → CATransaction-Umhüllung ändert die Dauer
  • layer.speed != 1.0 → Etwas verlangsamt die Animation
  • Liste der aktiven Animationen ist lang → Mehrere Animationen konkurrieren

VERPFLICHTENDE INTERPRETATION

Bevor Sie IRGENDEINEN Code ändern, müssen Sie identifizieren, WELCHE EINZIGE Diagnose die Ursache ist:

  1. Wenn der Completion feuert, aber die verstrichene Zeit != deklarierte Dauer ist → Muster 2 anwenden (CATransaction)
  2. Wenn der Completion NICHT feuert UND isRemovedOnCompletion true ist → Muster 3 anwenden
  3. Wenn der Completion feuert, aber die visuelle Darstellung ruckelt → MUSS zuerst mit Instruments profilieren
    • Sie können nicht raten: „Es liegt wahrscheinlich an den Frames“ – beweisen Sie es mit Daten
    • Profil > Core Animation Instrument zeigt Frame-Drops mit Sicherheit
    • Wenn Sie Instruments überspringen, raten Sie nur

Wenn die Diagnosen widersprüchlich oder unklar sind

  • STOPPEN Sie. Fahren Sie NOCH NICHT mit den Mustern fort
  • Fügen Sie weitere print-Anweisungen hinzu, um die Ursache einzugrenzen
  • Fragen Sie: „Die Diagnosen zeigen X und Y, aber Z passt nicht. Was übersehe ich?“
  • Profilieren Sie mit Instruments > Core Animation, wenn Sie unsicher sind

Entscheidungsbaum

CAAnimation-Problem?
├─ Completion-Handler feuert nie?
│  ├─ Nur im Simulator?
│  │  └─ Simulator-Timing ist anders (60Hz). Auf echtem Gerät testen.
│  ├─ Nur auf echtem Gerät?
│  │  ├─ Prüfen: isRemovedOnCompletion und fillMode
│  │  ├─ Prüfen: CATransaction-Umhüllung
│  │  └─ Prüfen: App geht während der Animation in den Hintergrund
│  └─ Sowohl im Simulator als auch auf dem Gerät?
│     ├─ Prüfen: Completion-Handler wird VOR dem Hinzufügen der Animation gesetzt
│     └─ Prüfen: [weak self] wird tatsächlich erfasst (nicht nil vor Completion)
│
├─ Dauerabweichung (deklariert != visuell)?
│  ├─ Ist layer.speed != 1.0?
│  │  └─ Etwas hat die Animationsdauer skaliert. Finden und beheben.
│  ├─ Ist die Animation in CATransaction eingeschlossen?
│  │  └─ CATransaction.setAnimationDuration() überschreibt animation.duration
│  └─ Ist die visuelle Dauer LÄNGER als deklariert?
│     └─ Simulator (60Hz) vs. Geräte-Bildrate (120Hz). Für echte Hardware neu berechnen.
│
├─ Feder-Physik falsch auf dem Gerät?
│  ├─ Sind Werte für ein Gerät hartkodiert?
│  │  └─ Geräteleistungsklasse verwenden, nicht Modell
│  ├─ Sind Dämpfungs-/Steifigkeitswerte mit Masse/Steifigkeit vertauscht?
│  │  └─ CASpringAnimation-Parameterbedeutungen prüfen
│  └─ Funktioniert es im Simulator, aber nicht auf dem Gerät?
│     └─ Simulator verwendet 60Hz. Gerät kann 120Hz verwenden. Neu berechnen.
│
└─ Geste + Animation ruckelt?
   ├─ Konkurrieren Animationen (gleicher keyPath)?
   │  └─ Alte Animation entfernen, bevor eine neue hinzugefügt wird
   ├─ Aktualisiert die Geste den Layer, während die Animation läuft?
   │  └─ CADisplayLink für synchronisierte Updates verwenden
   └─ Blockiert die Geste den Hauptthread?
      └─ Mit Instruments > Core Animation profilieren

Häufige Muster

Muster-Auswahlregeln (VERPFLICHTEND)

Wenden Sie EIN MUSTER nach dem anderen an, in dieser Reihenfolge

  1. Beginnen Sie immer mit Muster 1 (Completion-Handler-Grundlagen)

    • Wenn der Completion NIE feuert → Muster 1
    • Überprüfen Sie, ob der Completion VOR add() mit einer print-Anweisung gesetzt wird (Zeile 33)
    • Fahren Sie nur mit Muster 2 fort, wenn der Completion FEUERT, aber das Timing falsch ist
  2. Dann Muster 2 (CATransaction-Dauerabweichung)

    • Nur wenn der Completion feuert, aber die verstrichene Zeit != deklarierte Dauer ist
    • Überprüfen Sie die Logs aus den Obligatorischen ersten Schritten (Zeile 40-47)
  3. Dann Muster 3 (isRemovedOnCompletion)

    • Nur wenn die Animation abgeschlossen ist, aber der visuelle Zustand zurückgesetzt wird
  4. Muster 4-7 Anwendung basierend auf spezifischem Symptom (siehe Entscheidungsbaum Zeile 91+)

VERBOTEN

  • ❌ Mehre Muster gleichzeitig anwenden („Lass mich Muster 2 UND Muster 4 zusammen ausprobieren“)
  • ❌ Muster 1 überspringen, weil „ich schon weiß, dass es das nicht ist“
  • ❌ Muster kombinieren, ohne zu verstehen, warum jedes benötigt wird
  • ❌ Muster zufällig ausprobieren und hoffen, dass eines funktioniert

Muster 1: Completion-Handler-Grundlagen

❌ FALSCH (Handler NACH dem Hinzufügen der Animation gesetzt)

layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in  // ❌ Zu spät!
    print("Fertig")
}

✅ RICHTIG (Handler VOR dem Hinzufügen gesetzt)

animation.completion = { [weak self] finished in
    print("🔥 Animation beendet: \(finished)")
    guard let self = self else { return }
    self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")

Warum Der Completion-Handler muss gesetzt werden, BEVOR die Animation zum Layer hinzugefügt wird. Ein Setzen danach bewirkt nichts.


Muster 2: CATransaction vs. animation.duration

❌ FALSCH (CATransaction überschreibt die Animationsdauer)

CATransaction.begin()
CATransaction.setAnimationDuration(2.0)  // ❌ Überschreibt ALLE Animationen!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5  // Dies wird ignoriert
layer.add(anim, forKey: nil)
CATransaction.commit()  // Animation dauert 2,0 Sekunden, nicht 0,5

✅ RICHTIG (Dauer an der Animation setzen, nicht an der Transaktion)

let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Keine CATransaction-Umhüllung

Warum CATransaction.setAnimationDuration() betrifft ALLE Animationen im Transaktionsblock. Verwenden Sie es nur, wenn Sie alle Animationen gleichmäßig ändern möchten.


Muster 3: isRemovedOnCompletion & fillMode

❌ FALSCH (Animation verschwindet nach Abschluss)

let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Nach 0,5s wird die Animation entfernt UND der Layer kehrt zum ursprünglichen Zustand zurück

✅ RICHTIG (Animationszustand beibehalten)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // Endzustand nach der Animation beibehalten
layer.add(anim, forKey: nil)
// Nach 0,5s wird der Animationszustand beibehalten

Warum Standardmäßig werden Animationen entfernt und der Layer kehrt zurück. Für dauerhafte Zustandsänderungen setzen Sie isRemovedOnCompletion = false und fillMode = .forwards.


Muster 4: Weak Self im Completion (VERPFLICHTEND)

❌ VERBOTEN (Starkes Self erzeugt einen Retain-Zyklus)

anim.completion = { finished in
    self.property = "value"  // ❌ GARANTIERTER Retain-Zyklus
}

✅ VERPFLICHTEND (Immer weak self verwenden)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "value"  // Sicherer Zugriff
}

Warum dies VERPFLICHTEND und nicht optional ist

  • CAAnimation hält den Completion-Handler am Leben, bis die Animation abgeschlossen ist
  • Der Completion-Handler erfasst self stark (sofern nicht explizit weak)
  • Erzeugt einen Retain-Zyklus: self → Animation → Completion → self
  • Speicherleck tritt auch auf, wenn die Animation kurzlebig ist (0,3s verhindert es nicht)

VERBOTENE Rationalisierungen

  • ❌ „Die Animation ist kurz, also besteht kein Retain-Zyklus-Risiko“
  • ❌ „Ich entferne die Animation manuell, also ist es in Ordnung“
  • ❌ „Dieser Codepfad wird nur einmal ausgeführt“

Verwenden Sie IMMER [weak self] in Completion-Handlern. Keine Ausnahmen.


Muster 5: Mehrere Animationen (Gleicher keyPath)

❌ FALSCH (Animationen kollidieren)

// Animation 1 hinzufügen
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")

// Später Animation 2 hinzufügen
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")  // ❌ Gleicher Schlüssel, ersetzt anim1!

✅ RICHTIG (Vor dem Hinzufügen entfernen)

layer.removeAnimation(forKey: "slide")  // Zuerst alte entfernen

let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")

Oder eindeutige Schlüssel verwenden:

let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")

let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2")  // Anderer Schlüssel

Warum Das Hinzufügen einer Animation mit demselben Schlüssel ersetzt die vorherige Animation. Entweder die alte Animation entfernen oder eindeutige Schlüssel verwenden.


Muster 6: CADisplayLink für Geste + Animations-Synchronisation

❌ FALSCH (Geste aktualisiert direkt, Animation aktualisiert mit anderer Rate)

func handlePan(_ gesture: UIPanGestureRecognizer) {
    let translation = gesture.translation(in: view)
    view.layer.position.x = translation.x  // ❌ Synchronisationsproblem
}

// Separat:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // Ruckeln durch Desynchronisation

✅ RICHTIG (CADisplayLink zur Synchronisation verwenden)

var displayLink: CADisplayLink?

func startSyncedAnimation() {
    displayLink = CADisplayLink(
        target: self,
        selector: #selector(updateAnimation)
    )
    displayLink?.add(to: .main, forMode: .common)
}

@objc func updateAnimation() {
    // Geste UND Animation im selben Frame aktualisieren
    let gesture = currentGesture
    let position = calculatePosition(from: gesture)
    layer.position = position  // Synchronisierte Aktualisierung
}

Warum Gestenerkenner und CAAnimation können mit unterschiedlichen Bildraten laufen. CADisplayLink synchronisiert beide mit der Bildwiederholfrequenz.


Muster 7: Feder-Animation – Geräteunterschiede

❌ FALSCH (Für ein Gerät hartkodiert)

let springAnim = CASpringAnimation()
springAnim.damping = 0.7  // Hartkodiert für iPhone 15 Pro
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil)  // Ruckelt auf iPhone 12

✅ RICHTIG (An Geräteleistung anpassen)

let springAnim = CASpringAnimation()

// Geräteleistungsklasse verwenden, nicht Modell
if ProcessInfo.processInfo.processorCount >= 6 {
    // Moderne A-Serie (A14+)
    springAnim.damping = 0.7
    springAnim.stiffness = 100
} else {
    // Ältere A-Serie
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

Warum Feder-Physik fühlt sich bei 60Hz vs. 120Hz anders an. Geräteklasse (Kernanzahl, GPU) verwenden, nicht das Modell.


Kurzreferenztabelle

ProblemPrüfenBehebung
Completion feuert nieHandler VOR add() setzencompletion = vor add() verschieben
DauerabweichungCATransaction-Umhüllung?CATransaction entfernen oder Animation daraus entfernen
Ruckeln auf älteren GerätenWert hartkodiert?ProcessInfo für Geräteklasse verwenden
Animation verschwindetisRemovedOnCompletion?Auf false setzen, fillMode = .forwards verwenden
Geste + Animation ruckeltSynchronisierte Updates?CADisplayLink verwenden
Mehrere Animationen kollidierenGleicher Schlüssel?Eindeutige Schlüssel oder zuerst removeAnimation() verwenden
Weak Self im HandlerCompletion korrekt erfasst?Immer [weak self] im Completion verwenden

Wenn Sie nach 30 Minuten nicht weiterkommen

Wenn Sie >30 Minuten mit einer immer noch defekten Animation verbracht haben:

STOPPEN. Sie haben entweder

  1. Einen obligatorischen Schritt übersprungen (am häufigsten)
  2. Die Diagnoseausgabe falsch interpretiert
  3. Das falsche Muster für Ihr Symptom angewendet
  4. Befinden sich im 5%-Randfall, der Instruments-Profilierung erfordert

VERPFLICHTENDE Checkliste, bevor Sie behaupten „Skill hat nicht funktioniert“

  • Ich habe ALLE 4 Diagnoseblöcke aus den Obligatorischen ersten Schritten ausgeführt (Zeilen 28-63)
  • Ich habe die GENAUEN Ausgaben der Diagnosen eingefügt (Logs, print-Anweisungen)
  • Ich habe EINE Ursache aus „Was Ihnen das sagt“ identifiziert (Zeilen 66-72)
  • Ich habe das ERSTE passende Muster aus dem Entscheidungsbaum angewendet (Zeilen 91+)
  • Ich habe das Muster auf einem ECHTEN Gerät getestet, nicht nur im Simulator
  • Ich habe die Core Animation Profiling von Instruments ausgeführt (wenn Bildrate vermutet wurde)
  • Ich habe den vollständigen Diagnosecode in meinen Code eingefügt, bevor ich ihn entferne

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.

Verwandte Skills