¿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:
- Si la finalización se activa pero el tiempo transcurrido != duración declarada → Aplicar Patrón 2 (CATransaction)
- Si la finalización no se activa Y isRemovedOnCompletion es verdadero → Aplicar Patrón 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
-
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
-
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)
-
Luego Patrón 3 (isRemovedOnCompletion)
- Solo si la animación se completa pero el estado visual revierte
-
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
| Problema | Revisar | Solución |
|---|---|---|
| La finalización nunca se activa | Establecer 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
- Te saltaste un paso obligatorio (más común)
- Malinterpretaste la salida de diagnóstico
- Aplicaste el patrón incorrecto para tu síntoma
- 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
- ...