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-DispositionLink で(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);
}

仕様

仕様 策定状況 コメント
ECMAScript 3rd Edition (ECMA-262) 標準 初期定義。
ECMAScript 5.1 (ECMA-262)
encodeURIComponent の定義
標準  
ECMAScript 2015 (6th Edition, ECMA-262)
encodeURIComponent の定義
標準  
ECMAScript 2017 Draft (ECMA-262)
encodeURIComponent の定義
ドラフト  

ブラウザ実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本サポート (有) (有) 5.5 (有) (有)
機能 Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
基本サポート (有) (有) (有) (有) (有) (有)

関連項目

ドキュメントのタグと貢献者

タグ: 
 このページの貢献者: YuichiNukiyama, x2357, dskmori, teoli, Jxck, SphinxKnight, ssw, s_fujimoto, ethertank, Potappo, Hot
 最終更新者: YuichiNukiyama,