JavaScript URL API

Introdução aos Objetos URL do JavaScript

O JavaScript fornece uma poderosa interface URL nativa para construir, analisar e manipular URLs. Em vez de fatiar strings com expressões regulares ou chamadas manuais a split() — que falham em casos extremos como portas, caracteres codificados e componentes ausentes —, o objeto URL analisa um endereço em partes estruturadas e individualmente acessíveis.

A interface URL está disponível nativamente nos navegadores e no Node.js (é um global, sem necessidade de require). Este guia abrange como criar e analisar URLs, ler e modificar cada componente, trabalhar com strings de consulta por meio do URLSearchParams e lidar com tarefas práticas comuns, como construir requisições de API e rastrear links.

Criando e Analisando URLs com JavaScript

Criação Básica de URL

Para criar um URL, passe a string de endereço ao construtor URL. Se a string não for uma URL absoluta válida, o construtor lança um TypeError:

const url = new URL("https://www.w3docs.com");

Analisando Componentes de URL

Assim que um objeto URL é criado, você pode ler qualquer parte dele por meio de uma propriedade dedicada:

O conjunto completo de componentes para uma URL como https://user:[email protected]:8080/path?q=1#top é:

Validando uma URL Antes de Analisá-la

Como o construtor lança uma exceção em entrada inválida, valide strings não confiáveis primeiro. O método estático URL.canParse() retorna um boolean sem lançar exceção:

Manipulando Objetos URL

Trabalhando com a String de Consulta via URLSearchParams

Todo URL expõe uma propriedade searchParams — um objeto URLSearchParams ativo cujas alterações são escritas diretamente de volta para a URL. Essa é a forma preferida de editar uma string de consulta, pois ela cuida da codificação por você. O exemplo abaixo usa um URLSearchParams separado para mostrar como as peças se encaixam:

Na prática, você geralmente ignora o object intermediário e edita url.searchParams diretamente — ele muta a URL no lugar:

Chaves Repetidas e Iteração

As strings de consulta podem conter a mesma chave mais de uma vez (por exemplo ?tag=js&tag=web). get() retorna apenas o primeiro valor, enquanto getAll() retorna todos os valores. Você também pode percorrer todos os pares com for...of:

Explicação

• Inicialização:
  • O object URL é criado com uma URL base que já inclui um parâmetro de consulta (initial=123).
• Objeto URLSearchParams:
  • URLSearchParams é inicializado com url.search, que contém a string de consulta da URL.
• Adicionar um Parâmetro:
  • O método .set() é usado para adicionar um novo parâmetro (key=value) à string de consulta. Se a chave já existir, seu valor é atualizado; caso contrário, o par chave-valor é adicionado.
• Ler um Parâmetro:
  • O método .get() recupera o valor do parâmetro especificado pela chave (key), que é então registrado no console.
• Remover um Parâmetro:
  • O método .delete() remove o parâmetro especificado pela chave (initial). Isso é usado para demonstrar como remover um parâmetro da string de consulta.
• Atualizar a Pesquisa da URL:
  • Após modificar os parâmetros, a propriedade search da URL é atualizada com a representação em string do object URLSearchParams.
• Saída:
  • Por fim, a URL modificada é registrada no console, mostrando o efeito das operações.

Modificando Caminho e Hash

Veja um trecho de JavaScript que mostra como modificar o pathname e o hash de uma URL:

Explicação

• Inicialização do Objeto URL:
  • O object URL é inicialmente criado a partir de uma string que representa uma URL completa. Essa URL inclui um pathname, uma string de consulta e um fragmento hash.
• Modificando o Pathname:
  • A propriedade pathname do object URL é definida para um novo caminho (/path/to/resource). Essa propriedade especifica o caminho ou rota no servidor.
• Modificando o Hash:
  • A propriedade hash é atualizada para "section". Nas URLs, o hash representa um marcador dentro da página, frequentemente usado para rolar até uma seção específica.
• Registrando as Alterações:
  • A URL original é registrada antes das modificações para mostrar o estado inicial.
  • Após as modificações, o novo estado da URL é registrado para demonstrar os efeitos de alterar o pathname e o hash.

Uso Avançado de Objetos URL

Lidando com URLs Relativas

O object URL também pode resolver URLs relativas em relação a uma URL base, o que é particularmente útil para aplicações web que lidam com links dinâmicos:

Trabalhando com Codificação de URL

Ao lidar com URLs que incluem caracteres que precisam de codificação, o object URL os trata automaticamente, garantindo que as URLs sejam válidas:

Para lidar com arquivos locais ou blobs, URL.createObjectURL() gera uma string de URL temporária que referencia o object na memória, o que é útil para visualizar imagens ou baixar arquivos diretamente do JavaScript.

Exemplos Práticos de Manipulação de URL

Rastreando URLs de Campanha

Você pode usar objetos URL para gerenciar efetivamente URLs de campanha, que são frequentemente usadas no marketing digital para rastrear o desempenho de diversos esforços de marketing:

Integrando com Web APIs

Os objetos URL combinam naturalmente com a Fetch API: você pode passar uma instância de URL diretamente para fetch(), e searchParams garante que a string de consulta esteja corretamente codificada. Após a resolução da requisição, você geralmente analisa a resposta com os métodos JSON:

Alternativa moderna (async/await):

async function fetchPosts() {
  const apiUrl = new URL("https://jsonplaceholder.typicode.com/posts");
  apiUrl.searchParams.set("userId", "1");
  const response = await fetch(apiUrl);
  const data = await response.json();
  console.log(data[0]); // Outputs the first post by user with userId 1
}

Erros Comuns

• O construtor lança uma exceção em entrada inválida. new URL("example.com") falha porque não possui protocolo. Forneça uma URL absoluta completa, passe uma URL base como segundo argumento, ou proteja com URL.canParse().
• Strings relativas precisam de uma base. new URL("/about") lança uma exceção sozinho; new URL("/about", "https://www.w3docs.com") resolve corretamente.
• origin é somente leitura. Você não pode atribuir a url.origin. Altere protocol, hostname ou port individualmente em vez disso.
• get() retorna apenas o primeiro valor. Para chaves que podem se repetir, use getAll().
• A normalização é automática. Ler href pode adicionar uma barra final (https://w3docs.com torna-se https://w3docs.com/) e codificar em porcentagem caracteres reservados. Compare URLs analisadas, não strings brutas, ao verificar igualdade.
• A ordem de searchParams é a ordem de inserção. Use params.sort() se precisar de uma string de consulta canônica e estável para cache ou assinatura.

Conclusão

O objeto URL do JavaScript é uma ferramenta robusta para lidar com todos os aspectos da manipulação e análise de URLs. Ao dominar suas propriedades e métodos, os desenvolvedores podem simplificar a interação de suas aplicações web com URLs, melhorando tanto a funcionalidade quanto a experiência do usuário. Seja gerenciando estruturas complexas de URL, integrando com APIs ou rastreando campanhas de marketing, o objeto URL oferece uma forma confiável e eficiente de trabalhar com endereços web em JavaScript.

Prática