Communitygithub.com

Débogage d'Animations UIKit

Utilisez cette compétence lorsque le gestionnaire de complétion de CAAnimation ne se déclenche pas, que la physique des ressorts semble incorrecte sur l'appareil, que la durée de l'animation ne correspond pas au temps réel, que l'interaction geste + animation provoque des saccades, ou que le timing diffère entre le simulateur et le matériel réel – diagnostic systématique des animations avec les motifs CATransaction, la connaissance du taux de rafraîchissement et le comportement spécifique à l'appareil.

Qu'est-ce que Débogage d'Animations UIKit ?

Cette compétence fournit une approche structurée pour diagnostiquer et résoudre les problèmes d'animations UIKit (CAAnimation) sur iOS. Elle est conçue pour les développeurs iOS utilisant des agents d'IA comme Claude Code, Cursor ou Codex. La compétence part du principe que 90% des problèmes 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. Elle propose des étapes de diagnostic obligatoires (vérification du gestionnaire de complétion, mesure de la durée réelle, inspection de l'état de l'animation et de la couche), un arbre de décision pour identifier la cause racine, et sept motifs de correction communs allant du réglage du gestionnaire de complétion avant l'ajout de l'animation, à la gestion des différences de rafraîchissement entre simulateur (60 Hz) et appareils réels (120 Hz), en passant par l'adaptation de la physique des ressorts à la classe de performance de l'appareil. L'outillage système recommandé inclut Instruments pour le profilage Core Animation et CADisplayLink pour la synchronisation geste-animation. La compétence met en garde contre les solutions de contournement interdites comme le hardcodage de valeurs spécifiques à un appareil.

Compatible avec✓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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. Si la complétion se déclenche mais que le temps écoulé != durée déclarée → Appliquez le Motif 2 (CATransaction)
  2. Si la complétion ne se déclenche PAS ET isRemovedOnCompletion est vrai → Appliquez le Motif 3
  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

  1. 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
  2. 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)
  3. Ensuite le Motif 3 (isRemovedOnCompletion)

    • Uniquement si l'animation se termine mais que l'état visuel revient en arrière
  4. 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èmeVérifiezCorrectif
La complétion ne se déclenche jamaisDéfinissez le gestionnaire AVANT add()Déplacez completion = avant add()
Inadéquation de duréeY a-t-il une encapsulation CATransaction ?Supprimez CATransaction ou retirez l'animation de celle-ci
Saccades sur appareils anciensLa valeur est-elle codée en dur ?Utilisez ProcessInfo pour la classe d'appareil
L'animation disparaîtisRemovedOnCompletion ?Mettez à false, utilisez fillMode = .forwards
Saccades geste + animationMises à jour synchronisées ?Utilisez CADisplayLink
Conflit d'animations multiplesMême clé ?Utilisez des clés uniques ou removeAnimation() d'abord
Weak self dans le gestionnaireComplé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

  1. Avez sauté une étape obligatoire (le plus courant)
  2. Avez mal interprété la sortie de diagnostic
  3. Avez appliqué le mauvais motif pour votre symptôme
  4. Ê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

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.

Skills associés