Document.documentURI — Eigenschaft · JavaScript-Referenz

Signatur

Document.documentURI

Beschreibung

Mit document.documentURI fragt man die Adresse ab, unter der das aktuelle Dokument geladen wurde. Der Wert ist eine Zeichenkette mit der vollständigen, serialisierten URL einschließlich Pfad, Suchparametern (?…) und Fragment (#…).

Die Eigenschaft ist auf dem Document-Interface definiert und funktioniert daher für alle Dokumenttypen, also auch für XML-Dokumente, die per DOMParser oder document.implementation.createDocument() erzeugt wurden. Genau darin liegt der Unterschied zu document.URL: Historisch gab es URL nur auf HTMLDocument, documentURI dagegen auf jedem Document. In heutigen Browsern liefern beide Eigenschaften denselben Wert.

Typische Anwendungsfälle sind Logging und Fehlerberichte (von welcher Seite kommt ein Fehler?), das Auflösen relativer Pfade in generischem DOM-Code und die Prüfung, woher ein Dokument stammt, etwa bei Dokumenten aus einem iframe mit gleichem Ursprung.

Die Eigenschaft ist schreibgeschützt. Um zu einer anderen Adresse zu navigieren, verwendet man location.href oder location.assign(). Um die URL ohne Neuladen zu ändern, nutzt man history.pushState(). Danach gibt documentURI den neuen Wert zurück.

Rückgabewert

Typ

string

Beschreibung

Die vollständige URL des Dokuments als Zeichenkette. Bei Dokumenten, die per Skript erzeugt wurden, ist das meist "about:blank" oder die URL des erzeugenden Dokuments.

Beispiele

Aktuelle Dokument-URL auslesen

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

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

URL zerlegen, z. B. für Fehlerberichte

const url = new URL(document.documentURI);

const report = {
  seite: url.pathname,
  artikelId: url.searchParams.get('id'),
  anker: url.hash,
  zeitpunkt: new Date().toISOString()
};

window.addEventListener('error', (event) => {
  navigator.sendBeacon('/api/errors', JSON.stringify({
    ...report,
    meldung: event.message
  }));
});

console.log(report.seite, report.artikelId, report.anker);

/blog/artikel 42 #kommentare

documentURI bei per Skript erzeugten Dokumenten

// Das XML-Dokument wird von DOMParser erzeugt.
const xmlDoc = new DOMParser().parseFromString(
  '<config><debug>true</debug></config>',
  'application/xml'
);
console.log(xmlDoc.documentURI); // erbt die URL des erzeugenden Dokuments

// Das leere HTML-Dokument wird über die Implementation erzeugt.
const emptyDoc = document.implementation.createHTMLDocument('Test');
console.log(emptyDoc.documentURI);

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

URL eines iframe-Dokuments mit gleichem Ursprung prüfen

const frame = document.querySelector('iframe#vorschau');

frame.addEventListener('load', () => {
  try {
    const uri = frame.contentDocument.documentURI;
    console.log('iframe zeigt:', uri);
  } catch (err) {
    // Bei fremdem Ursprung ist contentDocument null
    console.warn('Kein Zugriff auf das iframe-Dokument (Cross-Origin).');
  }
});

iframe zeigt: https://example.com/vorschau.html

// Wichtig · Fallstricke

Schreibgeschützt: Wenn man document.documentURI einen Wert zuweist, wird das stillschweigend ignoriert, im Strict Mode kommt es zu einem TypeError. Zum Navigieren verwendet man location.href, zum Ändern der Adresse ohne Neuladen history.pushState().
Unterschied zu document.URL: Beide liefern heute denselben Wert. documentURI steht aber garantiert auf jedem Document zur Verfügung, auch bei XML-Dokumenten.
Nicht gleich baseURI: Ein <base href>-Element verändert document.baseURI, documentURI bleibt davon unberührt. Für das Auflösen relativer Links ist daher meist baseURI die richtige Wahl.
Sensible Daten: Die URL kann Tokens, Sitzungs-IDs oder personenbezogene Daten in Suchparametern oder im Fragment enthalten. Vor dem Loggen oder Übertragen an Drittanbieter sollte man sie bereinigen. Den Wert außerdem nie ungeprüft per innerHTML ausgeben, sonst droht XSS.
Kompatibilität: Wird von allen modernen Browsern unterstützt. In sehr alten Internet-Explorer-Versionen fehlte die Eigenschaft auf HTML-Dokumenten, dort stand nur document.URL zur Verfügung.

Siehe auch

Document.URL Node.baseURI Window.location Document.referrer History.pushState() DOMParser