【jQuery UI 1.8 The User Interface Library for jQuery】.学习笔记.8.Datepicker控件

• 默认datepicker的安装启用
• 探索它的配置选项
• 安装启用一个触发按钮
• 配置一个供选择的动画
• dateFormat选项
• 简单的国际化
• 多月datepicker
• 日期范围选择
• datepicker的方法
• 使用AJAX的datepicker

按着Ctrl键期间，箭头可以用来选择新的day cell，按Return键选中。

1 默认的datepicker

1 <label for="date">Enter a date:</label>2 <input id="date">3 $(function(){ 4 $("#date").datepicker(); 5 });

2 datepicker的配置选项

Option	Default value	Usage
altField	“”	指定一个候选的<input>CSS选择器，当选择日期后，日期也被加入该选择器
altFormat	“”	为候选<input>指定一个候选的日期格式。
appendText	“”	当<input>显示被选择日期时，加入的text
autoSize	false	自动设置<input>元素的宽度，使其能适应特定的日期格式
buttonImage	“”	为<button>触发器指定一个图片路径
buttonImageOnly	false	当设置为true时，用一个图片替代button触发器
buttonText	“…”	在<button>触发器上显示的文本
calculateWeek	$.datepicker.iso8601Week	接收一个函数，用来计算这天是这年的第几周
changeMonth	false	显示month的下拉列表
chengeYear	false	显示year的下拉列表
constrainInput	true	约束<input>的日期格式
defaultDate	null	当datepicker打开时,<input>为空，设置高亮日期
disable	false	禁用
duration	“normal”	设置datepicker打开的速度
gotoCurrent	false	设置当前日期链接，使datepicker移动到当前被选择的日期，而不是今天
hideIfNoPreNext	false	当没有需要的时候，隐藏 pre/next 链接，而不是禁用他们
maxDate	null	设置能被选择的最大日期。接受一个日期对象或相对数字。例如，+7，或者一个字符串，如 +6m
minDate	null	试着能被选择的最小日期，同上
navigationAsDateFormat	false	允许我们使用prev ,next, current links指定月的名字
numberOfMonths	1	设置在datepicker上一页只显示的一个月的日期
selectOtherMonths	false	允许上个月和下个月的日期在当前月的panel上，可被选择。显不显示由showOtherMonths决定。
shortYearCutoff	“+10”	当使用 y year 代表当前世纪的年
showAnim	“show”	设置datepicker显示时的动画
showButtonPanel	false	显示由关闭，当前链接构成的buttons panel
showCurrentAtPos	0	设置当前月份在多月份datepicker中的位置
showOn	“focus”	设置触发datepicker的事件
showOptions	{}	一个文字对象，包含控制动画配置的选项
showOtherMonths	false	显示前一个月和后一个月的最后一个和第一个日子。能不能被选择由selectOtherMonths决定。
showWeek	false	用一个列显示这是这年的第几周。与calculateWeek选项关联
stepMonths	1	设置使用上一个下一个链接时，被导航几个月
yearRange	“-10:+10”	指定year下拉框的范围

2.1 基本选项

1 (function($){ 2 var pickerOpts = { 3 appendText: "mm/dd/yy", 4 defaultDate: "+5", 5 showOtherMonths: true 6 }; 7 $("#date").datepicker(pickerOpts); 8 })(jQuery);

appendText选项的值，在datepicker出现之前，就显示在初始页面上，通过<span>直接显示在<input>后面。处于样式的目的，我们可以通过 .ui-datepicker-append classname触发这个新的<span>元素。

当datepicker打开初始化，此时的<input>为空时，defaultDate 选项设置高亮的日期。Enter键可以选择高亮的日期。若给defaultDate传null或者一个标准的 JavaScript 日期对象,，则当前日期会被选中。

current date和 default date的显示效果不同。current date 是亮黄色，default date有着灰边框。

一旦日期已经被选择过，接下来打开时，被选择的日期会作为default date。

2.2 最大最小日期

默认地，没有上下边界。

1 var pickerOpts = { 2 minDate: new Date(), 3 maxDate: "+10" 4 };

我们传递一个标准的，没有修改的JavaScript date object 给 minDate 选项，它会设置最小值今天。

最大最小日期也接受 +6w , –10m , 1y 。

2.3 改变datepicker ui 的元素

datepicker API 暴露了大量的能够直接添加移除附加 datepicker 中 UI 元素的选项。

1 var pickerOpts = { 2 changeMonth: true, 3 changeYear: true 4 };

这两个选项能够启用年和月的下拉框。默认地，年的下拉框包含前10年和后10年。

1 var pickerOpts = { 2 changeMonth: true, 3 changeYear: true, 4 yearRange: "-25:+25" 5 };

通过 yearRange选项可以扩大可选年的范围。

1 var pickerOpts = { 2 showButtonPanel: true 3 };

启用button panel。

2.4 添加button触发器

1 var pickerOpts = { 2 showOn: "button", 3 buttonText: "Open Picker" 4 };

这个配置选项，会为在关联的<input>后面直接地、自动地添加一个button元素。buttonText指定了该button的文本。

1 var pickerOpts = { 2 showOn: "button", 3 buttonText: "Open Picker" 4 buttonImage: "img/cal.png", 5 };

此时button显示的是图片，没有显示buttonText。原因是，buttonText选项的值被自动作为<img>元素的title 和 alt 属性。

1 var pickerOpts = { 2 showOn: "button", 3 buttonImage: "img/date-picker/cal.png", 4 buttonText: "Open Picker", 5 buttonImageOnly: true 6 }

2.5 配置可选的动画效果

这里有 duration , showAnim , showOptions 配置选项。

duration 可以简单地配置 datepicker 打开关闭的速度。它需要一个字符串参数（slow , normal ,fast），或者一个以 milliseconds 为单位的数字。

showAnim会改变动画。默认的动画用来简单地显示动画，但是我们也能使用库中的任何 show/hide 效果。

1 var pickerOpts = { 2 showAnim: "drop", 3 showOptions: {direction: "up"} 4 };

为了使用showAnim 和 showOption 选项，我们需要引用 jquery.effects.core.js和 jquery.effects.drop.js 两个文件。

2.6 多个月

1 var pickerOpts = { 2 numberOfMonths: 3 3 };

控件没有限制能够显示month的数量。但是多一个就会影响性能。和多月datepickers关联的选项还有stepMonths，它控制当我们点击上一个或下一个链接时，多少个月会变化。

另一个和多月datepicker相关的是showCurrentAtPos选项。默认当前月位于所有打开的月的第一个。可以通过以零开头的索引，改变当前页所处的位置。

2.7 改变日期格式

有大小写之分 case-sensitive

d	适用与一个数字的日
dd	两个数字的日
m	适用于一个数字的月
mm	两个数字的月
y	两个数字的年
yy	四个数字的年
D	短日名
DD	全日名
M	短月名
MM	长月名
‘…’	任何字符串
@	UNIX 时间戳，从1970/01/01开始的总milliseconds

dates以代码地方式返回，是通过getDate方法，传递GMT标准日期时间。为了转换日期格式，会用到$.datepicker.formatDate()功能。

当我们在date开始处添加 Selected: 字符串，我们需要使用 Selecte’d’: 字符串。因为小写的 d 是 短日名 的格式。

1 var pickerOpts = { 2 dateFormat:"Selecte'd': d MM yy" 3 };

这里也有一些内置的公共标准格式。这些格式以常量和能被通过 $.datepicker 访问的对象，添加到组件。

Option value Short-hand Formatted as…
$.datepicker.ATOM "yy-mm-dd" 2011-04-13
$.datepicker.COOKIE "D, dd M y" Wed, 13 Apr 2011
$.datepicker.ISO_8601 "yy-mm-dd" 2011-04-13
$.datepicker.RFC_822 "D, d M y" Wed, 13 Apr 11
$.datepicker.RFC_850 "DD, dd-M-y" Wednesday, 13-Apr-11
$.datepicker.RFC_1036 "D, d M y" Wed, 13 Apr 11
$.datepicker.RFC_1123 "D, d M yy" Wed, 13 Apr 2011
$.datepicker.RFC_2822 "D, d M yy" Wed, 13 Apr 2011
$.datepicker.RSS "D, d M y" Wed, 13 Apr 11
$.datepicker.TIMESTAMP @ (UNIX timestamp) 1302649200000
$.datepicker.W3C "yy-mm-dd" 2011-04-13

2.8 更新附加的input元素

有时我们想通过选择一个时期更新两个<input>，并显示不同的日期格式。

1 var pickerOpts = { 2 altField: "#alt", 3 altFormat: $.datepicker.TIMESTAMP 4 };

2.9 本地化

这里也有一些区域化的选项。他们能够为简单地用可选的语言显示datepicker的文本，或者改变英语单词，从而简单地提供客户本地化支持。

Option	Default	Usage
closeText	“Close”	关闭按钮上显示的文本
currentText	“Current”	当前日期链接上显示的文本
dateFormat	“mm/dd/yy”	当添加到<input>时，日期的格式
dayNames	[“Sunday”,”Monday”,”Tusday”,”Wednesday”,”Thursday”,”Friday”,”Saturday”]	一星期每天的名字数组
dayNamesMin	["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"]	一星期中，每天两个字的名字数组
dayNamesShort	["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]	一星期中，每天简短的名字数组
firstDay		指定datepicker第一列的日期
isRTL	false	将日历设置为从右向左的格式
monthNames	["January", "Febru-ary", "March", "April", "May", "June", "July, "August", "September", "October", "November", "December"]	月的名字数组
monthNamesShot	["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]	月的简短名字数组
nextText	“Next”	下一个链接上的文本
prevText	“Prev”	上一个链接上的文本
showMonthAfterYear	false	在控件header上显示下一年的月
yearSuffix	“”	在month header中的年后面显示一个附加的字符串文本。

1 var pickerOpts = { 2 closeText: "Kthxbai", 3 currentText: "Todai", 4 nextText: "Fwd", 5 prevText: "Bak", 6 monthNames: ["January", "February", "March", "April", "Mai", "Jun", 7 "July", "August", "Septembr", "Octobr", "Novembr", "Decembr"], 8 monthNamesShort: ["Jan", "Feb", "Mar", "Apr", "Mai", "Jun", "Jul", 9 "Aug", "Sep", "Oct", "Nov", "Dec"], 10 dayNames: ["Sundai", "Mondai", "Tuesdai", "Wednesdai", "Thursdai", 11 "Fridai", "Katurdai"], 12 dayNamesShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Kat"], 13 The Datepicker Widget 14 [ 180 ] 15 dayNamesMin: ["Su", "Mo", "Tu", "We", "Th", "Fr", "Ka"], 16 dateFormat: 'dd/mm/yy', 17 firstDay: 1, 18 isRTL: false, 19 showButtonPanel: true 20 };

可以手工配置每个部分的名字，也可以使用默认配置。一个大范围的不同翻译已经被提供，就位于 i18n 文件夹中。

2.10 回调属性

Event	Fired when…
beforeShow	将要打开
beforeShowDay	每个日期个体都会被提出来，用来检测是否这个日期应该被选择
onChangeMonthYear	当前月或年变化
onClose	关闭后
onSelect	一个日期被选择

1 <select id="language"> 2 <option id="en-GB">English</option> 3 <option id="ar">Arabic</option> 4 <option id="ar-DZ">Algerian Arabic</option> 5 <option id="az">Azerbaijani</option> 6 <option id="bg">Bulgarian</option> 7 <option id="bs">Bosnian</option> 8 <option id="ca">Catalan</option> 9 <option id="cs">Czech</option>10 <option id="da">Danish</option>11 <option id="de">German</option>12 <option id="el">Greek</option>13 <option id="en-AU">English/Australia</option>14 <option id="en-NZ">English/New Zealand</option>15 <option id="en-US">English/United States</option>16 <option id="eo">Esperanto</option>17 <option id="es">Spanish</option>18 <option id="et">Estonian</option>19 <option id="eu">Euskarako</option>20 <option id="fa">Farsi</option>21 <option id="fi">Finnish</option>22 <option id="fo">Faroese</option>23 <option id="fr">French</option>24 <option id="fr-CH">Swiss-French</option>25 <option id="gl">Galician</option>26 <option id="he">Hebrew</option>27 <option id="hr">Croatian</option>28 <option id="hu">Hungarian</option>29 <option id="hy">Armenian</option>30 <option id="id">Indonesian</option>31 <option id="is">Icelandic</option>32 <option id="it">Italian</option>33 <option id="ja">Japanese</option>34 <option id="ko">Korean</option>35 <option id="kz">Kazakh</option>36 <option id="lt">Lithuanian</option>37 <option id="lv">Latvian</option>38 <option id="ml">Malayalam</option>39 <option id="ms">Malaysian</option>40 <option id="nl">Dutch</option>41 <option id="no">Norwegian</option>42 <option id="pl">Polish</option>43 <option id="pt-BR">Brazillian</option>44 <option id="pt">Portuguese</option>45 <option id="rm">Romansh</option>46 <option id="ro">Romanian</option>47 <option id="ru">Russian</option>48 <option id="sk">Slovakian</option>49 <option id="sl">Slovenian</option>50 <option id="sq">Albanian</option>51 <option id="sr-SR">Serbian</option>52 <option id="sv">Swedish</option>53 <option id="ta">Tamil</option>54 <option id="th">Thai</option>55 <option id="tr">Turkish</option>56 <option id="uk">Ukrainian</option>57 <option id="vi">Vietnamese</option>58 <option id="zh-CN">Chinese</option>59 <option id="zh-HK">Chinese</option>60 <option id="zh-TW">Taiwanese</option>61 </select>62 <input id="date">63 $(function(){ 64 var pickerOpts = { 65 beforeShow: function() { 66 var lang = $(":selected", $("#language")).attr("id"); 67 $.datepicker.setDefaults($.datepicker.regional[lang]); 68 } 69 }; 70 $("#date").datepicker(pickerOpts); 71 $.datepicker.setDefaults($.datepicker.regional['']); 72 });

我们使用beforeShow回调函数，每次datepicker显示时都会执行它。获得被选中的 选项  的id，传递给 $.datepicker.regional 选项。这个选项通过 $.datepicker.setDefaults() 功能设置。

3 功能方法

Utility	Used to…
formatDate	用指定的格式将日期对象转换为字符串。当使用dateFormate 方法时，日期会通过 formatDate 以指定的格式返回。这个方法接受三个参数，要转成的格式，要转换的日期，一个附加的配置选项（包括 dayNamesShort , dayNames , monthNamesShort , monthNames）
iso8601Week	依据 ISO8601 日期时间标准，返回指定日期的周数。这个方法接受一个参数——指定日期
noWeekends	使得周末不能被选中。它能被传递给 beforeShowDay 事件
parseDate	与 formatDate相反，转换一个格式化的日期字符串成日期对象。接收三个参数，预期的日期解析格式，要转换的日期字符串，一个配置对象选项（shortYearCutoff，dayNamesShort，dayNames，monthNameShort，monthNames）
regional	设置datepicker的语言
setDefaults	为所有的datepicker设置配置选项。接受一个包含新配置选项的字符对象

这些方法被$.datepicker管理对象作为一个单独的实例被调用。在初始化时，它自动被控件创建。

4  选择方法

Method	Used to…
dialog	在对话框控件中打开datepicker
getDate	得到当前被选择的日期
hide	以编码的形式关闭
isDisabled	检测datepicker是否被关闭
refresh	重绘一个datepicker
setDate	以编码的形式选择一个日期
show	以编码的形式显示一个datepicker

4.1 以代码的方式选择一个日期

1 <input id="date">2 <button id="setDate" type="button">SetDate</button>3 4 $(function(){ 5 $("#date").datepicker(); 6 $("#setDate").click(function(){ 7 $("#date").datepicker("setDate","+7") 8 }); 9 });

像defaultDate配置选项一样，支持相对文本，或者一个日期对象。

4.2 在 dialog box 中显示 datepicker

1 <style> 2 .ui-datepicker { width: 17em; padding: .2em .2em 0; z-index: 9999 !important;} 3 </style> 4 <input id="date"> 5 <script> 6 $(function(){ 7 function updateDate(date){ 8 $("#date").val(date); 9 } 10 $("#date").focus(function(){ 11 $(this).datepicker("dialog",null,updateDate); 12 }); 13 }); 14 </script>

updateDate回调函数会在每次日期被选中时被调用。对话框中的datepicker选中日期后，不会写给<input>，需要使用此函数，将值传给<input>。

我们使用focus事件调用dialog方法，它有两个参数，第一个设为了null，所以默认会选中当前日期。第二个是当日期被选中时的回调函数，被映射到updateDate函数。

我们也支持额外的第三个第四个参数。第三个参数是datepicker的配置对象。第四个是用来控制包含datepicker的dialog位置。默认的，位置在屏幕中央。

如果看不到弹出的dialog和 datepicker，那么使用以下样式

1 .ui-datepicker { 17em; padding: .2em .2em 0; z-index: 9999 !important; }

5  AJAX datepicker

1 <body> 2 <div id="bookingForm" class="ui-widget ui-corner-all"> 3 <div class="ui-widget-header ui-corner-top"> 4 <h2>Booking Form</h2> 5 </div> 6 <div class="ui-widget-content ui-corner-bottom"> 7 <label>Appointment date:</label><input id="date"> 8 </div> 9 <div>10 <script src="development-bundle/jquery-1.4.4.js"></script>11 <script src="jq/jquery-ui-1.8.9.js"></script>12 <script>13 (function($){ 14 var months = [], 15 days = []; 16 $.getJSON( 17 "http://www.danwellman.co.uk/bookedDates.php?jsoncallback=?", 18 function(data) { 19 for (var x =0; x < data.dates.length; x++) { 20 months.push(data.dates[x].month); 21 days.push(data.dates[x].day); 22 } 23 } 24 ); 25 function addDates(date){ 26 if (date.getDay() ==0|| date.getDay() ==6) { 27 return [false, ""]; 28 } 29 for (var x =0; x < days.length; x++) { 30 if (date.getMonth() == months[x] -1&&31 date.getDate() == days[x]) { 32 return [false, "preBooked_class"]; 33 } 34 } 35 return [true, ""]; 36 } 37 var pickerOpts = { 38 beforeShowDay: addDates, 39 minDate: "+1"40 }; 41 $("#date").datepicker(pickerOpts); 42 })(jQuery); 43 </script>44 <style>45 #bookingForm { width:503px;}46 #bookingForm h2 { margin-left:20px;}47 #bookingForm .ui-widget-content {48 padding:20px 0; border-top:none;49 }50 label {51 margin:4px 20px 0; font-family:Verdana; font-size:80%;52 float:left;53 }54 #date { width:302px;}55 .ui-datepicker .preBooked_class { background:none;}56 .ui-datepicker .preBooked_class span {57 color:#ffffff;58 background:url(./img/date-picker/red_horizon.gif) no-repeat;59 }60 </style>61 </body>

服务器返回的数据如下

1 jsonp1376646626023({ 'dates':[ 2 {'month':1,'day':5}, 3 {'month':1,'day':6}, 4 {'month':1,'day':19}, 5 {'month':2,'day':9}, 6 {'month':2,'day':10}, 7 {'month':3,'day':16}, 8 {'month':3,'day':23}, 9 {'month':4,'day':13}, 10 {'month':4,'day':15}, 11 {'month':5,'day':4}, 12 {'month':5,'day':12}, 13 {'month':5,'day':13}, 14 {'month':6,'day':15}, 15 {'month':6,'day':16}, 16 {'month':7,'day':13}, 17 {'month':8,'day':17}, 18 {'month':9,'day':9}, 19 {'month':9,'day':10}, 20 {'month':9,'day':11}, 21 {'month':10,'day':13}, 22 {'month':10,'day':14}, 23 {'month':10,'day':27}, 24 {'month':11,'day':16}, 25 {'month':12,'day':28}, 26 {'month':12,'day':29}, 27 {'month':12,'day':30} 28 ]})

此处如果自己制作服务端，要注意需要有一个回调函数的返回。

第一部分，我们初始化定义了两个空数组，它们执行AJAX请求，从服务端获得JSON对象。JSON对象包含一个单一的叫做dates的选项。这个选项的值是一个数组，每一个item都是一个对象。

它的每一个子对象都包含month和day属性，代表不能被选择的一天。

下面，我们定义了一个addDates回调函数，被beforeShowDay事件调用。这个函数传入一个日期，返回一个包含至多两个items的数组。第一个是boolean，代表是否这天能被选中。第二个是可选的，给这个禁用的日期提供一个classname。

我们的函数首先检查是否当前日期是否为一周中的0 sunday或 6 saturday。如果是，返回false作为数组的第一个item，使得周末不能被选中。

这里有一个内建的管理对象$.datepicker().noWeekends()能自动使得周末不能被选中。

接着，我们遍历months 和 days 数组，查看任何被传递给回调函数是否能匹配。如果 month 和 days 都匹配这个日期，则返回false，用自定义的classnames给他。如果不匹配，则返回一个包含true的数组，来表示这天可选。这允许我们指定任意数量的天数，不能被选中。

最后，我们定义了一个配置对象。它的属性简单地调用函数，使得JSON对象中指定的日期不能被选择。minDate选项设为相对地“+1”，证明我们不想让任何人选择过去的，或者今天。