Depuração de Animação UIKit
Visão Geral
Problemas com CAAnimation se manifestam como manipuladores de conclusão ausentes, tempo incorreto ou travamentos sob condições específicas. Princípio central: 90% dos problemas de CAAnimation são causados pelo tempo de CATransaction, estado da camada ou suposições sobre a taxa de quadros, não por bugs no Core Animation.
Sinais de Alerta — Suspeitar de Problema com CAAnimation
Se você vir QUALQUER UM destes, suspeite da lógica de animação, não do comportamento do dispositivo:
- O manipulador de conclusão dispara no simulador, mas não no dispositivo
- A duração da animação (0,5s) não corresponde à duração visual (1,2s)
- A animação de mola parece correta no iPhone 15 Pro, mas trava em dispositivos mais antigos
- Gestos + animação juntos causam gagueira (funcionam bem separadamente)
[weak self]no manipulador de conclusão e você não tem certeza do porquê- ❌ PROIBIDO: Codificar duração/valores para "corresponder ao que realmente acontece"
- Isso envia bugs específicos do dispositivo para usuários em hardware diferente
- Não racionalize isso como uma "correção temporária" ou "bom o suficiente"
Distinção crítica: O simulador frequentemente oculta problemas de tempo (apenas 60Hz, sem aceleração). Dispositivos reais os expõem (taxa de quadros variável, aceleração da CPU, pressão de segundo plano). OBRIGATÓRIO: Testar em dispositivo real (modelo mais antigo suportado) antes de enviar.
Primeiros Passos Obrigatórios
SEMPRE execute estes PRIMEIRO (antes de alterar o código):
// 1. Verificar se a conclusão está disparando
animation.completion = { [weak self] finished in
print("🔥 COMPLETION FIRED: finished=\(finished)")
guard let self = self else {
print("🔥 SELF WAS NIL")
return
}
// código original
}
// 2. Verificar duração real vs. 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("Tempo decorrido: \(Date().timeIntervalSince(startTime))") // Real
}
// 3. Verificar quais animações estão ativas
if let keys = layer.animationKeys() {
print("Animações ativas: \(keys)")
for key in keys {
if let anim = layer.animation(forKey: key) {
print("\(key): duração=\(anim.duration), removida=\(anim.isRemovedOnCompletion)")
}
}
}
// 4. Verificar estado da camada
print("Velocidade da camada: \(layer.speed)") // != 1.0 significa que o tempo está sendo escalado
print("TimeOffset da camada: \(layer.timeOffset)") // != 0 significa que a animação está deslocada
O que isso te diz
- Print da conclusão aparece → O manipulador dispara, o problema está no código do callback
- Print da conclusão ausente → O manipulador não dispara, verifique CATransaction/estado da camada
- Tempo decorrido == declarado → A duração está correta, o travamento visual é devido aos quadros
- Tempo decorrido != declarado → O encapsulamento CATransaction está alterando a duração
- layer.speed != 1.0 → Algo está desacelerando a animação
- Lista de animações ativas é longa → Múltiplas animações competindo
INTERPRETAÇÃO OBRIGATÓRIA
Antes de alterar QUALQUER código, você deve identificar qual ÚNICO diagnóstico é a causa raiz:
- Se a conclusão dispara, mas o tempo decorrido != duração declarada → Aplicar Padrão 2 (CATransaction)
- Se a conclusão não dispara E isRemovedOnCompletion é verdadeiro → Aplicar Padrão 3
- Se a conclusão dispara, mas o visual está travado → DEVE criar perfil com Instruments primeiro
- Você não pode adivinhar "provavelmente são os quadros" - prove com dados
- O instrumento Perfil > Core Animation mostra quedas de quadros com certeza
- Se você pular Instruments, está adivinhando
Se os diagnósticos são contraditórios ou pouco claros
- PARE. Não prossiga para os padrões ainda
- Adicione mais prints para restringir a causa
- Pergunte: "Os diagnósticos mostram X e Y, mas Z não corresponde. O que estou perdendo?"
- Crie perfil com Instruments > Core Animation se não tiver certeza
Árvore de Decisão
Problema com CAAnimation?
├─ O manipulador de conclusão nunca dispara?
│ ├─ Apenas no simulador?
│ │ └─ O tempo do simulador é diferente (60Hz). Teste em dispositivo real.
│ ├─ Apenas no dispositivo real?
│ │ ├─ Verifique: isRemovedOnCompletion e fillMode
│ │ ├─ Verifique: encapsulamento CATransaction
│ │ └─ Verifique: app vai para segundo plano durante a animação
│ └─ Tanto no simulador quanto no dispositivo?
│ ├─ Verifique: manipulador de conclusão está definido ANTES de adicionar a animação
│ └─ Verifique: [weak self] está realmente capturado (não nil antes da conclusão)
│
├─ Incompatibilidade de duração (declarada != visual)?
│ ├─ layer.speed != 1.0?
│ │ └─ Algo escalou a duração da animação. Encontre e corrija.
│ ├─ A animação está encapsulada em CATransaction?
│ │ └─ CATransaction.setAnimationDuration() substitui animation.duration
│ └─ A duração visual é MAIOR que a declarada?
│ └─ Simulador (60Hz) vs. taxa de quadros do dispositivo (120Hz). Recalcule para hardware real.
│
├─ Física de mola errada no dispositivo?
│ ├─ Os valores estão codificados para um dispositivo?
│ │ └─ Use classe de desempenho do dispositivo, não modelo
│ ├─ Os parâmetros damping/stiffness estão trocados com mass/stiffness?
│ │ └─ Verifique os significados dos parâmetros de CASpringAnimation
│ └─ Funciona no simulador, mas não no dispositivo?
│ └─ Simulador usa 60Hz. Dispositivo pode usar 120Hz. Recalcule.
│
└─ Travamento de gesto + animação?
├─ As animações estão competindo (mesmo keyPath)?
│ └─ Remova a animação antiga antes de adicionar a nova
├─ O gesto está atualizando a camada enquanto a animação roda?
│ └─ Use CADisplayLink para atualizações sincronizadas
└─ O gesto está bloqueando a thread principal?
└─ Crie perfil com Instruments > Core Animation
Padrões Comuns
Regras de Seleção de Padrões (OBRIGATÓRIO)
Aplique UM padrão por vez, nesta ordem
-
Sempre comece com o Padrão 1 (Básico do Manipulador de Conclusão)
- Se a conclusão NUNCA dispara → Padrão 1
- Verifique se a conclusão está definida ANTES de add() com print (linha 33)
- Só prossiga para o Padrão 2 se a conclusão DISPARAR, mas o tempo estiver errado
-
Depois, Padrão 2 (Incompatibilidade de duração CATransaction)
- Somente se a conclusão disparar, mas o tempo decorrido != duração declarada
- Verifique os logs dos Primeiros Passos Obrigatórios (linha 40-47)
-
Depois, Padrão 3 (isRemovedOnCompletion)
- Somente se a animação completar, mas o estado visual reverter
-
Padrões 4-7 Aplique com base no sintoma específico (veja Árvore de Decisão linha 91+)
PROIBIDO
- ❌ Aplicar múltiplos padrões ao mesmo tempo ("deixe-me tentar o Padrão 2 E o Padrão 4 juntos")
- ❌ Pular o Padrão 1 porque "já sei que não é isso"
- ❌ Combinar padrões sem entender por que cada um é necessário
- ❌ Tentar padrões aleatoriamente esperando que um funcione
Padrão 1: Básico do Manipulador de Conclusão
❌ ERRADO (Manipulador definido DEPOIS de adicionar animação)
layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in // ❌ Muito tarde!
print("Pronto")
}
✅ CORRETO (Manipulador definido ANTES de adicionar)
animation.completion = { [weak self] finished in
print("🔥 Animação finalizada: \(finished)")
guard let self = self else { return }
self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")
Por que O manipulador de conclusão deve ser definido antes que a animação seja adicionada à camada. Definir depois não faz nada.
Padrão 2: CATransaction vs. animation.duration
❌ ERRADO (CATransaction substitui a duração da animação)
CATransaction.begin()
CATransaction.setAnimationDuration(2.0) // ❌ Substitui todas as animações!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5 // Isso é ignorado
layer.add(anim, forKey: nil)
CATransaction.commit() // A animação leva 2.0 segundos, não 0.5
✅ CORRETO (Definir duração na animação, não na transação)
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Sem encapsulamento CATransaction
Por que CATransaction.setAnimationDuration() afeta TODAS as animações no bloco de transação. Use-o apenas se quiser alterar todas as animações uniformemente.
Padrão 3: isRemovedOnCompletion e fillMode
❌ ERRADO (Animação desaparece após a conclusão)
let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Após 0.5s, a animação é removida E a camada reverte ao estado original
✅ CORRETO (Manter estado da animação)
anim.isRemovedOnCompletion = false
anim.fillMode = .forwards // Manter estado final após a animação
layer.add(anim, forKey: nil)
// Após 0.5s, o estado da animação é preservado
Por que Por padrão, as animações são removidas e a camada reverte. Para mudanças de estado permanentes, defina isRemovedOnCompletion = false e fillMode = .forwards.
Padrão 4: Weak Self na Conclusão (OBRIGATÓRIO)
❌ PROIBIDO (Strong self cria ciclo de retenção)
anim.completion = { finished in
self.property = "value" // ❌ CICLO DE RETENÇÃO GARANTIDO
}
✅ OBRIGATÓRIO (Sempre usar weak self)
anim.completion = { [weak self] finished in
guard let self = self else { return }
self.property = "value" // Seguro para acessar
}
Por que isso é OBRIGATÓRIO, não opcional
- CAAnimation mantém o manipulador de conclusão vivo até que a animação termine
- O manipulador de conclusão captura self fortemente (a menos que explicitamente fraco)
- Cria um ciclo de retenção: self → animation → completion → self
- O vazamento de memória ocorre mesmo que a animação seja de curta duração (0,3s não o impede)
Racionalizações PROIBIDAS
- ❌ "A animação é curta, então não há risco de ciclo de retenção"
- ❌ "Vou remover a animação manualmente, então está tudo bem"
- ❌ "Este caminho de código só é executado uma vez"
SEMPRE use [weak self] nos manipuladores de conclusão. Sem exceções.
Padrão 5: Múltiplas Animações (Mesmo keyPath)
❌ ERRADO (Animações em conflito)
// Adicionar animação 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")
// Mais tarde, adicionar animação 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide") // ❌ Mesma chave, substitui anim1!
✅ CORRETO (Remover antes de adicionar)
layer.removeAnimation(forKey: "slide") // Remover antiga primeiro
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")
Ou use chaves ú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") // Chave diferente
Por que Adicionar animação com a mesma chave substitui a animação anterior. Remova a animação antiga ou use chaves únicas.
Padrão 6: CADisplayLink para Sincronização de Gesto + Animação
❌ ERRADO (Gesto atualiza diretamente, animação atualiza em taxa diferente)
func handlePan(_ gesture: UIPanGestureRecognizer) {
let translation = gesture.translation(in: view)
view.layer.position.x = translation.x // ❌ Problema de sincronização
}
// Separadamente:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil) // Travamento por dessincronização
✅ CORRETO (Usar CADisplayLink para sincronização)
var displayLink: CADisplayLink?
func startSyncedAnimation() {
displayLink = CADisplayLink(
target: self,
selector: #selector(updateAnimation)
)
displayLink?.add(to: .main, forMode: .common)
}
@objc func updateAnimation() {
// Atualizar gesto E animação no mesmo quadro
let gesture = currentGesture
let position = calculatePosition(from: gesture)
layer.position = position // Atualização sincronizada
}
Por que O reconhecedor de gestos e a CAAnimation podem rodar em taxas de quadros diferentes. CADisplayLink sincroniza ambos com a taxa de atualização da tela.
Padrão 7: Diferenças de Animação Spring Entre Dispositivos
❌ ERRADO (Codificado para um dispositivo)
let springAnim = CASpringAnimation()
springAnim.damping = 0.7 // Codificado para iPhone 15 Pro
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil) // Travando no iPhone 12
✅ CORRETO (Adaptar ao desempenho do dispositivo)
let springAnim = CASpringAnimation()
// Usar classe de desempenho do dispositivo, não modelo
if ProcessInfo.processInfo.processorCount >= 6 {
// Série A moderna (A14+)
springAnim.damping = 0.7
springAnim.stiffness = 100
} else {
// Série A mais antiga
springAnim.damping = 0.85
springAnim.stiffness = 80
}
layer.add(springAnim, forKey: nil)
Por que A física da mola parece diferente em 60Hz vs. 120Hz. Use a classe do dispositivo (contagem de núcleos, GPU), não o modelo.
Tabela de Referência Rápida
| Problema | Verificar | Correção |
|---|---|---|
| Conclusão nunca dispara | Definir manipulador ANTES de add() | Mover completion = antes de add() |
| Incompatibilidade de duração | Há encapsulamento CATransaction? | Remover CATransaction ou remover animação dele |
| Travamento em dispositivos mais antigos | O valor está codificado? | Usar ProcessInfo para classe do dispositivo |
| Animação desaparece | isRemovedOnCompletion? | Definir para false, usar fillMode = .forwards |
| Travamento de gesto + animação | Atualizações sincronizadas? | Usar CADisplayLink |
| Múltiplas animações em conflito | Mesma chave? | Usar chaves únicas ou removeAnimation() primeiro |
| Weak self no manipulador | A conclusão está capturada corretamente? | Sempre usar [weak self] na conclusão |
Quando Estiver Travado Após 30 Minutos
Se você gastou >30 minutos e a animação ainda está quebrada:
PARE. Você:
- Pulou uma etapa obrigatória (mais comum)
- Interpretou mal a saída do diagnóstico
- Aplicou o padrão errado para seu sintoma
- Está nos 5% de casos extremos que exigem perfil com Instruments
Checklist OBRIGATÓRIO antes de alegar que "a skill não funcionou"
- Eu executei TODOS os 4 blocos de diagnóstico dos Primeiros Passos Obrigatórios (linhas 28-63)
- Eu colei a saída EXATA dos diagnósticos (logs, prints)
- Eu identifiquei UMA causa raiz de "O que isso te diz" (linhas 66-72)
- Eu apliquei o PRIMEIRO padrão correspondente da Árvore de Decisão (linhas 91+)
- Eu testei o padrão em um dispositivo REAL, não apenas no simulador
- Eu verifiquei o padrão com prints/logs mostrando que a correção funcionou
Se TODAS as caixas estiverem marcadas e ainda estiver quebrado
- Você DEVE criar perfil com Instruments > Core Animation
- Custo de tempo: 30-60 minutos (inevitável para casos extremos)
- Codificar valores, asyncAfter, ou "enviar e torcer" são PROIBIDOS
- Peça orientação antes de adicionar qualquer solução alternativa
Transparência de custo de tempo
- Padrão 1: 2-5 minutos
- Padrão 2: 5-10 minutos
- Padrão 3: 2-5 minutos
- Padrão 4: 2 minutos (sempre aplique)
- Padrão 5: 5-10 minutos
- Padrão 6: 10-20 minutos
- Padrão 7: 10-15 minutos
- Instruments: 30-60 minutos (apenas para casos extremos)