Документация

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

Опции

classes
string

Добавляет дополнительные классы календарю.

inline
boolean
false

Делает календарь постоянно видимым.

locale
object
locale/ru

Язык отображения календаря. Доступные локали находятся в директории air-datepicker/locale/.

Подробнее со структурой локализации можно ознакомиться в соответствующем разделе.

import AirDatepicker from 'air-datepicker';
import localeEn from 'air-datepicker/locale/en';

new AirDatepicker('#el', {
    locale: localeEn
})
startDate
Date | string | number
new Date()

Устанавливает начальную дату отображения календаря.

firstDay
number

Индекс дня, с которого начинается неделя. Возможные значение от 0 (воскресенье) до 6 (суббота). По умолчанию берется из локализации, если значение передать сюда, то оно будет иметь больший приоритет.

weekends
array
[6, 0]

Индексы дней, которые будут считаться выходными. Им будет добавлен класс .-weekend-. По умолчанию это суббота и воскресенье.

isMobile
boolean
false

Если true, то календарь будет появляться в виде модального окна с немного увеличенными размерами.

visible
boolean
false

Показывает календарь сразу же после инициализации.

dateFormat
string | (date) => string
""

Формат даты. С 3 версии формат даты основывается на стандарте Unicode Technical Standard #35. По умолчанию берется из текущей локали. Значение, переданное сюда, будет иметь больший приоритет.

Доступные символы:

T — время в миллисекундах
E — краткое названия дня недели, поле daysShort из локали
EEEE — полное названия дня недели, поле days из локали
d — день месяца
dd — день месяца с лидирующим нулем
M — номер месяца
MM — номер месяца с лидирующим нулем
MMM — краткое наименование месяца, поле monthsShort из локали
MMMM — полное наименование месяца, поле months из локали
yy — сокращенный год из двух цифр
yyyy — полный номер года
yyyy1 — первый год декады текущего года
yyyy2 — последний год декады текущего года

Вы также можете передать сюда функцию, для ручной обработки выбранных дат. Она должна возвратить строку. Если включен режим выбора нескольких дат, то в эту функцию будет передан массив выбранных дат.

new AirDatepicker('#el', {
    dateFormat(date) {
        return date.toLocaleString('ja', {
            year: 'numeric',
            day: '2-digit',
            month: 'long'
        });
    }
})
altField
string | DOMNode
""

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

altFieldDateFormat
string | (date) => string
"T"

Формат даты дополнительного поля

toggleSelected
boolean
true

Если true, то клик на активной ячейке снимет с нее выделение

keyboardNav
boolean
true

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

Сочетания клавиш:

Ctrl + → | ↑ — переход на месяц вперед
Ctrl + ← | ↓ — переход на месяц назад
Shift + → | ↑ — переход на год вперед
Shift + ← | ↓ — переход на год назад
Alt + → | ↑ — переход на 10 лет вперед
Alt + ← | ↓ — переход на 10 лет назад
Ctrl + Shift + ↑ — смена представления, от дней до декад
Esc — закрытие календаря
selectedDates
Date[] | string[] | number[]
false

Массив активных дат. Принимает как отдельные типы данных, так и смешанные. Если будет передан невалидный формат даты, то это значение будет проигнорировано

import AirDatepicker from 'air-datepicker';

let startDate = new Date('2021-07-20');

new AirDatepicker('#el', {
    startDate,
    multipleDates: true,
    selectedDates: [startDate, '2021-07-25', 1626307200000]
})
container
string | HTMLElement
""

Родительский элемент для календаря. По умолчанию все календари помещаются в элемент с классом .air-datepicker-global-container.

position
string | function
"bottom left"

Позиционирование календаря относительно текстового поля.

Если передать строку, то первым значением задается основная ось позиционирования, вторым - положение на этой оси. Например {position: 'top right'} - установит позицию календаря справа вверху от текстового поля.

Если передать функцию, то можно регулировать позицию самостоятельно - она будет вызвана при срабатывании метода show(). Но в таком случае все анимации отключаются и вам придется добавлять их вручную, если они требуются. Функция принимает объект из следующих полей

$datepicker
HTMLDivElement
 — элемент календаря
$target
HTMLInputElement
 — целевой элемент, на котором был проинициализирован календарь
$pointer
HTMLElement
 — стрелочка, указывающая на целевой элемент
isViewChange
boolean
 — поскольку календарь также позиционируется во время смены представления, то это поле позволяет определить в какой момент вызывается функция - при появлении или при переходе от одного вида к другому
done
() => void
 — функция, которая должна быть вызвана в конце, в случае ручной обработки скрытия календаря

Если требуется ручная обработка скрытия календаря, то вы можете возвратить функцию из position - она будет вызвана при срабатывании hide() - по завершению обработки не забудьте вызвать функцию done для завершения процесса скрытия.

Пример ручной обработки позиционирования:

new AirDatepicker('#el', {
    autoClose: true,
    position({$datepicker, $target, $pointer}) {
        let coords = $target.getBoundingClientRect(),
            dpHeight = $datepicker.clientHeight,
            dpWidth = $datepicker.clientWidth;
    
        let top = coords.y + coords.height / 2 + window.scrollY - dpHeight / 2;
        let left = coords.x + coords.width / 2 - dpWidth / 2;
    
        $datepicker.style.left = `${left}px`;
        $datepicker.style.top = `${top}px`;
    
        $pointer.style.display = 'none';
    }
})
view
string
"days"

Начальное представление календаря. Возможные значения:

days — отображение дней одного месяца
months — отображения месяцев одного года
years — отображение годов одной декады
minView
string
"days"

Минимально возможное представление календаря. Используется, например, когда нужно предоставить только выбор месяца. Возможные значения такие же как и у view

showOtherMonths
boolean
true

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

selectOtherMonths
boolean
true

Если true, то можно будет выбрать даты из других месяцев.

moveToOtherMonthsOnSelect
boolean
true

Если true, то при выборе дат из другого месяца будет осуществлен переход к этому месяцу.

minDate
Date | string | number
""

Минимально возможная дата для выбора.

maxDate
Date | string | number
""

Максимально возможная дата для выбора.

disableNavWhenOutOfRange
boolean
true

Нужно ли запрещать переходить на следующий или предыдущий месяц/год/декаду если они выходят за рамки минимальной или максимальной дат.

Если true, то при наступлении такого сценария будут деактивироваться кнопки навигации календаря

multipleDates
boolean | number
false

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

multipleDatesSeparator
string
", "

Разделитель между датами - используется в режиме множественного выбора дат и в режиме выбора диапазона.

range
boolean
false

Предоставляет возможность выбора диапазона дат. В качестве разделителя будет использовано значение из multipleDatesSeparator

dynamicRange
boolean
true

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

buttons
string | string[] | object | object[] | false
false

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

Изначально доступны два варианта:

today — кнопка «Сегодня» - при нажатии будет осуществлен переход к сегодняшней дате
clear — кнопка «Очистить» - при нажатии все активные даты будут деактивированы.

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

ButtonShape = {
    content: string | (dpInstance) => string
    tagName?: string
    className?: string
    attrs?: object
    onClick?: (dpInstance) => void
}

Пример произвольной кнопки

import AirDatepicker from 'air-datepicker';

let button = {
    content: 'Select 2021-07-26',
    className: 'custom-button-classname',
    onClick: (dp) => {
        let date = new Date('2021-07-26');
        dp.selectDate(date);
        dp.setViewDate(date);
    }
}

new AirDatepicker('#el', {
    buttons: [button, 'clear'] // Custom button, and pre-installed 'clear' button
})
monthsField
string
"monthsShort"

Поле из объекта локализации, которое будет использовано для отображения названий месяца в представлении months.

showEvent
string
"focus"

Событие, которому будет показан календарь.

autoClose

Если true, то после выбора даты календарь будет скрыт.

prevHtml
string
"<svg><path d="M 17,12 l -5,5 l 5,5"></path></svg>"

Контент кнопки «Назад» в навигации календаря

nextHtml
string
"<svg><path d="M 14,12 l 5,5 l -5,5"></path></svg>"

Контент кнопки «Вперед» в навигации календаря

Шаблоны заголовков в навигации календаря. Можно использовать HTML теги и символы из dateFormat. Также можно передать функцию в качестве значения - она получит экземпляр календаря в качестве аргумента, и должна будет вернуть строку.

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

Значения по умолчанию:

let navTitlesDefaults = {
    days: 'MMMM, <i>yyyy</i>',
    months: 'yyyy',
    years: 'yyyy1 - yyyy2'
}

Применение:

new AirDatepicker('#el', {
    navTitles: {
        days: '<strong>Choose date</strong> MM, yyyy'
    }
})
timepicker
boolean
false

Включает возможность выбрать время.

onlyTimepicker
boolean
false

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

dateTimeSeparator
string
" "

Разделитель между датой и временем.

timeFormat
string

Формат времени. Так же как и dateFormat опирается на Unicode Technical Standard #35. Если передать 12-часовой формат отображения часов, то ползунки времени будут автоматически подстроены под соответствующий режим.

Возможные символы:

h — часы в 12-часовом формате
hh — часы в 12-часовом формате с лидирующим нулем
H — часы в 24-часовом формате
HH — часы в 24-часовом формате с лидирующим нулем
m — минуты
mm — минуты с лидирующим нулем
aa — период дня маленькими буквам
AA — период дня заглавными буквами
minHours
number
0

Минимально допустимое к выбору значение часов.

maxHours
number
24

Максимально допустимое к выбору значение часов.

minMinutes
number
0

Минимально допустимое к выбору значение минут.

maxMinutes
number
59

Максимально допустимое к выбору значение минут.

hoursStep
number
1

Шаг выбора часов.

minutesStep
number
1

Шаг выбора минут.

Локализация

Начиная с версии 3.0.0 язык календаря нужно передавать как объект, вместо строки, как было раньше. Вы можете подключить одну из доступных локализаций либо же создать свою собственную. Доступные локализации находится в директории 'locales/'

Пример объекта локализации

export default {
    days: ['Воскресенье', 'Понедельник', 'Вторник', 'Среда', 'Четверг', 'Пятница', 'Суббота'],
    daysShort: ['Вос','Пон','Вто','Сре','Чет','Пят','Суб'],
    daysMin: ['Вс','Пн','Вт','Ср','Чт','Пт','Сб'],
    months: ['Январь', 'Февраль', 'Март', 'Апрель', 'Май', 'Июнь', 'Июль', 'Август', 'Сентябрь', 'Октябрь', 'Ноябрь', 'Декабрь'],
    monthsShort: ['Янв', 'Фев', 'Мар', 'Апр', 'Май', 'Июн', 'Июл', 'Авг', 'Сен', 'Окт', 'Ноя', 'Дек'],
    today: 'Сегодня',
    clear: 'Очистить',
    dateFormat: 'dd.MM.yyyy',
    timeFormat: 'HH:mm',
    firstDay: 1
};

События

onSelect
({date, formattedDate, datepicker}) => void

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

date
Date | Date[]
 — выбранная дата, если включен режим выбора нескольких дат, то будет передан массив.
formattedDate
string | string[]
 — отформатированная выбранная дата, или массив в случае с мульти выбором.
datepicker
AirDatepicker
 — экземпляр календаря
onChangeViewDate
({month, year, decade}) => void

Срабатывает при перелистывании календаря вперед или назад. Получает в качестве аргумента объект с актуальными значениям месяца, года и декады.

month
number
 — месяц просматриваемой даты
year
number
 — год просматриваемой даты
decade
number[]
 — декада просматриваемой даты. Первый элемент массива - начало декады, второй - конец
onChangeView
("days | months | years") => void

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

onRenderCell
({date, cellType, datepicker}) => {html, classes, disabled}

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

В качестве аргумента принимает объект, описывающий текущую ячейку:

date
Date
 — дата текущей ячейки
cellType
"day | month | year"
 — тип ячейки - день, месяц или год
datepicker
AirDatepicker
 — экземпляр календаря

Функция должна возвращать объект, состоящий из следующих полей:

html
string
 — произвольное содержимое ячейки
classes
string
 — дополнительные классы
disabled
boolean
 — нужно ли делать ячейку невозможную к выбору
new AirDatepicker('#el', {
    onRenderCell({date, cellType}) {
        // Disable all 12th dates in month
        if (cellType === 'day') {
            if (date.getDate() === 12) {
                return {
                    disabled: true
                }
            }
        }
    }
})
onShow
(isFinished) => void

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

isFinished
boolean
 — индикатор завершения анимации появления
onHide
(isFinished) => void

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

isFinished
boolean
 — индикатор завершения анимации скрытия
onClickDayName
({dayIndex, datepicker}) => void

Добавляет возможность кликать по названиям дней в календаре. При этом, этим элементах будет добавлен класс `-clickable-`

dayIndex
index
 — индекс дня недели, где 0 - воскресенье, 6 - суббота
datepicker
object
 — экземпляр календаря