Débogage d'Animations UIKit
Aperçu
Les problèmes de CAAnimation se manifestent par des gestionnaires de fin manquants, un timing incorrect ou des à-coups dans des conditions spécifiques. Principe fondamental : 90 % des problèmes de CAAnimation sont dus au timing de CATransaction, à l'état de la couche ou aux hypothèses sur le taux de rafraîchissement, et non à des bogues de Core Animation.
Drapeaux Rouges — Suspecter 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 fin 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 à-coups (fonctionne bien séparément)
[weak self]dans le gestionnaire de fin et vous n'êtes pas sûr de la raison- ❌ INTERDIT : Coder en dur des durées/valeurs pour "correspondre à ce qui se passe réellement"
- Cela introduit des bogues spécifiques à l'appareil chez des utilisateurs avec du matériel différent
- Ne rationalisez pas cela comme une "correction temporaire" ou "assez bonne"
Distinction critique : Le simulateur cache souvent les problèmes de timing (60 Hz uniquement, pas de limitation de performance). Les appareils réels les exposent (taux de rafraîchissement variable, limitation du processeur, pression de l'arrière-plan). OBLIGATOIRE : Tester sur un appareil réel (le modèle le plus ancien pris en charge) avant de publier.
Premières Étapes Obligatoires
Exécutez TOUJOURS ces étapes en premier (avant de modifier le code) :
// 1. Vérifier si le gestionnaire de fin se déclenche
animation.completion = { [weak self] finished in
print("🔥 GESTIONNAIRE DE FIN DÉCLENCHÉ : finished=\(finished)")
guard let self = self else {
print("🔥 SELF ÉTAIT NIL")
return
}
// code original
}
// 2. Vérifier la durée réelle par rapport à la durée 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éelle
}
// 3. Vérifier les animations actives
if let keys = layer.animationKeys() {
print("Animations actives : \(keys)")
for key in keys {
if let anim = layer.animation(forKey: key) {
print("\(key) : durée=\(anim.duration), supprimée=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. Vérifier l'état de la couche
print("Vitesse de la couche : \(layer.speed)") // != 1.0 signifie que le timing est modifié
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 du gestionnaire de fin apparaît → Le gestionnaire se déclenche, le problème est dans le code de rappel
- L'impression du gestionnaire de fin est absente → Le gestionnaire ne se déclenche pas, vérifier CATransaction/état de la couche
- Temps écoulé == durée déclarée → La durée est correcte, les à-coups visuels sont dus aux 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 LE diagnostic unique qui est la cause racine :
- Si le gestionnaire de fin se déclenche mais que le temps écoulé != durée déclarée → Appliquer le Motif 2 (CATransaction)
- Si le gestionnaire de fin ne se déclenche PAS ET isRemovedOnCompletion est vrai → Appliquer le Motif 3
- Si le gestionnaire de fin se déclenche mais que le visuel est saccadé → DOIT profiler avec Instruments en premier
- Vous ne pouvez pas deviner "c'est probablement les trames" - prouvez-le avec des données
- Profiler > Instrument Core Animation montre les chutes 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 manque ?"
- Profiler avec Instruments > Core Animation si vous n'êtes pas sûr
Arbre de Décision
Problème CAAnimation ?
├─ Le gestionnaire de fin 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 l'appareil réel ?
│ │ ├─ Vérifier : isRemovedOnCompletion et fillMode
│ │ ├─ Vérifier : encapsulation CATransaction
│ │ └─ Vérifier : l'application passe en arrière-plan pendant l'animation
│ └─ À la fois sur simulateur et appareil ?
│ ├─ Vérifier : le gestionnaire de fin est défini AVANT d'ajouter l'animation
│ └─ Vérifier : [weak self] est réellement capturé (pas nil avant la fin)
│
├─ Décalage de durée (déclarée != visuelle) ?
│ ├─ layer.speed != 1.0 ?
│ │ └─ Quelque chose a modifié la durée de l'animation. Trouvez et corrigez.
│ ├─ L'animation est encapsulée dans CATransaction ?
│ │ └─ CATransaction.setAnimationDuration() remplace animation.duration
│ └─ La durée visuelle est PLUS LONGUE que la durée déclarée ?
│ └─ Simulateur (60 Hz) vs taux de rafraîchissement de l'appareil (120 Hz). Recalculez pour le matériel réel.
│
├─ Physique du ressort incorrecte sur l'appareil ?
│ ├─ Les valeurs sont codées en dur pour un appareil ?
│ │ └─ Utilisez la classe de performance de l'appareil, pas le modèle
│ ├─ Les paramètres d'amortissement/rigidité sont échangés avec masse/rigidité ?
│ │ └─ Vérifiez la signification des paramètres de CASpringAnimation
│ └─ Fonctionne sur le simulateur mais pas sur l'appareil ?
│ └─ Le simulateur utilise 60 Hz. L'appareil peut utiliser 120 Hz. Recalculez.
│
└─ À-coups geste + animation ?
├─ Les animations sont en compétition (même keyPath) ?
│ └─ Supprimez l'ancienne animation avant d'en ajouter une nouvelle
├─ Le geste met à jour la couche pendant que l'animation s'exécute ?
│ └─ Utilisez CADisplayLink pour des mises à jour synchronisées
└─ Le geste bloque le thread principal ?
└─ Profiler 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 Fin)
- Si le gestionnaire de fin ne se déclenche JAMAIS → Motif 1
- Vérifiez que le gestionnaire de fin est défini AVANT add() avec une instruction print (ligne 33)
- Passez au Motif 2 uniquement si le gestionnaire de fin se DÉCLENCHE mais que le timing est incorrect
-
Puis Motif 2 (Décalage de durée CATransaction)
- Uniquement si le gestionnaire de fin se déclenche mais que le temps écoulé != durée déclarée
- Vérifiez les logs des Premières Étapes Obligatoires (ligne 40-47)
-
Puis 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 Fin
❌ INCORRECT (Gestionnaire défini APRÈS avoir ajouté l'animation)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ Trop tard !
print("Terminé")
}
✅ 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 fin 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éfinir 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 uniformément toutes les animations.
Motif 3 : isRemovedOnCompletion et fillMode
❌ INCORRECT (L'animation disparaît après la fin)
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 à son é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 le Gestionnaire de Fin (OBLIGATOIRE)
❌ INTERDIT (Strong self crée un cycle de rétention)
anim.completion = { finished in
self.property = "valeur" // ❌ Cycle de rétention GARANTI
}
✅ OBLIGATOIRE (Toujours utiliser weak self)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "valeur" // Sécurisé d'accéder
}
Pourquoi c'est OBLIGATOIRE, pas optionnel
- CAAnimation garde le gestionnaire de fin actif jusqu'à la fin de l'animation
- Le gestionnaire de fin capture self fortement (sauf si explicitement weak)
- Crée un cycle de rétention : self → animation → complétion → 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 ça va"
- ❌ "Ce chemin de code ne s'exécute qu'une seule fois"
Utilisez TOUJOURS [weak self] dans les gestionnaires de fin. Aucune exception.
Motif 5 : Animations Multiples (Même keyPath)
❌ INCORRECT (Les animations entrent en conflit)
// Ajouter l'animation 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")
// Plus tard, ajouter l'animation 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide") // ❌ Même clé, remplace anim1 !
✅ CORRECT (Supprimer avant d'ajouter)
layer.removeAnimation(forKey: "slide") // Supprimer d'abord l'ancienne
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. Soit supprimez l'ancienne animation, soit utilisez des clés uniques.
Motif 6 : CADisplayLink pour la Synchronisation Geste + Animation
❌ INCORRECT (Le geste met à jour directement, l'animation met à jour à un taux différent)
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) // À-coups dus à la désynchronisation
✅ CORRECT (Utiliser 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() {
// Mettre à 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 geste et CAAnimation peuvent s'exécuter à des taux de rafraîchissement différents. CADisplayLink synchronise les deux avec le taux de rafraîchissement de l'écran.
Motif 7 : Différences d'Animation Ressort selon l'Appareil
❌ 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 (Adapter à la performance de l'appareil)
let springAnim = CASpringAnimation()
// Utiliser 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 du ressort se sent différente à 60 Hz vs 120 Hz. Utilisez la classe de l'appareil (nombre de cœurs, GPU) pas le modèle.
Tableau de Référence Rapide
| Problème | Vérifier | Corriger |
|---|---|---|
| Le gestionnaire de fin ne se déclenche jamais | Définir le gestionnaire AVANT add() | Déplacer completion = avant add() |
| Décalage de durée | Encapsulation CATransaction ? | Supprimer CATransaction ou retirer l'animation de celle-ci |
| À-coups sur les anciens appareils | Valeur codée en dur ? | Utiliser ProcessInfo pour la classe de l'appareil |
| L'animation disparaît | isRemovedOnCompletion ? | Définir sur false, utiliser fillMode = .forwards |
| À-coups geste + animation | Mises à jour synchronisées ? | Utiliser CADisplayLink |
| Conflit d'animations multiples | Même clé ? | Utiliser des clés uniques ou removeAnimation() d'abord |
| Weak self dans le gestionnaire | Gestionnaire de fin capturé correctement ? | Toujours utiliser [weak self] dans le gestionnaire de fin |
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 avec Instruments
Checklist OBLIGATOIRE avant de prétendre "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
- J'ai vérifié le motif avec des instructions print/logs montrant que la correction fonctionne
Si TOUTES les cases sont cochées et toujours cassé
- Vous DEVEZ profiler avec Instruments > Core Animation
- Coût en temps : 30 à 60 minutes (inévitable pour les cas limites)
- Coder en dur, asyncAfter, ou "publier et espérer" sont INTERDITS
- Demandez des conseils avant d'ajouter des solutions de contournement
Transparence du coût en temps
- Motif 1 : 2-5 min
… [le reste du contenu est tronqué pour la traduction]