PreferenceObject.clearOverride() — Methode · JavaScript-Referenz

Signatur

PreferenceObject.prototype.clearOverride()

Beschreibung

clearOverride() gehört zur experimentellen User Preferences API. Über navigator.preferences erhält man einen PreferenceManager, dessen Eigenschaften wie colorScheme, contrast, reducedMotion, reducedTransparency oder reducedData jeweils ein PreferenceObject sind. Mit requestOverride(value) kann eine Website eine Präferenz für die eigene Origin überschreiben, zum Beispiel ein dunkles Farbschema erzwingen. clearOverride() nimmt diesen Override wieder zurück.

Nach dem Aufruf hat override wieder den Wert null. value entspricht dann wieder der tatsächlichen Einstellung des Systems bzw. Browsers. Media Queries wie prefers-color-scheme und matchMedia() richten sich ebenfalls wieder nach dieser Einstellung. Ändert sich der wirksame Wert, löst das PreferenceObject ein change-Ereignis aus.

Typischerweise gehört die Methode zu einem Einstellungsschalter mit der Option „Systemstandard“ oder „Automatisch“: Wählt die Person diese Option, ruft man clearOverride() auf, statt einen festen Wert zu speichern.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Den neuen Zustand liest man über override (danach null) und value aus.

Beispiele

Farbschema-Override zurücksetzen

const scheme = navigator.preferences?.colorScheme;

if (scheme) {
  await scheme.requestOverride('dark');
  console.log('Override:', scheme.override, '| Wert:', scheme.value);

  scheme.clearOverride();
  console.log('Override:', scheme.override, '| Wert:', scheme.value);
} else {
  console.log('User Preferences API nicht verfügbar');
}

Override: dark | Wert: dark Override: null | Wert: light // abhängig von der Systemeinstellung

Theme-Auswahl mit Option „System“

// <select id="theme"><option value="system">System</option><option value="light">Hell</option><option value="dark">Dunkel</option></select>
const select = document.querySelector('#theme');
const scheme = navigator.preferences?.colorScheme;

if (scheme) {
  // Startzustand aus dem aktuellen Override ableiten
  select.value = scheme.override ?? 'system';

  select.addEventListener('change', async () => {
    try {
      if (select.value === 'system') {
        scheme.clearOverride();
      } else {
        await scheme.requestOverride(select.value);
      }
    } catch (err) {
      console.error('Präferenz konnte nicht geändert werden:', err);
    }
  });
} else {
  select.disabled = true;
}

Auf die Änderung nach clearOverride() reagieren

const motion = navigator.preferences?.reducedMotion;

if (motion) {
  motion.addEventListener('change', () => {
    console.log('Reduzierte Bewegung jetzt:', motion.value);
  });

  await motion.requestOverride('reduce');
  // Später: wieder die Systemeinstellung verwenden
  motion.clearOverride();
  console.log(matchMedia('(prefers-reduced-motion: reduce)').matches);
}

Reduzierte Bewegung jetzt: reduce Reduzierte Bewegung jetzt: no-preference false // bei Systemeinstellung „no-preference“

// Wichtig · Fallstricke

Experimentell: Die API steht bisher nur in Chromium-basierten Browsern hinter einem Flag bzw. in einem Origin Trial zur Verfügung. Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man deshalb immer prüfen, ob sie vorhanden ist, etwa mit navigator.preferences?.colorScheme. Ist sie nicht vorhanden, bietet sich als Ersatz eine eigene CSS-Klasse oder ein data-theme-Attribut an.
Der Override gilt nur für die eigene Origin. Andere Websites und das Betriebssystem bleiben unberührt.
Wurde kein Override gesetzt, bewirkt der Aufruf nichts und löst auch kein change-Ereignis aus.
Stimmt der Override mit dem Systemwert überein, ändert sich value nicht. Dann feuert ebenfalls kein change-Ereignis, obwohl override auf null zurückgesetzt wird.
Die Methode ist synchron, requestOverride() gibt dagegen ein Promise zurück. Das ist bei gemischtem Code wichtig.
Die Spezifikation kann sich noch ändern. Der genaue Zeitpunkt des change-Ereignisses kann sich deshalb je nach Implementierung unterscheiden.

Siehe auch

Navigator.preferences PreferenceObject.requestOverride() PreferenceObject.override Performance.clearMarks() Performance.clearMeasures()