Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten. Erfahre mehr über dieses Experiment.

View in English Always switch to English

Intl.DateTimeFormat.prototype.formatToParts()

Baseline
Weitgehend verfügbar

Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Oktober 2018 browserübergreifend verfügbar.

Die Methode formatToParts() von Intl.DateTimeFormat-Instanzen gibt ein Array von Objekten zurück, die jeweils einen Teil der formatierten Zeichenfolge darstellen, die format() zurückgeben würde. Sie ist nützlich, um aus gebietsschemaspezifischen Bestandteilen eigene Zeichenfolgen zusammenzusetzen.

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: Array ["Friday", ", ", "June", " ", "1", ", ", "2012"]

Syntax

js
formatToParts(date)

Parameter

date Optional

Das zu formatierende Datum. Dies kann ein Date- oder Temporal.PlainDateTime-Objekt sein. Es kann auch ein Temporal.PlainTime-, Temporal.PlainDate-, Temporal.PlainYearMonth- oder Temporal.PlainMonthDay-Objekt sein, sofern das DateTimeFormat-Objekt so konfiguriert wurde, dass es mindestens einen für das jeweilige Objekt relevanten Bestandteil ausgibt.

Hinweis: Bei einem Temporal.ZonedDateTime-Objekt wird immer ein TypeError ausgelöst. Verwenden Sie stattdessen Temporal.ZonedDateTime.prototype.toLocaleString() oder konvertieren Sie es in ein Temporal.PlainDateTime-Objekt.

Wenn Sie date weglassen, wird das aktuelle Datum formatiert (wie von Date.now() zurückgegeben). Da dies verwirrend sein kann, empfiehlt es sich, ein Datum immer ausdrücklich anzugeben.

Rückgabewert

Ein Array von Objekten, die jeweils einen Teil des formatierten Datums enthalten. Jedes Objekt hat die beiden Eigenschaften type und value, die jeweils eine Zeichenfolge enthalten. Werden die value-Zeichenfolgen in der angegebenen Reihenfolge verkettet, ergibt sich dieselbe Zeichenfolge wie bei format(). type kann eine der folgenden Datum-Uhrzeit-Komponenten sein:

weekday

Zum Beispiel "T", "Tuesday" oder "Dienstag".

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".

type kann auch einen der folgenden Werte haben:

literal

Eine beliebige Zeichenfolge, die Teil des Formatmusters ist und nicht von date beeinflusst wird, zum Beispiel "/", ", ", "o'clock", "de" oder " ".

relatedYear

Eine vierstellige gregorianische Jahreszahl, falls der Kalender statt einer Jahreszahl einen yearName verwendet, zum Beispiel "2019". Weitere Informationen finden Sie unter Benannte Jahre.

yearName

Der Name des Jahres, üblicherweise in Kalendern ohne fortlaufende Jahreszählung, zum Beispiel "geng-zi".

unknown

Reserviert für Bestandteile, die keiner der obigen Kategorien zugeordnet werden können; sollte nur selten vorkommen.

Beispiele

formatToParts() verwenden

Die Methode format() gibt lokalisierte Zeichenfolgen zurück, deren Bestandteile sich nicht direkt bearbeiten lassen:

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"

In vielen Benutzeroberflächen möchten Sie die Formatierung dieser Zeichenfolge jedoch anpassen oder sie mit anderem Text kombinieren. Die Methode formatToParts() gibt dieselben Informationen in einzelnen Teilen zurück:

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: "literal", value: "." },
  { type: "fractionalSecond", value: "000" },
  { type: "literal", value: " " },
  { type: "dayPeriod", value: "AM" },
];

Die Informationen liegen nun getrennt vor und können auf eigene Weise formatiert und wieder zusammengesetzt werden. Beispielsweise können Sie mit Array.prototype.map(), Pfeilfunktionen, einer switch-Anweisung, Template-Literalen und Array.prototype.join() zusätzliche Auszeichnung für bestimmte Bestandteile einfü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. Der chinesische und der tibetische Kalender verwenden beispielsweise einen 60-jährigen Sexagesimalzyklus benannter Jahre. In diesen Kalendern gibt es keine allgemeingültige Möglichkeit, jedes Jahr eindeutig zu nummerieren. Daher werden die Jahre anhand ihrer Zuordnung zu den entsprechenden Jahren des gregorianischen Kalenders unterschieden. Ist DateTimeFormat so konfiguriert, dass die Jahreskomponente ausgegeben wird, wird in diesem Fall relatedYear statt 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 entspricht die Kombination der Optionen für Datum-Uhrzeit-Komponenten einem Format, das auch einen yearName enthält. Es gibt keine separate Option, mit der sich die Anzeige von yearName steuern lässt. Die folgenden Optionen setzen beispielsweise month auf "long" und führen zu einem yearName-Bestandteil, obwohl year weiterhin auf "numeric" gesetzt 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() lediglich alle value-Zeichenfolgen verkettet, erscheinen in diesem Fall sowohl das gregorianische Jahr als auch der Jahresname in der Ausgabe.

Spezifikationen

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

Browser-Kompatibilität

Siehe auch