Intl.supportedValuesOf() — Methode · JavaScript-Referenz

Signatur

Intl.supportedValuesOf(key)

Beschreibung

Intl.supportedValuesOf() ist eine statische Methode des Namensraums Intl. Mit ihr fragen Sie ab, welche Werte die jeweilige Umgebung (Browser, Node.js, Deno …) für eine bestimmte Kategorie von Internationalisierungs-Optionen kennt. Sie erhalten ein alphabetisch sortiertes Array ohne Duplikate, z. B. alle unterstützten ISO-4217-Währungscodes oder alle IANA-Zeitzonen.

Typische Einsatzfälle:

Auswahllisten befüllen, etwa ein Zeitzonen- oder Währungs-Dropdown in Einstellungsdialogen, ohne eigene statische Listen pflegen zu müssen.
Feature-Erkennung: prüfen, ob z. B. der Kalender "islamic-umalqura" oder die Einheit "kilometer-per-hour" verfügbar ist, bevor Sie ihn an Intl.DateTimeFormat oder Intl.NumberFormat übergeben.
Validierung von Benutzereingaben, etwa bei gespeicherten Profilwerten wie der bevorzugten Zeitzone.

Das Ergebnis hängt von der Implementierung und den mitgelieferten ICU-Daten ab. Es kann sich daher zwischen Browsern, Browser-Versionen und Node.js-Builds (z. B. small-icu gegenüber full-icu) unterscheiden. Die Methode liefert die Werte ohne Bezug zu einer bestimmten Locale.

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	"calendar" \| "collation" \| "currency" \| "numberingSystem" \| "timeZone" \| "unit"		Die Kategorie, deren unterstützte Werte zurückgegeben werden sollen: `"calendar"` (Kalender), `"collation"` (Sortierregeln), `"currency"` (ISO-4217-Codes), `"numberingSystem"` (Zahlensysteme), `"timeZone"` (IANA-Zeitzonen) oder `"unit"` (einfache Maßeinheiten für `Intl.NumberFormat`). Groß- und Kleinschreibung werden unterschieden.

Rückgabewert

Typ

string[]

Beschreibung

Ein neues, aufsteigend sortiertes Array mit eindeutigen Zeichenketten, die die unterstützten Werte der angegebenen Kategorie darstellen. Bei einem ungültigen key wird ein RangeError ausgelöst.

Beispiele

Unterstützte Werte je Kategorie abfragen

const keys = ['calendar', 'collation', 'currency', 'numberingSystem', 'timeZone', 'unit'];

for (const key of keys) {
  const values = Intl.supportedValuesOf(key);
  console.log(`${key}: ${values.length} Werte, z. B. ${values.slice(0, 3).join(', ')}`);
}

calendar: 17 Werte, z. B. buddhist, chinese, coptic collation: 10 Werte, z. B. compat, emoji, eor currency: 300 Werte, z. B. AED, AFN, ALL numberingSystem: 90 Werte, z. B. adlm, ahom, arab timeZone: 420 Werte, z. B. Africa/Abidjan, Africa/Accra, Africa/Addis_Ababa unit: 45 Werte, z. B. acre, bit, byte (die Anzahl hängt von der Umgebung ab)

Zeitzonen-Auswahlliste mit lokalisierten Namen befüllen

const select = document.querySelector('#timezone');
const current = Intl.DateTimeFormat().resolvedOptions().timeZone;

const formatName = (timeZone) =>
  new Intl.DateTimeFormat('de-DE', { timeZone, timeZoneName: 'longGeneric' })
    .formatToParts(new Date())
    .find((part) => part.type === 'timeZoneName')?.value ?? timeZone;

for (const tz of Intl.supportedValuesOf('timeZone')) {
  const option = new Option(`${tz} (${formatName(tz)})`, tz);
  option.selected = tz === current;
  select.append(option);
}

Verfügbarkeit prüfen und sicher formatieren

const isSupported = (key, value) => {
  if (typeof Intl.supportedValuesOf !== 'function') return false;
  return Intl.supportedValuesOf(key).includes(value);
};

const unit = isSupported('unit', 'kilometer-per-hour') ? 'kilometer-per-hour' : null;
const speed = 88.5;

const text = unit
  ? new Intl.NumberFormat('de-DE', { style: 'unit', unit }).format(speed)
  : `${speed} km/h`;

console.log(text);
console.log(isSupported('currency', 'EUR'));
console.log(isSupported('calendar', 'klingonisch'));

88,5 km/h true false

Ungültigen Schlüssel abfangen

try {
  Intl.supportedValuesOf('language');
} catch (error) {
  console.log(error instanceof RangeError, error.name);
}

true RangeError

// Wichtig · Fallstricke

Ungültiger Schlüssel: Alles außer den sechs dokumentierten Werten (auch "timezone" in Kleinschreibung oder "locale") löst einen RangeError aus.
Ergebnis hängt von der Umgebung ab: Anzahl und Inhalt der Werte unterscheiden sich je nach Engine und ICU-Version. Node.js-Builds mit small-icu liefern teils deutlich weniger Daten. Verlassen Sie sich nicht auf eine feste Länge oder Reihenfolge über Umgebungen hinweg.
Zeitzonen: Zurückgegeben werden nur kanonische IANA-Bezeichner. Veraltete Aliase wie "Asia/Calcutta" fehlen oft, obwohl Intl.DateTimeFormat sie akzeptiert. Ob "UTC" in der Liste steht, war zwischen Implementierungen lange uneinheitlich. Prüfen Sie Zeitzonen deshalb besser zusätzlich, indem Sie new Intl.DateTimeFormat(undefined, { timeZone }) in einem try-Block aufrufen.
Sortierungen: Die Werte "standard" und "search" gibt die Methode laut Spezifikation nicht zurück, weil sie nicht über den co-Unicode-Erweiterungsschlüssel ausgewählt werden sollen.
Einheiten: Die Liste enthält nur einfache Einheiten. Zusammengesetzte Einheiten wie "kilometer-per-hour" sind trotzdem erlaubt, solange beide Bestandteile unterstützt werden. includes() auf der Liste schlägt für sie daher fehl, obwohl die Formatierung funktioniert.
Performance: Jeder Aufruf erzeugt ein neues Array (bei Zeitzonen mehrere hundert Einträge). Speichern Sie das Ergebnis bei häufigen Prüfungen zwischen, z. B. in einem Set.
Kompatibilität: Verfügbar ab Chrome/Edge 99, Firefox 93, Safari 15.4 und Node.js 18. In älteren Umgebungen vorher mit typeof Intl.supportedValuesOf === 'function' prüfen.

Siehe auch

Intl Intl.getCanonicalLocales() Intl.DateTimeFormat Intl.NumberFormat Intl.Collator Intl.Locale Intl.DateTimeFormat.prototype.resolvedOptions()