Was macht UIKit Animations-Debugging?
Überblick
CAAnimation-Probleme zeigen sich als fehlende completionHandler, falsche Timing-Werte oder Ruckler unter bestimmten Bedingungen. Kernprinzip: 90 % der CAAnimation-Probleme liegen an CATransaction-Timing, Layer-Zustand oder Annahmen zur Bildwiederholrate, nicht an Fehlern im Core Animation-Framework.
Warnsignale – CAAnimation-Problem vermuten
Wenn SIE IRGENDEINES dieser Signale sehen, vermuten Sie Animationslogik, nicht Geräteverhalten:
- completionHandler feuert im Simulator, aber nicht auf dem Gerät
- Animationsdauer (0,5 s) stimmt nicht mit der visuellen Dauer (1,2 s) überein
- Federanimation sieht auf dem iPhone 15 Pro korrekt aus, ruckelt aber auf älteren Geräten
- Gesten und Animationen zusammen verursachen Stottern (einzeln einwandfrei)
[weak self]im completionHandler und Sie sind sich nicht sicher, warum- ❌ VERBOTEN Dauer/Werte hartzucodieren, „damit sie dem tatsächlichen Verhalten entsprechen“
- Dies bringt gerätespezifische Fehler auf Geräte anderer Benutzer:innen
- Rechtfertigen Sie dies nicht als „vorübergehende Lösung“ oder „gut genug“
Wichtiger Unterschied: Der Simulator verbirgt oft Timing-Probleme (nur 60 Hz, keine Drosselung). Echte Geräte legen sie offen (variable Bildwiederholrate, CPU-Drosselung, Hintergrunddruck). PFLICHT: Vor dem Ausliefern auf einem echten Gerät (dem ältesten unterstützten Modell) testen.
Zwingende Erste Schritte
Führen Sie diese IMMER ZUERST aus (bevor Sie Code ändern):
// 1. Prüfen, ob completion überhaupt feuert
animation.completion = { [weak self] finished in
print("🔥 COMPLETION AUSGELÖST: finished=\(finished)")
guard let self = self else {
print("🔥 SELF WAR NIL")
return
}
// Originalcode
}
// 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-Zustand prüfen
print("Layer-Geschwindigkeit: \(layer.speed)") // != 1.0 bedeutet, Timing wird skaliert
print("Layer-Zeitversatz: \(layer.timeOffset)") // != 0 bedeutet, Animation ist versetzt
Was Ihnen das sagt
- Ausgabe von completion erscheint → Handler feuert, Problem liegt im Callback-Code
- Ausgabe von completion fehlt → Handler feuert nicht, CATransaction/Layer-Zustand prüfen
- Verstrichene Zeit == deklariert → Dauer korrekt, visuelles Ruckeln kommt von Frames
- Verstrichene Zeit != deklariert → CATransaction-Umschließung ändert die Dauer
- layer.speed != 1.0 → Etwas verlangsamt die Animation
- Liste aktiver Animationen ist lang → Mehrere Animationen konkurrieren
PFLICHT: Interpretation
Bevor Sie IRGENDEINEN Code ändern, müssen Sie identifizieren, WELCHE EINE Diagnose die Ursache ist:
- Wenn completion feuert, aber verstrichene Zeit != deklarierte Dauer → Wende Muster 2 (CATransaction) an
- Wenn completion NICHT feuert UND isRemovedOnCompletion wahr ist → Wende Muster 3 an
- Wenn completion feuert, aber die Darstellung ruckelt → MUSS zuerst mit Instruments profiliert werden
- Sie können nicht raten: „Es sind wahrscheinlich Frames“ – beweisen Sie es mit Daten
- Profiling > Core Animation-Instrument zeigt Frame-Einbrüche mit Sicherheit
- Wenn Sie Instruments überspringen, raten Sie nur
Wenn Diagnosen widersprüchlich oder unklar sind
- STOPP. Fahren Sie noch NICHT mit 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?
├─ completionHandler feuert nie?
│ ├─ Nur auf Simulator?
│ │ └─ Simulator-Timing ist anders (60 Hz). Auf echtem Gerät testen.
│ ├─ Nur auf echtem Gerät?
│ │ ├─ Prüfen: isRemovedOnCompletion und fillMode
│ │ ├─ Prüfen: CATransaction-Umschließung
│ │ └─ Prüfen: App geht während der Animation in den Hintergrund
│ └─ Auf Simulator UND Gerät?
│ ├─ Prüfen: completionHandler 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 verpackt?
│ │ └─ CATransaction.setAnimationDuration() überschreibt animation.duration
│ └─ Ist die visuelle Dauer LÄNGER als deklariert?
│ └─ Simulator (60 Hz) vs. Geräte-Bildwiederholrate (120 Hz). Für echte Hardware neu berechnen.
│
├─ Federphysik auf dem Gerät falsch?
│ ├─ Sind Werte für ein Gerät hartcodiert?
│ │ └─ Geräteleistungsklasse verwenden, nicht Modell
│ ├─ Sind Parameter für Dämpfung/Steifigkeit mit Masse/Steifigkeit vertauscht?
│ │ └─ CASpringAnimation-Parameterbedeutungen prüfen
│ └─ Funktioniert es auf dem Simulator, aber nicht auf dem Gerät?
│ └─ Simulator verwendet 60 Hz. Gerät verwendet möglicherweise 120 Hz. Neu berechnen.
│
└─ Gesten + Animations-Ruckeln?
├─ Konkurrieren Animationen (gleicher keyPath)?
│ └─ Alte Animation entfernen, bevor neue hinzugefügt wird
├─ Aktualisiert die Geste den Layer, während die Animation läuft?
│ └─ CADisplayLink für synchronisierte Aktualisierungen verwenden
└─ Blockiert die Geste den Haupt-Thread?
└─ Mit Instruments > Core Animation profilieren
Häufige Muster
Regeln zur Musterauswahl (PFLICHT)
Wenden Sie IMMER EIN Muster nach dem anderen in dieser Reihenfolge an
-
Beginnen Sie immer mit Muster 1 (Completion Handler Grundlagen)
- Wenn completion NIE feuert → Muster 1
- Überprüfen Sie mit print-Anweisung (Zeile 33), ob completion VOR add() gesetzt ist
- Fahren Sie nur mit Muster 2 fort, wenn completion FEUERT, aber das Timing falsch ist
-
Dann Muster 2 (CATransaction-Dauerabweichung)
- Nur wenn completion feuert, aber verstrichene Zeit != deklarierte Dauer
- Logs aus den Zwingenden Ersten Schritten (Zeile 40-47) prüfen
-
Dann Muster 3 (isRemovedOnCompletion)
- Nur wenn Animation abgeschlossen ist, aber der visuelle Zustand zurückgesetzt wird
-
Muster 4-7 Basierend auf dem spezifischen Symptom anwenden (siehe Entscheidungsbaum Zeile 91+)
VERBOTEN
- ❌ Mehrere Muster gleichzeitig anwenden („Lass mich Muster 2 UND Muster 4 zusammen ausprobieren“)
- ❌ Muster 1 überspringen, weil „ich weiß bereits, 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 completionHandler muss gesetzt sein, bevor die Animation zum Layer hinzugefügt wird. Ein nachträgliches Setzen bewirkt nichts.
Muster 2: CATransaction vs. animation.duration
❌ FALSCH (CATransaction überschreibt 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 auf der Animation setzen, nicht auf der Transaktion)
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Keine CATransaction-Umschließung
Warum CATransaction.setAnimationDuration() wirkt sich auf ALLE Animationen im Transaktionsblock aus. 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,5 s 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,5 s 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 (PFLICHT)
❌ VERBOTEN (starkes Self erzeugt Retain-Zyklus)
anim.completion = { finished in
self.property = "value" // ❌ GARANTIERT Retain-Zyklus
}
✅ PFLICHT (Immer weak self verwenden)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "value" // Sicherer Zugriff
}
Warum dies PFLICHT und nicht optional ist
- CAAnimation hält den completionHandler am Leben, bis die Animation abgeschlossen ist
- completionHandler erfasst self stark (außer explizit weak gesetzt)
- Erzeugt Retain-Zyklus: self → animation → completion → self
- Speicherleck tritt auch bei kurzlebigen Animationen auf (0,3 s verhindern es nicht)
VERBOTENE Rechtfertigungen
- ❌ „Animation ist kurz, also kein Risiko für Retain-Zyklus“
- ❌ „Ich entferne die Animation manuell, also ist es in Ordnung“
- ❌ „Dieser Codepfad wird nur einmal ausgeführt“
Verwenden Sie IMMER [weak self] in completionHandlern. Keine Ausnahmen.
Muster 5: Mehrere Animationen (Gleicher keyPath)
❌ FALSCH (Animationen konkurrieren)
// 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 Key, ersetzt anim1!
✅ RICHTIG (Vorher entfernen)
layer.removeAnimation(forKey: "slide") // Zuerst alte entfernen
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")
Oder eindeutige Keys 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 Key
Warum Das Hinzufügen einer Animation mit demselben Key ersetzt die vorherige Animation. Entweder alte Animation entfernen oder eindeutige Keys verwenden.
Muster 6: CADisplayLink für Gesten- + Animationssynchronisation
❌ FALSCH (Geste direkt aktualisieren, Animation 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 Bildwiederholraten laufen. CADisplayLink synchronisiert beide mit der Bildschirmaktualisierungsrate.
Muster 7: Federanimation – Geräteunterschiede
❌ FALSCH (Für ein Gerät hartcodiert)
let springAnim = CASpringAnimation()
springAnim.damping = 0.7 // Für iPhone 15 Pro hartcodiert
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 Federphysik fühlt sich bei 60 Hz anders an als bei 120 Hz. Geräteklasse (Kernanzahl, GPU) verwenden, nicht Modell.
Kurzreferenztabelle
| Problem | Prüfung | Lösung |
|---|---|---|
| completion feuert nie | Setze Handler VOR add() | completion = vor add() verschieben |
| Dauerabweichung | Ist CATransaction-Umschließung vorhanden? | CATransaction entfernen oder Animation daraus lösen |
| Ruckeln auf älteren Geräten | Ist Wert hartcodiert? | ProcessInfo für Geräteklasse verwenden |
| Animation verschwindet | isRemovedOnCompletion? | Auf false setzen, fillMode = .forwards verwenden |
| Gesten + Animationsruckeln | Synchronisierte Aktualisierungen? | CADisplayLink verwenden |
| Mehrere Animationen konkurrieren | Gleicher Key? | Eindeutige Keys oder removeAnimation() zuerst |
| Weak Self im Handler | Wird completion korrekt erfasst? | Immer [weak self] in completion verwenden |
Wenn Sie nach 30 Minuten nicht weiterkommen
Wenn Sie >30 Minuten verbracht haben und die Animation immer noch nicht funktioniert:
STOPP. Entweder haben Sie
- Einen zwingenden Schritt übersprungen (am häufigsten)
- Die Diagnoseausgabe falsch interpretiert
- Das falsche Muster für Ihr Symptom angewendet
- Sind im 5 %-Randfall, der Instruments-Profiling erfordert
PFLICHT-Checkliste, bevor Sie behaupten „Skill hat nicht funktioniert"
- Ich habe ALLE 4 Diagnoseblöcke aus den Zwingenden Ersten Schritten (Zeilen 28-63) ausgeführt
- Ich habe die GENAUEN Ausgaben der Diagnosen eingefügt (Logs, print-Anweisungen)
- Ich habe EINE Ursache aus „Was Ihnen das sagt“ (Zeilen 66-72) identifiziert
- Ich habe das ERSTE passende Muster aus dem Entscheidungsbaum (Zeilen 91+) angewendet
- Ich habe das Muster auf einem ECHTEN GERÄT getestet, nicht nur auf dem Simulator
- Ich habe das Muster mit print-Anweisungen/Logs verifiziert, die die Funktionsfähigkeit der Korrektur zeigen
Wenn ALLE Kästchen angekreuzt sind und es immer noch nicht funktioniert
- Sie MÜSSEN mit Instruments > Core Animation profilieren
- Zeitaufwand: 30-60 Minuten (für Randfälle unvermeidbar)
- Hartcodieren,
asyncAfteroder „Ausliefern und hoffen“ sind VERBOTEN - Bitten Sie um Rat, bevor Sie Workarounds hinzufügen
Transparenz zum Zeitaufwand
- Muster 1: 2-5 min
…
[gekürzt für die Übersetzung]