URLSearchParams

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

メモ: この機能はウェブワーカー内で利用可能です。

URLSearchParams インターフェイスは、URL のクエリー文字列の操作に役立つメソッドを定義します。

URLSearchParams オブジェクトは反復可能ですので、for...of 構造の中で直接使用して、キーと値のペアをクエリー文字列に現れるのと同じ順序で反復処理することができます。例えば次の 2 行は等価です。

for (const [key, value] of mySearchParams) {
}
for (const [key, value] of mySearchParams.entries()) {
}

URLSearchParams は機能的には Map に似ていますが、反復処理を行う際には、Map では実装方法の関係で発生しないような落とし穴に陥る可能性があります。

コンストラクター

URLSearchParams(): URLSearchParams オブジェクトを返すコンストラクターです。

インスタンスメソッド

URLSearchParams[Symbol.iterator](): このオブジェクトに含まれるすべてのキーと値のペアを、クエリー文字列に現れるのと同じ順序で反復処理することができるイテレーターを返します。
URLSearchParams.append(): 指定されたキーと値のペアを新しい検索パラメーターとして追加します。
URLSearchParams.delete(): 指定された名前と値に一致する検索パラメーターを、検索パラメーターのリストからすべて削除します。
URLSearchParams.entries(): このオブジェクトに含まれるすべてのキーと値のペアを、クエリー文字列に現れるのと同じ順序で反復処理することができるイテレーターを返します。
URLSearchParams.forEach(): コールバック関数を介して、このオブジェクトに含まれるすべての値を反復処理します。
URLSearchParams.get(): 指定された検索パラメーターに対応する最初の値を返します。
URLSearchParams.getAll(): 指定された検索パラメーターに対応するすべての値を返します。
URLSearchParams.has(): 指定されたパラメーター、またはパラメーターと値のペアが存在するかどうかを示す論理値を返します。
URLSearchParams.keys(): このオブジェクトに含まれるすべてのキーと値のペアのキーを反復処理するイテレーターを返します。
URLSearchParams.set(): 指定された検索パラメーターに結び付けられた値を指定された値に設定します。複数の値が存在していた場合、他のものは削除されます。
URLSearchParams.sort(): すべてのキーと値のペアを、キーを基準にソートします。
URLSearchParams.toString(): URL で使用するのに適したクエリー文字列を返します。
URLSearchParams.values(): このオブジェクトに含まれるすべてのキーと値のペアの値を反復処理するイテレーターを返します。

例

const paramsString = "q=URLUtils.searchParams&topic=api";
const searchParams = new URLSearchParams(paramsString);

// 検索パラメーターの列挙
for (const p of searchParams) {
  console.log(p);
}

console.log(searchParams.has("topic")); // true
console.log(searchParams.has("topic", "fish")); // false
console.log(searchParams.get("topic") === "api"); // true
console.log(searchParams.getAll("topic")); // ["api"]
console.log(searchParams.get("foo") === null); // true
console.log(searchParams.append("topic", "webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=api&topic=webdev"
console.log(searchParams.set("topic", "More webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=More+webdev"
console.log(searchParams.delete("topic"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams"

// 検索パラメーターはオブジェクトにすることもできる
const paramsObj = { foo: "bar", baz: "bar" };
const searchParams = new URLSearchParams(paramsObj);

console.log(searchParams.toString()); // "foo=bar&baz=bar"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // "bar"

重複する検索パラメーター

const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);

console.log(searchParams.toString()); // "foo=bar&foo=baz"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // bar （最初の値のみを返す）
console.log(searchParams.getAll("foo")); // ["bar", "baz"]

URL の解釈なし

URLSearchParams コンストラクターは URL 全体を解釈しません。しかし、もし存在すれば、文字列から最初の ? 以降を削除します。

const paramsString1 = "http://example.com/search?query=%40";
const searchParams1 = new URLSearchParams(paramsString1);

console.log(searchParams1.has("query")); // false
console.log(searchParams1.has("http://example.com/search?query")); // true

console.log(searchParams1.get("query")); // null
console.log(searchParams1.get("http://example.com/search?query")); // "@" （decodeURIComponent('%40') と同じ）

const paramsString2 = "?query=value";
const searchParams2 = new URLSearchParams(paramsString2);
console.log(searchParams2.has("query")); // true

const url = new URL("http://example.com/search?query=%40");
const searchParams3 = new URLSearchParams(url.search);
console.log(searchParams3.has("query")); // true

URLSearchParams コンストラクターはプラス記号 (+) を空白として解釈します。以下の例では、16 進エスケープシーケンスを使って、URL 検索パラメーターに格納する必要のあるバイナリーデータ（各バイトが情報を持つ）を含む文字列を模倣しています。btoa() でエンコードされた文字列は + を含んでおり、 URLSearchParams では温存されないことに注意してください。

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'
const binQuery = searchParams.get("bin"); // 'E AXQB A', '+' はスペースに置き換えられる

console.log(atob(binQuery) === rawData); // false

データを encodeURIComponent() でエンコードすることで、これを回避できます。

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'
const encodedBase64Data = encodeURIComponent(base64Data); // 'E%2BAXQB%2BA'

const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get("bin"); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true

空の値と値なし

URLSearchParams は = の後に何もないパラメーターと、= もないパラメーターの区別をしません。

const emptyVal = new URLSearchParams("foo=&bar=baz");
console.log(emptyVal.get("foo")); // '' を返す
const noEquals = new URLSearchParams("foo&bar=baz");
console.log(noEquals.get("foo")); // これも '' を返す
console.log(noEquals.toString()); // 'foo=&bar=baz'

仕様書

Specification
URL Standard # urlsearchparams

ブラウザーの互換性

BCD tables only load in the browser