简介这是一款面向前端开发者的轻量级jQuery日期时间选择插件专为需要用户高效输入或选择日期与时间的表单场景设计适用于中初级Web开发者快速集成美观、功能完备的时间控件。压缩包共9个文件含2个核心JSjquery.js与datetimepicker.js、1个样式CSS、1个演示HTML和1个说明HTM文档以及4张界面截图PNG整体仅73KB开箱即用无冗余依赖。目前已有283人学习下载资源结构清晰HTML提供可直接运行的示例页CSS与JS分离便于按需引入截图直观展示多视图、中文界面及时间粒度效果。读者可直接获得完整可用的本地化组件方案包含中文语言支持、自定义格式如yyyy-mm-dd HH:ii:ss、禁用日期设定、事件回调绑定等实战配置配合说明文档即可快速完成初始化与二次定制。1. 这不是又一个日历弹窗jQuery DateTimePicker 是一套能嵌进表单、扛住生产环境的日期时间双控组件你有没有遇到过这种场景后台系统要录入带精确到分钟的排班时间前端却只能用原生input typedatetime-local——结果在 Safari 上直接不显示在旧版 Edge 上点开是空白用户填完提交还发现时区错乱或者更糟自己手写一个“年月日时分”下拉组合结果月份天数没做联动校验2月30号也能选进去。jQuery DateTimePicker.zip 这个资源就是为这类真实业务卡点而生的它不是一个花哨的演示 Demo而是一套经过多年迭代、被大量表单类项目验证过的轻量级 JS 插件包。它把日期选择器Date Picker和时间选择器Time Picker真正融合成一个逻辑闭环的控件支持中文本地化、禁用日期范围、最小/最大时间约束、自定义格式输出且不依赖 moment.js 等重型库。适合需要快速集成、对兼容性有硬性要求、又不愿引入 Vue/React 全家桶的中后台项目。如果你正在维护一个 jQuery 技术栈的老系统或是要做一个离线可用的工控终端页面这个 zip 包里不到 80KB 的 JS CSS 图标资源就是你能拿到的最省心、最可控的时间输入方案。2. 从解压到可用三步完成基础集成与最小可运行验证2.1 解压结构解析看清文件职责避免“扔进 js 文件夹就完事”的玄学操作下载得到DateTimePicker.zip后解压目录结构通常如下实际以你解压后为准但主流版本高度一致DateTimePicker/ ├── css/ │ ├── jquery.datetimepicker.css # 核心样式含日历面板、时间滚轮、按钮等 │ └── jquery.datetimepicker.min.css # 压缩版生产环境推荐 ├── js/ │ ├── jquery.datetimepicker.js # 未压缩源码含完整注释调试首选 │ ├── jquery.datetimepicker.min.js # 压缩版体积小加载快 │ └── jquery.js # 注意此为插件所依赖的 jQuery 1.10 版本非最新勿直接替换你项目中的 jQuery ├── images/ │ ├── icons.png # 雪碧图含清空、切换视图、确认等图标 │ └── ... # 其他小图标资源 └── demo.html # 官方示例页含 10 种典型用法提示js/jquery.js是插件作者测试时捆绑的 jQuery 版本不要用它覆盖你项目中已有的 jQuery。该插件兼容 jQuery 1.10 至 3.6只要你的项目 jQuery 版本在此范围内直接引用插件 JS 即可。若你用的是 jQuery 3.7需额外验证兼容性见第 4 章避坑。2.2 HTML 页面接入两行 script 一行初始化跑通第一个实例在你的 HTML 页面head中引入 CSS在/body前引入 JS确保 jQuery 已先加载!-- 在 head 中 -- link relstylesheet hrefpath/to/DateTimePicker/css/jquery.datetimepicker.min.css !-- 在 /body 前jQuery 之后 -- script srcpath/to/your/jquery.min.js/script script srcpath/to/DateTimePicker/js/jquery.datetimepicker.min.js/script然后在需要时间输入的input元素上添加 class 或 id并在页面加载后初始化!-- HTML -- input typetext iddatetime-input placeholder请选择日期时间 !-- JavaScript -- script $(function() { $(#datetime-input).datetimepicker({ format: Y-m-d H:i, // 输出格式2024-05-20 14:30 step: 5, // 时间粒度5 分钟一档可选 1, 5, 10, 15, 30, 60 lang: ch, // 中文语言包内置支持 timepickerScrollbar: true, // 显示时间滚动条默认 true datepicker: true, // 启用日期选择默认 true timepicker: true // 启用时间选择默认 true }); }); /script这段代码执行后点击输入框会弹出一个带日历网格 右侧时间滚轮的复合面板。关键参数说明format必须显式设置否则默认为Y/m/d H:i斜杠在某些后端解析时易出错step直接影响用户体验设为1虽精细但滚动项过多5是平衡精度与操作效率的常见做法lang: ch触发插件内置中文翻译月份、星期、按钮文字无需额外加载语言文件。2.3 验证是否生效用浏览器控制台快速定位加载失败初始化后若无反应别急着改配置先做三步诊断打开浏览器开发者工具F12切换到Console标签页看是否有Uncaught ReferenceError: $ is not defined—— 表明 jQuery 未加载或加载顺序错误切换到Network标签页刷新页面筛选js和css确认jquery.datetimepicker.min.js和.min.css状态码为200大小非0在 Console 中手动执行$(#datetime-input).data(xdsoft_datetimepicker)若返回一个对象非undefined说明插件已成功绑定若返回undefined检查#datetime-input是否在 DOM 加载完成前就被调用即是否漏了$(function(){...})包裹。这三步比反复修改format参数高效十倍——很多“不生效”问题根源都在资源加载链路上。3. 生产级配置实战覆盖 90% 业务场景的七种参数组合3.1 限定可选时间范围防止用户选“昨天下午三点”提交今日工单业务规则常要求只能选今天及之后的时间如预约服务、或只能选过去 30 天如查询历史记录。DateTimePicker 提供minDate/maxDate和minTime/maxTime双维度控制$(#appointment-time).datetimepicker({ format: Y-m-d H:i, minDate: 0, // 0 表示今天-1 表示昨天3 表示三天后 maxDate: 1M, // 1M 表示一个月后2w 表示两周后 minTime: 08:00, // 最早可选时间仅当日有效 maxTime: 18:00, // 最晚可选时间仅当日有效 allowBlank: false // 禁止留空强制选择 });参数说明minDate: 0是相对值比写死2024-05-20更健壮避免日期硬编码导致上线即失效1M支持M(月)、w(周)、d(天) 单位2w比14d更语义化minTime/maxTime只对当天生效若用户选了明天则时间范围自动重置为全天除非你同时设minDate: 1d锁定只能选明天。3.2 禁用特定日期跳过节假日、设备维护日等业务黑期用disabledDates数组传入不可选日期支持多种格式适配不同数据源$(#maintenance-schedule).datetimepicker({ format: Y-m-d H:i, disabledDates: [ 2024-05-21, // 精确到日 2024-06-01, // 儿童节 2024-06-10, // 端午节 2024-06-15 to 2024-06-18, // 连续区间含首尾 2024-07-*, // 七月所有日期* 通配符 2024-08-?? // 八月所有日期?? 通配符效果同 * ], inline: true // 内联显示不弹窗适合固定位置表单 });注意disabledDates中的日期字符串必须为Y-m-d格式不能带时间部分通配符*和??功能相同但??更符合正则习惯建议统一用??。3.3 自定义格式与后端对接让 value 值直接入库不需二次解析前端展示格式如2024年5月20日 14:30和后端接收格式如2024-05-20T14:30:00往往不同。插件提供format显示/输入格式与value最终提交值分离能力$(#event-time).datetimepicker({ format: Y年m月d日 H:i, // 用户看到的友好格式 formatDate: Y-m-d, // 日期部分单独格式用于生成 value formatTime: H:i:s, // 时间部分单独格式用于生成 value onChangeDateTime: function(dp, $input) { // 每次选择后手动设置符合 ISO 8601 的 value const date $input.datetimepicker(getDate); if (date) { const isoString date.toISOString().slice(0, 16); // 截取到分钟2024-05-20T14:30 $input.val(isoString); // 覆盖 input 的 value } } });为什么不用format: Y-m-d\\TH:i因为反斜杠转义在某些 jQuery 版本下解析异常且toISOString()是浏览器原生方法稳定可靠。slice(0,16)确保只保留YYYY-MM-DDTHH:mm去掉秒和时区适配多数后端datetime字段。3.4 中文本地化深度定制不只是翻译还要适配农历、节气等业务需求lang: ch仅启用基础中文但实际项目常需扩展。插件支持通过i18n选项注入自定义翻译$.datetimepicker.setLocale(ch-custom, { months: [一月,二月,三月,四月,五月,六月, 七月,八月,九月,十月,十一月,十二月], dayOfWeek: [周日,周一,周二,周三,周四,周五,周六], shortDayOfWeek: [日,一,二,三,四,五,六], todayButton: 今天, clearButton: 清空, nowButton: 现在, selectTime: 选择时间, selectDate: 选择日期, timeText: 时间, hourText: 小时, minuteText: 分钟, secondText: 秒 }); $(#custom-ch-input).datetimepicker({ lang: ch-custom, // 使用自定义语言包 format: Y年m月d日 H:i, timepickerScrollbar: false, // 关闭滚动条改用上下箭头更适合触屏 scrollMonth: false, // 禁用鼠标滚轮切月防误操作 scrollTime: false // 禁用鼠标滚轮切时间 });血泪经验scrollMonth和scrollTime默认为true但在触屏设备如工业平板上手指滑动极易误触发月份/时间跳变导致用户困惑。生产环境务必显式设为false。3.5 与表单验证联动在 jQuery Validation 插件中无缝集成若你项目已用jquery-validation可将 DateTimePicker 的有效性纳入统一校验流// 先定义自定义校验方法 $.validator.addMethod(datetimepicker, function(value, element) { const $input $(element); const dp $input.data(xdsoft_datetimepicker); return value dp dp.getDate(); // 有值且能获取到日期对象 }, 请选择有效的日期时间); // 初始化表单验证 $(#my-form).validate({ rules: { event_time: { required: true, datetimepicker: true } }, messages: { event_time: { required: 时间不能为空 } } }); // 同时监听 datetimepicker 的 change 事件触发即时校验 $(#event_time).on(change, function() { $(this).valid(); });关键点dp.getDate()返回Date对象或null比单纯判断value.length 0更可靠——用户可能手动输入非法字符串如2024-02-30此时getDate()返回null校验自然失败。4. 避坑指南五个高频翻车现场与对应后悔药4.1 现象点击输入框无反应Console 无报错Network 显示 JS 加载成功原因插件依赖jQuery.fn.extend()方法而某些精简版 jQuery如jquery.slim.min.js移除了ajax和effect模块也一并去掉了extend所需的底层支持。解决必须使用完整版 jQueryjquery.min.js或jquery.js不可用slim版。检查你引入的 jQuery 文件大小完整版通常 85KBslim 版 65KB。4.2 现象选择时间后input 的 value 显示正常但提交到后端时变成Invalid Date或空字符串原因插件内部用new Date(value)解析输入值若value格式与format不严格匹配如format: Y-m-d H:i但用户手动输入2024/05/20 14:30解析失败。解决禁止用户手动输入。添加readonly属性并用 CSS 去除光标样式#my-datetime-input { readonly: true; background-color: #f9f9f9; cursor: pointer; }同时初始化时加allowBlank: false确保必选。4.3 现象在 iOS Safari 上时间滚轮无法拖动点击数字无响应原因iOS Safari 对transform: translateZ(0)的硬件加速处理异常导致滚轮容器z-index层级错乱。解决在 CSS 中强制重置滚轮容器的z-index和transform.xdsoft_timepicker .xdsoft_time_box { z-index: 9999 !important; transform: none !important; -webkit-transform: none !important; }4.4 现象设置了minDate: 0但用户仍能通过键盘输入昨天的日期并提交原因minDate仅约束面板选择行为不拦截手动输入。这是插件设计使然非 bug。解决在onChangeDateTime回调中二次校验并在onShow时同步禁用输入框需配合readonly$(#input).datetimepicker({ minDate: 0, onShow: function(ct) { $(this).prop(readonly, true); // 弹出时锁定输入 }, onChangeDateTime: function(dp, $input) { const selected $input.datetimepicker(getDate); const today new Date(); today.setHours(0,0,0,0); if (selected selected today) { alert(不能选择今天之前的日期); $input.val(); // 清空非法值 } } });4.5 现象多实例同页时一个实例的onChange回调会触发另一个实例的更新原因插件全局事件命名空间未隔离onChangeDateTime等回调在多个实例间共享作用域。解决每个实例必须用唯一 ID 初始化并在回调中用this或$input明确指向当前元素// ❌ 错误用 class 绑定回调中 this 指向混乱 $(.datetime-input).datetimepicker({ ... }); // ✅ 正确用唯一 ID回调中 this 指向当前 input $(#input-1).datetimepicker({ onChangeDateTime: function(dp, $input) { console.log(这是 input-1 的回调); // this #input-1 } }); $(#input-2).datetimepicker({ onChangeDateTime: function(dp, $input) { console.log(这是 input-2 的回调); // this #input-2 } });5. 进阶技巧用自定义事件与 API 实现跨组件通信与状态同步5.1 监听插件内部事件比轮询更优雅的状态感知DateTimePicker 内置多个可监听事件用于响应用户操作避免setInterval轮询 value 变化事件名触发时机典型用途changeinput value 改变时包括手动输入、面板选择、clear通用变更通知适合触发表单脏检查changeYear年份切换时如点击年份选择器动态加载该年数据如年度报告changeMonth月份切换时如点击 按钮预加载下月日程懒加载优化selectTime用户点击时间数字确认时记录用户时间选择偏好埋点$(#start-time).on(change, function() { const startVal $(this).val(); const endInput $(#end-time); // 同步结束时间最小值不能早于开始时间 if (startVal) { endInput.datetimepicker(setOptions, { minDateTime: startVal // 注意此处传字符串插件自动解析 }); } }); $(#end-time).on(change, function() { const endVal $(this).val(); const startInput $(#start-time); // 反向同步若结束时间早于开始时间重置开始时间 if (endVal) { const endDate new Date(endVal); const startDate startInput.datetimepicker(getDate); if (startDate endDate startDate) { startInput.datetimepicker(setDate, endVal); } } });注意setOptions是动态修改配置的方法minDateTime接收字符串如2024-05-20 14:30或Date对象比重新初始化整个插件轻量得多。5.2 手动控制 API实现“一键清空”、“跳转到今天”等交互增强插件暴露的 API 方法是实现复杂交互的基石以下为高频实用方法清单方法名用法说明getDate()$(#inp).datetimepicker(getDate)获取当前选中时间的Date对象null 表示未选setDate(date)$(#inp).datetimepicker(setDate, new Date())设置时间为指定Date对象支持字符串需匹配 formatdestroy()$(#inp).datetimepicker(destroy)彻底卸载插件恢复 input 原始状态用于动态表单show()/hide()$(#inp).datetimepicker(show)手动控制面板显隐如配合外部按钮disable()/enable()$(#inp).datetimepicker(disable)禁用/启用整个控件灰显不可交互// 场景表单有“重置为今天”按钮 $(#reset-to-today).click(function() { const now new Date(); // 设置日期为今天时间保持当前或设为 00:00 $(#datetime-input).datetimepicker(setDate, now); }); // 场景动态表单中某字段隐藏时销毁插件显示时重建 $(#toggle-section).click(function() { const $input $(#dynamic-datetime); if ($(this).is(:checked)) { // 显示时初始化 $input.datetimepicker({ format: Y-m-d H:i, minDate: 0 }); } else { // 隐藏时销毁释放内存 $input.datetimepicker(destroy); $input.val(); // 清空值 } });5.3 与现代框架桥接在 Vue 2/3 中封装为可复用组件无侵入式虽为 jQuery 插件但可通过ref和生命周期钩子桥接到 Vue。以 Vue 3 Composition API 为例template div input refdatetimeInput :valuemodelValue input$emit(update:modelValue, $event.target.value) classdatetime-input / /div /template script setup import { ref, onMounted, onUnmounted, watch } from vue const props defineProps({ modelValue: String, options: { type: Object, default: () ({ format: Y-m-d H:i }) } }) const emit defineEmits([update:modelValue]) const datetimeInput ref(null) onMounted(() { // 初始化插件 $(datetimeInput.value).datetimepicker({ ...props.options, onChangeDateTime: (dp, $input) { emit(update:modelValue, $input.val()) } }) }) onUnmounted(() { // 组件卸载时销毁 $(datetimeInput.value).datetimepicker(destroy) }) // 监听父组件传入的 modelValue 变化同步插件显示 watch(() props.modelValue, (newVal) { if (newVal) { $(datetimeInput.value).datetimepicker(setDate, newVal) } else { $(datetimeInput.value).val() } }) /script关键点watch同步modelValue是双向绑定的核心确保父组件修改值时子组件 UI 实时更新onUnmounted销毁是防止内存泄漏的强制动作。此封装完全不修改原有 jQuery 插件零耦合。从那以后我每次在老系统里集成时间控件都强制走一遍「Network 查加载 → Console 查绑定 → 手动getDate()验证」三步诊断。哪怕只是改一个format参数也先确认插件实例是否存在——因为太多“不生效”问题其实发生在datetimepicker()函数根本没执行成功的阶段。希望帮到你。本文还有配套的精品资源点击获取
