DateTimePicker

Кастомный date/time picker на TypeScript (Vite), который:

• работает поверх input полей,
• поддерживает single и multi (диапазон),
• поддерживает локализацию и пользовательские переводы,
• управляет значением поля через кнопку OK,
• корректно работает с часовыми поясами (опция timezone),
• адаптивное позиционирование на мобильных устройствах,
• предоставляет обертки для React, Vue и jQuery.

Установка

Использование как пакет NPM

Установите пакет из npm:

npm install glike35-date-time-picker

Импортируйте в вашем проекте:

import { DateTimePicker } from 'glike35-date-time-picker';

Пакетный CSS заскоуплен под dtp-* и не переопределяет глобальные body, form или обычные input.

Разработка

Если вы клонировали репозиторий и хотите внести изменения:

npm install          # установка зависимостей
npm run dev          # запуск сервера разработки
npm run build        # сборка проекта

CDN сборка

Пакет доступен через CDN (jsDelivr и unpkg). Подключите скрипт на странице:

Для разработки

<!-- через jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/glike35-date-time-picker@1/dist/date-time-picker.umd.js"></script>

<!-- через unpkg -->
<script src="https://unpkg.com/glike35-date-time-picker@1/dist/date-time-picker.umd.js"></script>

Для использования на проде

<!-- через jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/glike35-date-time-picker@1/dist/cdn/date-time-picker.min.js"></script>

<!-- через unpkg -->
<script src="https://unpkg.com/glike35-date-time-picker@1/dist/cdn/date-time-picker.min.js"></script>

После загрузки скрипта глобальная переменная DateTimePicker станет доступной. Используйте её для создания экземпляров:

<input type="text" id="my-date-input" placeholder="Выберите дату" />

<script>
  const picker = new DateTimePicker('#my-date-input', {
    lang: 'ru',
    startWeek: 'monday',
  });
</script>

Полный пример смотрите в examples/cdn-example.html.

Быстрый старт

Установка пакета

npm install glike35-date-time-picker

Использование в проекте

import { DateTimePicker } from 'glike35-date-time-picker';

new DateTimePicker('form input[name="date_start"]', {
  lang: 'ru',
});

Использование через CDN

См. раздел CDN сборка выше.

Примеры

В папке examples/ собраны различные примеры использования DateTimePicker:

Без оберток (чистый JavaScript через CDN)

• Базовый выбор даты – простой date picker
• Выбор времени – time picker с кастомными опциями
• Выбор даты и времени – datetime picker с поддержкой часовых поясов
• Диапазон дат – выбор диапазона (multi mode)
• Кастомные опции – настройка языка, форматов, ограничений
• Работа с событиями – обработка событий пикера

С обертками для фреймворков

• Использование с React – React компонент
• Использование с Vue 3 – Vue 3 компонент
• Использование с jQuery – jQuery плагин

Другие примеры

• CDN пример – оригинальный пример подключения через CDN
• Индекс всех примеров – главная страница с навигацией

Чтобы запустить примеры локально, выполните npm run dev и откройте соответствующие HTML файлы в браузере.

Как это работает

• Пикер открывается при focus/click на основном input.
• По OK пишет значение в input и диспатчит input/change.
• По Cancel откатывает к последнему подтвержденному значению.
• Нативный UI браузера для managed input отключается (readOnly + скрытый нативный индикатор), используется только кастомный popover.
• На узких экранах (< 768px) пикер автоматически позиционируется по центру экрана и адаптируется под размер viewport.

Опции

new DateTimePicker(selector, options?)

selector: HTMLElement | string
options: частичный объект настроек:

• lang?: string
  Текущий язык (по умолчанию ru).

• fallbackLang?: string
  Язык fallback (по умолчанию ru).

• translations?: Record<string, Record<string, string>>
  Пользовательские переводы/переопределения.

• startWeek?: 'monday' | 'sunday'
  Первый день недели.

• workType?: 'single' | 'multi'
  Режим выбора: одиночный или диапазон.

• mode?: 'date' | 'time' | 'datetime'
  Режим значения.

• displayFormat?: string
  Явный формат отображения в UI и в видимом managed input (например dd.MM.yyyy HH:mm).

• valueFormat?: string
  Формат значения в исходном input и в onInput/onChange (по умолчанию для даты yyyy-MM-dd; для времени HH:mm; для date-time yyyy-MM-ddTHH:mm).

• displayFormatsByLang?: Record<string, string>
  Форматы отображения по языку (для режима date).

• rangeSeparator?: string
  Разделитель диапазона в строковом fallback (' - ' по умолчанию).

• rangeEndSelector?: string
  Селектор второго поля конца диапазона (важно для multi).

• timezone?: 'local' | 'utc' | string
  Режим часового пояса для операций с датами. По умолчанию 'local'.

  • 'local' – использовать локальное время системы пользователя.
  • 'utc' – использовать UTC (без смещения).
  • строка IANA (например 'Europe/Moscow') – использовать указанный часовой пояс (требуется поддержка браузера).
    Влияет на парсинг, форматирование и сравнение дат.

• onInput?: (value, payload, picker) => void

• onChange?: (value, payload, picker) => void Колбэки после записи значения. payload: Date | Date[] | null (зависит от режима/выбора).

• minDate?: Date | string Минимальная доступная дата (включительно). Может быть объектом Date или строкой в формате ISO (YYYY-MM-DD). Даты вне диапазона будут отключены.

• maxDate?: Date | string Максимальная доступная дата (включительно). Может быть объектом Date или строкой в формате ISO (YYYY-MM-DD). Даты вне диапазона будут отключены.

• openToDate?: Date | string Дата, на месяц и год которой нужно открыть календарь при первом показе. Если значение выходит за minDate/maxDate, используется ближайшая допустимая граница.

Поддержка часовых поясов

DateTimePicker корректно обрабатывает часовые пояса благодаря встроенным утилитам src/utils/dateUtils.ts. По умолчанию используется локальное время системы, но можно явно указать режим через опцию timezone.

Пример использования UTC

new DateTimePicker('#date-input', {
  timezone: 'utc',
  mode: 'date',
});

При timezone: 'utc' все операции с датами (парсинг, сравнение, форматирование) выполняются в UTC, что гарантирует одинаковое поведение независимо от локального времени пользователя.

Пример с конкретным часовым поясом

new DateTimePicker('#date-input', {
  timezone: 'Europe/Moscow',
  mode: 'date',
});

Подробнее см. документацию по часовым поясам.

Локализация и пользовательские переводы

DateTimePicker поддерживает встроенные переводы для русского (ru), английского (en) и немецкого (de) языков. Вы можете передавать собственные переводы или переопределять существующие через опцию translations.

Встроенные языки

• Русский (ru) – язык по умолчанию
• Английский (en) – полная поддержка
• Немецкий (de) – базовые переводы

Использование пользовательских переводов

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

new DateTimePicker('#date-input', {
  lang: 'en',
  translations: {
    en: {
      'date picker': 'Custom Date Picker',
      'select month': 'Choose Month',
      'select year': 'Choose Year',
      cancel: 'Abort',
      ok: 'Confirm',
    },
    de: {
      'date picker': 'Benutzerdefinierte Datumsauswahl',
      'select month': 'Monat wählen',
      'select year': 'Jahr wählen',
    },
  },
});

Приоритет переводов

1. Пользовательские переводы для текущего языка (translations[lang])
2. Пользовательские переводы для fallback языка (translations[fallbackLang])
3. Встроенные переводы для текущего языка
4. Встроенные переводы для fallback языка
5. Ключ (если перевод не найден)

Полный список ключей перевода

Все ключи перевода можно найти в файлах локализации:

• src/locales/ru.json
• src/locales/en.json
• src/locales/de.json

Основные ключи:

• "date picker", "select month", "select year"
• "previous month", "next month"
• "calendar", "month selection", "year selection"
• "select time", "cancel", "ok"
• Названия месяцев ("jan", "feb", ...)
• Названия дней недели ("sunday", "monday", ...)
• Сокращенные названия дней ("mon", "tue", ...)

Динамическое изменение языка

Вы можете изменить язык после инициализации, установив свойство picker.options.lang:

const picker = new DateTimePicker('#date-input', { lang: 'ru' });
// ... позже
picker.options.lang = 'en';

При этом будут использоваться переводы для нового языка (как пользовательские, так и встроенные).

Адаптивное позиционирование

На экранах шириной менее 768px пикер автоматически переключается в адаптивный режим:

• Позиционируется по центру экрана.
• Ширина ограничивается шириной viewport (с отступами).
• При изменении размера окна позиция пересчитывается.
• На больших экранах используется стандартное позиционирование (рядом с input элементом).

Адаптивный режим можно отключить, установив adaptive: false в опциях (опция пока не реализована, но заложена в архитектуру).

Использование с фреймворками

React

Установите зависимости React:

npm install react react-dom
npm install --save-dev @types/react @types/react-dom

Используйте компонент DateTimePicker из wrappers/react/DateTimePicker.tsx:

import { DateTimePicker } from './wrappers/react/DateTimePicker';

function App() {
  const handleChange = (value: string) => {
    console.log('Selected:', value);
  };

  return <DateTimePicker mode="date" value="2026-04-28" onChange={handleChange} />;
}

Компонент поддерживает контролируемый и неконтролируемый режимы, все опции оригинального пикера и методы API через ref.

Vue 3

Используйте компонент DateTimePicker из wrappers/vue/DateTimePicker.vue:

<template>
  <DateTimePicker mode="date" v-model="selectedDate" :lang="lang" />
</template>

<script setup>
import { ref } from 'vue';
import DateTimePicker from './wrappers/vue/DateTimePicker.vue';

const selectedDate = ref('2026-04-28');
const lang = ref('ru');
</script>

Компонент использует Composition API и поддерживает v-model, все опции и события.

Подробнее см. документацию по оберткам.

jQuery

jQuery плагин-обертка позволяет использовать DateTimePicker в проектах с jQuery.

Установка

Подключите jQuery и скрипты DateTimePicker:

<!-- jQuery -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

<!-- Основной скрипт DateTimePicker (CDN или локальный) -->
<script src="dist/datetimepicker.js"></script>

<!-- jQuery плагин -->
<script src="wrappers/jquery.datetimepicker.js"></script>

Использование

// Базовая инициализация
$('#my-date-input').datetimepicker();

// С настройками
$('#datepicker').datetimepicker({
  lang: 'en',
  startWeek: 'sunday',
  workType: 'single',
  displayFormat: 'DD.MM.YYYY',
  minDate: '2024-01-01',
  maxDate: '2024-12-31',
  timezone: 'Europe/Moscow',
});

// Диапазон дат
$('#start-date').datetimepicker({
  rangeEndSelector: '#end-date',
  rangeSeparator: ' до ',
});

Методы плагина

// Получить экземпляр DateTimePicker
var picker = $('#my-input').datetimepicker('getPicker');

// Открыть/закрыть пикер
$('#my-input').datetimepicker('open');
$('#my-input').datetimepicker('close');

// Установить/получить значение
$('#my-input').datetimepicker('setValue', '2024-12-31');
var value = $('#my-input').datetimepicker('getValue');

Глобальные настройки

$.datetimepicker.setDefaults({
  lang: 'ru',
  startWeek: 'monday',
  rangeSeparator: ' - ',
});

Подробнее см. документацию jQuery обертки.

Accessibility & Keyboard Navigation

DateTimePicker разработан с учётом доступности (WCAG) и поддерживает навигацию с клавиатуры.

ARIA атрибуты

• Все интерактивные элементы имеют соответствующие ARIA роли (role="dialog", role="grid", role="row", role="gridcell").
• Кнопки навигации снабжены aria-label с описанием действия.
• Выбранный день помечается aria-selected="true".
• Текущий день помечается aria-current="date".
• Отключённые дни (вне диапазона min/max) имеют aria-disabled="true".
• Диалог связан с input элементом через aria-controls и aria-expanded.

Навигация с клавиатуры

DateTimePicker реализует полную поддержку клавиатурной навигации с focus trap (ловушкой фокуса), которая удерживает фокус внутри открытого пикера.

Основные клавиши

Когда пикер открыт, можно использовать следующие клавиши:

• Escape – закрыть пикер (фокус возвращается на input элемент).
• Enter – выбрать сфокусированный день (или подтвердить выбор).
• Стрелки влево/вправо – переместить фокус на предыдущий/следующий день.
• Стрелки вверх/вниз – переместить фокус на день неделей выше/ниже.
• PageUp – перейти к предыдущему месяцу.
• PageDown – перейти к следующему месяцу.
• Home – перейти к первому дню месяца.
• End – перейти к последнему дню месяца.
• Tab / Shift+Tab – циклическая навигация по всем фокусируемым элементам внутри пикера.

Focus trap (ловушка фокуса)

Пикер реализует focus trap, который:

1. При открытии автоматически устанавливает фокус на текущую дату (или выбранную дату, если есть)
2. Удерживает фокус внутри пикера при навигации Tab/Shift+Tab
3. Предотвращает скролл страницы при использовании стрелок навигации
4. При закрытии возвращает фокус на исходный input элемент

Визуальное выделение

Фокус визуально выделяется с помощью класса .dtp-focused (синяя outline). Отключённые дни (вне диапазона min/max) пропускаются при навигации стрелками - фокус автоматически перескакивает на ближайшую доступную дату.

Ограничения дат (minDate/maxDate)

Опции minDate и maxDate позволяют ограничить выбор дат. Даты вне указанного диапазона отображаются с классом .disabled и не могут быть выбраны. При навигации стрелками фокус автоматически перескакивает на ближайшую доступную дату.

Если поле пустое, календарь открывается на ближайшей допустимой дате. Например, если задан только maxDate, пикер сразу покажет месяц этой даты, а не текущий месяц пользователя.

Пример:

new DateTimePicker('#date-input', {
  minDate: '2026-04-10',
  maxDate: '2026-04-20',
});

Открытие календаря на нужной дате

Для явного управления стартовым месяцем используйте openToDate:

new DateTimePicker('#birthday', {
  maxDate: '2023-05-08',
  openToDate: '2023-05-08',
});

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

Система событий (Event System)

DateTimePicker предоставляет расширенную систему событий для отслеживания взаимодействия с компонентом. Доступны два способа обработки событий: через callback-функции в options и через методы on(), off(), once().

Доступные события

• open - пикер открыт
• close - пикер закрыт
• select - выбрана дата/время (срабатывает при клике на день в календаре и при нажатии OK)
• monthChange - изменен месяц в календаре
• yearChange - изменен год в календаре
• timeChange - изменено время
• viewChange - изменен вид пикера (calendar/month/year)
• destroy - пикер уничтожен

Использование через callback-функции в options

new DateTimePicker('input[name="date"]', {
  onOpen: picker => console.log('Picker opened', picker),
  onClose: picker => console.log('Picker closed', picker),
  onSelect: (date, picker) => console.log('Date selected', date),
  onMonthChange: (month, year, picker) => console.log('Month changed', month, year),
  onYearChange: (year, picker) => console.log('Year changed', year),
  onTimeChange: (time, picker) => console.log('Time changed', time),
  onViewChange: (view, picker) => console.log('View changed', view),
  onDestroy: picker => console.log('Picker destroyed', picker),
});

Использование через методы on(), off(), once()

const picker = new DateTimePicker('input[name="date"]');

// Подписка на событие
picker.on('open', event => {
  console.log('Picker opened', event.detail.picker);
});

// Подписка на одноразовое событие
picker.once('select', event => {
  console.log('First selection', event.detail.date);
});

// Отписка от события
const handler = event => console.log('Month changed', event.detail.month);
picker.on('monthChange', handler);
picker.off('monthChange', handler);

// Проверка наличия подписчиков
picker.hasListeners('open'); // boolean
picker.listenerCount('open'); // number

// Удаление всех подписчиков
picker.removeAllListeners('open'); // удаляет все обработчики для события 'open'
picker.removeAllListeners(); // удаляет все обработчики для всех событий

Детали событий

Каждое событие передает объект CustomEvent с деталями в свойстве detail:

• open, close, destroy: { picker: DateTimePicker }
• select: { date: Date | Date[], picker: DateTimePicker }
• monthChange: { month: number, year: number, picker: DateTimePicker }
• yearChange: { year: number, picker: DateTimePicker }
• timeChange: { time: string, picker: DateTimePicker }
• viewChange: { view: 'calendar' | 'month' | 'year', picker: DateTimePicker }

Связь input.type и mode

Если mode задан явно

Включена строгая проверка совместимости:

• mode: 'date' -> input.type должен быть date или month
• mode: 'time' -> input.type должен быть time
• mode: 'datetime' -> input.type должен быть datetime-local

При несовместимости бросается ошибка.

Если mode не задан

Режим определяется автоматически по input.type:

• time -> time
• datetime-local -> datetime
• иначе -> date

MULTI (диапазон):

Для workType: 'multi' рекомендуется обязательно передавать rangeEndSelector и использовать два поля:

• первое поле: начало диапазона,
• второе поле: конец диапазона.

Почему это важно:

• input[type="date"], datetime-local, month принимают только одно значение в строгом формате.
• Строка диапазона в одном таком поле (2026-03-01 - 2026-03-10) невалидна.

Пример multi (правильный)

<form>
  <input type="date" name="date_start" />
  <input type="date" name="date_end" />
</form>

import { DateTimePicker } from './src/datetimepicker';
import { WORK_TYPE } from './src/constants';

new DateTimePicker('form input[name="date_start"]', {
  workType: WORK_TYPE.MULTI,
  mode: 'date',
  rangeEndSelector: 'input[name="date_end"]',
});

Примеры режимов

Single date

<input type="date" name="date" />

new DateTimePicker('input[name="date"]', { mode: 'date' });

Single time

<input type="time" name="time" />

new DateTimePicker('input[name="time"]', { mode: 'time' });

Single datetime

<input type="datetime-local" name="dt" />

new DateTimePicker('input[name="dt"]', { mode: 'datetime' });

Форматы

• Формат значения (input.value) управляется через valueFormat:

  • date: по умолчанию yyyy-MM-dd
  • time: по умолчанию HH:mm
  • datetime-local: по умолчанию yyyy-MM-ddTHH:mm
  • month: по умолчанию yyyy-MM

• Managed input разделяется на скрытый value input и видимый display input:

  • скрытый исходный input сохраняет name и отправляется формой,
  • видимый input не имеет name и показывает дату по displayFormat.

• Формат отображения в UI управляется через:

  • displayFormat (высший приоритет),
  • displayFormatsByLang[lang],
  • displayFormatsByLang[fallbackLang],
  • fallback (dd.MM.yyyy или HH:mm/... HH:mm в time/datetime).

Тестирование

Проект включает несколько HTML тестов для проверки функциональности:

• test-events.html – тестирование системы событий
• test-localization.html – проверка локализации и переводов
• test-timezone.html – тестирование работы с часовыми поясами
• test-validation.html – проверка валидации и ограничений дат

Запустите сервер разработки (npm run dev) и откройте соответствующие файлы в браузере.

Разработка

Команды npm

• npm run dev – запуск сервера разработки Vite
• npm run build – сборка проекта (TypeScript компиляция + Vite)
• npm run build:full – сборка проекта (TypeScript компиляция + Vite + минифицированные файлы для CDN)
• npm run preview – предпросмотр собранного проекта

Структура проекта

src/
├── datetimepicker.ts          # Основной класс DateTimePicker
├── components/                # Компоненты календаря (Month, WeekDays, CalendarDay)
├── events/                    # Система событий (EventEmitter)
├── i18n/                      # Локализация (I18n класс, переводы)
├── interfaces/                # TypeScript интерфейсы
├── types/                     # TypeScript типы
├── utils/                     # Утилиты (dateUtils, helpers)
└── style.css                  # Стили компонента

wrappers/
├── react/DateTimePicker.tsx   # React wrapper компонент
├── vue/DateTimePicker.vue     # Vue 3 wrapper компонент
└── README.md                  # Документация по оберткам

docs/
├── events-examples.md         # Примеры использования событий
└── timezone-handling.md       # Документация по часовым поясам

plans/
├── current_progress.md        # Текущий прогресс разработки
└── improvement_plan.md        # План улучшений

TypeScript

Проект использует TypeScript с strict настройками. Все интерфейсы имеют префикс I (например IOption, ICalendarDay). Константы определены в UPPER_CASE. Для импорта типов используется ключевое слово type (включен verbatimModuleSyntax).

Лицензия

MIT