Токены для времени

В Moment.js форматирование и разбор дат строятся вокруг системы токенов — специальных строковых маркеров, которые описывают, как именно интерпретировать или отображать компоненты даты и времени. Эти токены используются в методах format() и parse(), а также в ряде вспомогательных функций, связанных с локализацией и временем.

Токены в Moment.js — это строго определённые шаблоны, каждый из которых соответствует конкретной части даты или времени. Например:

  • YYYY — год в четырёхзначном формате
  • MM — месяц с ведущим нулём
  • DD — день месяца
  • HH — часы в 24-часовом формате
  • mm — минуты
  • ss — секунды

Токены чувствительны к регистру. MM (месяц) и mm (минуты) — разные сущности.

Токены года

Работа с годом представлена несколькими вариантами, отличающимися количеством цифр и форматом вывода:

  • YYYY — полный год (например, 2026)
  • YY — последние две цифры года (26)
  • Y — год по ISO-8601 (используется реже)

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

moment().format('YYYY');
moment().format('YY');

Особенность YYYY заключается в том, что он всегда возвращает четырёхзначное значение, даже для исторических дат, если они поддерживаются библиотекой.

Токены месяца

Месяцы в Moment.js представлены несколькими уровнями детализации:

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

Пример:

moment().format('MM');
moment().format('MMM');
moment().format('MMMM');

При использовании текстовых форм (MMM, MMMM) учитывается локализация, что позволяет выводить названия месяцев на разных языках.

Токены дня

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

  • D — день месяца (1–31)
  • DD — день с ведущим нулём (01–31)
  • Do — порядковый день месяца (1st, 2nd, 3rd и т.д.)

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

moment().format('Do MMMM');

День недели

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

  • d — день недели (0–6, где 0 — воскресенье)
  • dd — сокращённое название (Su, Mo)
  • ddd — более длинное сокращение (Sun, Mon)
  • dddd — полное название (Sunday, Monday)

Пример:

moment().format('dddd');
moment().format('ddd');

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

Токены времени (часы, минуты, секунды)

Часы

Moment.js поддерживает два формата часов:

  • H — 24-часовой формат без нуля (0–23)
  • HH — 24-часовой формат с нулём (00–23)
  • h — 12-часовой формат (1–12)
  • hh — 12-часовой формат с нулём
  • k — 24-часовой формат (1–24)
  • kk — 24-часовой формат с ведущим нулём (01–24)

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

  • m — минуты без нуля
  • mm — минуты с нулём
  • s — секунды без нуля
  • ss — секунды с нулём

Пример:

moment().format('HH:mm:ss');

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

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

  • S — сотые доли секунды (0–9)
  • SS — десятки миллисекунд (00–99)
  • SSS — полные миллисекунды (000–999)

Пример:

moment().format('SSS');

Утро и вечер (AM/PM)

Для 12-часового формата времени применяются:

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

Локализация влияет на представление этих значений, особенно в языках, где традиционно используется 24-часовой формат.

Часовой пояс

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

  • Z — смещение от UTC в формате +05:00
  • ZZ — смещение без двоеточия (+0500)

Пример:

moment().format('Z');

Эти токены особенно важны при работе с API и синхронизацией данных между системами.

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

Некоторые токены напрямую зависят от языка:

  • MMMM — название месяца
  • dddd — день недели
  • Do — порядковые числительные
  • A / a — обозначение времени суток

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

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

Если требуется вывести символы, которые совпадают с токенами, используется экранирование с помощью квадратных скобок:

moment().format('[Today is] YYYY-MM-DD');

Содержимое в [] не интерпретируется как токены и выводится буквально.

Разбор строки даты (Parsing tokens)

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

  • Формат должен строго соответствовать входной строке
  • Несоответствие токенов приводит к некорректному результату (Invalid date)

Пример:

moment('2026-05-21', 'YYYY-MM-DD');

При строгом режиме парсинга учитывается точное соответствие:

moment('21/05/2026', 'DD/MM/YYYY', true);

Третий параметр true включает strict parsing.

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

На практике токены редко используются по отдельности. Чаще всего они комбинируются в сложные шаблоны:

moment().format('dddd, Do MMMM YYYY, HH:mm:ss Z');

Такой шаблон включает:

  • день недели (dddd)
  • порядковый день (Do)
  • месяц (MMMM)
  • год (YYYY)
  • время (HH:mm:ss)
  • часовой пояс (Z)

Поведение при неверных токенах

Если Moment.js встречает неизвестный токен:

  • он интерпретируется как обычный текст
  • либо игнорируется при парсинге
  • либо приводит к Invalid date при строгом режиме

Пример:

moment().format('YYYY-QQ-MM');

Здесь QQ не является валидным токеном и будет обработан как текст.

Влияние локали на токены

Токены, возвращающие текст, полностью зависят от активной локали:

  • месяцы
  • дни недели
  • порядковые суффиксы

Изменение локали:

moment.locale('ru');
moment().format('dddd, Do MMMM');

В результате форматирование адаптируется под правила выбранного языка.

Токены в контексте производительности и поддержки

Хотя система токенов удобна, она имеет особенности:

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

Несмотря на это, токены остаются центральным механизмом работы с датами в Moment.js и определяют весь процесс преобразования даты в строку и обратно.

Оглавление