読み込み中...

URLSearchParamsを使ったJavaScriptのクエリ操作方法10選

JavaScriptでURLSearchParamsを使ったクエリ文字列操作 JS
この記事は約20分で読めます。

【サイト内のコードはご自由に個人利用・商用利用いただけます】

この記事では、プログラムの基礎知識を前提に話を進めています。

説明のためのコードや、サンプルコードもありますので、もちろん初心者でも理解できるように表現してあります。

本記事のサンプルコードを活用して機能追加、目的を達成できるように作ってありますので、是非ご活用ください。

※この記事は、一般的にプロフェッショナルの指標とされる『実務経験10,000時間以上』を満たす現役のプログラマチームによって監修されています。

※Japanシーモアは、常に解説内容のわかりやすさや記事の品質に注力しております。不具合、分かりにくい説明や不適切な表現、動かないコードなど気になることがございましたら、記事の品質向上の為にお問い合わせフォームにてご共有いただけますと幸いです。
(送信された情報は、プライバシーポリシーのもと、厳正に取扱い、処分させていただきます。)

●URLSearchParamsとは？

みなさん、URLってご存知ですよね？

でも、URLの中にある「?」以降の部分、クエリ文字列って何だか知っていますか？

実は、このクエリ文字列を簡単に操作できるのがURLSearchParamsです。

URLSearchParamsは、JavaScriptのビルトインオブジェクトの1つで、クエリ文字列をオブジェクトとして扱うことができます。

例えば、「https://example.com/?key1=value1&key2=value2」というURLがあったとします。

このクエリ文字列「?key1=value1&key2=value2」の部分を、URLSearchParamsを使えばこんな風に簡単に取得できるんです。

const url = new URL('https://example.com/?key1=value1&key2=value2');
const searchParams = url.searchParams;
console.log(searchParams.get('key1')); // 'value1'
console.log(searchParams.get('key2')); // 'value2'

便利そうですよね？でも、これはまだ基本的な使い方の一部です。

URLSearchParamsにはもっと色々な機能があるんですよ。

○URLSearchParamsの基本的な使い方

URLSearchParamsを使うには、まずURLオブジェクトから取得する必要があります。

URLオブジェクトのsearchParamsプロパティがURLSearchParamsオブジェクトを返してくれるんです。

取得したURLSearchParamsオブジェクトを使えば、クエリパラメータの取得や設定、削除など、色々なことができます。

順番に見ていきましょう。

○サンプルコード1：クエリパラメータの取得

クエリパラメータを取得するには、getメソッドを使います。

引数にパラメータのキー名を指定すると、その値を返してくれます。

const url = new URL('https://example.com/?key1=value1&key2=value2');
const searchParams = url.searchParams;
console.log(searchParams.get('key1')); // 'value1'
console.log(searchParams.get('key2')); // 'value2'
console.log(searchParams.get('key3')); // null

存在しないキー名を指定した場合はnullが返ってきます。

すべてのパラメータを取得したい場合は、entriesメソッドを使うと良いでしょう。

for (const [key, value] of searchParams.entries()) {
  console.log(`${key}: ${value}`);
}
// 出力結果
// key1: value1
// key2: value2

for…of文を使ってentriesメソッドで取得した[キー, 値]のペアを反復処理できます。

これで全パラメータが取得できましたね。

○サンプルコード2：クエリパラメータの設定

新しくクエリパラメータを設定したい場合は、setメソッドを使います。

引数にキー名と値を指定します。

const url = new URL('https://example.com/');
const searchParams = url.searchParams;
searchParams.set('key1', 'value1');
searchParams.set('key2', 'value2');
console.log(url.toString()); 
// 出力結果
// 'https://example.com/?key1=value1&key2=value2'

setメソッドを使うと、既存のパラメータは上書きされ、新しいパラメータが追加されます。

結果としてURLも更新されますね。

○サンプルコード3：クエリパラメータの削除

不要になったクエリパラメータは、deleteメソッドで削除しましょう。

引数にキー名を指定します。

const url = new URL('https://example.com/?key1=value1&key2=value2');
const searchParams = url.searchParams;  
searchParams.delete('key1');
console.log(url.toString());
// 出力結果 
// 'https://example.com/?key2=value2'

deleteメソッドを実行すると、指定したキーとその値がクエリ文字列から削除され、URLが更新されます。

○サンプルコード4：クエリ文字列の構築

URLSearchParamsを使えば、クエリ文字列を一から構築することもできます。

const searchParams = new URLSearchParams();
searchParams.append('key1', 'value1');
searchParams.append('key2', 'value2');
const url = new URL(`https://example.com/?${searchParams.toString()}`);
console.log(url.toString()); 
// 出力結果
// 'https://example.com/?key1=value1&key2=value2'

appendメソッドを使ってキーと値のペアを追加していき、最後にtoStringメソッドでクエリ文字列に変換します。

これを新しいURLに組み込めば、望み通りのURLが構築できるというわけです。

●URLSearchParamsの応用テクニック

基本的な使い方は理解できたと思いますが、URLSearchParamsの本当の力はこれからです。

もっと実践的なテクニックを身につけて、業務の生産性を上げていきましょう。

○サンプルコード5：クエリパラメータの存在チェック

例えば、特定のクエリパラメータが存在するかどうかを確認したい場合ってありますよね。

そんな時は、hasメソッドが役立ちます。

const url = new URL('https://example.com/?key1=value1&key2=value2');
const searchParams = url.searchParams;
console.log(searchParams.has('key1')); // true
console.log(searchParams.has('key3')); // false

hasメソッドは、指定したキーがクエリ文字列に存在すればtrue、存在しなければfalseを返します。

条件分岐を使ったパラメータの有無による処理の切り替えに便利ですね。

○サンプルコード6：クエリパラメータの反復処理

クエリパラメータを1つずつ処理していきたい場合は、forEachメソッドが使えます。

const url = new URL('https://example.com/?key1=value1&key2=value2');
const searchParams = url.searchParams;
searchParams.forEach((value, key) => {
  console.log(`${key}: ${value}`);
});
// 出力結果
// key1: value1
// key2: value2

forEachメソッドは、各パラメータのキーと値を引数に取るコールバック関数を実行します。

これを使えば、パラメータを1つずつ処理できるので、例えば特定の条件を満たすパラメータだけを取得したりできますね。

○サンプルコード7：オブジェクトとの相互変換

URLSearchParamsとオブジェクトを相互に変換できると、コードの柔軟性が高まります。

fromEntries/Objectのメソッドを使えば簡単に変換できますよ。

const searchParams = new URLSearchParams('key1=value1&key2=value2');
const obj = Object.fromEntries(searchParams);
console.log(obj); 
// 出力結果
// { key1: 'value1', key2: 'value2' }

const newSearchParams = new URLSearchParams(obj);  
console.log(newSearchParams.toString());
// 出力結果
// 'key1=value1&key2=value2'

Object.fromEntriesメソッドを使えば、URLSearchParamsをオブジェクトに変換できます。

逆に、オブジェクトからURLSearchParamsを作ることもできます。

これを応用すれば、オブジェクトで扱いやすいような複雑なパラメータ操作も、最終的にはURLSearchParamsに戻してURLに組み込むことができるんです。

○サンプルコード8：複数の値を持つパラメータの処理

同じキー名で複数の値を持つパラメータを扱う際は、getAll/appendメソッドが便利です。

const searchParams = new URLSearchParams('key1=value1&key1=value2&key2=value3');

console.log(searchParams.getAll('key1')); // ['value1', 'value2']
console.log(searchParams.get('key1')); // 'value1' (最初の値のみ)

searchParams.append('key1', 'value4');  
console.log(searchParams.getAll('key1')); // ['value1', 'value2', 'value4']

getAllメソッドを使えば、同じキー名を持つ全ての値を配列で取得できます。

一方、通常のgetメソッドでは最初の値だけが取得されるので注意が必要ですね。

また、appendメソッドを使えば、既存のキーに新しい値を追加することもできます。

○サンプルコード9：URLの更新とブラウザ履歴への追加

URLSearchParamsを使って現在のURLを更新したい場合は、window.historyと組み合わせると便利です。

const url = new URL(window.location);
url.searchParams.set('key', 'value');

window.history.pushState({}, '', url);    
// URLを更新し、ブラウザの履歴に追加する
// 例: https://example.com/?key=value

window.historyのpushStateメソッドを使えば、URLを更新しつつ、ブラウザの履歴にも新しいエントリを追加できます。

これによって、ユーザーがブラウザの戻るボタンを押した時に、更新前のURLに戻ることができるようになります。

●よくあるエラーと対処法

URLSearchParamsを使っていると、時々厄介なエラーに遭遇することがあります。

でも大丈夫、ここではそんなエラーへの対処法を詳しく解説していきますからね。

あなたのコーディングライフがちょっとでも楽になれば嬉しいです。

○エラー1：クエリ文字列のパースに失敗する

新しいURLSearchParamsオブジェクトを作る際、不正な形式のクエリ文字列を渡すとエラーが発生することがあります。

例えばこんな感じです。

const searchParams = new URLSearchParams('key1=value1&key2=value2&key3');
// TypeError: Invalid query string

ご覧の通り、「key3」にはイコール記号も値も付いていません。

こういう不正な形式のクエリ文字列を渡すと、TypeErrorが発生してしまうんですよね。

こんな時の対処法としては、try…catch文を使ってエラーをキャッチするのが良いでしょう。

そして、エラーが発生した場合は、デフォルトのクエリ文字列を使うようにするんです。

let searchParams;
try {
  searchParams = new URLSearchParams('key1=value1&key2=value2&key3');
} catch (e) {
  console.error('Error parsing query string:', e);
  searchParams = new URLSearchParams('');
}

こうすれば、不正な形式のクエリ文字列が渡されても、アプリケーションが停止することはありません。

エラーをキャッチして適切に処理することが大切ですね。

○エラー2：既存のURLを上書きしてしまう

既存のURLオブジェクトを再利用する際、うっかりsearchプロパティを直接上書きしてしまうと、予期せぬ動作につながることがあります。

例えばこんなコードです。

const url = new URL('https://example.com/?key1=value1');
url.search = 'key2=value2';
console.log(url.toString()); 
// 'https://example.com/?key2=value2'

ご覧の通り、元々あった「key1=value1」が消えてしまいました。

これでは困りますよね。

こんな時は、searchプロパティを直接操作するのではなく、必ずURLSearchParamsを使うようにしましょう。

const url = new URL('https://example.com/?key1=value1');
url.searchParams.append('key2', 'value2');
console.log(url.toString());
// 'https://example.com/?key1=value1&key2=value2'

appendメソッドを使えば、既存のクエリパラメータを保持したまま新しいパラメータを追加できます。

URLSearchParamsを使うことで、こういったミスを防げるんですね。

○エラー3：キー名や値のエンコーディングを忘れる

キー名や値に特殊文字が含まれる場合、それらを適切にエンコードしないとエラーの原因になります。

例えばこんな感じです。

const searchParams = new URLSearchParams();
searchParams.append('key&', 'あア亜');
console.log(searchParams.toString());
// 'key&=あア亜' (不正なクエリ文字列)

ご覧の通り、キー名に「&」が、値に非ASCII文字が含まれています。

これらはエンコードしないと不正なクエリ文字列になってしまいます。

こんな時は、encodeURIComponent関数を使ってキー名と値をエンコードするのが良いでしょう。

const searchParams = new URLSearchParams();
const key = encodeURIComponent('key&'); 
const value = encodeURIComponent('あア亜');
searchParams.append(key, value);
console.log(searchParams.toString()); 
// 'key%26=%E3%81%82%E3%82%A2%E4%BA%9C'

エンコードされたクエリ文字列なら、特殊文字が含まれていても問題ありません。

逆に、クエリ文字列からキーと値を取り出す際は、decodeURIComponent関数を使ってデコードすることを忘れずに。

○エラー4：未対応ブラウザでのエラー

URLSearchParamsはモダンブラウザではサポートされていますが、古いブラウザ、特にInternet Explorer (IE)では使えません。もしあなたのアプリケーションがIEもサポートしているなら、URLSearchParamsを使う前にブラウザチェックをするのが賢明です。

if ('URLSearchParams' in window) {
  // URLSearchParamsを使ったコード
} else {
  // 代替コード 
}

IEをサポートする必要がないなら、Babelなどのトランスパイラを使って古いブラウザでも動くようにコードを変換するのも手ですね。

●URLSearchParamsの活用シーン

さて、ここまででURLSearchParamsの基本的な使い方から応用テクニック、よくあるエラーまで一通り見てきました。

でも、知識を実践で活かさなければ本当の力にはなりませんよね。

そこで、これからはURLSearchParamsを実際のアプリケーション開発でどう活用できるのか、具体的なシーンを見ていきましょう。

きっとあなたの開発スキルがさらに磨かれるはずです。

○サンプルコード10：ページネーションのURL生成

例えば、検索結果や商品リストのページネーションを実装する際、URLSearchParamsはとても便利に使えます。

現在のページ番号をクエリパラメータで管理することで、ユーザーはURLを共有したりブックマークしたりできるようになります。

しかも、サーバー側での処理も楽になりますね。

const searchParams = new URLSearchParams(window.location.search);
const currentPage = Number(searchParams.get('page')) || 1;
const perPage = 20;

// 次のページのURLを生成する
const nextPage = currentPage + 1;
searchParams.set('page', nextPage);
const nextUrl = `${window.location.pathname}?${searchParams.toString()}`;

// 次のページのリンクを表示する
const link = document.createElement('a');
link.href = nextUrl;
link.textContent = `Next Page (${nextPage})`;
document.body.appendChild(link);

このコードでは、現在のページ番号をクエリパラメータ「page」から取得し、次のページのURLを生成しています。

生成されたURLを使って「次のページ」リンクを動的に表示していますね。

こんな風に、URLSearchParamsを使えばページネーションのURLを簡単に管理できます。

ページ番号の増減や、1ページあたりの表示件数の変更なども容易ですよ。

○検索フォームとの連携

検索フォームの入力内容をクエリパラメータで表現するのにも、URLSearchParamsは大活躍します。


ユーザーが入力した検索条件をクエリ文字列に変換することで、検索結果のURLを共有可能にしたり、検索条件を保持したままページ遷移したりできるようになります。

<form id="searchForm">
  <input type="text" name="q" placeholder="Search...">
  <select name="category">
    <option value="">All Categories</option>    
    <option value="1">Category 1</option>
    <option value="2">Category 2</option>
  </select>
  <button type="submit">Search</button>
</form>
const searchForm = document.getElementById('searchForm');
searchForm.addEventListener('submit', (event) => {
  event.preventDefault();
  const formData = new FormData(searchForm);
  const searchParams = new URLSearchParams(formData);
  const url = `${window.location.pathname}?${searchParams.toString()}`;
  window.location.href = url;
});

ここでは、検索フォームの入力値をFormDataオブジェクトで取得し、それをURLSearchParamsに変換しています。

変換されたクエリ文字列を使って検索結果ページのURLを構築し、そのURLにリダイレクトしていますね。

こうすることで、ユーザーは検索条件を保持したままページ遷移ができるようになります。

サーバー側でも、クエリパラメータから検索条件を復元して検索処理を行えば良いだけですね。

○アプリケーションの状態管理

クエリパラメータを使ってアプリケーションの状態を管理するのも、URLSearchParamsならお手の物です。

例えば、複雑な入力フォームの内容をクエリパラメータで表現しておけば、ページをリロードしても入力内容を復元できるようになります。

const form = document.getElementById('myForm');
const searchParams = new URLSearchParams(window.location.search);

// クエリパラメータから入力内容を復元する
for (const [name, value] of searchParams.entries()) {
  const input = form.elements[name];
  if (input) {
    input.value = value;
  }  
}

form.addEventListener('input', () => {  
  // 入力内容をクエリパラメータに反映する
  const formData = new FormData(form);
  const newSearchParams = new URLSearchParams(formData);
  const newUrl = `${window.location.pathname}?${newSearchParams.toString()}`;
  window.history.replaceState(null, '', newUrl);
});

このコードでは、ページ読み込み時にクエリパラメータから入力内容を復元しています。

そして、フォームの入力イベントを監視し、入力内容が変更されるたびにクエリパラメータを更新しています。

こうすることで、ユーザーはページをリロードしても入力内容を失うことなく作業を続けられるようになります。

複雑な設定画面などで重宝しそうですね。

○APIリクエストパラメータの処理

サーバーサイドのAPIとの通信の際、リクエストパラメータの処理にもURLSearchParamsが使えます。

クライアントサイドでURLSearchParamsを使ってリクエストパラメータを構築し、そのままAPIのURLに付加することで、サーバー側での処理が楽になります。

async function fetchData(params) {
  const searchParams = new URLSearchParams(params);
  const url = `https://api.example.com/data?${searchParams.toString()}`;
  const response = await fetch(url);
  const data = await response.json();
  return data;
}

// APIリクエストパラメータを指定して関数を呼び出す
const params = { category: 1, sort: 'desc' };
const data = await fetchData(params);
console.log(data);

ここでは、fetchData関数の引数としてリクエストパラメータを受け取り、それをURLSearchParamsに変換してAPIのURLに付加しています。

こうすることで、サーバー側ではリクエストパラメータの解析が楽になりますし、クライアント側でもパラメータの管理が簡単になります。

Win-Winの関係ですね。

まとめ

さて、ここまでURLSearchParamsについて詳しく解説してきました。

基本的な使い方から応用テクニック、エラー対処法、実践的な活用シーンまで、様々な側面からURLSearchParamsについてご理解いただけたことかと思います。

開発に少しでも役立てば幸いです。

それでは、また次の記事でお会いしましょう！