new Intl.ListFormat() — Methode · JavaScript-Referenz

Signatur

new Intl.ListFormat(locales, options)

Beschreibung

Mit dem Konstruktor Intl.ListFormat() erzeugen Sie einen Formatierer, der ein Array von Zeichenketten als grammatikalisch korrekte Aufzählung in der gewünschten Sprache ausgibt. Die Trennzeichen und Konjunktionen passt er dabei an die Sprache an: im Deutschen „und“, im Englischen „and“ inklusive Oxford-Komma („A, B, and C“), im Spanischen „y“ bzw. „e“ vor einem i-Laut.

Nützlich ist das überall dort, wo Sie Listen in Fließtext einbauen, etwa bei ausgewählten Filtern („Rot, Grün und Blau“), bei Teilnehmerlisten, Validierungsmeldungen („Erlaubt sind PNG, JPG oder GIF“) oder bei Maßeinheiten („3 Std., 20 Min.“). Das spart fehleranfällige join()-Konstruktionen mit Sonderbehandlung für das letzte Element.

Über options.type legen Sie fest, ob die Liste als Und-Verknüpfung ("conjunction"), als Oder-Verknüpfung ("disjunction") oder als Einheitenliste ("unit") formatiert wird. options.style steuert, wie ausführlich die Ausgabe ist. Erstellen Sie die Instanz möglichst nur einmal und verwenden Sie sie dann mehrfach über format() oder formatToParts(), denn das Anlegen ist deutlich teurer als das Formatieren.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| undefined	Standard-Locale der Laufzeitumgebung	BCP-47-Sprachkennung wie `"de-DE"` oder ein Array davon, sortiert nach Priorität. Mit `undefined` wird die Locale des Systems bzw. Browsers verwendet.
$options	object	{}	Konfigurationsobjekt mit den unten beschriebenen Eigenschaften.
$options.localeMatcher	"lookup" \| "best fit"	"best fit"	Algorithmus, mit dem die passende Locale ausgewählt wird.
$options.type	"conjunction" \| "disjunction" \| "unit"	"conjunction"	`"conjunction"` ergibt eine Und-Liste, `"disjunction"` eine Oder-Liste und `"unit"` eine Liste von Maßangaben ohne Konjunktion (z. B. „5 kg, 20 g“).
$options.style	"long" \| "short" \| "narrow"	"long"	Wie ausführlich formatiert wird. `"narrow"` ist nur bei `type: "unit"` wirklich sinnvoll, dort entfallen je nach Sprache sogar die Trennzeichen.

Rückgabewert

Typ

Intl.ListFormat

Beschreibung

Eine neue Intl.ListFormat-Instanz mit den Methoden format(), formatToParts() und resolvedOptions().

Beispiele

Und- und Oder-Listen auf Deutsch

const farben = ['Rot', 'Grün', 'Blau'];

const und = new Intl.ListFormat('de', { type: 'conjunction' });
const oder = new Intl.ListFormat('de', { type: 'disjunction' });

console.log(und.format(farben));
console.log(oder.format(farben));

Rot, Grün und Blau Rot, Grün oder Blau

Sprachvergleich mit derselben Liste

const personen = ['Anna', 'Ben', 'Carla'];

for (const locale of ['de-DE', 'en-US', 'en-GB', 'es']) {
  const lf = new Intl.ListFormat(locale, { style: 'long', type: 'conjunction' });
  console.log(`${locale}: ${lf.format(personen)}`);
}

de-DE: Anna, Ben und Carla en-US: Anna, Ben, and Carla en-GB: Anna, Ben and Carla es: Anna, Ben y Carla

Einheitenliste für eine Dauer

const zahl = new Intl.NumberFormat('de', { style: 'unit', unit: 'hour', unitDisplay: 'short' });
const min = new Intl.NumberFormat('de', { style: 'unit', unit: 'minute', unitDisplay: 'short' });

const dauer = new Intl.ListFormat('de', { type: 'unit', style: 'short' });
console.log(dauer.format([zahl.format(2), min.format(15)]));

2 Std., 15 Min.

Validierungsmeldung und formatToParts()

const erlaubt = ['PNG', 'JPG', 'GIF'];
const lf = new Intl.ListFormat('de', { type: 'disjunction' });

const meldung = `Erlaubte Formate: ${lf.format(erlaubt)}.`;
console.log(meldung);

// Einzelteile, z. B. um die Elemente hervorzuheben
const html = lf.formatToParts(erlaubt)
  .map(({ type, value }) => (type === 'element' ? `<strong>${value}</strong>` : value))
  .join('');
console.log(html);

Erlaubte Formate: PNG, JPG oder GIF. PNG, JPG oder GIF

// Wichtig · Fallstricke

Nur mit new aufrufen: Ohne new wirft Intl.ListFormat() einen TypeError. Das ist anders als bei Intl.NumberFormat oder Intl.DateTimeFormat.
Nur Zeichenketten: format() nimmt ein Iterable von Strings entgegen. Zahlen oder andere Werte führen zu einem TypeError. Formatieren Sie Zahlen deshalb vorher, z. B. mit Intl.NumberFormat oder mit String().
Ungültige Optionen: Unbekannte Werte für type oder style sowie ungültige Locale-Kennungen lösen einen RangeError aus.
Ausgabe nicht fest verdrahten: Die genaue Ausgabe hängt von den CLDR-Daten der jeweiligen Engine ab und kann sich zwischen Versionen ändern. Vergleichen Sie Ergebnisse in Tests daher nicht als fest kodierte Strings über verschiedene Laufzeitumgebungen hinweg.
Leistung: Legen Sie die Instanz einmal an und verwenden Sie sie wieder, statt sie in Schleifen oder Render-Funktionen jedes Mal neu zu erzeugen.
Sicherheit: Wenn Sie Ergebnisse von formatToParts() zu HTML zusammensetzen, müssen Sie Nutzereingaben vorher escapen. Sonst droht XSS.
Kompatibilität: Chrome 72+, Firefox 78+, Safari 14.1+, Edge 79+, Node.js 12.17+ (mit vollständigen ICU-Daten). Für ältere Umgebungen gibt es das Polyfill @formatjs/intl-listformat.

Siehe auch

Intl.ListFormat Intl.ListFormat.prototype.format() Intl.ListFormat.prototype.formatToParts() Intl.ListFormat.prototype.resolvedOptions() Intl.ListFormat.supportedLocalesOf() Intl.NumberFormat Array.prototype.join()