Quando Usar APIs Imperativas ou Declarativas

O React incentiva um estilo declarativo: você descreve como a interface deve se parecer para um determinado estado, e o React reconcilia o DOM para corresponder a isso. A maior parte do comportamento flui por propriedades e estado, em vez de comandos diretos ao DOM.

Esse modelo torna as interfaces previsíveis, pois a saída renderizada é uma função pura do estado, e não o resultado de uma sequência de mutações manuais.

Algumas interações resistem a uma expressão puramente declarativa. Focar um elemento de forma imperativa, disparar uma animação em um momento preciso ou controlar um componente DOM de terceiros muitas vezes não pode ser representado de forma limpa como uma função do estado.

Nesses casos, o React oferece mecanismos de escape, como referências e referências imperativas, usados com moderação quando as propriedades declarativas não são suficientes.

APIs imperativas envolvem compromissos. Elas são mais difíceis de testar, pois é necessário acionar métodos e observar efeitos colaterais, e podem romper o fluxo unidirecional de dados que torna os aplicativos React fáceis de acompanhar.

As chamadas imperativas também tendem a espalhar o comportamento por vários manipuladores de eventos, em vez de concentrá-lo em um mapeamento claro de estado para interface, aumentando o custo de manutenção.

Prefira APIs declarativas e recorra às imperativas apenas para interações e medições: foco, rolagem, animações, reprodução de mídia e leitura de tamanhos ou posições.

Se algo puder ser modelado como um estado que corresponda à saída renderizada, faça isso. Se for uma ação momentânea sem uma representação clara em estado, uma referência imperativa é apropriada.

Um modal declarativo renderiza com base em uma propriedade isOpen pertencente ao componente pai, portanto sua visibilidade é controlada pelo estado. Um modal imperativo expõe métodos de abertura e fechamento, ocultando seu próprio estado atrás de uma referência.

A versão declarativa se encaixa melhor no fluxo de dados do React e geralmente é preferida, enquanto a versão imperativa pode ser conveniente quando o acionamento precisa ocorrer a partir de código disperso e orientado por eventos.

Você pode redefinir um formulário de forma declarativa alterando sua propriedade de chave, o que força o React a montá-lo novamente do zero com o estado padrão. Nenhuma chamada imperativa é necessária.

A alternativa imperativa expõe um método de redefinição em uma referência. O truque da chave costuma ser mais limpo porque aproveita a reconciliação do React em vez de limpar o estado manualmente.

O roteador do Next.js expõe métodos imperativos como enviar, substituir e pré-carregar. Pré-carregar uma rota antes de uma provável navegação é uma ação, não parte do estado de renderização, portanto uma chamada imperativa se encaixa naturalmente.

Isso mostra que até as ferramentas idiomáticas do React usam APIs imperativas quando a operação é fundamentalmente uma ação acionada em um determinado momento.

A orientação oficial apresenta referências e referências imperativas como mecanismos de escape, ferramentas para sair do modelo declarativo quando isso é realmente necessário. Elas não são a forma padrão de criar funcionalidades.

Manter essa mentalidade evita o uso excessivo: recorra a um mecanismo de escape somente depois de confirmar que propriedades e estado não conseguem expressar o comportamento de forma limpa.

Antes de adicionar uma referência imperativa, pergunte: isso pode ser um estado mapeado para a interface? Se sim, mantenha uma abordagem declarativa. É um foco, uma rolagem, uma medição, uma animação ou uma ação de terceiros? Se sim, o uso imperativo pode ser justificado.

Confirme também que a superfície é pequena e documentada e que você não está usando uma referência simplesmente para transmitir dados que uma propriedade poderia carregar.

Aplicativos reais combinam as duas abordagens. A grande maioria da lógica permanece declarativa, com uma fina camada de referências imperativas para o pequeno conjunto de interações que precisa delas.

Alcançar esse equilíbrio mantém seu código previsível e testável, além de permitir o gerenciamento de foco, o controle de mídia e a integração de bibliotecas quando o código declarativo não consegue alcançar esses recursos.

Escolha quando uma API imperativa é a ferramenta adequada.

O React usa por padrão uma interface declarativa orientada por propriedades e estado, que é previsível e testável. Referências imperativas existem como mecanismos de escape para foco, rolagem, animação, medição e controle de DOM de terceiros.

Compare modais declarativos e imperativos, prefira a propriedade de chave para redefinir formulários e lembre-se de que até o roteador do Next.js usa métodos imperativos para ações. Mantenha a camada imperativa pequena, documentada e justificada.