PreferenceObject — Schnittstelle · JavaScript-Referenz

Signatur

interface PreferenceObject extends EventTarget

Beschreibung

Ein PreferenceObject steht für genau eine Benutzereinstellung, die sonst nur über CSS-Media-Features wie prefers-color-scheme oder prefers-reduced-motion abgefragt werden kann. Du erhältst die Objekte über navigator.preferences (eine PreferenceManager-Instanz), zum Beispiel navigator.preferences.colorScheme, .contrast, .reducedMotion, .reducedTransparency und .reducedData. Einen Konstruktor gibt es nicht.

Wozu das gut ist: Viele Websites haben einen eigenen Umschalter für den Dunkelmodus oder für weniger Animationen. Mit requestOverride() überschreibt die Seite den Wert, den das System meldet. Die Media-Features in CSS und in matchMedia() liefern danach den neuen Wert. Du brauchst also keine eigene CSS-Klasse wie .dark mehr, und Stylesheets, Bilder mit <picture> und eingebettete Komponenten verhalten sich gleich.

Wichtige Mitglieder:

value (string, nur lesbar): der aktuell wirksame Wert, also die Überschreibung, falls es eine gibt, sonst der Systemwert.
override (string | null, nur lesbar): die aktuelle Überschreibung der Seite oder null.
validValues (eingefrorenes string[]): die erlaubten Werte, z. B. ["light", "dark"] bei colorScheme.
requestOverride(value): fordert eine Überschreibung an und gibt ein Promise<undefined> zurück.
clearOverride(): entfernt die Überschreibung sofort. Danach gilt wieder der Systemwert.
change-Event bzw. onchange: wird ausgelöst, wenn sich value ändert, sei es durch das System oder durch eine Überschreibung.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	string \| null		Parameter von `requestOverride()`: der gewünschte Wert. Er muss in `validValues` enthalten sein, sonst wird das Promise abgelehnt. Laut Spezifikation entfernen `null` oder ein leerer String die Überschreibung.

Rückgabewert

Typ

PreferenceObject

Beschreibung

Wird über navigator.preferences.<name> abgerufen und nicht selbst erzeugt. requestOverride() gibt Promise<undefined> zurück, clearOverride() gibt undefined zurück.

Beispiele

Einstellung lesen (mit Feature-Erkennung)

const pref = navigator.preferences?.colorScheme;

if (pref) {
  console.log('Wirksamer Wert:', pref.value);
  console.log('Überschreibung:', pref.override);
  console.log('Erlaubt:', pref.validValues);
} else {
  // Rückfall auf matchMedia
  const dark = matchMedia('(prefers-color-scheme: dark)').matches;
  console.log('Wirksamer Wert:', dark ? 'dark' : 'light');
}

Wirksamer Wert: dark Überschreibung: null Erlaubt: ['light', 'dark']

Dunkelmodus-Umschalter mit requestOverride()

const toggle = document.querySelector('#theme-toggle');

toggle.addEventListener('click', async () => {
  const pref = navigator.preferences?.colorScheme;
  if (!pref) return;

  const next = pref.value === 'dark' ? 'light' : 'dark';
  try {
    await pref.requestOverride(next);
    localStorage.setItem('theme-override', next);
    console.log('Neues Farbschema:', pref.value);
  } catch (err) {
    console.error('Überschreibung abgelehnt:', err.name);
  }
});

Neues Farbschema: light

Auf Änderungen reagieren und Überschreibung zurücksetzen

const motion = navigator.preferences?.reducedMotion;

if (motion) {
  const onChange = () => {
    document.documentElement.dataset.motion = motion.value;
    console.log('reducedMotion ist jetzt:', motion.value);
  };

  motion.addEventListener('change', onChange);
  // alternativ: motion.onchange = onChange;

  document.querySelector('#reset')?.addEventListener('click', () => {
    motion.clearOverride(); // zurück zum Systemwert
    localStorage.removeItem('motion-override');
  });
}

reducedMotion ist jetzt: no-preference

// Wichtig · Fallstricke

Experimentell: Die API wird derzeit nur in Chromium-Browsern getestet, entweder hinter einem Flag oder als Origin Trial. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit navigator.preferences?.colorScheme, ob sie vorhanden ist, und greife sonst auf matchMedia() oder eine CSS-Klasse zurück.
Überschreibungen gelten nur für den Ursprung (Origin), und ob der Browser sie über mehrere Sitzungen speichert, hängt von der Implementierung ab. Speichere die Wahl des Nutzers zusätzlich selbst, z. B. in localStorage, und setze sie beim Laden erneut.
requestOverride() kann abgelehnt werden: bei einem ungültigen Wert oder wenn der Browser die Anfrage verweigert. Fange Fehler daher immer mit try/catch ab.
Werte in validValues können je nach Browser und Einstellung verschieden sein. Schreibe Werte wie "dark" nicht fest in den Code, ohne sie vorher gegen validValues zu prüfen.
Barrierefreiheit: Überschreibe Einstellungen wie reducedMotion oder contrast nur, wenn der Nutzer es selbst ausdrücklich wählt, und nie automatisch. Sonst übergehst du bewusst getroffene Systemeinstellungen.

Siehe auch

Navigator.preferences PreferenceManager XRReferenceSpace ProgressEvent WebGLObject