Intl.DateTimeFormat.prototype.formatToParts()

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

formatToParts(date)

Parameter

date Optional

Das zu formatierende Datum. Kann ein Date oder Temporal.PlainDateTime-Objekt sein. Darüber hinaus kann es sich um ein Temporal.PlainTime, Temporal.PlainDate, Temporal.PlainYearMonth oder Temporal.PlainMonthDay-Objekt handeln, wenn das DateTimeFormat-Objekt so konfiguriert wurde, dass es mindestens einen relevanten Teil des Datums druckt.

Hinweis: Ein Temporal.ZonedDateTime-Objekt wird immer einen TypeError auslösen; verwenden Sie stattdessen Temporal.ZonedDateTime.prototype.toLocaleString() oder konvertieren Sie es in ein Temporal.PlainDateTime-Objekt.

Wenn es weggelassen wird, wird das aktuelle Datum formatiert (wie von Date.now() zurückgegeben), was etwas verwirrend sein könnte. Daher ist es ratsam, immer explizit ein Datum zu übergeben.

Rückgabewert

Ein Array von Objekten, die das formatierte Datum in Teilen enthalten. Jedes Objekt hat zwei Eigenschaften, type und value, die jeweils einen String enthalten. Die string-Verkettung von value in der angegebenen Reihenfolge ergibt denselben String wie format(). Der type kann einer der Datums-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

Jeder String, der Teil des Formatmusters ist und nicht vom date beeinflusst wird; zum Beispiel "/", ", ", "o'clock", "de", " ", usw.

relatedYear

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

yearName

Der dem Jahr gegebene Name, normalerweise in Kalendern ohne das Konzept von kontinuierlichen Jahren; zum Beispiel "geng-zi".

unknown

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

Beispiele

Verwendung von formatToParts()

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

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 jedoch die Formatierung dieses Strings anpassen oder ihn mit anderen Texten verweben. Die formatToParts()-Methode erzeugt dieselben Informationen in Teilen:

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 in benutzerdefinierter Weise formatiert und wieder verknüpft werden. Zum Beispiel durch die Verwendung von Array.prototype.map(), Pfeilfunktionen, einer switch-Anweisung, Template Literals und Array.prototype.join(), um zusätzlichen Markup für bestimmte Komponenten einzufügen.

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; zum Beispiel verwenden die chinesischen und tibetischen Kalender einen 60-jährigen Sexagenariuszyklus von benannten Jahren. Diese Kalender haben keine universelle Methode, um jedes Jahr eindeutig zu nummerieren, sodass Jahre durch die Beziehung zu den entsprechenden Jahren im gregorianischen Kalender unterschieden werden. In diesem Fall wird, wenn das DateTimeFormat so konfiguriert ist, dass es die Jahreskomponente ausgibt, ein Token für relatedYear anstelle von year ausgegeben.

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 Datums-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 werden im folgenden Beispiel die Optionen month auf "long" gesetzt und führen zu einem yearName-Token, obwohl year noch auf "numeric" steht:

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-Strings zusammenfügt, sehen Sie in diesem Fall das gregorianische Jahr und den Jahrnamen zusammen im Ausgabe.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Intl.DateTimeFormat
• Intl.DateTimeFormat.prototype.format()