Что такое timeago.js

timeago.js — компактная Javascript-библиотека для преобразования даты и времени в человекочитаемый относительный формат. Вместо точного времени вроде:

2025-05-26T10:30:00Z

библиотека позволяет выводить:

5 минут назад
2 часа назад
только что
через 3 дня

Подобный формат активно используется в:

  • социальных сетях;
  • мессенджерах;
  • блогах;
  • комментариях;
  • новостных сайтах;
  • панелях уведомлений;
  • системах мониторинга;
  • административных интерфейсах.

Главная задача timeago.js — автоматическое вычисление временной разницы между текущим моментом и указанной датой с последующим выводом удобной текстовой формы.

Основные возможности timeago.js

Преобразование даты в относительное время

Библиотека автоматически вычисляет:

  • секунды;
  • минуты;
  • часы;
  • дни;
  • недели;
  • месяцы;
  • годы.

Пример:

import { format } from 'timeago.js';

format('2025-05-26 12:00:00');

Результат:

3 часа назад

Поддержка будущего времени

timeago.js работает не только с прошедшими событиями.

Пример:

format('2025-06-01');

Результат:

через 5 дней

Это удобно для:

  • таймеров;
  • дедлайнов;
  • событий календаря;
  • публикаций;
  • запланированных задач.

Автоматическое обновление времени

Библиотека умеет самостоятельно обновлять отображение времени в DOM.

Например:

1 минуту назад

через некоторое время автоматически станет:

2 минуты назад

без ручного обновления страницы.

Локализация

timeago.js поддерживает множество языков:

  • русский;
  • английский;
  • немецкий;
  • французский;
  • китайский;
  • японский;
  • испанский;
  • и другие.

Можно создавать собственные локали.

Минимальный размер

Библиотека очень лёгкая и не перегружает приложение. Это важно для:

  • frontend-разработки;
  • мобильных интерфейсов;
  • SPA-приложений;
  • высоконагруженных проектов.

Установка библиотеки

Установка через npm

npm install timeago.js

Установка через yarn

yarn add timeago.js

Подключение через CDN

<script src="https://unpkg.com/timeago.js/dist/timeago.min.js"></script>

Архитектура библиотеки

timeago.js строится вокруг нескольких основных функций:

Функция Назначение
format() Форматирование даты
render() Автоматическое обновление DOM
cancel() Остановка обновления
register() Регистрация локали

Форматирование времени через format()

Базовый пример

import { format } from 'timeago.js';

const result = format('2025-05-26 14:00:00');

console.log(result);

Результат:

2 часа назад

Какие значения принимает format()

Функция поддерживает:

Строку даты

format('2025-05-26');

Timestamp

format(Date.now() - 1000 * 60);

Объект Date

format(new Date());

Принцип вычисления времени

Библиотека:

  1. Получает текущую дату.
  2. Вычисляет разницу.
  3. Определяет единицу времени.
  4. Формирует текст.

Например:

format(Date.now() - 3000);

Разница:

3 секунды

Результат:

3 секунды назад

Поддерживаемые временные интервалы

timeago.js автоматически переключается между единицами времени.

Секунды

только что
10 секунд назад

Минуты

1 минуту назад
15 минут назад

Часы

2 часа назад
12 часов назад

Дни

1 день назад
5 дней назад

Недели

2 недели назад

Месяцы

3 месяца назад

Годы

2 года назад

Использование локализации

Русский язык

import { format } from 'timeago.js';

format('2025-05-26', 'ru');

Английский язык

format('2025-05-26', 'en_US');

Работа с render()

Функция render() используется для автоматического обновления времени внутри HTML-элементов.

Пример HTML

<div class="time" datetime="2025-05-26T10:00:00"></div>

Подключение render()

import { render } from 'timeago.js';

const nodes = document.querySelectorAll('.time');

render(nodes, 'ru');

Что делает render()

Функция:

  • считывает атрибут datetime;
  • вычисляет разницу;
  • вставляет текст;
  • автоматически обновляет содержимое.

Автоматическое обновление DOM

После запуска:

render(nodes);

обновление времени происходит автоматически через внутренние таймеры.

Например:

59 секунд назад

через секунду станет:

1 минуту назад

Использование с одним элементом

const node = document.querySelector('.time');

render(node);

Использование с массивом элементов

const items = document.querySelectorAll('.time');

render(items);

Остановка обновления через cancel()

Иногда требуется прекратить автоматическое обновление.

Пример:

import { cancel } from 'timeago.js';

cancel();

Зачем нужен cancel()

Это особенно важно:

  • при уничтожении компонентов;
  • в SPA-приложениях;
  • при переходах между страницами;
  • для предотвращения утечек памяти.

Работа в React

Простой пример

import { format } from 'timeago.js';

function Post({ createdAt }) {
  return (
    <span>
      {format(createdAt, 'ru')}
    </span>
  );
}

Автообновление в React

import { useEffect, useRef } from 'react';
import { render, cancel } from 'timeago.js';

function Time({ date }) {
  const ref = useRef();

  useEffect(() => {
    render(ref.current, 'ru');

    return () => cancel(ref.current);
  }, []);

  return (
    <time ref={ref} datetime={date}></time>
  );
}

Работа во Vue

<template>
  <time ref="time" :datetime="date"></time>
</template>

<script setup>
import { onMounted, onBeforeUnmount, ref } from 'vue';
import { render, cancel } from 'timeago.js';

const props = defineProps({
  date: String
});

const time = ref(null);

onMounted(() => {
  render(time.value, 'ru');
});

onBeforeUnmount(() => {
  cancel(time.value);
});
</script>

Работа в Angular

import { format } from 'timeago.js';

export class AppComponent {
  createdAt = format('2025-05-26');
}

Создание собственной локали

Библиотека позволяет полностью переопределять правила отображения времени.

Регистрация локали

import { register } from 'timeago.js';

register('custom', (number, index) => {
  return [
    ['только что', 'прямо сейчас'],
    ['%s секунд назад', 'через %s секунд'],
    ['1 минуту назад', 'через 1 минуту'],
    ['%s минут назад', 'через %s минут']
  ][index];
});

Использование своей локали

format(Date.now() - 10000, 'custom');

Структура локализации

Функция локали получает:

Аргумент Назначение
number Количество единиц времени
index Индекс временного интервала

Индексы временных интервалов

Индекс Интервал
0 Сейчас
1 Секунды
2 1 минута
3 Минуты
4 1 час
5 Часы
6 1 день
7 Дни
8 1 неделя
9 Недели
10 1 месяц
11 Месяцы
12 1 год
13 Годы

Поддержка ISO-дат

timeago.js корректно работает с ISO 8601.

Пример:

format('2025-05-26T12:00:00Z');

Работа с Unix timestamp

format(1716720000000);

Работа с часовыми поясами

Библиотека использует встроенные механизмы Javascript Date.

Следовательно:

  • временные зоны обрабатываются браузером;
  • UTC поддерживается;
  • локальное время учитывается автоматически.

Использование в SSR

При серверном рендеринге:

  • время может отличаться между сервером и клиентом;
  • возможен гидрационный конфликт.

Поэтому render() обычно запускают только на клиенте.

Оптимизация производительности

Проблема большого количества таймеров

Если на странице сотни элементов времени:

<time></time>
<time></time>
<time></time>

каждый может обновляться отдельно.

Способы оптимизации

Ленивый рендеринг

Обновлять только видимые элементы.

Виртуализация списков

Особенно важно для:

  • чатов;
  • комментариев;
  • новостных лент.

Отмена обновлений

cancel(node);

при удалении элемента из DOM.

Типичные сценарии использования

Социальные сети

5 минут назад
2 часа назад

Комментарии

только что

Уведомления

1 секунду назад

Онлайн-статусы

был в сети 3 минуты назад

Отличие от Intl.RelativeTimeFormat

Современный Javascript имеет встроенный API:

Intl.RelativeTimeFormat

Однако timeago.js:

  • проще в использовании;
  • содержит готовую логику вычислений;
  • умеет обновлять DOM;
  • имеет готовые локали;
  • не требует ручного расчёта времени.

Сравнение с Intl.RelativeTimeFormat

Возможность timeago.js Intl.RelativeTimeFormat
Автоматический расчёт Да Нет
DOM-обновление Да Нет
Готовые локали Да Частично
Простота использования Высокая Средняя
Размер Очень маленький Встроен в браузер

Сравнение с Moment.js

Moment.js значительно тяжелее и предназначен для комплексной работы с датами.

timeago.js решает только одну задачу:

relative time formatting

За счёт этого библиотека:

  • быстрее;
  • легче;
  • проще;
  • удобнее для frontend-интерфейсов.

Преимущества timeago.js

Минимальный размер

Подходит для production-сборок.

Простое API

Всего несколько основных функций.

Автоматическое обновление

Не требуется писать собственные таймеры.

Хорошая поддержка локализации

Можно легко создавать свои переводы.

Работа с DOM

Редкая возможность среди библиотек форматирования времени.

Ограничения библиотеки

Не является полноценной date-библиотекой

Нет:

  • сложной арифметики дат;
  • календарных вычислений;
  • timezone API;
  • парсинга нестандартных форматов.

Ограниченная кастомизация интервалов

Для сложных правил может потребоваться собственная локаль.

Зависимость от Date

Все ограничения объекта Date Javascript сохраняются.

Когда использовать timeago.js

Библиотека особенно полезна:

  • в интерфейсах реального времени;
  • в социальных приложениях;
  • в чатах;
  • в системах уведомлений;
  • в административных панелях;
  • в SPA;
  • в мобильных web-приложениях.

Когда timeago.js не подходит

Библиотека плохо подходит для:

  • сложной работы с часовыми поясами;
  • бизнес-календарей;
  • финансовых систем;
  • математических операций с датами;
  • enterprise-систем планирования.

В подобных случаях обычно используют:

  • date-fns;
  • Luxon;
  • Day.js;
  • Temporal;
  • Moment.js (в legacy-проектах).

Внутренний принцип работы

Библиотека:

  1. Получает timestamp.
  2. Сравнивает с Date.now().
  3. Вычисляет разницу в секундах.
  4. Подбирает интервал.
  5. Формирует строку локализации.
  6. Планирует следующее обновление.

Пример полного использования

HTML

<time class="post-time" datetime="2025-05-26T10:00:00"></time>

Javascript

import { render } from 'timeago.js';

const elements = document.querySelectorAll('.post-time');

render(elements, 'ru');

Результат

3 часа назад

с автоматическим обновлением без перезагрузки страницы.

Оглавление