PreferenceManager.contrast — Eigenschaft · JavaScript-Referenz

Signatur

PreferenceManager.contrast

Beschreibung

Die Eigenschaft contrast der Schnittstelle PreferenceManager (erreichbar über navigator.preferences) gibt ein PreferenceObject zurück. Es steht für die Nutzerpräferenz, die sonst über die CSS-Media-Query prefers-contrast ausgewertet wird. Über dieses Objekt kann eine Website die Systemeinstellung nur für sich selbst überschreiben, z. B. um einen eigenen Schalter „Hoher Kontrast“ in den Seiteneinstellungen anzubieten.

Das zurückgegebene PreferenceObject bietet unter anderem:

value: den aktuell wirksamen Wert (mit Überschreibung, falls gesetzt), z. B. "more", "less" oder "no-preference".
override: den von der Website gesetzten Wert oder null, wenn nichts überschrieben ist.
validValues: die Werte, die für eine Überschreibung erlaubt sind.
requestOverride(value): fordert eine Überschreibung an und gibt ein Promise zurück.
clearOverride(): entfernt die Überschreibung wieder.
das Ereignis change, das bei Änderungen des wirksamen Werts ausgelöst wird.

Der Vorteil gegenüber eigenen CSS-Klassen: Wird die Überschreibung gesetzt, werten Media-Queries wie @media (prefers-contrast: more) und matchMedia() automatisch den überschriebenen Wert aus. Bestehende Stylesheets funktionieren also ohne Anpassung weiter.

Beispiele

Aktuellen Kontrastwert mit Feature-Erkennung auslesen

if ('preferences' in navigator && navigator.preferences.contrast) {
  const contrast = navigator.preferences.contrast;
  console.log('Wirksamer Wert:', contrast.value);
  console.log('Überschreibung:', contrast.override);
  console.log('Erlaubte Werte:', contrast.validValues);
} else {
  // Rückfall auf die Media-Query
  const more = matchMedia('(prefers-contrast: more)').matches;
  console.log('Hoher Kontrast gewünscht:', more);
}

Wirksamer Wert: no-preference Überschreibung: null Erlaubte Werte: ["more", "less", "no-preference"]

Schalter „Hoher Kontrast“ in den Seiteneinstellungen

const toggle = document.querySelector('#high-contrast');
const contrast = navigator.preferences?.contrast;

if (contrast) {
  toggle.checked = contrast.value === 'more';

  toggle.addEventListener('change', async () => {
    try {
      if (toggle.checked) {
        await contrast.requestOverride('more');
      } else {
        contrast.clearOverride();
      }
    } catch (err) {
      console.error('Überschreibung fehlgeschlagen:', err);
      toggle.checked = contrast.value === 'more';
    }
  });
} else {
  toggle.disabled = true;
}

Auf Änderungen reagieren

const contrast = navigator.preferences?.contrast;

contrast?.addEventListener('change', () => {
  console.log('Kontrast jetzt:', contrast.value);
  document.documentElement.dataset.contrast = contrast.value;
});

// Media-Queries berücksichtigen die Überschreibung automatisch
matchMedia('(prefers-contrast: more)').addEventListener('change', (e) => {
  console.log('prefers-contrast: more ->', e.matches);
});

Kontrast jetzt: more prefers-contrast: more -> true

// Wichtig · Fallstricke

Experimentell: Die Web Preferences API ist noch kein Standard und derzeit höchstens in Chromium-basierten Browsern (teils hinter Flag oder im Origin Trial) verfügbar. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit navigator.preferences?.contrast und sieh einen Rückfall über matchMedia('(prefers-contrast: …)') vor.

Die Überschreibung gilt nur für die eigene Website (bzw. den eigenen Origin) und ändert nicht die Systemeinstellung.
requestOverride() gibt ein Promise zurück, das abgelehnt werden kann, z. B. bei ungültigen Werten, die nicht in validValues stehen. Fehler also immer abfangen.
Barrierefreiheit: Die Systemeinstellung des Nutzers solltest du nur auf seinen ausdrücklichen Wunsch überschreiben und immer eine Möglichkeit zum Zurücksetzen (clearOverride()) anbieten.
Den Wert "custom" der Media-Query prefers-contrast kann man in der Regel nicht als Überschreibung setzen, weil er von erzwungenen Farben (forced-colors) abhängt.

Siehe auch

PreferenceManager.colorScheme PreferenceManager.reducedData PreferenceManager.reducedMotion PreferenceManager.reducedTransparency PaymentManager.userHint