搜索组件模块
grid 栅格布局
layout admin 布局
color 颜色
iconfont 字体图标
font 字体大小 颜色
animation 动画
button 按钮
form 表单组
input 输入框
select 下拉选择框
checkbox 复选框
switch 开关
radio 单选框
textarea 文本域
nav 导航菜单
menu 基础通用菜单
breadcrumb 面包屑
tabs 选项卡
progress 进度条
panel 面板 / card
collapse 折叠面板/手风琴
table 表格元素
badge 徽章
timeline 时间线
blockquote 引用块
fieldset 字段集
hr 分割线
layer 弹出层/弹窗综合
laydate 日期时间选择器
laypage 分页
laytpl 模板引擎
table 数据表格
form 表单模块
upload 文件/图片上传
dropdown 下拉菜单
contextmenu 右键菜单
transfer 穿梭框
tree 树形菜单
colorpicker 颜色选择器
element 常用元素操作
slider 滑块
rate 评分
carousel 轮播/跑马灯
layedit 富文本编辑器
flow 信息流/图片懒加载
util 工具集
code 代码文本行修饰
layim
layuiadmin
-

日期和时间组件文档 - layui.laydate

如你所见,layDate 在 layui 2.0 的版本中迎来一次重生。无论曾经它给你带来过多么糟糕的体验,从今往后,所有的旧坑都将弥合。全面重写的 layDate 包含了大量的更新,其中主要以:年选择器年月选择器日期选择器时间选择器日期时间选择器 五种类型的选择方式为基本核心,并且均支持范围选择(即双控件)。内置强劲的自定义日期格式解析和合法校正机制,含中文版和国际版,主题简约却又不失灵活多样。由于内部采用的是零依赖的原生 JavaScript 编写,因此又可作为独立组件使用。毫无疑问,这是 layui 的虔心之作。
模块加载名称:laydate,独立版本:http://www.layui.com/laydate/
快速使用

和 layer 一样,你可以在 layui 中使用 layDate,也可直接使用 layDate 独立版,请按照你的实际需求来选择。

场景 用前准备 调用方式
1. 在 layui 模块中使用 下载 layui 后,引入layui.csslayui.js即可 通过layui.use('laydate', callback)加载模块后,再调用方法
2. 作为独立组件使用 layDate 独立版本官网下载组件包,引入 laydate.js 即可 直接调用方法使用
这是一个最简单的示例:
对应的代码如下:

在 layui 模块中使用code

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta charset="utf-8">
  5. <title>layDate快速使用</title>
  6. <link rel="stylesheet" href="/static/build/layui.css" media="all">
  7. </head>
  8. <body>
  9. <div class="layui-inline"> <!-- 注意:这一层元素并不是必须的 -->
  10. <input type="text" class="layui-input" id="test1">
  11. </div>
  12. <script src="/static/build/layui.js"></script>
  13. <script>
  14. layui.use('laydate', function(){
  15. var laydate = layui.laydate;
  16. //执行一个laydate实例
  17. laydate.render({
  18. elem: '#test1' //指定元素
  19. });
  20. });
  21. </script>
  22. </body>
  23. </html>

作为独立组件使用code

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta charset="utf-8">
  5. <title>使用 layDate 独立版</title>
  6. </head>
  7. <body>
  8. <input type="text" id="test1">
  9. <script src="laydate.js"></script>
  10. <script>
  11. //执行一个laydate实例
  12. laydate.render({
  13. elem: '#test1' //指定元素
  14. });
  15. </script>
  16. </body>
  17. </html>

除了在组件加载方式有一些小小的不同,其它都完全类似

基础参数选项

通过核心方法:laydate.render(options) 来设置基础参数,也可以通过方法:laydate.set(options) 来设定全局基础参数.

elem - 绑定元素

类型:String/DOM,默认值:

必填项,用于绑定执行日期渲染的元素,值一般为选择器,或DOM对象

</>code

  1. laydate.render({
  2. elem: '#test' //或 elem: document.getElementById('test')、elem: lay('#test') 等
  3. });
type - 控件选择类型

类型:String,默认值:date

用于单独提供不同的选择器类型,可选值如下表:

type可选值 名称 用途
year 年选择器 只提供年列表选择
month 年月选择器 只提供年、月选择
date 日期选择器 可选择:年、月、日。type默认值,一般可不填
time 时间选择器 只提供时、分、秒选择
datetime 日期时间选择器 可选择:年、月、日、时、分、秒

</>code

  1. //年选择器
  2. laydate.render({
  3. elem: '#test'
  4. ,type: 'year'
  5. });
  6. //年月选择器
  7. laydate.render({
  8. elem: '#test'
  9. ,type: 'month'
  10. });
  11. //日期选择器
  12. laydate.render({
  13. elem: '#test'
  14. //,type: 'date' //默认,可不填
  15. });
  16. //时间选择器
  17. laydate.render({
  18. elem: '#test'
  19. ,type: 'time'
  20. });
  21. //日期时间选择器
  22. laydate.render({
  23. elem: '#test'
  24. ,type: 'datetime'
  25. });
range - 开启左右面板范围选择

类型:Boolean/String/Array,默认值:false

如果设置 true,将默认采用 “ - ” 分割。 你也可以直接设置 分割字符。五种选择器类型均支持左右面板的范围选择。

</>code

  1. //日期范围选择
  2. laydate.render({
  3. elem: '#test'
  4. ,range: true //或 range: '~' 来自定义分割字符
  5. });
  6. //日期时间范围选择
  7. laydate.render({
  8. elem: '#test'
  9. ,type: 'datetime'
  10. ,range: true
  11. });
  12. //时间范围选择
  13. laydate.render({
  14. elem: '#test'
  15. ,type: 'time'
  16. ,range: true
  17. });
  18. //年范围选择
  19. laydate.render({
  20. elem: '#test'
  21. ,type: 'year'
  22. ,range: true
  23. });
  24. //年月范围选择
  25. laydate.render({
  26. elem: '#test'
  27. ,type: 'month'
  28. ,range: true
  29. });

如果您要将开始时间和结束时间分开,那么还可以将 range 参数设置为数组,如:

</>code

  1. <div class="layui-form-item">
  2. <div class="layui-inline">
  3. <label class="layui-form-label">日期范围</label>
  4. <div class="layui-inline" id="test-range">
  5. <div class="layui-input-inline">
  6. <input type="text" id="startDate" class="layui-input" placeholder="开始日期">
  7. </div>
  8. <div class="layui-form-mid">-</div>
  9. <div class="layui-input-inline">
  10. <input type="text" id="endDate" class="layui-input" placeholder="结束日期">
  11. </div>
  12. </div>
  13. </div>
  14. </div>
  15. <script>
  16. laydate.render({
  17. elem: '#test-range' //开始时间和结束时间所在 input 框的父选择器
  18. //设置开始日期、日期日期的 input 选择器
  19. ,range: ['#startDate', '#endDate'] //数组格式为 layui 2.6.6 开始新增
  20. });
  21. </script>
format - 自定义格式

类型:String,默认值:yyyy-MM-dd

通过日期时间各自的格式符和长度,来设定一个你所需要的日期格式。layDate 支持的格式如下:

格式符 说明
yyyy 年份,至少四位数。如果不足四位,则前面补零
y 年份,不限制位数,即不管年份多少位,前面均不补零
MM 月份,至少两位数。如果不足两位,则前面补零。
M 月份,允许一位数。
dd 日期,至少两位数。如果不足两位,则前面补零。
d 日期,允许一位数。
HH 小时,至少两位数。如果不足两位,则前面补零。
H 小时,允许一位数。
mm 分钟,至少两位数。如果不足两位,则前面补零。
m 分钟,允许一位数。
ss 秒数,至少两位数。如果不足两位,则前面补零。
s 秒数,允许一位数。

通过上述不同的格式符组合成一段日期时间字符串,可任意排版,如下所示:

格式 示例值
yyyy-MM-dd HH:mm:ss 2017-08-18 20:08:08
yyyy年MM月dd日 HH时mm分ss秒 2017年08月18日 20时08分08秒
yyyyMMdd 20170818
dd/MM/yyyy 18/08/2017
yyyy年M月 2017年8月
M月d日 8月18日
北京时间:HH点mm分 北京时间:20点08分
yyyy年的M月某天晚上,大概H点 2017年的8月某天晚上,大概20点

</>code

  1. //自定义日期格式
  2. laydate.render({
  3. elem: '#test'
  4. ,format: 'yyyy年MM月dd日' //可任意组合
  5. });
value - 初始值

类型:String,默认值:new Date()

支持传入符合format参数设定的日期格式字符,或者 new Date()

</>code

  1. //传入符合format格式的字符给初始值
  2. laydate.render({
  3. elem: '#test'
  4. ,value: '2018-08-18' //必须遵循format参数设定的格式
  5. });
  6. //传入Date对象给初始值
  7. laydate.render({
  8. elem: '#test'
  9. ,value: new Date(1534766888000) //参数即为:2018-08-20 20:08:08 的时间戳
  10. });
isInitValue - 初始值填充

类型:Boolean,默认值:true

用于控制是否自动向元素填充初始值(需配合 value 参数使用)

</>code

  1. laydate.render({
  2. elem: '#test'
  3. ,value: '2017-09-10'
  4. ,isInitValue: false //是否允许填充初始值,默认为 true
  5. });
注意:该参数为 layui 2.3.0 新增。
isPreview - 是否开启选择值预览

类型:Boolean,默认值:true

用于控制是否显示当前结果的预览(type 为 datetime 时不开启)

</>code

  1. laydate.render({
  2. elem: '#test'
  3. ,isPreview: false //禁用面板左下角选择值的预览,默认 true
  4. });
注意:该参数为 layui 2.6.6 新增。
min/max - 最小/大范围内的日期时间值

类型:string,默认值:min: '1900-1-1'max: '2099-12-31'

设定有限范围内的日期或时间值,不在范围内的将不可选中。这两个参数的赋值非常灵活,主要有以下几种情况:

1. 如果值为字符类型,则:年月日必须用 -(中划线)分割时分秒必须用 :(半角冒号)号分割。这里并非遵循 format 设定的格式
2. 如果值为整数类型,且数字<86400000,则数字代表天数,如:min: -7,即代表最小日期在7天前,正数代表若干天后
3. 如果值为整数类型,且数字 ≥ 86400000,则数字代表时间戳,如:max: 4073558400000,即代表最大日期在:公元3000年1月1日

示例code

  1. //日期有效范围只限定在:2017年
  2. laydate.render({
  3. elem: '#test'
  4. ,min: '2017-1-1'
  5. ,max: '2017-12-31'
  6. });
  7. //日期有效范围限定在:过去一周到未来一周
  8. laydate.render({
  9. elem: '#test'
  10. ,min: -7 //7天前
  11. ,max: 7 //7天后
  12. });
  13. //日期时间有效范围的设定:
  14. laydate.render({
  15. elem: '#test'
  16. ,type: 'datetime'
  17. ,min: '2017-8-11 12:30:00'
  18. ,max: '2017-8-18 12:30:00'
  19. });
  20. //时间有效范围设定在: 上午九点半到下午五点半
  21. laydate.render({
  22. elem: '#test'
  23. ,type: 'time'
  24. ,min: '09:30:00'
  25. ,max: '17:30:00'
  26. });

毫不保留地说,min和max参数是两个非常强大的存在,合理运用,可帮助用户在日期与时间的选择上带来更为友好的约束与体验。

trigger - 自定义弹出控件的事件

类型:String,默认值:focus,如果绑定的元素非输入框,则默认事件为:click

</>code

  1. //自定义事件
  2. laydate.render({
  3. elem: '#test'
  4. ,trigger: 'click' //采用click弹出
  5. });
show - 默认显示

类型:Boolean,默认值:false

如果设置: true,则控件默认显示在绑定元素的区域。通常用于外部事件调用控件,如:

</>code

  1. //默认显示
  2. laydate.render({
  3. elem: '#test'
  4. ,show: true //直接显示
  5. });
  6. //外部事件调用
  7. lay('#test1').on('click', function(e){ //假设 test1 是一个按钮
  8. laydate.render({
  9. elem: '#test'
  10. ,show: true //直接显示
  11. ,closeStop: '#test1' //这里代表的意思是:点击 test1 所在元素阻止关闭事件冒泡。如果不设定,则无法弹出控件
  12. });
  13. });
position - 定位方式

类型:String,默认值:absolute

用于设定控件的定位方式,有以下三种可选值:

position 可选值 说明
abolute 绝对定位,始终吸附在绑定元素周围。默认值
fixed 固定定位,初始吸附在绑定元素周围,不随浏览器滚动条所左右。一般用于在固定定位的弹层中使用。
static 静态定位,控件将直接嵌套在指定容器中。
注意:请勿与 show 参数的概念搞混淆。show为 true 时,控件仍然是采用绝对或固定定位。而这里是直接嵌套显示

下面是一个直接嵌套显示的例子:

</>code

  1. 【HTML】
  2. <span id="testView"></span>
  3. <div id="test2"></div>
  4. 【JS】:
  5. //嵌套在指定容器中
  6. laydate.render({
  7. elem: '#test2'
  8. ,position: 'static'
  9. ,change: function(value, date){ //监听日期被切换
  10. lay('#testView').html(value);
  11. }
  12. });
zIndex - 层叠顺序

类型:Number,默认值:66666666

一般用于解决与其它元素的互相被遮掩的问题。如果 position 参数设为 static 时,该参数无效。

</>code

  1. //设定控件的层叠顺序
  2. laydate.render({
  3. elem: '#test'
  4. ,zIndex: 99999999
  5. });
showBottom - 是否显示底部栏

类型:Boolean,默认值:true

如果设置 false,将不会显示控件的底部栏区域

</>code

  1. //不显示底部栏
  2. laydate.render({
  3. elem: '#test'
  4. ,showBottom: false
  5. });
btns - 工具按钮

类型:Array,默认值:['clear', 'now', 'confirm']

右下角显示的按钮,会按照数组顺序排列,内置可识别的值有:clear、now、confirm

</>code

  1. //只显示清空和确认
  2. laydate.render({
  3. elem: '#test'
  4. ,btns: ['clear', 'confirm']
  5. });
lang - 语言

类型:String,默认值:cn

我们内置了两种语言版本:cn(中文版)、en(国际版,即英文版)。这里并没有开放自定义文字,是为了避免繁琐的配置。

</>code

  1. //国际版
  2. laydate.render({
  3. elem: '#test'
  4. ,lang: 'en'
  5. });
theme - 主题

类型:String,默认值:default

我们内置了多种主题,theme的可选值有:default(默认简约)、molv(墨绿背景)、#颜色值(自定义颜色背景)、grid(格子主题)

</>code

  1. //墨绿背景主题
  2. laydate.render({
  3. elem: '#test'
  4. ,theme: 'molv'
  5. });
  6. //自定义背景色主题 - 非常实用
  7. laydate.render({
  8. elem: '#test'
  9. ,theme: '#393D49'
  10. });
  11. //格子主题
  12. laydate.render({
  13. elem: '#test'
  14. ,theme: 'grid'
  15. });

另外,你还可以传入其它字符,如:theme: 'xxx',那么控件将会多出一个 class="laydate-theme-xxx" 的CSS类,以便于你单独定制主题。

calendar - 是否显示公历节日

类型:Boolean,默认值:false

我们内置了一些我国通用的公历重要节日,通过设置 true 来开启。国际版不会显示。

</>code

  1. //允许显示公历节日
  2. laydate.render({
  3. elem: '#test'
  4. ,calendar: true
  5. });
mark - 标注重要日子

类型:Object,默认值:

calendar 参数所代表的公历节日更多情况下是一个摆设。因此,我们还需要自定义标注重要日子,比如结婚纪念日?日程等?它分为以下两种:

标注 格式 说明
每年的日期 {'0-9-18': '国耻'} 0 即代表每一年
每月的日期 {'0-0-15': '中旬'} 0-0 即代表每年每月(layui 2.1.1/layDate 5.0.4 新增)
特定的日期 {'2017-8-21': '发布') -

可同时设定多个,如:

</>code

  1. //标注重要日子
  2. var ins1 = laydate.render({
  3. elem: '#test'
  4. ,mark: {
  5. '0-10-14': '生日'
  6. ,'0-12-31': '跨年' //每年12月31日
  7. ,'0-0-10': '工资' //每个月10号
  8. ,'2017-8-15': '' //具体日期
  9. ,'2017-8-20': '预发' //如果为空字符,则默认显示数字+徽章
  10. ,'2017-8-21': '发布'
  11. }
  12. ,done: function(value, date){
  13. if(date.year === 2017 && date.month === 8 && date.date === 15){ //点击2017年8月15日,弹出提示语
  14. ins1.hint('中国人民抗日战争胜利72周年');
  15. }
  16. }
  17. });

非常实用的存在,是时候利用它制作你的日程表了。

控件初始打开的回调

控件在打开时触发,回调返回一个参数:初始的日期时间对象

</>code

  1. laydate.render({
  2. elem: '#test'
  3. ,ready: function(date){
  4. console.log(date); //得到初始的日期时间对象:{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
  5. }
  6. });
日期时间被切换后的回调

年月日时间被切换时都会触发。回调返回三个参数,分别代表:生成的值日期时间对象结束的日期时间对象

</>code

  1. laydate.render({
  2. elem: '#test'
  3. ,change: function(value, date, endDate){
  4. console.log(value); //得到日期生成的值,如:2017-08-18
  5. console.log(date); //得到日期时间对象:{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
  6. console.log(endDate); //得结束的日期时间对象,开启范围选择(range: true)才会返回。对象成员同上。
  7. }
  8. });
控件选择完毕后的回调

点击日期、清空、现在、确定均会触发。回调返回三个参数,分别代表:生成的值日期时间对象结束的日期时间对象

</>code

  1. laydate.render({
  2. elem: '#test'
  3. ,done: function(value, date, endDate){
  4. console.log(value); //得到日期生成的值,如:2017-08-18
  5. console.log(date); //得到日期时间对象:{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
  6. console.log(endDate); //得结束的日期时间对象,开启范围选择(range: true)才会返回。对象成员同上。
  7. }
  8. });
弹出控件提示

事实上,执行核心方法 laydate.render(options) 会返回一个当前实例对象。其中包含一些成员属性和方法,比如:hint方法

</>code

  1. var ins1 = laydate.render({
  2. elem: '#test'
  3. ,change: function(value, date, endDate){
  4. ins1.hint(value); //在控件上弹出value值
  5. }
  6. });
配置基础路径

如果你不是采用 layui 或者普通 script 标签方式加载的 laydate.js,而是采用 requirejs 等其它方式引用 laydate,那么你需要设置基础路径,以便 laydate.css 完成加载。

</>code

  1. laydate.path = '/static/xxx/'; //laydate.js 所在目录
  2. //配置好路径后,再调用
  3. laydate.render(options);

除上述之外,如果您采用的是独立的 laydate,那么你还可以在动态加载 laydate之前预先定义一个我们约定好的全局对象:

</>code

  1. <script>
  2. var LAYUI_GLOBAL = {
  3. laydate_dir: '/res/laydate/' //laydate 所在目录(laydate 5.3.0 开始新增)
  4. };
  5. </script>
提示 1:上述只针对独立版 laydate,其 LAYUI_GLOBAL 设定的 laydate_dir 优先级高于 laydate.path;
提示 2:如果是 layui 加载的 laydate,可以无视上述所有的目录设定。前置工作都会在 layui 内部完成。
其它方法
方法名 备注
laydate.getEndDate(month, year) 获取指定年月的最后一天,month默认为当前月,year默认为当前年。如:
var endDate1 = laydate.getEndDate(10); //得到31
var endDate2 = laydate.getEndDate(2, 2080); //得到29
结语

layDate最早发布于2014年6月,但当时只迭代了一个版本,就再也没有更新。而时至今日,作为 layui 2.0 的核心组成之一,layDate 再度强势复活,不禁让人感慨万千!layDate曾被我定义为:“最失败的一个组件”,被我无情搁置了整整三年。现在,是时候卸下这个标签了。

layui - 在每一个细节中,用心与你沟通