1 | # vue-timeago [![NPM version](https://img.shields.io/npm/v/vue-timeago.svg)](https://npmjs.com/package/vue-timeago) [![NPM downloads](https://img.shields.io/npm/dm/vue-timeago.svg)](https://npmjs.com/package/vue-timeago) [![Build Status](https://img.shields.io/circleci/project/github/egoist/vue-timeago/master.svg)](https://circleci.com/gh/egoist/vue-timeago)
|
2 |
|
3 | > A timeago component Vue.js
|
4 |
|
5 | ## Install
|
6 |
|
7 | ```bash
|
8 | yarn add vue-timeago
|
9 | # or
|
10 | npm i vue-timeago
|
11 | ```
|
12 |
|
13 | CDN: [UNPKG](https://unpkg.com/vue-timeago/dist/) | [jsDelivr](https://cdn.jsdelivr.net/npm/vue-timeago/dist/) (available as `window.VueTimeago`)
|
14 |
|
15 | ## Usage
|
16 |
|
17 | For usages on version 4, please check out [this branch](https://github.com/egoist/vue-timeago/tree/4).
|
18 |
|
19 | ```js
|
20 | import VueTimeago from 'vue-timeago'
|
21 |
|
22 | Vue.use(VueTimeago, {
|
23 | name: 'Timeago', // Component name, `Timeago` by default
|
24 | locale: 'en', // Default locale
|
25 | // We use `date-fns` under the hood
|
26 | // So you can use all locales from it
|
27 | locales: {
|
28 | 'zh-CN': require('date-fns/locale/zh_cn'),
|
29 | ja: require('date-fns/locale/ja')
|
30 | }
|
31 | })
|
32 | ```
|
33 |
|
34 | Then in your lovely component:
|
35 |
|
36 | ```vue
|
37 | <!-- simple usage -->
|
38 | <!-- time is a dateString that can be parsed by Date.parse() -->
|
39 | <timeago :datetime="time"></timeago>
|
40 |
|
41 | <!-- Auto-update time every 60 seconds -->
|
42 | <timeago :datetime="time" :auto-update="60"></timeago>
|
43 |
|
44 | <!-- custom locale -->
|
45 | <!-- use a different locale instead of the global config -->
|
46 | <timeago :datetime="time" locale="zh-CN"></timeago>
|
47 | ```
|
48 |
|
49 | ## Plugin options
|
50 |
|
51 | ```js
|
52 | Vue.use(VueTimeago, pluginOptions)
|
53 | ```
|
54 |
|
55 | ### locales
|
56 |
|
57 | - **Type**: `{ [localeName: string]: any }`
|
58 |
|
59 | An object of locales.
|
60 |
|
61 | ### locale
|
62 |
|
63 | - **Type**: `string`
|
64 |
|
65 | The default locale name.
|
66 |
|
67 | ### converter
|
68 |
|
69 | - **Type**: `(date, locale, converterOptions) => string`
|
70 |
|
71 | A `converter` that formats regular dates in `xxx ago` or `in xxx` style.
|
72 |
|
73 | Check out our [default converter](https://github.com/egoist/vue-timeago/blob/master/src/converter.js) which uses [date-fns/distance_in_words_to_now](https://date-fns.org/v1.29.0/docs/distanceInWordsToNow) under the hood.
|
74 |
|
75 | ### converterOptions
|
76 |
|
77 | - **Type**: `Object`
|
78 |
|
79 | Provide an object which will be available as argument `converterOptions` in the `converter` we mentioned above.
|
80 |
|
81 | Our default converter supports most options that [date-fns/distance_in_words_to_now](https://date-fns.org/v1.29.0/docs/distanceInWordsToNow) library supports, namely:
|
82 |
|
83 | - **includeSeconds**: (default: `false`) distances less than a minute are more detailed
|
84 | - **addSuffix**: (default: `true`) result specifies if the second date is earlier or later than the first
|
85 |
|
86 | ## props
|
87 |
|
88 | ### datetime
|
89 |
|
90 | - **Type**: `Date` `string` `number`
|
91 | - **Required**: `true`
|
92 |
|
93 | The datetime to be formatted .
|
94 |
|
95 | ### autoUpdate
|
96 |
|
97 | - **Type**: `number` `boolean`
|
98 | - **Default**: `false`
|
99 |
|
100 | The period to update the component, in **seconds**.
|
101 |
|
102 | You can omit this prop or set it to `0` or `false` to disable auto-update.
|
103 |
|
104 | When `true` it will be equivalent to `60`.
|
105 |
|
106 | ### locale
|
107 |
|
108 | Just like the `locale` option in the plugin options, but this could override the global one.
|
109 |
|
110 | ### converter
|
111 |
|
112 | Just like the `converter` option in the plugin options, but this could override the global one.
|
113 |
|
114 | ### converterOptions
|
115 |
|
116 | Just like the `converterOptions` option in the plugin options, but this could override the global one.
|
117 |
|
118 | ## Recipes
|
119 |
|
120 | ### Update Locale Globally
|
121 |
|
122 | ```js
|
123 | Vue.use(VueTimeago, {
|
124 | locale: 'en',
|
125 | locales: {
|
126 | 'zh-CN': require('date-fns/locale/zh_cn')
|
127 | }
|
128 | })
|
129 | ```
|
130 |
|
131 | In your components you can use `this.$timeago.locale` to access the global locale, in this case it's `en`, the `<timeago>` component will get updated when you set it to another valid locale, e.g. `this.$timeago.locale = 'zh-CN'`.
|
132 |
|
133 | ## What about the good old [vue-timeago v3](https://github.com/egoist/vue-timeago/tree/3)?
|
134 |
|
135 | The older version (700 bytes gzipped) is much smaller than the current version (2.8kB gzipped) that uses [`date-fns`](https://date-fns.org/).
|
136 |
|
137 | But the current version gives more precise result (and hopefully handles more edge cases), and we don't need to maintain a big list of locale messages because `date-fns` already did it for us.
|
138 |
|
139 | ## Development
|
140 |
|
141 | ```bash
|
142 | # for dev
|
143 | yarn example
|
144 |
|
145 | # build in cjs es umd format
|
146 | yarn build
|
147 | ```
|
148 |
|
149 | ## License
|
150 |
|
151 | MIT © [EGOIST](https://github.com/egoist)
|