Document.URL — Eigenschaft · JavaScript-Referenz

Signatur

get Document.URL

Beschreibung

document.URL gibt die Adresse des aktuellen Dokuments als Zeichenkette zurück, inklusive Protokoll, Host, Pfad, Query-String und Fragment (#hash). Die Eigenschaft ist schreibgeschützt. Zuweisungen werden stillschweigend ignoriert und lösen keine Navigation aus.

Im Unterschied zu window.location, das ein Location-Objekt mit einzelnen Bestandteilen und Navigationsmethoden liefert, ist document.URL ein einfacher String. Sie eignet sich gut für Logging, Analyse, Fehlerberichte oder als Eingabe für den URL-Konstruktor, wenn man die Adresse nur lesen und zerlegen will.

Inhaltlich entspricht document.URL der Eigenschaft document.documentURI. Der Unterschied: URL gibt es nur bei HTML-Dokumenten, documentURI bei allen Dokumenttypen (z. B. auch XML). Bei Dokumenten, die per about:blank, srcdoc oder document.open() entstehen, kann der Wert von der sichtbaren Adresse im Browser abweichen.

Rückgabewert

Typ

string

Beschreibung

Die vollständige, serialisierte URL des Dokuments, z. B. "https://example.com/pfad?x=1#abschnitt".

Beispiele

Aktuelle Adresse ausgeben

// Angenommen, die Seite ist https://example.com/blog/artikel?id=42#kommentare
console.log(document.URL);

https://example.com/blog/artikel?id=42#kommentare

URL zerlegen und Query-Parameter lesen

const url = new URL(document.URL);
const id = url.searchParams.get('id');

console.log(url.pathname); // Pfad
console.log(id);           // Parameter "id"
console.log(url.hash);     // Fragment

/blog/artikel 42 #kommentare

Seitenadresse in Fehlerberichten mitsenden

window.addEventListener('error', (event) => {
  const report = {
    message: event.message,
    page: document.URL,
    referrer: document.referrer,
    time: new Date().toISOString()
  };
  // sendBeacon funktioniert auch beim Verlassen der Seite
  navigator.sendBeacon('/api/errors', JSON.stringify(report));
});

Schreibversuch hat keine Wirkung

const vorher = document.URL;
document.URL = 'https://example.org/'; // wird ignoriert (im Strict Mode: TypeError)
console.log(document.URL === vorher);

// Zum Navigieren stattdessen:
// location.href = 'https://example.org/';

true

// Wichtig · Fallstricke

Schreibgeschützt: Außerhalb des Strict Mode werden Zuweisungen stillschweigend ignoriert, in Strict-Mode-Code und in ES-Modulen lösen sie einen TypeError aus. Zum Navigieren nimmt man location.href, location.assign() oder die History-API.
Nach history.pushState()/replaceState() zeigt document.URL die neue Adresse an, obwohl kein neues Dokument geladen wurde.
Sicherheit: Die URL enthält Nutzereingaben wie Query-String und Hash. Werte daraus nie ungeprüft in innerHTML, eval() oder document.write() einfügen, sonst droht DOM-basiertes XSS. Bei Logging und Analyse darauf achten, dass Tokens oder personenbezogene Daten in der URL landen können.
In iframes mit srcdoc liefert die Eigenschaft about:srcdoc, in leeren Frames about:blank.
Die Eigenschaft wird von allen Browsern seit langem unterstützt. Für Nicht-HTML-Dokumente ist document.documentURI die allgemeinere Alternative.

Siehe auch

Document.documentURI Window.location Location.href Document.referrer History.pushState() CSSSkewY.ay