Signatur
Beschreibung
formatToParts() erzeugt dieselbe Ausgabe wie format(), liefert sie aber in Einzelteile zerlegt. Jedes Element des Arrays ist ein Objekt mit den Eigenschaften type (z. B. "day", "month", "year", "hour", "literal") und value (der formatierte Text dieses Teils). Fügt man alle value-Werte aneinander, erhält man exakt den String von format().
Die Methode ist dann nützlich, wenn einzelne Bestandteile eines lokalisierten Datums gezielt gestaltet oder weiterverarbeitet werden sollen, zum Beispiel um den Monatsnamen fett zu setzen, Trennzeichen auszutauschen oder einzelne Werte (etwa die Stunde in einer bestimmten Zeitzone) auszulesen, ohne den formatierten String mühsam und fehleranfällig per Regex zu zerlegen.
Mögliche Werte für type sind unter anderem: era, year, relatedYear, yearName, month, day, weekday, dayPeriod, hour, minute, second, fractionalSecond, timeZoneName und literal (feste Zeichen wie Punkte, Leerzeichen oder Kommata). Welche Teile vorkommen, hängt von den Optionen des Formatierers und der Locale ab.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $date | Date | number | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.PlainTime | Temporal.Instant | … | Date.now() | Das zu formatierende Datum. Zahlen werden als Millisekunden seit der Unix-Epoche interpretiert. Fehlt der Wert (undefined), wird der aktuelle Zeitpunkt verwendet. Temporal-Objekte werden nur in Umgebungen mit Temporal-Unterstützung akzeptiert. |
Rückgabewert
value-Werte zusammengesetzt dem Ergebnis von format(date) entsprechen. Bei manchen Kalendern kann zusätzlich eine Eigenschaft source nur in formatRangeToParts() auftreten, nicht hier.Beispiele
Grundlegende Zerlegung eines deutschen Datums
const fmt = new Intl.DateTimeFormat('de-DE', {
day: '2-digit',
month: 'long',
year: 'numeric'
});
const parts = fmt.formatToParts(new Date(2024, 2, 15));
console.log(parts);Monatsnamen im HTML hervorheben
const fmt = new Intl.DateTimeFormat('de-DE', { dateStyle: 'long' });
const html = fmt
.formatToParts(new Date(2024, 11, 24))
.map(({ type, value }) =>
type === 'month' ? `<strong>${value}</strong>` : value
)
.join('');
console.log(html);Uhrzeit in einer anderen Zeitzone als Zahlen auslesen
const getTimeInZone = (date, timeZone) => {
const fmt = new Intl.DateTimeFormat('en-US', {
timeZone,
hour: '2-digit',
minute: '2-digit',
hourCycle: 'h23'
});
// Teile in ein Objekt { hour: '..', minute: '..' } umwandeln
const map = Object.fromEntries(
fmt.formatToParts(date)
.filter(p => p.type !== 'literal')
.map(p => [p.type, p.value])
);
return { hour: Number(map.hour), minute: Number(map.minute) };
};
const date = new Date(Date.UTC(2024, 5, 1, 12, 30));
console.log(getTimeInZone(date, 'Asia/Tokyo'));// Wichtig · Fallstricke
- Nicht auf Reihenfolge oder Literale verlassen: Anzahl, Reihenfolge und Inhalt der
literal-Teile hängen von Locale, Optionen und der ICU-/CLDR-Version der Engine ab und können sich zwischen Browserversionen ändern. Werte immer übertypesuchen, nicht über den Index. - Werte sind immer Strings und können je nach Locale nicht-lateinische Ziffern enthalten (z. B.
ar-EG). Zum Rechnen mitnumberingSystem: 'latn'formatieren und dann mitNumber()umwandeln. - Mit
hour12: falseliefern manche Engines für Mitternacht"24". Sicherer isthourCycle: 'h23'. - Ein ungültiges Datum (z. B.
new Date('abc')) löst einenRangeErroraus. - Der Typ
fractionalSecondist neuer (ca. 2020),relatedYear/yearNametreten nur bei Nicht-Gregorianischen Kalendern (z. B.chinese) auf. - Kompatibilität: in allen aktuellen Browsern und Node.js ab Version 8 (mit vollständigen ICU-Daten) verfügbar.