encodeURIComponent()

BaselineWidely available

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

encodeURIComponent() 関数はURI を、特定の文字の各インスタンスを、その文字のUTF-8 エンコード方式を表す 1 つから 4 つのエスケープシーケンスで置き換えることでエンコードします (2 つのサロゲート文字で構成される文字の場合は 4 つのエスケープシーケンスになります)。encodeURI() と比較すると、この関数は URI 構文の一部を含むより多くの文字をエンコードします。

試してみましょう

// Encodes characters such as ?,=,/,&,:console.log(`?x=${encodeURIComponent("test?")}`);// Expected output: "?x=test%3F"console.log(`?x=${encodeURIComponent("шеллы")}`);// Expected output: "?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"

構文

encodeURIComponent(uriComponent)

引数

uriComponent: URI の部分（パス、クエリー文字列、フラグメントなど）としてエンコードされる文字列。他にも文字列に変換される値があります。

返値

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

例外

URIError: uriComponent に孤立サロゲートがあると発生します。

返値

encodeURIComponent() はグローバルオブジェクトの関数プロパティです。

encodeURIComponent はencodeURI() で説明されているのと同じエンコーディングアルゴリズムを使用します。下記を除くすべての文字をエスケープします。

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

encodeURI() と比較すると、encodeURIComponent() はより多くの文字セットをエスケープします。encodeURIComponent() は、サーバーにPOST されたフォームからユーザーが入力した項目に対して使用します。これは、文字参照やその他エンコード/デコードを要求される文字について、データ入力中に不用意に発生する可能性のある記号をエンコードします。例えば、ユーザーがJack & Jill と入力した場合、テキストはJack & Jill とエンコードされる可能性があります。encodeURIComponent() を使用しない場合は "&" が新しいフィールドの始まりとしてサーバー上で解釈され、データの完全性が損なわれる可能性があります。

application/x-www-form-urlencoded では、スペースは+ に置換されます。そのため、encodeURIComponent() による置換に加えて%20 を+ に置き換えることが望まれるかもしれません。

例

Content-Disposition とリンクヘッダーのエンコーディング

次の例は、サーバーレスポンスヘッダー引数のContent-Disposition やLink で (UTF-8 からなるファイル名などに) 必要となる特別な UTF-8 エンコーディングを提供します。

const fileName = "my file(2).txt";const 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)      // The following creates the sequences %27 %28 %29 %2A (Note that      // the valid encoding of "*" is %2A, which necessitates calling      // toUpperCase() to properly encode). Although RFC3986 reserves "!",      // RFC5987 does not, so we do not need to escape it.      .replace(        /['()*]/g,        (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,      )      // 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)),      )  );}

RFC3986 のエンコーディング

最新のRFC3986 では、!,',(,),* を、たとえこれらの文字が正式な URI 区切り文字として使用されていないとしても予約しています。IPv6 の URI 構文の一部である[ と] もエンコードします。 RFC3986 に準拠したencodeURI の実装では、これらをエスケープすべきではありません。これはencodeURI() の例で示されています。

function encodeRFC3986URIComponent(str) {  return encodeURIComponent(str).replace(    /[!'()*]/g,    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,  );}

孤立サロゲートのエンコードによる例外

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

// 上位・下位の正しいペアencodeURIComponent("\uD800\uDFFF"); // "%F0%90%8F%BF"// 上位のみであり "URIError: malformed URI sequence" が発生encodeURIComponent("\uD800");// 下位のみであり "URIError: malformed URI sequence" が発生encodeURIComponent("\uDFFF");

String.prototype.toWellFormed() を使用することができます。これは孤立サロゲートを Unicode 置換文字 (U+FFFD) に置き換えることで、このエラーを避けることができます。また、String.prototype.isWellFormed() を使用することで、文字列をencodeURIComponent() に渡す前に、孤立サロゲートが含まれているかどうかを調べることができます。