Latest web development tutorials

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

所屬類別

小部件（Widgets）

用法

描述：從彈出框或內聯日曆選擇一個日期。

版本新增： 1.0

jQuery UI 日期選擇器（Datepicker）是向頁面添加日期選擇功能的高度可配置插件。 您可以自定義日期格式和語言，限制可選擇的日期範圍，添加按鈕和其他導航選項。

默認情況下，當相關的文本域獲得焦點時，在一個小的覆蓋層打開日期選擇器。 對於一個內聯的日曆，只需簡單地將日期選擇器附加到div 或者span 上。

鍵盤交互

當日期選擇器打開時，下面的鍵盤命令可用：

  • PAGE UP：移到上一個月。
  • PAGE DOWN：移到下一個月。
  • CTRL+PAGE UP：移到上一年。
  • CTRL+PAGE DOWN：移到下一年。
  • CTRL+HOME：移到當前月份。 如果日期選擇器是關閉的則打開。
  • CTRL+LEFT：移到上一天。
  • CTRL+RIGHT：移到下一天。
  • CTRL+UP：移到上一周。
  • CTRL+DOWN：移到下一周。
  • ENTER：選擇聚焦的日期。
  • CTRL+END：關閉日期選擇器，並清除日期。
  • ESCAPE：關閉日期選擇器，不做任何選擇。

實用功能

$.datepicker.setDefaults( settings )

為所有的日期選擇器改變默認設置。

使用option()方法來改變個別實例的設置。

代碼實例：

設置所有的日期選擇器在獲得焦點時或點擊圖標時打開。 

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

設置所有的日期選擇器都有法語文本。 

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

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

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

格式可以是下列組合：

  • d - 一月中的第幾天（沒有前導零）
  • dd - 一月中的第幾天（兩位數）
  • o - 一年中的第幾天（沒有前導零）
  • oo - 一年中的第幾天（三位數）
  • D - 天的短名稱
  • DD - 天的長名稱
  • m - 一年中的第幾月（沒有前導零）
  • mm - 一年中的第幾月（兩位數）
  • M - 月的短名稱
  • MM - 月的長名稱
  • y - 年（兩位數）
  • yy - 年（四位數）
  • @ - Unix 時間戳（ms since 01/01/1970）
  • ! - Windows 鐘錶（100ns since 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-My' （參照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 時間戳（ms since 01/01/1970）
  • ! - Windows 鐘錶（100ns since 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 定義一周：一周從星期一開始，每一年的第一周包含1 月4 日。 這意味著上一年至多有三天可能包含在當年的第一周中，當年至多有三天可能包含在上一年的最後一周中。

該函數是calculateWeek選項的默認實現。

代碼實例：

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

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

$.datepicker.noWeekends

設置如beforeShowDay 函數，防止選擇週末。

我們可以在beforeShowDay選項中提供noWeekends()函數，用來計算所有工作日，提供一個true / false值的數組，用來指示日期是否可選擇。

代碼實例：

設置DatePicker，讓周末不可選。 

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

局限

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

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

您可以通過下面代碼恢復默認的本地化：

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

您可以通過下面代碼覆蓋一個特定地點的日期選擇器：

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

主題化

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

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

如果numberOfMonths選項用於顯示多個月份，則使用一些額外的class：

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

依賴

附加說明

  • 該部件要求一些功能性的CSS，否則將無法工作。 如果您創建了一個自定義的主題，請使用小部件指定的CSS 文件作為起點。
  • 該部件以編程方式操作元素的值，因此當元素的值改變時不會觸發原生的change事件。
  • 不支持在<input type="date">上創建日期選擇器，因為會造成與本地選擇器的UI衝突。

實例

一個簡單的jQuery UI 日期選擇器（Datepicker）。 

<!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>