Que fait Débogage d'Animations UIKit ?
Aperçu
Les problèmes de CAAnimation se manifestent par des gestionnaires de complétion manquants, un timing incorrect ou des saccades dans des conditions spécifiques. Principe fondamental : 90% des problèmes de CAAnimation proviennent de la synchronisation CATransaction, de l'état des couches ou d'hypothèses sur le taux de rafraîchissement, et non de bugs dans Core Animation.
Drapeaux Rouges — Suspectez un Problème CAAnimation
Si vous voyez L'UN de ces signes, suspectez la logique d'animation, pas le comportement de l'appareil :
- Le gestionnaire de complétion se déclenche sur le simulateur mais pas sur l'appareil
- La durée de l'animation (0,5 s) ne correspond pas à la durée visuelle (1,2 s)
- L'animation ressort semble correcte sur iPhone 15 Pro mais saccadée sur des appareils plus anciens
- Geste + animation ensemble provoquent des saccades (séparément, ça va)
[weak self]dans le gestionnaire de complétion et vous n'êtes pas sûr de la raison- ❌ INTERDIT de coder en dur la durée/les valeurs pour "correspondre à ce qui se passe réellement"
- Cela expédie des bugs spécifiques à un appareil aux utilisateurs sur du matériel différent
- Ne rationalisez pas cela comme un "correctif temporaire" ou "assez bien"
Distinction cruciale : Le simulateur cache souvent les problèmes de timing (uniquement 60 Hz, pas de throttling). Les vrais appareils les exposent (taux de rafraîchissement variable, throttling CPU, pression d'arrière-plan). OBLIGATOIRE : Testez sur un appareil réel (le modèle le plus ancien pris en charge) avant de livrer.
Premières Étapes Obligatoires
Exécutez TOUJOURS ces étapes D'ABORD (avant de modifier le code) :
// 1. Vérifiez si la complétion se déclenche
animation.completion = { [weak self] finished in
print("🔥 COMPLETION DÉCLENCHÉE : finished=\(finished)")
guard let self = self else {
print("🔥 SELF ÉTAIT NIL")
return
}
// code original
}
// 2. Vérifiez la durée réelle vs déclarée
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5 // Déclarée
layer.add(anim, forKey: "test")
DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
print("Temps écoulé : \(Date().timeIntervalSince(startTime))") // Réel
}
// 3. Vérifiez quelles animations sont actives
if let keys = layer.animationKeys() {
print("Animations actives : \(keys)")
for key in keys {
if let anim = layer.animation(forKey: key) {
print("\(key) : duration=\(anim.duration), removed=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. Vérifiez l'état de la couche
print("Vitesse de la couche : \(layer.speed)") // != 1.0 signifie que le timing est mis à l'échelle
print("Décalage temporel de la couche : \(layer.timeOffset)") // != 0 signifie que l'animation est décalée
Ce que cela vous indique
- L'impression de complétion apparaît → Le gestionnaire se déclenche, le problème est dans le code de rappel
- L'impression de complétion manque → Le gestionnaire ne se déclenche pas, vérifiez l'état CATransaction/couche
- Temps écoulé == durée déclarée → La durée est correcte, les saccades visuelles proviennent des trames
- Temps écoulé != durée déclarée → L'encapsulation CATransaction modifie la durée
- layer.speed != 1.0 → Quelque chose ralentit l'animation
- La liste des animations actives est longue → Plusieurs animations en compétition
INTERPRÉTATION OBLIGATOIRE
Avant de modifier DU CODE, vous devez identifier QUEL diagnostic est la cause racine :
- Si la complétion se déclenche mais que le temps écoulé != durée déclarée → Appliquez le Motif 2 (CATransaction)
- Si la complétion ne se déclenche PAS ET isRemovedOnCompletion est vrai → Appliquez le Motif 3
- Si la complétion se déclenche mais que le visuel est saccadé → DEVEZ profiler avec Instruments d'abord
- Vous ne pouvez pas deviner "c'est probablement les trames" - prouvez-le avec des données
- Profile > Instrument Core Animation montre les pertes de trames avec certitude
- Si vous sautez Instruments, vous devinez
Si les diagnostics sont contradictoires ou peu clairs
- ARRÊTEZ. Ne passez PAS encore aux motifs
- Ajoutez plus d'instructions print pour cerner la cause
- Demandez : "Les diagnostics montrent X et Y mais Z ne correspond pas. Qu'est-ce que je rate ?"
- Profil avec Instruments > Core Animation si incertain
Arbre de Décision
Problème CAAnimation ?
├─ Le gestionnaire de complétion ne se déclenche jamais ?
│ ├─ Uniquement sur le simulateur ?
│ │ └─ Le timing du simulateur est différent (60 Hz). Testez sur un appareil réel.
│ ├─ Uniquement sur un appareil réel ?
│ │ ├─ Vérifiez : isRemovedOnCompletion et fillMode
│ │ ├─ Vérifiez : encapsulation CATransaction
│ │ └─ Vérifiez : l'application passe en arrière-plan pendant l'animation
│ └─ Sur le simulateur et l'appareil ?
│ ├─ Vérifiez : le gestionnaire de complétion est défini AVANT d'ajouter l'animation
│ └─ Vérifiez : [weak self] est réellement capturé (pas nil avant la complétion)
│
├─ Inadéquation de durée (déclarée != visuelle) ?
│ ├─ Est-ce que layer.speed != 1.0 ?
│ │ └─ Quelque chose a mis à l'échelle la durée de l'animation. Trouvez et corrigez.
│ ├─ L'animation est-elle encapsulée dans CATransaction ?
│ │ └─ CATransaction.setAnimationDuration() remplace animation.duration
│ └─ La durée visuelle est-elle PLUS LONGUE que déclarée ?
│ └─ Simulateur (60 Hz) vs taux de rafraîchissement de l'appareil (120 Hz). Recalculez pour le matériel réel.
│
├─ La physique des ressorts est incorrecte sur l'appareil ?
│ ├─ Les valeurs sont-elles codées en dur pour un seul appareil ?
│ │ └─ Utilisez la classe de performance de l'appareil, pas le modèle
│ ├─ Les valeurs d'amortissement/raideur sont-elles échangées avec masse/raideur ?
│ │ └─ Vérifiez les significations des paramètres CASpringAnimation
│ └─ Cela fonctionne-t-il sur le simulateur mais pas sur l'appareil ?
│ └─ Le simulateur utilise 60 Hz. L'appareil peut utiliser 120 Hz. Recalculez.
│
└─ Saccades geste + animation ?
├─ Des animations sont-elles en compétition (même keyPath) ?
│ └─ Supprimez l'ancienne animation avant d'en ajouter une nouvelle
├─ Le geste met-il à jour la couche pendant que l'animation s'exécute ?
│ └─ Utilisez CADisplayLink pour des mises à jour synchronisées
└─ Le geste bloque-t-il le thread principal ?
└─ Profilez avec Instruments > Core Animation
Motifs Courants
Règles de Sélection des Motifs (OBLIGATOIRE)
Appliquez UN motif à la fois, dans cet ordre
-
Commencez toujours par le Motif 1 (Bases du Gestionnaire de Complétion)
- Si la complétion ne se déclenche JAMAIS → Motif 1
- Vérifiez que la complétion est définie AVANT add() avec une instruction print (ligne 33)
- Passez au Motif 2 UNIQUEMENT si la complétion se DÉCLENCHE mais que le timing est incorrect
-
Ensuite le Motif 2 (Inadéquation de durée CATransaction)
- Uniquement si la complétion se déclenche mais que le temps écoulé != durée déclarée
- Vérifiez les logs des Premières Étapes Obligatoires (lignes 40-47)
-
Ensuite le Motif 3 (isRemovedOnCompletion)
- Uniquement si l'animation se termine mais que l'état visuel revient en arrière
-
Motifs 4-7 Appliquez en fonction du symptôme spécifique (voir Arbre de Décision ligne 91+)
INTERDIT
- ❌ Appliquer plusieurs motifs à la fois ("laissez-moi essayer le Motif 2 ET le Motif 4 ensemble")
- ❌ Sauter le Motif 1 parce que "je sais déjà que ce n'est pas ça"
- ❌ Combiner des motifs sans comprendre pourquoi chacun est nécessaire
- ❌ Essayer des motifs au hasard en espérant que l'un fonctionne
Motif 1 : Bases du Gestionnaire de Complétion
❌ INCORRECT (Gestionnaire défini APRÈS avoir ajouté l'animation)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ Trop tard !
print("Fait")
}
✅ CORRECT (Gestionnaire défini AVANT d'ajouter)
animation.completion = { [weak self] finished in
print("🔥 Animation terminée : \(finished)")
guard let self = self else { return }
self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")
Pourquoi Le gestionnaire de complétion doit être défini avant que l'animation ne soit ajoutée à la couche. Le définir après ne fait rien.
Motif 2 : CATransaction vs animation.duration
❌ INCORRECT (CATransaction remplace la durée de l'animation)
CATransaction.begin()
CATransaction.setAnimationDuration(2.0) // ❌ Remplace toutes les animations !
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5 // Ceci est ignoré
layer.add(anim, forKey: nil)
CATransaction.commit() // L'animation prend 2,0 secondes, pas 0,5
✅ CORRECT (Définissez la durée sur l'animation, pas sur la transaction)
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Pas d'encapsulation CATransaction
Pourquoi CATransaction.setAnimationDuration() affecte TOUTES les animations dans le bloc de transaction. Utilisez-le uniquement si vous souhaitez modifier toutes les animations uniformément.
Motif 3 : isRemovedOnCompletion & fillMode
❌ INCORRECT (L'animation disparaît après la complétion)
let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Après 0,5 s, l'animation est supprimée ET la couche revient à l'état d'origine
✅ CORRECT (Conserver l'état de l'animation)
anim.isRemovedOnCompletion = false
anim.fillMode = .forwards // Conserver l'état final après l'animation
layer.add(anim, forKey: nil)
// Après 0,5 s, l'état de l'animation est préservé
Pourquoi Par défaut, les animations sont supprimées et la couche revient en arrière. Pour les changements d'état permanents, définissez isRemovedOnCompletion = false et fillMode = .forwards.
Motif 4 : Weak Self dans la Complétion (OBLIGATOIRE)
❌ INTERDIT (Strong self crée un cycle de rétention)
anim.completion = { finished in
self.property = "valeur" // ❌ Cycle de rétention GARANTI
}
✅ OBLIGATOIRE (Utilisez toujours weak self)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "valeur" // Accès sûr
}
Pourquoi c'est OBLIGATOIRE, pas optionnel
- CAAnimation garde le gestionnaire de complétion en vie jusqu'à la fin de l'animation
- Le gestionnaire de complétion capture self fortement (sauf si explicitement weak)
- Crée un cycle de rétention : self → animation → completion → self
- La fuite mémoire se produit même si l'animation est de courte durée (0,3 s ne l'empêche pas)
Rationalisations INTERDITES
- ❌ "L'animation est courte, donc pas de risque de cycle de rétention"
- ❌ "Je vais supprimer l'animation manuellement, donc c'est bon"
- ❌ "Ce chemin de code ne s'exécute qu'une seule fois"
Utilisez TOUJOURS [weak self] dans les gestionnaires de complétion. Aucune exception.
Motif 5 : Animations Multiples (Même keyPath)
❌ INCORRECT (Conflit d'animations)
// Ajout de l'animation 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")
// Plus tard, ajout de l'animation 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide") // ❌ Même clé, remplace anim1 !
✅ CORRECT (Supprimez avant d'ajouter)
layer.removeAnimation(forKey: "slide") // Supprimez l'ancienne d'abord
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")
Ou utilisez des clés uniques :
let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")
let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2") // Clé différente
Pourquoi Ajouter une animation avec la même clé remplace l'animation précédente. Supprimez l'ancienne animation ou utilisez des clés uniques.
Motif 6 : CADisplayLink pour la Synchronisation Geste + Animation
❌ INCORRECT (Le geste met directement à jour, l'animation met à jour à une fréquence différente)
func handlePan(_ gesture: UIPanGestureRecognizer) {
let translation = gesture.translation(in: view)
view.layer.position.x = translation.x // ❌ Problème de synchronisation
}
// Séparément :
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil) // Saccades dues à la désynchronisation
✅ CORRECT (Utilisez CADisplayLink pour la synchronisation)
var displayLink: CADisplayLink?
func startSyncedAnimation() {
displayLink = CADisplayLink(
target: self,
selector: #selector(updateAnimation)
)
displayLink?.add(to: .main, forMode: .common)
}
@objc func updateAnimation() {
// Mettez à jour le geste ET l'animation dans la même trame
let gesture = currentGesture
let position = calculatePosition(from: gesture)
layer.position = position // Mise à jour synchronisée
}
Pourquoi Le reconnaisseur de gestes et CAAnimation peuvent s'exécuter à des fréquences d'images différentes. CADisplayLink synchronise les deux avec la fréquence de rafraîchissement de l'écran.
Motif 7 : Différences d'Animation Ressort entre Appareils
❌ INCORRECT (Codé en dur pour un appareil)
let springAnim = CASpringAnimation()
springAnim.damping = 0.7 // Codé en dur pour iPhone 15 Pro
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil) // Saccadé sur iPhone 12
✅ CORRECT (Adaptez à la performance de l'appareil)
let springAnim = CASpringAnimation()
// Utilisez la classe de performance de l'appareil, pas le modèle
if ProcessInfo.processInfo.processorCount >= 6 {
// Série A moderne (A14+)
springAnim.damping = 0.7
springAnim.stiffness = 100
} else {
// Série A plus ancienne
springAnim.damping = 0.85
springAnim.stiffness = 80
}
layer.add(springAnim, forKey: nil)
Pourquoi La physique des ressorts est ressentie différemment à 60 Hz vs 120 Hz. Utilisez la classe d'appareil (nombre de cœurs, GPU) pas le modèle.
Tableau de Référence Rapide
| Problème | Vérifiez | Correctif |
|---|---|---|
| La complétion ne se déclenche jamais | Définissez le gestionnaire AVANT add() | Déplacez completion = avant add() |
| Inadéquation de durée | Y a-t-il une encapsulation CATransaction ? | Supprimez CATransaction ou retirez l'animation de celle-ci |
| Saccades sur appareils anciens | La valeur est-elle codée en dur ? | Utilisez ProcessInfo pour la classe d'appareil |
| L'animation disparaît | isRemovedOnCompletion ? | Mettez à false, utilisez fillMode = .forwards |
| Saccades geste + animation | Mises à jour synchronisées ? | Utilisez CADisplayLink |
| Conflit d'animations multiples | Même clé ? | Utilisez des clés uniques ou removeAnimation() d'abord |
| Weak self dans le gestionnaire | Complétion capturée correctement ? | Utilisez toujours [weak self] dans la complétion |
Quand Vous Êtes Bloqué Après 30 Minutes
Si vous avez passé >30 minutes et que l'animation est toujours cassée :
ARRÊTEZ. Soit vous
- Avez sauté une étape obligatoire (le plus courant)
- Avez mal interprété la sortie de diagnostic
- Avez appliqué le mauvais motif pour votre symptôme
- Êtes dans le cas limite de 5 % nécessitant un profilage Instruments
Liste de vérification OBLIGATOIRE avant de prétendre que "la compétence n'a pas fonctionné"
- J'ai exécuté TOUS les 4 blocs de diagnostic des Premières Étapes Obligatoires (lignes 28-63)
- J'ai collé la sortie EXACTE des diagnostics (logs, instructions print)
- J'ai identifié UNE cause racine à partir de "Ce que cela vous indique" (lignes 66-72)
- J'ai appliqué le PREMIER motif correspondant de l'Arbre de Décision (lignes 91+)
- J'ai testé le motif sur un APPAREIL RÉEL, pas seulement le simulateur