jQuery Date Range Picker 时间选择详解:time、defaultTime 与 defaultEndTime 完整指南
jQuery Date Range Picker 时间选择详解:time、defaultTime 与 defaultEndTime 完整指南
jQuery Date Range Picker 是一个功能强大的 jQuery 日期范围选择插件,除了日期之外,它还能通过 time 配置在面板中启用小时/分钟选择滑杆,并通过 defaultTime、defaultEndTime 精确控制初始时间。本文结合官方演示 demo.js 与插件源码 src/jquery.daterangepicker.js,带你快速掌握日期 + 时间组合选型的完整用法,告别"只能选到日"的尴尬。
一、为什么需要时间选择功能?
很多业务场景——预约系统、活动排期、日志查询——需要的不只是"哪一天",还有"几点几分"。插件默认只选日期(格式 YYYY-MM-DD),开启时间选择后,下拉面板底部会多出两组滑杆:
- Hour(小时):0–23 的滑杆
- Minute(分钟):0–59 的滑杆
左右两个月份面板下方各一组,分别对应起始时间和结束时间,拖动滑杆即可实时调整,无需手动输入。
二、启用 time 时间选择的最快配置方法
默认情况下 time.enabled 是 false(见 src/jquery.daterangepicker.js),只需加一行即可开启:
$('#date-range1').dateRangePicker({
format: 'DD.MM.YYYY HH:mm',
autoClose: false,
time: {
enabled: true
}
});
👉 完整示例见 demo.js。
两个关键注意点:
format中必须包含时间占位符(moment 格式),如HH:mm、H:mm:ss,否则最终值不会显示时间部分;autoClose建议设为false,让面板保持打开,方便用户拖动滑杆调整时间后再点 Apply 确认。
三、defaultTime:设置默认起始时间
defaultTime 用于指定面板打开时**第一个时间滑杆(起始时间)**的初始值。
⚠️ 注意:它必须是 Date 对象,而不是字符串。插件内部会直接调用 moment(date).hours() 来读取小时和分钟(见 renderTime 实现)。
不设置时的默认行为是当前时间(new Date(),见 getDefaultTime)。
常见用法:让起始时间默认为当天 00:00:
defaultTime: moment().startOf('day').toDate()
四、defaultEndTime:设置默认结束时间
defaultEndTime 控制**第二个时间滑杆(结束时间)**的初始值,规则是:
- 设置了它 → 结束滑杆显示该时间;
- 没设置 → 回退为与
defaultTime相同(源码 init_datepicker)。
典型场景:查询"今天一整天"的数据时,起始取 00:00、结束取 23:59,官方演示正是这么写的:
$('#date-range1-1').dateRangePicker({
format: 'DD.MM.YYYY HH:mm',
autoClose: false,
time: {
enabled: true
},
defaultTime: moment().startOf('day').toDate(),
defaultEndTime: moment().endOf('day').toDate()
});
完整对照见 demo.js。
五、常见配置速查清单
| 配置项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
time.enabled |
Boolean | false |
是否显示时间滑杆 |
defaultTime |
Date 对象 | 当前时间 | 起始时间滑杆的初始值 |
defaultEndTime |
Date 对象 | 同 defaultTime |
结束时间滑杆的初始值 |
format |
字符串 | YYYY-MM-DD |
值的显示格式,含时间需加 HH:mm |
autoClose |
Boolean | false |
是否选完即关闭面板 |
swapTime |
Boolean | false |
反向选择时是否同步交换两组时间 |
六、进阶技巧与细节
1. 已预设 startDate/endDate 时,时间从哪来?
如果同时配置了 startDate 和 endDate,两组时间滑杆会直接取这两个日期自带的时间部分来初始化,defaultTime/defaultEndTime 此时不生效(见 初始化逻辑)。
2. swapTime:反向选择的贴心设计
用户可能先点结束日期、再点开始日期(即起点 > 终点)。此时插件会自动交换日期;再开启 swapTime: true,两组时间滑杆也会随之交换(swapTime 实现),避免出现"起始 10:00、结束 08:00"这种诡异状态。
3. 通过事件拿到最终的时间值
点击 Apply 后,datepicker-change 与 datepicker-apply 事件返回的 obj 中包含完整的 date1、date2(含时间戳)与格式化后的 value 字符串,可直接提交给后端:
.on('datepicker-apply', function(event, obj) {
console.log(obj.value); // 如 "05.06.2013 09:30 to 07.06.2013 18:00"
});
事件清单详见 demo.js。
七、上手清单(5 分钟跑通)
- 引入 jQuery 1.7+、Moment 2.8.1+ 及插件文件(开发用 dist/jquery.daterangepicker.min.js,样式为 dist/daterangepicker.css);
- 在
dateRangePicker({...})中加入time: { enabled: true }; - 把
format改成带HH:mm的格式; - 按需设置
defaultTime/defaultEndTime(记得传 Date 对象); - 监听
datepicker-apply事件获取带时间的最终值。
🎉 到这里,你就掌握了 jQuery Date Range Picker 时间选择的三大核心配置:time、defaultTime 与 defaultEndTime。更多样式定制可参考 src/daterangepicker.scss,版本变更记录见 CHANGELOG.md。
