クエリ文字列から生成

// クエリ文字列から生成（先頭の?は含めても含めなくても良い）
const params1 = new URLSearchParams("name=田中&age=30");
const params2 = new URLSearchParams("?name=田中&age=30");

オブジェクトから生成

// オブジェクトから生成
const params = new URLSearchParams({
  name: "田中",
  age: 30,
  hobby: ["読書", "旅行"]
});

URLオブジェクトのsearchプロパティから生成

// URLオブジェクトから検索パラメータを取得
const url = new URL("https://example.com/search?name=田中&age=30");
const params = url.searchParams;  // URLSearchParamsオブジェクトが取得できる

パラメータの取得

const params = new URLSearchParams("name=田中&age=30&tag=javascript&tag=programming");

// 特定のパラメータの値を取得（最初の値のみ）
const name = params.get("name");  // "田中"
const age = params.get("age");    // "30"
const notFound = params.get("email");  // null（存在しない場合はnull）

// 特定のパラメータの全ての値を取得（配列として）
const tags = params.getAll("tag");  // ["javascript", "programming"]

// パラメータの存在チェック
const hasName = params.has("name");  // true
const hasEmail = params.has("email");  // false

パラメータの追加・設定

const params = new URLSearchParams();

// パラメータの追加（同じキーを複数追加可能）
params.append("tag", "javascript");
params.append("tag", "programming");
console.log(params.toString());  // "tag=javascript&tag=programming"

// パラメータの設定（既存の値を上書き）
params.set("tag", "coding");
console.log(params.toString());  // "tag=coding"

// 複数のパラメータを一度に設定
params.set("name", "田中");
params.set("age", "30");
console.log(params.toString());  // "tag=coding&name=田中&age=30"

パラメータの削除

const params = new URLSearchParams("name=田中&age=30&tag=javascript&tag=programming");

// 特定のパラメータを削除
params.delete("age");
console.log(params.toString());  // "name=田中&tag=javascript&tag=programming"

// 特定のキーの全てのパラメータを削除
params.delete("tag");
console.log(params.toString());  // "name=田中"

パラメータの一括操作

const params = new URLSearchParams("name=田中&age=30");

// 全てのパラメータをクリア
params.forEach((value, key) => {
  console.log(`${key}: ${value}`);  // "name: 田中", "age: 30"
});

// 全てのキーを取得
for (const key of params.keys()) {
  console.log(key);  // "name", "age"
}

// 全ての値を取得
for (const value of params.values()) {
  console.log(value);  // "田中", "30"
}

// 全てのエントリー（[key, value]のペア）を取得
for (const [key, value] of params.entries()) {
  console.log(`${key}: ${value}`);  // "name: 田中", "age: 30"
}

// 全てのエントリーを取得（Iterator）
const iterator = params.entries();
console.log(iterator.next().value);  // ["name", "田中"]
console.log(iterator.next().value);  // ["age", "30"]

クエリ文字列への変換

const params = new URLSearchParams();
params.set("name", "田中");
params.set("age", "30");

// クエリ文字列に変換
const queryString = params.toString();  // "name=田中&age=30"

// URLに適用
const url = new URL("https://example.com");
url.search = params.toString();
console.log(url.href);  // "https://example.com/?name=田中&age=30"

// または直接URLSearchParamsを設定
const url2 = new URL("https://example.com");
url2.searchParams.append("name", "田中");
url2.searchParams.append("age", "30");
console.log(url2.href);  // "https://example.com/?name=田中&age=30"

文字列の自動エンコード

URLSearchParamsは自動的に値をURLエンコードするため、手動でエンコードする必要がありません。

const params = new URLSearchParams();
params.set("q", "JavaScriptとは？");
console.log(params.toString());  // "q=JavaScript%E3%81%A8%E3%81%AF%EF%BC%9F"

// すでにエンコードされた文字列を使用する場合は注意
const encodedParam = new URLSearchParams("q=JavaScript%E3%81%A8%E3%81%AF%EF%BC%9F");
console.log(encodedParam.get("q"));  // "JavaScriptとは？"（自動的にデコードされる）

数値と真偽値の扱い

URLSearchParamsは全ての値を文字列として扱います。数値や真偽値を設定する場合は、文字列に変換されることに注意しましょう。

const params = new URLSearchParams();
params.set("age", 30);         // 数値を設定
params.set("active", true);    // 真偽値を設定

console.log(params.get("age"));     // "30"（文字列）
console.log(params.get("active"));  // "true"（文字列）

// 数値に変換
const age = parseInt(params.get("age"), 10);  // 30（数値）

// 真偽値に変換
const active = params.get("active") === "true";  // true（真偽値）

同じキーを持つ複数のパラメータの扱い

Webフォームなどでは、同じ名前の複数のパラメータが送信されることがあります。URLSearchParamsでは、appendメソッドとgetAllメソッドを使用して、このような状況に対応できます。

// チェックボックスのグループなどで同じ名前の複数のパラメータがある場合
const params = new URLSearchParams();
params.append("hobby", "読書");
params.append("hobby", "旅行");
params.append("hobby", "料理");

// すべての値を取得
const hobbies = params.getAll("hobby");  // ["読書", "旅行", "料理"]

// 最初の値のみ取得
const firstHobby = params.get("hobby");  // "読書"

フォームデータとの連携

URLSearchParamsはFormDataオブジェクトと連携して使用することもできます。

// フォーム要素の取得
const form = document.querySelector("#search-form");

// フォームデータからURLSearchParamsを生成
const params = new URLSearchParams(new FormData(form));

// または手動でフォームの値を設定
const formData = new FormData();
formData.append("name", "田中");
formData.append("age", "30");
const params2 = new URLSearchParams(formData);

// クエリ文字列に変換
console.log(params2.toString());  // "name=田中&age=30"

URLSearchParamsの便利なユースケース