Location.toString() — Methode · JavaScript-Referenz

Signatur

Location.prototype.toString()

Beschreibung

Die Methode toString() des Location-Interfaces ist ein sogenannter Stringifizierer. Sie liefert die gesamte URL des Dokuments als String, also Protokoll, Host, Port, Pfad, Query-String und Fragment. Der Rückgabewert entspricht genau dem Lesewert von location.href.

Normalerweise ruft man toString() nicht selbst auf. Die Methode wird automatisch verwendet, wenn ein Location-Objekt in einen String umgewandelt wird: in Template-Literalen, bei Verkettung mit +, bei String(location) oder bei Übergabe an APIs, die einen String erwarten, zum Beispiel new URL(location).

Ein expliziter Aufruf lohnt sich, wenn man deutlich machen will, dass ein primitiver String gebraucht wird und keine Referenz auf das veränderliche Location-Objekt. Das ist etwa beim Speichern, Loggen oder Vergleichen von URLs der Fall. Anders als href ist toString() nur lesend. Mit der Methode kann man also nicht navigieren.

Rückgabewert

Typ

string

Beschreibung

Die vollständige, serialisierte URL des Dokuments. Sie ist identisch mit location.href.

Beispiele

Aktuelle URL auslesen

// Angenommen, die Seite ist https://example.com:8080/shop/artikel?id=42#details
const url = location.toString();
console.log(url);
console.log(url === location.href);

https://example.com:8080/shop/artikel?id=42#details true

Implizite Umwandlung in Template-Literal und Verkettung

// toString() wird automatisch aufgerufen
console.log(`Aktuelle Seite: ${location}`);
console.log('Seite: ' + location);
console.log(typeof location, typeof String(location));

Aktuelle Seite: https://example.com/blog/beitrag Seite: https://example.com/blog/beitrag object string

URL für Fehlerbericht an den Server senden

const meldeFehler = async (fehler) => {
  await fetch('/api/fehler', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      nachricht: fehler.message,
      // Primitiver String statt Location-Objekt
      seite: location.toString(),
      zeitpunkt: new Date().toISOString()
    })
  });
};

window.addEventListener('error', (e) => meldeFehler(e.error ?? new Error(e.message)));

Query-Parameter mit URL-Objekt auswerten

// new URL() ruft intern toString() auf
const aktuelleUrl = new URL(location.toString());
const seite = aktuelleUrl.searchParams.get('seite') ?? '1';
console.log(`Seite ${seite} von ${aktuelleUrl.pathname}`);

Seite 3 von /suche

// Wichtig · Fallstricke

Nur lesend: toString() verändert die URL nicht. Für eine Navigation verwendet man location.href = …, location.assign() oder location.replace().
Fragment enthalten: Der Rückgabewert enthält auch den Hash (#…). Wenn der Hash stört, etwa beim Vergleichen von URLs, baut man die URL mit location.origin + location.pathname + location.search zusammen.
Serialisierung ist Momentaufnahme: Ein gespeicherter String wird nicht aktualisiert. Nach history.pushState() oder einer Hash-Änderung muss toString() erneut aufgerufen werden.
JSON: JSON.stringify(location) liefert keinen URL-String. Stattdessen entsteht ein Objekt mit den Eigenschaften. Deshalb vorher explizit location.toString() verwenden.
Sicherheit: Die URL kann sensible Daten enthalten, etwa Tokens im Query-String oder Fragment, und ist vom Nutzer steuerbar. Sie darf nie ungeprüft über innerHTML ausgegeben werden (XSS-Gefahr). Vor dem Loggen oder Weitergeben sollte man sensible Parameter entfernen.
Kompatibilität: Die Methode wird von allen Browsern unterstützt, auch von sehr alten. In Web Workern gibt es das Gegenstück WorkerLocation.toString().

Siehe auch

Location Location.href Location.assign() Location.replace() URL.prototype.toString() RTCSessionDescription.toJSON()