简介jQuery日期与时间选择器插件DateTimePicker面向需要为网页快速集成日期输入组件的Web前端开发者提供了一套轻量易用的日期时间交互解决方案。插件内置多语言、自定义显示格式、日周月年四种视图、时分秒选择、禁用指定日期、事件回调、皮肤定制等丰富功能并兼顾响应式布局与无障碍性可广泛应用于后台管理系统、预约表单、数据录入等常见交互场景。压缩包共9个文件包含核心JS逻辑、CSS样式、HTML示例页面与效果预览图整体体积仅73KB轻量易部署适合直接引入项目使用。已有283人学习/浏览附件提供了详细的使用说明文档和可直接运行的调用示例开发者可参照文档快速完成初始化与配置例如切换中文界面、设定时间格式并基于事件回调灵活扩展业务逻辑提升开发效率。1. 收到 jQuery 日期和时间插件 DateTimePicker.zip 之后先确认这三件事jQuery 日期和时间插件 DateTimePicker 以 zip 压缩包形式到手时里面装的就是一套能让表单页直接弹日历、滚时间的控件。它解决的是表单里最让人头疼的一类输入日期时间。让用户手敲 2025-06-15 14:30 这种字符串十个里有四个会敲成 2025.6.15 或 15/06/2025 的样子后端正则写得再严也拦不住这些变体。换成弹出式选择后格式由程序统一生成校验成本几乎归零。它最适合三类项目还有大量 jQuery 存量业务的后台管理系统、活动报名与预约表单、以及各类 ERP/OA 里需要精确到分钟的场景。前提很简单页面本身还在用 jQuery而不是已经从根上换成新框架的工程。对这个包的需求通常也分两种多数人只想要一个能弹日历和时间滚轮、返回固定格式字符串的控件少数人需要联动、禁用指定日期、动态增删行这类业务逻辑。本文把两条路都铺开——zip 解压、最小初始化、核心参数、事件联动、高频排查一路走完。2. 拆包接入这个 zip 里装了什么怎么让它跑起来第一个建议别双击解压到桌面再把文件一个个拖进项目。老项目里路径本身就是事故高发区我见过因为把一个 css 放错层级导致整个后台日历裸奔的例子。解压这一步也用命令做至少你能看清包里到底有几层目录、主文件叫什么名字。2.1 解压后先认文件JS、CSS、示例页各有什么用mkdir -p vendor/datetimepicker unzip DateTimePicker.zip -d vendor/datetimepicker find vendor/datetimepicker -maxdepth 2 -type f | sort | head -30-d指定解压目标目录避免文件散落当前目录find限制最大深度为两层配合head只看前 30 条结果目的是在动手之前先掌握包的结构。Windows 环境没有 find 命令时用dir /s vendor\datetimepicker也能达到同样效果。常见的发行包里文件基本是同一套骨架只是命名随版本微调。我按典型情况整理成一张对照表具体文件名以你解压出来的实际内容为准文件类型典型文件名作用主脚本压缩版jquery.datetimepicker.full.min.js核心逻辑加自带日期格式化器大多数页面选它主脚本基础版jquery.datetimepicker.js核心逻辑不带内置格式化器仅当项目已有等价工具时才需要样式文件jquery.datetimepicker.css弹层外观漏引它就会出现日历裸奔备选主题jquery.datetimepicker.dark.css深色主题界面本身偏暗时替换默认样式示例页index.html 或 demo.html当前版本的标准用法、语言包、参数写法都在里面提示优先选用文件名里带 full 和 min 的那份 JS它自带日期格式化逻辑省去再引一个独立格式化库的麻烦。CSS 和 JS 必须从同一个目录取版本错位会导致类名对不上样式全丢。2.2 最小接入jQuery 在前初始化一行就够link relstylesheet hrefvendor/datetimepicker/jquery.datetimepicker.css script srcvendor/jquery/jquery-3.6.0.min.js/script script srcvendor/datetimepicker/jquery.datetimepicker.full.min.js/script顺序不能乱jQuery 必须最先加载插件脚本紧跟其后。插件是在 jQuery 加载完成后把自己注册到$.fn上的反过来引就报方法不存在。input typetext idmeetingTime namemeetingTime readonly placeholder请选择会议时间input 上加readonly是常见做法理由有两个防止用户手敲出非法格式移动端上减少软键盘误弹。插件写回值的操作不受 readonly 影响。$(#meetingTime).datetimepicker({ format: Y-m-d H:i, step: 15 });format决定最终写回 input 的字符串格式step: 15表示时间滚轮按 15 分钟一档。跑起来的效果是点击输入框弹出日历点日期切换年月时间部分滚动选择确定后 input 的 value 变成类似 2025-06-15 14:30 的文本随表单一起提交。2.3 它内部怎么工作一个 Date 对象、一个弹层、一个字符串把它当黑匣子用当然可以但我建议至少理解三步。第一步插件内部维护一个 Date 实例日历上的点击只改年月日时间滚轮只改时分秒互不干扰。第二步每次变更后按format把 Date 格式化第三步把格式化结果写回 input 的 value所以表单提交时后端永远收到一段纯文本。理解这三步能解释很多怪现象。比如 value 格式完全由 format 决定format 写错时字符串就会原样输出比如在onChangeDateTime回调里读时间拿到的是 Date 对象而 input.value 是格式化后的字符串两者类型完全不同再比如弹层是插件动态挂到页面里的 div它有自己的层级规则这也是后面第五个章节里弹层被弹窗遮挡问题的根源。少数场景可以开inline: true让日历常驻页面不走浮层定位逻辑更简单。3. 核心参数把格式、步长和可选范围调到符合业务zip 自带的示例页只是默认形态实际业务卡的永远是格式、边界和步长。这一章把最常用的几组参数讲透参数表之外的细节以你手头这份包的示例页为准。3.1 format 格式串它是 PHP 风格别按 JS 写法填这是第一个必改参数也是最容易踩的坑。插件用的是 PHP 风格格式串和 JavaScript 里 toLocaleDateString 那套完全不同。写错的结果很直观选完日期后 input 里出现 yyyy-MM-dd 这样的字面量。常用记号列成一张表写法含义输出示例Y四位年份2025y两位年份25m月份补零06n月份不补零6d日期补零15j日期不补零15H24 小时制补零14G24 小时制不补零14h12 小时制补零02i分钟补零05s秒补零09A上午/下午AM/PM$(#deadline).datetimepicker({ format: Y-m-d H:i:s, step: 5, defaultTime: 18:00 });#deadline这个场景是秒级精度所以格式串到秒defaultTime: 18:00让日期不变时时间默认落在 18:00适合每日定时任务的截止时间。日常用得最多的三套写法是分钟级Y-m-d H:i、秒级Y-m-d H:i:s、纯日期Y-m-d配合timepicker: false。一旦发现 value 里出现 yyyy 字样九成是格式串写反了直接对照上表重写。3.2 时间范围与步长minDate、maxDate、allowTimes 怎么配合预约类业务通常要同时限住日期范围和时间点比如只能约未来 30 天、每天只能在固定时间到店。const later30 new Date(); later30.setDate(later30.getDate() 30); $(#appointTime).datetimepicker({ format: Y-m-d H:i, step: 30, minDate: 0, maxDate: later30, allowTimes: [09:30, 10:00, 10:30, 11:00, 14:00, 14:30, 15:00] });minDate: 0里的 0 不是普通日期字符串是插件里今天的约定写法表示今天之前不可选。maxDate我一般直接传 Date 对象比如这段代码里 new 出来的 30 天后比传字符串更不容易踩解析坑。step: 30控制时间列表的粒度30 表示每半小时一项但allowTimes给了枚举列表时以它为准时间面板里只会出现列出的这些时刻适合店铺只在这些时段接单的场景。注意这两组参数管的是不同面板minDate/maxDate 约束日期面板step/allowTimes 约束时间面板别混。想精确禁掉某些日期用disabledDates传日期数组或在beforeShowDay回调里对每个日期格返回是否可点比如节假日、已约满的日期可以在这里拦掉。3.3 行为类参数inline、mask、closeOnDateSelect纯日期场景和嵌入式日历场景需要另一组参数$(#eventDate).datetimepicker({ timepicker: false, inline: true, closeOnDateSelect: true, dayOfWeekStart: 1, mask: true });timepicker: false关掉时间面板只留日历inline: true让日历直接渲染在 input 下方常驻常用于筛选面板里选完日期触发列表刷新的布局closeOnDateSelect: true在纯日期模式下选完就收起弹层少点一次dayOfWeekStart: 1让周一排在日历第一列符合国内习惯mask: true允许手输但字符位置被占死用户只能按格式敲数字这个选项只在去掉 readonly 的可编辑场景才有意义。3.4 中文界面先翻包里的语言文件再谈自定义默认界面是英文的但到后台项目里基本都得换成中文。不同发行版注入翻译的方式不一样有的内置多语言包、认lang: zh有的要求调用全局方法设置。我一般先翻包里有没有 locale 目录或语言相关 js 文件有就照它的示例抄。最不依赖版本差异的写法是初始化时传一份翻译字典$(#appointTime).datetimepicker({ lang: zh, i18n: { zh: { months: [1月, 2月, 3月, 4月, 5月, 6月, 7月, 8月, 9月, 10月, 11月, 12月], dayOfWeekShort: [日, 一, 二, 三, 四, 五, 六], dayOfWeek: [星期日, 星期一, 星期二, 星期三, 星期四, 星期五, 星期六] } } });这个字典结构是最常见的形态缺哪个键补哪个就好。如果你这份包在示例页里用的是全局 setLocale 的方式直接照抄示例效果等价。整站统一语言时在全局统一设置一次比每个 input 都传一遍省事。4. 事件与方法让选择结果驱动后续业务初始化只是第一步业务从来不是把控件摆上去就结束。这一章处理三件事两个选择器之间的联动、实例的生命周期、以及和后端接口的格式约定。4.1 onChangeDateTime联动两个选择器的最稳写法最常见的联动是开始时间不能晚于结束时间$(#startTime).datetimepicker({ format: Y-m-d H:i, step: 15, onChangeDateTime: function (ct) { $(#endTime).datetimepicker({ format: Y-m-d H:i, step: 15, minDate: ct }); $(#endTime).val(); } });onChangeDateTime的参数ct是插件内部维护的 Date 对象可以直接塞给另一个选择器的minDate。每改一次开始时间结束时间的最小值就跟着刷新同时把已经选过的结束时间清空防止出现结束早于开始的脏数据。这里我用的是对已初始化元素再次调用 datetimepicker 并传选项的写法多数发行版里这是合并选项而不是重复创建弹层。个别版本会重复挂载表现是点开出现两层日历遇到这种状况改为先 destroy 再重新初始化也就是第 5 章推荐的封装模式。再往下走一步两个时间都选好后算时长const toDate (s) new Date(s.replace( , T)); $(#endTime).datetimepicker({ format: Y-m-d H:i, onChangeDateTime: function () { const st $(#startTime).val(); const en $(#endTime).val(); if (st en) { const hours (toDate(en) - toDate(st)) / 3600000; $(#duration).text(hours.toFixed(1) 小时); } } });replace( , T)是防 iOS 的写法。new Date(2025-06-15 14:30)在 Chrome 和 Node 里能解析但在 iOS Safari 上会返回 Invalid Date把空格换成 T 之后就变成标准 ISO 字符串全平台通用。这个细节在移动端联调时救过我两次。4.2 常用方法与生命周期管理插件暴露了几个实例方法用字符串当第一个参数调用调用作用典型场景.datetimepicker(show)强制弹出点击自定义按钮时触发选择.datetimepicker(hide)收起弹层提交或清空时收尾.datetimepicker(toggle)开合切换自定义图标按钮.datetimepicker(reset)回到初始值表单重置.datetimepicker(destroy)卸载实例还原 input删除动态行、关闭弹窗前$(#pickBtn).on(click, function () { $(#meetingTime).datetimepicker(show); }); $(#resetBtn).on(click, function () { $(#meetingTime).datetimepicker(reset); });show适合那种不用原生 input、而是用按钮加文字展示时间的自定义组件reset在表单重置时配合使用。destroy平时容易被忽略但动态行删除前不调它简单页面可能没感觉弹窗反复开关的场景就会出现实例残留、布局闪烁这类说不清的问题。4.3 表单提交value 是字符串留给后端什么格式要提前定插件写回 input 的是本地时间字符串不含时区信息。后端接口如果要毫秒时间戳建议前端转换后放隐藏域$(#orderForm).on(submit, function (e) { const t $(#deliveryTime).val(); if (!t) { alert(请先选择送达时间); e.preventDefault(); return; } $(#deliveryTimeStamp).val(toDate(t).getTime()); });如果后端直接收Y-m-d H:i字符串接口文档里一定要把格式写死不然联调时你会花一下午排查为什么入库时间少了 8 小时。时区偏移在日志里看起来完全像代码 bug实际上只是前端本地时间和后端所在时区的差值提前约定好就不存在这个坑。5. DateTimePicker 的 5 个高频排查点从样式错乱到动态绑定失效以下五条按现象、原因、解决的结构记录每条都来自实际项目里的翻车现场。5.1 样式全乱日历格子挤成一条现象弹层能打开但没边框没配色日期挤成竖条图标错位。原因CSS 没引进来或者 JS 与 CSS 不是同一份发行版。类名对不上时样式规则全失效这最容易让人误判成插件本身坏了。解决先开浏览器 Network 面板确认 css 请求是 200 而不是 404再确认 css 和 js 从同一个目录取最后用 DevTools 定位弹层根节点看它的 class 与 css 文件里的选择器是否一致。常见做法是把两份文件放同一目录、用相对路径引用从源头避免路径分层错误。5.2 输入框里出现 yyyy-MM-dd HH:mm 字面量现象选完日期value 是 yyyy-MM-dd HH:mm 这样的原样字符串仿佛插件完全没格式化。原因format 用了类似 JS 日期方法的写法而这个插件的格式串是另一套约定不认识的字母按字面量输出。解决按 3.1 的格式表重写改成Y-m-d H:i然后手动选一次看 value 输出。这个问题的血泪教训是上线第二天日志里全是这种字面量字符串搜索都搜不干净所以我把格式串检查固定成了自检清单第一项。5.3 弹层被遮罩或弹窗挡住现象在自研弹窗、抽屉、Modal 里使用日历 div 出现在遮罩层后面或显示不全点了没反应。原因弹层是插件动态挂到页面里的 div有自己的层级设定页面弹窗层级更高时日历就沉下去了。另一个常见诱因是某个父容器设置了 transform改变了 absolute 定位的参照系弹层位置算歪。解决初始化时给 zIndex 选项传一个足够高的值如果父容器有 transform把选择器从弹窗根容器里挪出来实在压不住就直接开inline: true让日历常驻页面绕开浮层定位的玄学。5.4 控制台报错或点击无反应jQuery 版本问题现象初始化没报错点击 input 毫无反应或者控制台飘一个 undefined 方法错误。原因页面里同时存在多份 jQuery 或其它库占用 $。插件只注册在它加载那一刻的 $ 上后来加载的脚本覆盖全局 $点击处理就断了旧版插件在 jQuery 3 的新 API 上也可能存在兼容问题。解决全站收敛到一份 jQuery插件脚本紧跟在 jQuery 之后引入。实在躲不开多版本的历史页面统一用jQuery(...)代替$(...)调用。换 jQuery 大版本之前先在测试页把初始化、选择、提交整条链路跑一遍这种翻车成本不高但排查成本极高。5.5 动态新增行新 input 点不出日历现象表格可以加行新行的 input 外观和旧行一样但点击没有任何反应。原因初始化动作只发生在页面加载那一刻后插入的 DOM 元素根本没绑上事件。这是数据结构更新了、视图没跟着更新的典型表现。解决把初始化代码封装成一个函数每次 addRow 后对新行重新调用。不要试图用事件委托在父容器上绑 click因为弹层显示时机和 input 状态都由插件实例管理委托只能触发事件却管不了后续状态。第 6 章给一个可复用的封装直接抄。6. 收尾把这组控件封装成标准组件再养成自检习惯项目里 DateTimePicker 通常不止一个输入框在用。我习惯把参数收敛到一处避免十个初始化十个样$.datetimepicker.setDefaults({ format: Y-m-d H:i, step: 30, mask: true, closeOnDateSelect: true }); function initDtp($input, extra) { $input.each(function () { const $el $(this); if ($el.data(dtp-inited)) { $el.datetimepicker(destroy); $el.removeData(dtp-inited); } $el.datetimepicker($.extend({}, extra || {})); $el.data(dtp-inited, true); }); } // 页面初始化 initDtp($(.js-datetime)); // 动态新增行后 initDtp($newRow.find(.js-datetime));setDefaults一次设置全局默认值所有实例自动继承initDtp用自定义的 data 标记做幂等保护重复调用时先 destroy 再初始化避免出现点一下弹出两层日历动态新增行的场景直接复用同一个函数。选择器不要写死 id用js-datetime这类 class 统一标记后面加新输入框零成本。移动端体验是这类老控件共同的短板弹层在小屏上点按吃力iOS 上 readonly 输入框有时仍会唤起键盘。我的做法是加一个宽度判断窄屏时给同一个 name 换成原生 datetime-local 输入框宽屏继续用 DateTimePicker。原生输入框在移动端交互、时区处理上都更省心等于把最不可控的那部分交给浏览器自己管。上线前我固定跑一遍自检四连选一个日期看 value 是否符合 format提交到后端看入库时间是否就是所选时刻再切 23:59、00:00 这类边界值确认 step 和 mask 不会把边界时间吞掉最后在弹窗、动态行两个场景各点一次确认浮层和绑定没被环境干扰。边界值测试是这类控件最值的投入很多隐蔽的格式化问题都藏在一天的开头和结尾。我以前吃过 format 写错的亏日志刷新出来一片字面量字符串的那几分钟够我记一辈子。现在这套自检习惯救过我不止一次。希望帮到你。本文还有配套的精品资源点击获取