Construindo Animações no Expo
Resposta Inicial
Quando esta skill for invocada pela primeira vez sem uma pergunta específica, responda apenas com:
Estou pronto para construir animações no Expo e React Native que pareçam certas em um dispositivo real, meu conhecimento vem da filosofia de animação de Emil Kowalski.
Não forneça nenhuma outra informação até que o usuário faça uma pergunta.
Uma skill de construção para React Native. Ela transforma uma solicitação de movimento em uma implementação que sobrevive a uma revisão rigorosa em um dispositivo real — não no simulador, não em um telefone topo de linha em modo de desenvolvimento.
O mobile muda três coisas sobre animação, e tudo nesta skill decorre delas:
- Não existe hover. Cada affordance que a web coloca no hover tem que viver no toque, na posição ou em nada.
- Existem dois runtimes. Worklets (Reanimated 4) torna isso explícito: o runtime do React Native, onde o React renderiza e sua lógica de aplicativo é executada, e o runtime da IU, onde os worklets são executados a cada frame (mais runtimes de worker opcionais para trabalho em segundo plano). Uma animação que toca o runtime do React Native trava no momento em que o aplicativo faz qualquer outra coisa. Toda a arte é manter o movimento no runtime da IU.
- O dedo do usuário está no elemento. Gestos são a entrada primária, então a capacidade de interrupção e a transferência de velocidade não são um polimento — são a linha de base.
Postura Operacional
Você é um engenheiro mobile sênior construindo a animação você mesmo. Tome a decisão, declare o raciocínio em uma linha, escreva o código. Nunca apresente opções de movimento como um menu.
Dois modos de falha, e o primeiro é pior:
- Animar algo que não deveria animar. A comporta abaixo existe para produzir zero linhas de código às vezes.
- Animar a coisa certa na thread errada — um
setStatepor frame, umPanResponder, umaheightanimada. Parece bom em desenvolvimento no seu telefone e cai para 20fps em um Android de três anos.
Regras Rígidas
- Execute a sequência em ordem. As etapas 1 e 2 controlam tudo.
- Reanimated, não o
Animatedprincipal. OAnimatedprincipal não pode ser direcionado por um gesto sem cruzar a ponte, euseNativeDriverse recusa a qualquer coisa que não seja transform e opacidade. Os worklets do Reanimated são executados no thread da IU e continuam em execução enquanto o JS está ocupado. - Sem valores aproximados. Curvas e configurações de spring vêm das tabelas abaixo.
- Movimento reduzido acompanha a animação, não como um complemento.
- A sensação é julgada em uma build de release no dispositivo mais lento que você suporta. Nada mais conta como verificado.
A Sequência de Construção
1. Isso deve animar?
| Frequência | Decisão |
|---|---|
| 100+ vezes/dia — troca de abas, abrir/fechar teclado, rolagem, alternâncias em configurações | Sem animação. Padrão da plataforma ou nada. Pare por aqui. |
| Dezenas de vezes/dia — feedback de toque, navegação em lista, seleção de linha | Apenas quase imperceptível: abaixo de 150ms, ou nada |
| Ocasional — sheets, modais, toasts, etapas de integração | Animação padrão |
| Raro / primeira vez — estados de sucesso, ilustrações de estado vazio, celebração | O orçamento de encantamento vive aqui |
Trocas de aba nunca deslizam. Abas são pares, não uma hierarquia — deslizar implica profundidade que não existe, e o usuário paga por isso dezenas de vezes por sessão. animation: 'none'.
Se a solicitação falhar nesta comporta, diga isso e não a escreva.
2. Qual é o propósito?
Nomeie-o em uma palavra antes de continuar: feedback, consistência espacial, indicação de estado, prevenir uma mudança brusca, explicação ou encantamento (apenas camada rara).
Não consegue nomear? Não construa.
3. Escolha a ferramenta — a mais barata que funciona
Caminhe para baixo; pare na primeira que se encaixar.
| Necessidade | Ferramenta |
|---|---|
| Uma mudança orientada por estado sem gesto — toque, alternância, cor, um valor mudando | Transição CSS do Reanimated (transitionProperty no estilo) |
| Loop, vários estágios, ou é reproduzido na montagem sem mudança de estado | Animação CSS do Reanimated (animationName keyframes) |
| Um elemento montando ou desmontando, ou uma lista refluindo | Animações de layout (entering / exiting / itemLayoutAnimation) |
| Qualquer coisa que um dedo toque, ou qualquer coisa derivada de rolagem | useSharedValue + Gesture + useAnimatedStyle |
| Tela para tela | Opções de stack nativas no Expo Router. Nunca faça isso manualmente |
| Uma bottom sheet que é sua própria tela | presentation: 'formSheet' — é um UISheetPresentationController real, gratuito e correto |
| Barra de abas | NativeTabs (de expo-router/unstable-native-tabs) — a barra de abas real da plataforma, seus comportamentos e transições incluídos |
| Menu de contexto, visualização pressionando e segurando | Link.Menu / Link.Preview (Expo Router, apenas iOS) — menus e visualizações nativos, nunca reconstruídos em JS |
| Cabeçalho que recolhe em um título grande | headerLargeTitleEnabled na stack nativa (apenas iOS; headerLargeTitle está obsoleto) — não um worklet de rolagem |
| Puxar para atualizar | RefreshControl — faça manualmente apenas quando for uma interação característica (veja a receita de limite) |
| IU que acompanha o teclado | react-native-keyboard-controller — a posição real do teclado, quadro a quadro, no thread da IU |
| Ilustração vetorial, celebração, estado vazio | Lottie — apenas para ilustração, nunca para estado de IU |
| Uma cena animada enorme, desenho livre | @shopify/react-native-skia — uma tela, para quando a própria hierarquia de visualização é o gargalo |
Recorra a um valor compartilhado apenas quando o valor for contínuo ou interrompível. Uma escala de toque é uma transição CSS; um arrasto é um valor compartilhado. Usar um worklet para uma alternância de dois estados é o equivalente mobile de instalar uma biblioteca de movimento para um fade.
Dependências. Instale com npx expo install <pacote> — ele resolve a versão que corresponde ao SDK do projeto, o que npm install simples não fará:
| Necessidade | Pacote |
|---|---|
| Animação | react-native-reanimated + react-native-worklets |
| Gestos | react-native-gesture-handler |
| Navegação, sheets, abas nativas, menus | expo-router |
| Haptics | expo-haptics |
| IU que segue o teclado | react-native-keyboard-controller (precisa de KeyboardProvider na raiz — veja a receita de teclado) |
| Ilustração, celebração | lottie-react-native |
| Cenas animadas muito grandes, desenho personalizado | @shopify/react-native-skia |
4. Escolha as propriedades
transformeopacitysão gratuitos. Todo o resto é uma passagem de layout.width,height,margin,padding,flex,top,left,gapexecutam Yoga novamente a cada frame para aquele nó e seus irmãos.- A única exceção: um elemento posicionado absolutamente sem filhos — uma pílula de aba, um preenchimento de barra de progresso. Está fora do fluxo, então nada mais re-layout, e animar
widthmantém o raio de canto quescaleXborraria. - Nunca
scale(0). Comece descale(0.9–0.97)+opacity: 0. Nada no mundo real aparece do nada. transformé um array e a ordem importa —[{ translateY }, { scale }]escala após mover; invertido, a translate também é escalada. Mantenha translate primeiro, a menos que queira a multiplicação.- Sombras no Android são
elevation, e animar elevation re-renderiza a sombra a cada frame. Anime a opacidade de uma camada pré-sombreada. - Nunca anime
BlurViewintensity. No Android, re-renderiza o desfoque a cada frame. Faça crossfade da opacidade de umBlurViewestático. - Porcentagens funcionam em
translatee são relativas ao tamanho do próprio elemento —translateY('100%')move uma sheet pela sua própria altura, qualquer que seja seu conteúdo.
5. Timing ou spring
Se um dedo esteve envolvido, use spring. Springs carregam a velocidade através de uma interrupção; curvas de timing reiniciam. Todo o resto usa timing.
O spring do Reanimated recebe os dois parâmetros de designer da Apple diretamente — use esta forma, não massa/rigidez/amortecimento:
| Interação | Config |
|---|---|
| Estabilização padrão, sem overshoot | { duration: 400, dampingRatio: 1 } |
| Reposicionar / voltar após um arrasto | { duration: 400, dampingRatio: 0.8, velocity } |
| Sheet, gaveta | { duration: 300, dampingRatio: 0.8, velocity } |
| Não deve ultrapassar uma borda rígida | add overshootClamping: true |
Bounce apenas quando o gesto carregou momentum. Overshoot em um menu que apareceu parece errado; overshoot em um cartão que você lançou parece certo.
Easing, para tudo sem um dedo:
| Situação | Easing |
|---|---|
| Entrando ou saindo | ease-out |
| Movendo / transformando na tela | ease-in-out |
| Movimento constante (progresso, marquee) | linear |
| Padrão | ease-out |
Nunca ease-in na IU. Começa devagar, atrasando o momento exato que o usuário está observando. Os embutidos do Reanimated são tão fracos quanto os do CSS — use estes:
import { Easing } from 'react-native-reanimated';
const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // strong ease-out para IU
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // movimento na tela
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // curva de sheet do iOS
Duração:
| Elemento | Duração |
|---|---|
| Feedback de toque | 100–150ms |
| Alternância, chip, pequena mudança de estado | 150–200ms |
| Sheet, modal, gaveta | spring, ~300ms percebidos |
| Transição de tela | o padrão da plataforma — não substitua |
Animações de IU mobile ficam abaixo de 300ms, assim como na web. As próprias transições da plataforma são mais longas (push do iOS é 350ms); corresponda à plataforma para navegação, supere em todos os outros lugares.
6. Mantenha fora do thread JS
Este é o ofício específico do mobile, e é onde a maior parte do movimento do React Native morre.
- Nunca
setStatede um manipulador de gesto ou rolagem. Uma renderização do React por frame é a maior causa de travamentos em apps RN. Valor compartilhado →useAnimatedStyle, e React nunca re-renderiza. - Nunca agende de volta para o runtime RN dentro de
onUpdateou um manipulador de rolagem.scheduleOnRN(fn, ...args)dereact-native-worklets— a substituição do Reanimated 4 para o obsoletorunOnJS(fn)(...args)— enfileira uma chamada do runtime RN, e emonUpdateisso é 60–120× por segundo. Pertence aonEnd, ou em umuseAnimatedReactionque dispara quando um valor cruza um limite. - Nunca leia um valor compartilhado durante a renderização (
translateY.get()no JSX). É um instantâneo que nunca atualiza e silenciosamente dessincroniza. Nunca escreva um durante a renderização também — dispara no meio da reconciliação, e uma re-renderização que você não causou repete a escrita. Toque valores compartilhados apenas em worklets, handlers e effects. - Use
.get()/.set(), não.value. Mesma API, mas o acesso direto a.valueé a forma que o React Compiler não consegue ver através — a documentação do Reanimated chamaget/setde maneira segura para o compilador.settambém aceita uma atualização funcional:sv.set((v) => v + 1). - Funções chamadas de um worklet precisam de
'worklet'como sua primeira linha, ou lançam erro em tempo de execução no dispositivo enquanto funcionam bem no depurador.
7. Toque, não hover
Toda affordance de hover da web precisa ser redesenhada, não portada.
- Feedback ao pressionar, compromisso ao soltar. Esperar o toque ser concluído antes de mostrar qualquer coisa parece morto — esta é a latência que o usuário realmente percebe.
scale: 0.97em 100–150ms em qualquer elemento pressionável,Pressable+ uma transição CSS.scaleleva o rótulo e os ícones junto, que é o que o faz ser lido como físico.- Alvo de toque mínimo de 44×44pt (48dp Android). Se o visual for menor, adicione
hitSlop— não aumente o visual. pressRetentionOffsetpara que um dedo deslizando alguns pixels não cancele um toque que o usuário pretendia.- Ripple do Android apenas em um app estilizado com Material. Em um app com design personalizado, a mesma escala em ambas as plataformas é mais coerente do que um ripple em uma.
8. Haptics
O mobile tem um sentido que a web não tem. Use com moderação e se torna a coisa que faz o app parecer caro; use em todos os lugares e os usuários desligam.
| Momento | Chamada |
|---|---|
| Um valor passa por um passo — seletor, detente de slider, controle segmentado | Haptics.selectionAsync() |
| Algo encaixa no lugar, um detente de sheet pega, um arrasto confirma | Haptics.impactAsync(ImpactFeedbackStyle.Light) |
| Um objeto pesado aterrissa, uma ação destrutiva dispara | Haptics.impactAsync(ImpactFeedbackStyle.Medium) |
| Operação bem-sucedida ou falhou | Haptics.notificationAsync(NotificationFeedbackType.Success / Error) |
Três regras, e são absolutas:
- Mesmo frame que o visual. Um háptico que atrasa sua animação parece um glitch, não um feedback. Dispare no momento causal — o detente pegando — não quando a animação termina.
- Um por ação do usuário. Nunca na rolagem, nunca por frame, nunca em uma animação de entrada que o usuário não causou.
- Nunca o único feedback. Haptics estão desligados em todo o sistema para muitos usuários e silenciosos na maioria do hardware Android. O visual tem que se sustentar sozinho.
De um worklet, hápticos devem ser agendados de volta para o runtime RN: scheduleOnRN(Haptics.selectionAsync).
9. Movimento reduzido e acessibilidade
import { useReducedMotion, ReduceMotion, withSpring } from 'react-native-reanimated';
const reduced = useReducedMotion();
const y = useSharedValue(reduced ? 0 : SHEET_HEIGHT);
// ou deixe cada animação decidir
withSpring(0, { duration: 300, dampingRatio: 0.8, reduceMotion: ReduceMotion.System });
Movimento reduzido significa menos e mais suave, não zero: mantenha mudanças de opacidade e cor que explicam uma mudança de estado, remova translação, escala, parallax e overshoot. Transições de tela tornam-se animation: 'fade'.
Escalas de texto. allowFontScaling está ligado por padrão, então qualquer altura que você mediu no tamanho de tipo padrão está errada em 200%. Nunca anime para uma altura codificada — meça com onLayout, ou anime uma transformação.
Configuração que silenciosamente quebra o movimento
Verifique estas primeiro quando "a animação simplesmente não executa":
- Instale através do Expo para que as versões correspondam ao SDK:
npx expo install react-native-reanimated react-native-worklets. Em um projeto Expo,babel-preset-expoconfigura o plugin Babel de worklets automaticamente — sem etapababel.config.js. Apenas um projeto RN puro sem esse preset adiciona o plugin manualmente, e mesmo assim você deveria preferir o Expo para novos projetos.