Animação 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, a macro @Animatable do iOS 26, tipos de animação e o sistema de Transações.
Princípio central Animação no SwiftUI é interpolação matemática ao longo do tempo, alimentada pelo protocolo VectorArithmetic. Entender essa base libera todo o poder do sistema de animação declarativo do SwiftUI.
Requisitos de Sistema
- iOS 13+: Protocolo Animatable, animações timing/spring
- iOS 17+: Animações spring padrão, animações escopo, PhaseAnimator, KeyframeAnimator
- iOS 18+: Transições de zoom, ponte de animação UIKit/AppKit
- iOS 26+: Macro @Animatable
Parte 1: Entendendo Animação
O que é Interpolação
Animação é o processo de gerar valores intermediários entre um estado inicial e 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 requer que os dados animados estejam em conformidade com VectorArithmetic — fornecendo subtração, escalonamento, adição e um valor zero. Isso permite que o SwiftUI interpole entre quaisquer dois valores.
Tipos conformes embutidos: CGFloat, Double, Float, Angle (1D), CGPoint, CGSize (2D), CGRect (4D).
Insight chave A aritmética vetorial abstrai sobre a dimensionalidade. O SwiftUI anima 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 — não existem intermediários fracionários entre 3 e 4. O SwiftUI simplesmente define o valor instantaneamente.
Solução: Use Float/Double e exiba como Int:
@State private var count: Float = 0
// ...
Text("\(Int(count))")
.animation(.spring, value: count)
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 corpo 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.5ao longo do tempo
Parte 2: Protocolo Animatable
Visão Geral
O protocolo Animatable permite que views animem suas propriedades definindo quais dados devem ser interpolados.
protocol Animatable {
associatedtype AnimatableData: VectorArithmetic
var animatableData: AnimatableData { get set }
}
O SwiftUI constrói um atributo animável para qualquer view em conformidade com este protocolo.
Views Animáveis Embutidas
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 Shape
Circle,Rectangle,RoundedRectangleCapsule,Ellipse,Path- Implementações customizadas de
Shape
AnimatablePair para Dados Multidimensionais
Ao animar múltiplas propriedades, use AnimatablePair para combinar vetores. Por exemplo, scaleEffect combina CGSize (2D) e UnitPoint (2D) em um vetor 4D via AnimatablePair<CGSize.AnimatableData, UnitPoint.AnimatableData>. Acesse componentes via .first e .second. A macro @Animatable (iOS 26+) elimina completamente essa burocracia.
Conformidade Animatable Customizada
Quando usar
- Animando layout customizado (como RadialLayout)
- Animando código de desenho customizado
- Animando propriedades que afetam caminhos de formas (paths)
Exemplo: Visualização 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
numbermuda de 0 para 100- O SwiftUI chama
bodypara cada quadro da animação - Cada quadro recebe um novo valor
number: 0 → 5 → 15 → 30 → 55 → 80 → 100 - O Text é atualizado para mostrar o inteiro interpolado
Aviso de Performance
A conformidade Animatable customizada é cara — O SwiftUI chama body para cada quadro na thread principal. Efeitos embutidos (.scaleEffect(), .opacity()) são executados fora da thread principal e não chamam body. Use conformidade customizada apenas quando modificadores embutidos não conseguem atingir o efeito (ex.: animar um Layout customizado que reposiciona subviews por quadro).
Parte 3: Macro @Animatable (iOS 26+)
Visão Geral
A macro @Animatable elimina a burocracia de conformar manualmente ao protocolo Animatable.
Antes do iOS 26, você tinha que:
- Conformar manualmente a
Animatable - Escrever getter e setter
animatableData - Usar
AnimatablePairpara múltiplas propriedades - Excluir propriedades não animáveis manualmente
iOS 26+, você apenas adiciona @Animatable:
@MainActor
@Animatable
struct MyView: View {
var scale: CGFloat
var opacity: Double
var body: some View {
// ...
}
}
A macro automaticamente:
- Gera conformidade com
Animatable - Inspeciona todas as propriedades armazenadas
- Cria
animatableDataa partir de propriedades conformes a VectorArithmetic - Lida com dados multidimensionais usando
AnimatablePair
Comparação Antes/Depois
Antes da macro @Animatable
struct HikingRouteShape: Shape {
var startPoint: CGPoint
var endPoint: CGPoint
var elevation: Double
var drawingDirection: Bool // Não quero animar isso
// Declaração tediosa de animatableData manual
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 da macro @Animatable
@Animatable
struct HikingRouteShape: Shape {
var startPoint: CGPoint
var endPoint: CGPoint
var elevation: Double
@AnimatableIgnored
var drawingDirection: Bool // Excluída 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 em: \(startTime.formatted())")
}
}
}
}
Caso de Uso no Mundo Real
@Animatable funciona para qualquer exibição numérica — preços de ações, frequência cardíaca, pontuações, temporizadores, barras de progresso:
@MainActor
@Animatable
struct AnimatedValueView: View {
var value: Double
var changePercent: Double
@AnimatableIgnored
var label: String
var body: some View {
VStack(alignment: .trailing) {
Text("\(value, format: .number.precision(.fractionLength(2)))")
.font(.title)
Text("\(changePercent > 0 ? "+" : "")\(changePercent, format: .percent)")
.foregroundStyle(changePercent > 0 ? .green : .red)
}
}
}
// Uso
AnimatedValueView(value: currentPrice, changePercent: 0.025, label: "Preço")
.animation(.spring(duration: 0.8), value: currentPrice)
Parte 4: Tipos de Animação
Animações de Curva de Tempo (Timing Curve)
Animações de curva de tempo usam curvas bezier para controlar a velocidade da animação ao longo do tempo.
Predefinições embutidas
.animation(.linear) // Velocidade constante
.animation(.easeIn) // Começa devagar, termina rápido
.animation(.easeOut) // Começa rápido, termina devagar
.animation(.easeInOut) // Começo e fim lentos, meio rápido
Curvas de tempo customizadas
let customCurve = UnitCurve(
startControlPoint: CGPoint(x: 0.2, y: 0),
endControlPoint: CGPoint(x: 0.8, y: 1)
)
.animation(.timingCurve(customCurve, duration: 0.5))
Duração
Todas as animações de curva de tempo aceitam uma duração opcional:
.animation(.easeInOut(duration: 0.3))
.animation(.linear(duration: 1.0))
Padrão: 0,35 segundos
Animações Spring
Animações spring usam simulação física para criar movimento natural e orgânico.
Predefinições embutidas
.animation(.smooth) // Sem bounce (padrão desde iOS 17)
.animation(.snappy) // Pequena quantidade de bounce
.animation(.bouncy) // Maior quantidade de bounce
Springs customizadas
.animation(.spring(duration: 0.6, bounce: 0.3))
Parâmetros
duration— Duração percebida da animaçãobounce— Quantidade de bounce (0 = sem bounce, 1 = muito elástico)
Muito mais intuitivo que os parâmetros tradicionais de spring (massa, rigidez, amortecimento).
Animações de Ordem Superior
Modifique animações base para criar efeitos complexos.
Atraso (Delay)
.animation(.spring.delay(0.5))
Aguarda 0,5 segundos antes de iniciar a animação.
Repetição
.animation(.easeInOut.repeatCount(3, autoreverses: true))
.animation(.linear.repeatForever(autoreverses: false))
Repete a animação várias vezes ou infinitamente.
Velocidade
.animation(.spring.speed(2.0)) // 2x mais rápido
.animation(.spring.speed(0.5)) // 2x mais lento
Multiplica a velocidade da animação.
Mudanças na Animação Padrão (iOS 17+)
Antes do iOS 17
withAnimation {
// Usava curva de tempo por padrão
}
iOS 17+
withAnimation {
// Usa .smooth spring por padrão
}
Por que a mudança: Animações spring parecem mais naturais e preservam a velocidade quando interrompidas.
Recomendação: Adote springs. Elas fazem sua UI parecer mais responsiva e polida.
Parte 5: Sistema de Transações (Transaction)
withAnimation
A maneira mais comum de acionar uma animação.
Button("Aumentar Escala") {
withAnimation(.spring) {
scale = 1.5
}
}
Como funciona
withAnimationabre uma transação- Define a animação no dicionário da transação
- Executa a closure (mudanças de estado)
- A transação se propaga para baixo na hierarquia de views
- Atributos animáveis verificam a animação e interpolam
Animação explícita
withAnimation(.spring(duration: 0.6, bounce: 0.4)) {
isExpanded.toggle()
}
Sem animação
withAnimation(nil) {
// As mudanças acontecem imediatamente, sem animação
resetState()
}
Modificador animation()
Aplique animações a valores específicos dentro de uma view.
Uso básico
Circle()
.fill(isActive ? .blue : .gray)
.animation(.spring, value: isActive)
Como funciona: A animação só se aplica quando isActive muda. Outras mudanças de estado não acionarão esta animação.
Múltiplas animações na mesma view
Circle()
.scaleEffect(scale)
.animation(.bouncy, value: scale)
.opacity(opacity)
.animation(.easeInOut, value: opacity)
Animações diferentes para propriedades diferentes.
Animações Escopo (iOS 17+)
Escopo restrito de animações para atributos animáveis específicos.
Problema com a abordagem antiga
struct AvatarView: View {
var selected: Bool
var body: some View {
Image("avatar")
.scaleEffect(selected ? 1.5 : 1.0)
.animation(.spring, value: selected)
// ⚠️ Se a imagem também muda quando selecionado muda,
// a transição da imagem também é animada (acidental)
}
}
Solução: Animação escopo
struct AvatarView: View {
var selected: Bool
var body: some View {
Image("avatar")
.animation(.spring, value: selected) {
$0.scaleEffect(selected ? 1.5 : 1.0)
}
// ✅ Apenas scaleEffect anima, a transição da imagem não
}
}
Como funciona
- A animação só se aplica aos atributos dentro da closure
- Outros atributos não são afetados
- Previne animações acidentais
Chaves de Transação Customizadas
Defina tipos TransactionKey customizados para propagar contexto através do sistema de transações. Use withTransaction para definir valores e o modificador .transaction para lê-los. Isso permite aplicar diferentes animações com base em como uma mudança de estado foi acionada (toque vs. programática).
Parte 6: Tópicos Avançados
Protocolo CustomAnimation
Implemente animações personalizadas substituindo CustomAnimation e definindo lógica de interpolação e velocidade. Exemplo: Animação de batida cardíaca ou animação de salto.