URL & URLSearchParams in JavaScript erklärt

Schluss mit URL-Parsing per String-Tricks

Bevor es die URL-API gab, haben alle ihre URLs mit split('?'), Regexes und viel Hoffnung zerlegt. Das ging meistens gut – bis ein Wert ein &, ein =, ein Leerzeichen oder ein Nicht-ASCII-Zeichen enthielt. Dann war Schluss. Dabei bringen sowohl der Browser als auch Node einen ordentlichen Parser mit. Nutz ihn.

Ein einziger Aufruf, und schon hast du jeden Bestandteil der URL zerlegt und korrekt dekodiert vorliegen. Bei ungültigem Input wirft der Konstruktor einen TypeError — und das ist in der Regel genau das, was du willst: Eine kaputte URL soll laut scheitern, statt stillschweigend Müll durch den Rest deines Codes zu schleusen.

URL-Parameter auslesen in JavaScript

Jedes URL-Objekt hat eine .searchParams-Property — ein URLSearchParams-Objekt, das sowohl lesend als auch schreibend mit dem Query-String umgehen kann:

Ein paar Dinge, die man dabei im Hinterkopf haben sollte:

• Die Werte kommen schon dekodiert zurück. ?name=Ada%20Lovelace liefert dir "Ada Lovelace".
• Alles ist ein String. "2" ist nicht 2. Wenn du eine Zahl brauchst, konvertiere mit Number().
• Mehrfach vorkommende Keys sind völlig okay. get gibt den ersten Treffer zurück, getAll liefert alle.
• Fehlt ein Key, bekommst du null zurück — nicht undefined. Dadurch lässt sich ?? "default" gut kombinieren.

Query-String in JavaScript bauen

Mit URLSearchParams kannst du einen Query-String komplett von Hand zusammenbauen — ohne manuelles Escapen, ohne & selbst aneinanderzuketten:

Oder du baust sie dir aus einem Objekt — jedes Iterable aus [key, value]-Paaren funktioniert, und ein gewöhnliches Objekt genauso:

set vs. append: set ersetzt einen bereits vorhandenen Wert für den jeweiligen Schlüssel. append fügt einen weiteren hinzu. Nimm append, wenn ein Schlüssel legitimerweise mehrfach vorkommen darf (Tags, Filter); set dagegen für Parameter mit nur einem Wert.

URL verändern

Da URL ein lebendiges Objekt ist, wirken sich Änderungen an searchParams automatisch auf .search und .href aus:

Das ist der idiomatische Weg, um einen Query-Parameter an eine bestehende URL anzuhängen. Kein Prüfen auf „Hat die URL schon ein ??", kein Kopfzerbrechen, ob man & oder ? voranstellen muss.

Andere Teile der URL lassen sich auf dieselbe Weise anpassen:

Alle Parameter durchlaufen

URLSearchParams ist iterierbar. Mit for...of bekommst du [key, value]-Paare, und natürlich stehen dir auch die gewohnten Helfer keys(), values() und entries() zur Verfügung:

Beachte, dass wiederholte Keys auch mehrfach auftauchen — du siehst also nacheinander tag = web und dann tag = beginner als separate Einträge. Das entspricht exakt dem tatsächlichen Query-String.

Wenn du für einen schnellen Debug-Output lieber ein einfaches Objekt hättest, funktioniert Object.fromEntries — allerdings werden dabei doppelte Keys zusammengefasst und nur der letzte Wert bleibt erhalten:

Fürs Debugging okay. Falsch, sobald ein Key mehrfach vorkommen kann.

Relative URLs brauchen eine Basis

new URL("/search?q=js") wirft für sich genommen einen Fehler – ein relativer Pfad ist alleine keine gültige URL. Gib eine Basis als zweites Argument mit:

Die Regeln für die Auflösung sind exakt dieselben, die auch der Browser bei <a href> anwendet: Ein führender / ist absolut ab dem Host, ohne Slash wird relativ zum aktuellen Pfad aufgelöst, und .. springt eine Ebene nach oben. Sehr praktisch, wenn du API-URLs aus einer konfigurierten Basis-URL zusammenbaust.

Im Browser liefert dir window.location.href eine fertige Basis, mit der du die URL der aktuellen Seite parsen kannst:

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

Umgang mit ungültigen URLs

Der URL-Konstruktor wirft bei fehlerhaften Eingaben eine Exception. Praktisch ist das schon – nur brauchst du eben try/catch, sobald du eine URL parst, die ein Nutzer eingetippt oder ein Fremdsystem geliefert hat:

Moderne Umgebungen bieten außerdem URL.canParse(input) – eine simple Boolean-Prüfung, mit der du dir das try/catch-Geturne sparst, wenn du eine URL nur validieren möchtest:

Ein kleines Praxisbeispiel

Jetzt bauen wir alles zusammen: Wir lesen die aktuellen Filter aus einer URL aus, passen sie an und erzeugen daraus eine neue URL, zu der wir navigieren können:

Wenn du null übergibst, wird der Parameter entfernt. Jeder andere Wert setzt ihn oder überschreibt ihn. Dieses Muster wirst du früher oder später in der einen oder anderen Form brauchen — sobald du Filter-UIs, Pagination oder Deep Links baust.

Das Wichtigste auf einen Blick

• new URL(string) zerlegt eine URL in ihre benannten Bestandteile. Bei Murks fliegt eine Exception.
• url.searchParams liefert ein URLSearchParams-Objekt — damit hast du get, getAll, set, append, delete und has zur Hand.
• Das Encoding übernimmt JavaScript für dich. Finger weg von encodeURIComponent, solange du Strings nicht manuell zusammenbaust.
• Für relative Pfade gibst du als zweites Argument eine Basis-URL mit.
• Zum Validieren von fremden Eingaben nimmst du URL.canParse (oder ein try/catch).

Jedes Mal, wenn du in Versuchung kommst, eine URL mit .split('?') zu zerlegen oder einen Query-Parameter per Regex rauszufischen: Greif stattdessen zu diesen APIs. Sie sind kürzer, korrekt und schon in der Runtime eingebaut.