Communitygithub.com

Depuração de Animações UIKit

Use quando o manipulador de conclusão do CAAnimation não dispara, a física de mola parece errada no dispositivo, a duração da animação não corresponde ao tempo real, a interação gesto + animação causa travamentos ou o tempo difere entre o simulador e o hardware real. Diagnóstico sistemático de CAAnimation com padrões CATransaction, consciência de taxa de quadros e comportamento específico do dispositivo.

O que é Depuração de Animações UIKit?

Esta habilidade especializada em depuração de animações UIKit (CAAnimation) é essencial para desenvolvedores iOS que enfrentam problemas onde animações se comportam de forma inconsistente entre o simulador e dispositivos reais. O guia oferece uma abordagem sistemática para diagnosticar e resolver problemas comuns, como manipuladores de conclusão que nunca disparam, durações de animação incorretas devido a transações CATransaction, física de mola inadequada em diferentes gerações de hardware, e conflitos entre gestos e animações. Ele enfatiza que 90% dos problemas de CAAnimation são causados por suposições de timing, estado da camada ou taxa de quadros, e não por bugs reais do Core Animation. A metodologia inclui passos diagnósticos obrigatórios (como verificar velocidade da camada e animações ativas), uma árvore de decisão para identificar a causa raiz, e padrões de solução específicos (como sempre usar `[weak self]` em manipuladores de conclusão, evitar valores hardcoded, e utilizar CADisplayLink para sincronização). A habilidade impõe regras rigorosas: testar em dispositivo real antes de enviar, aplicar um padrão por vez, e nunca pular etapas diagnósticas. Suporta plataformas iOS e macOS, e exige que o desenvolvedor evite 'soluções temporárias' que mascarem bugs específicos de dispositivo.

Funciona com✓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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Depuração de Animações UIKit faz?

Visão Geral

Problemas com CAAnimation se manifestam como manipuladores de conclusão ausentes, temporização incorreta ou travamentos sob condições específicas. Princípio central: 90% dos problemas de CAAnimation são causados por suposições de timing de CATransaction, estado da camada ou taxa de quadros, não por bugs do Core Animation.

Bandeiras Vermelhas — Suspeite de Problema de CAAnimation

Se você vir QUALQUER um destes, suspeite de lógica de animação, não 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
  • Gesto + animação juntos causam gagueira (funcionam bem separadamente)
  • [weak self] no manipulador de conclusão e você não tem certeza do porquê
  • ❌ PROIBIDO Hardcodar duração/valores para "corresponder ao que realmente acontece"
    • Isso envia bugs específicos de dispositivo para usuários em hardware diferente
    • Não racionalize isso como uma "correção temporária" ou "suficientemente bom"

Distinção crítica: O simulador frequentemente esconde problemas de temporização (apenas 60Hz, sem limitação). Dispositivos reais os expõem (taxa de quadros variável, limitação de CPU, pressão de segundo plano). OBRIGATÓRIO: Testar em dispositivo real (modelo mais antigo suportado) antes de enviar.

Passos Iniciais Obrigatórios

SEMPRE execute estes PRIMEIRO (antes de alterar o código):

// 1. Verifique se a conclusão está disparando
animation.completion = { [weak self] finished in
    print("🔥 CONCLUSÃO DISPAROU: finished=\(finished)")
    guard let self = self else {
        print("🔥 SELF ERA NIL")
        return
    }
    // código original
}

// 2. Verifique a 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. Verifique 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. Verifique o estado da camada
print("Velocidade da camada: \(layer.speed)")  // != 1.0 significa que o tempo está escalado
print("Deslocamento de tempo da camada: \(layer.timeOffset)")  // != 0 significa que a animação está deslocada

O que isso lhe diz

  • Mensagem de conclusão aparece → O manipulador dispara, o problema está no código do callback
  • Mensagem de 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:

  1. Se a conclusão dispara, mas o tempo decorrido != duração declarada → Aplique o Padrão 2 (CATransaction)
  2. Se a conclusão não dispara E isRemovedOnCompletion é true → Aplique o Padrão 3
  3. Se a conclusão dispara, mas o visual está travando → DEVE primeiro criar perfil com Instruments
    • Você não pode adivinhar "provavelmente são 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 forem contraditórios ou pouco claros

  • PARE. Não prossiga para os padrões ainda
  • Adicione mais instruções print 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 de CAAnimation?
├─ O manipulador de conclusão nunca dispara?
│  ├─ Apenas no simulador?
│  │  └─ A temporização do simulador é diferente (60Hz). Teste em dispositivo real.
│  ├─ Apenas no dispositivo real?
│  │  ├─ Verifique: isRemovedOnCompletion e fillMode
│  │  ├─ Verifique: encapsulamento CATransaction
│  │  └─ Verifique: o app vai para segundo plano durante a animação
│  └─ Tanto no simulador quanto no dispositivo?
│     ├─ Verifique: o manipulador de conclusão é definido ANTES de adicionar a animação
│     └─ Verifique: [weak self] é 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 são hardcoded 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 CASpringAnimation
│  └─ Funciona no simulador, mas não no dispositivo?
│     └─ O simulador usa 60Hz. O 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 é executada?
   │  └─ 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ão (OBRIGATÓRIO)

Aplique UM padrão por vez, nesta ordem

  1. Sempre comece com o Padrão 1 (Fundamentos do Manipulador de Conclusão)

    • Se a conclusão NUNCA dispara → Padrão 1
    • Verifique se a conclusão é definida ANTES de add() com instrução print (linha 33)
    • Prossiga para o Padrão 2 apenas se a conclusão DISPARAR, mas a temporização estiver errada
  2. Depois, Padrão 2 (Incompatibilidade de duração CATransaction)

    • Apenas se a conclusão disparar, mas o tempo decorrido != duração declarada
    • Verifique os logs dos Passos Iniciais Obrigatórios (linhas 40-47)
  3. Depois, Padrão 3 (isRemovedOnCompletion)

    • Apenas se a animação for concluída, mas o estado visual reverter
  4. Padrões 4-7 Aplique com base no sintoma específico (consulte a Á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 "eu 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: Fundamentos do Manipulador de Conclusão

❌ ERRADO (Manipulador definido DEPOIS de adicionar a animação)

layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in  // ❌ Tarde demais!
    print("Concluído")
}

✅ CORRETO (Manipulador definido ANTES de adicionar)

animation.completion = { [weak self] finished in
    print("🔥 Animação concluída: \(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 de a animação ser 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 (Defina a 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 & fillMode

❌ ERRADO (A 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 o estado da animação)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // Manter o 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 alterações 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 = "valor"  // ❌ CICLO DE RETENÇÃO GARANTIDO
}

✅ OBRIGATÓRIO (Sempre use weak self)

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

Por que isso é OBRIGATÓRIO, não opcional

  • CAAnimation mantém o manipulador de conclusão ativo até que a animação termine
  • O manipulador de conclusão captura self fortemente (a menos que explicitamente weak)
  • Cria ciclo de retenção: self → animação → conclusão → self
  • O vazamento de memória ocorre mesmo que a animação seja curta (0,3s nã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 é executado apenas uma vez"

USE SEMPRE [weak self] em 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 primeiro a antiga

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 sincronia
}

// Separadamente:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // Travamento por dessincronização

✅ CORRETO (Use 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 ser executados 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 no Dispositivo

❌ ERRADO (Hardcoded para um dispositivo)

let springAnim = CASpringAnimation()
springAnim.damping = 0.7  // Hardcoded para iPhone 15 Pro
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil)  // Travamento no iPhone 12

✅ CORRETO (Adapte ao desempenho do dispositivo)

let springAnim = CASpringAnimation()

// Use 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 antiga
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

Por que A física de mola parece diferente em 60Hz vs. 120Hz. Use classe de dispositivo (contagem de núcleos, GPU), não modelo.


Tabela de Referência Rápida

ProblemaVerificarCorrigir
A conclusão nunca disparaDefinir manipulador ANTES de add()Mover completion = antes de add()
Incompatibilidade de duraçãoHá encapsulamento CATransaction?Remover CATransaction ou remover animação dele
Travamento em dispositivos mais antigosO valor está hardcoded?Use ProcessInfo para classe de dispositivo
A animação desapareceisRemovedOnCompletion?Definir como false, usar fillMode = .forwards
Travamento de gesto + animaçãoAtualizações sincronizadas?Use CADisplayLink
Conflito de múltiplas animaçõesMesma chave?Use chaves únicas ou removeAnimation() primeiro
Weak self no manipuladorA conclusão foi capturada corretamente?Sempre use [weak self] na conclusão

Quando Estiver Travado Após 30 Minutos

Se você passou >30 minutos e a animação ainda está quebrada:

PARE. Ou você

  1. Pulou uma etapa obrigatória (mais comum)
  2. Interpretou mal a saída do diagnóstico
  3. Aplicou o padrão errado para seu sintoma
  4. Está no caso de borda de 5% que requer criação de perfil com Instruments

Lista de verificação OBRIGATÓRIA antes de alegar "a habilidade não funcionou"

  • Executei TODOS os 4 blocos de diagnóstico dos Passos Iniciais Obrigatórios (linhas 28-63)
  • Colei a saída EXATA dos diagnósticos (logs, instruções print)
  • Identifiquei UMA causa raiz em "O que isso lhe diz" (linhas 66-72)
  • Apliquei o PRIMEIRO padrão correspondente da Árvore de Decisão (linhas 91+)
  • Testei o padrão em um dispositivo REAL, não apenas no simulador
  • Se travado, criei perfil com Instruments > Core Animation para verificar dados de quadros

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.

Habilidades Relacionadas