jQuery UI API - 日期選擇器部件（Datepicker Widget） · W3School jQuery UI 教程

# jQuery UI API - 日期選擇器部件（Datepicker Widget） ## 所屬類別 [小部件（Widgets）](ref-widgets.html) ## 用法 **描述：**從彈出框或內聯日歷選擇一個日期。 **版本新增：**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()`](#method-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-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 時間戳（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`](#option-calculateWeek) 選項的默認實現。 **代碼實例：** 查找日期在一年中的第幾周。 ``` $.datepicker.iso8601Week( new Date( 2007, 1 - 1, 26 ) ); ``` #### $.datepicker.noWeekends 設置如 beforeShowDay 函數，防止選擇周末。我們可以在 [`beforeShowDay`](#option-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 框架](api-css-framework.html) 來定義它的外觀和感觀的樣式。如果需要使用日期選擇器指定的樣式，則可以使用下面的 CSS class 名稱： * `ui-datepicker`：日期選擇器的外層容器。如果日期選擇器是內聯的，該元素會另外帶有一個 `ui-datepicker-inline` class。如果設置了 [`isRTL`](#option-isRTL) 選項，該元素會另外帶有一個 `ui-datepicker-rtl` class。 * `ui-datepicker-header`：日期選擇器的頭部容器。 * `ui-datepicker-prev`：用于選擇上一月的控件。 * `ui-datepicker-next`：用于選擇下一月的控件。 * `ui-datepicker-title`：日期選擇器包含月和年的標題容器。 * `ui-datepicker-month`：月的文本顯示，如果設置了 [`changeMonth`](#option-changeMonth) 選項則顯示 `<select>` 元素。 * `ui-datepicker-year`：年的文本顯示，如果設置了 [`changeYear`](#option-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`](#option-showButtonPanel) 選項時使用按鈕面板（buttonpane）。 * `ui-datepicker-current`：用于選擇當天日期的按鈕。如果 [`numberOfMonths`](#option-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 名稱。 ### 依賴 * [UI 核心（UI Core）](ref-ui-core.html) * [特效核心（Effects Core）](ref-effects-core.html)（可選的；當與 [`showAnim`](#option-showAnim) 選項一起使用時） ### 附加說明 * 該部件要求一些功能性的 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> ```