URL.searchParams — Eigenschaft · JavaScript-Referenz

Signatur

get URL.prototype.searchParams

Beschreibung

Die Eigenschaft searchParams einer URL-Instanz gibt ein URLSearchParams-Objekt zurück, das den Query-String (den Teil nach ?) in Form von Schlüssel-Wert-Paaren darstellt. Damit lassen sich Parameter bequem lesen (get(), getAll(), has()) und bearbeiten (set(), append(), delete(), sort()), ohne den String von Hand zu zerlegen oder zu kodieren.

Schreibgeschützt bedeutet nur, dass man der Eigenschaft selbst kein neues Objekt zuweisen kann (url.searchParams = … wird ignoriert bzw. wirft im Strict Mode einen Fehler). Das zurückgegebene Objekt ist aber live mit der URL verbunden: Jede Änderung über seine Methoden aktualisiert sofort url.search und url.href. Umgekehrt spiegelt das Objekt auch Änderungen wider, die über url.search oder url.href vorgenommen werden.

Typische Einsatzfälle sind das Auslesen von Parametern aus location.href, das sichere Zusammenbauen von API-URLs für fetch() mit korrekter Prozentkodierung sowie das Aktualisieren von Filter- oder Paginierungszuständen in der Adresszeile zusammen mit history.replaceState().

Rückgabewert

Typ

URLSearchParams

Beschreibung

Ein mit der URL verknüpftes URLSearchParams-Objekt. Bei jedem Zugriff wird dasselbe Objekt zurückgegeben (url.searchParams === url.searchParams ist true).

Beispiele

Parameter aus einer URL lesen

const url = new URL('https://shop.example.com/suche?q=laptop&seite=2&tag=neu&tag=angebot');

const params = url.searchParams;
console.log(params.get('q'));            // Suchbegriff
console.log(Number(params.get('seite'))); // als Zahl
console.log(params.getAll('tag'));       // mehrfache Schlüssel
console.log(params.has('sortierung'));
console.log(params.get('sortierung'));   // fehlt -> null

laptop 2 [ 'neu', 'angebot' ] false null

API-URL für fetch sicher zusammenbauen

const ladeArtikel = async (suchbegriff, seite = 1) => {
  const url = new URL('https://api.example.com/artikel');
  url.searchParams.set('q', suchbegriff);   // wird automatisch kodiert
  url.searchParams.set('seite', seite);
  url.searchParams.append('felder', 'titel');
  url.searchParams.append('felder', 'preis');

  console.log(url.href);
  const antwort = await fetch(url);
  return antwort.json();
};

ladeArtikel('Kaffee & Tee', 3);

https://api.example.com/artikel?q=Kaffee+%26+Tee&seite=3&felder=titel&felder=preis

Filterzustand in der Adresszeile aktualisieren

const setzeFilter = (name, wert) => {
  const url = new URL(window.location.href);
  if (wert) {
    url.searchParams.set(name, wert);
  } else {
    url.searchParams.delete(name);
  }
  url.searchParams.delete('seite'); // Paginierung zurücksetzen
  history.replaceState(null, '', url);
};

setzeFilter('farbe', 'blau');
console.log(new URL(location.href).searchParams.get('farbe'));

blau

Live-Verbindung zwischen search und searchParams

const url = new URL('https://example.com/?a=1');
const params = url.searchParams;

params.append('b', '2');
console.log(url.search);

url.search = '?x=9';
console.log(params.get('x'), params.has('a'));

console.log(Object.fromEntries(params));

?a=1&b=2 9 false { x: '9' }

// Wichtig · Fallstricke

Kodierung: URLSearchParams verwendet das Format application/x-www-form-urlencoded. Leerzeichen werden als + serialisiert, nicht als %20. Beim Lesen wird ein wörtliches + in der Query als Leerzeichen gedeutet. Ein Pluszeichen im Wert muss deshalb als %2B übergeben werden, set() erledigt das automatisch.
Normalisierung: Nach jeder Änderung über searchParams wird der gesamte Query-String neu serialisiert. Eine eigene Kodierung (z. B. %20) oder Parameter ohne = können dabei verändert werden. Wenn die ursprüngliche Schreibweise genau erhalten bleiben muss, arbeite direkt mit url.search.
Alles ist ein String: get() gibt immer einen string oder null zurück. Zahlen und boolesche Werte musst du selbst umwandeln. set('x', undefined) speichert den Text "undefined".
Keine Zuweisung: url.searchParams = new URLSearchParams(...) hat keine Wirkung. Verwende stattdessen url.search = neueParams.toString().
Hash: Parameter hinter # gehören zum Fragment (url.hash), nicht zu searchParams.
Sicherheit: Werte aus Query-Parametern kommen vom Nutzer. Gib sie nie ungeprüft über innerHTML aus, sonst droht XSS. Verwende textContent.
Kompatibilität: Wird von allen modernen Browsern und von Node.js (global ab Version 10) unterstützt, aber nicht vom Internet Explorer. Die Methode URLSearchParams.prototype.size gibt es erst in neueren Versionen (etwa 2023).

Siehe auch

URL.search URL.href URLSearchParams.prototype.get() URLSearchParams.prototype.set() History.replaceState() encodeURIComponent()