PreferenceObject.validValues — Eigenschaft · JavaScript-Referenz

Signatur

PreferenceObject.validValues

Beschreibung

Die schreibgeschützte Eigenschaft validValues der Schnittstelle PreferenceObject gehört zur Web Preferences API. Sie liefert ein eingefrorenes Array (FrozenArray<string>) mit allen Werten, die eine Website für die jeweilige Benutzereinstellung als Überschreibung setzen darf. PreferenceObject-Instanzen erhält man über navigator.preferences, zum Beispiel navigator.preferences.colorScheme oder navigator.preferences.contrast.

Die Eigenschaft braucht man vor allem, um Bedienelemente wie einen Umschalter für den Dunkelmodus oder eine Kontrastauswahl dynamisch aufzubauen. Außerdem kann man damit einen Wert prüfen, bevor man requestOverride(value) aufruft. Ein Wert, der nicht in validValues steht, führt dazu, dass das zurückgegebene Promise abgelehnt wird.

Welche Werte enthalten sind, hängt von der Einstellung ab. Typische Werte sind:

colorScheme: "light", "dark"
contrast: "more", "less", "no-preference"
reducedMotion, reducedTransparency, reducedData: "reduce", "no-preference"

Die Werte stimmen mit den Schlüsselwörtern der passenden CSS-Media-Features überein (prefers-color-scheme, prefers-contrast usw.). Eine Überschreibung wirkt sich deshalb direkt auf Media Queries und matchMedia() aus.

Rückgabewert

Typ

ReadonlyArray<string> (FrozenArray<DOMString>)

Beschreibung

Ein eingefrorenes Array mit den Zeichenketten, die als Überschreibung für diese Einstellung erlaubt sind. Das Array lässt sich nicht verändern.

Beispiele

Erlaubte Werte für das Farbschema auslesen

if ('preferences' in navigator) {
  const { colorScheme } = navigator.preferences;
  console.log(colorScheme.validValues);
  console.log(Object.isFrozen(colorScheme.validValues));
} else {
  console.log('Web Preferences API wird nicht unterstützt');
}

["light", "dark"] true

Auswahlfeld für den Kontrast dynamisch erzeugen

const contrast = navigator.preferences?.contrast;

if (contrast) {
  const select = document.createElement('select');

  for (const value of contrast.validValues) {
    const option = new Option(value, value);
    option.selected = value === contrast.override;
    select.append(option);
  }

  select.addEventListener('change', async () => {
    try {
      await contrast.requestOverride(select.value);
    } catch (err) {
      console.error('Überschreibung fehlgeschlagen:', err);
    }
  });

  document.body.append(select);
}

Wert vor requestOverride() prüfen

const setPreference = async (name, value) => {
  const pref = navigator.preferences?.[name];
  if (!pref) throw new Error(`Einstellung "${name}" nicht verfügbar`);

  if (!pref.validValues.includes(value)) {
    throw new RangeError(
      `"${value}" ist ungültig. Erlaubt: ${pref.validValues.join(', ')}`
    );
  }
  await pref.requestOverride(value);
  return pref.override;
};

setPreference('colorScheme', 'sepia').catch((e) => console.log(e.message));

"sepia" ist ungültig. Erlaubt: light, dark

// Wichtig · Fallstricke

Experimentelle API: navigator.preferences gibt es bisher nur in Chromium-basierten Browsern, teils nur hinter einem Flag oder als Origin Trial. Prüfe deshalb immer zuerst mit 'preferences' in navigator, ob die API vorhanden ist, und biete einen Ersatzweg an (etwa eigene CSS-Klassen plus localStorage).
Das Array ist eingefroren: push() oder direkte Zuweisungen wirken nicht und lösen im Strict Mode einen TypeError aus. Wenn du die Werte ändern willst, arbeite mit einer Kopie ([...pref.validValues]).
validValues sagt nichts über die tatsächliche Systemeinstellung des Nutzers aus. Den gesetzten Überschreibungswert liefert override, den tatsächlich wirksamen Zustand ermittelst du mit matchMedia().
Die Liste kann je nach Einstellung und Browser-Version unterschiedlich ausfallen. Schreibe Werte deshalb nicht fest in den Code, sondern lies sie zur Laufzeit aus.

Siehe auch

Navigator.preferences PerformanceScriptTiming.invoker PreferenceObject.value StorageEvent.oldValue Element.ariaValueMax