URL.search — Eigenschaft · JavaScript-Referenz

Signatur

URL.prototype.search

Beschreibung

Die Eigenschaft search eines URL-Objekts enthält den Abfrageteil der URL, also alles zwischen dem ? und einem eventuellen Fragment (#…). Der Wert beginnt mit einem ?, sofern eine nicht leere Abfrage existiert, sonst ist er die leere Zeichenkette "".

Die Eigenschaft ist les- und schreibbar. Wenn Sie einen neuen Wert zuweisen, wird ein fehlendes führendes ? automatisch ergänzt, und Zeichen, die in einer Abfrage nicht erlaubt sind (z. B. Leerzeichen), werden prozentkodiert. Die Änderung wirkt sich sofort auf href und auf das verknüpfte searchParams-Objekt aus.

Für das gezielte Lesen oder Ändern einzelner Parameter ist URL.searchParams (ein URLSearchParams-Objekt) in der Regel die bessere Wahl. search eignet sich vor allem, um die komplette Abfrage auf einmal zu übernehmen, zu kopieren, zu entfernen oder zu vergleichen.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: die neue Abfragezeichenfolge, mit oder ohne führendes `?`. Eine leere Zeichenkette entfernt die Abfrage vollständig.

Rückgabewert

Typ

string

Beschreibung

Die Abfragezeichenfolge inklusive führendem ? (prozentkodiert) oder "", wenn keine Abfrage vorhanden ist.

Beispiele

Abfragezeichenfolge auslesen

const url = new URL('https://example.com/suche?q=javascript&seite=2#ergebnisse');
console.log(url.search);

const ohneQuery = new URL('https://example.com/start');
console.log(JSON.stringify(ohneQuery.search));

?q=javascript&seite=2 ""

Abfrage setzen und entfernen

const url = new URL('https://example.com/produkte');

// Führendes ? wird automatisch ergänzt, Leerzeichen kodiert
url.search = 'kategorie=bücher regal&sort=preis';
console.log(url.href);

// Abfrage komplett entfernen (z. B. Tracking-Parameter)
url.search = '';
console.log(url.href);

https://example.com/produkte?kategorie=b%C3%BCcher%20regal&sort=preis https://example.com/produkte

Zusammenspiel mit searchParams

const url = new URL('https://api.example.com/items?limit=10');

// Einzelne Parameter bequem über searchParams ändern
url.searchParams.set('offset', '20');
console.log(url.search);

// search überschreiben aktualisiert searchParams ebenfalls
url.search = '?limit=50';
console.log(url.searchParams.get('offset'), url.searchParams.get('limit'));

?limit=10&offset=20 null 50

Query-String der aktuellen Seite ohne Neuladen ändern

const url = new URL(window.location.href);
url.searchParams.set('filter', 'neu');

// Adresszeile aktualisieren, ohne die Seite neu zu laden
history.replaceState(null, '', url);
console.log(location.search);

?filter=neu

// Wichtig · Fallstricke

Eine URL, die nur mit ? endet (z. B. https://example.com/?), liefert für search ebenfalls "" – obwohl href das ? enthält. Prüfen Sie also nicht über search, ob ein Fragezeichen existiert.
Der Wert ist prozentkodiert. Zum Auslesen dekodierter Werte searchParams.get() verwenden, statt den String selbst zu zerlegen.
Beim Setzen über search werden Leerzeichen als %20 kodiert, URLSearchParams serialisiert sie dagegen als +. Beides ist gültig, kann aber String-Vergleiche verfälschen.
Im Gegensatz zu location.search = … löst das Setzen von URL.search keine Navigation aus – das URL-Objekt ist nur ein Datenobjekt.
Nutzerdaten aus der Abfrage niemals ungeprüft per innerHTML ausgeben (XSS-Gefahr).
Kompatibilität: in allen modernen Browsern und Node.js unterstützt; der Internet Explorer kennt das URL-Interface nicht.

Siehe auch

URL.searchParams URLSearchParams URL.hash URL.href Location.search URL SyncEvent.tag