jQuery UI API - виджет Datepicker

Категория

Виджеты

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

Описание:Выбор даты из всплывающего окна или встроенного календаря.

Добавлено в версии:1.0

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

По умолчанию datepicker открывается в небольшом всплывающем окне, когда связанное текстовое поле получает фокус. Для встроенного календаря просто прикрепите datepicker к div или span.

Взаимодействие с клавиатурой

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

  • PAGE UP: Перейти к предыдущему месяцу.
  • PAGE DOWN: Перейти к следующему месяцу.
  • CTRL+PAGE UP: Перейти к предыдущему году.
  • CTRL+PAGE DOWN: Перейти к следующему году.
  • CTRL+HOME: Перейти к текущему месяцу. Если datepicker закрыт, откройте его.
  • CTRL+LEFT: Перейти к предыдущему дню.
  • CTRL+RIGHT: Перейти к следующему дню.
  • CTRL+UP: Перейти к предыдущей неделе.
  • CTRL+DOWN: Перейти к следующей неделе.
  • ENTER: Выбрать дату, находящуюся в фокусе.
  • CTRL+END: Закрыть datepicker и очистить дату.
  • ESCAPE: Закрыть datepicker без выбора.

Вспомогательные функции

$.datepicker.setDefaults( settings )

Изменение настроек по умолчанию для всех datepicker.

Используйтеoption()метод для изменения настроек отдельных экземпляров.

Примеры кода:

Настроить все datepicker так, чтобы они открывались при получении фокуса или при щелчке по значку.

$.datepicker.setDefaults({
  showOn: "both",
  buttonImageOnly: true,
  buttonImage: "calendar.gif",
  buttonText: "Calendar"
});

Установить для всех datepickers французский текст.

$.datepicker.setDefaults( $.datepicker.regional[ "fr" ] );

$.datepicker.formatDate( format, date, settings )

Форматировать дату в строковое значение с указанным форматом.

Формат может быть комбинацией следующего:

  • d - день месяца (без ведущего нуля)
  • dd - день месяца (две цифры)
  • o - день года (без ведущего нуля)
  • oo - день года (три цифры)
  • D - краткое название дня
  • DD - полное название дня
  • m - месяц года (без ведущего нуля)
  • mm - месяц года (две цифры)
  • M - краткое название месяца
  • MM - полное название месяца
  • y - год (две цифры)
  • yy - год (четыре цифры)
  • @ - временная метка Unix (мс с 01/01/1970)
  • ! - часы Windows (100ns с 01/01/0001)
  • '...' - буквальный текст
  • '' - одинарная кавычка
  • Всё остальное - буквальный текст

Также есть несколько$.datepickerпредопределённых стандартных форматов даты:

  • ATOM - 'yy-mm-dd' (то же, что RFC 3339/ISO 8601)
  • COOKIE - 'D, dd M yy'
  • ISO_8601 - 'yy-mm-dd'
  • RFC_822 - 'D, d M y' (см. RFC 822)
  • RFC_850 - 'DD, dd-M-y' (см. RFC 850)
  • RFC_1036 - 'D, d M y' (см. RFC 1036)
  • RFC_1123 - 'D, d M yy' (см. RFC 1123)
  • RFC_2822 - 'D, d M yy' (см. RFC 2822)
  • RSS - 'D, d M y' (то же, что и RFC 822)
  • TICKS - '!'
  • TIMESTAMP - '@'
  • W3C - 'yy-mm-dd' (то же, что и ISO 8601)
Примеры кода:

Отображает дату в формате ISO. Выводит "2007-01-26".

$.datepicker.formatDate( "yy-mm-dd", new Date( 2007, 1 - 1, 26 ) );

Отображает дату в расширенном французском формате. Выводит "Samedi, Juillet 14, 2007".

$.datepicker.formatDate( "DD, MM d, yy", new Date( 2007, 7 - 1, 14 ), {
  dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
  dayNames: $.datepicker.regional[ "fr" ].dayNames,
  monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
  monthNames: $.datepicker.regional[ "fr" ].monthNames
});

$.datepicker.parseDate( format, value, settings )

Извлекает дату из строкового значения с указанным форматом.

Формат может быть комбинацией следующего:

  • d - день месяца (без ведущего нуля)
  • dd - день месяца (две цифры)
  • o - день года (без ведущего нуля)
  • oo - день года (три цифры)
  • D — краткое название дня недели
  • DD — полное название дня недели
  • m - месяц года (без ведущего нуля)
  • mm - месяц года (две цифры)
  • M - краткое название месяца
  • MM - полное название месяца
  • y - год (две цифры)
  • yy - год (четыре цифры)
  • @ - временная метка Unix (мс с 01/01/1970)
  • ! - часы Windows (100ns с 01/01/0001)
  • '...' - буквальный текст
  • '' - одинарная кавычка
  • Всё остальное - буквальный текст

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

  • 'Invalid arguments' — выбрасывается, если формат или значение пусты.
  • 'Missing number at position nn' — выбрасывается, если формат указывает на число, которое не найдено.
  • 'Unknown name at position nn' — выбрасывается, если формат указывает на название дня недели или месяца, которое не найдено.
  • 'Unexpected literal at position nn' — выбрасывается, если формат указывает литеральное значение, которое не найдено.
  • 'Invalid date' — выбрасывается, если дата недействительна, например '31/02/2007'.
Примеры кода:

Извлекает дату в формате ISO.

$.datepicker.parseDate( "yy-mm-dd", "2007-01-26" );

Извлечь дату в расширенном французском формате.

$.datepicker.parseDate( "DD, MM d, yy", "Samedi, Juillet 14, 2007", {
  shortYearCuroff: 20,
  dayNamesShort: $.datepicker.regional[ "fr" ].dayNamesShort,
  dayNames: $.datepicker.regional[ "fr" ].dayNames,
  monthNamesShort: $.datepicker.regional[ "fr" ].monthNamesShort,
  monthNames: $.datepicker.regional[ "fr" ].monthNames
});

$.datepicker.iso8601Week( date )

Определить неделю года для заданной даты: от 1 до 53.

Эта функция использует определение недели по ISO 8601: неделя начинается с понедельника, и первая неделя каждого года содержит 4 января. Это означает, что в первую неделю текущего года может входить не более трёх дней из предыдущего года, а в последнюю неделю предыдущего года может входить не более трёх дней из текущего года.

Эта функция являетсяcalculateWeekреализацией по умолчанию для данной опции.

Примеры кода:

Найти неделю года для даты.

$.datepicker.iso8601Week( new Date( 2007, 1 - 1, 26 ) );

$.datepicker.noWeekends

Задать функцию, такую как beforeShowDay, чтобы предотвратить выбор выходных.

Мы можемbeforeShowDayукажите в опцииnoWeekends()функцию для вычисления всех рабочих дней, предоставляющуюtrue/falseмассив значений, указывающих, можно ли выбрать дату.

Примеры кода:

Настройте Datepicker так, чтобы выходные были недоступны для выбора.

$( "#datepicker" ).datepicker({
  beforeShowDay: $.datepicker.noWeekends
});

Ограничения

Datepicker поддерживает локализацию содержимого для разных языков и форматов даты. Каждая локализация содержится в файле, к имени которого добавлен код языка; например, французский —jquery.ui.datepicker-fr.js. Требуемый файл локализации необходимо подключить после основного кода datepicker. Каждый файл локализации добавляет свои настройки в доступную коллекцию локализаций, и все экземпляры автоматически применяют эти настройки как значения по умолчанию.

$.datepicker.regionalСвойство содержит массив локализаций с ключами по коду языка, где ключом по умолчанию является"", который представляет английский. Каждая запись — это объект со следующими свойствами:closeText、prevText、nextText、currentText、monthNames、monthNamesShort、dayNames、dayNamesShort、dayNamesMin、weekHeader、dateFormat、firstDay、isRTL、showMonthAfterYearиyearSuffix。

Вы можете восстановить локализацию по умолчанию с помощью следующего кода:

$.datepicker.setDefaults( $.datepicker.regional[ "" ] );

Вы можете переопределить datepicker для конкретной локали с помощью следующего кода:

$( selector ).datepicker( $.datepicker.regional[ "fr" ] );

Темы оформления

Виджет Datepicker используетjQuery UI CSS Frameworkдля определения его внешнего вида и поведения. Если вам нужно использовать стили, специфичные для datepicker, можно использовать следующие имена CSS-классов:

  • ui-datepicker: Внешний контейнер datepicker. Если datepicker встроен, этот элемент дополнительно будет иметьui-datepicker-inlineкласс. Если заданisRTLпараметр, этот элемент дополнительно будет иметьui-datepicker-rtl класс.
    • ui-datepicker-header: Контейнер заголовка datepicker.
      • ui-datepicker-prev: Элемент управления для выбора предыдущего месяца.
      • ui-datepicker-next: Элемент управления для выбора следующего месяца.
      • ui-datepicker-title: Контейнер заголовка datepicker, содержащий месяц и год.
        • ui-datepicker-month: Текстовое отображение месяца. ЕслиchangeMonthопция установлена, отображает<select>элементу.
        • ui-datepicker-year: Текстовое отображение года. ЕслиchangeYearопция установлена, отображает<select>элементу.
    • ui-datepicker-calendar: Таблица, содержащая календарь.
      • ui-datepicker-week-end: Ячейки, содержащие выходные дни.
      • ui-datepicker-other-month: Ячейки для дней, которые встречаются в месяце, но не являются днями текущего месяца.
      • ui-datepicker-unselectable: Ячейки, которые не могут быть выбраны пользователем.
      • ui-datepicker-current-day: Ячейки для выбранной даты.
      • ui-datepicker-today: Ячейки для текущей даты.
    • ui-datepicker-buttonpane: КогдаshowButtonPanelопция используется, применяется панель кнопок.
      • ui-datepicker-current: Кнопка, используемая для выбора текущей даты.

ЕслиnumberOfMonthsопция используется для отображения нескольких месяцев, применяются некоторые дополнительные классы:

  • ui-datepicker-multi: Самый внешний контейнер datepicker с несколькими месяцами. Этот элемент дополнительно будет иметьui-datepicker-multi-2、ui-datepicker-multi-3илиui-datepicker-multi-4имя класса в зависимости от количества отображаемых месяцев.
    • ui-datepicker-group: Отдельный picker внутри группы. Этот элемент дополнительно будет иметьui-datepicker-group-first、ui-datepicker-group-middleилиui-datepicker-group-lastимя класса в зависимости от его позиции в группе.

Зависимости

Дополнительные примечания

  • Для этого виджета требуется некоторый функциональный CSS, иначе он не будет работать. Если вы создаёте собственную тему, используйте CSS-файл, специфичный для виджета, в качестве отправной точки.
  • Этот виджет программно управляет значением элемента, поэтому нативноеchangeсобытие не будет инициировано при изменении значения.
  • : Не поддерживается на<input type="date">: создание Datepicker, поскольку это вызовет конфликты пользовательского интерфейса с нативным средством выбора.

Примеры

Простой Datepicker из jQuery UI.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>日期选择器部件(Datepicker Widget)演示</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
 
<div id="datepicker"></div>
 
<script>
$( "#datepicker" ).datepicker();
</script>
 
</body>
</html>

Другие расширения