Air Datepicker

Star
In English

# AIR DATEPICKERлегкий кроссбраузерный jQuery календарь

## Описание

Легкий (~36kb минифицированный js файл и ~9kb gziped), кастомизируемый, кроссбраузерный календарь, написан с использованием`es5`и`css flexbox`. Работает во всех современных браузерах: IE 10+, Chrome, Firefox, Safari 8+, Opera 17+.

## Установка

    bower i --save air-datepicker

Либо можно скачать файлы напрямую с GitHub

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

Подключите стили и скрипты из папки`/dist`:

    <html>
        <head>
            <link href="dist/css/datepicker.min.css" rel="stylesheet" type="text/css">
            <script src="dist/js/datepicker.min.js"></script>
        </head>
    </html>

Календарь автоматически проинициализируется на элементах с классом`.datepicker-here`, при этом опции можно передать через`data`атрибуты.

    <input type='text' class="datepicker-here" data-position="right top" />

### Ручная инициализация

    // Инициализация
    $('#my-element').datepicker([options])

    // Доступ к экземпляру объекта
    $('#my-element').data('datepicker')

## Примеры

### Инициализация с опциями по умолчанию

Пример

    <input type='text' class='datepicker-here' />

### Выбор нескольких дат

Передайте параметр`{multipleDates: true}`для выбора нескольких дат. Если требуется ограничить количество выбранных дат, то передайте необходимое число`{multipleDates: 3}`.

Пример

    <input type="text"
        class="datepicker-here"
        data-multiple-dates="3"
        data-multiple-dates-separator=", "
        data-position='right top'/>

### Постоянно видимый календарь

Проинициализируйте плагин на элементе, который не является текстовым полем, например на`<div> … </div>`, либо передайте параметр`{inline: true}`.

Пример

    <div class="datepicker-here"></div>

### Выбор месяца

Пример

    <input type="text"
        class="datepicker-here"
        data-min-view="months"
        data-view="months"
        data-date-format="MM yyyy" />

### Минимальная и максимальные даты

Чтобы ограничить выбор даты, используйте`minDate`и`maxDate`, которым нужно передать объект даты.

Пример

    $('#minMaxExample').datepicker({
        // Можно выбрать тольо даты, идущие за сегодняшним днем, включая сегодня
        minDate: new Date()
    })

### Диапозон дат

Используйте парамтер`{range: true}`для выбора диапазона. В качестве разделителя дат будет использован`multipleDatesSeparator`

Для того, чтобы иметь возомжность выбрать одну и ту же дату, необходимо установить`{toggleSelected: false}`.

Пример

    <input type="text" data-range="true" data-multiple-dates-separator=" - " class="datepicker-here"/>

### Неактивные дни недели

Для того, чтобы сделать невозмножным выбрать конкретные дни недели, можно воспользоваться методом`onRenderCell`.

Пример

    // Сделаем неактивными воскресенье и субботу
    var disabledDays = [0, 6];

    $('#disabled-days').datepicker({
        onRenderCell: function (date, cellType) {
            if (cellType == 'day') {
                var day = date.getDay(),
                    isDisabled = disabledDays.indexOf(day) != -1;

                return {
                    disabled: isDisabled
                }
            }
        }
    })

### Кастомное содержимое ячеек

Air Datepicker позволяет менять содержимое ячеек как угодно. Для этого можно также воспользоваться методом`onRenderCell`. Давайте добавим вспомогательные элементы к нескольким датам и покажем случайный текст при выборе этих дат:

Пример

    var eventDates = [1, 10, 12, 22],
        $picker = $('#custom-cells'),
        $content = $('#custom-cells-events'),
        sentences = [ … ];

    $picker.datepicker({
        onRenderCell: function (date, cellType) {
            var currentDate = date.getDate();

            // Добавляем вспомогательный элемент, если число содержится в `eventDates`
            if (cellType == 'day' && eventDates.indexOf(currentDate) != -1) {
                return {
                    html: currentDate + '<span class="dp-note"></span>'
                }
            }
        },
        onSelect: function onSelect(fd, date) {
            var title = '', content = ''

            // Если выбрана дата с событием, то отображаем его
            if (date && eventDates.indexOf(date.getDate()) != -1) {
                title = fd;
                content = sentences[Math.floor(Math.random() * eventDates.length)];
            }

            $('strong', $content).html(title)
            $('p', $content).html(content)
        }
    })

    // Сразу выберем какую-ниудь дату из `eventDates`
    var currentDate = currentDate = new Date();
    $picker.data('datepicker').selectDate(new Date(currentDate.getFullYear(), currentDate.getMonth(), 10))

### Появление и скрытие календаря

Для добавления каких-либо действий с начала анимации или по ее окончанию, используйте опции`onShow`и`onHide`

Пример

    $('#example-show-hide-callbacks').datepicker({
        onShow: function(dp, animationCompleted){
            if (!animationCompleted) {
                log('start showing')
            } else {
                log('finished showing')
            }
        },
        onHide: function(dp, animationCompleted){
            if (!animationCompleted) {
                log('start hiding')
            } else {
                log('finished hiding')
            }
        }
    })

## Выбор времени

Для выбора времени используйте опцию`{timepicker: true}`- она добавит время и пару ползунков, с помощью которых можно уставноить часы и минуты.

По умолчанию будет установлено текущее время на компьюетере пользователя, это значение можно изменять параметром`startDate`.

Пример

    <div class="datepicker-here" data-timepicker="true"></div>

Подробнее о параметрах выбора времени можно почитать в Опциях.

### Формат времени

Формат времени задается в объекте локализации, либо в парамтре`timeFormat`. По умолчанию используется 24-х часовой формат. Для выбора 12-ти часового формата в`timeFormat`нужно добавить символ`aa`или`AA`. После чего в виджете появятся обозочения 'AM' или 'PM', в зависимости от выбранного периода времени.

Пример

    <div class="datepicker-here" data-timepicker="true" data-time-format='hh:ii aa'></div>

### Действия со временем

Для задания максимально/минимально возможных значений часов или минут используйте параметры`maxHours`,`minHours`,`maxMinutes`,`minMinutes`. Также время можно указывать в парамтерах`minDate`и`maxDate`

Давайте создадим календарь, где пользователь может выбрать время с 09:00 до 18:00, а в субботу и воскресенье с 10:00 до 16:00.

Пример

    <input type='text' id='timepicker-actions-exmpl' />
    <script>
        // Зададим стартовую дату
        var start = new Date(),
            prevDay,
            startHours = 9;

        // 09:00
        start.setHours(9);
        start.setMinutes(0);

        // Если сегодня суббота или воскресенье - 10:00
        if ([6,0].indexOf(start.getDay()) != -1) {
            start.setHours(10);
            startHours = 10
        }

        $('#timepicker-actions-exmpl').datepicker({
            timepicker: true,
            startDate: start,
            minHours: startHours,
            maxHours: 18,
            onSelect: function(fd, d, picker) {
                // Ничего не делаем если выделение было снято
                if (!d) return;

                var day = d.getDay();

                // Обновляем состояние календаря только если была изменена дата
                if (prevDay != undefined && prevDay == day) return;
                prevDay = day;

                // Если выбранный день суббота или воскресенье, то устанавливаем
                // часы для выходных, в противном случае восстанавливаем начальные значения
                if (day == 6 || day == 0) {
                    picker.update({
                        minHours: 10,
                        maxHours: 16
                    })
                } else {
                    picker.update({
                        minHours: 9,
                        maxHours: 18
                    })
                }
            }
        })
    </script>

## Локализация

Вы можете добавить свою локализацию в объект`$.fn.datepicker.language["my-lang"]`и при вызове календаря передать название языка в параметр`language`

    $.fn.datepicker.language['my-lang'] = {...}

    $('.my-datepicker').datepicker({
        language: 'my-lang'
    })

Также объект локализации можно передавать непосредственно в`language`

    $('.my-datepicker').datepicker({
        language: {
            days: [...]
            ...
        }
    })

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

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

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

## Опции

### classes

Тип `string`

Значение по умолчанию`""`

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

### inline

Тип `boolean`

Значение по умолчанию `false`

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

### language

Тип `string|object`

Значение по умолчанию`"ru"`

Язык календаря. Если передается строка, то поиск языка будет осуществляться в объекте`Datepicker.language`Если передан объект, то данные будут браться из него.

Если в объекте локализации не будет хватать каких то полей, то они будут взяты из языка по умолчанию.

### startDate

Тип `Date`

Значение по умолчанию `new Date()`

Дата, которая будет отображаться при инициализации календаря.

### firstDay

Тип `number`

Значение по умолчанию`""`

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

### weekends

Тип `array`

Значение по умолчанию`[6, 0]`

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

### dateFormat

Тип `string`

Значение по умолчанию`""`

Желаемый формат даты, кобминация из d, m, yyyy, D, M, и т.д. По умолчанию берется из локализации, если передать значение сюда, то оно будет иметь больший приоритет.

- @- время в миллесекундах
- d- дата
- dd- дата с лидирующем нулем
- D- сокращенное наименование дня
- DD- полное наименование дня
- m- номер мясяца
- mm- номер месяца с лидирующем нулем
- M- сокращенное наименовение месяца
- MM- полное наименовение месяца
- yy- сокращенный номер года
- yyyy- полный номер года
- yyyy1- первый год декады, в которую входит текущий год
- yyyy2- последний год декады, в которую входит текущий год

### altField

Тип `string|jQuery`

Значение по умолчанию`""`

Альтернативное поле воода в значение которого будут попадать выбранные даты с форматом`altFieldDateFormat`.

### altFieldDateFormat

Тип `string`

Значение по умолчанию`"@"`

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

### toggleSelected

Тип `boolean`

Значение по умолчанию `true`

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

### keyboardNav

Тип `boolean`

Значение по умолчанию `true`

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

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

- Ctrl + → | ↑- переход на месяц вперед
- Ctrl + ← | ↓- переход на месяц назад
- Shift + → | ↑- переход на год вперед
- Shift + ← | ↓- переход на год назад
- Alt + → | ↑- переход на 10 лет вперед
- Alt + ← | ↓- переход на 10 лет назад
- Ctrl + Shift + ↑- переход на следующий вид
- Esc- закрывает календарь

### position

Тип `string`

Значение по умолчанию`"bottom left"`

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

### offset

Тип `number`

Значение по умолчанию `12`

Отступ от основной оси позиционирования.

### view

Тип `string`

Значение по умолчанию`"days"`

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

- `days`- отображение дней месяца
- `months`- отображение месяцев одного года
- `years`- отображение годов одной декады

### minView

Тип `string`

Значение по умолчанию`"days"`

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

### showOtherMonths

Тип `boolean`

Значение по умолчанию `true`

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

### selectOtherMonths

Тип `boolean`

Значение по умолчанию `true`

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

### moveToOtherMonthsOnSelect

Тип `boolean`

Значение по умолчанию `true`

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

### showOtherYears

Тип `boolean`

Значение по умолчанию `true`

Если true, то при отображении декады, будут показаны годы из других декад.

### selectOtherYears

Тип `boolean`

Значение по умолчанию `true`

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

### moveToOtherYearsOnSelect

Тип `boolean`

Значение по умолчанию `true`

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

### minDate

Тип `Date`

Значение по умолчанию`""`

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

### maxDate

Тип `Date`

Значение по умолчанию`""`

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

### disableNavWhenOutOfRange

Тип `boolean`

Значение по умолчанию `true`

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

### multipleDates

Тип `boolean|number`

Значение по умолчанию `false`

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

### multipleDatesSeparator

Тип `string`

Значение по умолчанию`","`

Разделитель дат, который будет использован при объеденения нескольких дат в одну строку.

### range

Тип `boolean`

Значение по умолчанию `false`

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

### todayButton

Тип `boolean|Date`

Значение по умолчанию `false`

Если true, то будет отображена кнопка "Сегодня". Если передать объект даты, то при клике по кнопке будет осуществлен переход и последующий выбор этой даты.

    // Выбор сегодняшнего дня
    $('.datepicker').datepicker({
        todayButton: new Date()
    })

### clearButton

Тип `boolean`

Значение по умолчанию `false`

Если true, то будет отображена кнопка "Очистить".

### showEvent

Тип `string`

Значение по умолчанию`"focus"`

Тип события, по наступлению которого будет показан календарь.

### autoClose

Тип `boolean`

Значение по умолчанию `false`

Если 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>`

Контент кнопки 'следующий месяц|год|декада'.

### navTitles

Тип `object`

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

    navTitles = {
        days: 'MM, <i>yyyy</i>',
        months: 'yyyy',
        years: 'yyyy1 - yyyy2'
    };

Значение заголовка календаря в зависимости от текущего вида, можно использовать те же обозначения что и в`dateFormat`. Недостающие поля будут взяты из значения по умолчанию. Также можно использовать html теги.

    $('#my-datepicker').datepicker({
        navTitles: {
            days: '<h3>Выберете дату заезда</h3> MM, yyyy'
        }
    })

### monthsField

Тип `string`

Значение по умолчанию`"monthsShort"`

Какое поле из объекта локализации использовать в качестве названий месяцев, когда`view = "months"`.

### timepicker

Тип `boolean`

Значение по умолчанию `false`

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

### dateTimeSeparator

Тип `string`

Значение по умолчанию`" "`

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

### timeFormat

Тип `string`

Значение по умолчанию `null`

Формат времени. По умолчанию берется из локализации. Если передать значение сюда, то оно будет иметь больший приоритет. Для включения 12-ти часового режима добавьте 'aa' или 'AA' в параметр`timeFormat`, например`{timeFormat: "hh:ii AA"}`Возможные варианты:

- h- часы
- hh- часы, с лидирующим нулем
- i- минуты
- ii- минуты, с лидирующим нулем
- aa- период дня - 'am' или 'pm'
- AA- период дня заглавными буквами

### minHours

Тип `number`

Значение по умолчанию `0`

Минимальное значение часов от 0 до 23. Нельзя выбрать час меньше, чем переданное значение.

### maxHours

Тип `number`

Значение по умолчанию `23`

Максимальное значение часов от 0 до 23. Нельзя выбрать час больше, чем переданное значение.

### minMinutes

Тип `number`

Значение по умолчанию `0`

Минимальное значение часов от 0 до 59. Нельзя вустановить значение минут меньше, чем переданное значение.

### maxMinutes

Тип `number`

Значение по умолчанию `59`

Максимальное значение минут от 0 до 59. Нельзя вустановить значение минут больше, чем переданное значение.

### hoursStep

Тип `number`

Значение по умолчанию `1`

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

### minutesStep

Тип `number`

Значение по умолчанию `1`

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

## События

### onSelect(formattedDate, date, inst)

Тип `function`

Значение по умолчанию `null`

Функция обратного вызова при выборе даты.

- formattedDatestring- отформатированная дата.
- dateDate|array- объект`Date`выбранной даты, если`{multipleDates: true}`, то будет передан массив таких объектов.
- instobject- экземпляр плагина.

### onShow(inst, animationCompleted)

Тип `function`

Значение по умолчанию `null`

Функция обратного вызова при появлении календаря.

- instObject- экземпляр календаря.
- animationCompletedboolean- индикатор состояния анимации. если`false`, то анимация только началась, если`true`- уже закончилась.

### onHide(inst, animationCompleted)

Тип `function`

Значение по умолчанию `null`

Функция обратного вызова при скрытии календаря.

- instObject- экземпляр календаря.
- animationCompletedboolean- индикатор состояния анимации. если`false`, то анимация только началась, если`true`- уже закончилась.

### onChangeMonth(month, year)

Тип `function`

Значение по умолчанию `null`

Функция обратного вызова при изменении месяца.

- monthnumber- номер месяца (от 0 до 12), к которому осуществлен переход.
- yearnumber- номер года, к которому осуществлен переход.

### onChangeYear(year)

Тип `function`

Значение по умолчанию `null`

Функция обратного вызова при изменении года.

- yearnumber- номер года, к которому осуществлен переход

### onChangeDecade(decade)

Тип `function`

Значение по умолчанию `null`

Функция обратного вызова при изменении декады.

- decadearray- массив, состоящий из номера года с которого начинается декада, и года на котором она заканчивается.

### onChangeView(view)

Тип `function`

Значение по умолчанию `null`

Функция обратного вызова при изменении вида календаря

- viewstring- вид, к которому осуществлен переход (days, months, years).

### onRenderCell(date, cellType)

Тип `function`

Значение по умолчанию `null`

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

- dateDate- объект даты текущей ячейки
- cellTypestring- тип текущей ячейки (day, month, year).

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

    {
        html: '', // Кастомный контент ячейки
        classes: '', // Дополнительные классы для ячейки
        disabled: '' // true/false, если true, то ячейку нельзя будет выбрать
    }

#### Пример

    $('#my-datepicker').datepicker({
        // Передаем функцию, которая добавляет 11 числу каждого месяца класс 'my-class'
        // и делает их невозможными к выбору.
        onRenderCell: function(date, cellType) {
            if (cellType == 'day' && date.getDate() == 11) {
                return {
                    classes: 'my-class',
                    disabled: true
                }
            }
        }
    })

## API

Досутп к экземпляру плагина осуществляется через`data`атрибут.

    var myDatepicker = $('#my-elem').datepicker().data('datepicker');

    myDatepicker.show();

### show()

Показывает календарь.

### hide()

Скрывает календарь.

### destroy()

Удаляет календарь.

### next()

Переходит на следующий месяц если вид days, на следующий год если months, и следующую декаду если years.

### prev()

Переходит на предыдщуий месяц если вид days, на предыдущий год если months, и предыдущую декаду если years.

### selectDate(date)

- dateDate|Array- дата в формате JavaScript, или массив дат

Выбирает переданную дату или несколько дат, если передан массив с датами. Если`{multipleDates: false}`и уже есть активная дата, то она будет деактивирована. Если`{multipleDates: true}`то будет добавлена еще одна активная дата.

### removeDate(date)

- dateDate- дата в формате JavaScript`Date()`

Снимает выделение с переданной даты.

### clear()

Убирает выделение со всех активных дат.

### update(field[, value])

- fieldstring|object- название поля значение которого нужно обновить.
- fieldstring|*- новое значение параметра

Обновление опций календаря, после вызова метода он автоматически перерисуется. Можно обновлять сразу несколько параметров, для этого нужно передать объект с требуемыми полями.

    var datepicker = $('#my-elem').datepicker().data('datepicker');

    // Обновление одного параметра
    datepicker.update('minDate', new Date())

    // Обновление нескольких параметров
    datepicker.update({
        position: "top right",
        maxDate: new Date(),
        todayButton: true
    })

### view

Устанавливает новое представление для календаря.

    datepicker.view = 'months';

### date

Устанавливает новую отображаемую дату, нужно передать JavaScript`Date()`

    datepicker.date = new Date();

### $el

DOM элемент календаря

### selectedDates

Массив выбранных дат