PreferenceManager — Schnittstelle · JavaScript-Referenz

Signatur

interface PreferenceManager

Beschreibung

Das PreferenceManager-Interface gehört zur experimentellen User Preferences API. Eine Instanz erhältst du über navigator.preferences. Jede Eigenschaft steht für eine Benutzerpräferenz, die sonst nur über CSS-Media-Features wie prefers-color-scheme sichtbar ist, und liefert ein PreferenceObject:

colorScheme: entspricht prefers-color-scheme ("light", "dark")
contrast: entspricht prefers-contrast ("no-preference", "more", "less")
reducedMotion: entspricht prefers-reduced-motion ("no-preference", "reduce")
reducedTransparency: entspricht prefers-reduced-transparency
reducedData: entspricht prefers-reduced-data

Das Besondere daran: Die API liest die Präferenzen nicht nur, sie kann sie auch für die eigene Website überschreiben. Mit PreferenceObject.requestOverride(value) kann ein eigener Umschalter für den Dunkelmodus zum Beispiel prefers-color-scheme auf "dark" setzen. Danach reagieren alle CSS-Media-Queries, matchMedia() und eingebettete Inhalte so, als hätte der Benutzer das systemweit eingestellt. Mit clearOverride() nimmst du die Überschreibung wieder zurück.

Die API eignet sich vor allem für Einstellungsseiten und Theme-Umschalter. Ohne sie müsste man Präferenzen doppelt pflegen, einmal als Media-Query und einmal als CSS-Klasse. Die Werte liest du über PreferenceObject.value (ohne Überschreibung ist der Wert null). Die erlaubten Werte stehen in validValues, und auf Änderungen reagierst du mit dem Event change.

Rückgabewert

Typ

PreferenceManager

Beschreibung

Wird über navigator.preferences abgerufen. Die Eigenschaften colorScheme, contrast, reducedMotion, reducedTransparency und reducedData sind schreibgeschützt und liefern jeweils ein PreferenceObject.

Beispiele

Unterstützung prüfen und Farbschema auslesen

if ('preferences' in navigator) {
  const { colorScheme } = navigator.preferences;
  // value ist null, solange keine Überschreibung aktiv ist
  console.log('Überschreibung:', colorScheme.value);
  console.log('Erlaubte Werte:', colorScheme.validValues);
  // Den tatsächlich wirksamen Wert liefert weiterhin matchMedia
  const dark = matchMedia('(prefers-color-scheme: dark)').matches;
  console.log('Effektiv dunkel:', dark);
} else {
  console.log('User Preferences API nicht verfügbar');
}

Überschreibung: null Erlaubte Werte: ['light', 'dark'] Effektiv dunkel: false

Dark-Mode-Umschalter mit requestOverride()

const select = document.querySelector('#theme'); // <select> mit auto/light/dark

select.addEventListener('change', async () => {
  const pref = navigator.preferences?.colorScheme;
  if (!pref) return;
  try {
    if (select.value === 'auto') {
      pref.clearOverride();
    } else {
      await pref.requestOverride(select.value);
    }
    console.log('Aktiv:', pref.value ?? 'System');
  } catch (err) {
    console.error('Überschreiben fehlgeschlagen:', err.name);
  }
});

Aktiv: dark

Auf Änderungen reagieren (reducedMotion)

const motion = navigator.preferences?.reducedMotion;

const applyMotion = () => {
  const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
  document.documentElement.classList.toggle('no-animations', reduce);
  console.log('Animationen reduziert:', reduce);
};

if (motion) {
  motion.addEventListener('change', applyMotion);
  // alternativ: motion.onchange = applyMotion;
}
applyMotion();

Animationen reduziert: false

// Wichtig · Fallstricke

Experimentell: Die API ist noch nicht standardisiert. Chromium bietet sie nur hinter dem Flag Experimental Web Platform features oder als Origin Trial an, und das bisher nur teilweise (vor allem colorScheme). Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit 'preferences' in navigator und halte eine Lösung mit CSS-Klassen oder localStorage als Rückfall bereit.

PreferenceObject.value gibt nur die Überschreibung zurück, nicht die Systemeinstellung. Den tatsächlich wirksamen Wert ermittelst du mit matchMedia().
Eine Überschreibung gilt nur für den eigenen Origin. Ob und wie lange sie gespeichert bleibt, hängt vom Browser ab.
requestOverride() gibt ein Promise zurück. Es wird bei ungültigen Werten (zum Beispiel einem TypeError) oder fehlender Berechtigung abgelehnt. Frage nach einer Benutzeraktion an und fange Fehler ab.
Datenschutz: Präferenzen können zum Fingerprinting beitragen. Überschreibe Einstellungen zur Barrierefreiheit wie reducedMotion oder contrast nur, wenn der Benutzer das ausdrücklich wünscht.

Siehe auch

Navigator.preferences PaymentManager PreferenceObject XRReferenceSpace BatteryManager