A API Navigation em navegadores modernos

A API de navegação é um substituto mais novo e poderoso para a API de histórico. Ela trata as navegações como objetos de primeira classe que podem ser interceptados, abortados e aguardados — mais próximo da forma como as SPAs realmente precisam lidar com o roteamento em 2024.

window.navigation expõe a lista de entradas, a entrada atual e o evento de navegação. navigation.entries() retorna todas as entradas do histórico atual; navigation.currentEntry é a entrada ativa. Compare isso com o comprimento opaco e o estado não legível da API de histórico.

Escute navigation.addEventListener("navigate", handler) para interceptar toda navegação no mesmo documento — cliques em links, envios de formulários, navegação para trás ou para frente e navegação programática. Um único ponto de interceptação substitui o conjunto fragmentado de interceptação de cliques, escuta do evento de navegação no histórico e ouvintes de envio de formulários.

Chamar e.intercept({ handler }) assume o controle da navegação. A função manipuladora retorna uma promessa; enquanto ela estiver pendente, a navegação estará "em andamento" e o endereço já terá sido atualizado. Isso unifica a antiga condição de corrida entre a alteração do endereço e a renderização da visualização.

Nem todas as navegações podem ser interceptadas (origens cruzadas, transferências). Verifique e.canIntercept antes de chamar intercept. Essa proteção defensiva de uma linha distingue a navegação da SPA de saídas reais para outra origem.

navigation.navigate(url, options) dispara uma navegação programaticamente, de forma equivalente a um clique. O objeto retornado contém as promessas de confirmação e conclusão, para que você possa aguardar a alteração do endereço ou a conclusão total da função manipuladora.

Cada entrada de navegação tem uma chave estável (que permanece entre recarregamentos) e um identificador (por sessão). Use a chave para o estado persistente (posições de rolagem salvas, rascunhos de formulários) e o identificador para o estado transitório. O único estado da API de histórico era um bloco opaco.

navigation.back() e navigation.forward() são atalhos convenientes para traverseTo. Eles retornam o mesmo par de promessas de confirmação e conclusão, para que você possa aguardar a navegação para trás antes de realizar tarefas posteriores.

Se o usuário clicar em um segundo link enquanto o primeiro ainda estiver sendo renderizado, a navegação em andamento poderá ser abortada. O manipulador recebe um AbortSignal por meio de e.signal; passe-o às chamadas de busca para que o trabalho obsoleto seja cancelado quando a nova navegação começar.

A API de Histórico funciona, mas é pouco prática: as alterações de estado e a renderização da visualização ficam desacopladas, o tratamento de cliques é manual, a coordenação entre vários ouvintes é frágil e a restauração da rolagem é incompleta. A API de Navegação foi projetada desde o início para atender às necessidades de SPA e resolve cada um desses problemas.

O Chrome e o Edge oferecem suporte à API de Navegação. O Safari e o Firefox estão atrasados (no início de 2026); publique código que detecte o recurso ("navigation" in window) e use o Histórico com o evento de mudança no histórico como alternativa quando ele não estiver disponível. Frameworks como SvelteKit e o roteador TanStack já encapsulam essa detecção.

Para projetos novos voltados a públicos que priorizam o Chromium, adote-a agora e aceite a alternativa baseada no Histórico. Para sites públicos destinados a um público amplo, aguarde o suporte do Safari e do Firefox (ou use uma biblioteca de roteamento que abstraia ambos). A API mais simples vale a espera.

Qual é a principal vantagem do evento de navegação da API de Navegação em comparação com a combinação do evento de mudança no histórico e da interceptação manual de cliques da API de Histórico?

A API de Navegação unifica a navegação de SPA sob um único evento de navegação, com semântica de interceptação e cancelamento, chaves estáveis por entry e espera assíncrona do manipulador. Ela substitui o conjunto improvisado de Histórico, mudança de estado e interceptação de cliques. Hoje, é compatível com navegadores baseados em Chromium; faça a detecção de recurso e use o Histórico como alternativa em código compatível com vários navegadores até que Safari e Firefox alcancem esse suporte.