Базовые токены форматирования

Day.js использует строковые шаблоны форматирования, основанные на токенах, где каждый символ или группа символов соответствует определённому фрагменту даты и времени. Механика построена на сопоставлении шаблона и внутреннего объекта даты, после чего формируется строковое представление без дополнительной обработки.

Ключевая особенность системы токенов заключается в строгой чувствительности к регистру. Например, MM и mm обозначают разные сущности: месяц и минуты соответственно. Ошибка в регистре приводит к некорректному результату, так как библиотека не выполняет автоматического исправления или угадывания намерения.

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

Год

Для работы с годом применяются следующие базовые токены:

  • YYYY — полный четырёхзначный год (например, 2026)
  • YY — сокращённый формат года (например, 26)

При форматировании:

dayjs().format('YYYY') // 2026
dayjs().format('YY')   // 26

Четырёхзначный формат используется как стандартный для хранения и отображения дат, поскольку исключает неоднозначность при обработке исторических или будущих значений.

Месяц

Месяцы представлены несколькими вариантами отображения:

  • MM — числовой формат с ведущим нулём (01–12)
  • M — числовой формат без ведущего нуля (1–12)
  • MMMM — полное название месяца (January, February и т.д., зависит от локали)
  • MMM — сокращённое название месяца (Jan, Feb и т.д.)

Примеры:

dayjs().format('MM')   // 05
dayjs().format('M')    // 5
dayjs().format('MMM')  // May
dayjs().format('MMMM') // May

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

День месяца

Для представления дня используются следующие токены:

  • DD — день с ведущим нулём (01–31)
  • D — день без ведущего нуля (1–31)
dayjs().format('DD') // 09
dayjs().format('D')  // 9

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

День недели

Для дня недели применяются текстовые и числовые представления:

  • d — числовой индекс дня недели (0–6, зависит от локали)
  • dd — короткое название дня
  • ddd — расширенное сокращение
  • dddd — полное название дня недели
dayjs().format('dd')   // Su
dayjs().format('ddd')  // Sun
dayjs().format('dddd') // Sunday

При работе с этим блоком критически важна локализация, поскольку названия дней могут существенно отличаться между языками.

Часы

Часовой компонент поддерживает два формата: 24-часовой и 12-часовой.

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

  • HH — часы с ведущим нулём (00–23)
  • H — часы без ведущего нуля (0–23)

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

  • hh — часы с ведущим нулём (01–12)
  • h — часы без ведущего нуля (1–12)
dayjs().format('HH') // 18
dayjs().format('H')  // 18
dayjs().format('hh') // 06 (при вечернем времени)
dayjs().format('h')  // 6

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

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

Минуты и секунды используют одинаковую структуру токенов:

  • mm — минуты с ведущим нулём (00–59)
  • m — минуты без ведущего нуля (0–59)
  • ss — секунды с ведущим нулём (00–59)
  • s — секунды без ведущего нуля (0–59)
dayjs().format('mm') // 04
dayjs().format('ss') // 09

Важно различать MM (месяцы) и mm (минуты), так как это одна из наиболее частых причин ошибок при форматировании.

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

Для точного времени используются токены:

  • SSS — миллисекунды (000–999)
  • SS — первые две цифры миллисекунд (00–99, усечённое значение)
  • S — первая цифра миллисекунд
dayjs().format('SSS')

Этот уровень точности применяется в логировании, профилировании и обработке событий с высокой частотой.

AM/PM индикатор

Для 12-часового формата используется:

  • A — AM/PM в верхнем регистре
  • a — am/pm в нижнем регистре
dayjs().format('A') // AM
dayjs().format('a') // am

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

Символы разделителей и литералы

Любые символы, не являющиеся токенами, трактуются как литералы. Это позволяет строить читаемые строки формата:

dayjs().format('YYYY-MM-DD HH:mm:ss')

Результат:

2026-05-22 18:04:09

Если требуется использовать символ, который может конфликтовать с токенами, применяется экранирование через квадратные скобки:

dayjs().format('[Year:] YYYY')

Результат:

Year: 2026

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

Полноценные форматы обычно представляют собой комбинацию нескольких блоков:

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

Такая строка объединяет день недели, дату, месяц, год и время в одном выражении. Внутренняя обработка происходит последовательно: каждый токен заменяется соответствующим значением, после чего формируется итоговая строка без дополнительной постобработки.

Чувствительность к локализации

Токены, отвечающие за текстовое представление (месяцы, дни недели), зависят от подключённой локали. В базовой конфигурации используется английская локализация, однако подключение дополнительных языков изменяет вывод без изменения самого шаблона форматирования.

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

При разборе строки форматирования библиотека анализирует токены по длине, отдавая приоритет более длинным последовательностям. Это означает, что YYYY обрабатывается как единый токен, а не как четыре отдельных символа Y.

Такой подход предотвращает неоднозначность и обеспечивает стабильность интерпретации даже при сложных форматах, содержащих пересекающиеся паттерны.

Оглавление