Skip to content

Latest commit

 

History

History
203 lines (150 loc) · 9.54 KB

date-formatter.md

File metadata and controls

203 lines (150 loc) · 9.54 KB
Raw

.dateFormatter( [options] ) ➜ function( value )

Return a function that formats a date according to the given options. The default formatting is numeric year, month, and day (i.e., { skeleton: "yMd" }.

The returned function is invoked with one argument: the Date instance value to be formatted.

Parameters

options.skeleton

String value indicating a skeleton (see description above), eg. { skeleton: "GyMMMd" }.

Skeleton provides a more flexible formatting mechanism than the predefined list full, long, medium, or short represented by date, time, or datetime. Instead, they are an open-ended list of patterns containing only date field information, and in a canonical order. For a complete list of skeleton patterns check the unicode CLDR documentation.

For example:

locale "GyMMMd" skeleton
en "Apr 9, 2014 AD"
zh "公元2014年4月9日"
es "9 abr. de 2014 d. C."
ar "٩ أبريل، ٢٠١٤ م"
pt "9 de abr de 2014 d.C."

options.date

One of the following String values: full, long, medium, or short, eg., { date: "full" }.

options.time

One of the following String values: full, long, medium, or short, eg., { time: "full" }.

options.datetime

One of the following String values: full, long, medium, or short, eg., { datetime: "full" }.

options.raw

String value indicating a machine raw pattern (anything in the "Sym." column) eg. { raw: "dd/mm" }. Note this is NOT recommended for i18n in general. Use skeleton instead.

options.timeZone

String based on the time zone names of the IANA time zone database, such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".

value

Date instance to be formatted, eg. new Date();

Example

Prior to using any date methods, you must load cldr/main/{locale}/ca-gregorian.json, cldr/main/{locale}/timeZoneNames.json, cldr/supplemental/metaZones.json, cldr/supplemental/timeData.json, cldr/supplemental/weekData.json, and the CLDR content required by the number module. Read CLDR content if you need more information.

var formatter;

Globalize.locale( "en" );
formatter = Globalize.dateFormatter();

formatter( new Date( 2010, 10, 30, 17, 55 ) );
// > "11/30/2010"

You can use the instance method .dateFormatter(), which uses the instance locale.

var enFormatter = Globalize( "en" ).dateFormatter(),
  deFormatter = Globalize( "de" ).dateFormatter();

enFormatter( new Date( 2010, 10, 30, 17, 55 ) );
// > "11/30/2010"

deFormatter( new Date( 2010, 10, 30, 17, 55 ) );
// > "30.11.2010"

Using short, medium, long, and full presets

Use convenient presets for date, time, or datetime. Their possible values are: short, medium, long, and full.

presetValue Globalize( "en" ).dateFormatter( presetValue )( new Date( 2010, 10, 1, 17, 55 ) )
{ date: "short" } "11/1/10"
{ date: "medium" } "Nov 1, 2010"
{ date: "long" } "November 1, 2010"
{ date: "full" } "Monday, November 1, 2010"
{ time: "short" } "5:55 PM"
{ time: "medium" } "5:55:00 PM"
{ time: "long" } "5:55:00 PM PST"
{ time: "full" } "5:55:00 PM Pacific Standard Time"
{ datetime: "short" } "11/1/10, 5:55 PM"
{ datetime: "medium" } "Nov 1, 2010, 5:55:00 PM"
{ datetime: "long" } "November 1, 2010 at 5:55:00 PM PST"
{ datetime: "full" } "Monday, November 1, 2010 at 5:55:00 PM Pacific Standard Time"

For comparison, follow the same formatter { datetime: "short" } on different locales.

locale Globalize( locale ).dateFormatter({ datetime: "short" })( new Date( 2010, 10, 1, 17, 55 ) )
en "11/1/10, 5:55 PM"
en_GB "01/11/2010 17:55"
zh "10/11/1 下午5:55"
zh-u-nu-native "一〇/一一/一 下午五:五五"
es "1/11/10 17:55"
de "01.11.10 17:55"
pt "01/11/10 17:55"
ar "١‏/١١‏/٢٠١٠ ٥،٥٥ م"

Using open-ended skeletons

Use open-ended skeletons for more flexibility (see its description above). See some examples below.

skeleton Globalize( "en" ).dateFormatter( skeleton )( new Date( 2010, 10, 1, 17, 55 ) )
{ skeleton: "E" } "Tue"
{ skeleton: "EHm" } "Tue 17:55"
{ skeleton: "EHms" } "Tue 17:55:00"
{ skeleton: "Ed" } "30 Tue"
{ skeleton: "Ehm" } "Tue 5:55 PM"
{ skeleton: "Ehms" } "Tue 5:55:00 PM"
{ skeleton: "Gy" } "2010 AD"
{ skeleton: "GyMMM" } "Nov 2010 AD"
{ skeleton: "GyMMMEd" } "Tue, Nov 30, 2010 AD"
{ skeleton: "GyMMMd" } "Nov 30, 2010 AD"
{ skeleton: "H" } "17"
{ skeleton: "Hm" } "17:55"
{ skeleton: "Hms" } "17:55:00"
{ skeleton: "M" } "11"
{ skeleton: "MEd" } "Tue, 11/30"
{ skeleton: "MMM" } "Nov"
{ skeleton: "MMMEd" } "Tue, Nov 30"
{ skeleton: "MMMd" } "Nov 30"
{ skeleton: "Md" } "11/30"
{ skeleton: "d" } "30"
{ skeleton: "h" } "5 PM"
{ skeleton: "hm" } "5:55 PM"
{ skeleton: "hms" } "5:55:00 PM"
{ skeleton: "ms" } "55:00"
{ skeleton: "y" } "2010"
{ skeleton: "yM" } "11/2010"
{ skeleton: "yMEd" } "Tue, 11/30/2010"
{ skeleton: "yMMM" } "Nov 2010"
{ skeleton: "yMMMEd" } "Tue, Nov 30, 2010"
{ skeleton: "yMMMd" } "Nov 30, 2010"
{ skeleton: "yMd" } "11/30/2010"
{ skeleton: "yQQQ" } "Q4 2010"
{ skeleton: "yQQQQ" } "4th quarter 2010"
{ skeleton: "GyMMMEdhms" } "Tue, Nov 30, 2010 AD, 5:55:00 PM"
{ skeleton: "Ehms" } "Tue 5:55:00 PM"
{ skeleton: "yQQQHm" } "Q4 2010, 17:55"
{ skeleton: "MMMEdhm" } "Tue, Nov 30, 5:55 PM"
{ skeleton: "yMMMdhm" } "Nov 30, 2010, 5:55 PM" 
var globalize = Globalize( "en" ),
  date = new Date( 2010, 10, 30, 17, 55 ),
  monthDayFormatter = globalize.dateFormatter({ skeleton: "MMMd" }),
  hourMinuteSecondFormatter = globalize.dateFormatter({ skeleton: "Hms" });

monthDayFormatter( date );
// > "Nov 30"

hourMinuteSecondFormatter( date );
// > "17:55:00"

Using time zones

Using specific timeZones, i.e., using options.timezone. Note that prior to using it, you must load IANA time zone data.

Globalize.loadTimeZone( require( "iana-tz-data" ) );
Globalize.locale( "en" );

Globalize.dateFormatter({ datetime: "medium", timeZone: "America/Los_Angeles" })( new Date() );
// > "Nov 1, 2010, 12:55:00 PM"

Globalize.dateFormatter({ datetime: "medium", timeZone: "America/Sao_Paulo" })( new Date() )
// > "Nov 1, 2010, 5:55:00 PM"

Globalize.dateFormatter({ datetime: "full", timeZone: "Europe/Berlin" })( new Date() )
// > "Monday, November 1, 2010 at 8:55:00 PM Central European Standard Time"

Note on performance

For improved performance on iterations, first create the formatter. Then, reuse it on each loop.

// In an application, this array could have a few hundred entries
var dates = [ new Date( 2010, 10, 30, 17, 55 ), new Date( 2015, 3, 18, 4, 25 ) ];
var formatter = Globalize( "en" ).dateFormatter({ time: "short" });

var formattedDates = dates.map(function( date ) {
  return formatter( date );
});
// > Array [ "5:55 PM", "4:25 AM" ]