Awesome
timeago.js
timeago.js is a nano library(less than
2 kb
) used to format datetime with*** time ago
statement. eg: '3 hours ago'.
- i18n supported.
- Time
ago
and timein
supported. - Real-time render supported.
- Node and browser supported.
- Well tested.
Official website. React version here: timeago-react. Python version here: timeago.
Such as
just now
12 seconds ago
2 hours ago
3 days ago
3 weeks ago
2 years ago
in 12 seconds
in 3 minutes
in 24 days
in 6 months
Usage
- install
npm install timeago.js
- import
import { format, render, cancel, register } from 'timeago.js';
or import with script
tag in html file and access global variable timeago
.
<script src="dist/timeago.min.js"></script>
- example
// format the time with locale
format('2016-06-12', 'en_US');
CDN
Alternatively to NPM, you can also use a CDN which will reflect the latest version as soon as it is published to npm.
<script src="//unpkg.com/timeago.js"></script>
API
There only 4 API below.
- format
format(date[, locale = 'en_US', opts])
, format a Date instance / timestamp / date string to string.
import { format } from 'timeago.js';
// format timestamp
format(1544666010224);
// format date instance
format(new Date(1544666010224));
// format date string
format('2018-12-12');
// format with locale
format(1544666010224, 'zh_CN');
// format with locale and relative date
format(1544666010224, 'zh_CN', { relativeDate: '2018-11-11' });
// e.g.
format(Date.now() - 11 * 1000 * 60 * 60); // returns '11 hours ago'
The default locale is en_US
, and the library contains en_US
and zh_CN
build-in.
- render & cancel
render(dom[, locale = 'en_US', opts])
cancel([dom])
Make a dom with
datetime
attribute automatic rendering and cancel.
HTML code:
<div class="timeago" datetime="2016-06-30 09:20:00"></div>
Javascript code:
import { render, cancel } from 'timeago.js';
const nodes = document.querySelectorAll('.timeago');
// use render method to render nodes in real time
render(nodes, 'zh_CN');
// render with opts
// render(nodes, 'en_US', { minInterval: 3 });
// cancel all real-time render task
cancel();
// or cancel for the specific one
cancel(nodes[0])
The 3rd parameter opts
contains:
export type Opts = {
/** the relative date */
readonly relativeDate?: TDate;
/** the realtime min update interval */
readonly minInterval?: number;
};
The DOM object should have the attribute
datetime
with date formatted string.
- register
register(locale, localeFunc)
, register a new locale, build-in locale contains:en_US
,zh_CN
, all locales here.
You can register your own language with register
API.
const localeFunc = (number: number, index: number, totalSec: number): [string, string] => {
// number: the timeago / timein number;
// index: the index of array below;
// totalSec: total seconds between date to be formatted and today's date;
return [
['just now', 'right now'],
['%s seconds ago', 'in %s seconds'],
['1 minute ago', 'in 1 minute'],
['%s minutes ago', 'in %s minutes'],
['1 hour ago', 'in 1 hour'],
['%s hours ago', 'in %s hours'],
['1 day ago', 'in 1 day'],
['%s days ago', 'in %s days'],
['1 week ago', 'in 1 week'],
['%s weeks ago', 'in %s weeks'],
['1 month ago', 'in 1 month'],
['%s months ago', 'in %s months'],
['1 year ago', 'in 1 year'],
['%s years ago', 'in %s years']
][index];
};
// register your locale with timeago
register('my-locale', localeFunc);
// use it
format('2016-06-12', 'my-locale');
Contributions
- The website is based on rmm5t/jquery-timeago which is a nice and featured project but it depends on jQuery.
- locale translations: The library needs more locale translations. You can:
- Open an issue to write the locale translations, or submit a pull request. How to ? see locales translation.
- Please test the locale by exec
npm test
. How to write test cases, see locales test cases.
LICENSE
MIT@hustcc