CookieChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface CookieChangeEvent extends Event

Beschreibung

CookieChangeEvent gehört zur Cookie Store API. Ein solches Objekt bekommst du, wenn du auf window.cookieStore das Event change abonnierst. Es wird ausgelöst, sobald ein Cookie, das für das aktuelle Dokument sichtbar ist, angelegt, überschrieben oder gelöscht wird. Die Quelle spielt dabei keine Rolle: Die Änderung kann aus JavaScript kommen (cookieStore.set(), document.cookie), von einem Set-Cookie-Header des Servers oder aus einem anderen Tab.

Früher musste man document.cookie regelmäßig abfragen, um Änderungen mitzubekommen. Mit dem Event reagierst du dagegen direkt darauf, zum Beispiel wenn eine Sitzung in einem anderen Tab beendet wird, wenn sich ein Einwilligungs-Cookie ändert oder wenn sich die gewählte Sprache ändert.

Das Event bringt zwei schreibgeschützte Eigenschaften mit:

changed: ein fest eingefrorenes Array von CookieListItem-Objekten (name, value, domain, path, expires, secure, sameSite, partitioned) für neu gesetzte oder überschriebene Cookies.
deleted: ein fest eingefrorenes Array von CookieListItem-Objekten für gelöschte Cookies. Bei gelöschten Cookies ist in der Regel nur name verlässlich gesetzt, value ist meist undefined.

In Service Workern wird stattdessen das verwandte ExtendableCookieChangeEvent über das Event cookiechange ausgelöst. Dafür musst du die Cookies vorher mit registration.cookies.subscribe() abonnieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Events, normalerweise `"change"`.
$options	object	{}	Konstruktor-Parameter: Optionen, die über `EventInit` hinausgehen (`bubbles`, `cancelable`, `composed` sind ebenfalls erlaubt).
$options.changed	Array<CookieListItem>	[]	Cookies, die als gesetzt bzw. geändert gemeldet werden sollen.
$options.deleted	Array<CookieListItem>	[]	Cookies, die als gelöscht gemeldet werden sollen.

Rückgabewert

Typ

CookieChangeEvent

Beschreibung

Beim Konstruktor: eine neue Instanz mit den eingefrorenen Arrays changed und deleted. In Event-Handlern bekommst du das Objekt als Argument übergeben.

Beispiele

Cookie-Änderungen mit addEventListener überwachen

if ('cookieStore' in window) {
  cookieStore.addEventListener('change', (event) => {
    for (const cookie of event.changed) {
      console.log(`Gesetzt: ${cookie.name} = ${cookie.value}`);
    }
    for (const cookie of event.deleted) {
      console.log(`Gelöscht: ${cookie.name}`);
    }
  });

  // Änderungen auslösen
  await cookieStore.set('theme', 'dark');
  await cookieStore.delete('theme');
} else {
  console.warn('Cookie Store API wird nicht unterstützt');
}

Gesetzt: theme = dark Gelöscht: theme

Abmeldung in einem anderen Tab erkennen (onchange-Property)

const handleCookieChange = (event) => {
  const sessionDeleted = event.deleted.some((c) => c.name === 'session_id');
  if (sessionDeleted) {
    console.log('Sitzung beendet – weiter zur Anmeldung');
    location.assign('/login');
  }
};

cookieStore.onchange = handleCookieChange;

// Später wieder abmelden:
// cookieStore.onchange = null;

Sitzung beendet – weiter zur Anmeldung

Event manuell erzeugen, z. B. für Tests

const event = new CookieChangeEvent('change', {
  changed: [{ name: 'lang', value: 'de' }],
  deleted: [{ name: 'old_pref' }]
});

console.log(event.type);                 // "change"
console.log(event.changed[0].name);      // "lang"
console.log(event.deleted.length);       // 1
console.log(Object.isFrozen(event.changed)); // true

change lang 1 true

Listener sauber wieder entfernen

const controller = new AbortController();

cookieStore.addEventListener('change', (event) => {
  console.log('Änderungen:', event.changed.length, 'gelöscht:', event.deleted.length);
}, { signal: controller.signal });

// Beim Verlassen der Ansicht:
controller.abort();

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die API seit Version 87. Safari und Firefox sind erst in neueren Versionen dazugekommen. Prüfe die Unterstützung immer vorher mit 'cookieStore' in window und sieh eine Ausweichlösung vor, etwa das Abfragen von document.cookie.
Nur in sicheren Kontexten: Die API steht nur über HTTPS bzw. auf localhost zur Verfügung.
HttpOnly-Cookies sind für Skripte unsichtbar. Für sie wird kein change-Event ausgelöst.
Wenn ein Cookie mit einem Ablaufdatum in der Vergangenheit gesetzt wird, erscheint es in deleted und nicht in changed. Wird ein bestehendes Cookie überschrieben, erscheint es nur in changed.
Bei Einträgen in deleted ist value in der Regel undefined. Verlass dich nur auf name (und gegebenenfalls path/domain).
Ein Event kann mehrere Änderungen auf einmal enthalten. Durchlaufe deshalb immer beide Arrays vollständig.
In Service Workern gibt es kein change-Event auf cookieStore. Dort verwendest du cookiechange mit ExtendableCookieChangeEvent und vorherigem subscribe().

Siehe auch

Document.cookie Event HashChangeEvent BufferedChangeEvent ClipboardChangeEvent