Работа с временными зонами

Библиотека Pikaday построена вокруг стандартного объекта Date языка JavaScript, что определяет ключевое ограничение: внутри ядра отсутствует собственная модель временных зон. Все операции с датами опираются на поведение среды выполнения (браузера или Node.js), где Date всегда хранит момент времени в UTC, но отображает его через локальную временную зону.

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

Внутренняя модель даты в JavaScript и влияние на календарь

Объект Date хранит абсолютное значение времени в миллисекундах от эпохи Unix (UTC), однако методы доступа делятся на две группы:

локальные: getFullYear(), getMonth(), getDate()
UTC-версии: getUTCFullYear(), getUTCMonth(), getUTCDate()

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

отображаемый день зависит от временной зоны устройства;
границы месяцев могут «съезжать» при преобразовании UTC;
серверные даты без временной зоны интерпретируются как локальные.

Основная проблема временных зон в календарях

Типовой источник ошибок возникает при передаче даты в формате ISO:

2026-06-01

и интерпретации её JavaScript как:

new Date("2026-06-01")

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

В результате:

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

Стратегии нормализации дат

Хранение только календарной даты без времени

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

YYYY-MM-DD

При таком подходе Pikaday используется только как UI-компонент, а преобразование выполняется отдельно.

Пример нормализации:

function toISODateString(date) {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, "0");
  const day = String(date.getDate()).padStart(2, "0");
  return `${year}-${month}-${day}`;
}

Такой формат исключает влияние временной зоны полностью.

Использование UTC для устранения смещений

Альтернативная стратегия — фиксировать даты в UTC:

const utcDate = new Date(Date.UTC(
  date.getFullYear(),
  date.getMonth(),
  date.getDate()
));

Преимущества:

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

Недостатки:

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

Смешанный подход (UI локальный + хранение UTC)

Наиболее распространённая архитектура:

Pikaday работает в локальной временной зоне;
в хранилище сохраняется нормализованный UTC-формат;
отображение выполняется через локальное преобразование.

Схема:

UI (Pikaday) → Date (local) → normalize → UTC string → server
server → UTC string → Date → local display (Pikaday)

Конфигурация Pikaday и моментальная интеграция

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

Пример конфигурации:

new Pikaday({
  field: document.getElementById("date"),
  format: "YYYY-MM-DD",
  toString(date, format) {
    return moment(date).format(format);
  },
  parse(dateString, format) {
    return moment(dateString, format).toDate();
  }
});

В данном случае временная зона определяется настройками Moment.js, что может быть критично при работе с серверными UTC-датами.

Проблемы перехода на летнее и зимнее время

При использовании локальных дат возникают ошибки, связанные с переходом на DST (Daylight Saving Time):

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

Pikaday, опираясь на Date, наследует эти особенности без дополнительной обработки.

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

Диапазоны дат и временные зоны

При использовании minDate и maxDate в Pikaday важно учитывать, что сравнение происходит по объектам Date:

new Pikaday({
  field: document.getElementById("date"),
  minDate: new Date(2026, 0, 1),
  maxDate: new Date(2026, 11, 31)
});

Проблема возникает при генерации этих значений из UTC-источников:

new Date("2026-01-01")

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

Корректный вариант:

new Date(2026, 0, 1)

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

Передача дат на сервер

Основная ошибка интеграции календарей заключается в передаче «сырых» объектов Date.

Рекомендуемая модель передачи:

строка ISO без времени: YYYY-MM-DD;
либо timestamp в UTC;
либо объект { year, month, day }.

Пример преобразования:

const payload = {
  date: toISODateString(picker.getDate())
};

Обратное восстановление даты из строки

При получении данных от сервера важно избегать автоматического парсинга строк:

const [year, month, day] = serverDate.split("-");
const date = new Date(year, month - 1, day);

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

Поведение Pikaday при смене временной зоны устройства

При изменении системной временной зоны:

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

Это поведение обусловлено отсутствием неизменяемого календарного типа данных в JavaScript.