Recomposed
Animation

animate*AsState vs Animatable: Animação É Apenas um Valor Interpolado

Oct 10, 2026 · 7 min read

animate*AsState vs Animatable: Animação É Apenas um Valor Interpolado

A intuição

Vindo do Android baseado em Views, ou da maioria dos toolkits de UI imperativos, "animar algo" parece ser uma ação que você executa. Você pega um objeto, um ObjectAnimator, um UIViewPropertyAnimator, entrega a ele uma duração e um alvo, e chama .start(). A animação é algo que roda sobre uma view, separadamente do resto do seu código, e você precisa se lembrar de chamar .cancel() nela se uma nova animação for disparada antes da anterior terminar.

animate*AsState e Animatable parecem, de fora, o mesmo tipo de API: uma duração, uma curva de suavização, um valor-alvo. O modelo mental por baixo, no entanto, é diferente:

  • Não existe um objeto de animação anexado a um composable da mesma forma que um ObjectAnimator é anexado a uma View. O que existe é um valor, e a leitura atual desse valor em qualquer frame dado é simplesmente "onde quer que a esteja atualmente" em seu caminho em direção ao alvo mais recente.
  • Você nunca chama .start() ou .cancel() sozinho no caso comum. Você muda o alvo, alterando um mutableStateOf simples, e a animação percebe que o alvo se moveu e se reorienta por conta própria.
  • Se o alvo mudar novamente em pleno voo (o usuário toca duas vezes rápido), nada precisa ser parado e reiniciado. O valor simplesmente se curva em direção ao novo alvo a partir de onde quer que esteja atualmente.

Exemplo concreto: um valor que salta vs um valor que é animado

// jump: expanded flips instantly, size flips with it, no animation at all
var expanded by remember { mutableStateOf(false) }
val size = if (expanded) 200.dp else 100.dp
 
Box(Modifier.size(size).background(Color.Blue))
// animated: same boolean, same target expression, but size is now a read
// of an interpolated value instead of the raw target
var expanded by remember { mutableStateOf(false) }
val size by animateDpAsState(targetValue = if (expanded) 200.dp else 100.dp)
 
Box(Modifier.size(size).background(Color.Blue))

A única coisa que mudou é de onde size é lido. expanded continua alternando instantaneamente em ambas as versões, não existe algo como um "booleano animado". animateDpAsState apenas se posiciona entre esse alvo e o size que você lê, suavizando o que você vê na tela a cada frame sem você tocar em expanded de forma alguma.

Mais casos: Animatable é o mesmo mecanismo, na mão

animate*AsState é o wrapper de conveniência. Animatable é a mesma ideia com o wrapper removido, para que você possa ver o que ele está realmente fazendo:

var target by remember { mutableStateOf(0f) }
val offset = remember { Animatable(0f) }
 
LaunchedEffect(target) {
    // retargets automatically: if offset is already mid-flight toward an
    // older target, this cancels that run and continues from wherever
    // offset currently sits, toward the new target
    offset.animateTo(target, animationSpec = spring())
}
 
Row {
    Button(onClick = { target = 0f }) { Text("0f") }
    Button(onClick = { target = 120f }) { Text("120f") }
}

Isso está fazendo, na mão, exatamente o que esse one-liner faz por você:

val offset by animateFloatAsState(targetValue = target, animationSpec = spring())

Toque nos dois botões abaixo como nos daquele código, incluindo toques rápidos, em pleno voo. A curva é a mesma de spring() que o Compose usa por padrão (Spring.StiffnessMedium, Spring.DampingRatioNoBouncy), não uma curva de suavização genérica representando-a:

offset.value = 0.0f — animating toward target 0

tap the other button mid-flight: the curve bends toward the new target instead of resetting to zero

Internamente, animateFloatAsState guarda um Animatable na memória e lança um com chave no alvo, cujo corpo é essa mesma chamada animateTo. O motivo para usar Animatable diretamente em vez do wrapper *AsState é controle: animateTo é uma função suspend, então você pode fazer await nela e executar código após a animação realmente se estabilizar; snapTo salta para um valor sem nenhuma interpolação, útil para resetar o estado sem uma animação visível; e animateDecay permite que um fling continue sob seu próprio momentum em vez de perseguir um alvo fixo.

O fundamental

Isso é animação baseada em valor. A "animação" é apenas um valor Animatable mais uma em execução que continua escrevendo novos valores interpolados nele, frame a frame, em direção a qualquer alvo que tenha recebido pela última vez, seguindo a curva descrita por um . animate*AsState é uma instância gerenciada exatamente disso: um Animatable guardado na memória mais um LaunchedEffect que chama animateTo(target) toda vez que o alvo muda. Não existe um objeto "player" separado sentado fora do próprio valor, o valor é a animação.

Toda a família animate*AsState

Toda função animate*AsState tipada é exatamente o mesmo wrapper Animatable + LaunchedEffect da seção anterior, apenas pré-preenchida com um TwoWayConverter para um tipo específico, a peça que sabe como transformar esse tipo em um vetor de floats e voltar para que uma spring ou tween tenha algo para interpolar.

FunçãoAnimaNotas
animateFloatAsStateFloato caso base; a maioria das outras são isso com um tipo envolto em torno dele
animateDpAsStateDpo mesmo que Float, apenas envolto em uma unidade
animateIntAsStateIntarredonda para um número inteiro a cada frame
animateIntOffsetAsStateIntOffsetx/y em pixels inteiros, ex: Modifier.offset { }
animateIntSizeAsStateIntSizelargura/altura em pixels inteiros
animateOffsetAsStateOffsetx/y em float, ex: uma posição arrastada
animateSizeAsStateSizelargura/altura em float
animateRectAsStateRecttodas as quatro bordas, animadas juntas
animateColorAsStateColorvive em um artefato animation separado do resto, já que Color traz consigo o módulo de gráficos que animation-core de outra forma evita depender
animateValueAsStatequalquer Ta forma genérica por baixo de todas as acima; entregue a ela seu próprio TwoWayConverter<T, V> e ela animará um tipo que nenhuma das funções nomeadas cobre

Não existe um animateBooleanAsState, e isso não é um descuido: um Boolean não tem nada para interpolar entre, é um de dois valores sem nada no meio. Animar "entre" true e false sempre, na verdade, significa animar algum outro tipo que representa os dois estados, um alpha Float, uma Color, um tamanho Dp, com o booleano apenas decidindo em direção a qual alvo esse valor deve se mover.

Onde você realmente usaria isso

  • Feedback de toque. animateFloatAsState controlando um scale ou alpha a partir de interactionSource.collectIsPressedAsState(), de forma que um botão visivelmente se comprima ou escureça no instante em que é pressionado, depois volte com uma spring ao ser liberado.
  • Expandir/recolher. animateDpAsState na height de um card (ou um Modifier.size), alternado pelo mesmo booleano que troca o conteúdo, de forma que o container redimensione em vez de saltar entre duas alturas.
  • Destaque de seleção. animateColorAsState no background de um item de lista, alternado por uma flag de selecionado, de forma que trocar a seleção faça um crossfade da cor de destaque em vez de piscá-la ligada e desligada.
  • Arrastar para dispensar. Animatable controlado diretamente dentro de Modifier.pointerInput: snapTo em cada delta de arraste para um rastreamento exato 1:1 sob o dedo, e então animateTo(0f) para voltar no lugar ou animateDecay para deixá-lo voar para fora da tela, dependendo de o arraste ter cruzado um limite de dispensa ao ser liberado.
  • Progresso que não avança em saltos discretos. animateFloatAsState na fração de uma barra de progresso, com o estado subjacente sendo atualizado apenas na granularidade que o trabalho real reporta, de forma que a própria barra forneça a suavidade em vez de a fonte de dados precisar fazer isso.
  • Executar código apenas quando o movimento realmente termina. Animatable aguardado com animateTo dentro de uma coroutine, de forma que o callback de dispensa de um snackbar, ou a reativação de um botão, seja disparado quando o deslizamento para fora tiver visivelmente terminado, não no instante em que o estado-alvo mudou.

Em outros lugares: o mesmo fundamento, framework diferente

  • Flutter: existe exatamente a mesma divisão, apenas com nomes diferentes. AnimatedContainer, AnimatedOpacity, e o resto da família ImplicitlyAnimatedWidget funcionam como animate*AsState, você muda uma propriedade-alvo e o widget se reconstrói em direção a ela por conta própria. AnimationController combinado com um Tween é o equivalente ao Animatable: a mesma interpolação subjacente, com controle direto sobre iniciar, parar e ler o valor em pleno voo.
  • Transições CSS: transition: width 0.3s ease em um elemento significa que você nunca chama nada para "iniciar" uma animação. Você apenas muda o width (alternando uma classe, por exemplo), e o navegador interpola do valor computado antigo para o novo, o mesmo comportamento de reorientação que animateDpAsState reagindo a um novo targetValue.
  • SwiftUI: .animation(_:value:) é a metade implícita, no formato de animate*AsState, conecte-a a uma propriedade @State e toda mudança nessa propriedade anima automaticamente. withAnimation { } envolvendo uma mutação de estado explícita é a metade no formato de Animatable: você ainda está animando um valor, apenas disparando e delimitando-o você mesmo em vez de deixar um modifier observar as mudanças.

Onde isso realmente pega as pessoas

Usar a chave errada no LaunchedEffect

// wrong: Unit never changes, so this effect runs once on first
// composition and never again. offset.animateTo runs exactly once,
// toward whatever target happened to be at that moment.
LaunchedEffect(Unit) {
    offset.animateTo(target)
}
// right: keyed on target, so the effect relaunches, and retargets,
// every time target actually changes
LaunchedEffect(target) {
    offset.animateTo(target)
}

Toda mudança posterior em target é silenciosamente ignorada na primeira versão, porque nada dispara novamente o bloco. Animatable não sabe que seu valor mudou; apenas um LaunchedEffect com chave nesse valor sabe.

Esquecer o remember em torno do Animatable

// wrong: a brand-new Animatable(0f), reset to 0f, on every recomposition
val offset = Animatable(0f)
// right: the same instance survives recomposition, so it can actually
// finish animating instead of restarting from 0f each time
val offset = remember { Animatable(0f) }

Sem remember, o valor nunca termina de fato de animar até seu alvo. Ele continua sendo recriado do zero e reiniciando, o que parece tremulação ou um valor que fica travado perto de seu ponto de partida.

Misturar uma leitura animada com uma leitura bruta do mesmo alvo

// mismatch: color crossfades, but size jumps instantly, even though
// both are supposedly animating off the same `selected` boolean
val color by animateColorAsState(if (selected) Color.Blue else Color.Gray)
val size = if (selected) 56.dp else 48.dp

Esse é o mesmo bug do primeiro exemplo deste post, apenas reintroduzido por acidente quando um composable tem mais de uma propriedade controlada pelo mesmo alvo. Corrigi-lo é o mesmo movimento daquele exemplo: passar size por animateDpAsState também.

Modelo mental para realmente usar

Você não está dizendo ao Compose para tocar uma animação; você está entregando a ele um novo valor-alvo, e o Animatable por baixo continua interpolando em direção a qualquer alvo que tenha recebido mais recentemente.

Keep reading

Related reads

Receba novos posts no seu e-mail