URLSearchParams: URLSearchParams() Konstruktor

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.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Der URLSearchParams()-Konstruktor erstellt und gibt ein neues URLSearchParams-Objekt zurück.

Syntax

js
new URLSearchParams()
new URLSearchParams(options)

Parameter

options Optional

Eine der folgenden Optionen:

  • Ein String, der aus dem Format application/x-www-form-urlencoded geparst wird. Ein führendes '?'-Zeichen wird ignoriert. Dies ist die einzige Form, die das Prozent-Codierung dekodiert und + in U+0020 SPACE umwandelt.
  • Eine wörtliche Sequenz von Name-Wert-Paaren als String oder ein beliebiges Objekt — wie ein FormData-Objekt — mit einem Iterator, der eine Sequenz von String-Paaren erzeugt. Beachten Sie, dass File-Einträge als [object File] serialisiert werden, anstatt als ihr Dateiname (wie in einem application/x-www-form-urlencoded-Formular).
  • Ein Datensatz von String-Schlüsseln und String-Werten. Beachten Sie, dass Verschachtelung nicht unterstützt wird.

Rückgabewert

Eine Instanz des URLSearchParams-Objekts.

Beispiele

Das folgende Beispiel zeigt, wie man ein URLSearchParams-Objekt aus verschiedenen Eingaben erstellt.

js
// Retrieve params via url.search, passed into constructor
const url = new URL("https://example.com?foo=1&bar=2");
const params1 = new URLSearchParams(url.search);

// Get the URLSearchParams object directly from a URL object
const params1a = url.searchParams;

// Pass in a string literal
const params2 = new URLSearchParams("foo=1&bar=2");
const params2a = new URLSearchParams("?foo=1&bar=2");

// Pass in a sequence of pairs
const params3 = new URLSearchParams([
  ["foo", "1"],
  ["bar", "2"],
]);

// Pass in a record
const params4 = new URLSearchParams({ foo: "1", bar: "2" });

Dieses Beispiel zeigt, wie man eine neue URL mit einem Objekt von Suchparametern aus einer bestehenden URL erstellt, die Suchparameter enthält.

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: 2,
  e: false,
};

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

// Here it is as a function that accepts (URL, Record<string, string>)
const addSearchParams = (url, params = {}) =>
  new URL(
    `${url.origin}${url.pathname}?${new URLSearchParams([
      ...Array.from(url.searchParams.entries()),
      ...Object.entries(params),
    ])}`,
  );

Spezifikationen

Specification
URL
# dom-urlsearchparams-urlsearchparams

Browser-Kompatibilität