Таблица токенов

Форматирование и разбор дат в Day.js основаны на системе токенов — специальных символов, которые описывают структуру вывода или парсинга даты. Каждый токен представляет собой отдельный компонент времени или форматирования, который подставляется при обработке объекта даты.

Day.js использует строковые шаблоны, где последовательности символов интерпретируются как инструкции для формирования строки даты.

Ключевые особенности:

  • токены чувствительны к регистру;
  • последовательность символов имеет значение;
  • нераспознанные символы выводятся как есть;
  • форматирование всегда опирается на объект даты Day.js.

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

dayjs().format('YYYY-MM-DD')

Годовые токены

Год представлен несколькими вариантами, различающимися уровнем детализации.

Токен Описание Пример
YYYY Полный год (4 цифры) 2026
YY Последние 2 цифры года 26
Y Год (ISO-совместимый формат) 2026

Особенность токена Y заключается в поддержке расширенных календарных систем и отрицательных лет.

Месяцы

Месяцы представлены как числовыми, так и текстовыми токенами.

Токен Описание Пример
MM Месяц с ведущим нулём 01–12
M Месяц без ведущего нуля 1–12
MMM Краткое название месяца Jan
MMMM Полное название месяца January

При локализации значения MMM и MMMM зависят от текущей языковой настройки Day.js.

Дни месяца и недели

Day.js различает день месяца и день недели как отдельные сущности.

День месяца

Токен Описание Пример
DD День с ведущим нулём 01–31
D День без ведущего нуля 1–31
Do День месяца с порядковым суффиксом 1st, 2nd, 3rd

Токен Do требует подключения дополнительного плагина advancedFormat.

День недели

Токен Описание Пример
d День недели (0–6) 0
dd Сокращённое название Su
ddd Краткое название Sun
dddd Полное название Sunday

Нумерация начинается с воскресенья (0), если не переопределена локалью.

Часы

Временные токены делятся на 12-часовой и 24-часовой форматы.

24-часовой формат

Токен Описание Пример
HH Часы (00–23) 14
H Часы (0–23) 4

12-часовой формат

Токен Описание Пример
hh Часы (01–12) 02
h Часы (1–12) 2
A AM/PM в верхнем регистре PM
a am/pm в нижнем регистре pm

Использование 12-часового формата требует обязательного указания AM/PM для однозначности времени.

Минуты и секунды

Токен Описание Пример
mm Минуты с ведущим нулём 05
m Минуты 5
ss Секунды с ведущим нулём 09
s Секунды 9

Эти токены применяются в большинстве временных форматов.

Миллисекунды

Токен Описание Пример
S Сотые доли секунды 0–9
SS Десятки миллисекунд 00–99
SSS Миллисекунды 000–999

Чем больше символов S, тем выше точность отображения.

Часовой пояс и смещения

Day.js не включает полноценную работу с часовыми поясами в базовой конфигурации, но через плагины добавляются дополнительные токены.

Токен Описание Пример
Z Смещение от UTC +05:00
ZZ Смещение без двоеточия +0500

Работа с часовыми поясами требует подключения utc и timezone плагинов.

Кварталы и недели года

Расширенные токены используются для бизнес-логики и аналитики.

Токен Описание Пример
Q Квартал года 1–4
Qo Порядковый квартал 1st–4th
W Неделя года 1–53
WW Неделя с ведущим нулём 01–53

Недели зависят от ISO-стандарта при использовании соответствующих настроек.

Экранирование токенов

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

Пример:

dayjs().format('[Сегодня:] DD-MM-YYYY')

Результат:

Сегодня: 23-05-2026

Скобки отключают парсинг содержимого внутри них.

Комбинирование токенов

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

Пример:

dayjs().format('dddd, DD MMMM YYYY, HH:mm:ss')

Результат:

Saturday, 23 May 2026, 14:05:09

Такие конструкции используются для генерации пользовательских строк отображения даты.

Особенности интерпретации

При разборе строки Day.js ориентируется на строгие соответствия токенов:

  • лишние символы игнорируются только вне токенов;
  • неоднозначные форматы требуют явного указания;
  • некорректные шаблоны возвращают Invalid Date.

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

dayjs('2026-99-99', 'YYYY-MM-DD')

Результат будет недопустимой датой.

Локализация токенов

Некоторые токены зависят от активной локали:

  • MMM / MMMM — названия месяцев;
  • ddd / dddd — дни недели;
  • A / a — формат AM/PM.

Подключение локали изменяет только текстовые представления, не влияя на числовую интерпретацию.

Расширенные форматы

При использовании плагинов появляются дополнительные токены:

  • X — Unix timestamp (секунды)
  • x — Unix timestamp (миллисекунды)

Пример:

dayjs().format('X')

Вывод:

1716471909

Эти токены применяются для интеграции с API и базами данных.

Практика составления форматов

Составление шаблонов требует баланса между читаемостью и точностью:

  • минимальные форматы подходят для API;
  • расширенные форматы используются в интерфейсах;
  • локализованные строки применяются в пользовательских представлениях.

Пример универсального формата:

YYYY-MM-DDTHH:mm:ssZ

Он соответствует ISO-подобной структуре и широко применяется в обмене данными.

Оглавление