new URLSearchParams() — Methode · JavaScript-Referenz

Signatur

new URLSearchParams(options)

Beschreibung

Der Konstruktor URLSearchParams() erzeugt ein Objekt, mit dem sich der Query-Teil einer URL (alles nach dem ?) bequem lesen, verändern und wieder serialisieren lässt. Die Kodierung und Dekodierung von Sonderzeichen übernimmt das Objekt selbst – manuelles encodeURIComponent() und das Zerlegen von Strings mit split("&") entfallen.

Als Eingabe akzeptiert der Konstruktor mehrere Formen:

String: ein Query-String wie "q=js&page=2". Ein führendes ? wird ignoriert.
Objekt (Record): { q: "js", page: 2 } – Werte werden zu Strings umgewandelt.
Iterierbares von Paaren: z. B. [["tag", "a"], ["tag", "b"]], ein Map oder ein anderes URLSearchParams-Objekt. Nur so lassen sich doppelte Schlüssel direkt anlegen.
FormData: da FormData iterierbar ist, kann ein Formular direkt übernommen werden (nur Text-Felder sinnvoll).

Typische Einsatzfälle sind das Auslesen von Parametern aus location.search, das Bauen von Query-Strings für fetch()-Aufrufe sowie das Versenden von Formulardaten im Format application/x-www-form-urlencoded – ein URLSearchParams-Objekt kann direkt als body übergeben werden und setzt den passenden Content-Type automatisch.

Parameter

Name	Typ	Default	Beschreibung
$options	string \| Record<string, string> \| Iterable<[string, string]> \| URLSearchParams \| FormData	"" (leere Parameterliste)	Initiale Parameter. Ein String wird als Query-String geparst (führendes `?` wird entfernt), ein Objekt liefert Schlüssel-Wert-Paare über seine eigenen aufzählbaren Eigenschaften, ein Iterierbares muss Paare aus genau zwei Elementen liefern.

Rückgabewert

Typ

URLSearchParams

Beschreibung

Ein neues URLSearchParams-Objekt mit den übergebenen Parametern, das u. a. get(), set(), append(), delete(), has() und toString() bereitstellt und iterierbar ist.

Beispiele

Parameter aus der aktuellen URL auslesen

// z. B. bei https://example.com/suche?q=fetch+api&page=3
const params = new URLSearchParams(window.location.search);

const suchbegriff = params.get('q');
const seite = Number(params.get('page') ?? 1);

console.log(suchbegriff, seite);
console.log(params.has('sort'));

fetch api 3 false

Query-String aus einem Objekt für fetch() bauen

const filter = { kategorie: 'bücher', preisMax: 30, sortierung: 'neu & beliebt' };
const params = new URLSearchParams(filter);

console.log(params.toString());

const response = await fetch(`/api/produkte?${params}`);
const produkte = await response.json();

kategorie=b%C3%BCcher&preisMax=30&sortierung=neu+%26+beliebt

Mehrfach-Schlüssel über ein Array von Paaren

const params = new URLSearchParams([
  ['tag', 'javascript'],
  ['tag', 'web'],
  ['limit', '10']
]);

console.log(params.getAll('tag'));
console.log(params.get('tag'));
console.log(`${params}`);

[ 'javascript', 'web' ] javascript tag=javascript&tag=web&limit=10

Formular als application/x-www-form-urlencoded senden

const form = document.querySelector('#login');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const body = new URLSearchParams(new FormData(form));

  // Content-Type wird automatisch gesetzt
  const res = await fetch('/login', { method: 'POST', body });
  console.log(res.status);
});

// Wichtig · Fallstricke

Pluszeichen: Beim Parsen eines Strings wird + als Leerzeichen interpretiert. new URLSearchParams("a=1+2").get("a") ergibt "1 2". Rohe Werte mit + (z. B. Base64, Telefonnummern) vorher mit encodeURIComponent() kodieren oder per set() einfügen.
Kein vollständiger URL-Parser: Wird eine ganze URL wie "https://x.de/?a=1" übergeben, wird sie nicht zerlegt – der erste Schlüssel lautet dann "https://x.de/?a". Stattdessen new URL(str).searchParams verwenden.
Verschachtelte Objekte und Arrays werden nicht serialisiert: { ids: [1, 2] } wird zu ids=1%2C2, Objekte zu [object Object]. Für Mehrfachwerte ein Array von Paaren oder append() nutzen.
Werte wie null und undefined in Objekten werden zu den Strings "null" bzw. "undefined" – vorher herausfiltern.
Das Objekt ist eine Kopie: Änderungen wirken sich nicht auf location.search aus. Nur URL.prototype.searchParams ist mit seiner URL verknüpft. Zum Aktualisieren der Adresszeile history.replaceState() verwenden.
FormData mit File-Einträgen ergibt nur den Dateinamen als Wert – für Datei-Uploads FormData direkt senden.
Kompatibilität: in allen modernen Browsern verfügbar; der Internet Explorer unterstützt die API nicht. Die Objekt- und Paar-Initialisierung kam in älteren Browsern (vor ca. 2017) später hinzu.

Siehe auch

URLSearchParams URL.searchParams URLSearchParams.prototype.get() URLSearchParams.prototype.append() URLSearchParams.prototype.toString() URL FormData encodeURIComponent()