ui-mcalendar

日历选择插件

兼容性说明

适用于移动端浏览器

特性

1. 选择单个时间点
2. 选择起始时间段
3. 选择单个时间点时可指定能被选择的枚举日期
4. 选择起始时间段时，指定能被选择的起始范围
5. 支持自定义日历模板
6. 支持自定义工具栏
7. 支持与具体的input等元素绑定

安装

 npm install ui-mcalendar --save

使用

支持页面直接引入、AMD、CommonJs的方式加载模块

调用

1.引入样式文件，或者自定义样式;如果引用的js为indexCss.js则无需手动引入css文件

<link rel="stylesheet" type="text/css" href="ui-mcalendar/src/ui-mcalendar.css"/>

2.引入js，以直接引入为例

<script type="text/javascript" src="ui-mcalendar/index.js"></script>

或者直接引入包含了css文件的js，则无需手动引入ui-mcalendar.css

<script type="text/javascript" src="ui-mcalendar/indexCss.js"></script>

3.实例化插件 HTML:

<!--选择日期后值保存在这里-->
<input tpye="input" id="calendarValue"/>
<!--日历容器-->
<div class="wrapper"></div>

JS:

var input = document.querySelector("#calendarValue");
var cal = new futuCalendar({
    wrapper:".wrapper",
    valueTarget:input,
    selectMonth:function(instance,info,offset){
        alert("你切换了月") 
    },
    selectDateCallback:function(el,dataInfo){
        console.log("你选择了日期");
    }
});
cal.show();

一个完整的配置如下：

// 选择单个日期
 var cal = new futuCalendar({
    wrapper:".wrapper",
    templateStr:"<div>.....</div>",
    autohide:true,
    showToolBar:true,
    toolList:[{
        text:"关闭",
        className:"closeCalendar",
        action:function(instance,item){
            instance.hide();
            console.log(item);
        }
    }],
    valueTarget:input,
    templateStr:document.querySelector("#templatedemo").innerHTML,
    enableList:["2016-08-01","2016-08-02"],
    defaultDate:new Date("2016-08-01"),
    selectMonth:function(instance,info,offset){
        console.log(info);
    },
    selectDateCallback:function(el,dataInfo){
        console.log(dataInfo);
    }
});

//选择起始时间段
var cal = new futuCalendar({
      wrapper:".wrapper",
      initshow: false,
      autohide:false,
      hasMask:true,
      startEndSelect: true,
      startEndDataFormat:"yyyy/MM/dd至yyyy/MM/dd",
      startEndConfig:{
          allowStartDate:new Date("2016-09-01"),
          allEndDate:new Date("2016-12-01"),
          duration:60,
          itemClass:"startenditem",
          exceedDuration:function(duration){
              alert("日期选择超过了起始差"+duration);
          }
      },
      showToolBar:true,
      toolList:[{
          text:"最近一周",
          className:"nearweak",
          action:function(instance,item){
              instance.setSEPoints(d,+d + 6*24*3600*1000,function(){});
          }
      },{
          text:"关闭",
          className:"closeCalendar",
          action:function(instance,item){
              instance.hide();
          }
      }],
      valueTarget:input,
      selectDateCallback:function(el,dataInfo){
          console.log(dataInfo);
      }
  });

更多实例

效果图

目录结构

example： 示例目录

src：index.js组件源码，commonjs模式，不可直接运行；ui-calendar.css 默认提供的样式

template：日历模板

gulpfile：打包配置

index.js：打包后的源码,不包含css，使用时可手动引入ui-calendar.css

indexCss.js：打包后的源码,包含css，使用时无需手动引入ui-calendar.css

readme.md：说明文档

在ui-mcalendar目录下运行 $ npm start命令，即可在浏览器中看到目录机构

API

1. futuCalendar(config)

构造函数，参数：

• config: 日历配置相关参数，json对象，具体字段见参数说明。

  • config.templateStr

    类型： String。

    默认值: 组件默认的模板字符串，模板文件存在于templates/mcalendar.html中；用户可以自定义组件模板类型，用于增减页面元素。

  • config.wrapper

    类型： <Element|String>，页面元素或者是元素选择器。

    说明： 组件容器，用于存放日历实例。

    默认值： 空，需用户指定，可选。

  • config.valueTarget

    类型： <Element|String>，页面元素或者是元素选择器。

    说明： 选择某个日期时，会将日期赋值给该元素，如果该元素为input，textarea，则赋值给value属性。否则赋值给元素的innerHTML属性。

    默认值： 空，可选。

  • config.dataFormat

    类型： String

    说明： 填充valueTarget元素的日期格式。各个占位符意思如下： yyyy：年份，四位, MM:月份，两位, dd:日期，2位

    默认值： yyyy-MM-dd, 例如：2016-10-01。

  • config.weekdates

    类型： Array,

    说明： 由于显示星期的名称，插件默认每周首日从周日开始。

    默认值： ["日", "一", "二", "三", "四", "五", "六"]。

    此处功能待扩展

  • config.autohide

    类型： Boolean

    说明： 选中某个日期之后，是否自动关闭（不显示）日历。

    默认值： true,默认会自动关闭。

  • config.enableList

    类型： <Array|"all">

    说明： 指明是否所有日期是否可选。当前值为字符创all时，表示所有 日期均可选，如果只为数组，则表示只有数组中的日期可被选中，此时，能被选中的日期将会获得 selectable类用于标识突出。

    默认值： all，默认所有日期均可选择。

  • config.defaultDate

    类型： Date

    说明： 初次显示日历时，被选中的日期，如果不设置则关联的valueTarget不设置值

    默认值： 空。

  • config.initshow

    类型： Boolean

    说明： 初始化时，是否立即显示日历。

    默认值： false，默认不显示日历。

  • config.hasMask

    类型： Boolean

    说明： 是否显示mask。

    默认值： false，默认不显示遮罩。

  • config.toolTemplateStr

    类型： String 或者 Function

    说明： 可选，用于自定义工具栏部分的模板。如果不设置，则所有按钮均使用a标签,class属性及文本内容。用户可通过此参数配置每个按钮更多属性。当此参数为Function时，必须返回一个字符串作为模板。示例如下：

        <script type="text/template" id="demo-tooltemplate">
            <%_.each(toolList,function(item,i){%>
               <a href='javascript:void(0)' name='test' age='27' tool-id='<%=i%>'  class='<%=item.className%>  tool-item'>按钮<%=item.text%></a>
            <%})%>
        </script>
    

    默认值： 空

  • config.toolList

    类型： Array

    说明： 用于生成顶部工具栏的数组列表

    结构说明： 每个节点最终会生成一个a节点，插入tool-bar中.

    • toolList[i].text:节点（工具按钮）名
    • toolList[i].className:用户设定的类名，可用于自定义样式
    • toolList[i].action:点击工具按钮时的回调函数，回参包括日历实例instance，及当前点击元素item；instance对象可调用其方法，详见下方方法说明。 DEMO：

    toolList:[{
         text:"关闭",
         className:"closeCalendar",
         action:function(instance,item){
             instance.hide();
             console.log(item);
         }
     }]
    

    默认值： 空

  • config.showToolBar

    类型： Boolean

    说明： 是否显示工具栏，为true时显示，为false则不显示。

    默认值： false,不显示工具栏

  • config.startEndSelect

    类型： Boolean

    说明： 日历是否能选择起始时间段（2个时间值），为true及可选择起始时间点，为false只能选择一个日期。

    默认值： false, 只能选择一个时间点

  • config.startEndDataFormat

    类型： String

    **说明：**日历选择的起始时间段（2个时间值），最终会展示的时间格式，主要涉及onfig.valueTarget元素内容及getDateInfo().dateStr的内容格式,只有在config.startEndSelect为true时有意义。

    默认值： yyyy/MM/dd-yyyy/MM/dd

  • config.startEndConfig

    类型： JSON

    说明： 日历允许选择的起始时间段时的配置JSON

     - `startEndConfig.allowStartDate`: 选择时间段时，能选择的最小日期, 类型为Date。
     - `startEndConfig.allEndDate`: 选择时间段时，能选择的最大日期， 类型为Date。
     - `startEndConfig.duration`: 选择的时间段包含的日期个数最大值；用户选择的2个时间区间大于该值时会触发exceedDuration函数， 类型为Number。
     - `startEndConfig.defaultStartEnd`:  默认选择的起始时间点，`[start,end]`,类型为数组，长度为2，元素为可实例化为Date，对象的变量;`start`和`end`必须在`startEndConfig.allEndDate`和`startEndConfig.allEndDate`间，且时间间隔小于或者等于`startEndConfig.duration`，否则视为无效设置。
     - `startEndConfig.itemClass`: 选择的时间区间中的日期的className,用户可设置为其他值以改变样式，默认为"startenditem"。
     - `startEndConfig.exceedDuration(num,item)`: 用户选择的2个时间区间大于该值时会触发此函数，选择的区间不会生效，回调函数包含2个参数。item表示用户第二次选择的日期元素，num表示用户选择的区间所包含的日期个数。
    

    默认配置

     {
         duration: 10000000,
         itemClass: "startenditem"
     }
    

    demo

    var d = new Date();
    // ......
    startEndConfig:{
         allowStartDate:new Date("2016-"+(d.getMonth()+1)+"-01"),
         allEndDate:new Date("2016-"+(d.getMonth()+1)+"-28"),
         duration:20,
         itemClass:"startenditem",
         exceedDuration:function(duration,item){
             alert("你选择的日期个数超标，共"+duration+"个日期");
         }
     }
    

  • config.selectDateCallback(el, dateInfo)

    类型： Function

    说明： 选中某个日期时的回调，注意：只有当前日期可被选中时才会执行。回参包括被选中的DOM元素，dateInfo为json对象，结构如下{date:日期对象，dateStr：符合config.dataFormat格式的日期字符串}。

    默认值: 空。

  • config.selectMonth(instance, monthAndYear, offset)

    类型： Function

    说明： 切换月份时的回调函数，注意在初始化日历时也会被调用。回参包括日历实例instance，instance对象可调用其方法，详见下方方法说明。monthAndYear为json对象，包含年份及月份信息，结构为：{month:月份，year：年份}。offset为月份变动值，为1表示向往后推进一个月，-1表示向以前推进一个月，0表示初始化。

    默认值： 空。

  • config.displayChange(showOrhide)

    类型： Function

    说明： 用户关闭或者显示日历时始终会执行的函数，如果设置了show或者hide方法的回调，则此方法会在回调方法之后再执行；showOrhide表示刚刚执行的动作，true即表示执行了显示日历操作，false表示执行了关闭日历的操作。

    默认值： 空。

  • config.unSelectable(target)

    类型： Function

    说明： 点击了不可选的日期时的回调函数，主要用于指定了点击区域或者某些日期情况下的提示， target为用户点击的日期。

    return： 此函数需要设置返回值，当unSelectable返回true时，点击日期后日历会根据config.autohide来进行显示或者隐藏；返回为false时，点击日期后日历保持原状，即不会隐藏。如不设置返回值，默认返回false。

    默认值： 空。

2. futuCalendar#show(callback)

说明： 全局方法，显示日历,实例化日历时默认不显示，可调用此方法来显示，

参数： 显示日历时的回调函数，回调函数的参数为日历实例，

return： this，当前日历实例，

demo:

cal.show(function(instance){
    console.log("这是日历对象",instance);
});

3. futuCalendar#hide(callback)

说明： 全局方法，隐藏日历，

参数： 显示日历时的回调函数，回调函数的参数为日历实例，

return： this，当前日历实例，

demo:

cal.hide(function(instance){
    console.log("这是日历对象",instance);
});

4. futuCalendar#getDateInfo()

说明： 全局方法，获取当前选择的日期

return： JSON对象，日期信息，分两种情况

• 当config.startEndSelect为false（默认为false）时，返回的值为选中的单个日期信息。格式为{date:Date对象，dateStr：符合option.dataFormat格式的时间字符串}； 如：

• 当config.startEndSelect为true（即用户选择的为时间段）时，返回的是时间段信息。格式为{date:[开始时间对象,结束时间对象],ateStr：符合option.startEndDataFormat格式的时间字符串} 如：

5. futuCalendar#goLastMonth(callback)

说明： 切换到上一个月的日历信息

参数： 切换后的回调函数，回调函数的参数为日历实例，

return： this，当前日历实例，

demo:

cal.goLastMonth(function(instance){
    console.log("你切换到了上个月，这是日历对象",instance);
});

6. futuCalendar#goNextMonth(callback)

说明： 切换到下一个月的日历信息

参数： 切换后的回调函数，回调函数的参数为日历实例，

return：this，当前日历实例，

demo:

cal.goLastMonth(function(instance){
    console.log("你切换到了下个月，这是日历对象",instance);
});

7. futuCalendar#setDate(date, callback)

说明： 设置日历的日期，即设置那一天被选中

参数： date为Date对象或者可以被实例化为Date对象的变量，callback为切换后的回调函数，回调函数的参数为日历实例，

return： this，当前日历实例，

demo：

cal.setDate(date，function(instance){
    console.log("你切换到日期，这是日历对象",instance);
});

8. futuCalendar#setCliableList(list,callback,showRightNow)

说明： 重新设置可以点击的日期，会覆盖enableList中的配置

参数： list为日期数组，如["2016-12-01","2016-12-02"]或者[new Date("2016-12-01")],数组中元素需要可以实例化为Date对象;callback为回调函数，函数参数为数组中日期所对应的日期DOM元素；showRightNow表示设置完成之后是否理解显示日历，默认不显示；showRightNow为true时则设置完成之后立即显示日历。

demo：

// 设置"2016-09-22","2016-09-23"可点击，并将对应dom字体颜色设置为red,并且立即显示；
cal.setCliableList(["2016-09-22","2016-09-23"],function(item){
    item.style.color = "red";
},true);

9. futuCalendar#getItemIndexByDate(date)

说明： 根据日期获取指定元素的索引

参数： date为Date对象或者可以被实例化为Date对象的变量。

return： Number,返回该日期在42个日期元素中的索引。

10. futuCalendar#getItem(date)

说明： 根据日期或者索引获取指定元素

参数： 当date为日期时，如果当前日期未在当前日历上显示，则返回空；当date为数值时，则返回42个日期元素中的指定dom元素。 return： Element,对应的日期DOM元素

11. futuCalendar#setSEPoints(startDate,endDate,callback,showEndMonth)

**说明：**在开启选取起始点功能时，设置指定起始点间的日期被选中,注意，此时会限制于config.startencconfig中的设置,否则会抛出异常

参数： startDate为时间段的起始日期，endDate为结束日期，startDate和endDate为Date实例或者可以实例化为Date对象的变量（时间戳或者日期字符串），callback为设置之后的回调函数，回调函数参数为当前日历实例。showEndMonth:设置起始日期之后，是否显示当前日历为结束月的日历；true时显示设置的结束日期所在月的日历，false时显示开始时间所在月的日历。

return： this，当前日历实例，

demo：

var d = new Date();
instance.setSEPoints(d,+d + 6*24*3600*1000,function(instance){
    alert("耶，您成功选择了最近一周的日期");
});

日历日期元素样式重写指引

1. 组件提供的默认样式保存在/src/ui-mlcalendar.css中，用户亦可以自己进行覆盖重写相关样式。

2. 不同状态的日期元素说明

   

   ① :日期属于上月或者下月时的样式，样式选择器为：.futu-calendar .regular-date li.othermonth span

   ②，⑤：选择时间段时标志起始时间点的样式，选择器为：.futu-calendar .regular-date li.startendflag span

   ③: 时间段内日期的样式，用户可以通过'config.startEndconfig.itemClass'指定该元素的class, 以便更方便重写样式,默认的样式选择器为： .futu-calendar .regular-date li.startenditem span

   ④，⑥：在只有一部分日期能选择时，用于标志可以被点击的日期的样式，选择器为：.futu-calendar .regular-date li.selectable span

   ⑦：单选日期时，被选中的日期的样式，样式选择器为：.futu-calendar .regular-date li.selected span

   ⑧： 普通日期，样式选择器为：.futu-calendar .regular-date ul li span

demo:

.futu-calendar .regular-date ul li span{
    font-size: 100%;
    background-color:white;
}
/* 可选日期 */
.futu-calendar .regular-date li.selectable span{
    background-color: green;
    color: white;
}
/* 被选中的日期 */
.futu-calendar .regular-date li.selected span{
    background-color: pink;
    color: white;
}
/* 其他月份 */
.futu-calendar .regular-date li.othermonth span{
    background-color: gray;
    color: white;
}
/*起始日期间的日期*/
.futu-calendar .regular-date li.startenditem span{
    background-color: red;
    color: white;
}
/* 起始日期 */
.futu-calendar .regular-date li.startendflag span{
    background-color: orange;
    color: white;
}

更多样式情况请直接通过元素定位工具进行查找即可。

开发

1. 源码位于src/index.js，开发完成后在ui-mcalendar目录下运营gulp命令，生成根目录下的index.js。
2. 实例项目examples中，使用script标签的方式引入，可直接运行。
3. 依赖underscore.js,开发过程中已进行打包，无需重复引入。
4. 在ui-mcalendar目录下运行 $ npm start命令即开启一个http-server。

版本记录

1.2.2,1.2.3 2017-05-10

• bug修复，存在mask时，日历显示，底部html页面将无法滚动

1.2.1 2017-01-19

• 修复选择跨年日期段的显示问题

1.2.0 2016-12-23

• 代码健壮，不直接使用通过配置传入的日期对象，而是重新实例化
• 增加组件的异常提示

1.1.9 2016-11-14

• 增加参数用于设置时间段时，显示的是开始月还是结算月

1.1.8 2016-11-11

• 增加参数用于设置时间段时，显示的是开始月还是结算月

1.1.7 2016-11-10

• 修复重复选择时间段时日期不被选中的问题

1.1.6 2016-11-02

• 增加参数用于自定义工具栏模板
• 其他细节改进

1.1.5 2016-10-27

• 选择时间段时，增加参数startEndConfig.defaultStartEnd,用于设置默认选则的时间段
• 修复在没有设置startEndConfig.allowStartDate,startEndConfig.allEndDate时选择时间段不成功的问题
• 解决IOS闪烁效果
• 解决IOS上日期排序不准确的问题

1.1.3 2016-10-24

• 修正readme样式
• 增加点击了不可选日期时的回调

1.1.2 2016-10-20

• 增加displayChange配置方法，当用户显示或者关闭日历时始终会执行的方法

1.1.1 2016-10-19

• 优化样式，防止被外部样式覆盖

1.1.0 2016-10-14

• 新增选择时间段功能
• 其他代码优化

1.0.10 2016-09-30

• 解决document.children属性不兼容的问题，使用childNode兼容

1.0.9 2016-09-27

• 处理forEach不兼容的问题，使用underscore的each方法代替
• 扩展setCliableList参数以便于用户设置日历是否立即可见

1.0.8 2016-09-26

• 使用click代理tap事件，解决点击击穿问题

1.0.7 2016-09-23

• 解决gulpfile错误

1.0.6 2016-09-23

• 使用click代理tap事件，解决点击击穿问题

1.0.5 2016-09-23

• 修正readme文件

1.0.4 2016-09-23

• 提供了打包了css的版本

1.0.3 2016-09-23

• 修复bug，增加配置参数

1.0.2 2016-09-22

• 修复bug，增加配置参数

1.0.0 2016-09-22

• 初始化版本，完成代码及文档