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: alfabeto, dígitos decimais, - _ . ! ~ * ' ( )
Note-se que umURIError
(en-US) 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 provê o encoding especial requerido pelo UTF-8 nos parâmetros 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
Especificação | Status | Comentario |
---|---|---|
ECMAScript 3rd Edition (ECMA-262) | Padrão | Definição Inicial. |
ECMAScript 5.1 (ECMA-262) The definition of 'encodeURIComponent' in that specification. |
Padrão | |
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'encodeURIComponent' in that specification. |
Padrão |
Compatibilidade com navegadores
BCD tables only load in the browser