URLSearchParams.has() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.has(name, value)

Beschreibung

Die Methode has() eines URLSearchParams-Objekts gibt true zurück, wenn mindestens ein Name-Wert-Paar mit dem angegebenen Namen existiert, sonst false. Damit lässt sich einfach prüfen, ob ein Query-Parameter wie ?debug oder ?page=2 in einer URL vorkommt.

Wird zusätzlich das Argument value übergeben, liefert has() nur dann true, wenn ein Paar mit genau diesem Namen und genau diesem Wert existiert. Das hilft vor allem bei mehrfach vorkommenden Parametern wie ?tag=js&tag=css, weil man dann nicht erst mit getAll() ein Array holen und durchsuchen muss.

has() ist die richtige Wahl, wenn schon das Vorhandensein eines Parameters etwas bedeutet, zum Beispiel bei Schaltern ohne Wert wie ?preview. get() gibt bei ?preview einen leeren String "" zurück, und der gilt als falsy. has() unterscheidet dagegen sauber zwischen „nicht vorhanden“ und „vorhanden, aber leer“.

Der Vergleich beachtet Groß- und Kleinschreibung. Er arbeitet mit den dekodierten Namen und Werten: Aus %20 und + in der Query wird ein Leerzeichen.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des gesuchten Parameters (in dekodierter Form). Andere Typen werden in einen String umgewandelt.
$value	string	undefined	Optionaler Wert. Wenn angegeben, muss ein Paar mit genau diesem Namen und genau diesem Wert existieren. `undefined` wird so behandelt, als fehle das Argument.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn ein passendes Name-Wert-Paar existiert, sonst false.

Beispiele

Schalter aus der Adresszeile lesen

// Beispiel-URL: https://example.com/shop?debug&page=2
const params = new URLSearchParams('?debug&page=2');

if (params.has('debug')) {
  console.log('Debug-Modus aktiv');
}

console.log(params.has('page'));   // Parameter vorhanden
console.log(params.has('sort'));   // Parameter fehlt
console.log(params.has('Page'));   // Groß-/Kleinschreibung zählt

Debug-Modus aktiv true false false

Unterschied zwischen has() und get() bei leeren Werten

const params = new URLSearchParams('preview=&lang=de');

// get() liefert einen leeren String, und der ist falsy
console.log(Boolean(params.get('preview'))); // false – irreführend!

// has() erkennt korrekt, dass der Parameter vorhanden ist
console.log(params.has('preview'));

false true

Bestimmtes Name-Wert-Paar prüfen (Filter-Tags)

const url = new URL('https://example.com/artikel?tag=js&tag=css&tag=html');
const { searchParams } = url;

const toggleTag = (tag) => {
  if (searchParams.has('tag', tag)) {
    searchParams.delete('tag', tag); // entfernt nur dieses Paar
  } else {
    searchParams.append('tag', tag);
  }
};

toggleTag('css');
toggleTag('node');
console.log(url.search);

?tag=js&tag=html&tag=node

Kodierte Namen werden dekodiert verglichen

const params = new URLSearchParams('voller%20name=Anna&stadt=Bad+T%C3%B6lz');

console.log(params.has('voller name'));
console.log(params.has('voller%20name'));
console.log(params.has('stadt', 'Bad Tölz'));

true false true

// Wichtig · Fallstricke

Kompatibilität: has(name) gibt es in allen modernen Browsern und in Node.js (global ab Version 10). Das zweite Argument value ist neuer: Chrome/Edge 117, Firefox 115, Safari 17, Node.js 20.2 bzw. 18.18. Ältere Umgebungen ignorieren das zweite Argument einfach und prüfen nur den Namen. Dann liefert has('tag', 'x') ohne Fehlermeldung true, sobald irgendein tag vorkommt. Wenn du ältere Umgebungen unterstützen musst, nimm stattdessen params.getAll('tag').includes('x').
has() berücksichtigt keinen Wert. Bei ?page= gibt has('page') also true zurück, obwohl der Wert leer ist.
Der Name muss in dekodierter Form übergeben werden. Ein + in der Query wird als Leerzeichen gelesen. Wer ein echtes Plus-Zeichen meint, muss es in der URL als %2B kodieren.
Den Parameter value nicht als undefined weitergeben, wenn eigentlich die Prüfung „irgendein Wert“ gemeint ist. Umgekehrt gilt: Wird eine Variable durchgereicht, die undefined ist, prüft has() nur den Namen.
Werte und Namen, die keine Strings sind, werden umgewandelt: has('id', 5) entspricht has('id', '5').

Siehe auch

URLSearchParams URLSearchParams.get() URLSearchParams.getAll() URLSearchParams.delete() URLSearchParams.set() URLSearchParams.append() URL.searchParams