URLSearchParams.keys() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.keys()

Beschreibung

Die Methode keys() liefert einen Iterator, der nacheinander die Namen aller Query-Parameter zurückgibt. Die Reihenfolge entspricht der Reihenfolge im Query-String bzw. der Reihenfolge, in der die Einträge hinzugefügt wurden.

Wichtig: Kommt ein Schlüssel mehrfach vor (z. B. ?tag=a&tag=b), liefert der Iterator ihn auch mehrfach. Brauchen Sie eindeutige Namen, wandeln Sie das Ergebnis in ein Set um.

Typische Anwendungsfälle sind das Prüfen, welche Filter in einer URL gesetzt sind, das Aufbauen von Formularzuständen aus der Adresszeile oder das Loggen und Validieren eingehender Parameter, z. B. gegen eine Liste erlaubter Namen.

Der Rückgabewert ist ein Iterator und kein Array. Er lässt sich mit for...of durchlaufen oder mit Array.from() bzw. dem Spread-Operator in ein Array umwandeln.

Rückgabewert

Typ

Iterator<string>

Beschreibung

Ein Iterator, der alle Schlüssel als bereits dekodierte Zeichenketten liefert. Doppelte Schlüssel sind mehrfach enthalten.

Beispiele

Alle Schlüssel mit for...of ausgeben

const params = new URLSearchParams('q=javascript&page=2&sort=asc');

for (const key of params.keys()) {
  console.log(key);
}

q page sort

Eindeutige Schlüssel bei Mehrfachwerten

const params = new URLSearchParams('tag=js&tag=web&lang=de');

console.log([...params.keys()]);
console.log([...new Set(params.keys())]);

[ 'tag', 'tag', 'lang' ] [ 'tag', 'lang' ]

Unbekannte Parameter aus der aktuellen URL erkennen

const erlaubt = new Set(['q', 'page', 'sort']);
const params = new URL('https://example.com/suche?q=css&page=1&debug=1').searchParams;

const unbekannt = [...new Set(params.keys())].filter((key) => !erlaubt.has(key));
console.log(unbekannt);

[ 'debug' ]

Parameter sicher entfernen (erst kopieren, dann löschen)

const params = new URLSearchParams('utm_source=nl&utm_medium=mail&id=42');

// Schlüssel zuerst in ein Array kopieren, da delete() den Iterator beeinflusst
const utmKeys = [...params.keys()].filter((key) => key.startsWith('utm_'));
utmKeys.forEach((key) => params.delete(key));

console.log(params.toString());

id=42

// Wichtig · Fallstricke

Keine eindeutigen Schlüssel: Doppelte Namen erscheinen mehrfach. Für eindeutige Schlüssel verwenden Sie new Set(params.keys()).
Iterator statt Array: Methoden wie map() oder filter() gibt es darauf erst nach Array.from() oder [...]. Die neueren Iterator-Helfer wie .filter() direkt am Iterator werden noch nicht überall unterstützt. Ein Iterator lässt sich nur einmal durchlaufen.
Ändern während der Iteration: Wenn Sie während der Schleife delete() oder append() aufrufen, kann das Ergebnis unerwartet sein, z. B. übersprungene Einträge. Kopieren Sie die Schlüssel vorher in ein Array.
Dekodierung: Die Schlüssel sind bereits dekodiert. + wird zu einem Leerzeichen, %C3%A4 wird zu ä.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Im Internet Explorer fehlt die Methode, dort ist ein Polyfill nötig. In Node.js ist URLSearchParams seit Version 10 global verfügbar.

Siehe auch

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