Intl.NumberFormat.prototype.formatRange() — Methode · JavaScript-Referenz

Signatur

Intl.NumberFormat.prototype.formatRange(startRange, endRange)

Beschreibung

formatRange() gibt einen Zahlenbereich als einen String zurück, der zur Sprache passt. Dafür gelten die Locale und die Optionen, mit denen die Intl.NumberFormat-Instanz erstellt wurde. Die Methode verwendet den Bereichs-Trenner der jeweiligen Sprache (im Deutschen meist einen Halbgeviertstrich –). Doppelte Teile wie Währungssymbol oder Einheit werden nach Möglichkeit nur einmal ausgegeben. Aus 3 bis 5 in Euro wird also 3–5 € und nicht 3 € – 5 €.

Sinnvoll ist das überall, wo Preisspannen, Mengenbereiche oder Messwert-Intervalle angezeigt werden, etwa in Filterleisten, Produktlisten oder Diagrammbeschriftungen. Wenn Sie zwei einzeln formatierte Zahlen selbst zusammensetzen, stimmen Trenner, Leerzeichen und Symbol-Position oft nicht mit den Regeln der Sprache überein. formatRange() erledigt das korrekt.

Sind beide Werte nach dem Runden gleich (z. B. 2.9 und 3.1 bei maximumFractionDigits: 0), gibt die Methode keinen Bereich aus. Sie zeigt dann einen Näherungswert mit Tilde, etwa ~3 €. Brauchen Sie die einzelnen Bestandteile, zum Beispiel zum Gestalten, verwenden Sie formatRangeToParts().

Parameter

Name	Typ	Default	Beschreibung
$startRange Pflicht	number \| bigint \| string		Anfangswert des Bereichs. Strings werden als exakte Dezimalzahl gelesen, ohne Genauigkeitsverlust wie bei `number`.
$endRange Pflicht	number \| bigint \| string		Endwert des Bereichs. Es gelten dieselben Typen wie bei `startRange`.

Rückgabewert

Typ

string

Beschreibung

Der formatierte Zahlenbereich als String, z. B. "3–5 €" oder, wenn beide Werte nach dem Runden gleich sind, ein Näherungswert wie "~3 €".

Beispiele

Preisspanne in Euro

const preis = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
  maximumFractionDigits: 0,
});

console.log(preis.formatRange(3, 5));
console.log(preis.formatRange(2.9, 3.1)); // gerundet gleich -> Näherungswert

3–5 € ~3 €

Vergleich verschiedener Locales

const opts = { style: 'currency', currency: 'USD', maximumFractionDigits: 0 };

for (const locale of ['en-US', 'de-DE', 'ja-JP']) {
  const nf = new Intl.NumberFormat(locale, opts);
  console.log(locale, nf.formatRange(100, 250));
}

en-US $100 – $250 de-DE 100–250 $ ja-JP $100～$250

Entfernungsbereich mit Einheit für einen Filter

const km = new Intl.NumberFormat('de-DE', {
  style: 'unit',
  unit: 'kilometer',
  unitDisplay: 'short',
});

const filter = { min: 5, max: 12.5 };
const label = `Umkreis: ${km.formatRange(filter.min, filter.max)}`;
console.log(label);

Umkreis: 5–12,5 km

Große Werte exakt als String oder BigInt

const nf = new Intl.NumberFormat('de-DE');

// Strings und BigInt werden ohne Rundungsfehler verarbeitet
console.log(nf.formatRange('9007199254740993', 9007199254740995n));

9.007.199.254.740.993–9.007.199.254.740.995

// Wichtig · Fallstricke

Fehler: Wird ein Argument weggelassen oder ist undefined, wirft die Methode einen TypeError. Ist ein Wert NaN, wirft sie einen RangeError.
Umgekehrte Bereiche: Frühe Entwürfe und ältere Engines warfen einen RangeError, wenn startRange > endRange war. Nach der endgültigen Spezifikation ist das erlaubt. Prüfen Sie die Reihenfolge besser selbst, wenn Sie ältere Umgebungen unterstützen müssen.
Ausgabe nicht fest verdrahten: Trenner, Leerzeichen (oft geschützte oder schmale Leerzeichen) und Symbol-Position hängen von den CLDR-Daten der Engine ab. Sie können sich zwischen Browsern und Versionen ändern. Vergleichen Sie Ausgaben in Tests deshalb nicht Zeichen für Zeichen.
Kompatibilität: Die Methode ist erst seit ES2023 verfügbar (Chrome/Edge 106, Firefox 116, Safari 15.4, Node.js 19). Für ältere Umgebungen prüfen Sie vorher mit typeof Intl.NumberFormat.prototype.formatRange === 'function' und greifen sonst auf zwei format()-Aufrufe zurück.
Performance: Legen Sie die Intl.NumberFormat-Instanz einmal an und verwenden Sie sie mehrfach, statt sie in Schleifen neu zu erzeugen.

Siehe auch

Intl.NumberFormat Intl.NumberFormat.prototype.format() Intl.NumberFormat.prototype.formatRangeToParts() Intl.NumberFormat.prototype.formatToParts() Intl.DateTimeFormat.prototype.formatRange() Number.prototype.toLocaleString()