encodeURIComponent vs encodeURI: Quando Usar Cada Um

As Duas Funções de Codificação de URL do JavaScript

O JavaScript oferece duas funções nativas para codificação de URL: encodeURI() e encodeURIComponent(). Embora possam parecer semelhantes, usar a função errada pode resultar em URLs quebradas, vulnerabilidades de segurança ou corrupção de dados. Entender a diferença é fundamental para desenvolvedores web.

encodeURI() - Para URIs Completas

A função encodeURI() foi projetada para codificar uma URI completa. Ela codifica todos os caracteres, exceto aqueles que têm significado especial na estrutura de uma URI. Especificamente, ela NÃO codifica:

• Caracteres reservados: ; , / ? : @ & = + $ #
• Caracteres não reservados: letras, dígitos, - _ . ! ~ * ' ( )

// encodeURI preserva a estrutura da URI
encodeURI('https://example.com/path?q=hello world&lang=en')
// "https://example.com/path?q=hello%20world&lang=en"
// Observação: :, /, ?, =, & NÃO são codificados

encodeURIComponent() - Para Componentes de URI

A função encodeURIComponent() foi projetada para codificar um único componente de uma URI (como o valor de um parâmetro de consulta). Ela codifica TODOS os caracteres, exceto:

• Caracteres não reservados: letras, dígitos, - _ . ! ~ * ' ( )

// encodeURIComponent codifica tudo, exceto os caracteres não reservados
encodeURIComponent('hello world & goodbye')
// "hello%20world%20%26%20goodbye"
// Observação: o & É codificado porque é um caractere reservado

// Usando-a no valor de um parâmetro de consulta
const url = 'https://example.com/search?q=' +
  encodeURIComponent('cats & dogs');
// "https://example.com/search?q=cats%20%26%20dogs"

Erros Comuns

Erro 1: Usar encodeURI para Valores de Consulta

Se você usar encodeURI() para codificar o valor de um parâmetro de consulta que contém um "e comercial" (&), ele não será codificado e será interpretado como um separador de parâmetros, quebrando a sua URL.

// ERRADO: o & no valor quebra a URL
const badUrl = 'https://api.example.com/search?q=' +
  encodeURI('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20&%20Jerry"
// O servidor entende: q="Tom " e um parâmetro " Jerry" sem valor

// CORRETO: use encodeURIComponent
const goodUrl = 'https://api.example.com/search?q=' +
  encodeURIComponent('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20%26%20Jerry"
// O servidor entende corretamente: q="Tom & Jerry"

Erro 2: Usar encodeURIComponent para URLs Completas

Se você usar encodeURIComponent() em uma URL inteira, ela codificará os dois-pontos, as barras, os pontos de interrogação e outros caracteres estruturais, tornando a URL completamente inutilizável.

Quando Usar Cada Um: A Regra Simples

• Use encodeURI() quando você tiver uma URI completa que possa conter espaços ou caracteres não ASCII, mas cuja estrutura seja válida
• Use encodeURIComponent() quando estiver codificando um único pedaço de dado que será inserido em uma URI (valores de parâmetros de consulta, segmentos de caminho, etc.)

A Alternativa URLSearchParams

O JavaScript moderno oferece a API URLSearchParams, que trata a codificação automaticamente. Essa costuma ser a melhor abordagem para construir query strings:

const params = new URLSearchParams({
  q: 'Tom & Jerry',
  category: 'cartoons & animation',
  page: '1'
});

const url = 'https://example.com/search?' + params.toString();
// "https://example.com/search?q=Tom+%26+Jerry&category=cartoons+%26+animation&page=1"

// Ou use a API URL
const url2 = new URL('https://example.com/search');
url2.searchParams.set('q', 'Tom & Jerry');
console.log(url2.toString());