Автоматическое форматирование дат

Автоматическое форматирование дат — основная возможность timeago.js. Библиотека самостоятельно вычисляет временной интервал между переданной датой и текущим моментом, подбирает подходящую единицу измерения и формирует строку на нужном языке. При этом вся логика вычислений скрыта внутри библиотеки.

Базовый принцип работы

Когда вызывается format(date), библиотека выполняет следующие шаги:

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

Таблица автоматических интервалов

Разница Результат (en) Результат (ru)
< 45 секунд just now только что
45с – 89с 1 minute ago 1 минуту назад
90с – 44 мин 30с X minutes ago X минут назад
44м 30с – 89 мин 1 hour ago 1 час назад
90м – 21ч 30м X hours ago X часов назад
21ч 30м – 35ч 30м 1 day ago 1 день назад
35ч 30м – 25.5 дней X days ago X дней назад
25.5 – 45 дней 1 month ago 1 месяц назад
45 – 319 дней X months ago X месяцев назад
319 – 547 дней 1 year ago 1 год назад
> 547 дней X years ago X лет назад

Автоматический выбор единицы измерения

Нет необходимости вручную считать секунды, минуты или дни. Достаточно передать любое представление даты:

import { format } from 'timeago.js';

// 10 секунд назад
format(Date.now() - 10000);
// → "10 seconds ago"

// 5 минут назад
format(Date.now() - 300000);
// → "5 minutes ago"

// 3 часа назад
format(Date.now() - 10800000);
// → "3 hours ago"

// 2 дня назад
format(Date.now() - 172800000);
// → "2 days ago"

Автоматическое обновление через render()

Функция format выполняет разовое форматирование. Для автоматического обновления в реальном времени предназначена функция render.

HTML:

<time class="post-date" datetime="2025-05-26T12:00:00Z"></time>

Jav * aScript:

import { render } from 'timeago.js';

const nodes = document.querySelectorAll('.post-date');
render(nodes, 'ru');

После вызова render:

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

Интервалы автоматического обновления

Библиотека подстраивает частоту обновления под текущий временной интервал:

Текущее отображение Интервал обновления
Только что / секунды ~10 секунд
Минуты ~1 минута
Часы ~1 час
Дни и более ~1 день

Это умная оптимизация: нет смысла обновлять “2 дня назад” каждые 10 секунд.

Формат вывода для прошлого и будущего

Библиотека автоматически определяет направление времени:

// Прошедшее
format(Date.now() - 60000, 'ru');
// → "1 минуту назад"

// Будущее
format(Date.now() + 60000, 'ru');
// → "через 1 минуту"

Это позволяет использовать одну и ту же функцию как для дат публикации, так и для дедлайнов.

Форматирование с опорной точкой

Иногда требуется вычислить разницу не относительно текущего момента, а относительно другой даты:

import { format } from 'timeago.js';

const base = new Date('2025-06-01T00:00:00Z');
const target = new Date('2025-05-26T00:00:00Z');

format(target, 'ru', { relativeDate: base });
// → "5 дней назад"

Числа в строках форматирования

В строках локали используется плейсхолдер %s, который заменяется числом:

%s минут назад → 5 минут назад
через %s часов → через 3 часов

Локали с множественными формами дополнительно учитывают грамматику языка.

Особенности русской грамматики

Автоматическое форматирование на русском языке учитывает правила согласования числительных:

1 минуту назад
2 минуты назад
5 минут назад
21 минуту назад

Эта логика реализована внутри функции русской локали, которая анализирует последнюю цифру числа.

Форматирование без DOM

Функция format чисто функциональна — она не изменяет DOM и не создаёт таймеров. Это делает её удобной для:

  • серверного рендеринга;
  • шаблонизаторов;
  • предварительного рендеринга в SSR;
  • тестирования.
const label = format(post.createdAt, 'ru');
// используется в шаблоне или передаётся в компонент

Автоматический выбор языка через navigator.language

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

import { format } from 'timeago.js';

const locale = navigator.language.startsWith('ru') ? 'ru' : 'en_US';

format(new Date(), locale);

Форматирование в списке элементов

import { format } from 'timeago.js';

const posts = [
  { title: 'Первый пост', createdAt: '2025-05-26T08:00:00Z' },
  { title: 'Второй пост', createdAt: '2025-05-25T14:00:00Z' },
  { title: 'Третий пост', createdAt: '2025-05-20T10:00:00Z' },
];

posts.forEach(post => {
  console.log(`${post.title}: ${format(post.createdAt, 'ru')}`);
});

Результат:

Первый пост: 4 часа назад
Второй пост: 22 часа назад
Третий пост: 6 дней назад
Оглавление