encodeURIComponent()

encodeURIComponent() 関数は、特定の文字を UTF-8 文字エンコーディングで表された 1 個から 4 個のエスケープシーケンスに置き換えることで、URI (Uniform Resource Identifier) をエンコードします（サロゲートペアで構成される文字のみ 4 個のエスケープシーケンスになります）。

構文

encodeURIComponent(str);

引数

str

URI の構成要素となる文字列。

戻り値

特定の文字がエスケープされた新しい文字列。

説明

encodeURIComponent は次を除く全ての文字をエスケープします : アルファベット、10進数字、- _ . ! ~ * ' ( )

上位・下位のペアでないサロゲート文字をエンコードしようとした場合 URIError が発生します。

// 上位・下位の正しいペア
console.log(encodeURIComponent('\uD800\uDFFF'));

// 上位のみであり "URIError: malformed URI sequence" が発生
console.log(encodeURIComponent('\uD800'));

// 下位のみであり "URIError: malformed URI sequence" が発生
console.log(encodeURIComponent('\uDFFF')); 

サーバへの予想外のリクエストを避けるため、URI の一部として送信が想定されるユーザ入力値には encodeURIComponent を呼び出すべきです。例えば、ユーザーが URL クエリパラメータの comment 変数に "Thyme &time=again" と言った文字列を入力できると仮定しましょう。この変数に encodeURIComponent を使用しない場合、変数には comment=Thyme%20&time=again が与えられます。アンパサンドと等号記号によって新しいキー/バリューペアが作られることに注意してください。そのため、"Thyme &time=again" という値を持つ comment キーが POST される代わりに、"Thyme " と（time というキーに対する） again という値を持つ 2 つのキーが POST されます。

application/x-www-form-urlencoded によれば、スペースは '+' に置換されます。そのため、encodeURIComponent による置換に加えて "%20" を "+" に変換したいと考えるユーザーもおられるでしょう。

（! ' ( ) * が予約語になっている）RFC 3986 仕様を忠実に順守するには、これらの URI 区切り文字としての役目が失われてしまうものの、以下の例が問題なく使用できます。

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

使用例

次の例は、サーバレスポンスヘッダパラメータの Content-Disposition と Link で（UTF-8 からなるファイル名などに）必要となる特別な UTF-8 エンコーディングを提供します :

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

console.log(header); 
// "Content-Disposition: attachment; filename*=UTF-8''my%20file%282%29.txt" と出力される


function encodeRFC5987ValueChars (str) {
    return encodeURIComponent(str).
        // RFC3986 では "!" は予約文字だが、RFC5987 ではそうではないため、
        // エスケープする必要がないことに注意
        replace(/['()]/g, escape). // i.e., %27 %28 %29
        replace(/\*/g, '%2A').
            // 以下の文字、| ` ^ は RFC5987 ではパーセントエンコーディングする必要がないので、
            // 通信上での可読性向上のため unescape を行う
            replace(/%(?:7C|60|5E)/g, unescape);
}

仕様

ブラウザ実装状況

関連項目

• decodeURI
• encodeURI
• decodeURIComponent