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. Zusätzlich kann es ein Temporal.PlainTime, Temporal.PlainDate, Temporal.PlainYearMonth oder Temporal.PlainMonthDay-Objekt sein, wenn das DateTimeFormat-Objekt konfiguriert wurde, um mindestens einen relevanten Teil des Datums auszugeben.

Hinweis: Ein Temporal.ZonedDateTime-Objekt wird immer einen TypeError werfen; 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 wird empfohlen, immer explizit ein Datum zu übergeben.

Rückgabewert

Ein Array von Objekten, das das formatierte Datum in Teilen enthält. Jedes Objekt hat zwei Eigenschaften, type und value, die jeweils einen String enthalten. Die Stringverkettung von value, in der angegebenen Reihenfolge, führt zu demselben String wie format(). Der type kann einer der date-time components 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 named years für weitere Details.

yearName

Der dem Jahr gegebene Name, normalerweise in Kalendern ohne das Konzept kontinuierlicher Jahre; 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 gibt lokalisierte, undurchsichtige Strings aus, 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 möglicherweise das Format dieses Strings anpassen oder mit anderen Texten vermischen. Die formatToParts()-Methode liefert 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" },
];

Jetzt sind die Informationen separat verfügbar und können auf eine benutzerdefinierte Weise formatiert und wieder zusammengesetzt werden. Zum Beispiel durch die 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.

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 Seksagenarz-Zyklus benannter Jahre. Diese Kalender haben keine universelle Methode, jedes Jahr eindeutig zu nummerieren, daher werden Jahre anhand ihrer Beziehung zu entsprechenden Jahren im Gregorianischen Kalender unterschieden. In diesem Fall wird, wenn das DateTimeFormat konfiguriert ist, um die Jahreskomponente auszugeben, 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 date-time components-Optionen zu einem Format, das auch einen yearName beinhaltet. Es gibt keine separate Option, die steuert, ob yearName angezeigt wird oder nicht. Zum Beispiel führen die unten angegebenen Optionen dazu, dass month auf "long" gesetzt wird und ein yearName-Token ergibt, obwohl year immer noch "numeric" ist:

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 zusammenverkettet, sehen Sie in diesem Fall das Gregorianische Jahr und den Jahrnamen zusammen in der Ausgabe.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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