encodeURIComponent()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨julho de 2015⁩.

O métodoencodeURIComponent() 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 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 okconsole.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 chamarencodeURIComponent 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ávelcommentario. Ao não usarencodeURIComponent nessa variável irá ser obetidocommentario=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 chavecommentario igual a "Thyme &time=again", tem-se chaves em POST, uma igual a "Thyme" e outra (time) igual aagain.

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

Para ser mais rigoroso à aderência daRFC 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âmetrosContent-Disposition eLink 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)  );}