jQuery UI API - 日期選擇器部件（Datepicker Widget）

所屬類別

小部件（Widgets）

用法

描述：從彈出框或內(nèi)聯(lián)日歷選擇一個(gè)日期。

版本新增：1.0

jQuery UI 日期選擇器（Datepicker）是向頁(yè)面添加日期選擇功能的高度可配置插件。您可以自定義日期格式和語(yǔ)言，限制可選擇的日期范圍，添加按鈕和其他導(dǎo)航選項(xiàng)。

默認(rèn)情況下，當(dāng)相關(guān)的文本域獲得焦點(diǎn)時(shí)，在一個(gè)小的覆蓋層打開(kāi)日期選擇器。對(duì)于一個(gè)內(nèi)聯(lián)的日歷，只需簡(jiǎn)單地將日期選擇器附加到 div 或者 span 上。

鍵盤交互

當(dāng)日期選擇器打開(kāi)時(shí)，下面的鍵盤命令可用：

  • PAGE UP：移到上一個(gè)月。
  • PAGE DOWN：移到下一個(gè)月。
  • CTRL+PAGE UP：移到上一年。
  • CTRL+PAGE DOWN：移到下一年。
  • CTRL+HOME：移到當(dāng)前月份。如果日期選擇器是關(guān)閉的則打開(kāi)。
  • CTRL+LEFT：移到上一天。
  • CTRL+RIGHT：移到下一天。
  • CTRL+UP：移到上一周。
  • CTRL+DOWN：移到下一周。
  • ENTER：選擇聚焦的日期。
  • CTRL+END：關(guān)閉日期選擇器，并清除日期。
  • ESCAPE：關(guān)閉日期選擇器，不做任何選擇。

實(shí)用功能

$.datepicker.setDefaults( settings )

為所有的日期選擇器改變默認(rèn)設(shè)置。

使用 option() 方法來(lái)改變個(gè)別實(shí)例的設(shè)置。

代碼實(shí)例：

設(shè)置所有的日期選擇器在獲得焦點(diǎn)時(shí)或點(diǎn)擊圖標(biāo)時(shí)打開(kāi)。

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

設(shè)置所有的日期選擇器都有法語(yǔ)文本。

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

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

格式化日期為一個(gè)帶有指定格式的字符串值。

格式可以是下列組合：

  • d - 一月中的第幾天（沒(méi)有前導(dǎo)零）
  • dd - 一月中的第幾天（兩位數(shù)）
  • o - 一年中的第幾天（沒(méi)有前導(dǎo)零）
  • oo - 一年中的第幾天（三位數(shù)）
  • D - 天的短名稱
  • DD - 天的長(zhǎng)名稱
  • m - 一年中的第幾月（沒(méi)有前導(dǎo)零）
  • mm - 一年中的第幾月（兩位數(shù)）
  • M - 月的短名稱
  • MM - 月的長(zhǎng)名稱
  • y - 年（兩位數(shù)）
  • yy - 年（四位數(shù)）
  • @ - Unix 時(shí)間戳（ms since 01/01/1970）
  • ! - Windows 鐘表（100ns since 01/01/0001）
  • '...' - 文本
  • '' - 單引號(hào)
  • 其他 - 文本

也有一些 $.datepicker 預(yù)定義的標(biāo)準(zhǔn)日期格式：

  • 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 相同）
代碼實(shí)例：

以 ISO 格式顯示日期。產(chǎn)生 "2007-01-26"。

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

以擴(kuò)展法語(yǔ)格式顯示日期。產(chǎn)生 "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 )

從一個(gè)指定格式的字符串值中提取日期。

格式可以是下列組合：

  • d - 一月中的第幾天（沒(méi)有前導(dǎo)零）
  • dd - 一月中的第幾天（兩位數(shù)）
  • o - 一年中的第幾天（沒(méi)有前導(dǎo)零）
  • oo - 一年中的第幾天（三位數(shù)）
  • D - 星期幾的短名稱
  • DD - 星期幾的長(zhǎng)名稱
  • m - 一年中的第幾月（沒(méi)有前導(dǎo)零）
  • mm - 一年中的第幾月（兩位數(shù)）
  • M - 月的短名稱
  • MM - 月的長(zhǎng)名稱
  • y - 年（兩位數(shù)）
  • yy - 年（四位數(shù)）
  • @ - Unix 時(shí)間戳（ms since 01/01/1970）
  • ! - Windows 鐘表（100ns since 01/01/0001）
  • '...' - 文本
  • '' - 單引號(hào)
  • 其他 - 文本

一些可能被拋出的異常：

  • 'Invalid arguments' - 如果格式或值為空則拋出此異常。
  • 'Missing number at position nn' - 如果格式顯示一個(gè)未找到的數(shù)值則拋出此異常。
  • 'Unknown name at position nn' - 如果格式顯示一個(gè)未找到的星期幾名稱或月份名稱則拋出此異常。
  • 'Unexpected literal at position nn' - 如果格式顯示一個(gè)未找到的文本值則拋出此異常。
  • 'Invalid date' - 如果日期無(wú)效則拋出此異常，比如 '31/02/2007'。
代碼實(shí)例：

提取一個(gè) ISO 格式的日期。

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

提取一個(gè)擴(kuò)展法語(yǔ)格式的日期。

$.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 )

確定一個(gè)給定的日期在一年中的第幾周：1 到 53。

該函數(shù)使用 ISO 8601 定義一周：一周從星期一開(kāi)始，每一年的第一周包含 1 月 4 日。這意味著上一年至多有三天可能包含在當(dāng)年的第一周中，當(dāng)年至多有三天可能包含在上一年的最后一周中。

該函數(shù)是 calculateWeek 選項(xiàng)的默認(rèn)實(shí)現(xiàn)。

代碼實(shí)例：

查找日期在一年中的第幾周。

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

$.datepicker.noWeekends

設(shè)置如 beforeShowDay 函數(shù)，防止選擇周末。

我們可以在 beforeShowDay 選項(xiàng)中提供 noWeekends() 函數(shù)，用來(lái)計(jì)算所有工作日，提供一個(gè) true/false 值的數(shù)組，用來(lái)指示日期是否可選擇。

代碼實(shí)例：

設(shè)置 DatePicker，讓周末不可選。

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

局限

日期選擇器提供了迎合不同的語(yǔ)言和日期格式本地化內(nèi)容的支持。每個(gè)本地化包含在名稱后追加語(yǔ)言代碼的文件中，例如法語(yǔ)為 jquery.ui.datepicker-fr.js。所需的本地化文件需要包含在主要的日期選擇器代碼后面。每個(gè)本地化文件添加了它自己的設(shè)置到可用的本地化集合中，所有實(shí)例自動(dòng)應(yīng)用這些設(shè)置為默認(rèn)設(shè)置。

$.datepicker.regional 屬性保存了一個(gè)本地化數(shù)組，以語(yǔ)言代碼作為前置，默認(rèn)前置為 ""，表示英語(yǔ)。每個(gè)條目是一個(gè)帶有下列屬性的對(duì)象：closeText、prevText、nextText、currentText、monthNames、monthNamesShort、dayNames、dayNamesShort、dayNamesMin、weekHeader、dateFormat、firstDay、isRTL、showMonthAfterYear 和 yearSuffix。

您可以通過(guò)下面代碼恢復(fù)默認(rèn)的本地化：

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

您可以通過(guò)下面代碼覆蓋一個(gè)特定地點(diǎn)的日期選擇器：

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

主題化

日期選擇器部件（Datepicker Widget）使用 jQuery UI CSS 框架 來(lái)定義它的外觀和感觀的樣式。如果需要使用日期選擇器指定的樣式，則可以使用下面的 CSS class 名稱：

  • ui-datepicker：日期選擇器的外層容器。如果日期選擇器是內(nèi)聯(lián)的，該元素會(huì)另外帶有一個(gè) ui-datepicker-inline class。如果設(shè)置了 isRTL 選項(xiàng)，該元素會(huì)另外帶有一個(gè) ui-datepicker-rtl class。
    • ui-datepicker-header：日期選擇器的頭部容器。
      • ui-datepicker-prev：用于選擇上一月的控件。
      • ui-datepicker-next：用于選擇下一月的控件。
      • ui-datepicker-title：日期選擇器包含月和年的標(biāo)題容器。
        • ui-datepicker-month：月的文本顯示，如果設(shè)置了 changeMonth 選項(xiàng)則顯示 <select> 元素。
        • ui-datepicker-year：年的文本顯示，如果設(shè)置了 changeYear 選項(xiàng)則顯示 <select> 元素。
    • ui-datepicker-calendar：包含日歷的表格。
      • ui-datepicker-week-end：周末的單元格。: Cells containing weekend days.
      • ui-datepicker-other-month：發(fā)生在某月但不是當(dāng)前月天數(shù)的單元格。
      • ui-datepicker-unselectable：用戶不可選擇的單元格。
      • ui-datepicker-current-day：已選中日期的單元格。
      • ui-datepicker-today：當(dāng)天日期的單元格。
    • ui-datepicker-buttonpane：當(dāng)設(shè)置 showButtonPanel 選項(xiàng)時(shí)使用按鈕面板（buttonpane）。
      • ui-datepicker-current：用于選擇當(dāng)天日期的按鈕。

如果 numberOfMonths 選項(xiàng)用于顯示多個(gè)月份，則使用一些額外的 class：

  • ui-datepicker-multi：一個(gè)多月份日期選擇器的最外層容器。該元素會(huì)根據(jù)要顯示的月份個(gè)數(shù)另外帶有 ui-datepicker-multi-2、ui-datepicker-multi-3 或 ui-datepicker-multi-4 class 名稱。
    • ui-datepicker-group：分組內(nèi)單獨(dú)的選擇器。該元素會(huì)根據(jù)它在分組中的位置另外帶有 ui-datepicker-group-first、ui-datepicker-group-middle 或 ui-datepicker-group-last class 名稱。

依賴

附加說(shuō)明

  • 該部件要求一些功能性的 CSS，否則將無(wú)法工作。如果您創(chuàng)建了一個(gè)自定義的主題，請(qǐng)使用小部件指定的 CSS 文件作為起點(diǎn)。
  • 該部件以編程方式操作元素的值，因此當(dāng)元素的值改變時(shí)不會(huì)觸發(fā)原生的 change 事件。
  • 不支持在 <input type="date"> 上創(chuàng)建日期選擇器，因?yàn)闀?huì)造成與本地選擇器的 UI 沖突。

實(shí)例

一個(gè)簡(jiǎn)單的 jQuery UI 日期選擇器（Datepicker）。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>日期選擇器部件（Datepicker Widget）演示</title>
  <link rel="stylesheet"  rel="external nofollow" target="_blank" >
  <script src="http://code.jquery.com/jquery-1.10.2.js" rel="external nofollow" ></script>
  <script src="http://code.jquery.com/ui/1.10.4/jquery-ui.js" rel="external nofollow" ></script>
</head>
<body>
 
<div id="datepicker"></div>
 
<script>
$( "#datepicker" ).datepicker();
</script>
 
</body>
</html>

查看演示