Location — Schnittstelle · JavaScript-Referenz

Signatur

interface Location

Beschreibung

Ein Location-Objekt beschreibt die aktuelle Adresse (URL) eines Browsing-Kontexts. Es ist über window.location und document.location erreichbar – beide verweisen auf dasselbe Objekt. Die Eigenschaften zerlegen die URL in ihre Bestandteile: href (gesamte URL), protocol, host, hostname, port, pathname, search (Query-String inkl. ?), hash (Fragment inkl. #) sowie die schreibgeschützte origin. Zusätzlich liefert ancestorOrigins (nicht in Firefox) die Origins übergeordneter Frames.

Anders als ein reines URL-Objekt ist Location aktiv: Das Setzen fast jeder Eigenschaft löst eine Navigation aus. Wer location.pathname oder location.search ändert, lädt eine neue Seite; das Ändern von location.hash springt dagegen nur zum Anker und löst ein hashchange-Event aus, ohne die Seite neu zu laden.

Die Methoden steuern die Navigation gezielt:

assign(url) – navigiert zur URL und legt einen neuen Eintrag im Verlauf an (entspricht location.href = url).
replace(url) – navigiert, ersetzt aber den aktuellen Verlaufseintrag; der Zurück-Button führt nicht zur alten Seite zurück.
reload() – lädt das aktuelle Dokument neu.
toString() – liefert href als String.

Zum reinen Lesen und Analysieren von Parametern kombiniert man location am besten mit URL bzw. URLSearchParams. Für URL-Änderungen ohne Neuladen (z. B. in Single-Page-Apps) ist die History-API (history.pushState()) das passende Werkzeug.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL		Nur bei `assign()` und `replace()`: Ziel-URL, absolut oder relativ zur aktuellen Dokument-URL.
$forceGet	boolean	false	Nicht standardisierter Parameter von `reload()`, nur in Firefox wirksam (umgeht den Cache). Andere Browser ignorieren ihn – nicht verwenden.

Rückgabewert

Typ

Location

Beschreibung

window.location bzw. document.location liefern das Location-Objekt des Dokuments. Die Methoden assign(), replace() und reload() geben undefined zurück.

Beispiele

URL-Bestandteile auslesen

// Angenommen: https://shop.example.com:8080/produkte/liste?kategorie=buecher&seite=2#top
const { href, protocol, host, hostname, port, pathname, search, hash, origin } = window.location;

console.log(protocol); // Protokoll inkl. Doppelpunkt
console.log(host);     // Host inkl. Port
console.log(pathname);
console.log(search);
console.log(hash);
console.log(origin);

https: shop.example.com:8080 /produkte/liste ?kategorie=buecher&seite=2 #top https://shop.example.com:8080

Query-Parameter mit URLSearchParams auswerten

// Aktuelle URL: https://example.com/suche?q=javascript&seite=3
const params = new URLSearchParams(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 3

Weiterleiten: assign() vs. replace()

const nachLoginWeiterleiten = (eingeloggt) => {
  if (!eingeloggt) {
    // Login-Seite soll im Verlauf bleiben -> assign
    const ziel = new URL('/login', location.origin);
    ziel.searchParams.set('zurueck', location.pathname);
    location.assign(ziel);
  } else {
    // Zwischenseite ersetzen, damit "Zurück" nicht erneut hierher führt
    location.replace('/dashboard');
  }
};

nachLoginWeiterleiten(false);

Hash-Navigation ohne Neuladen

const zeigeAbschnitt = () => {
  const id = location.hash.slice(1) || 'start';
  console.log(`Aktiver Abschnitt: ${id}`);
};

window.addEventListener('hashchange', zeigeAbschnitt);
zeigeAbschnitt();

// Später, z. B. bei Klick auf einen Tab:
location.hash = 'einstellungen'; // kein Reload, löst hashchange aus

Aktiver Abschnitt: start Aktiver Abschnitt: einstellungen

// Wichtig · Fallstricke

Sicherheit / Open Redirect & XSS: Niemals ungeprüfte Nutzereingaben (z. B. einen ?redirect=-Parameter) an location.href, assign() oder replace() übergeben. URLs mit javascript:-Schema führen dabei Code aus (DOM-basiertes XSS). Ziel mit new URL(wert, location.origin) parsen und protocol sowie origin gegen eine Positivliste prüfen.
Werte aus location.search oder location.hash nie per innerHTML ins DOM schreiben – stattdessen textContent verwenden.
Das Setzen von pathname, search usw. löst jeweils eine Navigation aus. Mehrere Änderungen daher zuerst in einem URL-Objekt vornehmen und dann einmal location.href setzen.
Bei Frames anderer Origin ist nur das Schreiben von href bzw. der Aufruf von replace()/assign() erlaubt; Lesezugriffe werfen einen SecurityError.
search und hash liefern leere Strings, wenn kein Wert vorhanden ist – nicht "?" bzw. "#". Die Werte sind prozentkodiert; ggf. decodeURIComponent() oder URLSearchParams nutzen.
location.reload(true) (erzwungenes Neuladen ohne Cache) ist nicht standardisiert und wird außerhalb von Firefox ignoriert.
location.ancestorOrigins wird von Firefox nicht unterstützt. Alle übrigen Bestandteile sind in allen Browsern verfügbar.
In Web Workern gibt es stattdessen die schreibgeschützte WorkerLocation (self.location) ohne Navigationsmethoden.

Siehe auch

Window.location Document.location URL URLSearchParams History History.pushState() WorkerLocation