URLSearchParams.append() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.append(name, value)

Beschreibung

Die Methode append() hängt ein neues Schlüssel/Wert-Paar an ein URLSearchParams-Objekt an. Anders als set() ersetzt sie keine vorhandenen Einträge. Wenn der Schlüssel schon existiert, wird ein weiterer Eintrag mit demselben Namen angelegt. So entstehen Mehrfachparameter wie ?tag=js&tag=css.

Typische Einsätze sind das Zusammenbauen von Query-Strings für fetch()-Anfragen, Filter mit Mehrfachauswahl (Checkboxen, Tags) und das Erweitern der Suchparameter einer vorhandenen URL über url.searchParams. Die Werte werden beim Serialisieren mit toString() automatisch im Format application/x-www-form-urlencoded kodiert. Leerzeichen werden dabei zu +, Sonderzeichen wie & oder = werden prozentkodiert.

Beide Argumente werden in Strings umgewandelt. Zahlen, Booleans, null und undefined landen deshalb als "42", "true", "null" bzw. "undefined" in der URL. Die Reihenfolge der Einträge bleibt erhalten. Neue Paare stehen immer am Ende.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name (Schlüssel) des neuen Parameters. Wird in einen String umgewandelt.
$value Pflicht	string		Wert des Parameters. Wird in einen String umgewandelt, z. B. `42` → `"42"`.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das Objekt wird direkt verändert. Verkettungen wie params.append(...).append(...) sind deshalb nicht möglich.

Beispiele

Einfaches Anhängen und Mehrfachwerte

const params = new URLSearchParams('q=javascript');
params.append('tag', 'web');
params.append('tag', 'api');

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

q=javascript&tag=web&tag=api [ 'web', 'api' ]

append() im Vergleich zu set()

const params = new URLSearchParams('page=1');
params.append('page', '2');
console.log(params.toString()); // Duplikat

params.set('page', '3');
console.log(params.toString()); // ersetzt alle

page=1&page=2 page=3

Query-String für fetch() aus einem Filterobjekt bauen

const filter = { search: 'Laptop & Zubehör', brands: ['Lenovo', 'Dell'], maxPrice: 1200 };

const params = new URLSearchParams();
params.append('search', filter.search);
for (const brand of filter.brands) {
  params.append('brand', brand);
}
params.append('maxPrice', filter.maxPrice); // Zahl wird zu String

const url = `https://api.example.com/products?${params}`;
console.log(url);

// const res = await fetch(url);

https://api.example.com/products?search=Laptop+%26+Zub%C3%A4h%C3%B6r&brand=Lenovo&brand=Dell&maxPrice=1200

Parameter an eine vorhandene URL anhängen

const url = new URL('https://example.com/suche?q=test');
url.searchParams.append('lang', 'de');
url.searchParams.append('utm_source', 'newsletter');

console.log(url.href);

https://example.com/suche?q=test&lang=de&utm_source=newsletter

// Wichtig · Fallstricke

Duplikate: append() legt bei jedem Aufruf einen neuen Eintrag an. Wenn ein Parameter nur einmal vorkommen soll, verwende set(). Sonst entstehen z. B. bei wiederholten Aufrufen in Event-Handlern Werte wie page=1&page=2&page=3.
Typumwandlung: undefined und null werden zu den Strings "undefined" bzw. "null". Prüfe optionale Werte vor dem Anhängen.
Kodierung: Leerzeichen werden als + kodiert, nicht als %20. Manche Server erwarten %20. Kodiere niemals vorher selbst mit encodeURIComponent(), sonst wird der Wert doppelt kodiert (z. B. %2520).
Keine Verkettung: Die Methode gibt undefined zurück.
Serverseitige Auswertung: Mehrfachschlüssel wie tag=a&tag=b werden je nach Backend unterschiedlich gelesen. PHP etwa erwartet tag[], sonst gewinnt nur der letzte Wert.
Kompatibilität: Wird von allen modernen Browsern unterstützt, aber nicht vom Internet Explorer. In Node.js ist URLSearchParams seit Version 10 global verfügbar.

Siehe auch

URLSearchParams URLSearchParams.set() URLSearchParams.delete() URLSearchParams.get() URLSearchParams.keys()