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