日期选择器部件(Datepicker Widget)
所属类别
用法
描述:从弹出框或内联日历选择一个日期。
版本新增: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-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
选项的默认实现。
查找日期在一年中的第几周。
$.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 名称。
依赖
- UI 核心(UI Core)
- 特效核心(Effects Core)(可选的;当与
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>