Depuración de Animaciones UIKit
Descripción general
Los problemas de CAAnimation se manifiestan como manejadores de finalización faltantes, tiempos incorrectos o tirones bajo condiciones específicas. Principio fundamental: el 90% de los problemas de CAAnimation se deben al tiempo 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 un problema de CAAnimation
Si ves CUALQUIERA de estas señales, sospecha que es un problema de lógica de animación, no de comportamiento del dispositivo:
- El manejador de finalización se ejecuta en el simulador pero no en el dispositivo
- La duración de la animación (0.5s) no coincide con la duración visual (1.2s)
- La animación con resorte se ve correcta en iPhone 15 Pro pero entrecortada en dispositivos más antiguos
- La combinación de gesto + animación causa tartamudeo (por separado funciona bien)
- Usas
[weak self]en el manejador de finalización y no estás seguro de por qué - ❌ PROHIBIDO: Codificar duraciones/valores para "que coincidan con lo que realmente sucede"
- Esto envía errores específicos del dispositivo a usuarios con hardware diferente
- No justifiques esto como una "solución temporal" o "suficientemente buena"
Distinción crítica: el simulador a menudo oculta problemas de tiempo (solo 60Hz, sin limitación). Los dispositivos reales los exponen (tasa de fotogramas variable, limitación de CPU, presión en segundo plano). OBLIGATORIO: probar en un dispositivo real (el modelo más antiguo compatible) antes de enviar.
Pasos obligatorios iniciales
SIEMPRE ejecuta estos PRIMERO (antes de cambiar el código):
// 1. Verificar si la finalización se está ejecutando
animation.completion = { [weak self] finished in
print("🔥 FINALIZACIÓN EJECUTADA: finished=\(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), eliminada=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. Verificar el estado de la capa
print("Velocidad de la capa: \(layer.speed)") // != 1.0 significa que el tiempo está escalado
print("Desplazamiento de tiempo de la capa: \(layer.timeOffset)") // != 0 significa que la animación está desplazada
Qué te dice esto
- Aparece el print de finalización → El manejador se ejecuta, el problema está en el código de callback
- Falta el print de finalización → El manejador no se ejecuta, verifica CATransaction/estado de la capa
- Tiempo transcurrido == declarado → La duración es correcta, el tirón visual se debe a los fotogramas
- Tiempo transcurrido != declarado → El envoltorio de CATransaction está cambiando la duración
- layer.speed != 1.0 → Algo está ralentizando la animación
- La lista de animaciones activas es 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 ejecuta pero el tiempo transcurrido != duración declarada → Aplicar Patrón 2 (CATransaction)
- Si la finalización no se ejecuta Y isRemovedOnCompletion es true → Aplicar Patrón 3
- Si la finalización se ejecuta pero lo visual es entrecortado → DEBES perfilar con Instruments primero
- No puedes adivinar "probablemente son los fotogramas" - demuéstralo con datos
- Perfil > Instrumento Core Animation muestra las 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 declaraciones 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 ejecuta?
│ ├─ ¿Solo en el simulador?
│ │ └─ El tiempo del simulador es diferente (60Hz). Prueba en un dispositivo real.
│ ├─ ¿Solo en el dispositivo real?
│ │ ├─ Verificar: isRemovedOnCompletion y fillMode
│ │ ├─ Verificar: envoltorio de CATransaction
│ │ └─ Verificar: la aplicación pasa a segundo plano durante la animación
│ └─ ¿En simulador y dispositivo?
│ ├─ Verificar: el manejador de finalización se establece ANTES de agregar la animación
│ └─ Verificar: [weak self] realmente se captura (no es nil antes de la finalización)
│
├─ ¿Discrepancia 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 MÁS LARGA que la declarada?
│ └─ Simulador (60Hz) vs. tasa de fotogramas del dispositivo (120Hz). Recalcula para hardware real.
│
├─ ¿Física de resortes incorrecta en el dispositivo?
│ ├─ ¿Los valores están codificados para un dispositivo?
│ │ └─ Usa la clase de rendimiento del dispositivo, no el modelo
│ ├─ ¿La amortiguación/rigidez están intercambiadas con masa/rigidez?
│ │ └─ Verifica los significados de los parámetros de CASpringAnimation
│ └─ ¿Funciona en el simulador pero no en el dispositivo?
│ └─ El simulador usa 60Hz. El dispositivo puede usar 120Hz. Recalcula.
│
└─ ¿Tirones de gesto + animación?
├─ ¿Las animaciones compiten (mismo keyPath)?
│ └─ Elimina la animación antigua antes de agregar la nueva
├─ ¿El gesto actualiza la capa mientras se ejecuta la animación?
│ └─ 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 ejecuta → Patrón 1
- Verifica que la finalización se establezca ANTES de add() con una declaración print (línea 33)
- Solo procede al Patrón 2 si la finalización SE EJECUTA pero el tiempo es incorrecto
-
Luego Patrón 2 (Discrepancia de duración de CATransaction)
- Solo si la finalización se ejecuta pero el tiempo transcurrido != duración declarada
- Verifica los registros de los Pasos obligatorios iniciales (línea 40-47)
-
Luego Patrón 3 (isRemovedOnCompletion)
- Solo si la animación se completa pero el estado visual revierte
-
Patrones 4-7 Aplica 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 el Patrón 2 Y el Patrón 4 juntos")
- ❌ Saltarse el Patrón 1 porque "ya sé que no es eso"
- ❌ Combinar patrones sin entender por qué se necesita cada uno
- ❌ Probar patrones al azar con la esperanza de que uno funcione
Patrón 1: Conceptos básicos del manejador de finalización
❌ INCORRECTO (Manejador establecido DESPUÉS de agregar la 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 agregar la animación 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 tarda 2.0 segundos, no 0.5
✅ CORRECTO (Establecer la 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 de CATransaction
Por qué: CATransaction.setAnimationDuration() afecta a TODAS las animaciones dentro del bloque de transacción. Úsalo solo si deseas cambiar todas las animaciones de manera uniforme.
Patrón 3: isRemovedOnCompletion y 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.5s, la animación se elimina Y la capa vuelve a su estado original
✅ CORRECTO (Mantener el estado de la animación)
anim.isRemovedOnCompletion = false
anim.fillMode = .forwards // Mantener el estado final después de la animación
layer.add(anim, forKey: nil)
// Después de 0.5s, el estado de la animación se conserva
Por qué: De forma predeterminada, 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 la finalización (OBLIGATORIO)
❌ PROHIBIDO (Self fuerte crea un 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 weak)
- 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.3s no lo previene)
Racionalizaciones PROHIBIDAS
- ❌ "La animación es corta, así que 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"
SIEMPRE usa [weak self] en los manejadores de finalización. Sin excepciones.
Patrón 5: Múltiples animaciones (Mismo keyPath)
❌ INCORRECTO (Las animaciones entran 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. Elimina la animación anterior 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 una velocidad diferente)
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) // Tirón por desincronización
✅ CORRECTO (Usar CADisplayLink para la 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 fotograma. CADisplayLink sincroniza ambos con la velocidad de actualización de la pantalla.
Patrón 7: Diferencias de animación con resorte entre dispositivos
❌ 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) // Entrecortado en iPhone 12
✅ CORRECTO (Adaptar al rendimiento del dispositivo)
let springAnim = CASpringAnimation()
// Usar la clase de rendimiento del dispositivo, no el modelo
if ProcessInfo.processInfo.processorCount >= 6 {
// A-series moderna (A14+)
springAnim.damping = 0.7
springAnim.stiffness = 100
} else {
// A-series antigua
springAnim.damping = 0.85
springAnim.stiffness = 80
}
layer.add(springAnim, forKey: nil)
Por qué: La física de resortes se siente diferente a 60Hz vs. 120Hz. Usa la clase de dispositivo (número de núcleos, GPU) no el modelo.
Tabla de referencia rápida
| Problema | Verificar | Solución |
|---|---|---|
| La finalización nunca se ejecuta | Establecer el manejador ANTES de add() | Mover completion = antes de add() |
| Discrepancia de duración | ¿Está envuelto en CATransaction? | Eliminar CATransaction o eliminar la animación de él |
| Tirón en dispositivos antiguos | ¿Está el valor codificado? | Usar ProcessInfo para la clase de dispositivo |
| La animación desaparece | ¿isRemovedOnCompletion? | Establecer a false, usar fillMode = .forwards |
| Tirón de gesto + animación | ¿Actualizaciones sincronizadas? | Usar CADisplayLink |
| Conflicto de múltiples animaciones | ¿Misma clave? | Usar claves únicas o removeAnimation() primero |
| Weak self en el manejador | ¿Finalización capturada correctamente? | Siempre usar [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 sin funcionar:
DETENTE. O bien:
- Te saltaste un paso obligatorio (lo más común)
- Malinterpretaste la salida del diagnóstico
- Aplicaste el patrón incorrecto para tu síntoma
- Estás en el 5% de casos extremos que requieren creación de perfiles 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, declaraciones 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
- Verifiqué el patrón con declaraciones print/registros que muestran que la solución funcionó
Si TODAS las casillas están marcadas y aún no funciona
- DEBES perfilar con Instruments > Core Animation
- Costo de tiempo: 30-60 minutos (inevitable para casos extremos)
- Codificar, asyncAfter o "enviar y esperar" están PROHIBIDOS
- Pide orientación antes de agregar cualquier solución alternativa
Transparencia del costo de tiempo
- Patrón 1: 2-5 minutos
- Patrón 2: 2-5 minutos
- Patrón 3: 2-5 minutos
- Patrón 4: 2-5 minutos
- Patrón 5: 2-5 minutos
- Patrón 6: 2-5 minutos
- Patrón 7: 2-5 minutos
- Instruments > Core Animation: 30-60 minutos