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

構文

encodeURIComponent(str);

引数

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

戻り値

与えられた文字列を表す URI 構成要素としてエスケープされた新しい文字列です。

説明

encodeURIComponent下記を除くすべての文字をエスケープします:

エスケープされない:

    A-Z a-z 0-9 - _ . ! ~ * ' ( )

encodeURIComponent と encodeURI の違いを見てください:

var set1 = ";,/?:@&=+$";  // Reserved Characters
var set2 = "-_.!~*'()";   // Unescaped Characters
var set3 = "#";           // Number Sign
var set4 = "ABC abc 123"; // Alphanumeric Characters + Space

console.log(encodeURI(set1)); // ;,/?:@&=+$
console.log(encodeURI(set2)); // -_.!~*'()
console.log(encodeURI(set3)); // #
console.log(encodeURI(set4)); // ABC%20abc%20123 (the space gets encoded as %20)

console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24
console.log(encodeURIComponent(set2)); // -_.!~*'()
console.log(encodeURIComponent(set3)); // %23
console.log(encodeURIComponent(set4)); // ABC%20abc%20123 (the space gets encoded as %20)

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

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

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

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

フォーム POST からサーバーに渡されるユーザー入力値には encodeURIComponent を呼び出すべきです。これは、特殊な HTML エンティティやエンコード・デコードを必要とする他の文字のデータ入力中に誤って生成される可能性がある "&" シンボルをエンコードします。

例えば、ユーザーが "Jack & Jill" と入力したら、テキストは "Jack & Jill" にエンコードされるかもしれません。encodeURIComponent を使わないと "&" が新しいフィールドの始まりとしてサーバー上で解釈され、データの完全性が損なわれる可能性があります。

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); 
// 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);
}

// here is an alternative to the above function
function encodeRFC5987ValueChars2(str) {
  return encodeURIComponent(str).
    // Note that although RFC3986 reserves "!", RFC5987 does not,
    // so we do not need to escape it
    replace(/['()*]/g, c => "%" + c.charCodeAt(0).toString(16)). // i.e., %27 %28 %29 %2a (Note that valid encoding of "*" is %2A
                                                                 // which necessitates calling toUpperCase() to properly encode)
    // 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, (str, hex) => String.fromCharCode(parseInt(hex, 16)));
}

仕様

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

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイルサーバー
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeEdge MobileAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung InternetNode.js
encodeURIComponentChrome 完全対応 ありEdge 完全対応 ありFirefox 完全対応 1IE 完全対応 5.5Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありEdge Mobile 完全対応 ありFirefox Android 完全対応 4Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 ありnodejs 完全対応 あり

凡例

完全対応  
完全対応

関連項目

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

タグ: 
最終更新者: segayuu,