日期与时间选择器

日期与时间选择器 laydate 提供了年、月、日、时、分、秒的多类型选择面板,也是 Layui 的常用组件之一。

示例

常规用法

  

多类型选择器

默认为日期选择器,即上文「常规用法」示例中的效果。以下主要呈现其他类型选择器:

  

范围选择

  

配置快捷选项 2.8+

  

自定义格式

  

节日及标注

  

限制可选日期

  

批量绑定元素

  

更多功能示例

  

自定义主题

  

静态显示

  

扩展农历 🔥

  

API

API 描述
var laydate = layui.laydate 获得 laydate 模块。
laydate.render(options) laydate 组件渲染,核心方法。
laydate.hint(id, opts) 2.8+ 在对应的 laydate 组件面板上弹出提示层。
laydate.getInst(id) 2.8+ 获取组件对应的渲染实例。
laydate.unbind(id) 2.8+ 对目标元素解除当前实例的绑定。
laydate.close(id) 2.7+ 关闭日期面板。
laydate.getEndDate(month, year) 获取某月的最后一天。

渲染

laydate.render(options);

  • 参数 options : 基础属性配置项。#详见属性
    2.8+ : 除 elem 属性外,其他基础属性也可以直接写在元素的 lay-options="{}" 属性中。
<input type="text" id="ID-test-laydate">
<input type="text" class="class-test-laydate" lay-options="{value: '2016-10-14'}">
<input type="text" class="class-test-laydate" lay-options="{value: '2017-08-21'}">
 
<!-- import layui --> 
<script>
layui.use(function(){
  var laydate = layui.laydate;
  // 单个渲染
  laydate.render({
    elem: '#ID-test-laydate'
  });
  // 批量渲染
  laydate.render({
    elem: '.class-test-laydate'
  });
});
</script>

属性

属性名 描述 类型 默认值
elem

绑定元素选择器或 DOM 对象

string/DOM -

type

组件面板选择类型。支持以下可选值:
  • year 年选择器,只提供年列表选择
  • month 年月选择器,只提供年、月选择
  • date 日期选择器(默认),可选择:年、月、日选择
  • time 时间选择器,只提供时、分、秒选择
  • datetime 日期时间选择器,可选择:年月日、时分秒

效果详见: #示例

string

date

id

设定实例唯一索引,以便用于其他方法对例进行相关操作。若该属性未设置,则默认从 elem 属性绑定的元素中的 id 属性值中获取。

string -

range

开启左右面板的范围选择,将会根据 type 类型呈现对应的范围选择面板。该属性值支持以下类型:

  • 若为 boolean 类型,即表示是否开启范围选择,若设为 true,则开始日期与结束日期默认采用 - 连接符
  • 若为 string 类型,则表示开启范围选择,且自定义开始日期与结束日期的连接符。如: range: '~'
  • 若为 array 类型,即表示开启范围选,且开始日期和结束日期分别赋值在两个目标选择器中,如:
range: ['#start', '#end']

详细用法可参考: #示例

boolean
string
array

false

rangeLinked 2.8+

是否开启日期范围选择时的区间联动标注模式,该模式必须开启 range 属性才能生效。日期范围默认采用的是左右面板独立选择模式,设置该属性后,将采用左右面板联动选择模式
效果详见: #示例

boolean

false

fullPanel 2.8+

是否开启全面板,即日期和时间显示在同一面板。 当 type: 'datetime' 且未设置 range 属性时生效。
效果详见: #示例

boolean

false

format

自定义日期和时间值的返回格式,默认值: yyyy-MM-dd。 其格式符规则如下:

格式符 描述
yyyy 年份,输出四个字符。若不足四位,则前置补零
y 年份,允许一位
MM 月份,输出两个字符。若不足两位,则前置补零
M 月份,允许一位
dd 日期,输出两个字符。若不足两位,则前置补零
d 日期,允许一位
HH 小时,输出两个字符。若不足两位,则前面补零
H 小时,允许一位
mm 分钟,输出两个字符。若不足两位,则前面补零
m 分钟,允许一位
ss 秒数,输出两个字符。若不足两位,则前面补零
s 秒数,允许一位

通过上述格式符组成日期时间字符串,如下所示:

// 返回值示例: 2008-08-08 20:08:08
format: 'yyyy-MM-dd HH:mm:ss'
 
// 返回值示例: 北京时间 6 点 30 分
format: '北京时间 H 点 m 分'

相关用法可参考: #示例

formatToDisplay 2.9.9+

仅用于格式化日期显示的格式,不影响日期值

formatToDisplay: function (value) {
  // value - 日期字符串
  var date = new Date(value);
  var displayValue = [
    value,
    date.toLocaleDateString(Intl.LocalesArgument, { weekday: 'long' })
  ].join(' ');
  return displayValue;
};
function -

value

初始值。值支持以下类型:
  • 若为 string 类型,则必须和 format 属性格式对应
value: '2018-08-18'
  • 若为 date 对象类型,则可直接赋值 new Date()
value: new Date(1534766888000) // 参数即为:2018-08-20 20:08:08 的毫秒数
  • 当开启 range 时,初始设置日期范围值
 // 开始日期 - 结束日期
value: '1900-01-01 - 2100-01-01'
string
date

new Date()

isInitValue

是否将初始值填充在目标元素中,一般配合 value 属性使用

boolean

true

shortcuts 2.8+

用于开启面板左侧的快捷选择栏。其值配置规则如下:
shortcuts: [
  {
    text: "快捷选项文本",
    value: '快捷选项值'
  },
  // 更多选项 …
]

其中 value 支持以下类型:

  • 若为 string 类型,必须和 format 设置的格式对应;
  • 若为 date 对象类型,则可通过操作 new Date() 来对选项值进行相应的返回计算;
  • 若为 array 类型,则数组成员可填写开始日期和结束日期。
  • 若为 function 类型,返回值同上。2.8.16+

详细用法可参考: #示例

string
date
array
function
-
weekStart 2.7+

设置起始周。 支持 0-6 的数字,0 即代表从周日开始。

weekStart: 1 // 设置周一为起始周
number

0

isPreview

用于是否在面板左下角显示当前结果的预览。当 type:datetime 时强制为 false

boolean

true

min / max

限制可供选择的最小或最大日期时间值。默认值:

  • min: '1900-1-1'
  • max: '2099-12-31'

属性值支持以下可选类型:

  • 若值为字符类型,则:年月日必须用 - 连接,且时分秒必须用 : 连接。 此处无需遵循 format 设定的格式;
  • 若值为整数类型,且数字 < 86400000,则数字代表天数,如: min: -7 即代表最小日期在 7 天前,正数代表若干天后;
  • 若值为整数类型,且数字 ≥ 86400000,则数字代表毫秒数,如:max: 4073558400000 即代表最大日期在公元 3000年1月1日。

示例:

min: '2017-1-1 00:00:00' // 最小日期时间值
min: -7 // 最小日期为 7 天前
max: 7 // 最大日期为 7 天后

相关效果可参考: #示例

disabledDate 2.9.8+

用于设置不可选取的日期。示例:

disabledDate: function(date, type){
  // date - 当前的日期对象
  // type - 面板类型,'start'/'end'
  // 返回值为 true 的日期会被禁用
  return date.getTime() < new Date(2024, 1).getTime(); // 2024-02-01
}
function -
disabledTime 2.9.8+

用于设置不可选取的时间。示例:

disabledTime: function(date, type){
  // date - 当前的日期对象
  // type - 面板类型,'start'/'end'
  // 数组中指定的时间会被禁用
  return {
    hours: function(){
      return range(0, 10);
    },
    minutes:function(hour){
      return hour > 5 ? range(0, 20) : [];
    },
    seconds:function(hour, minute){
      return range(0, 2);
    }
  };
}
function range(start, end) {
  var result = [];
  for (var i = start; i < end; i++) {
    result.push(i);
  }
  return result;
}
function -
trigger

自定义弹出组件面板的事件

string

click

show

是否在渲染时默认显示组件面板。组件在执行渲染时,默认需通过触发目标元素的事件,方可显示组件面板,而该属性可跳过目标元素的事件,直接显示组件面板。

boolean

false

position

设置组件面板的定位方式。支持以下可选值:

  • absolute 绝对定位,始终吸附在绑定元素周围。
  • fixed 固定定位,初始吸附在绑定元素周围,不随浏览器滚动条所左右。一般用于在固定定位的弹层中使用。
  • static 静态定位,控件将直接嵌套显示在指定容器中。用法详见:#示例
string

absolute

zIndex

设置组件面板的层叠顺序。一般用于解决与其它元素的互相被遮掩的问题。若 position: 'static' 时,则该属性无效。

number

99999999

shade 2.8+

用于开启弹出日期面板时的遮罩。值支持以下可选类型:
  • 若为 number 类型,则表示遮罩透明度。如:
shade: 0.5
  • 若为 array 类型,则可设置遮罩颜色和透明度,如:
shade: [0.5, '#000'] // 遮罩的透明度和背景色

效果详见: #示例

number
array
-
showBottom

是否显示组件面板的底部栏

boolean

true

btns

自定义排版组件面板底部栏中的按钮,按钮将按照数组顺序排列。内置按钮名称:clear,now,confirm

 // 显示清空、确认按钮
btns: ['clear', 'confirm']
array -
autoConfirm 2.8+

是否在选中目标值时即自动确认。
当开启 range 属性时,该属性无效。

boolean

true

lang

设置组件的语言版本。可选值如下:

  • cn 中文版
  • en 英文版
string

cn

theme

设置组件面板主题。除了默认主题,还内置主题: molv grid circle2.8+ ,且支持直接传入自定义的主题色。

theme: '#FF5722'

2.8+ : 多个主题可用数组格式,如:

theme: ['grid', '#FF5722']

若第 1 个成员为 hex 格式的主色值,则第 2 个成员为辅色值

// 主色、辅色 --- 2.8.4 新增
theme: ['#16baaa', '#16b777']

效果及用法详见: #示例

string
array
-
calendar

是否显示我国常见的公历节日。当 lang: 'en' 时无效。

boolean

true

mark

自定义日期标记。该属性是对 calendar 属性的进一步延伸,灵活度更高。属性可批量设置多个日期标记,如:

  • object 类型
mark: {
  '0-10-14': '生日', //每年每月的某一天
  '0-0-10': '工资', // 每月 10 号
  '2008-8-8': '开幕', // 指定的日期
}

前缀 0- 即代表每年,0-0- 即代表每年每月。

  • function 类型 2.9.9+
mark: function (ymd, render) {
  var y = ymd.year;
  var m = ymd.month;
  var d = ymd.date;
  // 字符串
  if (m === 6 && d === 1) return render('儿童节');
  // 对象
  render ({
    '0-10-14': '生日',
    '0-0-15': '中旬',
    '2024-03-20': 'v2',
    '2024-03-31': '月底',
  });
}

效果详见: #示例

object -

holidays 2.7+

用于标注节假日及补班日。
  • 若为 array 类型,值是一个二维数组,如:
holidays: [
  // 2023 年的节假日
  ['2023-1-1','2023-1-2','2023-1-3'],
  // 2023 年的补班日
  ['2023-1-28','2023-1-29']
]
  • 若为 function 类型 2.9.9+
holidays: function (ymd, render) {
  var y = ymd.year;
  var m = ymd.month;
  var d = ymd.date;
  // 字符串
  if (y === 2023 && m === 6) {
    render('holidays'); // 'holidays'/'workdays'
  // 数组
  } else if (y === 2024) {
    render([
      ['2024-03-01', '2024-03-02', '2024-03-03'],
      ['2024-03-6', '2024-03-25'],
    ]);
  }
}

相关日期值可详细参考国家每年公布的法定节假日安排

效果详见: #示例

array -
cellRender 2.9.9+

自定义单元格内容。

cellRender: function(ymd, render, info){
  var y = ymd.year;
  var m = ymd.month;
  var d = ymd.date;
  // 面板类型 'year' | 'month' | 'date'
  if(info.type === 'date'){
    render(d); // 参数为 string, HTMLElement, JQuery 类型
  }
}
function -

ready

组件面板初始打开的回调函数。返回的参数如下:
ready: function(date){
  /* 得到初始的日期时间对象,date 参数格式如下:
    {
      year: 2017, // 年
      month: 8, // 月
      date: 18, // 日 
      hours: 0, // 时 
      minutes: 0, // 分 
      seconds: 0 // 秒
    }
  */
  console.log(date);
}

change

日期时间被切换后的回调函数。返回的参数如下:
change: function(value, date, endDate){
  console.log(value); // 日期字符,如: 2017-08-18
  console.log(date); // 包含年月日时分秒各项值的对象
  console.log(endDate); // 结束日期时间对象,当设置 range 时才会返回。对象成员同上。
}

done

日期时间选择完毕的回调函数,点击清空、现在、确定也均会触发。返回的参数如下:
done: function(value, date, endDate){
  console.log(value); // 日期字符,如: 2017-08-18
  console.log(date); // 包含年月日时分秒各项值的对象
  console.log(endDate); // 结束日期时间对象,当设置 range 时才会返回。对象成员同上。
}
onConfirm 2.8+

点击底部栏「确定」按钮时的回调函数。返回的参数同 done

onNow 2.8+

点击底部栏「现在」按钮时的回调函数。返回的参数同 done

onClear 2.8+

点击底部栏「清空」按钮时的回调函数。返回的参数同 done

close 2.7+

组件面板被关闭(移除)后的回调函数。无返回参数。

弹出提示 2.8+

laydate.hint(id, opts);

  • 参数 id : 组件渲染时定义的 id 属性值
  • 参数 opts : 该方法支持的属性可选项,详见下表
opts 描述 类型 默认值
content 提示内容 string -
ms 提示层自动消失所需的毫秒数 number 3000

该方法用于在指定的日期面板弹出一个提示层。

var laydate = layui.laydate;
// 渲染
laydate.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 
  // 其他属性 …
});
// 弹出提示
laydate.hint('test', {
  content: '提示内容'
});

获取实例 2.8+

laydate.getInst(id);

  • 参数 id : 组件渲染时定义的 id 属性值

该方法用于获取 laydate 对应 id 的渲染实例,以获得该实例对应的成员属性。

var laydate = layui.laydate;
// 渲染
laydate.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 
  // 其他属性 …
});
// 获取对应的实例
var inst = laydate.getInst('test');
console.log(inst); // 实例对象

解除实例绑定 2.8+

laydate.unbind(id);

  • 参数 id : 组件渲染时定义的 id 属性值

该方法用于对目标元素对应的实例的绑定完全解除,即触发元素事件时,不再执行组件渲染。

var laydate = layui.laydate;
// 渲染
laydate.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 
  // 其他属性 …
});
// 解除对应的实例绑定
laydate.unbind('test');

关闭日期面板 2.7+

laydate.close(id);

  • 参数 id : 组件渲染时定义的 id 属性值。 若 id 参数不填,则关闭当前打开的日期面板

该方法用于关闭对应的日期面板

var laydate = layui.laydate;
// 渲染
laydate.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 
  // 其他属性 …
});
// 关闭对应的日期面板
laydate.close('test');

获取某月的最后一天

laydate.getEndDate(month, year);

  • 参数 month : 月份,默认为当前月。
  • 参数 year : 年份,默认为今年。

该方法用于获取某个月份的最后一天

var days1 = laydate.getEndDate(10); // 获得 10 月的最后一天为 31 号
var days2 = laydate.getEndDate(2, 2080); // 获得 2080 年 2 月的最后一天为 29 号

贴士

laydate 曾经可作为单独组件使用,鉴于维护成本的考量,目前 laydate 组件已完全集成到 Layui 中,而单独版本已不做同步维护。 因此,建议直接使用 layui 中 laydate 即可。