This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
The Intl.DateTimeFormat.prototype.formatToParts()
method allows locale-aware formatting of strings produced by DateTimeFormat
formatters.
Intl.DateTimeFormat.prototype.formatToParts(date)
date
Optional
An Array
of objects containing the formatted date in parts.
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:
","
, "o'clock"
, "de"
, etc.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', hour12: true, timeZone: 'UTC' }); formatter.format(date); // "Monday, 12/17/2012, 3:00:42 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: '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 `<strong>${value}</strong>`; 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 AM" console.log(dateString); // "Monday, 12/17/2012, 3:00:42 <strong>AM</strong>"
A polyfill for this feature is available in the proposal repository.
Specification | Status | Comment |
---|---|---|
ECMAScript Internationalization API 4.0 (ECMA-402) The definition of 'Intl.DateTimeFormat.prototype.formatToParts' in that specification. | Draft | Initial definition |
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | No support[1] | 51.0 (51.0) | No support | No support | No support |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | No support | No support | 54.0 (54.0)[2] | No support | No support | No support |
[1] This method is implemented since Chrome 55 behind the --datetime-format-to-part
s command line parameter (see V8 issue 5244).
[2] This method was initially only exposed to B2G system apps starting from Gecko 46 (Firefox 46.0 / Thunderbird 46.0 / SeaMonkey 2.43) (see bug 1216150).
Intl.DateTimeFormat
Intl.DateTimeFormat.prototype.format
Date.prototype.toLocaleString()
Date.prototype.toLocaleDateString()
Date.prototype.toLocaleTimeString()
© 2005–2017 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/formatToParts