URL.toString() — Methode · JavaScript-Referenz

Signatur

URL.prototype.toString()

Beschreibung

Die Methode toString() eines URL-Objekts liefert die komplette URL als String, also Protokoll, Zugangsdaten, Host, Port, Pfad, Query-String und Fragment. Das Ergebnis entspricht exakt dem Wert der Eigenschaft href. Anders als href ist toString() aber nur lesend: Zum Ändern der gesamten URL muss man href setzen.

Man ruft toString() selten direkt auf, weil JavaScript die Methode automatisch nutzt, sobald ein URL-Objekt in einen String umgewandelt wird. Das passiert zum Beispiel bei Template-Literalen, bei der Verkettung mit + oder bei String(url). Deshalb kann man ein URL-Objekt direkt an fetch(), window.open() oder location.assign() übergeben.

Der zurückgegebene String ist immer normalisiert: Das Schema und der Host werden kleingeschrieben, Standardports (etwa :443 bei HTTPS) entfallen, Pfadsegmente wie .. werden aufgelöst und Sonderzeichen werden prozentkodiert. Änderungen an searchParams oder anderen Eigenschaften erscheinen sofort im Ergebnis.

Rückgabewert

Typ

string

Beschreibung

Die vollständige, serialisierte URL – derselbe Wert wie url.href.

Beispiele

Einfache Serialisierung und Normalisierung

const url = new URL('HTTPS://Example.COM:443/a/b/../c?x=1#top');
console.log(url.toString());
console.log(url.toString() === url.href);

https://example.com/a/c?x=1#top true

Query-Parameter dynamisch aufbauen und für fetch nutzen

const api = new URL('https://api.example.com/v1/search');
api.searchParams.set('q', 'Kaffee & Kuchen');
api.searchParams.set('page', '2');

console.log(api.toString());

// fetch akzeptiert das URL-Objekt direkt (implizites toString)
const response = await fetch(api);
console.log(response.ok);

https://api.example.com/v1/search?q=Kaffee+%26+Kuchen&page=2

Implizite Umwandlung in Template-Literalen

const base = new URL('/produkte/42', 'https://shop.example.de');
const link = `<a href="${base}">Produkt ansehen</a>`;
console.log(link);
console.log(String(base));

<a href="https://shop.example.de/produkte/42">Produkt ansehen</a> https://shop.example.de/produkte/42

URLs als Schlüssel vergleichen

const a = new URL('https://example.com/pfad?x=1');
const b = new URL('https://EXAMPLE.com:443/pfad?x=1');

console.log(a === b);                       // Objektvergleich
console.log(a.toString() === b.toString()); // Stringvergleich

const cache = new Map();
cache.set(a.toString(), 'Daten');
console.log(cache.get(b.toString()));

false true Daten

// Wichtig · Fallstricke

Nur lesend: toString() gibt denselben Wert wie href zurück, kann die URL aber nicht verändern. Zum Setzen der URL url.href = '...' verwenden.
Objektvergleich: Zwei URL-Objekte sind mit === nie gleich, auch wenn sie auf dieselbe Adresse zeigen. Zum Vergleichen und als Map-Schlüssel die serialisierten Strings nutzen.
Kodierung: searchParams kodiert Leerzeichen als + (Format application/x-www-form-urlencoded). Manche Server erwarten stattdessen %20.
Zugangsdaten: Stehen username und password in der URL, gibt toString() sie im Klartext mit aus. Solche URLs nicht ungeprüft loggen oder in HTML einfügen.
Sicherheit: Ein gültiges URL-Objekt kann auch javascript:- oder data:-URLs enthalten. Vor dem Einsetzen in href-Attribute url.protocol prüfen, damit keine XSS-Lücke entsteht.
JSON.stringify(url) nutzt toJSON(), das dasselbe Ergebnis liefert.
Kompatibilität: wird von allen modernen Browsern und Node.js (global ab Version 10) unterstützt, nicht aber vom Internet Explorer.

Siehe auch

URL URL.href URL.toJSON() URL.searchParams URLSearchParams.toString() URL.canParse() Request.textStream()