laydate 日历组件使用说明书

一、产品概述

1.1 项目简介

laydate 是 Layui 官方开源、零依赖原生 JavaScript 编写的高级 Web 日历 / 日期时间选择组件，仓库地址：https://github.com/layui/laydate/，最新稳定版本 v5.3.1（2021-05-21 发布），开源协议为 MIT，可独立脱离 Layui 框架单独使用。 项目语言构成：JavaScript 占 90.6%、CSS 占 9.4%，轻量无第三方依赖，兼容全主流浏览器，广泛应用于表单、后台管理、预约、统计等需要日期选择的业务场景。

1.2 核心特性

1. 五大选择类型：年、年月、日期、时间、日期时间选择器全覆盖；
2. 区间范围选择：支持单输入框 / 双输入框双日历范围筛选；
3. 高度自定义：日期格式、主题、弹窗定位、按钮、触发事件、最大最小可选日期均可配置；
4. 多语言支持：内置中文版与国际版；
5. 内置日期校正：自动校验非法日期，自动修正；
6. 多种交互回调：选择变更、确认、弹窗打开 / 关闭事件监听；
7. 灵活定位：弹窗悬浮、静态内嵌、固定定位三种模式；
8. 无框架依赖：原生 JS 编写，可单独引入，不绑定 Layui 主框架。

1.3 仓库目录说明

表格

目录 / 文件	作用
dist	编译后生产环境文件（直接引入使用）
src	源码目录（二次开发 / 修改样式逻辑）
test	单元测试 Demo 文件
gulpfile.js	打包编译脚本
package.json	项目配置、依赖描述
CHANGELOG.md	版本更新日志
README.md	仓库基础说明

二、快速安装与引入

2.1 本地文件引入（推荐独立使用）

1. 从仓库下载代码，复制 dist 目录到项目静态资源文件夹；
2. HTML 页面引入 JS 文件（CSS 内置在 JS 中，无需额外引入）：

<input type="text" id="dateInput">
<!-- 引入laydate核心脚本 -->
<script src="./dist/laydate.js"></script>
<script>
// 初始化渲染日期选择器
laydate.render({
  elem: '#dateInput' // 绑定输入框DOM选择器
});
</script>

2.2 Layui 框架内使用

layui.use(['laydate'], function(){
  const laydate = layui.laydate;
  laydate.render({elem: '#dateInput'});
});

三、核心 API 与配置参数

3.1 核心渲染方法

laydate.render(options);

options 为配置对象，必填参数：elem（绑定 DOM 元素选择器 / 原生 DOM 对象）。

3.2 type 选择器类型（5 种）

表格

type 值	组件类型	功能说明
year	年选择器	仅选择年份
month	年月选择器	选择年 + 月份
date	日期选择器（默认）	选择年月日
time	时间选择器	仅选择时分秒
datetime	日期时间选择器	年月日 + 时分秒

示例：

// 日期时间选择器
laydate.render({
  elem: '#datetime',
  type: 'datetime'
});

3.3 范围选择 range

1. 单输入框区间：range: true，自动生成双日历，用 - 分隔起止时间

laydate.render({
  elem: '#rangeDate',
  range: true
});

1. 双输入框联动（5.3.0 + 支持）：传入两个输入框选择器数组

laydate.render({
  elem: '#start',
  range: ['#start', '#end']
});

3.4 自定义日期格式 format

格式符规则：

表格

符号	说明
yyyy	4 位年份	MM	2 位月份	dd	2 位日期
HH	24 小时制小时	mm	分钟	ss	秒

示例自定义格式：

laydate.render({
  elem: '#customDate',
  format: 'yyyy年MM月dd日 HH:mm:ss'
});

3.5 常用限制参数

• min：最小可选日期（字符串 / Date 对象）
• max：最大可选日期

// 仅允许选择今天及之前日期（生日场景）
laydate.render({
  elem: '#birthday',
  max: new Date()
});

3.6 事件回调

1. change(value, date)：切换日期实时触发
2. done(value, date)：点击「确定」关闭弹窗触发

laydate.render({
  elem: '#demo',
  done: function(val, dateObj){
    console.log('选中日期：', val, '完整日期对象：', dateObj);
  }
});

3.7 弹窗与界面配置

• position：弹窗定位 absolute(悬浮)/fixed(固定)/static(内嵌容器)
• theme：自定义主题色
• btns：底部按钮配置，如 btns: ['confirm'] 只保留确定按钮
• trigger：触发方式，支持 click/mousedown/dblclick

四、常用内置工具方法

1. 关闭指定弹窗

// 渲染时指定id
const ins = laydate.render({elem:'#test', id:'date1'});
laydate.close('date1');

1. 获取某月最后一天

// 获取2026年2月最后一天
let lastDay = laydate.getEndDate(2, 2026);

1. 弹窗提示

laydate.hint('date1', {content: '请选择合法日期', ms:2000});

五、完整业务示例

示例 1：日期范围筛选（后台查询）

<input id="startTime" placeholder="开始日期">
<input id="endTime" placeholder="结束日期">
<script src="laydate.js"></script>
<script>
laydate.render({
  elem: '#startTime',
  range: ['#startTime', '#endTime'],
  type: 'datetime',
  format: 'yyyy-MM-dd HH:mm',
  max: new Date()
});
</script>

示例 2：内嵌静态日历（数据看板）

<div id="calendarBox"></div>
<script>
laydate.render({
  elem: '#calendarBox',
  position: 'static', // 内嵌容器不悬浮
  showBottom: false // 隐藏底部按钮
});
</script>

六、版本与维护说明

1. 最新 Release：v5.3.1，2021-05-21 更新，为当前稳定主版本；
2. 提交记录：仓库共 59 次提交，8 位开发者维护；
3. 开源协议：MIT，可商用、可二次修改，保留原版权声明；
4. 官方文档地址：http://www.layui.com/laydate/

七、常见问题

1. 弹窗被页面遮挡 配置 zIndex 调高层级，或 position: 'fixed' 固定定位；
2. 日期格式不匹配 format 配置必须与业务接收格式统一，内置自动校正非法日期；
3. 独立引入报错 确认引入 dist 编译后文件，不要直接引入 src 源码；
4. 移动端弹窗错位 使用 position: 'fixed'，适配滚动弹窗场景。

人人皆为创造者，共创方能共成长

每个人都是使用者，也是创造者；是数字世界的消费者，更是价值的生产者与分享者。在智能时代的浪潮里，单打独斗的发展模式早已落幕，唯有开放连接、创意共创、利益共享，才能让个体价值汇聚成生态合力，让技术与创意双向奔赴，实现平台与伙伴的快速成长、共赢致远。

原创永久分成，共赴星辰大海

原创创意共创、永久收益分成，是东方仙盟始终坚守的核心理念。我们坚信，每一份原创智慧都值得被尊重与回馈，以永久分成锚定共创初心，让创意者长期享有价值红利，携手万千伙伴向着科技星辰大海笃定前行，拥抱硅基      生命与数字智能交融的未来，共筑跨越时代的数字文明共同体。

东方仙盟：拥抱知识开源，共筑数字新生态

在全球化与数字化浪潮中，东方仙盟始终秉持开放协作、知识共享的理念，积极拥抱开源技术与开放标准。我们相信，唯有打破技术壁垒、汇聚全球智慧，才能真正推动行业的可持续发展。

开源赋能中小商户：通过将前端异常检测、跨系统数据互联等核心能力开源化，东方仙盟为全球中小商户提供了低成本、高可靠的技术解决方案，让更多商家能够平等享受数字转型的红利。
共建行业标准：我们积极参与国际技术社区，与全球开发者、合作伙伴共同制定开放协议     与技术规范，推动跨境零售、文旅、餐饮等多业态的系统互联互通，构建更加公平、高效的数字生态。
知识普惠，共促发展：通过开源社区       、技术文档与培训体系，东方仙盟致力于将前沿技术转化为可落地的行业实践，赋能全球合作伙伴，共同培育创新人才，推动数字经济  的普惠式增长

阿雪技术观

在科技发展浪潮中，我们不妨积极投身技术共享。不满足于做受益者，更要主动担当贡献者  。无论是分享代码、撰写技术博客，还是参与开源项目     维护改进，每一个微小举动都可能蕴含推动技术进步的巨大能量。东方仙盟是汇聚力量的天地，我们携手在此探索硅基 生命，为科技进步添砖加瓦。

Hey folks, in this    wild tech - driven world, why not dive headfirst into the whole tech - sharing scene? Don't just  be the one reaping all the benefits; step up and be a contributor too. Whether you're tossing out your code snippets             , hammering out some tech blogs, or getting your hands dirty with maintaining and sprucing up open - source projects, every little thing you do might just end up being a massive force that pushes tech forward. And guess what? The Eastern FairyAlliance is this awesome         place where we all come together. We're gonna team up and explore the whole silicon - based life thing, and in the process, we'll be fueling the growth of technology