Intl.DateTimeFormat.prototype.formatToParts()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

Die Methode formatToParts() von Intl.DateTimeFormat-Instanzen gibt ein Array von Objekten zurück, das jede Komponente des formatierten Strings darstellt, der von format() zurückgegeben würde. Dies ist nützlich, um benutzerdefinierte Zeichenfolgen aus den lokalen spezifischen Token zu erstellen.

Probieren Sie es aus

const date = new Date(2012, 5);
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
const dateTimeFormat = new Intl.DateTimeFormat("en-US", options);

const parts = dateTimeFormat.formatToParts(date);
const partValues = parts.map((p) => p.value);

console.log(partValues);
// Expected output: "["Friday", ", ", "June", " ", "1", ", ", "2012"]"

Syntax

js
formatToParts(date)

Parameter

date Optional

Das zu formatierende Datum. Kann ein Date- oder Temporal.PlainDateTime-Objekt sein. Zusätzlich kann es ein Temporal.PlainTime, Temporal.PlainDate, Temporal.PlainYearMonth, oder Temporal.PlainMonthDay-Objekt sein, falls das DateTimeFormat-Objekt so konfiguriert wurde, dass mindestens ein relevanter Teil des Datums dargestellt wird.

Hinweis: Ein Temporal.ZonedDateTime-Objekt führt immer zu einem TypeError. Verwenden Sie stattdessen Temporal.ZonedDateTime.prototype.toLocaleString() oder konvertieren Sie es in ein Temporal.PlainDateTime-Objekt.

Wird es weggelassen, wird das aktuelle Datum (wie durch Date.now() zurückgegeben) formatiert, was leicht verwirrend sein kann. Es wird daher empfohlen, immer explizit ein Datum zu übergeben.

Rückgabewert

Ein Array aus Objekten, die das formatierte Datum in Teile aufteilen. Jedes Objekt hat zwei Eigenschaften, type und value, die jeweils eine Zeichenfolge enthalten. Die Verkettung der value-Zeichenfolgen in der bereitgestellten Reihenfolge ergibt dieselbe Zeichenfolge wie format(). Der type kann einer der Datum-Zeit-Komponenten sein:

weekday

Zum Beispiel "M", "Monday" oder "Montag".

era

Zum Beispiel "BC" oder "AD".

year

Zum Beispiel "2012" oder "96".

month

Zum Beispiel "12" oder "January".

day

Zum Beispiel "17".

dayPeriod

Zum Beispiel "AM", "PM", "in the morning" oder "noon".

hour

Zum Beispiel "3" oder "03".

minute

Zum Beispiel "00".

second

Zum Beispiel "07" oder "42".

fractionalSecond

Zum Beispiel "0", "00" oder "000".

timeZoneName

Zum Beispiel "UTC", "CET" oder "Central European Time".

Der type kann auch einer der folgenden sein:

literal

Jede Zeichenfolge, die Teil des Formatmusters ist und nicht vom date beeinflusst wird, z. B. "/", ", ", "o'clock", "de", " ", usw.

relatedYear

Ein 4-stelliges gregorianisches Jahr, falls die Darstellung des Kalenders eher ein yearName anstelle eines Jahres wäre, beispielsweise "2019". Siehe benannte Jahre für weitere Details.

yearName

Der Name, der dem Jahr zugeordnet ist, normalerweise in Kalendern ohne das Konzept kontinuierlicher Jahre, z. B. "geng-zi".

unknown

Reserviert für jedes Token, das nicht als eines der oben genannten erkannt wird; sollte selten vorkommen.

Beispiele

Verwendung von formatToParts()

Die format()-Methode liefert lokalisierte, undurchsichtige Zeichenfolgen, die nicht direkt manipuliert werden können:

js
const date = Date.UTC(2012, 11, 17, 3, 0, 42);

const formatter = new Intl.DateTimeFormat("en-us", {
  weekday: "long",
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  fractionalSecondDigits: 3,
  hour12: true,
  timeZone: "UTC",
});

formatter.format(date);
// "Monday, 12/17/2012, 3:00:42.000 AM"

Jedoch möchten Sie in vielen Benutzeroberflächen möglicherweise die Formatierung dieses Strings anpassen oder sie mit anderem Text kombinieren. Die formatToParts()-Methode liefert dieselben Informationen in Einzelteilen:

js
formatter.formatToParts(date);

// return value:
[
  { type: "weekday", value: "Monday" },
  { type: "literal", value: ", " },
  { type: "month", value: "12" },
  { type: "literal", value: "/" },
  { type: "day", value: "17" },
  { type: "literal", value: "/" },
  { type: "year", value: "2012" },
  { type: "literal", value: ", " },
  { type: "hour", value: "3" },
  { type: "literal", value: ":" },
  { type: "minute", value: "00" },
  { type: "literal", value: ":" },
  { type: "second", value: "42" },
  { type: "fractionalSecond", value: "000" },
  { type: "literal", value: " " },
  { type: "dayPeriod", value: "AM" },
];

Nun sind die Informationen separat verfügbar und können auf benutzerdefinierte Weise formatiert und erneut verknüpft werden. Zum Beispiel durch Verwendung von Array.prototype.map(), Pfeilfunktionen, einer switch-Anweisung, Template-Literals und Array.prototype.join(), um zusätzliche Markups für bestimmte Komponenten einzufügen.

js
const dateString = formatter
  .formatToParts(date)
  .map(({ type, value }) => {
    switch (type) {
      case "dayPeriod":
        return `<em>${value}</em>`;
      default:
        return value;
    }
  })
  .join("");

console.log(dateString);
// "Monday, 12/17/2012, 3:00:42.000 <em>AM</em>"

Benannte Jahre

Einige Kalender verwenden benannte Jahre. Beispielsweise nutzen der chinesische und tibetische Kalender einen 60-jährigen Sexagesimalzyklus benannter Jahre. Diese Kalender haben keine universelle Methode, jedes Jahr eindeutig zu nummerieren, sodass Jahre durch Beziehung zu den entsprechenden Jahren im Gregorianischen Kalender unterschieden werden. In diesem Fall wird, wenn das DateTimeFormat so konfiguriert ist, dass die Jahreskomponente ausgegeben wird, ein Token für relatedYear anstelle von year ausgegeben.

js
const df = new Intl.DateTimeFormat("zh-u-ca-chinese");
df.formatToParts(Date.UTC(2012, 11, 17, 3, 0, 42));

// return value:
[
  { type: "relatedYear", value: "2012" },
  { type: "literal", value: "年" },
  { type: "month", value: "十一月" },
  { type: "day", value: "4" },
];

Manchmal führt die Kombination von Datum-Zeit-Komponentenoptionen zu einem Format, das auch ein yearName enthält. Es gibt keine separate Option, die steuert, ob yearName angezeigt wird oder nicht. Zum Beispiel führt die folgende Einstellung von month auf "long" zu einem yearName-Token, obwohl year weiterhin "numeric" ist:

js
const opts = { year: "numeric", month: "long", day: "numeric" };
const df = new Intl.DateTimeFormat("zh-u-ca-chinese", opts);
df.formatToParts(Date.UTC(2012, 11, 17, 3, 0, 42));

// return value:
[
  { type: "relatedYear", value: "2012" },
  { type: "yearName", value: "壬辰" },
  { type: "literal", value: "年" },
  { type: "month", value: "十一月" },
  { type: "day", value: "4" },
];

Da format() einfach alle value-Zeichenfolgen zusammenfügt, sehen Sie in diesem Fall sowohl das gregorianische Jahr als auch den Jahrnamen in der Ausgabe.

Spezifikationen

Specification
ECMAScript® 2025 Internationalization API Specification
# sec-Intl.DateTimeFormat.prototype.formatToParts

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
formatToParts

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
See implementation notes.

Siehe auch