PreferenceObject: change — Ereignis · JavaScript-Referenz

Signatur

preferenceObject.addEventListener("change", handler)

Beschreibung

Das change-Ereignis gehört zur experimentellen Web Preferences API. Über navigator.preferences bekommt man für jede Benutzereinstellung ein eigenes PreferenceObject, etwa colorScheme, contrast, reducedMotion, reducedTransparency oder reducedData. Mit diesen Objekten kann eine Website eine Systemeinstellung wie das Farbschema für die eigene Seite überschreiben (override). Das ist zum Beispiel sinnvoll für einen Hell/Dunkel-Umschalter, der sich dann auch auf CSS-Media-Queries wie prefers-color-scheme auswirkt.

Das Ereignis wird ausgelöst, sobald sich die Eigenschaft override des jeweiligen PreferenceObject ändert. Das passiert, wenn ein Override über requestOverride(value) gesetzt oder über clearOverride() entfernt wird. Es wird auch ausgelöst, wenn ein anderes Dokument desselben Ursprungs (z. B. ein anderer Tab) den Override ändert. So lassen sich Bedienelemente wie Schalter oder Auswahlfelder synchron halten.

Einen Handler registriert man mit addEventListener("change", handler) oder über die Eigenschaft onchange. Der Handler bekommt ein einfaches Event ohne zusätzliche Daten. Den neuen Zustand liest man direkt am Objekt ab, also über event.target.override und den wirksamen Wert event.target.value.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"change"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Änderung des Overrides aufgerufen wird. `event.target` ist das betroffene `PreferenceObject`.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event-Objekt (bubbelt nicht, nicht abbrechbar).

Beispiele

Theme-Umschalter mit dem Override synchron halten

if ('preferences' in navigator) {
  const colorScheme = navigator.preferences.colorScheme;
  const toggle = document.querySelector('#dark-toggle');

  const updateUI = () => {
    // override ist null, wenn nur die Systemeinstellung gilt
    toggle.checked = colorScheme.value === 'dark';
    console.log(`Override: ${colorScheme.override}, wirksam: ${colorScheme.value}`);
  };

  colorScheme.addEventListener('change', updateUI);
  updateUI();

  toggle.addEventListener('change', async () => {
    await colorScheme.requestOverride(toggle.checked ? 'dark' : 'light');
  });
}

Override: null, wirksam: light Override: dark, wirksam: dark

Handler über die onchange-Eigenschaft

const contrast = navigator.preferences?.contrast;

if (contrast) {
  contrast.onchange = (event) => {
    const pref = event.target;
    document.documentElement.dataset.contrast = pref.value;
    console.log('Kontrast-Override geändert:', pref.override);
  };

  // Override setzen, danach wieder entfernen
  await contrast.requestOverride('more');
  contrast.clearOverride();
}

Kontrast-Override geändert: more Kontrast-Override geändert: null

Listener mit AbortController wieder entfernen

const controller = new AbortController();
const motion = navigator.preferences?.reducedMotion;

motion?.addEventListener('change', () => {
  console.log('reducedMotion jetzt:', motion.value);
}, { signal: controller.signal });

// Später, z. B. beim Abbau einer Komponente:
controller.abort(); // entfernt den Listener

// Wichtig · Fallstricke

Experimentell: Die Web Preferences API gibt es bisher nur in Chromium-basierten Browsern, teils hinter einem Flag oder als Origin Trial. Firefox und Safari unterstützen sie nicht. Vor der Nutzung immer mit 'preferences' in navigator prüfen.
Das Ereignis meldet Änderungen am Override. Ändert der Nutzer die Einstellung im Betriebssystem, während ein Override aktiv ist, ändert sich value nicht. Um auf Systemänderungen zu reagieren, zusätzlich matchMedia('(prefers-color-scheme: dark)') mit dessen change-Ereignis verwenden.
Das Event enthält keine Nutzdaten. Neue Werte immer direkt vom PreferenceObject lesen.
requestOverride() gibt ein Promise zurück und kann abgelehnt werden, z. B. bei einem ungültigen Wert (siehe validValues). Fehler mit try/catch abfangen.
Die Namen der Eigenschaften und das genaue Verhalten können sich noch ändern, solange die Spezifikation ein Entwurf ist.

Siehe auch

PreferenceObject PreferenceObject.value PreferenceObject.requestOverride() PreferenceObject.clearOverride() Navigator.preferences XRReferenceSpace: reset