jQuery Date Range Picker 时间选择详解:time、defaultTime 与 defaultEndTime 完整指南

原创2026-10-14 20:07:271,613 阅读
文章标签:前端UI库/组件

jQuery Date Range Picker 时间选择详解:time、defaultTime 与 defaultEndTime 完整指南

jQuery Date Range Picker 是一个功能强大的 jQuery 日期范围选择插件,除了日期之外,它还能通过 time 配置在面板中启用小时/分钟选择滑杆,并通过 defaultTime、defaultEndTime 精确控制初始时间。本文结合官方演示 demo.js 与插件源码 src/jquery.daterangepicker.js,带你快速掌握日期 + 时间组合选型的完整用法,告别"只能选到日"的尴尬。

jQuery Date Range Picker 日期范围与时间选择器界面预览

一、为什么需要时间选择功能?

很多业务场景——预约系统、活动排期、日志查询——需要的不只是"哪一天",还有"几点几分"。插件默认只选日期(格式 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。

两个关键注意点:

  1. format 中必须包含时间占位符(moment 格式),如 HH:mm、H:mm:ss,否则最终值不会显示时间部分;
  2. 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 分钟跑通)

  1. 引入 jQuery 1.7+、Moment 2.8.1+ 及插件文件(开发用 dist/jquery.daterangepicker.min.js,样式为 dist/daterangepicker.css);
  2. 在 dateRangePicker({...}) 中加入 time: { enabled: true };
  3. 把 format 改成带 HH:mm 的格式;
  4. 按需设置 defaultTime / defaultEndTime(记得传 Date 对象);
  5. 监听 datepicker-apply 事件获取带时间的最终值。

🎉 到这里,你就掌握了 jQuery Date Range Picker 时间选择的三大核心配置:time、defaultTime 与 defaultEndTime。更多样式定制可参考 src/daterangepicker.scss,版本变更记录见 CHANGELOG.md。

登录后查看全文
jquery-date-range-picker