日期和時間組件文檔 - layui.laydate

                    如你所見,layDate 在 layui 2.0 的版本中迎來一次重生。無論曾經它給你帶來過多么糟糕的體驗,從今往后,所有的舊坑都將彌合。全面重寫的 layDate 包含了大量的更新,其中主要以:年選擇器年月選擇器日期選擇器時間選擇器日期時間選擇器 五種類型的選擇方式為基本核心,并且均支持范圍選擇(即雙控件)。內置強勁的自定義日期格式解析和合法校正機制,含中文版和國際版,主題簡約卻又不失靈活多樣。由于內部采用的是零依賴的原生 JavaScript 編寫,因此又可作為獨立組件使用。毫無疑問,這是 layui 的虔心之作。
                    模塊加載名稱:laydate,獨立版本:http://www.fk434.com/laydate/
                    快速使用

                    和 layer 一樣,你可以在 layui 中使用 layDate,也可直接使用 layDate 獨立版,請按照你的實際需求來選擇。

                    場景 用前準備 調用方式
                    1. 在 layui 模塊中使用 下載 layui 后,引入layui.csslayui.js即可 通過layui.use('laydate', callback)加載模塊后,再調用方法
                    2. 作為獨立組件使用 layDate 獨立版本官網下載組件包,引入 laydate.js 即可 直接調用方法使用
                    這是一個最簡單的示例:
                    對應的代碼如下:
                    <!DOCTYPE html>
                    <html>
                    <head>
                      <meta charset="utf-8">
                      <title>layDate快速使用</title>
                      <link rel="stylesheet" href="/static/build/layui.css" media="all">
                    </head>
                    <body>
                     
                    <div class="layui-inline"> <!-- 注意:這一層元素并不是必須的 -->
                      <input type="text" class="layui-input" id="test1">
                    </div>
                     
                    <script src="/static/build/layui.js"></script>
                    <script>
                    layui.use('laydate', function(){
                      var laydate = layui.laydate;
                      
                      //執行一個laydate實例
                      laydate.render({
                        elem: '#test1' //指定元素
                      });
                    });
                    </script>
                    </body>
                    </html>
                          
                    <!DOCTYPE html>
                    <html>
                    <head>
                      <meta charset="utf-8">
                      <title>使用 layDate 獨立版</title>
                    </head>
                    <body>
                     
                    <input type="text" id="test1">
                     
                    <script src="laydate.js"></script>
                    <script>
                    //執行一個laydate實例
                    laydate.render({
                      elem: '#test1' //指定元素
                    });
                    </script>
                    </body>
                    </html>
                          

                    除了在組件加載方式有一些小小的不同,其它都完全類似

                    基礎參數選項

                    通過核心方法:laydate.render(options) 來設置基礎參數,也可以通過方法:laydate.set(options) 來設定全局基礎參數.

                    elem - 綁定元素

                    類型:String/DOM,默認值:

                    必填項,用于綁定執行日期渲染的元素,值一般為選擇器,或DOM對象

                    laydate.render({ 
                      elem: '#test' //或 elem: document.getElementById('test')、elem: lay('#test') 等
                    });
                          
                    type - 控件選擇類型

                    類型:String,默認值:date

                    用于單獨提供不同的選擇器類型,可選值如下表:

                    type可選值 名稱 用途
                    year 年選擇器 只提供年列表選擇
                    month 年月選擇器 只提供年、月選擇
                    date 日期選擇器 可選擇:年、月、日。type默認值,一般可不填
                    time 時間選擇器 只提供時、分、秒選擇
                    datetime 日期時間選擇器 可選擇:年、月、日、時、分、秒
                    //年選擇器
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'year'
                    });
                     
                    //年月選擇器
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'month'
                    });
                     
                    //日期選擇器
                    laydate.render({ 
                      elem: '#test'
                      //,type: 'date' //默認,可不填
                    });
                     
                    //時間選擇器
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'time'
                    });
                     
                    //日期時間選擇器
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'datetime'
                    });
                          
                    range - 開啟左右面板范圍選擇

                    類型:Boolean/String,默認值:false

                    如果設置 true,將默認采用 “ - ” 分割。 你也可以直接設置 分割字符。五種選擇器類型均支持左右面板的范圍選擇。

                    //年范圍選擇
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'year'
                      ,range: true //或 range: '~' 來自定義分割字符
                    });
                     
                    //年月范圍選擇
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'month'
                      ,range: true //或 range: '~' 來自定義分割字符
                    });
                     
                    //日期范圍選擇
                    laydate.render({ 
                      elem: '#test'
                      ,range: true //或 range: '~' 來自定義分割字符
                    });
                     
                    //時間范圍選擇
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'time'
                      ,range: true //或 range: '~' 來自定義分割字符
                    });
                     
                    //日期時間范圍選擇
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'datetime'
                      ,range: true //或 range: '~' 來自定義分割字符
                    });
                          
                    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點
                    //自定義日期格式
                    laydate.render({ 
                      elem: '#test'
                      ,format: 'yyyy年MM月dd日' //可任意組合
                    });
                          
                    value - 初始值

                    類型:String,默認值:new Date()

                    支持傳入符合format參數設定的日期格式字符,或者 new Date()

                    //傳入符合format格式的字符給初始值
                    laydate.render({ 
                      elem: '#test'
                      ,value: '2018-08-18' //必須遵循format參數設定的格式
                    });
                     
                    //傳入Date對象給初始值
                    laydate.render({ 
                      elem: '#test'
                      ,value: new Date(1534766888000) //參數即為:2018-08-20 20:08:08 的時間戳
                    });
                          
                    isInitValue - 初始值填充

                    類型:Boolean,默認值:true

                    用于控制是否自動向元素填充初始值(需配合 value 參數使用)

                    laydate.render({
                      elem: '#test'
                      ,value: '2017-09-10'
                      ,isInitValue: false //是否允許填充初始值,默認為 true
                    });
                          
                    注意:該參數為 layui 2.3.0 新增。
                    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日
                    //日期有效范圍只限定在:2017年
                    laydate.render({ 
                      elem: '#test'
                      ,min: '2017-1-1'
                      ,max: '2017-12-31'
                    });
                     
                    //日期有效范圍限定在:過去一周到未來一周
                    laydate.render({ 
                      elem: '#test'
                      ,min: -7 //7天前
                      ,max: 7 //7天后
                    });
                     
                    //日期時間有效范圍的設定: 
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'datetime'
                      ,min: '2017-8-11 12:30:00'
                      ,max: '2017-8-18 12:30:00'
                    });
                     
                    //時間有效范圍設定在: 上午九點半到下午五點半
                    laydate.render({ 
                      elem: '#test'
                      ,type: 'time'
                      ,min: '09:30:00'
                      ,max: '17:30:00'
                    });
                          

                    毫不保留地說,min和max參數是兩個非常強大的存在,合理運用,可幫助用戶在日期與時間的選擇上帶來更為友好的約束與體驗。

                    trigger - 自定義彈出控件的事件

                    類型:String,默認值:focus,如果綁定的元素非輸入框,則默認事件為:click

                    //自定義事件
                    laydate.render({ 
                      elem: '#test'
                      ,trigger: 'click' //采用click彈出
                    });
                          
                    show - 默認顯示

                    類型:Boolean,默認值:false

                    如果設置: true,則控件默認顯示在綁定元素的區域。通常用于外部事件調用控件,如:

                    //默認顯示
                    laydate.render({
                      elem: '#test'
                      ,show: true //直接顯示
                    });
                          
                    //外部事件調用
                    lay('#test1').on('click', function(e){ //假設 test1 是一個按鈕
                      laydate.render({
                        elem: '#test'
                        ,show: true //直接顯示
                        ,closeStop: '#test1' //這里代表的意思是:點擊 test1 所在元素阻止關閉事件冒泡。如果不設定,則無法彈出控件
                      });
                    });
                          
                    position - 定位方式

                    類型:String,默認值:absolute

                    用于設定控件的定位方式,有以下三種可選值:

                    position 可選值 說明
                    abolute 絕對定位,始終吸附在綁定元素周圍。默認值
                    fixed 固定定位,初始吸附在綁定元素周圍,不隨瀏覽器滾動條所左右。一般用于在固定定位的彈層中使用。
                    static 靜態定位,控件將直接嵌套在指定容器中。
                    注意:請勿與 show 參數的概念搞混淆。show為 true 時,控件仍然是采用絕對或固定定位。而這里是直接嵌套顯示

                    下面是一個直接嵌套顯示的例子:

                    【HTML】
                    <span id="testView"></span>
                    <div id="test2"></div>
                     
                    【JS】:      
                    //嵌套在指定容器中
                    laydate.render({
                      elem: '#test2'
                      ,position: 'static'
                      ,change: function(value, date){ //監聽日期被切換
                        lay('#testView').html(value);
                      }
                    });
                            
                    zIndex - 層疊順序

                    類型:Number,默認值:66666666

                    一般用于解決與其它元素的互相被遮掩的問題。如果 position 參數設為 static 時,該參數無效。

                    //設定控件的層疊順序
                    laydate.render({
                      elem: '#test'
                      ,zIndex: 99999999
                    });
                          
                    showBottom - 是否顯示底部欄

                    類型:Boolean,默認值:true

                    如果設置 false,將不會顯示控件的底部欄區域

                    //不顯示底部欄
                    laydate.render({
                      elem: '#test'
                      ,showBottom: false
                    });
                          
                    btns - 工具按鈕

                    類型:Array,默認值:['clear', 'now', 'confirm']

                    右下角顯示的按鈕,會按照數組順序排列,內置可識別的值有:clear、now、confirm

                    //只顯示清空和確認
                    laydate.render({
                      elem: '#test'
                      ,btns: ['clear', 'confirm']
                    });
                          
                    lang - 語言

                    類型:String,默認值:cn

                    我們內置了兩種語言版本:cn(中文版)、en(國際版,即英文版)。這里并沒有開放自定義文字,是為了避免繁瑣的配置。

                    //國際版
                    laydate.render({
                      elem: '#test'
                      ,lang: 'en'
                    });
                          
                    theme - 主題

                    類型:String,默認值:default

                    我們內置了多種主題,theme的可選值有:default(默認簡約)、molv(墨綠背景)、#顏色值(自定義顏色背景)、grid(格子主題)

                    //墨綠背景主題
                    laydate.render({
                      elem: '#test'
                      ,theme: 'molv'
                    });
                     
                    //自定義背景色主題 - 非常實用
                    laydate.render({
                      elem: '#test'
                      ,theme: '#393D49'
                    });
                     
                    //格子主題
                    laydate.render({
                      elem: '#test'
                      ,theme: 'grid'
                    });
                          

                    另外,你還可以傳入其它字符,如:theme: 'xxx',那么控件將會多出一個 class="laydate-theme-xxx" 的CSS類,以便于你單獨定制主題。

                    calendar - 是否顯示公歷節日

                    類型:Boolean,默認值:false

                    我們內置了一些我國通用的公歷重要節日,通過設置 true 來開啟。國際版不會顯示。

                    //允許顯示公歷節日
                    laydate.render({
                      elem: '#test'
                      ,calendar: true
                    });
                          
                    mark - 標注重要日子

                    類型:Object,默認值:

                    calendar 參數所代表的公歷節日更多情況下是一個擺設。因此,我們還需要自定義標注重要日子,比如結婚紀念日?日程等?它分為以下兩種:

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

                    可同時設定多個,如:

                    //標注重要日子
                    var ins1 = laydate.render({
                      elem: '#test'
                      ,mark: {
                        '0-10-14': '生日'
                        ,'0-12-31': '跨年' //每年12月31日
                        ,'0-0-10': '工資' //每個月10號
                        ,'2017-8-15': '' //具體日期
                        ,'2017-8-20': '預發' //如果為空字符,則默認顯示數字+徽章
                        ,'2017-8-21': '發布'
                      }
                      ,done: function(value, date){
                        if(date.year === 2017 && date.month === 8 && date.date === 15){ //點擊2017年8月15日,彈出提示語
                          ins1.hint('中國人民抗日戰爭勝利72周年');
                        }
                      }
                    });
                          

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

                    控件初始打開的回調

                    控件在打開時觸發,回調返回一個參數:初始的日期時間對象

                    laydate.render({
                      elem: '#test'
                      ,ready: function(date){
                        console.log(date); //得到初始的日期時間對象:{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
                      }
                    });
                          
                    日期時間被切換后的回調

                    年月日時間被切換時都會觸發。回調返回三個參數,分別代表:生成的值日期時間對象結束的日期時間對象

                    laydate.render({
                      elem: '#test'
                      ,change: function(value, date, endDate){
                        console.log(value); //得到日期生成的值,如:2017-08-18
                        console.log(date); //得到日期時間對象:{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
                        console.log(endDate); //得結束的日期時間對象,開啟范圍選擇(range: true)才會返回。對象成員同上。
                      }
                    });
                          
                    控件選擇完畢后的回調

                    點擊日期、清空、現在、確定均會觸發。回調返回三個參數,分別代表:生成的值日期時間對象結束的日期時間對象

                    laydate.render({
                      elem: '#test'
                      ,done: function(value, date, endDate){
                        console.log(value); //得到日期生成的值,如:2017-08-18
                        console.log(date); //得到日期時間對象:{year: 2017, month: 8, date: 18, hours: 0, minutes: 0, seconds: 0}
                        console.log(endDate); //得結束的日期時間對象,開啟范圍選擇(range: true)才會返回。對象成員同上。
                      }
                    });
                          
                    彈出控件提示

                    事實上,執行核心方法 laydate.render(options) 會返回一個當前實例對象。其中包含一些成員屬性和方法,比如:hint方法

                    var ins1 = laydate.render({
                      elem: '#test'
                      ,change: function(value, date, endDate){
                        ins1.hint(value); //在控件上彈出value值
                      }
                    });
                          
                    配置基礎路徑

                    如果你不是采用 layui 或者普通 script 標簽方式加載的 laydate.js,而是采用 requirejs 等其它方式引用 laydate,那么你需要設置基礎路徑,以便 laydate.css 完成加載。

                    laydate.path = '/static/xxx/'; //laydate.js 所在目錄
                     
                    //配置好路徑后,再調用
                    laydate.render(options);
                          
                    其它方法
                    方法名 備注
                    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 - 用心與你溝通

                    亚洲图色