Intl.ListFormat.prototype.format() — Methode · JavaScript-Referenz

Signatur

Intl.ListFormat.prototype.format(list)

Beschreibung

Die Methode format() einer Intl.ListFormat-Instanz verbindet die Elemente einer Liste zu einem lesbaren Satzteil, wie man ihn in der jeweiligen Sprache schreiben würde. Trennzeichen, Konjunktionen („und“, „oder“) und Sonderregeln wie das Oxford-Komma im Englischen oder das spanische „y“/„e“ werden automatisch berücksichtigt.

Wie die Liste formatiert wird, legen Sie beim Erzeugen des Formatierers fest: über die Locale sowie die Optionen type ("conjunction", "disjunction", "unit") und style ("long", "short", "narrow"). format() selbst nimmt nur noch die Liste entgegen. Deshalb lohnt es sich, einen Formatierer einmal zu erzeugen und dann mehrfach zu verwenden.

Einsetzen sollten Sie die Methode überall, wo Listen in Benutzeroberflächen angezeigt werden: ausgewählte Filter, Teilnehmende einer Unterhaltung, fehlende Pflichtfelder oder Maßangaben wie „5 Fuß, 3 Zoll“. Das ersetzt fehleranfällige Eigenbauten mit join(", ") und Sonderfällen für das letzte Element.

Parameter

Name	Typ	Default	Beschreibung
$list	Iterable<string>	[] (leere Liste)	Ein iterierbares Objekt (z. B. `Array` oder `Set`), dessen Elemente alle Strings sein müssen. Fehlt das Argument, wird ein leerer String zurückgegeben.

Rückgabewert

Typ

string

Beschreibung

Ein sprachspezifisch formatierter String mit allen Listenelementen. Bei einer leeren Liste ist das Ergebnis "", bei einem einzelnen Element das Element selbst.

Beispiele

Aufzählung mit „und“ und „oder“

const obst = ['Äpfel', 'Birnen', 'Kirschen'];

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

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

Äpfel, Birnen und Kirschen Äpfel, Birnen oder Kirschen

Vergleich verschiedener Sprachen

const namen = ['Anna', 'Ben', 'Clara'];

for (const locale of ['de', 'en', 'es', 'ja']) {
  const lf = new Intl.ListFormat(locale, { type: 'conjunction' });
  console.log(`${locale}: ${lf.format(namen)}`);
}

de: Anna, Ben und Clara en: Anna, Ben, and Clara es: Anna, Ben y Clara ja: Anna、Ben、Clara

Fehlende Pflichtfelder im Formular melden

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

const formular = { name: '', email: 'max@example.com', plz: '', ort: '' };
const labels = { name: 'Name', email: 'E-Mail', plz: 'PLZ', ort: 'Ort' };

const fehlend = Object.entries(formular)
  .filter(([, wert]) => wert.trim() === '')
  .map(([feld]) => labels[feld]);

if (fehlend.length > 0) {
  console.log(`Bitte ausfüllen: ${listFormat.format(fehlend)}.`);
}

Bitte ausfüllen: Name, PLZ und Ort.

Maßeinheiten und Set als Eingabe

const einheiten = new Intl.ListFormat('en', { type: 'unit', style: 'narrow' });
console.log(einheiten.format(['5 ft', '3 in']));

// Jedes Iterable funktioniert, auch ein Set
const tags = new Set(['JavaScript', 'CSS', 'HTML']);
const kurz = new Intl.ListFormat('de', { style: 'short' });
console.log(kurz.format(tags));

console.log(JSON.stringify(kurz.format([])));

5 ft 3 in JavaScript, CSS und HTML ""

// Wichtig · Fallstricke

Nur Strings erlaubt: Enthält die Liste ein Element, das kein String ist (z. B. eine Zahl, null oder ein Objekt), wirft format() einen TypeError. Wandeln Sie Zahlen vorher um, am besten mit Intl.NumberFormat: list.map(n => nf.format(n)).
Kein HTML-Escaping: Das Ergebnis ist reiner Text. Stammen die Einträge aus Benutzereingaben, geben Sie es mit textContent aus und nicht mit innerHTML, damit keine XSS-Lücke entsteht.
Ausgabe kann sich ändern: Die genaue Formatierung stammt aus den CLDR-Daten der Laufzeitumgebung und kann zwischen Browsern und Versionen leicht abweichen. Verwenden Sie die Ausgabe nicht für Stringvergleiche in Tests oder für maschinelles Parsen.
Performance: Einen Intl.ListFormat-Formatierer zu erzeugen ist vergleichsweise teuer. Erzeugen Sie ihn einmal und verwenden Sie ihn wieder, statt ihn in Schleifen oder bei jedem Rendern neu anzulegen.
Das Ergebnis weiterverarbeiten: Wenn Sie einzelne Elemente z. B. fett darstellen wollen, nutzen Sie formatToParts(). Die Methode liefert Element- und Literal-Teile getrennt.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome 72+, Firefox 78+, Safari 14.1+) sowie ab Node.js 12.11 mit vollständigen ICU-Daten. Ältere Umgebungen brauchen ein Polyfill (z. B. @formatjs/intl-listformat).

Siehe auch

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