30.11.2024

Adicionando um Parâmetro à URL Sem Atualizar a Página: pushState

Resposta Rápida

Adicionar um novo parâmetro à URL sem atualizar a página pode ser feito com o seguinte código:

history.pushState(null, '', `${location.href}&novoParam=valor`);

Esse trecho ativa a função history.pushState(), que acrescenta novoParam=valor à URL atual.

Se você procura uma abordagem mais elegante, utilize os objetos URL e URLSearchParams. Eles simplificam significativamente o trabalho com parâmetros:

const url = new URL(window.location);
url.searchParams.append('novoParam', 'valor');
window.history.pushState({}, '', url);

Dessa forma, novoParam será inserido como um parâmetro de consulta, garantindo codificação automática e uma estrutura de URL consistente.

Gerenciamento Avançado de URLs

Usando window.location e a API de URL, podemos editar a URL de forma detalhada, quebrando-a em seu protocolo, host e caminho para adicionar parâmetros de maneira organizada.

Atualizações Fluidas com replaceState

O método history.replaceState() funciona de maneira semelhante ao pushState(), mas modifica a URL sem adicionar uma nova entrada ao histórico do navegador. Isso é especialmente útil para filtragens e buscas, evitando entulhar o histórico do navegador com alterações desnecessárias.

window.history.replaceState(null, null, '?novoParam=valor');

Codificação de Parâmetros: Segurança em Primeiro Lugar

É crucial codificar chaves e valores de parâmetros se eles contiverem caracteres que possam representar uma ameaça à URL:

const chaveParam = encodeURIComponent('um parâmetro um pouco ousado&nome');
const valorParam = encodeURIComponent('valor com espaços, ou pior');
history.pushState(null, '', `${location.href}?${chaveParam}=${valorParam}`);

Isso garante que a estrutura da sua URL permaneça em conformidade com os padrões.

Abordagem Personalizada com Atualizações Complexas

Se searchParams não atender todas as suas necessidades, você pode recorrer ao gerenciamento direto de strings em combinação com pushState():

let url = new URL(window.location);
let novaUrl = `${url.protocol}//${url.host}${url.pathname}?${funçãoCriarUrlElegante()}`;
window.history.pushState(null, '', novaUrl);

Isso permite que você implemente sua própria lógica para verificar, substituir e adicionar parâmetros.

Visualização

O processo de adicionar um parâmetro a uma URL pode ser visualizado como acoplar um carro a um trem em movimento sem pará-lo:

Trem atual (🚂): [Locomotiva, 🚃 Carro A, 🚃 Carro B]

Adicionando um parâmetro: **Novo Carro (🔗 Param)** é acoplado ao trem.

Antes: 🚂🚃🚃  // O trem (URL) se move normalmente
Depois: 🚂🚃🚃🔗🚃  // O parâmetro (novo carro) adicionado de forma suave

O trem (URL) continua sua jornada sem desviar do seu ritmo, agora incluindo um novo passageiro (parâmetro).

Agrupando Parâmetros

Para facilitar a adição de múltiplos parâmetros de uma só vez, use o método $.param() do jQuery:

let params = { primeiro: 'valor1', segundo: 'valor2' };
let queryString = $.param(params);
history.pushState(null, '', `${location.href}?${queryString}`);

Isso garante que a string de consulta seja formatada e codificada corretamente.

Resolvendo Questões com "?"

Para adicionar corretamente parâmetros começando com um ponto de interrogação, respeite os parâmetros existentes:

function atualizarParametroUrl(param, valor) {
  const url = new URL(window.location);
  url.searchParams.set(param, valor);
  window.history.pushState(null, '', url);
}

Essa função adiciona ou atualiza parâmetros enquanto mantém uma URL limpa.

A Grande Imagem

Para interfaces interativas, é essencial manter a URL atualizada com o estado atual. Os métodos pushState() e replaceState() podem ser vinculados a ações do usuário, como cliques em botões, aplicação de filtros ou buscas, criando uma experiência interativa engajadora dentro da sua aplicação.

Recursos Úteis

1. Usando a API History – Web API | MDN — uma exploração detalhada sobre como manipular o histórico do navegador.
2. Trabalhando com a API History do HTML5 | CSS-Tricks — um guia instrutivo sobre pushState.
3. História: O Método pushState() – Web API | MDN — uma referência sobre pushState().
4. Obtendo Parâmetros de URL com JavaScript — SitePoint — gerenciando parâmetros de URL com JavaScript puro.
5. Localização do Janela JavaScript | w3schools — uma explicação sobre o objeto location no JavaScript.

Video

Navigation