O que o encodeURIComponent faz? Uma explicação simples com exemplos

Se você construiu uma URL em JavaScript, provavelmente encontrou encodeURIComponent e, possivelmente, seu irmão confusamente semelhante, encodeURI. Usar o errado é um bug clássico que quebra links de maneira sutil. Aqui está uma explicação clara do que encodeURIComponent faz, com exemplos e uma regra simples para escolher entre os dois.

O que isso faz

encodeURIComponent pega uma string e substitui qualquer caractere que não seja seguro em uma URL por seu equivalente codificado em porcentagem. Um espaço se torna %20, um E comercial se torna %26, um sinal de igual se torna %3D, um ponto de interrogação se torna %3F e assim por diante. O objetivo é tornar seguro um trecho de texto para ser colocado em uma URL como um valor, um termo de pesquisa, um parâmetro, um alvo de redirecionamento, sem que os caracteres especiais sejam mal interpretados como estrutura de URL. Ele codifica tudo o que pode causar um problema, que é exatamente o que você deseja para um único valor.

Um exemplo concreto

Digamos que você queira criar um URL de pesquisa para a consulta “gatos e cachorros”. Se você apenas concatená-lo, obterá ...?q=cats & Dogs, que quebra, o E comercial é lido como um separador de parâmetro e o espaço é ilegal. Execute o valor por meio de encodeURIComponent primeiro e "cats & Dogs" se torna cats%20%26%20dogs, fornecendo ...?q=cats%20%26%20dogs, que o servidor lê corretamente como o valor único "cats & Dogs". A codificação preserva o significado dos seus dados, escapando dos caracteres que de outra forma seriam estruturais.

encodeURIComponent vs encodeURI

A diferença é o que cada um deixa sozinho. encodeURIComponent codifica tudo reservado, incluindo os caracteres da estrutura de URL como / ? & = #, porque pressupõe que você está codificando um valor que está dentro de uma URL. encodeURI deliberadamente não codifica esses caracteres de estrutura, porque pressupõe que você está codificando uma URL inteira já construída e deseja mantê-la funcional. Portanto, encodeURI('https://x.com?a=b c') mantém ://, ? e = intactos e apenas corrige o espaço, enquanto encodeURIComponent escaparia de todos eles. Use componente para as partes, encodeURI para uma URL inteira.

A regra simples

Aqui está a regra que evita problemas: se você estiver codificando um valor que vai dentro de uma URL, um termo de pesquisa, um valor de parâmetro, um segmento de caminho, um alvo de redirecionamento, use encodeURIComponent. Se você estiver codificando um URL inteiro que deseja que permaneça um URL funcional, use encodeURI. Quando você não tem certeza, quase sempre deseja encodeURIComponent, porque quase sempre codifica um valor, não um URL inteiro. Fazer isso direito evita os bugs mais comuns de construção de URL.

Cuidado com a codificação dupla

Uma armadilha: nunca execute encodeURIComponent em uma string que já esteja codificada. Se você codificar um valor duas vezes, os próprios sinais de porcentagem serão codificados, %20 se tornará %2520 e o link será quebrado. Codifique apenas texto bruto e não codificado. Se você não tiver certeza se uma string já está codificada, decodifique-a primeiro e depois codifique-a exatamente uma vez. Esse erro de codificação dupla é a fonte do misterioso %2520 que você às vezes vê em URLs quebrados.