URLSearchParams: URLSearchParams() コンストラクター

Baseline Widely available

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

URLSearchParams() コンストラクターは、新しい URLSearchParams オブジェクトを作成して返します。

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

構文

js
new URLSearchParams()
new URLSearchParams(options)

引数

options 省略可

以下のいずれか。

  • 文字列。先頭の文字 '?' は無視され、application/x-www-form-urlencoded 形式としてパースされます。
  • 名前を表す文字列と値を表す文字列のペアのリテラル列、もしくはそのような文字列のペアの列を生成するイテレーターを持つ任意のオブジェクト（たとえば FormData のオブジェクト）。なお、File のエントリーは（application/x-www-form-urlencoded 形式で期待される）ファイル名ではなく [object File] としてシリアライズされます。
  • 文字列のキーと文字列の値からなるレコード。なお、ネストには対応していません。

返値

URLSearchParams のインスタンスです。

例

以下の例では、様々な入力から URLSearchParams オブジェクトを生成する方法を示します。

js
// url.search からパラメーターを取得し、コンストラクターに渡す
const url = new URL("https://example.com?foo=1&bar=2");
const params1 = new URLSearchParams(url.search);

// URL オブジェクトから直接 URLSearchParams オブジェクトを取得する
const params1a = url.searchParams;

// 文字列リテラルを渡す
const params2 = new URLSearchParams("foo=1&bar=2");
const params2a = new URLSearchParams("?foo=1&bar=2");

// ペアの列を渡す
const params3 = new URLSearchParams([
  ["foo", "1"],
  ["bar", "2"],
]);

// レコードを渡す
const params4 = new URLSearchParams({ foo: "1", bar: "2" });

この例では、検索パラメーターを持つ既存の URL から、検索パラメーターを表すオブジェクトを用い、新しい URL を構築する方法を示します。

js
const url = new URL("https://example.com/?a=hello&b=world");

console.log(url.href);
// https://example.com/?a=hello&b=world

console.log(url.origin);
// https://example.com

const add_params = {
  c: "a",
  d: new String(2),
  e: false.toString(),
};

const new_params = new URLSearchParams([
  ...Array.from(url.searchParams.entries()), // [["a","hello"],["b","world"]]
  ...Object.entries(add_params), // [["c","a"],["d","2"],["e","false"]]
]).toString();
console.log(new_params);
// a=hello&b=world&c=a&d=2&e=false

const new_url = new URL(`${url.origin}${url.pathname}?${new_params}`);

console.log(new_url.href);
// https://example.com/?a=hello&b=world&c=a&d=2&e=false

// (URL, Record<string, string>) を受け取る関数の形式で
const addSearchParams = (url, params = {}) =>
  new URL(
    `${url.origin}${url.pathname}?${new URLSearchParams([
      ...Array.from(url.searchParams.entries()),
      ...Object.entries(params),
    ])}`,
  );

仕様書

Specification
URL
# dom-urlsearchparams-urlsearchparams

ブラウザーの互換性