URLSearchParams.forEach() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.forEach(callbackFn, thisArg)

Beschreibung

Mit forEach() gehen Sie alle Query-Parameter eines URLSearchParams-Objekts der Reihe nach durch. Die Callback-Funktion bekommt pro Eintrag den Wert, den Schlüssel und das URLSearchParams-Objekt selbst übergeben, in genau dieser Reihenfolge. Das entspricht der Reihenfolge von Map.prototype.forEach(): Der Wert kommt zuerst.

Kommt ein Schlüssel mehrfach vor, zum Beispiel bei ?tag=js&tag=css, wird die Callback-Funktion für jedes Vorkommen einzeln aufgerufen. Die Methode eignet sich deshalb gut zum Protokollieren, zum Prüfen oder zum Umwandeln aller Parameter, etwa in ein Objekt, in Formularfelder oder in Einträge für Analysezwecke.

Die übergebenen Werte sind bereits dekodiert: Prozent-Kodierungen werden aufgelöst und + wird zu einem Leerzeichen. Wenn Sie vorzeitig abbrechen oder await verwenden müssen, ist eine for...of-Schleife über entries() meist die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$callbackFn Pflicht	(value: string, key: string, searchParams: URLSearchParams) => void		Funktion, die für jedes Paar aufgerufen wird. Sie erhält `value` (den dekodierten Wert), `key` (den dekodierten Schlüssel) und `searchParams` (das durchlaufene Objekt).
$thisArg	any	undefined	Wert, der beim Aufruf von `callbackFn` als `this` verwendet wird. Bei Pfeilfunktionen hat er keine Wirkung.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. forEach() ist nicht verkettbar und liefert kein neues Objekt.

Beispiele

Alle Query-Parameter ausgeben

const params = new URLSearchParams('?q=javascript&seite=2&sort=neu');

// Achtung: zuerst der Wert, dann der Schlüssel
params.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});

q = javascript seite = 2 sort = neu

Mehrfache Schlüssel zu Arrays zusammenfassen

const url = new URL('https://shop.example/suche?tag=js&tag=css&preis=10-50');
const filter = {};

url.searchParams.forEach((value, key) => {
  // Ein Schlüssel kann mehrfach vorkommen, daher Arrays anlegen
  (filter[key] ??= []).push(value);
});

console.log(filter);

{ tag: ['js', 'css'], preis: ['10-50'] }

Formularfelder aus der aktuellen URL vorbelegen

// Browser: Sucheingaben aus ?name=Anna&stadt=K%C3%B6ln wiederherstellen
const params = new URLSearchParams(window.location.search);

params.forEach((value, key) => {
  const field = document.querySelector(`[name="${CSS.escape(key)}"]`);
  if (field) field.value = value; // Wert ist bereits dekodiert, z. B. "Köln"
});

Verwendung von thisArg

const collector = {
  prefix: 'utm_',
  found: [],
};

const params = new URLSearchParams('utm_source=newsletter&id=7&utm_medium=email');

// Normale Funktion, damit thisArg als this greift
params.forEach(function (value, key) {
  if (key.startsWith(this.prefix)) this.found.push(`${key}:${value}`);
}, collector);

console.log(collector.found);

['utm_source:newsletter', 'utm_medium:email']

// Wichtig · Fallstricke

Reihenfolge der Argumente: Zuerst kommt value, dann key. Wer (key, value) => … schreibt, vertauscht Schlüssel und Werte. Dieser Fehler ist sehr häufig.
Kein Abbruch möglich: break und return beenden die Iteration nicht. Nutzen Sie stattdessen for (const [key, value] of params).
Kein async/await: Eine async-Callback-Funktion wird nicht abgewartet. Für nacheinander ablaufende asynchrone Aufgaben eignet sich for...of.
Ändern während der Iteration: Wenn Sie im Callback append(), delete() oder sort() aufrufen, ändern Sie die zugrunde liegende Liste mitten im Durchlauf. Das kann Einträge überspringen oder doppelt liefern. Arbeiten Sie deshalb besser mit einer Kopie (new URLSearchParams(params)).
Umwandlung in ein Objekt: Object.fromEntries(params) behält bei doppelten Schlüsseln nur den letzten Wert. Mit forEach() oder getAll() gehen keine Werte verloren.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt, außerdem von Node.js ab Version 10 (global) sowie von Deno und Bun. Der Internet Explorer unterstützt sie nicht.

Siehe auch

URLSearchParams URLSearchParams.entries() URLSearchParams.keys() URLSearchParams.values() URLSearchParams.getAll() URL.searchParams