Communitygithub.com

Depuración de Animaciones UIKit

Úsalo cuando el manejador de finalización de CAAnimation no se ejecuta, la física de resortes se ve mal en el dispositivo, la duración de la animación no coincide con el tiempo real, la interacción gesto + animación causa tirones, o el tiempo difiere entre el simulador y el hardware real: diagnóstico sistemático de CAAnimation con patrones de CATransaction, conciencia de la tasa de fotogramas y comportamiento específico del dispositivo.

¿Qué es Depuración de Animaciones UIKit?

Esta habilidad proporciona un enfoque sistemático y basado en reglas para diagnosticar y solucionar problemas comunes de CAAnimation en UIKit. Es especialmente útil cuando los manejadores de finalización no se activan en dispositivos físicos, las duraciones de animación declaradas no coinciden con la duración visual, la física de resortes se comporta de manera diferente en hardware diverso, o la interacción gesto + animación causa tirones. La habilidad enfatiza que la mayoría de los problemas de CAAnimation se deben a problemas de temporización de CATransaction, estado de capa o suposiciones sobre la tasa de fotogramas, no a errores de Core Animation. Requiere ejecutar pasos de diagnóstico obligatorios antes de cualquier cambio de código, incluyendo verificar la activación del manejador de finalización, la duración real de la animación, las animaciones activas en la capa y propiedades de temporización de la capa como `speed` y `timeOffset`. Un árbol de decisión estructurado guía la aplicación de uno de los siete patrones comunes (Manejador de Finalización, Transacción CAT, isRemovedOnCompletion, Weak Self, Animaciones Múltiples, CADisplayLink y Diferencias de Dispositivo en Resortes), con estrictas reglas para aplicar un patrón a la vez y en un orden específico. La habilidad prohíbe soluciones improvisadas como codificar duraciones o aplicar múltiples patrones simultáneamente, y exige pruebas en dispositivos reales (el modelo compatible más antiguo) antes de enviar el código.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Depuración de Animaciones UIKit?

Resumen

Los problemas de CAAnimation se manifiestan como manejadores de finalización faltantes, temporización incorrecta o tirones bajo condiciones específicas. Principio fundamental: el 90% de los problemas de CAAnimation se deben a la temporización de CATransaction, el estado de la capa o suposiciones sobre la tasa de fotogramas, no a errores de Core Animation.

Señales de Alerta — Sospechar Problema de CAAnimation

Si ves CUALQUIERA de estos, sospecha lógica de animación, no comportamiento del dispositivo:

  • El manejador de finalización se activa en el simulador pero no en el dispositivo
  • La duración de la animación (0,5 s) no coincide con la duración visual (1,2 s)
  • La animación de resorte se ve correcta en iPhone 15 Pro pero con tirones en dispositivos antiguos
  • Gesto + animación juntos causan tartamudeo (bien por separado)
  • [weak self] en el manejador de finalización y no estás seguro de por qué
  • ❌ PROHIBIDO Codificar duraciones/valores para "coincidir con lo que realmente sucede"
    • Esto envía errores específicos del dispositivo a usuarios con hardware diferente
    • No racionalices esto como una "solución temporal" o "suficientemente buena"

Distinción crítica: El simulador a menudo oculta problemas de temporización (solo 60 Hz, sin limitación). Los dispositivos reales los exponen (tasa de fotogramas variable, limitación de CPU, presión de fondo). OBLIGATORIO: Probar en dispositivo real (el modelo compatible más antiguo) antes de enviar.

Pasos Obligatorios Iniciales

SIEMPRE ejecuta estos PRIMERO (antes de cambiar código):

// 1. Verificar si la finalización se está activando
animation.completion = { [weak self] finished in
    print("🔥 FINALIZACIÓN ACTIVADA: finalizada=\(finished)")
    guard let self = self else {
        print("🔥 SELF ERA NIL")
        return
    }
    // código original
}

// 2. Verificar la duración real vs la declarada
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5  // Declarada
layer.add(anim, forKey: "test")

DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
    print("Tiempo transcurrido: \(Date().timeIntervalSince(startTime))")  // Real
}

// 3. Verificar qué animaciones están activas
if let keys = layer.animationKeys() {
    print("Animaciones activas: \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key): duración=\(anim.duration), removida=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. Verificar estado de la capa
print("Velocidad de capa: \(layer.speed)")  // != 1.0 significa que la temporización está escalada
print("Desplazamiento temporal de capa: \(layer.timeOffset)")  // != 0 significa que la animación está desplazada

Qué te dice esto

  • Aparece print de finalización → El manejador se activa, el problema está en el código de callback
  • Falta print de finalización → El manejador no se activa, verificar CATransaction/estado de la capa
  • Tiempo transcurrido == declarado → La duración es correcta, el tirón visual es por fotogramas
  • Tiempo transcurrido != declarado → El envoltorio CATransaction está cambiando la duración
  • layer.speed != 1.0 → Algo está ralentizando la animación
  • Lista de animaciones activas larga → Múltiples animaciones compitiendo

INTERPRETACIÓN OBLIGATORIA

Antes de cambiar CUALQUIER código, debes identificar CUÁL diagnóstico es la causa raíz:

  1. Si la finalización se activa pero el tiempo transcurrido != duración declarada → Aplicar Patrón 2 (CATransaction)
  2. Si la finalización no se activa Y isRemovedOnCompletion es verdadero → Aplicar Patrón 3
  3. Si la finalización se activa pero lo visual tiene tirones → DEBES perfilar con Instruments primero
    • No puedes adivinar "probablemente son fotogramas" - pruébalo con datos
    • Perfil > Instrumento Core Animation muestra caídas de fotogramas con certeza
    • Si omites Instruments, estás adivinando

Si los diagnósticos son contradictorios o poco claros

  • DETENTE. NO procedas a los patrones todavía
  • Agrega más sentencias print para reducir la causa
  • Pregunta: "Los diagnósticos muestran X e Y pero Z no coincide. ¿Qué me estoy perdiendo?"
  • Perfila con Instruments > Core Animation si no estás seguro

Árbol de Decisión

¿Problema de CAAnimation?
├─ ¿El manejador de finalización nunca se activa?
│  ├─ ¿Solo en el simulador?
│  │  └─ La temporización del simulador es diferente (60 Hz). Prueba en dispositivo real.
│  ├─ ¿Solo en dispositivo real?
│  │  ├─ Verificar: isRemovedOnCompletion y fillMode
│  │  ├─ Verificar: envoltorio CATransaction
│  │  └─ Verificar: la aplicación va al fondo durante la animación
│  └─ ¿En simulador y dispositivo?
│     ├─ Verificar: el manejador de finalización se establece ANTES de agregar animación
│     └─ Verificar: [weak self] realmente se captura (no nil antes de la finalización)
│
├─ ¿Desajuste de duración (declarada != visual)?
│  ├─ ¿layer.speed != 1.0?
│  │  └─ Algo escaló la duración de la animación. Encuéntralo y arréglalo.
│  ├─ ¿La animación está envuelta en CATransaction?
│  │  └─ CATransaction.setAnimationDuration() anula animation.duration
│  └─ ¿La duración visual es MAYOR que la declarada?
│     └─ Simulador (60 Hz) vs tasa de fotogramas del dispositivo (120 Hz). Recalcula para hardware real.
│
├─ ¿Física de resortes incorrecta en el dispositivo?
│  ├─ ¿Los valores están codificados para un dispositivo?
│  │  └─ Usa clase de rendimiento del dispositivo, no modelo
│  ├─ ¿Están intercambiados los parámetros de amortiguamiento/rigidez con masa/rigidez?
│  │  └─ Verifica los significados de los parámetros de CASpringAnimation
│  └─ ¿Funciona en el simulador pero no en el dispositivo?
│     └─ El simulador usa 60 Hz. El dispositivo puede usar 120 Hz. Recalcula.
│
└─ ¿Tirones de gesto + animación?
   ├─ ¿Están compitiendo las animaciones (mismo keyPath)?
   │  └─ Elimina la animación antigua antes de agregar la nueva
   ├─ ¿El gesto actualiza la capa mientras la animación se ejecuta?
   │  └─ Usa CADisplayLink para actualizaciones sincronizadas
   └─ ¿El gesto bloquea el hilo principal?
      └─ Perfila con Instruments > Core Animation

Patrones Comunes

Reglas de Selección de Patrones (OBLIGATORIO)

Aplica UN patrón a la vez, en este orden

  1. Siempre comienza con el Patrón 1 (Conceptos Básicos del Manejador de Finalización)

    • Si la finalización NUNCA se activa → Patrón 1
    • Verifica que la finalización se establezca ANTES de add() con sentencia print (línea 33)
    • Solo procede al Patrón 2 si la finalización SE ACTIVA pero la temporización es incorrecta
  2. Luego Patrón 2 (Desajuste de duración de CATransaction)

    • Solo si la finalización se activa pero el tiempo transcurrido != duración declarada
    • Revisa los registros de los Pasos Obligatorios Iniciales (líneas 40-47)
  3. Luego Patrón 3 (isRemovedOnCompletion)

    • Solo si la animación se completa pero el estado visual revierte
  4. Patrones 4-7 Aplicar según el síntoma específico (ver Árbol de Decisión línea 91+)

PROHIBIDO

  • ❌ Aplicar múltiples patrones a la vez ("déjame probar Patrón 2 Y Patrón 4 juntos")
  • ❌ Saltarse el Patrón 1 porque "ya sé que no es eso"
  • ❌ Combinar patrones sin entender por qué cada uno es necesario
  • ❌ Probar patrones al azar esperando que uno funcione

Patrón 1: Conceptos Básicos del Manejador de Finalización

❌ INCORRECTO (Manejador establecido DESPUÉS de agregar animación)

layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in  // ❌ ¡Demasiado tarde!
    print("Hecho")
}

✅ CORRECTO (Manejador establecido ANTES de agregar)

animation.completion = { [weak self] finished in
    print("🔥 Animación finalizada: \(finished)")
    guard let self = self else { return }
    self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")

Por qué: El manejador de finalización debe establecerse antes de que la animación se agregue a la capa. Establecerlo después no hace nada.


Patrón 2: CATransaction vs animation.duration

❌ INCORRECTO (CATransaction anula la duración de la animación)

CATransaction.begin()
CATransaction.setAnimationDuration(2.0)  // ❌ ¡Anula todas las animaciones!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5  // Esto se ignora
layer.add(anim, forKey: nil)
CATransaction.commit()  // La animación toma 2.0 segundos, no 0.5

✅ CORRECTO (Establecer duración en la animación, no en la transacción)

let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Sin envoltorio CATransaction

Por qué: CATransaction.setAnimationDuration() afecta TODAS las animaciones en el bloque de transacción. Úsalo solo si quieres cambiar todas las animaciones de manera uniforme.


Patrón 3: isRemovedOnCompletion & fillMode

❌ INCORRECTO (La animación desaparece después de completarse)

let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Después de 0.5 s, la animación se elimina Y la capa vuelve al estado original

✅ CORRECTO (Mantener estado de la animación)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // Mantener estado final después de la animación
layer.add(anim, forKey: nil)
// Después de 0.5 s, el estado de la animación se conserva

Por qué: Por defecto, las animaciones se eliminan y la capa revierte. Para cambios de estado permanentes, establece isRemovedOnCompletion = false y fillMode = .forwards.


Patrón 4: Weak Self en Finalización (OBLIGATORIO)

❌ PROHIBIDO (Self fuerte crea ciclo de retención)

anim.completion = { finished in
    self.property = "valor"  // ❌ CICLO DE RETENCIÓN GARANTIZADO
}

✅ OBLIGATORIO (Usar siempre weak self)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "valor"  // Seguro de acceder
}

Por qué esto es OBLIGATORIO, no opcional

  • CAAnimation mantiene vivo el manejador de finalización hasta que la animación se completa
  • El manejador de finalización captura self fuertemente (a menos que sea explícitamente débil)
  • Crea un ciclo de retención: self → animación → finalización → self
  • La fuga de memoria ocurre incluso si la animación es de corta duración (0.3 s no lo previene)

Racionalizaciones PROHIBIDAS

  • ❌ "La animación es corta, entonces no hay riesgo de ciclo de retención"
  • ❌ "Eliminaré la animación manualmente, así que está bien"
  • ❌ "Esta ruta de código solo se ejecuta una vez"

Usa SIEMPRE [weak self] en los manejadores de finalización. Sin excepciones.


Patrón 5: Múltiples Animaciones (Mismo keyPath)

❌ INCORRECTO (Animaciones en conflicto)

// Agregar animación 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")

// Más tarde, agregar animación 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")  // ❌ Misma clave, ¡reemplaza anim1!

✅ CORRECTO (Eliminar antes de agregar)

layer.removeAnimation(forKey: "slide")  // Eliminar la antigua primero

let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")

O usar claves únicas:

let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")

let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2")  // Clave diferente

Por qué: Agregar una animación con la misma clave reemplaza la animación anterior. O elimina la animación antigua o usa claves únicas.


Patrón 6: CADisplayLink para Sincronización de Gesto + Animación

❌ INCORRECTO (El gesto actualiza directamente, la animación actualiza a diferente ritmo)

func handlePan(_ gesture: UIPanGestureRecognizer) {
    let translation = gesture.translation(in: view)
    view.layer.position.x = translation.x  // ❌ Problema de sincronización
}

// Por separado:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // Tirones por desincronización

✅ CORRECTO (Usar CADisplayLink para sincronización)

var displayLink: CADisplayLink?

func startSyncedAnimation() {
    displayLink = CADisplayLink(
        target: self,
        selector: #selector(updateAnimation)
    )
    displayLink?.add(to: .main, forMode: .common)
}

@objc func updateAnimation() {
    // Actualizar gesto Y animación en el mismo fotograma
    let gesture = currentGesture
    let position = calculatePosition(from: gesture)
    layer.position = position  // Actualización sincronizada
}

Por qué: El reconocedor de gestos y CAAnimation pueden ejecutarse a diferentes velocidades de fotogramas. CADisplayLink sincroniza ambos con la tasa de actualización de la pantalla.


Patrón 7: Diferencias de Dispositivo en Animación de Resorte

❌ INCORRECTO (Codificado para un dispositivo)

let springAnim = CASpringAnimation()
springAnim.damping = 0.7  // Codificado para iPhone 15 Pro
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil)  // Tirones en iPhone 12

✅ CORRECTO (Adaptar al rendimiento del dispositivo)

let springAnim = CASpringAnimation()

// Usar clase de rendimiento del dispositivo, no modelo
if ProcessInfo.processInfo.processorCount >= 6 {
    // Serie A moderna (A14+)
    springAnim.damping = 0.7
    springAnim.stiffness = 100
} else {
    // Serie A antigua
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

Por qué: La física de resortes se siente diferente a 60 Hz vs 120 Hz. Usa clase de dispositivo (recuento de núcleos, GPU) no modelo.


Tabla de Referencia Rápida

ProblemaRevisarSolución
La finalización nunca se activaEstablecer manejador ANTES de add()Mover completion = antes de add()
Desajuste de duración¿Envoltorio CATransaction?Eliminar CATransaction o quitar la animación de él
Tirones en dispositivos antiguos¿Valor codificado?Usar ProcessInfo para clase de dispositivo
La animación desaparece¿isRemovedOnCompletion?Establecer a false, usar fillMode = .forwards
Tirones de gesto + animación¿Actualizaciones sincronizadas?Usar CADisplayLink
Conflicto de múltiples animaciones¿Misma clave?Usar claves únicas o removeAnimation() primero
Weak self en manejador¿Finalización capturada correctamente?Usar siempre [weak self] en la finalización

Cuando Estés Atascado Después de 30 Minutos

Si has pasado >30 minutos y la animación sigue rota:

DETENTE. O bien

  1. Te saltaste un paso obligatorio (más común)
  2. Malinterpretaste la salida de diagnóstico
  3. Aplicaste el patrón incorrecto para tu síntoma
  4. Estás en el 5% de casos extremos que requieren perfilado con Instruments

Lista de verificación OBLIGATORIA antes de afirmar "la habilidad no funcionó"

  • Ejecuté TODOS los 4 bloques de diagnóstico de los Pasos Obligatorios Iniciales (líneas 28-63)
  • Pegué la salida EXACTA de los diagnósticos (registros, sentencias print)
  • Identifiqué UNA causa raíz de "Qué te dice esto" (líneas 66-72)
  • Apliqué el PRIMER patrón coincidente del Árbol de Decisión (líneas 91+)
  • Probé el patrón en un dispositivo REAL, no solo en el simulador
  • ...

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 relacionados