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:
- Wenn der Completion feuert, aber die verstrichene Zeit != deklarierte Dauer ist → Muster 2 anwenden (CATransaction)
- Wenn der Completion NICHT feuert UND isRemovedOnCompletion true ist → Muster 3 anwenden
- 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
-
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
-
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)
-
Dann Muster 3 (isRemovedOnCompletion)
- Nur wenn die Animation abgeschlossen ist, aber der visuelle Zustand zurückgesetzt wird
-
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
| Problem | Prüfen | Behebung |
|---|---|---|
| Completion feuert nie | Handler VOR add() setzen | completion = vor add() verschieben |
| Dauerabweichung | CATransaction-Umhüllung? | CATransaction entfernen oder Animation daraus entfernen |
| Ruckeln auf älteren Geräten | Wert hartkodiert? | ProcessInfo für Geräteklasse verwenden |
| Animation verschwindet | isRemovedOnCompletion? | Auf false setzen, fillMode = .forwards verwenden |
| Geste + Animation ruckelt | Synchronisierte Updates? | CADisplayLink verwenden |
| Mehrere Animationen kollidieren | Gleicher Schlüssel? | Eindeutige Schlüssel oder zuerst removeAnimation() verwenden |
| Weak Self im Handler | Completion 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
- Einen obligatorischen Schritt übersprungen (am häufigsten)
- Die Diagnoseausgabe falsch interpretiert
- Das falsche Muster für Ihr Symptom angewendet
- 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