Communitygithub.com

IGTA-Tech/claude-skills-research

Use ao implementar animações em SwiftUI, entender VectorArithmetic, usar o macro @Animatable, escolher entre animações spring e timing curve, ou depurar comportamento de animação – referência abrangente de animações do iOS 13 ao iOS 26.

O que é claude-skills-research?

Este skill oferece uma referência completa e detalhada sobre o sistema de animação do SwiftUI, cobrindo desde conceitos fundamentais até técnicas avançadas. Baseia-se no princípio central de que animação em SwiftUI é interpolação matemática ao longo do tempo, impulsionada pelo protocolo VectorArithmetic. Ao dominar este skill, você será capaz de implementar animações personalizadas em views e shapes, entender por que certas propriedades como `Int` não animam, escolher entre animações spring e timing curve, e utilizar o novo macro `@Animatable` (disponível a partir do iOS 26) para reduzir drasticamente o código boilerplate. O guia também explica detalhadamente o protocolo Animatable, o uso de `AnimatablePair` para dados multidimensionais, o sistema de Transactions, e os tipos de animação disponíveis, incluindo spring, timing curves e animações baseadas em gestos. Além disso, aborda otimizações de performance e casos de uso reais em aplicativos fintech, saúde, fitness, jogos e produtividade. O skill é compatível com iOS 13+ para o protocolo Animatable, iOS 17+ para animações spring padrão e animações por escopo, e iOS 26+ para o macro `@Animatable`, sendo adequado para qualquer desenvolvedor ou agente de IA que trabalhe com SwiftUI.

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/swiftui-animation-ref

Perguntar na sua IA favorita

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

Documentação

Animação em SwiftUI

Visão Geral

Guia abrangente do sistema de animação do SwiftUI, desde conceitos fundamentais até técnicas avançadas. Este skill cobre o protocolo Animatable, o macro @Animatable do iOS 26, os tipos de animação e o sistema de Transaction.

Princípio fundamental A animação em SwiftUI é interpolação matemática ao longo do tempo, impulsionada pelo protocolo VectorArithmetic. Compreender essa base desbloqueia todo o poder do sistema de animação declarativa do SwiftUI.

Quando Usar Este Skill

  • Implementar views ou shapes animadas personalizadas
  • Entender por que uma propriedade não anima (Int vs Float/Double)
  • Escolher entre animações spring e timing curve
  • Usar o macro @Animatable (iOS 26+)
  • Conformar views ao protocolo Animatable
  • Depurar o comportamento de mesclagem de animações
  • Otimizar o desempenho de animações
  • Criar animações complexas ou de múltiplas etapas
  • Entender valores de modelo vs. valores de apresentação
  • Implementar algoritmos de animação personalizados

Requisitos do Sistema

iOS 13+ para o protocolo Animatable

iOS 17+ para animações spring padrão, animações por escopo

iOS 26+ para o macro @Animatable


Parte 1: Entendendo a Animação

O que é Interpolação

Animação é o processo de gerar valores intermediários entre um estado inicial e um final.

Exemplo: Animação de opacidade

.opacity(0) → .opacity(1)

Enquanto esta animação é executada, o SwiftUI calcula valores intermediários:

0.0 → 0.02 → 0.05 → 0.1 → 0.25 → 0.4 → 0.6 → 0.8 → 1.0

Como os valores são distribuídos

  • Determinado pela curva de tempo ou função de velocidade da animação
  • Animações spring usam simulação física
  • Curvas de tempo usam curvas bezier
  • Cada tipo de animação calcula os valores de forma diferente

Protocolo VectorArithmetic

O SwiftUI exige que os dados animados estejam em conformidade com VectorArithmetic, que fornece:

protocol VectorArithmetic {
    // Calcula a diferença entre dois valores
    static func - (lhs: Self, rhs: Self) -> Self

    // Escala valores
    static func * (lhs: Self, rhs: Double) -> Self

    // Soma valores
    static func + (lhs: Self, rhs: Self) -> Self

    // Valor zero
    static var zero: Self { get }
}

Tipos integrados em conformidade

  • 1-dimensional: CGFloat, Double, Float, Angle
  • 2-dimensional: CGPoint, CGSize
  • 4-dimensional: CGRect

Insight fundamental A aritmética vetorial abstrai a dimensionalidade dos dados animados. O SwiftUI pode animar todos esses tipos com uma única implementação genérica.

Por que Int Não Pode Ser Animado

Int não está em conformidade com VectorArithmetic porque:

  1. Não possui valores fracionários intermediários — Não existe "3.5" entre 3 e 4
  2. Não é contínuo — Inteiros são valores discretos
  3. Escala não faz sentido — O que significa 5 × 0.5 para um inteiro?

O que acontece quando você tenta

struct CounterView: View {
    @State private var count: Int = 0

    var body: some View {
        Text("\(count)")
            .animation(.spring, value: count)
    }
}

Resultado: O SwiftUI simplesmente substitui o texto antigo pelo novo. Nenhuma interpolação ocorre.

Solução: Use Float ou Double

struct AnimatedCounterView: View {
    @State private var count: Float = 0

    var body: some View {
        Text("\(Int(count))")
            .animation(.spring, value: count)
    }
}

Resultado: O SwiftUI interpola 0.0 → ... → 100.0 e você exibe o inteiro arredondado em cada quadro.

Valores de Modelo vs. Apresentação

Atributos animáveis têm conceitualmente dois valores:

Valor de Modelo

  • O valor alvo definido pelo seu código
  • Atualizado imediatamente quando o estado muda
  • O que você escreve no body da sua view

Valor de Apresentação

  • O valor interpolado atual que está sendo renderizado
  • Atualiza quadro a quadro durante a animação
  • O que o usuário realmente vê

Exemplo

.scaleEffect(selected ? 1.5 : 1.0)

Quando selected se torna true:

  • Valor de modelo: Imediatamente se torna 1.5
  • Valor de apresentação: Interpola 1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5 ao longo do tempo

Parte 2: Protocolo Animatable

Visão Geral

O protocolo Animatable permite que as views animem suas propriedades definindo quais dados devem ser interpolados.

protocol Animatable {
    associatedtype AnimatableData: VectorArithmetic

    var animatableData: AnimatableData { get set }
}

O SwiftUI cria um atributo animável para qualquer view em conformidade com este protocolo.

Views Animáveis Integradas

Muitos modificadores do SwiftUI estão em conformidade com Animatable:

Efeitos Visuais

  • .scaleEffect() — Anima transformação de escala
  • .rotationEffect() — Anima rotação
  • .offset() — Anima deslocamento de posição
  • .opacity() — Anima transparência
  • .blur() — Anima raio de desfoque
  • .shadow() — Anima propriedades de sombra

Todos os tipos de Shape

  • Circle, Rectangle, RoundedRectangle
  • Capsule, Ellipse, Path
  • Implementações personalizadas de Shape

AnimatablePair para Dados Multidimensionais

Ao animar múltiplas propriedades, use AnimatablePair para combinar vetores.

Exemplo: Implementação de scaleEffect

struct ScaleEffectModifier: ViewModifier, Animatable {
    var scale: CGSize
    var anchor: UnitPoint

    // Combina dois vetores 2D em um vetor 4D
    var animatableData: AnimatablePair<CGSize.AnimatableData, UnitPoint.AnimatableData> {
        get {
            AnimatablePair(scale.animatableData, anchor.animatableData)
        }
        set {
            scale.animatableData = newValue.first
            anchor.animatableData = newValue.second
        }
    }

    func body(content: Content) -> some View {
        content.scaleEffect(scale, anchor: anchor)
    }
}

Como funciona

  • CGSize é 2-dimensional (largura, altura)
  • UnitPoint é 2-dimensional (x, y)
  • AnimatablePair os funde em um vetor 4-dimensional
  • O SwiftUI interpola todos os 4 valores juntos

Conformidade Animatable Personalizada

Quando usar

  • Animando layouts personalizados (como RadialLayout)
  • Animando código de desenho personalizado
  • Animando propriedades que afetam caminhos de shapes

Exemplo: View de número animado

struct AnimatableNumberView: View, Animatable {
    var number: Double

    var animatableData: Double {
        get { number }
        set { number = newValue }
    }

    var body: some View {
        Text("\(Int(number))")
            .font(.largeTitle)
    }
}

// Uso
AnimatableNumberView(number: value)
    .animation(.spring, value: value)

Como funciona

  1. number muda de 0 para 100
  2. O SwiftUI chama body para cada quadro da animação
  3. Cada quadro recebe um novo valor de number: 0 → 5 → 15 → 30 → 55 → 80 → 100
  4. O Text é atualizado para mostrar o inteiro interpolado

Aviso de Performance

A conformidade personalizada com Animatable pode ser cara.

Quando você conforma uma view a Animatable:

  • O SwiftUI chama o body da sua view para cada quadro da animação
  • O layout é recalculado a cada quadro
  • Isso acontece na thread principal

Efeitos animáveis integrados (como .scaleEffect(), .opacity()) são muito mais eficientes:

  • Eles são executados fora da thread principal
  • Eles não chamam o body da sua view
  • Eles atualizam apenas a camada de renderização

Diretriz

  • Use efeitos integrados sempre que possível
  • Use conformidade personalizada com Animatable apenas se não conseguir o efeito com modificadores integrados
  • Analise com Instruments se tiver problemas de performance

Exemplo: Animação de layout circular

// Isso é caro, mas necessário para animar ao longo de um caminho circular
@Animatable
struct RadialLayout: Layout {
    var offsetAngle: Angle

    var animatableData: Angle.AnimatableData {
        get { offsetAngle.animatableData }
        set { offsetAngle.animatableData = newValue }
    }

    func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
        proposal.replacingUnspecifiedDimensions()
    }

    func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
        let radius = min(bounds.width, bounds.height) / 2
        let center = CGPoint(x: bounds.midX, y: bounds.midY)
        let angleStep = Angle.degrees(360.0 / Double(subviews.count))

        for (index, subview) in subviews.enumerated() {
            let angle = offsetAngle + angleStep * Double(index)
            let x = center.x + radius * cos(angle.radians)
            let y = center.y + radius * sin(angle.radians)

            subview.place(at: CGPoint(x: x, y: y), anchor: .center, proposal: .unspecified)
        }
    }
}

Por que é necessário: Animar offsetAngle requer recalcular posições a cada quadro. Nenhum modificador integrado pode fazer isso.


Parte 3: Macro @Animatable (iOS 26+)

Visão Geral

O macro @Animatable elimina o trabalho repetitivo de conformar manualmente ao protocolo Animatable.

Antes do iOS 26, você precisava:

  1. Conformar manualmente a Animatable
  2. Escrever getter e setter de animatableData
  3. Usar AnimatablePair para múltiplas propriedades
  4. Excluir propriedades não animáveis manualmente

iOS 26+, basta adicionar @Animatable:

@MainActor
@Animatable
struct MyView: View {
    var scale: CGFloat
    var opacity: Double

    var body: some View {
        // ...
    }
}

O macro automaticamente:

  • Gera a conformidade com Animatable
  • Inspeciona todas as propriedades armazenadas
  • Cria animatableData a partir de propriedades em conformidade com VectorArithmetic
  • Lida com dados multidimensionais usando AnimatablePair

Comparação Antes/Depois

Antes do macro @Animatable

struct HikingRouteShape: Shape {
    var startPoint: CGPoint
    var endPoint: CGPoint
    var elevation: Double
    var drawingDirection: Bool // Não queremos animar isso

    // Declaração tediosa e manual de animatableData
    var animatableData: AnimatablePair<AnimatablePair<CGFloat, CGFloat>,
                        AnimatablePair<Double, AnimatablePair<CGFloat, CGFloat>>> {
        get {
            AnimatablePair(
                AnimatablePair(startPoint.x, startPoint.y),
                AnimatablePair(elevation, AnimatablePair(endPoint.x, endPoint.y))
            )
        }
        set {
            startPoint = CGPoint(x: newValue.first.first, y: newValue.first.second)
            elevation = newValue.second.first
            endPoint = CGPoint(x: newValue.second.second.first, y: newValue.second.second.second)
        }
    }

    func path(in rect: CGRect) -> Path {
        // Código de desenho
    }
}

Depois do macro @Animatable

@Animatable
struct HikingRouteShape: Shape {
    var startPoint: CGPoint
    var endPoint: CGPoint
    var elevation: Double

    @AnimatableIgnored
    var drawingDirection: Bool // Excluído da animação

    func path(in rect: CGRect) -> Path {
        // Código de desenho
    }
}

Linhas de código: 20 → 12 (redução de 40%)

@AnimatableIgnored

Use @AnimatableIgnored para excluir propriedades da animação.

Quando usar

  • Valores de depuração — Flags apenas para desenvolvimento
  • IDs — Identificadores que não devem ser animados
  • Timestamps — Quando a view foi criada/atualizada
  • Estado interno — Contabilidade não visual
  • Tipos não VectorArithmetic — Cores, strings, booleanos

Exemplo

@MainActor
@Animatable
struct ProgressView: View {
    var progress: Double // Animado
    var totalItems: Int // Animado (se Float, não se Int)

    @AnimatableIgnored
    var title: String // Não animado

    @AnimatableIgnored
    var startTime: Date // Não animado

    @AnimatableIgnored
    var debugEnabled: Bool // Não animado

    var body: some View {
        VStack {
            Text(title)
            ProgressBar(value: progress)
            if debugEnabled {
                Text("Iniciado: \(startTime.formatted())")
            }
        }
    }
}

Casos de Uso Reais

Animações numéricas são extremamente comuns em várias categorias de aplicativos:

Aplicativos Fintech

@MainActor
@Animatable
struct StockPriceView: View {
    var price: Double
    var changePercent: Double

    var body: some View {
        VStack(alignment: .trailing) {
            Text("$\(price, format: .number.precision(.fractionLength(2)))")
                .font(.title)
            Text("\(changePercent > 0 ? "+" : "")\(changePercent, format: .percent)")
                .foregroundColor(changePercent > 0 ? .green : .red)
        }
    }
}

Caso de uso: Animar mudanças de preço de ações, valor de portfólio, transições de saldo de conta

Saúde e Fitness

@MainActor
@Animatable
struct HeartRateView: View {
    var bpm: Double

    @AnimatableIgnored
    var timestamp: Date

    var body: some View {
        VStack {
            Text("\(Int(bpm))")
                .font(.system(size: 60, weight: .bold))
            Text("BPM")
                .font(.caption)
                .foregroundColor(.secondary)
        }
    }
}

Caso de uso: Indicadores de frequência cardíaca, contadores de passos, cálculos de calorias, distância percorrida

Jogos

@MainActor
@Animatable
struct ScoreView: View {
    var score: Float
    var multiplier: Float

    var body: some View {
        HStack {
            Text("\(Int(score))")
                .font(.largeTitle)
            Text("×\(multiplier, format: .number.precision(.fractionLength(1)))")
                .font(.title2)
                .foregroundColor(.orange)
        }
    }
}

Caso de uso: Animações de pontuação, transições de XP, progresso de nível, multiplicadores de combo

Aplicativos de Produtividade

@MainActor
@Animatable
struct TimerView: View {
    var remainingSeconds: Double

    // ... continuação do markdown original ...

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 CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

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