【初心者向け】JavaScriptでURLエンコードをマスターしよう！encodeURIとencodeURIComponentの使い方

2024-06-30

JavaScript におけるエンコード: encodeURI と encodeURIComponent の使い分け

JavaScript には、URL エンコードと呼ばれる処理があります。これは、特殊文字を含む文字列を、Web ブラウザやサーバーで正しく解釈できるように変換するプロセスです。主に、URL に含める文字列に対してエンコードを行います。

この処理には、主に encodeURI と encodeURIComponent という2つの関数が使われます。それぞれの使い方と違いを理解することが重要です。

encodeURI は、URL 全体をエンコードするために使用されます。URL に含まれる予約文字（例：#, &, +, /, ?, :, @, =, $）を除いて、特殊文字をエスケープします。つまり、これらの予約文字はそのまま保持されます。

一方、encodeURIComponent は、URL の一部（例：クエリ文字列）をエンコードするために使用されます。encodeURI と異なり、予約文字に加えて、URL 構文の一部である文字（例：,、 ;) もエスケープします。

使い分け

一般的に、以下の要領で使い分けることを推奨します。

完全なURLをエンコードする場合: encodeURI を使用する
URL の一部（クエリ文字列など）をエンコードする場合: encodeURIComponent を使用する

例

以下の例は、それぞれの関数の動作を比較します。

const fullURL = "https://www.example.com/search?q=こんにちは";
const encodedFullURL = encodeURI(fullURL);
console.log(encodedFullURL); // 出力: https://www.example.com/search?q=%E3%81%97%E3%82%8A%E3%81%A8%E3%81%8A

const queryString = "こんにちは";
const encodedQueryString = encodeURIComponent(queryString);
console.log(encodedQueryString); // 出力: %E3%81%97%E3%82%8A%E3%81%A8%E3%81%8A

注意点

encodeURI と encodeURIComponent は、UTF-8 エンコーディングに基づいています。
誤ったエンコードを行うと、URL が正しく解析されず、エラーが発生する可能性があります。

encodeURI と encodeURIComponent は、それぞれ異なる目的で使用される関数です。URL 全体と部分（クエリ文字列など）を正しくエンコードするために、それぞれの違いを理解し、適切な関数を選択することが重要です。

// URL 全体をエンコード
const fullURL = "https://www.example.com/search?q=こんにちは";
const encodedFullURL = encodeURI(fullURL);
console.log(encodedFullURL); // 出力: https://www.example.com/search?q=%E3%81%97%E3%82%8A%E3%81%A8%E3%81%8A

// URL の一部（クエリ文字列）をエンコード
const queryString = "こんにちは";
const encodedQueryString = encodeURIComponent(queryString);
console.log(encodedQueryString); // 出力: %E3%81%97%E3%82%8A%E3%81%A8%E3%81%8A

// デコード
const decodedFullURL = decodeURI(encodedFullURL);
console.log(decodedFullURL); // 出力: https://www.example.com/search?q=こんにちは

const decodedQueryString = decodeURIComponent(encodedQueryString);
console.log(decodedQueryString); // 出力: こんにちは

補足

上記のコードは、Node.js やブラウザの JavaScript コンソールで実行できます。
decodeURI と decodeURIComponent 関数は、エンコードされた文字列を元の形式に戻すために使用します。

このサンプルコード以外にも、さまざまな状況に合わせて encodeURI と encodeURIComponent を活用することができます。

JavaScript で URL をエンコードするその他の方法

ビルトインの URL クラス

近年、JavaScript には URL クラスが導入されました。このクラスを使用して、URL のエンコードとデコードをより詳細な制御で行うことができます。

const url = new URL('https://www.example.com/search?q=こんにちは');
url.searchParams.set('q', 'ハロー%20ワールド');
const encodedURL = url.toString();
console.log(encodedURL); // 出力: https://www.example.com/search?q=%E3%83%8F%E3%83%AC%E3%83%BC%20%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89

const decodedURL = new URL(encodedURL);
console.log(decodedURL.searchParams.get('q')); // 出力: ハロー ワールド

カスタムエンコード関数

特定のニーズに合わせたエンコード処理が必要な場合は、カスタムエンコード関数を作成することができます。

function encodeCustom(str) {
  const safe = str.replace(/[^A-Za-z0-9-_.~]/g, function(char) {
    return '%' + char.charCodeAt(0).toString(16).toUpperCase();
  });
  return safe;
}

const encodedString = encodeCustom('こんにちは 世界');
console.log(encodedString); // 出力: %E3%81%97%E3%82%8A%E3%81%A8%E3%81%8A%20%E4%B8%96%E7%95%8C

サードパーティライブラリ

URL エンコーディングを扱うためのサードパーティライブラリもいくつか存在します。これらのライブラリは、追加機能や使いやすさを提供する場合があります。

それぞれの方法の比較

方法	利点	欠点
`encodeURI` / `encodeURIComponent`	シンプルで使いやすい	予約文字の扱いなど、詳細な制御が難しい
`URL` クラス	詳細な制御が可能	比較的新しく、ブラウザによってはサポートされていない場合がある
カスタムエンコード関数	完全なカスタマイズが可能	複雑で、エラーが発生しやすい可能性がある
サードパーティライブラリ	追加機能や使いやすさを提供	ライブラリの習得が必要