Como Obter Parâmetros de URL com JavaScript

Os parâmetros de URL (também chamados de query strings) são uma parte crucial do desenvolvimento web, permitindo que você passe dados entre páginas ou do cliente para o servidor. Seja construindo uma funcionalidade de busca, lidando com submissões de formulários ou rastreando preferências do usuário, saber como extrair e usar esses parâmetros é essencial.

Neste artigo, mostrarei as maneiras mais eficazes de obter parâmetros de URL usando JavaScript, desde abordagens modernas até soluções legadas.

Entendendo Parâmetros de URL

Os parâmetros de URL aparecem após o ponto de interrogação (?) em uma URL e são formatados como pares chave-valor:

https://example.com/page?name=john&id=123

Neste exemplo, há dois parâmetros: name com valor john e id com valor 123.

A Abordagem Moderna: URLSearchParams

A maneira mais simples e confiável de lidar com parâmetros de URL em navegadores modernos é usando a interface URLSearchParams.

Uso Básico

// Assumindo URL: https://example.com/page?product=shirt&color=blue&size=m

// Obter a query string
const queryString = window.location.search;

// Analisar a query string
const urlParams = new URLSearchParams(queryString);

// Obter o valor de um parâmetro específico
const product = urlParams.get('product'); // "shirt"
const color = urlParams.get('color');     // "blue"

Verificando se um Parâmetro Existe

// Verificar se um parâmetro existe
if (urlParams.has('product')) {
  // Parâmetro existe
  console.log('Parâmetro product existe');
}

Lidando com Múltiplos Valores

Se um parâmetro aparece várias vezes na URL, você pode recuperar todos os valores:

// URL: https://example.com/page?tag=javascript&tag=frontend

// Obter todos os valores para um parâmetro
const tags = urlParams.getAll('tag'); // ["javascript", "frontend"]

Iterando Sobre Parâmetros

URLSearchParams fornece métodos iteradores para trabalhar com todos os parâmetros:

// Iterar sobre todas as chaves de parâmetros
for (const key of urlParams.keys()) {
  console.log(key);
}

// Iterar sobre todos os valores de parâmetros
for (const value of urlParams.values()) {
  console.log(value);
}

// Iterar sobre todas as entradas de parâmetros (pares chave-valor)
for (const [key, value] of urlParams.entries()) {
  console.log(`${key}: ${value}`);
}

Abordagem Legada: Função Personalizada

Para navegadores mais antigos que não suportam URLSearchParams, você pode criar uma função personalizada:

function getUrlParam(param) {
  const queryString = window.location.search.substring(1);
  const urlParams = queryString.split('&');
  
  for (let i = 0; i < urlParams.length; i++) {
    const paramPair = urlParams[i].split('=');
    if (paramPair[0] === param) {
      return decodeURIComponent(paramPair[1] || "");
    }
  }
  return null;
}

// Uso
const productValue = getUrlParam('product');

Lidando com Casos Extremos Comuns

Caracteres Codificados

Parâmetros de URL frequentemente contêm caracteres codificados. Por exemplo, espaços são codificados como %20:

// URL: https://example.com/search?query=web%20development

const query = urlParams.get('query');
console.log(query); // "web development" (automaticamente decodificado)

Ao usar uma função personalizada, certifique-se de usar decodeURIComponent() para lidar corretamente com esses caracteres codificados.

Parâmetros Ausentes

Sempre verifique se um parâmetro existe antes de usá-lo:

const size = urlParams.has('size') ? urlParams.get('size') : 'default';

Parâmetros Vazios

Parâmetros podem existir sem valores:

// URL: https://example.com/page?newsletter=&theme=dark

const newsletter = urlParams.get('newsletter'); // "" (string vazia)
const hasNewsletter = urlParams.has('newsletter'); // true

Exemplo Completo: Obtendo Todos os Parâmetros de URL

Aqui está uma função abrangente para obter todos os parâmetros de URL como um objeto:

function getAllUrlParams() {
  const params = {};
  const queryString = window.location.search.substring(1);
  
  if (queryString) {
    const pairs = queryString.split('&');
    
    for (const pair of pairs) {
      const [key, value] = pair.split('=');
      
      // Se o parâmetro não tem valor, defina como true
      if (typeof value === 'undefined') {
        params[key] = true;
      } else {
        // Se já temos este parâmetro, converta para array
        if (params[key]) {
          if (!Array.isArray(params[key])) {
            params[key] = [params[key]];
          }
          params[key].push(decodeURIComponent(value));
        } else {
          params[key] = decodeURIComponent(value);
        }
      }
    }
  }
  
  return params;
}

Compatibilidade de Navegadores

URLSearchParams é suportado em todos os navegadores modernos, incluindo:

• Chrome 49+
• Firefox 44+
• Safari 10.1+
• Edge 17+

Para navegadores mais antigos como Internet Explorer, você precisará usar um polyfill ou a abordagem de função personalizada.

Considerações de Performance

Para a maioria das aplicações, a diferença de performance entre métodos é negligível. No entanto:

1. URLSearchParams é otimizado e mantido pelos fornecedores de navegadores
2. Funções personalizadas podem ser adaptadas às suas necessidades específicas
3. Se você está obtendo apenas um único parâmetro, uma regex simples pode ser mais rápida

Notas de Segurança

Lembre-se de que parâmetros de URL são visíveis na barra de endereços do navegador e não são seguros para informações sensíveis. Sempre valide e sanitize valores de parâmetros antes de usá-los em sua aplicação.

Conclusão

A interface URLSearchParams fornece uma maneira limpa e padronizada de trabalhar com parâmetros de URL em JavaScript. Para a maioria das aplicações web modernas, é a abordagem recomendada. Para suporte a navegadores legados, uma função personalizada pode fornecer a mesma funcionalidade com um pouco mais de código.

Ao entender como extrair e usar efetivamente parâmetros de URL, você pode construir aplicações web mais dinâmicas e interativas.

Perguntas Frequentes

Posso modificar parâmetros de URL com JavaScript?

Sim, você pode usar URLSearchParams para modificar parâmetros e então atualizar a URL com history.pushState() ou history.replaceState().

Como lidar com parâmetros de URL em uma aplicação de página única?

A maioria dos frameworks SPA (React, Vue, Angular) têm sistemas de roteamento integrados que lidam com parâmetros de URL. Consulte a documentação do seu framework para detalhes.

Parâmetros de URL são case-sensitive?

Nomes de parâmetros são case-sensitive de acordo com a especificação de URL, então 'name' e 'Name' são parâmetros diferentes.

Como lidar com arrays em parâmetros de URL?

Você pode usar o mesmo nome de parâmetro várias vezes (ex: ?color=red&color=blue) ou usar notação de colchetes (ex: ?colors[]=red&colors[]=blue).

Qual é o comprimento máximo dos parâmetros de URL?

Não há limite oficial, mas navegadores e servidores tipicamente têm limites práticos em torno de 2.000-8.000 caracteres para toda a URL.