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

В библиотеке Pikaday форматирование даты основано на строковых шаблонах, состоящих из специальных токенов. Эти токены определяют, как именно будет представлена дата в инпуте, при выводе пользователю, а также при программной обработке значения. Механизм форматирования тесно связан с принципами, знакомыми по библиотекам вроде Moment.js, однако в Pikaday он реализован в упрощённом и автономном виде, достаточном для задач datepicker-компонента.

Общая структура форматирования

Формат даты задаётся строкой, где каждый токен отвечает за отдельный компонент даты:

  • день
  • месяц
  • год
  • дополнительные символы (разделители, текстовые вставки)

Пример базового формата:

new Pikaday({
    field: document.getElementById('date'),
    format: 'DD.MM.YYYY'
});

В данном случае строка DD.MM.YYYY интерпретируется как:

  • DD — день месяца с ведущим нулём
  • MM — месяц с ведущим нулём
  • YYYY — четырёхзначный год

Результат: 05.01.2026

Основные токены

День месяца

D

День месяца без ведущего нуля.

Примеры:

  • 1
  • 9
  • 31

DD

День месяца с ведущим нулём.

Примеры:

  • 01
  • 09
  • 31

Используется в большинстве пользовательских интерфейсов, где требуется фиксированная ширина поля.

Месяц

M

Месяц без ведущего нуля.

Примеры:

  • 1 (январь)
  • 2 (февраль)
  • 12 (декабрь)

MM

Месяц с ведущим нулём.

Примеры:

  • 01
  • 02
  • 12

MMM

Сокращённое текстовое название месяца.

Примеры:

  • Jan
  • Feb
  • Dec

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

MMMM

Полное название месяца.

Примеры:

  • January
  • February
  • December

Год

YY

Двузначный формат года.

Примеры:

  • 26
  • 99
  • 04

YYYY

Четырёхзначный формат года.

Примеры:

  • 2026
  • 1999
  • 2004

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

День недели

D (в контексте недели)

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

dd

Сокращённое название дня недели.

Примеры:

  • Mo
  • Tu
  • We

ddd

Более расширенное сокращение.

Примеры:

  • Mon
  • Tue
  • Wed

dddd

Полное название дня недели.

Примеры:

  • Monday
  • Tuesday
  • Wednesday

Локализация этих значений задаётся через параметр i18n:

new Pikaday({
    field: document.getElementById('date'),
    i18n: {
        weekdays: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
        weekdaysShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
        months: ['January', 'February', 'March', 'April', 'May', 'June',
                  'July', 'August', 'September', 'October', 'November', 'December']
    }
});

Разделители и литералы

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

Примеры:

Точка как разделитель

format: 'DD.MM.YYYY'

Результат:

05.01.2026

Косая черта

format: 'DD/MM/YYYY'

Результат:

05/01/2026

Текстовые вставки

format: 'DD [day of] MMMM YYYY'

Результат:

05 day of January 2026

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

Приоритет токенов и разбор строки

При обработке строки форматирования Pikaday использует последовательный разбор слева направо. Токены распознаются по максимальному совпадению длины.

Например:

  • MMMM будет обработан раньше, чем MM или M
  • DD имеет приоритет над D

Это предотвращает неоднозначность при разборе строки:

format: 'D MMMM'

Здесь:

  • D — день без нуля
  • MMMM — полное название месяца

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

Pikaday позволяет задавать формат динамически, что важно для адаптивных интерфейсов и мультиязычных приложений.

Пример переключения формата

const picker = new Pikaday({
    field: document.getElementById('date'),
    format: 'DD.MM.YYYY'
});

// изменение формата в рантайме
picker.config.format = 'YYYY-MM-DD';

После изменения формата отображение значения в input будет автоматически адаптировано при следующем выборе даты.

Форматирование и парсинг значения

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

При вводе значения вручную Pikaday пытается сопоставить строку с заданным форматом:

new Pikaday({
    field: document.getElementById('date'),
    format: 'DD.MM.YYYY'
});

Если пользователь вводит:

05.01.2026

библиотека разбивает строку по шаблону:

  • 05 → день
  • 01 → месяц
  • 2026 → год

И формирует объект:

new Date(2026, 0, 5)

Если формат не совпадает, результат может быть Invalid Date.

Ограничения и особенности токенов

Отсутствие арифметики и вычислений

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

DD+1.MM.YYYY

Форматирование строго декларативно.

Чувствительность к регистру

Токены регистрозависимы:

  • MM — месяц
  • mm — не является валидным токеном месяца и может быть проигнорирован или интерпретирован как литерал

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

Ограниченная расширяемость

В отличие от более тяжёлых решений, Pikaday не предоставляет полноценной системы кастомных токенов. Расширение возможно только через:

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

Совместимость с локализацией

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

Пример:

format: 'DD MMMM YYYY'
  • EN: 05 January 2026
  • RU: 05 Январь 2026

Таким образом, формат и локализация работают совместно, но независимо друг от друга: формат определяет структуру, локализация — содержимое текстовых элементов.

Комбинирование токенов в сложных форматах

В реальных интерфейсах часто используются составные форматы:

format: 'dddd, DD MMMM YYYY'

Результат:

Monday, 05 January 2026

Или более прикладной вариант:

format: '[Date:] DD.MM.YYYY [Time slot selected]'

Результат:

Date: 05.01.2026 Time slot selected

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

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

Если строка содержит неизвестные последовательности символов, Pikaday трактует их как литералы.

Пример:

format: 'DD.QQ.YYYY'

Результат:

05.QQ.2026

Это поведение позволяет безопасно использовать пользовательские строки без риска поломки форматирования, но требует внимательности при проектировании шаблонов.

Практическая модель интерпретации формата

Процесс обработки формата можно представить как последовательность шагов:

  1. Чтение строки формата
  2. Поиск известных токенов
  3. Замена токенов значениями даты
  4. Оставление остальных символов без изменений
  5. Формирование итоговой строки

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

Оглавление