The Intl.DateTimeFormat.prototype.formatToParts()
method allows locale-aware formatting of strings produced by DateTimeFormat
formatters.
Syntax
dateTimeFormat.formatToParts(date)
Parameters
date
Optional- The date to format.
Return value
An Array
of objects containing the formatted date in parts.
Description
The formatToParts()
method is useful for custom formatting of date strings. It returns an Array
of objects containing the locale-specific tokens from which it possible to build custom strings while preserving the locale-specific parts. The structure the formatToParts()
method returns, looks like this:
[ { type: 'day', value: '17' }, { type: 'weekday', value: 'Monday' } ]
Possible types are the following:
- day
- The string used for the day, for example
"17"
. - dayPeriod
- The string used for the day period, for example,
"AM",
"PM"
,"in the morning"
, or"noon"
- era
- The string used for the era, for example
"BC"
or"AD"
. - fractionalSecond
- The string used for the fractional seconds, for example
"0"
or"00"
or"000"
. - hour
- The string used for the hour, for example
"3"
or"03"
. - literal
- The string used for separating date and time values, for example
"/"
,","
,"o'clock"
,"de"
, etc. - minute
- The string used for the minute, for example
"00"
. - month
- The string used for the month, for example
"12"
. - relatedYear
- The string used for the related 4-digit Gregorian year, in the event that the calendar's representation would be a yearName instead of a year, for example
"2019"
. - second
- The string used for the second, for example
"07"
or"42"
. - timeZoneName
- The string used for the name of the time zone, for example
"UTC"
. - weekday
- The string used for the weekday, for example
"M"
,"Monday"
, or"Montag"
. - year
- The string used for the year, for example
"2012"
or"96"
. - yearName
- The string used for the yearName in relevant contexts, for example
"geng-zi"
Polyfill
A polyfill for this feature is available in the proposal repository.
Examples
DateTimeFormat
outputs localized, opaque strings that cannot be manipulated directly:
var date = Date.UTC(2012, 11, 17, 3, 0, 42); var 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"
However, in many User Interfaces there is a desire to customize the formatting of this string. The formatToParts
method enables locale-aware formatting of strings produced by DateTimeFormat
formatters by providing you the string in parts:
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' } ]
Now the information is available separately and it can be formatted and concatenated again in a customized way. For example by using Array.prototype.map()
, arrow functions, a switch statement, template literals, and Array.prototype.reduce()
.
var dateString = formatter.formatToParts(date).map(({type, value}) => { switch (type) { case 'dayPeriod': return `<b>${value}</b>`; default : return value; } }).reduce((string, part) => string + part);
This will make the day period bold, when using the formatToParts()
method.
console.log(formatter.format(date)); // "Monday, 12/17/2012, 3:00:42.000 AM" console.log(dateString); // "Monday, 12/17/2012, 3:00:42.000 <b>AM</b>"
Named Years and Mixed calendars
In some cases, calendars use named years. Chinese and Tibetan calendars, for example, use a 60-year sexagenary cycle of named years. These years are disambiguated by relationship to corresponding years on the Gregorian calendar. When this is the case, the result of formatToParts()
will contain an entry for relatedYear
when a year would normally be present, containing the 4-digit Gregorian year, instead of an entry for year
. Setting an entry in the bag for year
(with any value) will yield both the and the yearName
Gregorian relatedYear:
let opts = { year: "numeric", month: "numeric", day: "numeric" }; let 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: 'literal', value: 'εΉ΄' }, { type: 'month', value: 'εδΈζ' }, { type: 'day', value: '4' } ]
If the year
option is not set in the bag (to any value), the result will include only the relatedYear
:
let 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' } ]
In cases where the year
would be output, .format()
may commonly present these side-by-side:
let df = new Intl.DateTimeFormat("zh-u-ca-chinese", {year: "numeric"}); df.format(Date.UTC(2012, 11, 17, 3, 0, 42)); // return value 2012壬辰年
This also makes it possible to mix locale and calendar in both format
:
let df = new Intl.DateTimeFormat("en-u-ca-chinese", {year: "numeric"}); let date = Date.UTC(2012, 11, 17, 3, 0, 42); df.format(date); // return value 2012(ren-chen)
And formatToParts
:
let opts = {month: 'numeric', day: 'numeric', year: "numeric"}; let df = new Intl.DateTimeFormat("en-u-ca-chinese", opts); let date = Date.UTC(2012, 11, 17, 3); df.formatToParts(date) // return value [ { type: 'month', value: '11' }, { type: 'literal', value: '/' }, { type: 'day', value: '4' }, { type: 'literal', value: '/' }, { type: 'relatedYear', value: '2012' } ]
Specifications
Specification |
---|
ECMAScript Internationalization API (ECMA-402) The definition of 'Intl.DateTimeFormat.prototype.formatToParts' in that specification. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
formatToParts | Chrome
Full support
57
| Edge Full support 18 | Firefox Full support 51 | IE No support No | Opera
Full support
44
| Safari Full support 11 | WebView Android
Full support
57
| Chrome Android
Full support
57
| Firefox Android Full support 56 | Opera Android
Full support
43
| Safari iOS Full support 11 | Samsung Internet Android
Full support
7.0
| nodejs
Full support
8.0.0
|
Legend
- Full support
- Full support
- No support
- No support
- See implementation notes.
- See implementation notes.