PreferenceManager.reducedTransparency — Eigenschaft · JavaScript-Referenz

Signatur

PreferenceManager.reducedTransparency

Beschreibung

Die Eigenschaft reducedTransparency der Schnittstelle PreferenceManager (erreichbar über navigator.preferences) gibt ein PreferenceObject zurück. Es steht für die Benutzereinstellung, ob durchscheinende Effekte wie backdrop-filter, halbtransparente Overlays oder „Glaseffekte“ reduziert werden sollen. Diese Einstellung ist auch über die Media-Query prefers-reduced-transparency abfragbar.

Anders als eine Media-Query erlaubt das PreferenceObject mehr als das Lesen: Eine Website kann die Systemeinstellung für ihren Ursprung überschreiben, z. B. über einen Schalter „Transparenz reduzieren“ in den eigenen Einstellungen. Das Objekt bietet dafür:

value: der aktuell wirksame Wert ("no-preference" oder "reduce")
override: der von der Website gesetzte Wert oder null, wenn nichts überschrieben ist
validValues: die erlaubten Werte
requestOverride(value): setzt einen Wert und gibt ein Promise zurück
clearOverride(): entfernt den überschriebenen Wert wieder
das Ereignis change bzw. die Eigenschaft onchange

Ein überschriebener Wert wirkt auch auf CSS: @media (prefers-reduced-transparency: reduce) und matchMedia() liefern danach den neuen Wert. Das Stylesheet muss also nicht doppelt gepflegt werden.

Rückgabewert

Typ

PreferenceObject

Beschreibung

Ein PreferenceObject für die Präferenz „reduzierte Transparenz“ mit value, override, validValues, requestOverride(), clearOverride() und dem Ereignis change. Die Eigenschaft ist schreibgeschützt.

Beispiele

Aktuellen Wert mit Funktionsprüfung auslesen

const getReducedTransparency = () => {
  // Web Preferences API vorhanden?
  if ('preferences' in navigator && navigator.preferences.reducedTransparency) {
    return navigator.preferences.reducedTransparency.value;
  }
  // Rückfall auf die Media-Query
  return matchMedia('(prefers-reduced-transparency: reduce)').matches
    ? 'reduce'
    : 'no-preference';
};

console.log(getReducedTransparency());

no-preference

Einstellungs-Schalter: Transparenz für die Website reduzieren

const pref = navigator.preferences?.reducedTransparency;
const toggle = document.querySelector('#reduce-transparency');

if (pref) {
  toggle.checked = pref.value === 'reduce';

  toggle.addEventListener('change', async () => {
    try {
      if (toggle.checked) {
        await pref.requestOverride('reduce');
      } else {
        // zurück zur Systemeinstellung
        pref.clearOverride();
      }
      console.log('Wirksam:', pref.value, '| Override:', pref.override);
    } catch (err) {
      console.error('Override fehlgeschlagen:', err);
    }
  });
} else {
  toggle.disabled = true;
}

Wirksam: reduce | Override: reduce

Auf Änderungen reagieren (change-Ereignis und onchange)

const pref = navigator.preferences?.reducedTransparency;

const apply = () => {
  document.documentElement.classList.toggle('no-glass', pref.value === 'reduce');
};

if (pref) {
  apply();
  pref.addEventListener('change', apply);
  // alternativ: pref.onchange = apply;

  // später wieder abmelden:
  // pref.removeEventListener('change', apply);
}

Gültige Werte ermitteln

const pref = navigator.preferences?.reducedTransparency;
console.log(pref ? [...pref.validValues] : 'API nicht verfügbar');

["no-preference", "reduce"]

// Wichtig · Fallstricke

Experimentell: Die Web Preferences API ist noch kein Standard. Bisher gibt es sie nur in Chromium-Browsern hinter einem Flag bzw. im Rahmen von Tests. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit navigator.preferences?.reducedTransparency, ob sie vorhanden ist, und greife sonst auf matchMedia('(prefers-reduced-transparency: reduce)') zurück. Auch diese Media-Query wird nicht überall unterstützt (z. B. in Safari).

Die Eigenschaft ist schreibgeschützt. navigator.preferences.reducedTransparency = … hat keine Wirkung. Änderungen laufen ausschließlich über requestOverride().
requestOverride() mit einem Wert, der nicht in validValues steht, führt zu einem abgelehnten Promise (TypeError).
Ein überschriebener Wert gilt nur für den eigenen Ursprung. Er kann sitzungsgebunden sein und die Systemeinstellung nicht dauerhaft ändern.
Barrierefreiheit: Die Wahl der Nutzer hat Vorrang. Setze nie ungefragt "no-preference", um eine Systemeinstellung „Transparenz reduzieren“ auszuhebeln. Überschreibe nur auf ausdrückliche Aktion hin.

Siehe auch

PreferenceManager.colorScheme PreferenceManager.reducedData PreferenceManager.reducedMotion PreferenceManager.contrast XRReferenceSpaceEvent.transform