new CookieChangeEvent() — Methode · JavaScript-Referenz

Signatur

new CookieChangeEvent(type, eventInitDict)

Beschreibung

Der Konstruktor CookieChangeEvent() erzeugt ein Ereignisobjekt mit den Eigenschaften changed und deleted. Beide sind eingefrorene Arrays aus Cookie-Objekten ({ name, value, domain, path, expires, secure, sameSite, partitioned }). Der Browser erzeugt solche Objekte selbst und löst sie auf cookieStore aus, sobald ein Cookie gesetzt, geändert oder gelöscht wird, egal ob über document.cookie, die Cookie Store API oder einen HTTP-Header Set-Cookie.

Den Konstruktor selbst ruft man vor allem in Tests, beim Mocking oder für eigene Ereignisverteilung auf, etwa wenn man Code prüfen will, der auf change-Ereignisse reagiert, ohne echte Cookies zu verändern. Ein mit dispatchEvent() ausgelöstes, selbst erzeugtes Ereignis hat isTrusted === false.

In Service Workern gibt es mit ExtendableCookieChangeEvent ein eigenes Gegenstück. Es wird über cookieStore.subscribe() und das Ereignis cookiechange auf self genutzt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Der Browser verwendet immer `"change"`.
$eventInitDict	CookieChangeEventInit	{}	Optionales Objekt. Es enthält neben den `EventInit`-Feldern (`bubbles`, `cancelable`, `composed`) auch `changed` (Array geänderter/neuer Cookies, Standard `[]`) und `deleted` (Array gelöschter Cookies, Standard `[]`).

Rückgabewert

Typ

CookieChangeEvent

Beschreibung

Ein neues CookieChangeEvent-Objekt. changed und deleted sind eingefrorene Arrays.

Beispiele

Ereignis manuell erzeugen und untersuchen

const event = new CookieChangeEvent('change', {
  changed: [{ name: 'theme', value: 'dark' }],
  deleted: [{ name: 'session' }]
});

console.log(event.type);
console.log(event.changed.map(c => `${c.name}=${c.value}`));
console.log(event.deleted.map(c => c.name));
console.log(Object.isFrozen(event.changed));

change ["theme=dark"] ["session"] true

Echte Cookie-Änderungen beobachten

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}`);
  }
});

await cookieStore.set('lang', 'de');
await cookieStore.delete('lang');

Gesetzt: lang = de Gelöscht: lang

Handler im Test mit einem simulierten Ereignis prüfen

const onCookieChange = (event) => {
  const theme = event.changed.find(c => c.name === 'theme');
  if (theme) document.documentElement.dataset.theme = theme.value;
};

const target = new EventTarget();
target.addEventListener('change', onCookieChange);

// Simuliertes Ereignis, ohne echte Cookies zu verändern
target.dispatchEvent(new CookieChangeEvent('change', {
  changed: [{ name: 'theme', value: 'light' }]
}));

console.log(document.documentElement.dataset.theme);

light

// Wichtig · Fallstricke

Browser-Unterstützung: Die Cookie Store API steht in Chromium-Browsern seit Version 87 zur Verfügung, in Safari seit 18.4 und in Firefox erst seit Version 140. Prüfen Sie die Verfügbarkeit mit 'CookieChangeEvent' in self bzw. 'cookieStore' in self.
Nur in sicheren Kontexten: Die API gibt es nur unter HTTPS oder localhost.
HttpOnly-Cookies erscheinen nie in changed oder deleted, weil Skripte keinen Zugriff auf sie haben.
Ein abgelaufenes Cookie oder ein Cookie, das mit einem Ablaufdatum in der Vergangenheit überschrieben wird, taucht in deleted auf, nicht in changed.
Die Arrays sind eingefroren. Wenn Sie etwa event.changed.push() aufrufen, wirft das im Strict Mode einen TypeError.
Selbst erzeugte Ereignisse haben isTrusted === false. Sicherheitsrelevante Logik sollte sich nicht auf sie verlassen.
In Service Workern nutzt man ExtendableCookieChangeEvent statt CookieChangeEvent.

Siehe auch

CookieChangeEvent CookieStore CookieStore.prototype.set() ExtendableCookieChangeEvent Document.cookie new BufferedChangeEvent()