204 lines
11 KiB
Markdown
204 lines
11 KiB
Markdown
|
# dateformat
|
||
|
|
|
||
|
|
A node.js package for Steven Levithan's excellent [dateFormat()][dateformat] function.
|
||
|
|
|
||
|
|
## Modifications
|
||
|
|
|
||
|
|
- Removed the `Date.prototype.format` method. Sorry folks, but extending native prototypes is for suckers.
|
||
|
|
- Added a `module.exports = dateFormat;` statement at the bottom
|
||
|
|
- Added the placeholder `N` to get the ISO 8601 numeric representation of the day of the week
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
```bash
|
||
|
|
$ npm install dateformat
|
||
|
|
$ dateformat --help
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
As taken from Steven's post, modified to match the Modifications listed above:
|
||
|
|
|
||
|
|
```js
|
||
|
|
import dateFormat, { masks } from "dateformat";
|
||
|
|
const now = new Date();
|
||
|
|
|
||
|
|
// Basic usage
|
||
|
|
dateFormat(now, "dddd, mmmm dS, yyyy, h:MM:ss TT");
|
||
|
|
// Saturday, June 9th, 2007, 5:46:21 PM
|
||
|
|
|
||
|
|
// You can use one of several named masks
|
||
|
|
dateFormat(now, "isoDateTime");
|
||
|
|
// 2007-06-09T17:46:21
|
||
|
|
|
||
|
|
// ...Or add your own
|
||
|
|
masks.hammerTime = 'HH:MM! "Can\'t touch this!"';
|
||
|
|
dateFormat(now, "hammerTime");
|
||
|
|
// 17:46! Can't touch this!
|
||
|
|
|
||
|
|
// You can also provide the date as a string
|
||
|
|
dateFormat("Jun 9 2007", "fullDate");
|
||
|
|
// Saturday, June 9, 2007
|
||
|
|
|
||
|
|
// Note that if you don't include the mask argument,
|
||
|
|
// dateFormat.masks.default is used
|
||
|
|
dateFormat(now);
|
||
|
|
// Sat Jun 09 2007 17:46:21
|
||
|
|
|
||
|
|
// And if you don't include the date argument,
|
||
|
|
// the current date and time is used
|
||
|
|
dateFormat();
|
||
|
|
// Sat Jun 09 2007 17:46:22
|
||
|
|
|
||
|
|
// You can also skip the date argument (as long as your mask doesn't
|
||
|
|
// contain any numbers), in which case the current date/time is used
|
||
|
|
dateFormat("longTime");
|
||
|
|
// 5:46:22 PM EST
|
||
|
|
|
||
|
|
// And finally, you can convert local time to UTC time. Simply pass in
|
||
|
|
// true as an additional argument (no argument skipping allowed in this case):
|
||
|
|
dateFormat(now, "longTime", true);
|
||
|
|
// 10:46:21 PM UTC
|
||
|
|
|
||
|
|
// ...Or add the prefix "UTC:" or "GMT:" to your mask.
|
||
|
|
dateFormat(now, "UTC:h:MM:ss TT Z");
|
||
|
|
// 10:46:21 PM UTC
|
||
|
|
|
||
|
|
// You can also get the ISO 8601 week of the year:
|
||
|
|
dateFormat(now, "W");
|
||
|
|
// 42
|
||
|
|
|
||
|
|
// and also get the ISO 8601 numeric representation of the day of the week:
|
||
|
|
dateFormat(now, "N");
|
||
|
|
// 6
|
||
|
|
```
|
||
|
|
|
||
|
|
### Mask options
|
||
|
|
|
||
|
|
| Mask | Description |
|
||
|
|
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
|
| `d` | Day of the month as digits; no leading zero for single-digit days. |
|
||
|
|
| `dd` | Day of the month as digits; leading zero for single-digit days. |
|
||
|
|
| `ddd` | Day of the week as a three-letter abbreviation. |
|
||
|
|
| `DDD` | "Ysd", "Tdy" or "Tmw" if date lies within these three days. Else fall back to ddd. |
|
||
|
|
| `dddd` | Day of the week as its full name. |
|
||
|
|
| `DDDD` | "Yesterday", "Today" or "Tomorrow" if date lies within these three days. Else fall back to dddd. |
|
||
|
|
| `m` | Month as digits; no leading zero for single-digit months. |
|
||
|
|
| `mm` | Month as digits; leading zero for single-digit months. |
|
||
|
|
| `mmm` | Month as a three-letter abbreviation. |
|
||
|
|
| `mmmm` | Month as its full name. |
|
||
|
|
| `yy` | Year as last two digits; leading zero for years less than 10. |
|
||
|
|
| `yyyy` | Year represented by four digits. |
|
||
|
|
| `h` | Hours; no leading zero for single-digit hours (12-hour clock). |
|
||
|
|
| `hh` | Hours; leading zero for single-digit hours (12-hour clock). |
|
||
|
|
| `H` | Hours; no leading zero for single-digit hours (24-hour clock). |
|
||
|
|
| `HH` | Hours; leading zero for single-digit hours (24-hour clock). |
|
||
|
|
| `M` | Minutes; no leading zero for single-digit minutes. |
|
||
|
|
| `MM` | Minutes; leading zero for single-digit minutes. |
|
||
|
|
| `N` | ISO 8601 numeric representation of the day of the week. |
|
||
|
|
| `o` | GMT/UTC timezone offset, e.g. -0500 or +0230. |
|
||
|
|
| `p` | GMT/UTC timezone offset, e.g. -05:00 or +02:30. |
|
||
|
|
| `s` | Seconds; no leading zero for single-digit seconds. |
|
||
|
|
| `ss` | Seconds; leading zero for single-digit seconds. |
|
||
|
|
| `S` | The date's ordinal suffix (st, nd, rd, or th). Works well with `d`. |
|
||
|
|
| `l` | Milliseconds; gives 3 digits. |
|
||
|
|
| `L` | Milliseconds; gives 2 digits. |
|
||
|
|
| `t` | Lowercase, single-character time marker string: a or p. |
|
||
|
|
| `tt` | Lowercase, two-character time marker string: am or pm. |
|
||
|
|
| `T` | Uppercase, single-character time marker string: A or P. |
|
||
|
|
| `TT` | Uppercase, two-character time marker string: AM or PM. |
|
||
|
|
| `W` | ISO 8601 week number of the year, e.g. 4, 42 |
|
||
|
|
| `WW` | ISO 8601 week number of the year, leading zero for single-digit, e.g. 04, 42 |
|
||
|
|
| `Z` | US timezone abbreviation, e.g. EST or MDT. For non-US timezones, the GMT/UTC offset is returned, e.g. GMT-0500 |
|
||
|
|
| `'...'`, `"..."` | Literal character sequence. Surrounding quotes are removed. |
|
||
|
|
| `UTC:` | Must be the first four characters of the mask. Converts the date from local time to UTC/GMT/Zulu time before applying the mask. The "UTC:" prefix is removed. |
|
||
|
|
|
||
|
|
### Named Formats
|
||
|
|
|
||
|
|
| Name | Mask | Example |
|
||
|
|
| ----------------- | ------------------------------ | ------------------------ |
|
||
|
|
| `default` | `ddd mmm dd yyyy HH:MM:ss` | Sat Jun 09 2007 17:46:21 |
|
||
|
|
| `shortDate` | `m/d/yy` | 6/9/07 |
|
||
|
|
| `paddedShortDate` | `mm/dd/yyyy` | 06/09/2007 |
|
||
|
|
| `mediumDate` | `mmm d, yyyy` | Jun 9, 2007 |
|
||
|
|
| `longDate` | `mmmm d, yyyy` | June 9, 2007 |
|
||
|
|
| `fullDate` | `dddd, mmmm d, yyyy` | Saturday, June 9, 2007 |
|
||
|
|
| `shortTime` | `h:MM TT` | 5:46 PM |
|
||
|
|
| `mediumTime` | `h:MM:ss TT` | 5:46:21 PM |
|
||
|
|
| `longTime` | `h:MM:ss TT Z` | 5:46:21 PM EST |
|
||
|
|
| `isoDate` | `yyyy-mm-dd` | 2007-06-09 |
|
||
|
|
| `isoTime` | `HH:MM:ss` | 17:46:21 |
|
||
|
|
| `isoDateTime` | `yyyy-mm-dd'T'HH:MM:sso` | 2007-06-09T17:46:21+0700 |
|
||
|
|
| `isoUtcDateTime` | `UTC:yyyy-mm-dd'T'HH:MM:ss'Z'` | 2007-06-09T22:46:21Z |
|
||
|
|
|
||
|
|
### Localization
|
||
|
|
|
||
|
|
Day names, month names and the AM/PM indicators can be localized by
|
||
|
|
passing an object with the necessary strings. For example:
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { i18n } from "dateformat";
|
||
|
|
|
||
|
|
i18n.dayNames = [
|
||
|
|
"Sun",
|
||
|
|
"Mon",
|
||
|
|
"Tue",
|
||
|
|
"Wed",
|
||
|
|
"Thu",
|
||
|
|
"Fri",
|
||
|
|
"Sat",
|
||
|
|
"Sunday",
|
||
|
|
"Monday",
|
||
|
|
"Tuesday",
|
||
|
|
"Wednesday",
|
||
|
|
"Thursday",
|
||
|
|
"Friday",
|
||
|
|
"Saturday",
|
||
|
|
];
|
||
|
|
|
||
|
|
i18n.monthNames = [
|
||
|
|
"Jan",
|
||
|
|
"Feb",
|
||
|
|
"Mar",
|
||
|
|
"Apr",
|
||
|
|
"May",
|
||
|
|
"Jun",
|
||
|
|
"Jul",
|
||
|
|
"Aug",
|
||
|
|
"Sep",
|
||
|
|
"Oct",
|
||
|
|
"Nov",
|
||
|
|
"Dec",
|
||
|
|
"January",
|
||
|
|
"February",
|
||
|
|
"March",
|
||
|
|
"April",
|
||
|
|
"May",
|
||
|
|
"June",
|
||
|
|
"July",
|
||
|
|
"August",
|
||
|
|
"September",
|
||
|
|
"October",
|
||
|
|
"November",
|
||
|
|
"December",
|
||
|
|
];
|
||
|
|
|
||
|
|
i18n.timeNames = ["a", "p", "am", "pm", "A", "P", "AM", "PM"];
|
||
|
|
```
|
||
|
|
|
||
|
|
> Notice that only one language is supported at a time and all strings
|
||
|
|
> _must_ be present in the new value.
|
||
|
|
|
||
|
|
### Breaking change in 2.1.0
|
||
|
|
|
||
|
|
- 2.1.0 was published with a breaking change, for those using localized strings.
|
||
|
|
- 2.2.0 has been published without the change, to keep packages refering to ^2.0.0 to continue working. This is now branch v2_2.
|
||
|
|
- 3.0.\* contains the localized AM/PM change.
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
(c) 2007-2009 Steven Levithan [stevenlevithan.com][stevenlevithan], MIT license.
|
||
|
|
|
||
|
|
[dateformat]: http://blog.stevenlevithan.com/archives/date-time-format
|
||
|
|
[stevenlevithan]: http://stevenlevithan.com/
|