Layui datePicker 日期选择器使用指南从渲染面板到区间回调一次讲清【免费下载链接】layui一套遵循浏览器原生态开发模式的 Web UI 组件库。项目地址: https://gitcode.com/GitHub_Trending/la/layuiLayui 3 内置的 datePicker 组件就是解决让用户在表单里可靠地选出一个日期或时间区间这个问题的日期选择器一个输入框、一块弹出日历面板、一套回调拿结果。读完本文你能独立完成绑定输入框并拿到格式化结果、配置五类面板年/月/日/时/日时分、设置区间选择与联动、限制可选范围与禁用时间、用快捷栏和实例方法控制面板——所有示例均来自仓库真实 API可直接在tests/visual/datePicker.html里对照运行。 三分钟上手第一个日期选择器这一步只需一个输入框加一次render调用。datePicker 基于框架的弹出层机制实现样式、定位、关闭逻辑都是开箱即用的你只需要告诉它绑谁、选什么类型、输出什么格式。link relstylesheet hrefdist/css/layui.css input typetext idorder-date classlay-input placeholder请选择下单日期 script srcdist/layui.js/script script typemodule const { datePicker } layui; datePicker.render({ elem: #order-date, // 绑定元素支持选择器或元素对象 type: date, // year|month|date|time|datetime format: yyyy-MM-dd, // 输出与回读值都以此模板为准 done({ value }) { // 选择完成点确定或自动确认 console.log(选中日期, value); }, }); /scriptrender会返回组件实例后面所有外部打开/关闭/提示/销毁操作都挂在它上面。点一下输入框面板就会出现在输入框下方默认placement: bottom-start选中日期后自动回填并关闭。仓库里完整的可运行示例在 tests/visual/datePicker.html本文后续所有配置项都能在其中找到对应 demo。五种面板用 type 切换用 format 定制输出面板长什么样由type决定输出字符串长什么样由format决定——这两项定了组件的渲染、校验、回读逻辑就全部随之确定。type 取值面板形态默认 format典型场景year年份列表15 年/页yyyy年份筛选、出生年份month年月列表12 月/页yyyy-MM月度报表、会员周期date月历网格yyyy-MM-dd普通日期输入time时/分/秒三列滚选HH:mm:ss会议时间、营业时间datetime月历 时间面板yyyy-MM-dd HH:mm:ss日志、排期format支持的格式符如下单双字母控制是否补零格式符含义示例yyyy/y年份4 位/不补零2026 / 26MM/M月两位/不补零08 / 8dd/d日两位/不补零23 / 3HH/H24 小时制两位/不补零09 / 9mm/m分钟两位/不补零08 / 8ss/s秒两位/不补零05 / 5想要中文风格输出直接把汉字写进模板即可输入框显示值与回填值都会变成这样datePicker.render({ elem: #custom-format, format: yyyy年MM月dd日 HH:mm, // 输出2026年08月23日 14:08 value: new Date(2026, 7, 23, 14, 8), // value 传 Date 或符合 format 的字符串 });只选时间的场景min/max传HH:mm:ss就能圈出可选项比如把预约时间锁在工作时段min: 09:30:00、max: 17:30:00。区间选择的三种配置方式区间选择只改一个配置项把range从false打开即可区别只在于选完的起止值往哪里放。配置写法效果适用场景range: true单输入框值为起 ~ 止字符串一个字段存整个区间range: [#start, #end]面板选一次起止分别回填两个输入框表单里开始/结束是两个字段配合rangeSeparator修改单输入框模式下的分隔符默认~后端要求-或其他分隔符双输入框 联动的完整写法左面板是起始月、右面板是结束月两面板始终相邻datePicker.render({ elem: #booking-range, type: datetime, range: [#start-date, #end-date], // 分别绑定开始/结束两个输入框 rangeLinked: true, // 联动左右面板固定相邻月 min: 0, // 数字 相对今天的天数0 表示今天 done({ value, dateTime, endDateTime }) { console.log(value); // 起 ~ 止 字符串 console.log(dateTime, endDateTime); // 两个结构化日期对象 }, });rangeLinked还支持传auto平时联动当起止落在同一个月时自动切换为独立双面板方便微调同一月内的区间。活动排期是区间选择的高频场景整场活动用datetime 区间再挂一个快捷栏运营点一下就能生成一天/三天/一周datePicker.render({ elem: #activity-time, type: datetime, range: true, min: 0, // 活动不能早于当前时刻 shortcuts: [ { text: 一天, value: () [new Date(), new Date(Date.now() 864e5)] }, { text: 一周, value: () [new Date(), new Date(Date.now() 7 * 864e5)] }, ], });注意快捷项的value可以是日期值也可以是函数区间模式下必须返回[start, end]数组点击即回填并自动确认。 样式、标注与限制让日期选择器贴合业务这一节按常见的三类需求归组面板外观、日历标注、可选范围控制。1. 外观变体。3.x 用variant取代了旧版的主题名内置三套variant效果default默认描边风格solid面板头部背景填充grid月历网格线样式需要换色时不引入主题文件直接覆盖 CSS 变量即可如选中色--lay-color-accent具体类名见 src/css/modules/datePicker.css。showBottom底部按钮栏、showPreview底部结果预览、btns: [clear, now, confirm]按钮种类与顺序可进一步增减面板元素内嵌式日历不弹层直接画在容器里用inline: true。2. 日历标注。三个配置项解决在日历上多显示点信息datePicker.render({ elem: #mark-demo, showFestival: true, // 显示公历节日元旦/国庆/圣诞等仅简体中文 mark: { 0-10-14: 生日, // 0 代表每年0-0-15 表示每月 15 号 2017-8-20: v2, // 也可写死具体日期 }, holidays: [ // 标注法定节假日 补班日两档 [2026-1-1, 2026-1-2], [2026-1-29, 2026-1-30], ], });mark也可以传函数holidays同样支持函数形式适合按接口数据动态标注。3. 可选范围与禁用项。min/max支持三种写法字符串年月日用-分隔、时分秒用:分隔如2026-08-01 09:00:00、Date对象、相对天数-30 30 天前0 今天且max: 0会取到当天 23:59:59。超出范围的初始值会被自动纠正到边界并给出面板内提示。更细粒度的禁用交给两个回调datePicker.render({ elem: #workday, min: -30, max: 30, // 只允许前后 30 天内 disabledDate(date) { // 禁用周末date 已归一化到 0 点 return date.getDay() 0 || date.getDay() 6; }, disabledTime(date, position) { // 只允许选 9:00-18:00 return { hours: [0, 1, 2, 3, 4, 5, 6, 7, 18, 19, 20, 21, 22, 23] }; }, });disabledDate返回true的日期会被置灰在年/月面板中只有该年月全部日期都被禁用时整个年/月才会置灰。position参数在区间模式下告诉你当前校验的是start还是end面板可实现结束日只能选开始日之后这类联动约束。回调与实例操作回调一共五件外加弹出层继承的afterOpen/afterClose每个回调收到的都是同一个参数对象字段含义只记一次即可回调触发时机说明ready面板渲染打开后拿初始日期做联动onChange面板内日期/时间变化含快速点击、快捷项点击done选择完成点确定、自动确认、点快捷项最常用取最终结果onConfirm/onNow/onClear点击确定/现在/清空需要区分来源时用afterOpen/afterClose弹出层打开/关闭后继承自 popup 组件参数字段类型含义instance实例可再调open/close等方法valuestring按format格式化后的最终字符串区间为起 ~ 止dateTimeobject{year, month, date, hours, minutes, seconds}month从 1 开始endDateTimeobject区间模式下的结束日期结构同上实例方法覆盖了旧版laydate.close(id)/laydate.hint()的全部用法const inst datePicker.render({ elem: #callback-demo, done({ value, dateTime, endDateTime }) { console.log(最终结果, value, dateTime, endDateTime); }, }); inst.open(); // 外部打开配合 trigger: manual 做纯按钮触发 inst.close(); // 外部关闭 inst.showMessage({ content: 请选择有效日期, ms: 2000 }); // 面板内轻提示 inst.destroy(); // 销毁实例路由切换/组件卸载时调用避免残留两个高频实战组合生日选择器——生日不能是未来且选完要算年龄datePicker.render({ elem: #birthday, max: 0, // 今天23:59:59为上限未来日期自动禁用 variant: grid, done({ value }) { const birth new Date(value); const now new Date(); let age now.getFullYear() - birth.getFullYear(); const passed now.getMonth() birth.getMonth() || (now.getMonth() birth.getMonth() now.getDate() birth.getDate()); document.getElementById(age).value passed ? age - 1 : age; }, });动态按钮触发的面板——面板不跟输入框只跟业务按钮走$(#btn-pick).on(click, () { datePicker.render({ elem: #pick-target, trigger: manual, // 不响应元素自身事件 defaultOpen: true, // 渲染完立即打开 }); });其他实用小开关面板打开状态下按回车等同点确定autoConfirm: false可关掉点日期即回填强制用户点确定weekStart: 1默认周一控制周起始日也接受0-6timePanelMode: inline让 datetime 面板的时间列常驻可见仅限非区间。 踩坑速查与调优清单下面每条都是现象 → 原因 → 解法排查时按顺序对号入座。输入框已有值打开面板却提示格式不合法并自动重置。原因组件严格按format模板反向解析现有值2026/8/3配yyyy-MM-dd就会失败。解法让存量数据与format一致若只是显示想好看用formatToDisplay传函数只改显示不影响值。初始值悄悄变成了别的日期。原因value落在min/max之外组件自动夹到边界并弹面板提示。解法核对三者或用Date对象传值避开字符串解析歧义。结束日期选在了开始日期之前确定按钮是灰的。原因区间校验拦截面板会提示结束时间不能早于开始时间。解法保持默认拦截逻辑或开rangeLinked: auto联动模式下反选会自动交换起止并重绘面板。面板跟随滚动错位、点输入框面板不关。定位由框架的 floating-ui 能力驱动滚动时自动重排属正常行为再次点击目标元素默认保持面板开启repeatClick: keep想点击即关传repeatClick: close。非 input 元素上设trigger: focus无效。原因组件检测到目标不是输入框/文本域时会自动降级为click。想只由按钮打开用trigger: manualinst.open()。年份选到很大或很小的值被拦截。内部年份合法区间为 100200000越界会提示非法日期并夹取。样式被页面全局 CSS 覆盖。优先用更具体的选择器或variant变体其次覆盖 CSS 变量最后才考虑类名前缀隔离需要遮挡页面时开backdrop数值即透明度如0.03。移动端体验差。弹出层在触屏上自动使用触摸触发小屏建议加大触发元素弹层内使用日期选择器时提高z-index或开遮罩避免点击穿透。调优清单按投入产出排序批量绑定elem: .batch-date一次 render 绑定页面里所有同构输入框不必逐个初始化。全局默认值datePicker.config({ trigger: focus })一次配置影响后续所有 render。国际化内置cn/enlang: en切换其他语言通过 src/core/i18n.js 扩展词条。路由切换离开页面时调用inst.destroy()清掉面板与键盘监听。动态内容AJAX 渲染完 DOM 后再 render或先trigger: manual建实例需要时open()。最后留一张配置速查表收工前对照一遍配置项取值/类型作用elem选择器/元素绑定目标支持类名批量typeyear\|month\|date\|time\|datetime面板类型formatstring输出与解析模板value/autoFillValueDate/string/arraybool初始值与是否自动回填默认回填rangebool / 两个选择器数组区间选择及双输入框绑定rangeSeparatorstring单输入框区间分隔符默认~rangeLinkedbool /auto双日历联动模式min/maxstring/Date/数字可选范围上下限weekStart0-6周起始日默认 1 周一variantdefault\|solid\|grid面板外观变体inlinebool面板内嵌渲染不弹层langcn\|en面板语言showFestival/mark/holidaysbool / object|fn / array|fn节日、自定义标注、节假日补班disabledDate/disabledTimefunction自定义禁用日期/禁用时段shortcutsarray快捷选择栏autoConfirm/btns/showBottom/showPreviewbool / array / bool / bool自动确认与底部栏控制timePanelModetoggle\|inlinedatetime 时间面板模式trigger/backdrop/defaultOpenstring / number / bool触发方式、遮罩、初始打开done/onChange/onConfirm/onNow/onClearfunction生命周期回调组件完整源码在 src/components/datePicker.js遇到本文没覆盖的行为如反选自动交换、边缘月份重绘可以直接搜对应关键字定位实现。【免费下载链接】layui一套遵循浏览器原生态开发模式的 Web UI 组件库。项目地址: https://gitcode.com/GitHub_Trending/la/layui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考