204 lines
9.5 KiB
Markdown
204 lines
9.5 KiB
Markdown
|
## .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](http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table).
|
|||
|
|
|
|||
|
|
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)](http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table) 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](https://www.iana.org/time-zones), 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.
|
|||
|
|
|
|||
|
|
[CLDR content]: ../../../README.md#2-cldr-content
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
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](#parameters)). 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"` |
|
|||
|
|
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
Globalize.loadTimeZone( require( "iana-tz-data" ) );
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// 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" ]
|
|||
|
|
```
|