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
formatToParts(date)
Parameter
dateOptional-
Das zu formatierende Datum. Dies kann ein
Date- oderTemporal.PlainDateTime-Objekt sein. Es kann auch einTemporal.PlainTime-,Temporal.PlainDate-,Temporal.PlainYearMonth- oderTemporal.PlainMonthDay-Objekt sein, sofern dasDateTimeFormat-Objekt so konfiguriert wurde, dass es mindestens einen für das jeweilige Objekt relevanten Bestandteil ausgibt.Hinweis: Bei einem
Temporal.ZonedDateTime-Objekt wird immer einTypeErrorausgelöst. Verwenden Sie stattdessenTemporal.ZonedDateTime.prototype.toLocaleString()oder konvertieren Sie es in einTemporal.PlainDateTime-Objekt.Wenn Sie
dateweglassen, wird das aktuelle Datum formatiert (wie vonDate.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
datebeeinflusst wird, zum Beispiel"/",", ","o'clock","de"oder" ". -
Eine vierstellige gregorianische Jahreszahl, falls der Kalender statt einer Jahreszahl einen
yearNameverwendet, 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:
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:
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.
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.
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:
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> |