jQuery Date Range Picker高级技巧:beforeShowDay禁用规则、selectForward与batchMode批量选择
jQuery Date Range Picker高级技巧:beforeShowDay禁用规则、selectForward与batchMode批量选择
jQuery Date Range Picker 是一个基于 jQuery 的日期范围选择插件(jquery-date-range-picker),用户只需点击两次即可选出一段日期区间,常用于酒店预订、报表统计、排班系统等场景。除了基础配置外,它还有三个被严重低估的高级能力:用 beforeShowDay 自定义禁用某些日期、用 selectForward 限制选择方向、用 batchMode 一键批量选中整周或整月。掌握它们,能让你的日期选择器瞬间专业起来。
💡 插件要求 jQuery 1.7+ 与 Moment 2.8.1+,样式文件为 src/daterangepicker.scss,压缩产物在 dist/jquery.daterangepicker.min.js,完整源码见 src/jquery.daterangepicker.js。
三个高级选项速览
| 选项 | 默认值 | 一句话作用 |
|---|---|---|
beforeShowDay |
false |
逐日回调,决定是否可选、附加样式和悬浮提示 |
selectForward |
false |
第二次点击必须落在第一次点击之后 |
selectBackward |
false |
第二次点击必须落在第一次点击之前 |
batchMode |
false |
点一次自动选满一整周/整月/工作日等 |
这些默认值定义在 src/jquery.daterangepicker.js 的默认配置段中。
beforeShowDay 禁用规则:让日历"听懂"业务逻辑
这是最强大的选项。beforeShowDay 会对日历中的每一天调用一次你的函数,你必须返回一个三元素数组:
$('#picker').dateRangePicker({
beforeShowDay: function(t) {
var valid = !(t.getDay() == 0 || t.getDay() == 6); // 禁用周六、周日
var _class = '';
var _tooltip = valid ? '' : 'weekends are disabled';
return [valid, _class, _tooltip];
}
});
三个返回值分别对应:
[0]布尔值:该日期是否可选(false即灰显禁用)[1]字符串:为该日期单元格附加的 CSS 类名,可用于高亮"今天"或"促销日"[2]字符串:鼠标悬浮时显示的 tooltip,比如"已满房"
这段官方示例可在 demo.js 中直接看到;渲染时逐日调用回调的逻辑位于 src/jquery.daterangepicker.js。
隐藏的第二个校验:区间必须"全程合法"
新手常踩的坑:beforeShowDay 不只是把日期变灰。当用户已选中起点、正在选终点时,插件还会把区间内每一天都走一遍 beforeShowDay,只要中间有任何一天返回 false,这个区间整体就无效(该终点会被标记为不可点)。相关校验逻辑在 src/jquery.daterangepicker.js。
这意味着它天然适合"入住/退房"类场景:某几天满房时,用户不仅点不到那一天,也无法"跨过"它完成预订。典型组合写法(startDate 设为今天 + 只允许向后选 + 周末禁选)见 demo.js 的 hotel-booking 示例。
selectForward 单向选择:杜绝"选反了"
默认情况下,jQuery Date Range Picker 允许先点后点(自动交换起止时间)。而某些业务有严格的方向约束:
$('#picker').dateRangePicker({
startDate: new Date(), // 起点锁定为今天
selectForward: true // 第二个日期只能晚于第一个
});
selectForward: true→ 只能在起点之后选第二个日期selectBackward: true→ 只能在起点之前选(适合"回溯分析"类报表)- 两者都默认
false,即不限方向
实现非常直观:在时间有效性校验里,只要候选时间点落在起点错误的一侧就直接判定无效,源码见 src/jquery.daterangepicker.js。示例分别位于 demo.js。
batchMode 批量选择:一次点击选满一周/一月
batchMode 开启后,用户只需点击任意一天,插件就自动推算出完整的起止区间,官方文档描述为 "auto batch select mode"(见 index.html)。支持的值及效果:
| 取值 | 效果 |
|---|---|
'week' |
自动选中当天所在的整周(周首由 startOfWeek 决定) |
'workweek' |
自动选中当周周一至周五 |
'weekend' |
自动选中当周周六至周日 |
'month' |
自动选中当天所在的整月 |
'week-range' |
保留范围选择,但起点自动对齐周首 |
'month-range' |
保留范围选择,但起点自动对齐月初 |
配置示例(week-range 模式):
$('#picker').dateRangePicker({
batchMode: 'week-range',
showShortcuts: false
});
点击日自动补齐起止区间的核心逻辑(handleStart / handleEnd 及 dayClicked 中的分支)位于 src/jquery.daterangepicker.js;week 与 week-range 两种模式的现成演示见 demo.js。做"按周/按月出报表"的产品时,这个选项能直接砍掉一半的交互步骤。
动手上手的正确姿势
- 打开 index.html,里面内置了全部演示:Batch mode、Disable some dates、selectForward/selectBackward 等都能实时调参;
- 所有可配置项及中文说明汇总在 index.html 底部,可按需查阅;
- 样式定制改 src/daterangepicker.scss,重新构建后生成 dist/jquery.daterangepicker.min.js;
- 版本迭代记录见 CHANGELOG.md,许可证为 LICENSE.txt(MIT)。
三个选项可以叠加使用:beforeShowDay 管"哪些日子不能选",selectForward 管"往哪个方向选",batchMode 管"一次能选多少"。把业务规则映射到这三个维度上,基本就覆盖了日期范围选择器的大部分高级需求。
