URLSearchParams.set() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.set(name, value)

Beschreibung

Mit set() legen Sie den Wert eines Query-Parameters fest. Gibt es den Parameter name bereits, bekommt das erste Vorkommen den neuen Wert, und alle weiteren Einträge mit diesem Namen werden gelöscht. Gibt es ihn noch nicht, wird ein neues Paar ans Ende gehängt.

Damit unterscheidet sich set() deutlich von append(). append() fügt immer einen weiteren Eintrag hinzu, sodass ein Name mehrfach vorkommen kann (z. B. ?tag=a&tag=b). set() sorgt dagegen dafür, dass ein Name genau einmal vorkommt. Das passt zu typischen Parametern wie Seite, Sortierung oder Suchbegriff.

In der Praxis nutzen Sie set() meist über url.searchParams eines URL-Objekts. Änderungen landen dort sofort in url.search und url.href. Die Kodierung übernimmt die Methode selbst: Sonderzeichen werden nach application/x-www-form-urlencoded kodiert, Leerzeichen werden also zu +.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Parameters, der gesetzt werden soll. Andere Typen werden in einen String umgewandelt.
$value Pflicht	string		Neuer Wert. Andere Typen werden mit `String()` umgewandelt, z. B. `2` zu `"2"` und `null` zu `"null"`.

Beispiele

Grundlagen: set() gegenüber append()

const params = new URLSearchParams('tag=js&tag=css&page=1');

params.set('tag', 'html'); // entfernt die weiteren tag-Einträge
params.set('sort', 'neu'); // neuer Name wird ans Ende gehängt

console.log(params.toString());
console.log(params.getAll('tag'));

tag=html&page=1&sort=neu [ 'html' ]

Seitenzahl in der aktuellen URL ändern (Paginierung)

const goToPage = (page) => {
  const url = new URL(window.location.href);
  url.searchParams.set('page', page); // Zahl wird zu "2"
  history.pushState({ page }, '', url);
  console.log(url.search);
};

// Angenommen: https://example.com/produkte?kategorie=buecher&page=1
goToPage(2);

?kategorie=buecher&page=2

Filter für eine API-Anfrage zusammensetzen

const fetchProducts = async (filters) => {
  const url = new URL('https://api.example.com/products');
  for (const [key, value] of Object.entries(filters)) {
    if (value !== undefined && value !== '') {
      url.searchParams.set(key, value);
    }
  }
  console.log(url.href);
  const response = await fetch(url);
  return response.json();
};

fetchProducts({ q: 'rote Schuhe & Socken', limit: 20, color: '' });

https://api.example.com/products?q=rote+Schuhe+%26+Socken&limit=20

// Wichtig · Fallstricke

Doppelte Einträge gehen verloren: set() löscht alle weiteren Vorkommen des Namens. Wenn Sie mehrere Werte brauchen (z. B. ?tag=a&tag=b), nehmen Sie append(). Um die Liste komplett neu aufzubauen, rufen Sie erst delete(name) auf und dann mehrmals append().
Werte werden zu Strings: set('x', null) ergibt x=null, set('x', undefined) ergibt x=undefined. Leere oder fehlende Werte sollten Sie deshalb vorher selbst herausfiltern.
Nicht doppelt kodieren: Übergeben Sie Rohwerte, nicht das Ergebnis von encodeURIComponent(). Sonst wird aus %20 ein %2520.
Leerzeichen: In toString() erscheinen Leerzeichen als +, nicht als %20. Server, die nur %20 erwarten, können daran scheitern.
Die Adresszeile ändert sich nicht: Ein Aufruf auf new URL(location.href).searchParams ändert nur das Objekt, nicht die angezeigte URL. Dafür brauchen Sie zusätzlich history.pushState() oder history.replaceState().
Reihenfolge: Ein vorhandener Parameter behält seine Position, ein neuer landet am Ende. Mit sort() bringen Sie die Parameter in eine feste Reihenfolge, z. B. für Cache-Schlüssel.
Kompatibilität: Wird von allen modernen Browsern und von Node.js unterstützt (dort global verfügbar). Der Internet Explorer kennt die Methode nicht.

Siehe auch

URLSearchParams URLSearchParams.append() URLSearchParams.get() URLSearchParams.delete() URLSearchParams.has() URL.searchParams new SpeechSynthesisEvent()