vue-luxon
Version:
Easy use of DateTime formatting & parsing in Vue using Luxon
479 lines (343 loc) • 22.7 kB
Markdown
# vue-luxon
DateTime formatting & parsing in Vue using Luxon
[](https://npmjs.com/package/vue-luxon) [](https://npmjs.com/package/vue-luxon) [](#) [](https://github.com/casbloem/vue-luxon)
## https://packages.cblm.nl/vue-luxon
## Install
```shell
npm install vue-luxon
```
### Setup
```javascript
import VueLuxon from "vue-luxon";
Vue.use(VueLuxon);
```
By default, vue-luxon expect the given datetime string to be time zone `utc` and format `iso` . The output will be based on the client's locale.
Change the default settings:
```javascript
Vue.use(VueLuxon, {
input: {
zone: "utc",
format: "iso"
},
output: "short"
});
```
[Learn more about settings](#settings)
## Basic usage
You can use the `$luxon` method everywhere in your vue app:
```js
this.$luxon("2020-10-05T14:48:00.000Z")
// October 5, 2020
```
Or use the `luxon` filter, as shown below:
```javascript
{{ "2020-10-05T14:48:00.000Z" | luxon }}
// October 5, 2020
```
You can change the output format:
```js
this.$luxon("2020-10-05T14:48:00.000Z", "dd-MM-yyyy")
// 05-10-2020
this.$luxon("2020-10-05 22:36", "relative")
// 22 days ago
```
And other settings:
```js
this.$luxon("2020-10-05 22:36", {
input: { format: "yyyy-MM-dd HH:mm", zone: "Asia/Tokyo" },
output: "full",
})
// October 5, 2020, 3:36 PM GMT+2
```
These formats will be in the clients browser language, unless you set a [specific language].
## Settings
| prop | options (default) | description |
| --------- | -------------------------------------- | ------------------------------------------------------------ |
| input | see [settings.input](#settingsinput) | The default input format and zone |
| output | see [settings.output](#settingsoutput) | The default output format, zone, language, and relative settings |
| templates | see [ templates](#templates) | Define objects to use as properties |
#### Default settings
You can change the default settings with the second argument of the `Vue.use` function.
```javascript
Vue.use(VueLuxon, {
templates: {},
input: {
zone: "utc",
format: "iso"
},
output: {
zone: "local",
format: {
year: "numeric",
month: "long",
day: "numeric"
},
locale: null,
relative: {
round: true,
unit: null
}
}
});
```
You can also override the default settings per method/filter easily:
```javascript
{{ datetimeString | luxon({ settings }) }}
this.$luxon({ settings })
```
### Zone
eg: `UTC`, `America/New_York`, `Asia/Tokyo`, ...
For the systems local zone you use `local`.
There is a [list on wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
### Formats
#### Input and Output formats
These formats can be used as `input.format` and `output.format`
| format | description | in- or output | example |
| -------------- | ------------------------------------ | ------------- | --------------------------------- |
| sql | SQL dates, times, and datetimes | both | `2017-05-15 09:24:15` |
| iso | ISO 8601 date time string | both | `2018-01-06T13:07:04.054` |
| rfc2822 | RFC 2822 | both | `Tue, 01 Nov 2016 13:23:12 +0630` |
| http | HTTP header specs (RFC 850 and 1123) | both | `Sun, 06 Nov 1994 08:49:37 GMT` |
| seconds | Unix timestamp | both | `1542674993` |
| millis | Unix timestamp milliseconds | both | `1542674993410` |
| _tokens_ | see: tokens | both | `yyyy-MM-dd` |
| *templateName* | see: [Templates](#templates) | both | |
#### Output formats
These formats can only be used as `output.format`
| format | example _(with locale `en_US`)_ |
| ---------------- | ---------------------------------------------------------- |
| relative | see: [Relative](#relative) |
| short | 10/14/1983, 1:30 PM |
| shorts | 10/14/1983, 1:30:23 PM |
| med | Oct 14, 1983, 1:30 PM |
| meds | Oct 14, 1983, 9:30:33 AM |
| full | October 14, 1983, 9:30 AM EDT |
| fulls | October 14, 1983, 9:30:33 AM EDT |
| huge | Friday, October 14, 1983, 9:30 AM Eastern Daylight Time |
| huges | Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time |
| time | 9:30 AM |
| times | 09:30:23 AM |
| time24 | 09:30 |
| time24s | 09:30:23 |
| time24longoffset | 09:30:23 Eastern Daylight Time |
| date_full | October 14, 1983 |
| date_huge | Tuesday, October 14, 1983 |
| date_med | Oct 14, 1983 |
| date_medd | Fri, Oct 14, 1983 |
| date_short | 10/14/1983 |
`output.format` can also be an object:
```javascript
// using an object:
format: {
year: 'numeric',
month: 'long',
day: 'numeric'
}
```
| Property | Possible values | Description |
| ------------ | ------------------------------------------- | ---------------------------------------- |
| weekday | `narrow` `short` `long` | The representation of the weekday |
| era | `narrow` `short` `long` | The representation of the era |
| year | `numeric` `2-digit` | The representation of the year |
| month | `numeric` `2-digit` `narrow` `short` `long` | The representation of the month |
| day | `numeric` `2-digit` | The representation of the day |
| hour | `numeric` `2-digit` | The representation of the hour |
| minute | `numeric` `2-digit` | The representation of the minute |
| second | `numeric` `2-digit` | The representation of the second |
| timeZoneName | `short` `long` | The representation of the time zone name |
### settings.input
`object` or `string`
An `object`containing a [zone](#zone) and [format](#format) or a `string` of a [template](#format-and-zone-templates) name.
```js
{
zone: "utc",
format: "iso"
}
```
### settings.output
`object` or `string`
An `object`containing a [zone](#zone) and [format](#format) or a `string` of a [template](#format-and-zone-templates) name.
```js
{
zone: "local",
format: "short",
locale: null,
relative: {} // see settings.relative
}
```
`locale` set to `null` will use the client's locale.
`relative` Read about the [relative format below](#relativeFormat)
### settings.output.locale
`string`
**`null` default value, this will use the client's locale.**
Or use a locale tag to set a client location.
Examples:
`en`: English (primary language).
`hi`: Hindi (primary language).
`de-AT`: German as used in Austria (primary language with country code).
`zh-Hans-CN`: Chinese written in simplified
### settings.output.relative
Set the `output.format` to `relative` to use the relative format. Or use the `luxonRelative` filter.
```
{{ datetime | luxonRelative }}
this.$luxon({ output: { format: "relative" } })
{{ datetime | luxonRelative({ style: "short" }) }}
this.$luxon({ output: { format: "relative", relative: { style: "short" } } })
```
You can change the behavior with the `relative settings object in the `output` .
```javascript
{
output: {
format: "relative"
relative: {
style: "long",
unit: null,
round: true,
padding: 0
},
}
}
```
| property | description | default |
| -------- | ------------------------------------------------------------ | ------- |
| style | the style of units, must be "long", "short", or "narrow" | `long` |
| unit | use a specific unit; if omitted, the method will pick the unit. Use one of "years", "quarters", "months", "weeks", "days", "hours", "minutes", or "seconds" | `null` |
| round | whether to round the numbers in the output. | `true` |
| padding | padding in milliseconds. This allows you to round up the result if it fits inside the threshold. Don't use in combination with {round: false} because the decimal output will include the padding. | `0` |
#### Templates
You can predefine setting templates.
By default there is a `server`, `client` and a `inputdate` template, but you can add your own to the options object.
It's also possible to use a template in a template, as the `inputdate` uses the `client` template's zone for example.
```js
templates: {
server: {
zone: "utc",
format: "iso"
},
client: {
zone: "local",
format: "short"
},
inputdate: {
zone: "client",
format: "yyyy-MM-dd"
}
}
```
There are multiple ways to use a template:
```js
// This will use the templates zone and format
{{ "2020-10-05T14:48:00.000Z" | luxon({ input: "server" }) }}
// This will use the templates zone
{{ "2020-10-05T14:48:00.000Z" | luxon({ input: { zone: "client" } }) }}
```
Or you can set the default input and output in the `Vue.use` function to use these templates by default:
```js
Vue.use(VueLuxon, {
input: "server",
output: "client",
});
```
Or create custom templates to use everywhere:
```js
Vue.use(VueLuxon, {
templates: {
serverAMS: {
zone: "Europe/Amsterdam",
format: "dd-MM-yyyy HH:mm:ss"
},
serverUTC: {
zone: "UTC",
format: "yyyy-MM-dd HH:mm:ss"
},
clientAMS: {
zone: "Europe/Amsterdam",
format: "med"
}
},
input: "serverUTC",
output: "clientAMS",
});
```
----
### Tokens
Tokens are useful for formatting and parsing.
You can use the following tokens:
| Standalone token | Format token | Description | Example |
| ---------------- | ------------ | ------------------------------------------------------------ | ----------------------------------------------------------- |
| S | | millisecond, no padding | 54 |
| SSS | | millisecond, padded to 3 | 054 |
| u | | fractional seconds, functionally identical to SSS | 054 |
| s | | second, no padding | 4 |
| ss | | second, padded to 2 padding | 04 |
| m | | minute, no padding | 7 |
| mm | | minute, padded to 2 | 07 |
| h | | hour in 12-hour time, no padding | 1 |
| hh | | hour in 12-hour time, padded to 2 | 01 |
| H | | hour in 24-hour time, no padding | 9 |
| HH | | hour in 24-hour time, padded to 2 | 13 |
| Z | | narrow offset | +5 |
| ZZ | | short offset | +05:00 |
| ZZZ | | techie offset | +0500 |
| ZZZZ | | abbreviated named offset | EST |
| ZZZZZ | | unabbreviated named offset | Eastern Standard Time |
| z | | IANA zone | America/New_York |
| a | | meridiem | AM |
| d | | day of the month, no padding | 6 |
| dd | | day of the month, padded to 2 | 06 |
| c | E | day of the week, as number from 1-7 (Monday is 1, Sunday is 7) | 3 |
| ccc | EEE | day of the week, as an abbreviate localized string | Wed |
| cccc | EEEE | day of the week, as an unabbreviated localized string | Wednesday |
| ccccc | EEEEE | day of the week, as a single localized letter | W |
| L | M | month as an unpadded number | 8 |
| LL | MM | month as an padded number | 08 |
| LLL | MMM | month as an abbreviated localized string | Aug |
| LLLL | MMMM | month as an unabbreviated localized string | August |
| LLLLL | MMMMM | month as a single localized letter | A |
| y | | year, unpadded | 2014 |
| yy | | two-digit year | 14 |
| yyyy | | four- to six- digit year, pads to 4 | 2014 |
| G | | abbreviated localized era | AD |
| GG | | unabbreviated localized era | Anno Domini |
| GGGGG | | one-letter localized era | A |
| kk | | ISO week year, unpadded | 17 |
| kkkk | | ISO week year, padded to 4 | 2014 |
| W | | ISO week number, unpadded | 32 |
| WW | | ISO week number, padded to 2 | 32 |
| o | | ordinal (day of year), unpadded | 218 |
| ooo | | ordinal (day of year), padded to 3 | 218 |
| D | | localized numeric date | 9/4/2017 |
| DD | | localized date with abbreviated month | Aug 6, 2014 |
| DDD | | localized date with full month | August 6, 2014 |
| DDDD | | localized date with full month and weekday | Wednesday, August 6, 2014 |
| t | | localized time | 9:07 AM |
| tt | | localized time with seconds | 1:07:04 PM |
| ttt | | localized time with seconds and abbreviated offset | 1:07:04 PM EDT |
| tttt | | localized time with seconds and full offset | 1:07:04 PM Eastern Daylight Time |
| T | | localized 24-hour time | 13:07 |
| TT | | localized 24-hour time with seconds | 13:07:04 |
| TTT | | localized 24-hour time with seconds and abbreviated offset | 13:07:04 EDT |
| TTTT | | localized 24-hour time with seconds and full offset | 13:07:04 Eastern Daylight Time |
| f | | short localized date and time | 8/6/2014, 1:07 PM |
| ff | | less short localized date and time | Aug 6, 2014, 1:07 PM |
| fff | | verbose localized date and time | August 6, 2014, 1:07 PM EDT |
| ffff | | extra verbose localized date and time | Wednesday, August 6, 2014, 1:07 PM Eastern Daylight Time |
| F | | short localized date and time with seconds | 8/6/2014, 1:07:04 PM |
| FF | | less short localized date and time with seconds | Aug 6, 2014, 1:07:04 PM |
| FFF | | verbose localized date and time with seconds | August 6, 2014, 1:07:04 PM EDT |
| FFFF | | extra verbose localized date and time with seconds | Wednesday, August 6, 2014, 1:07:04 PM Eastern Daylight Time |
| q | | quarter, no padding | 9 |
| qq | | quarter, padded to 2 | 13 |
------
#### Change the `$luxon` method name
Provide a `methodName` in the settings object.
--------
### Tips
- Save and serve your datetimes from the server in the `utc` time zone and the `iso` or `sql` format. Then use the client's locale format.
------
### Changelog
**0.10.0**
- `output.lang` is changed to `output.locale` and the locale is now always set.
- ESM version added
**0.9.0**
- New API