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

Signatur

Intl.DateTimeFormat.prototype.formatRange(startDate, endDate)

Beschreibung

formatRange() gibt einen Zeitraum aus, etwa „10.–14. März 2024“, und nicht zwei vollständige Datumsangaben hintereinander. Die Methode prüft, welche Teile beider Datumswerte gleich sind (Jahr, Monat, Tag, Tageszeit), und schreibt diese Teile nur einmal. Trennzeichen, Reihenfolge und Abkürzungen hängen vom Gebietsschema ab, das beim Erzeugen der Intl.DateTimeFormat-Instanz angegeben wurde.

Typische Einsatzfälle:

Veranstaltungszeiträume, z. B. Konferenzen, Urlaube oder Buchungen
Öffnungszeiten und Termine innerhalb eines Tages, z. B. „09:00–10:30“
Berichtszeiträume in Dashboards, z. B. „Januar–März 2024“

Die Ausgabe richtet sich nach den Optionen der Instanz, zum Beispiel dateStyle, timeStyle, month, hour oder timeZone. Wenn beide Datumswerte in allen angezeigten Feldern übereinstimmen, liefert die Methode dasselbe Ergebnis wie format(). Ein Bindestrich erscheint dann nicht.

Wenn du die einzelnen Bestandteile getrennt gestalten willst, etwa Start- und Enddatum unterschiedlich hervorheben, nimm stattdessen formatRangeToParts().

Parameter

Name	Typ	Default	Beschreibung
$startDate Pflicht	Date \| number		Beginn des Zeitraums als `Date`-Objekt oder als Zeitstempel in Millisekunden. In neueren Umgebungen sind auch `Temporal`-Objekte erlaubt.
$endDate Pflicht	Date \| number		Ende des Zeitraums, im selben Format wie `startDate`.

Rückgabewert

Typ

string

Beschreibung

Der formatierte Zeitraum als String. Die Schreibweise hängt vom Gebietsschema ab, und gemeinsame Teile beider Datumswerte werden zusammengefasst.

Beispiele

Mehrtägige Veranstaltung ausgeben

const fmt = new Intl.DateTimeFormat('de-DE', {
  day: 'numeric',
  month: 'long',
  year: 'numeric'
});

const start = new Date(2024, 2, 10);
const ende = new Date(2024, 2, 14);

console.log(fmt.formatRange(start, ende));
// Monatsübergreifend
console.log(fmt.formatRange(start, new Date(2024, 3, 14)));
// Jahresübergreifend
console.log(fmt.formatRange(start, new Date(2025, 3, 14)));

10.–14. März 2024 10. März – 14. April 2024 10. März 2024 – 14. April 2025

Termin innerhalb eines Tages

const terminFmt = new Intl.DateTimeFormat('de-DE', {
  dateStyle: 'medium',
  timeStyle: 'short'
});

const beginn = new Date(2024, 2, 10, 9, 0);
const schluss = new Date(2024, 2, 10, 10, 30);

console.log(terminFmt.formatRange(beginn, schluss));

10.03.2024, 09:00–10:30

Gleiche Datumswerte und Zeitstempel

const fmt = new Intl.DateTimeFormat('de-DE', { dateStyle: 'long' });
const tag = Date.UTC(2024, 0, 15, 12);

// Zeitstempel (number) statt Date-Objekt
// Stimmen alle angezeigten Felder überein, entspricht das Ergebnis format()
console.log(fmt.formatRange(tag, tag + 60 * 60 * 1000));
console.log(fmt.format(tag));

15. Januar 2024 15. Januar 2024

Fehlerbehandlung bei ungültigen Eingaben

const fmt = new Intl.DateTimeFormat('de-DE');

const sicherFormatieren = (von, bis) => {
  try {
    return fmt.formatRange(von, bis);
  } catch (err) {
    return `${err.name}: ungültiger Zeitraum`;
  }
};

console.log(sicherFormatieren(new Date(2024, 0, 1)));          // endDate fehlt
console.log(sicherFormatieren(new Date('kaputt'), new Date())); // Invalid Date

TypeError: ungültiger Zeitraum RangeError: ungültiger Zeitraum

// Wichtig · Fallstricke

Pflichtargumente: Fehlt eines der beiden Argumente oder ist es undefined, wirft die Methode einen TypeError. Anders als bei format() wird dann nicht das aktuelle Datum verwendet.
Ungültige Datumswerte: Ein Invalid Date oder NaN führt zu einem RangeError.
Endet vor dem Start: Frühe Umsetzungen (ES2021) warfen einen RangeError, wenn endDate vor startDate lag. Diese Prüfung wurde später aus der Spezifikation entfernt. Ältere Umgebungen verhalten sich daher anders als neue. Prüfe die Reihenfolge am besten selbst.
Ausgabe nicht fest: Die genaue Form hängt von den CLDR-Daten ab, die der Browser oder Node.js mitbringt. Beispiele sind Halbgeviertstrich (–) oder Bindestrich, schmale Leerzeichen und Abkürzungen. Vergleiche die Ergebnisse in Tests deshalb nicht mit festen Strings, und werte sie nicht maschinell aus.
Zeitzone: Ob zwei Zeitpunkte auf denselben Tag fallen, hängt von der Option timeZone ab. Ohne diese Option gilt die Zeitzone des Systems.
Kompatibilität: Chrome 76+, Firefox 91+, Safari 14.1+, Node.js 12.9+. Für sehr alte Umgebungen gibt es einen Polyfill unter @formatjs/intl-datetimeformat.

Siehe auch

Intl.DateTimeFormat.prototype.formatRangeToParts() Intl.DateTimeFormat.prototype.format() Intl.DateTimeFormat.prototype.formatToParts() Intl.DateTimeFormat Intl.RelativeTimeFormat Date.prototype.toLocaleDateString()