PreferenceObject.value — Eigenschaft · JavaScript-Referenz

Signatur

PreferenceObject.value

Beschreibung

Die schreibgeschützte Eigenschaft value eines PreferenceObject gibt an, welcher Wert für eine Nutzerpräferenz gerade gilt. Sie gehört zur experimentellen Web Preferences API. An die einzelnen PreferenceObject-Instanzen kommt man über navigator.preferences, zum Beispiel über navigator.preferences.colorScheme, .contrast, .reducedMotion, .reducedTransparency oder .reducedData.

Hat die Website mit requestOverride() einen eigenen Wert gesetzt, liefert value diesen Override. Andernfalls liefert sie den Wert, den der User-Agent festlegt, also in der Regel die Einstellung aus Browser oder Betriebssystem. value entspricht damit dem, was die zugehörige CSS-Media-Query (z. B. prefers-color-scheme) gerade auswertet.

Brauchbar ist die Eigenschaft vor allem für Einstellungsdialoge wie „Hell / Dunkel / System“. Dort muss die Oberfläche den aktuell wirksamen Zustand anzeigen, egal ob er von der Website oder vom System kommt. Ob ein Override gesetzt ist, verrät die Eigenschaft override. Welche Werte erlaubt sind, steht in validValues.

Rückgabewert

Typ

string

Beschreibung

Der wirksame Präferenzwert als Zeichenkette. Bei colorScheme etwa "light" oder "dark", bei contrast "more", "less" oder "no-preference", bei reducedMotion "reduce" oder "no-preference".

Beispiele

Aktuell wirksames Farbschema auslesen

if ('preferences' in navigator) {
  const scheme = navigator.preferences.colorScheme;
  console.log(`Wirksam: ${scheme.value}`);
  console.log(`Override: ${scheme.override ?? 'keiner'}`);
} else {
  // Fallback über Media Query
  const dark = matchMedia('(prefers-color-scheme: dark)').matches;
  console.log(`Wirksam (Fallback): ${dark ? 'dark' : 'light'}`);
}

Wirksam: dark Override: keiner

Theme-Umschalter mit Anzeige des echten Zustands

const scheme = navigator.preferences?.colorScheme;
const label = document.querySelector('#theme-status');

const render = () => {
  label.textContent = scheme.override
    ? `Manuell: ${scheme.value}`
    : `System: ${scheme.value}`;
};

document.querySelector('#toggle').addEventListener('click', async () => {
  const next = scheme.value === 'dark' ? 'light' : 'dark';
  try {
    await scheme.requestOverride(next);
  } catch (err) {
    console.warn('Override abgelehnt:', err);
  }
  render();
});

document.querySelector('#reset').addEventListener('click', () => {
  scheme.clearOverride();
  render();
});

scheme.addEventListener('change', render);
render();

Animationen abhängig von reducedMotion steuern

const motion = navigator.preferences?.reducedMotion;
const prefersReduced = motion
  ? motion.value === 'reduce'
  : matchMedia('(prefers-reduced-motion: reduce)').matches;

const duration = prefersReduced ? 0 : 300;
console.log(`Animationsdauer: ${duration} ms`);

Animationsdauer: 300 ms

// Wichtig · Fallstricke

Experimentell: Die Web Preferences API gibt es bislang nur in Chromium-basierten Browsern, und dort nur hinter einem Flag bzw. in einem Origin Trial. Firefox und Safari unterstützen sie nicht. Deshalb vorher immer mit 'preferences' in navigator prüfen und auf matchMedia() zurückfallen.
Schreibgeschützt: Eine Zuweisung an value hat keine Wirkung und wirft im Strict Mode einen Fehler. Um den Wert zu ändern, nutzt man requestOverride(), zum Zurücksetzen clearOverride().
value ist nie null. override dagegen ist null, solange kein Override gesetzt ist. Wer wissen will, woher der Wert stammt, muss beide Eigenschaften vergleichen.
Der Wert kann sich jederzeit ändern, etwa durch einen Wechsel der Systemeinstellung. Deshalb auf das change-Ereignis hören, statt den Wert nur einmal zu speichern.
In der MDN-Beschreibung wird die Eigenschaft teilweise fälschlich PreferenceManager zugeordnet. Tatsächlich gehört sie zu PreferenceObject.

Siehe auch

PreferenceObject PreferenceObject.validValues PreferenceObject.prototype.requestOverride() PreferenceObject.prototype.clearOverride() PreferenceManager Window.prototype.matchMedia()