Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

encodeURI() — codificação de um URI completo

encodeURI() codifica os caracteres de um URI completo, mantendo alguns delimitadores inalterados. Devolve uma nova cadeia com codificação percentual UTF-8; não se destina a codificar valores de parâmetros individuais.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

encodeURI(uri)

encodeURI(uri) é uma função global de ECMAScript, não uma API do navegador. Converte o argumento numa cadeia e devolve uma nova cadeia, substituindo alguns caracteres por sequências %HH que representam bytes UTF-8. Um espaço passa a %20, não a +.

Mantém inalteradas as letras ASCII, os algarismos e -_.!~*'();/?:@&=+$,#. Assim, &, = e # mantêm o seu significado especial, mas a função não preserva a estrutura de todos os URI válidos. Por exemplo, aplica a codificação percentual aos parênteses retos que envolvem um endereço IPv6 literal: http://[::1]/ passa a http://%5B::1%5D/, um URL com um anfitrião inválido. Para um valor de parâmetro individual, utiliza encodeURIComponent(), que também codifica &, = e #.

Se utilizares encodeURIComponent() para codificar um único segmento de caminho, rejeita antes da codificação os valores que sejam exatamente . ou ... A função deixa-os inalterados, pelo que um analisador de URL pode tratá-los como segmentos de ponto ao normalizar o caminho, em vez de os preservar como dados literais. Um segmento .. pode remover o segmento anterior do caminho.

A função não verifica se um endereço é válido nem se é seguro. Codifica % como %25, pelo que uma nova codificação altera as sequências de escape existentes: %20 passa a %2520. Um substituto UTF-16 sem par provoca URIError; um par válido é codificado como um único ponto de código.

O exemplo mostra quais os delimitadores que se mantêm inalterados no URL apresentado, como são codificados é e os espaços e a diferença entre codificar um URI completo e codificar um dos seus componentes.

Exemplos

const uri = "https://example.com/café menu?q=tea&size=large#top";
console.log(encodeURI(uri));
console.log(encodeURIComponent("tea&size=large"));
console.log(encodeURI("%20"));

Resultado

https://example.com/caf%C3%A9%20menu?q=tea&size=large#top
tea%26size%3Dlarge
%2520

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes