encodeURIComponent()

O método encodeURIComponent() codifica  uma URI (Identificador recurso uniforme) substituindo cada ocorrência de determinados caracteres por um, dois, três, ou quatro seqüências de escape que representam a codificação UTF-8 do caractere (só será quatro seqüências de escape para caracteres compostos por dois caracteres "substituto").

Syntaxe

encodeURIComponent(str);

Parâmetros

str

String. Uma sequência URI.

Descrição

encodeURIComponent escapa todos os caracteres, exceto: afabeto, digitos decimais, - _ . ! ~ * ' ( )

Note-se que umURIError será gerada se uma tentativas para codificar um substituto que não faz parte de um par de alta-baixa, por exemplo,

// high-low par ok
console.log(encodeURIComponent('\uD800\uDFFF'));

// lone high surrogate throws "URIError: malformed URI sequence"
console.log(encodeURIComponent('\uD800'));

// lone low surrogate throws "URIError: malformed URI sequence"
console.log(encodeURIComponent('\uDFFF')); 

Para previnir requisões inesperadas ao servidor, deve-se chamar encodeURIComponent ou qualquer parâmetro fornecido pelo usuário que será passado como parte da URI. Por exemplo, um usuário poderia digitar "Thyme &time=again" para uma variável commentario. Ao não usar encodeURIComponent nessa variável irá ser obetido commentario=Thyme%20&time=again. Note que o ampersa  e o sinal de igual marcam um novo par de chave e valor. Então ao invés de ter um POST com a chave commentario igual a "Thyme &time=again", tem-se chaves em  POST, uma igual a "Thyme " e outra (time) igual a again.

Para application/x-www-form-urlencoded, espaços são substituídos por '+', então pode-se querer seguir um encodeURIComponent substituição com uma substituição adicional de "%20" com "+".

Para ser mais rigoroso à aderência da RFC 3986 (qual reserva !, ', (, ), e *), mesmo que esses caracteres não tenham usos formalizados de delimitação de URI, o seguinte pode ser usado com segurança:

function ajustadoEncodeURIComponent (str) {
  return encodeURIComponent(str).replace(/[!'()*]/g, function(c) {
    return '%' + c.charCodeAt(0).toString(16);
  });
}

Exemplos

O exemplo seguinte prove o encoding especial requerido pelo UTF-8 nos parametros Content-Disposition e Link no cabeçalho de uma Response (e.g., UTF-8 filenames):

var fileName = 'my file(2).txt';
var header = "Content-Disposition: attachment; filename*=UTF-8''" 
             + encodeRFC5987ValueChars(fileName);

console.log(header); 
// logs "Content-Disposition: attachment; filename*=UTF-8''my%20file%282%29.txt"


function encodeRFC5987ValueChars (str) {
    return encodeURIComponent(str).
        // Note that although RFC3986 reserves "!", RFC5987 does not,
        // so we do not need to escape it
        replace(/['()]/g, escape). // i.e., %27 %28 %29
        replace(/\*/g, '%2A').
            // The following are not required for percent-encoding per RFC5987, 
            // so we can allow for a little better readability over the wire: |`^
            replace(/%(?:7C|60|5E)/g, unescape);
}

Especificações

Compatibilidade - Browser

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Veja também

• decodeURI
• encodeURI
• decodeURIComponent