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

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

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

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

Форматирование в Flatpickr строится на двух типах элементов:

  • литералы — обычные символы, которые выводятся без изменений;
  • токены — специальные последовательности символов, начинающиеся с буквы (или группы букв), которые заменяются значениями даты.

Пример формата:

dateFormat: "Y-m-d"

Результат:

2026-05-30

Здесь:

  • Y — год в 4-значном формате
  • m — месяц с ведущим нулём
  • d — день месяца с ведущим нулём

Год

Flatpickr поддерживает несколько вариантов отображения года:

  • Y — полный год (2026)
  • y — последние две цифры года (26)

Примеры:

"Y"  -> 2026
"y"  -> 26

Год всегда извлекается из объекта Date без преобразования временной зоны.

Месяц

Для месяцев используется несколько токенов в зависимости от формата отображения:

  • m — месяц (01–12)
  • n — месяц (1–12 без ведущего нуля)
  • F — полное название месяца (January, February и т.д.)
  • M — короткое название месяца (Jan, Feb и т.д.)

Примеры:

"m" -> 05
"n" -> 5
"F" -> May
"M" -> May (или сокращение в локали)

При использовании F и M учитывается текущая локализация Flatpickr, что позволяет автоматически адаптировать названия месяцев под язык интерфейса.

День месяца

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

  • d — день месяца с ведущим нулём (01–31)
  • j — день месяца без ведущего нуля (1–31)
  • D — сокращённое название дня недели (Mon, Tue)
  • l — полное название дня недели (Monday, Tuesday)

Примеры:

"d" -> 09
"j" -> 9
"D" -> Mon
"l" -> Monday

День недели

Flatpickr позволяет гибко управлять отображением дня недели:

  • D — короткое название дня недели
  • l — полное название дня недели
  • w — числовой индекс дня недели (0–6, начиная с воскресенья)

Пример:

"w" -> 6

Часы

Часовой формат зависит от выбранного режима (12-часовой или 24-часовой), но токены остаются универсальными:

  • H — часы в 24-часовом формате (00–23)
  • G — часы без ведущего нуля (0–23)
  • h — часы в 12-часовом формате (01–12)
  • g — часы в 12-часовом формате без ведущего нуля (1–12)

Примеры:

"H" -> 18
"G" -> 8
"h" -> 06
"g" -> 6

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

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

  • i — минуты с ведущим нулём (00–59)
  • S — секунды с ведущим нулём (00–59)

Примеры:

"i" -> 05
"S" -> 09

Полный формат времени

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

"Y-m-d H:i"

Результат:

2026-05-30 18:45

Или с 12-часовым форматом:

"Y-m-d h:i"
2026-05-30 06:45

Ам и Пм (AM/PM)

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

  • K — AM/PM в верхнем регистре
  • k — am/pm в нижнем регистре

Примеры:

"h:i K" -> 06:45 PM
"h:i k" -> 06:45 pm

Порядковые суффиксы

Для отображения порядковых числительных (например, 1st, 2nd, 3rd) используется токен:

  • S — суффикс дня месяца

Пример:

"dS F" -> 1st May

Поведение зависит от локали, так как суффиксы различаются в разных языках.

Экранирование символов

Любой символ, который не должен интерпретироваться как токен, экранируется с помощью обратного слэша:

dateFormat: "Y-m-d \\at H:i"

Результат:

2026-05-30 at 18:45

Без экранирования слово at было бы попыткой интерпретации как токены.

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

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

  • названия месяцев (F, M)
  • названия дней недели (D, l)
  • суффиксы (S)

Flatpickr использует объект локали, где задаются массивы названий:

locale: {
  months: ["January", "February", ...],
  weekdays: ["Sunday", "Monday", ...]
}

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

Частые комбинации форматов

На практике часто используются следующие шаблоны:

"Y-m-d"              // 2026-05-30
"d.m.Y"              // 30.05.2026
"j F Y"              // 30 May 2026
"D, d M Y"          // Sat, 30 May 2026
"Y-m-d H:i:S"       // 2026-05-30 18:45:09
"h:i K"             // 06:45 PM

Каждый из этих шаблонов представляет определённый уровень детализации даты и времени, от минимального до полного.

Особенности обработки формата

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

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

Динамическое изменение формата

Формат может изменяться после инициализации:

instance.set("dateFormat", "d.m.Y");

Это приводит к немедленному изменению отображения выбранной даты без пересоздания компонента.

Сочетание токенов с пользовательским вводом

При включённой опции ручного ввода (allowInput) формат токенов используется и для парсинга строки. Это означает, что:

  • формат определяет, как строка преобразуется в Date;
  • несоответствие формата приводит к ошибке парсинга;
  • структура строки должна строго соответствовать токенам.

Ограничения системы форматирования

Система токенов имеет ряд особенностей:

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

Расширенные сценарии использования

В сложных интерфейсах форматирование применяется не только для отображения, но и для синхронизации данных:

  • отображение в инпутах форм;
  • генерация строк для API;
  • логирование событий выбора даты;
  • формирование ключей для кэширования.

В таких случаях формат становится частью контрактного слоя между UI и бизнес-логикой приложения.

Оглавление