new HashChangeEvent() — Methode · JavaScript-Referenz

Signatur

new HashChangeEvent(type, options)

Beschreibung

Der Konstruktor HashChangeEvent() erzeugt ein synthetisches Ereignisobjekt vom Typ HashChangeEvent. Normalerweise erzeugt der Browser solche Objekte selbst, sobald sich der Fragment-Teil der URL (alles ab #) ändert, und löst damit das Ereignis hashchange auf window aus.

Selbst gebaut braucht man das Objekt vor allem in Tests (z. B. für die Hash-basierte Navigation einer Single-Page-App) oder wenn man die Router-Logik gezielt ohne echte URL-Änderung anstoßen will. Über das options-Objekt lassen sich die schreibgeschützten Eigenschaften oldURL und newURL festlegen. Dazu kommen die üblichen Optionen aus EventInit wie bubbles, cancelable und composed.

Wichtig: Ein mit dispatchEvent() ausgelöstes Ereignis ändert nicht die tatsächliche URL. Es ruft nur die registrierten Listener auf. Die Eigenschaft isTrusted ist bei solchen Ereignissen immer false.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"hashchange"`. Groß- und Kleinschreibung wird beachtet.
$options	HashChangeEventInit	{}	Optionales Objekt mit folgenden Feldern: `oldURL` (`string`, Standard `""`): die bisherige URL `newURL` (`string`, Standard `""`): die neue URL `bubbles`, `cancelable`, `composed` (`boolean`, Standard `false`) aus `EventInit`

Rückgabewert

Typ

HashChangeEvent

Beschreibung

Ein neues HashChangeEvent-Objekt mit den übergebenen Werten für oldURL und newURL.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const event = new HashChangeEvent('hashchange', {
  oldURL: 'https://example.com/#start',
  newURL: 'https://example.com/#kontakt'
});

console.log(event.type);      // Ereignistyp
console.log(event.oldURL);
console.log(event.newURL);
console.log(event.isTrusted); // synthetisch erzeugt

hashchange https://example.com/#start https://example.com/#kontakt false

Hash-Router gezielt auslösen (z. B. im Test)

const routes = {
  '#start': () => console.log('Startseite anzeigen'),
  '#kontakt': () => console.log('Kontaktformular anzeigen')
};

const onHashChange = (e) => {
  const hash = new URL(e.newURL).hash || '#start';
  (routes[hash] ?? (() => console.log('404')))();
};

window.addEventListener('hashchange', onHashChange);

// Navigation simulieren, ohne die URL zu verändern
window.dispatchEvent(new HashChangeEvent('hashchange', {
  oldURL: `${location.origin}/#start`,
  newURL: `${location.origin}/#kontakt`
}));

window.removeEventListener('hashchange', onHashChange);

Kontaktformular anzeigen

Echte Hash-Änderung vs. synthetisches Ereignis

window.onhashchange = (e) => {
  console.log(`${e.isTrusted ? 'Browser' : 'Skript'}: ${e.oldURL} → ${e.newURL}`);
};

// 1) Echt: der Browser feuert hashchange asynchron
location.hash = '#abschnitt-2';

// 2) Synthetisch: sofort, aber ohne URL-Änderung
window.dispatchEvent(new HashChangeEvent('hashchange', {
  oldURL: location.href,
  newURL: location.href.split('#')[0] + '#test'
}));

Skript: …/#abschnitt-2 → …/#test Browser: …/ → …/#abschnitt-2

// Wichtig · Fallstricke

Keine Navigation: dispatchEvent(new HashChangeEvent(...)) ändert weder location.hash noch den Verlauf. Für echte Änderungen setzt man location.hash.
Synchron vs. asynchron: Ein selbst ausgelöstes Ereignis ruft die Listener sofort (synchron) auf. Das vom Browser ausgelöste hashchange kommt dagegen asynchron in einem späteren Task.
isTrusted ist immer false. Code, der nur echten Ereignissen vertraut, reagiert darauf nicht.
oldURL und newURL sind schreibgeschützt und lassen sich nur über den Konstruktor setzen. Der Konstruktor prüft nicht, ob die Werte gültige URLs sind. Ohne Angabe sind sie leere Strings, und dann wirft etwa new URL(e.newURL) einen Fehler.
history.pushState()/replaceState() lösen kein hashchange aus, auch wenn sich der Hash ändert.
Kompatibilität: Alle modernen Browser unterstützen den Konstruktor. Der Internet Explorer kennt ihn nicht, dort war nur das veraltete document.createEvent('HashChangeEvent') verfügbar.

Siehe auch

HashChangeEvent HashChangeEvent.oldURL HashChangeEvent.newURL Location.hash EventTarget.dispatchEvent() PopStateEvent