URLSearchParams.entries() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.entries()

Beschreibung

Die Methode entries() des Interfaces URLSearchParams gibt einen Iterator zurück, der alle enthaltenen Query-Parameter als zweielementige Arrays [name, value] liefert. Schlüssel und Werte sind immer Zeichenketten und bereits dekodiert. Aus %20 oder + wird also ein Leerzeichen.

Die Reihenfolge entspricht der Reihenfolge im Query-String bzw. der Einfügereihenfolge. Kommt ein Schlüssel mehrfach vor (z. B. ?tag=a&tag=b), liefert der Iterator jedes Vorkommen einzeln. Das ist der wichtigste Unterschied zu get(), das nur den ersten Wert zurückgibt.

entries() ist der Standard-Iterator von URLSearchParams: params[Symbol.iterator] === params.entries. Deshalb funktionieren for...of, die Spread-Syntax und Object.fromEntries() auch direkt mit dem Objekt. Man ruft entries() vor allem dann ausdrücklich auf, wenn man einen echten Iterator braucht, etwa für next() oder die Iterator-Helfer.

Rückgabewert

Typ

URLSearchParams Iterator (Iterator<[string, string]>)

Beschreibung

Ein Iterator, dessen Werte Arrays der Form [name, value] sind, jeweils mit zwei Zeichenketten.

Beispiele

Alle Query-Parameter einer URL ausgeben

const url = new URL('https://shop.example/suche?q=rote+Schuhe&groesse=42&sort=preis');

for (const [name, value] of url.searchParams.entries()) {
  console.log(`${name} = ${value}`);
}

q = rote Schuhe groesse = 42 sort = preis

Mehrfach vorkommende Schlüssel gruppieren

const params = new URLSearchParams('tag=js&tag=web&tag=api&page=2');

const grouped = {};
for (const [key, value] of params.entries()) {
  (grouped[key] ??= []).push(value);
}
console.log(grouped);

// Achtung: Object.fromEntries behält nur den letzten Wert
console.log(Object.fromEntries(params.entries()));

{ tag: [ 'js', 'web', 'api' ], page: [ '2' ] } { tag: 'api', page: '2' }

Iterator manuell mit next() durchlaufen

const params = new URLSearchParams({ user: 'anna', lang: 'de' });
const it = params.entries();

console.log(it.next());
console.log(it.next());
console.log(it.next());

{ value: [ 'user', 'anna' ], done: false } { value: [ 'lang', 'de' ], done: false } { value: undefined, done: true }

Formulardaten in eine Map überführen

const params = new URLSearchParams(location.search);
const filters = new Map(params.entries());

if (filters.has('kategorie')) {
  console.log('Filter aktiv:', filters.get('kategorie'));
}
console.log([...params.entries()].length, 'Parameter gefunden');

// Wichtig · Fallstricke

Doppelte Schlüssel: Object.fromEntries() und new Map() überschreiben mehrfach vorkommende Schlüssel. Übrig bleibt der zuletzt gelesene Wert. Wenn alle Werte erhalten bleiben sollen, gruppiert man selbst oder nutzt getAll().
Live-Verhalten: Der Iterator arbeitet mit dem aktuellen Zustand der Liste. Wer während der Iteration mit delete(), append() oder set() ändert, kann Einträge überspringen. Deshalb vorher mit [...params.entries()] eine Kopie anlegen.
Einmal verbraucht: Ein Iterator lässt sich nur einmal durchlaufen. Für einen zweiten Durchlauf ruft man entries() erneut auf.
Nur Zeichenketten: Alle Werte kommen als Strings zurück ('42', nicht 42). Zahlen und Wahrheitswerte muss man selbst umwandeln.
Kompatibilität: Wird von allen modernen Browsern und von Node.js unterstützt (dort global ab v10). Der Internet Explorer kennt URLSearchParams nicht, dafür ist ein Polyfill nötig.

Siehe auch

URLSearchParams URLSearchParams.keys() URLSearchParams.values() URLSearchParams.forEach() URLSearchParams.getAll() URL.searchParams Object.fromEntries() for...of