1. 導入
Web開発において、URLのクエリパラメータ（?key=value）を操作することは日常的なタスクです。文字列操作で力技で置換しようとすると、エンコードの漏れや特殊文字の扱いでバグを生みがちです。URLSearchParams APIのsetメソッドを活用すれば、安全かつ簡潔にパラメータの追加・更新が可能になります。本記事では、このAPIの正しい使い方と実務で役立つTipsを解説します。
2. 基礎知識
URLSearchParamsは、URLのクエリ文字列を操作するための組み込みインターフェースです。
・append: 指定したキーが存在しても、新しい値を追加します（重複可）。
・set: 指定したキーが存在すれば値を置き換え、存在しなければ新しく追加します。
実務においては、検索条件の更新やページネーションの管理など、「特定のキーの値を最新に保つ」ケースが多いため、appendよりもsetを使う場面が圧倒的に多いです。
3. 実装/解決策
URLSearchParams.set(name, value) は、既存の値を上書きするという特性があるため、状態管理やURL生成において非常に予測しやすい挙動を提供します。
特に、SPAでのルーティング管理や、フォーム入力値に基づいた動的なクエリ生成において、余計な重複を気にせず実装できる点が強みです。
4. サンプルプログラム
以下は、現在のURLから特定のクエリパラメータを更新し、新しいURLを生成する実用的なコードです。
// 現在のURLが "https://example.com/search?q=old&page=1" だと仮定
const url = new URL(window.location.href);
// URLSearchParamsインスタンスを作成
const params = url.searchParams;
// setメソッドで特定のパラメータを更新
// 既存の 'q' は 'new_keyword' に置き換わり、'sort' は新規追加されます
params.set('q', 'new_keyword');
params.set('sort', 'desc');
// 変更後のクエリ文字列を取得
console.log(params.toString());
// 出力: "q=new_keyword&page=1&sort=desc"
// URL全体を更新する場合
url.search = params.toString();
console.log(url.href);
// 出力: "https://example.com/search?q=new_keyword&page=1&sort=desc"
5. 応用・注意点
実務で扱う際の重要な注意点が2つあります。
1. 同一キーの重複削除
setメソッドは、同じキーに対して複数の値が存在していた場合、そのすべてを削除し、指定した単一の値に置き換えます。もし「同じキーで複数の値（例: filter=a&filter=b）を保持したい」という要件がある場合は、setではなくappendを使うか、設計を見直す必要があります。
2. URLのエンコード
URLSearchParamsは、値のURLエンコードを自動的に処理してくれます。手動で文字列結合を行うと、スペースや日本語が含まれた際にエンコード漏れが発生し、サーバー側で正しくパースできないトラブルがよく起こります。URLSearchParams経由で値をセットする習慣をつければ、これらのエンコード問題は根本から回避可能です。
現場では、検索フォームの送信時などに「現在のURLSearchParamsをコピーし、setで更新したものを反映させる」というパターンを共通化しておくと、バグの少ないクリーンな実装が可能になります。