encodeURIComponent()
Baseline
広く利用可能
この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2015年7月以降、すべてのブラウザーで利用可能です。
encodeURIComponent() 関数は URI を、特定の文字の各インスタンスを、その文字の UTF-8 エンコード方式を表す 1 つから 4 つのエスケープシーケンスで置き換えることでエンコードします (2 つのサロゲート文字で構成される文字の場合は 4 つのエスケープシーケンスになります)。 encodeURI() と比較すると、この関数は URI 構文の一部を含むより多くの文字をエンコードします。
試してみましょう
// Encodes characters such as ?,=,/,&,:
console.log(`?x=${encodeURIComponent("test?")}`);
// 予想される結果: "?x=test%3F"
console.log(`?x=${encodeURIComponent("шеллы")}`);
// 予想される結果: "?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"
構文
encodeURIComponent(uriComponent)
引数
uriComponent-
URI の部分（パス、クエリー文字列、フラグメントなど）としてエンコードされる文字列。他にも文字列に変換される値があります。
返値
与えられた文字列を表す URI 構成要素としてエンコードされた新しい文字列です。
例外
返値
encodeURIComponent() はグローバルオブジェクトの関数プロパティです。
encodeURIComponent は encodeURI() で説明されているのと同じエンコーディングアルゴリズムを使用します。下記を除くすべての文字をエスケープします。
A–Z a–z 0–9 - _ . ! ~ * ' ( )
encodeURI() と比較すると、 encodeURIComponent() はより多くの文字セットをエスケープします。サーバーに送信されるフォームのユーザー入力フィールドには encodeURIComponent() を使用してください。これにより、文字参照のデータ入力中に不注意で生成される可能性のある & 記号や、エンコード/デコードが要求されるその他の文字がエンコードされます。例えば、ユーザーが 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() に渡す前に、孤立サロゲートが含まれているかどうかを調べることができます。
仕様書
| 仕様書 |
|---|
| ECMAScript® 2027 Language Specification # sec-encodeuricomponent-uricomponent |