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

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

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

1 默认的datepicker

});

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 基本选项

})(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 最大最小日期

默认地，没有上下边界。

};

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

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

2.3 改变datepicker ui 的元素

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

};

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

};

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

};

启用button panel。

2.4 添加button触发器

};

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

};

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

}

2.5 配置可选的动画效果

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

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

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

};

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

2.6 多个月

};

控件没有限制能够显示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 是短日名的格式。

};

这里也有一些内置的公共标准格式。这些格式以常量和能被通过 $.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>，并显示不同的日期格式。

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

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中的年后面显示一个附加的字符串文本。

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

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

2.10 回调属性

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

$(function(){
var pickerOpts = {
beforeShow: function() {
var lang = $(":selected", $("#language")).attr("id");
$.datepicker.setDefaults($.datepicker.regional[lang]);
}
};
$("#date").datepicker(pickerOpts);
$.datepicker.setDefaults($.datepicker.regional['']);
});

我们使用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 以代码的方式选择一个日期

$(function(){
$("#date").datepicker();
$("#setDate").click(function(){
$("#date").datepicker("setDate","+7")
});
});

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

4.2 在 dialog box 中显示 datepicker

.ui-datepicker { width: 17em; padding: .2em .2em 0; z-index: 9999 !important;} $(function(){
function updateDate(date){
$("#date").val(date);
}
$("#date").focus(function(){
$(this).datepicker("dialog",null,updateDate);
});
});
</script>

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

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

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

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

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

5 AJAX datepicker

服务器返回的数据如下

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

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

第一部分，我们初始化定义了两个空数组，它们执行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”，证明我们不想让任何人选择过去的，或者今天。