Работа со строковыми датами

Строковые даты — один из наиболее распространённых форматов входных данных, особенно при работе с API, базами данных и HTML-атрибутами. Функция format принимает строки и внутренне преобразует их через конструктор new Date(str). Это означает, что поддерживаются все форматы, которые корректно парсятся в браузере или Node.js.

Передача строки в format

import { format } from 'timeago.js';

format('2025-05-26T10:00:00Z', 'ru');
// → "4 часа назад"

Строка передаётся как первый аргумент — ровно так же, как Date или timestamp.

Поддерживаемые форматы строк

ISO 8601 — рекомендуемый формат

format('2025-05-26T10:00:00Z');          // UTC
format('2025-05-26T13:00:00+03:00');     // со смещением
format('2025-05-26T10:00:00.000Z');      // с миллисекундами
format('2025-05-26');                    // только дата

ISO 8601 поддерживается во всех современных браузерах и Node.js без исключений. Этот формат следует предпочитать при любой возможности.

RFC 2822

format('Mon, 26 May 2025 10:00:00 +0000');

Используется в HTTP-заголовках и почтовых протоколах.

Неформальные строки (ненадёжны)

format('May 26 2025');
format('2025/05/26');

Эти форматы работают в большинстве браузеров, но их поведение не стандартизировано и может различаться между платформами.

Строки из баз данных

MySQL возвращает даты в формате:

"2025-05-26 10:00:00"

Прямая передача такой строки нежелательна — браузеры расходятся в её интерпретации. Безопасный вариант:

const mysqlDate = '2025-05-26 10:00:00';

// Заменить пробел на T и добавить Z для UTC
format(new Date(mysqlDate.replace(' ', 'T') + 'Z'), 'ru');

PostgreSQL возвращает ISO-строки, пригодные для прямого использования:

format('2025-05-26T10:00:00.000Z', 'ru'); // ок

Строки из JSON-ответов API

Большинство REST API возвращают даты в ISO 8601:

{
  "id": 42,
  "createdAt": "2025-05-26T10:00:00.000Z"
}
const { createdAt } = await response.json();
format(createdAt, 'ru');

Если формат API отличается, рекомендуется нормализовать строку до ISO перед передачей.

Строки из атрибута datetime

При использовании render() библиотека читает атрибут datetime:

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

Строка из атрибута обрабатывается идентично строке в format. Стандарт HTML5 требует ISO 8601 для datetime — придерживайтесь этого соглашения.

Проблема строки “YYYY-MM-DD” без времени

format('2025-05-26');

Спецификация ECMAScript указывает, что строки формата YYYY-MM-DD интерпретируются как UTC полночь:

2025-05-26 → 2025-05-26T00:00:00.000Z

В браузере с часовым поясом UTC+3 это означает, что “26 мая” будет показываться как “3 часа назад” с 00:00 UTC, хотя пользователь ожидает “сегодня”.

Для избежания этой проблемы явно добавляйте время:

format('2025-05-26T00:00:00'); // локальное полночь (зависит от браузера)
format('2025-05-26T00:00:00Z'); // UTC полночь

Некорректные строки

format('not-a-date');
format('');
format('26-05-2025'); // формат DD-MM-YYYY не стандартизирован

Внутри библиотека выполняет new Date('not-a-date'), что возвращает Invalid Date. Результат форматирования будет некорректным.

Проверка перед форматированием:

function isoSafeFormat(str, locale = 'ru') {
  const d = new Date(str);
  if (isNaN(d.getTime())) return '';
  return format(d, locale);
}

Строки в разных локалях

Строки в локализованном формате не поддерживаются напрямую:

format('26 мая 2025');   // ненадёжно
format('26.05.2025');    // ненадёжно

Если данные приходят в таком формате (например, из пользовательского ввода), их нужно предварительно нормализовать:

// Пример преобразования DD.MM.YYYY → Date
function parseDotDate(str) {
  const [day, month, year] = str.split('.').map(Number);
  return new Date(year, month - 1, day);
}

format(parseDotDate('26.05.2025'), 'ru');

Строки в SSR

При серверном рендеринге строки из API безопасны — они не зависят от часового пояса сервера при правильном использовании ISO UTC:

// Сервер (Node.js)
const label = format('2025-05-26T10:00:00Z', 'ru');
// Результат детерминирован — UTC задан явно

Сравнение форматов строк по надёжности

Формат Надёжность Рекомендация
2025-05-26T10:00:00Z Высокая Использовать
2025-05-26T10:00:00+03:00 Высокая Использовать
2025-05-26T10:00:00.000Z Высокая Использовать
Mon, 26 May 2025 10:00:00 GMT Высокая Допустимо
2025-05-26 Средняя Осторожно (UTC)
May 26 2025 Средняя Проверять платформу
2025/05/26 Низкая Избегать
26.05.2025 Низкая Нормализовать
26-05-2025 Низкая Нормализовать
Оглавление