# timeago.js **Repository Path**: hustcc/timeago.js ## Basic Information - **Project Name**: timeago.js - **Description**: timeago.js 是一个非常简洁、轻量级、小于 2kb 的很简洁的Javascript库,用来将datetime时间转化成类似于 "***时间前"的描述字符串,例如:“3小时前” - **Primary Language**: JavaScript - **License**: MIT - **Default Branch**: master - **Homepage**: http://timeago.org/ - **GVP Project**: No ## Statistics - **Stars**: 31 - **Forks**: 2 - **Created**: 2016-06-23 - **Last Updated**: 2024-06-21 ## Categories & Tags **Categories**: javascript-toolkits **Tags**: None ## README # 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 time `in` supported. - Real-time render supported. - Node and browser supported. - Well tested. [Official website](https://timeago.org/). React version here: [timeago-react](https://github.com/hustcc/timeago-react). Python version here: [timeago](https://github.com/hustcc/timeago). [![Build Status](https://img.shields.io/travis/hustcc/timeago.js.svg)](https://travis-ci.org/hustcc/timeago.js) [![Coverage Status](https://coveralls.io/repos/github/hustcc/timeago.js/badge.svg?branch=master)](https://coveralls.io/github/hustcc/timeago.js?branch=master) [![npm Version](https://img.shields.io/npm/v/timeago.js.svg)](https://www.npmjs.com/package/timeago.js) [![CDNJS](https://img.shields.io/cdnjs/v/timeago.js.svg)](https://cdnjs.com/libraries/timeago.js) [![Dist gzip](https://img.badgesize.io/https://unpkg.com/timeago.js/dist/timeago.min.js?compression=gzip)](https://unpkg.com/timeago.js/dist/timeago.min.js) [![npm Download](https://img.shields.io/npm/dm/timeago.js.svg)](https://www.npmjs.com/package/timeago.js) [![npm License](https://img.shields.io/npm/l/timeago.js.svg)](https://www.npmjs.com/package/timeago.js) Such as ```plain 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 ```bash npm install timeago.js ``` - import ```ts import { format, render, cancel, register } from 'timeago.js'; ``` or import with `script` tag in html file and access global variable `timeago`. ```html ``` - example ```ts // format the time with locale format('2016-06-12', 'en_US'); ``` ## API There only 4 API below. - **format** > `format(date[, locale = 'en_US', opts])`, format a Date instance / timestamp / date string to string. ```ts 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', { relativeData: '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: ```html
``` Javascript code: ```ts 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: ```ts 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](src/lang). You can register your own language with `register` API. ```ts 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 1. The website is based on [rmm5t/jquery-timeago](https://github.com/rmm5t/jquery-timeago) which is a nice and featured project but it depends on jQuery. 2. **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](src/lang/). - Please **test** the locale by exec `npm test`. How to write test cases, see [locales test cases](__tests__/lang/). ## LICENSE MIT@[hustcc](https://github.com/hustcc)