Document.location — Eigenschaft · JavaScript-Referenz

Signatur

get Document.location

Beschreibung

document.location liefert ein Location-Objekt. Es zerlegt die aktuelle URL des Dokuments in ihre Bestandteile, etwa protocol, host, pathname, search und hash. Außerdem stellt es die Methoden assign(), replace() und reload() bereit, mit denen man weiterleiten oder die Seite neu laden kann.

Die Eigenschaft ist im engeren Sinn schreibgeschützt, denn das Location-Objekt selbst lässt sich nicht austauschen. Weist man ihr aber einen String zu, zum Beispiel document.location = "/login", navigiert der Browser zu dieser URL. Das entspricht dem Aufruf document.location.assign("/login").

In einem Dokument, das in einem Browsing-Kontext angezeigt wird, verweist document.location auf dasselbe Objekt wie window.location. Hat das Dokument keinen Browsing-Kontext, gibt die Eigenschaft null zurück. Das ist etwa bei Dokumenten der Fall, die per DOMParser oder document.implementation.createHTMLDocument() erzeugt wurden. Wer nur die URL als String braucht, kann auch document.URL verwenden. Diese Eigenschaft ist wirklich schreibgeschützt und löst keine Navigation aus.

Rückgabewert

Typ

Location | null

Beschreibung

Das Location-Objekt der aktuellen URL des Dokuments. null, wenn das Dokument keinen Browsing-Kontext hat.

Beispiele

URL-Bestandteile auslesen

// Angenommen, die Seite läuft unter https://example.com:8080/shop/artikel?id=42#bewertungen
const { protocol, hostname, port, pathname, search, hash } = document.location;

console.log(protocol, hostname, port);
console.log(pathname, search, hash);
console.log(document.location === window.location);

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

Query-Parameter mit URLSearchParams auswerten

// URL: https://example.com/suche?q=javascript&seite=2
const params = new URLSearchParams(document.location.search);
const suchbegriff = params.get('q') ?? '';
const seite = Number(params.get('seite') ?? 1);

console.log(`Suche nach "${suchbegriff}", Seite ${seite}`);

Suche nach "javascript", Seite 2

Weiterleitung nach Login-Prüfung

const pruefeSitzung = async () => {
  const res = await fetch('/api/session', { credentials: 'include' });
  if (res.status === 401) {
    // Rücksprungziel mitgeben; replace() erzeugt keinen History-Eintrag
    const ziel = encodeURIComponent(document.location.pathname + document.location.search);
    document.location.replace(`/login?redirect=${ziel}`);
  }
};

pruefeSitzung();

Zuweisung navigiert, Hash-Änderung nicht

// Ändert nur den Anker: kein Neuladen, es feuert aber ein hashchange-Event
document.location.hash = 'kontakt';

// Zuweisung eines Strings löst eine Navigation aus (wie assign())
const zurStartseite = () => {
  document.location = '/';
};

// Dokumente ohne Browsing-Kontext haben kein Location-Objekt
const doc = new DOMParser().parseFromString('<p>Hallo</p>', 'text/html');
console.log(doc.location);

null

// Wichtig · Fallstricke

Sicherheit (Open Redirect/XSS): Weise document.location oder location.href niemals ungeprüfte Nutzereingaben zu, etwa einen ?redirect=-Parameter. Eine URL wie javascript:alert(1) führt Code aus. Fremde Ziele missbrauchen Angreifer für Phishing. Prüfe das Ziel deshalb mit new URL(ziel, location.origin) und vergleiche danach origin bzw. das Protokoll.
Auch das Auslesen von location.hash oder location.search und das Einfügen per innerHTML ist eine klassische DOM-XSS-Quelle. Verwende stattdessen textContent.
assign() und die direkte Zuweisung legen einen neuen Eintrag im Verlauf an. replace() tut das nicht, dann funktioniert der Zurück-Button nicht zur alten Seite.
Wird nur hash geändert, lädt die Seite nicht neu. Änderungen an pathname, search oder host lösen dagegen eine Navigation aus. Für URL-Änderungen ohne Neuladen gibt es history.pushState().
Zugriff über Fenstergrenzen hinweg, etwa iframe.contentDocument.location, ist durch die Same-Origin-Policy beschränkt. Von fremden Ursprüngen aus ist nur das Setzen der URL erlaubt.
Für neuen Code ist window.location gebräuchlicher und klarer. In allen Browsern verhalten sich beide gleich.

Siehe auch

Window.location Location Document.URL Location.assign() Location.replace() History.pushState()