Limites de Suspense e prioridade de transmissão

Os limites Suspense são a unidade fundamental da granularidade da transmissão em fluxo. Cada limite Suspense na sua árvore de componentes cria uma seção que pode ser transmitida de forma independente — o React pode resolver e transmitir cada limite no seu próprio ritmo, independentemente de todos os outros.

A estrutura inicial consiste em tudo que está fora dos limites Suspense — o layout, a navegação, o rodapé e qualquer conteúdo disponível de forma síncrona. A estrutura inicial é transmitida primeiro e rapidamente, fornecendo aos usuários a estrutura da página de imediato enquanto as seções dependentes de dados são carregadas em segundo plano.

Quando o React transmite a estrutura inicial, qualquer limite Suspense cujos dados ainda não estejam disponíveis é renderizado como sua interface alternativa — normalmente um esqueleto de carregamento ou um indicador de carregamento. Essa interface alternativa é incluída na resposta HTML inicial, portanto o usuário vê um indicador de carregamento imediatamente, em vez de um espaço vazio.

Quando os dados de um limite Suspense são resolvidos, o React transmite o HTML resolvido junto com um pequeno script incorporado. Esse script move o conteúdo recém-transmitido de um elemento de modelo oculto para a posição correta no DOM, substituindo a interface alternativa sem recarregar a página inteira.

O React usa o padrão do elemento de modelo do HTML: o conteúdo Suspense resolvido é transmitido para um modelo oculto; em seguida, um script chama uma função interna do React para trocar o conteúdo do modelo pela posição correta no DOM. Isso permite manipular o DOM sem um framework de JS para fazer a substituição.

Os limites Suspense aninhados têm linhas do tempo de resolução independentes. Um limite Suspense interno pode ser resolvido antes do limite externo — o React transmite o conteúdo interno assim que ele está pronto, independentemente de o limite externo ter sido resolvido. Isso maximiza o paralelismo no carregamento de dados.

O posicionamento eficaz do Suspense coloca componentes lentos e dependentes de dados dentro de limites Suspense, e conteúdo rápido, estático ou disponível de forma síncrona fora deles. Barras de navegação, seções de destaque com texto estático e rodapés devem ficar fora. Listas de produtos, painéis do usuário e fluxos de comentários devem ficar dentro.

O React transmite os limites Suspense conforme eles são resolvidos — não necessariamente na ordem em que aparecem no documento. Uma seção abaixo da dobra pode ser resolvida antes de uma seção acima da dobra se exigir menos dados. O React trata a inserção no DOM corretamente, independentemente da ordem da transmissão.

A hidratação seletiva do React 18 responde à interação do usuário: se o usuário clicar ou passar o cursor sobre um limite Suspense que ainda não foi hidratado, o React prioriza a hidratação desse limite. Isso garante que as interações do usuário pareçam responsivas mesmo quando outras partes da página ainda estão sendo hidratadas.

Mais limites Suspense significam mais flexibilidade na transmissão em fluxo, mas um número excessivo adiciona sobrecarga devido aos scripts incorporados de substituição. Uma orientação prática é envolver "seções" inteiras (conteúdo acima da dobra, barra lateral e fluxo abaixo da dobra), em vez de componentes individuais. De um a três limites Suspense por página costuma ser um bom equilíbrio.

Na aba Rede do Chrome DevTools, use "Preservar registro" e observe a transmissão da resposta: o documento HTML cresce em blocos. A aba Desempenho mostra os marcadores FCP e LCP — compare versões com e sem transmissão em fluxo para quantificar a melhoria. Limite a rede a 3G rápido para tornar o efeito mais evidente.

O que acontece com a interface alternativa de um limite Suspense na resposta HTML inicial da transmissão em fluxo?

Os limites Suspense dividem sua árvore do React em seções que podem ser transmitidas de forma independente. A estrutura inicial (fora do Suspense) é transmitida primeiro; as interfaces alternativas aparecem imediatamente para os limites pendentes; e o conteúdo resolvido substitui as interfaces alternativas por meio de scripts incorporados. Os limites aninhados têm linhas do tempo independentes. Posicione os limites no nível das seções para obter a granularidade ideal da transmissão em fluxo e deixe o sistema de prioridade do React cuidar da ordem de hidratação orientada pela interação.