Calendar 多功能日历组件

Calendar 可以实现一月、多月和整年日历功能，支持日期单选、周选和范围选择，可通过数据接口显示农历和特殊工作日、休息日，还可以与其他组件进行组合应用。日历组件也适配移动端。

使用

Calendar 组件及其依赖库或组件列表如下：

• root.js 基本库
• Animation 动画库 root.animation.js
• DateTime 日期时间类 root.datetime.js
• Calendar 组件默认样式 root.calendar.css
• 需要两个iconfont图标，在root.calendar.iconfont.css中。
• 如果要显示农历，还需要自己做一个农历数据接口，农历数据文件为data目录下的calendar.csv

引用代码示例如下，可放在页面的任何地方，建议放在 HEAD 标签中：

<script type="text/javascript" src="/root.js"></script> <script type="text/javascript" src="/root.animation.js"></script> <script type="text/javascript" src="/root.input.js"></script> <script type="text/javascript" src="/root.datetime.js"></script> <script type="text/javascript" src="/root.calendar.js"></script> <link href="/css/root/calendar.css" rel="stylesheet" type="text/css" /> <link href="/css/root/iconfont.css" rel="stylesheet" type="text/css" />

如果需要显示农历和特殊工作日/休息日，还需要把日历数据放到数据库中，实现一个GET接口，核心语句如下：

SELECT concat(solar_year, '-', IF(solar_month < 10, '0', ''), solar_month, '-', IF(solar_day < 10, '0', ''), solar_day) AS solar, lunar_day, solar_term, festival, workday FROM qross_calendar WHERE solar_year IN (#{year}) -> TO NESTED MAP 'solar';

数据结构为：

{ "2020-09-20": { "lunar_day": "初四", "solar_term": "", "festival": "", "workday": -1 }, ... }

特殊工作日和休息日的管理设置参见 Master 管理平台中的“系统” -> “Keeper 监控” -> “工作日历”。

示例

和其他的组件一件，日历组件也通过自定义 HTML 标签实现，一般不需要写 Javascript 代码。唯一可能写代码的地方只有 事件，以下配合示例进行说明：

单月单选模式

```html <calendar id="calendar1"></calendar> ```

注意是 `<calendar></calendar>` 而不是 `<calendar />`，虽然标签之间没有任何东西。

日历中各个部分的文字如星期的文字均可设置，见下面属性说明。

INPUT 单选模式

```html ```

注意`type`属性一定要设置为`calendar`。

各个部分的样式如日期的字体大小均可自行设置，见下面的样式属性说明。

双月周选模式

```html ```

可通过日历属性获取已选中周的各项值，如第几周、开始日期、结束日期等。

INPUT 周选模式

```html ```

    选中的周：   开始日期：   结束日期：

可以通过事件参数或Calendar选择器获取选中的周、开始日期和结束日期。如

$('#calendar4').on('WeekSelected', function(year, weekOfYear, startDate, endDate) { $('#SelectedWeek').html = this.week; //返回选中的年和周，格式 yyyy-ww $('#WeekStartDate').html = $('#calendar4').get('start'); //返回选中周的开始日期，格式 yyyy-MM-dd $('#WeekEndDate').html = endDate; //返回选中周的结束日期，格式 yyyy-MM-dd //以上三种方式都可以得到选中的值，详见下面的属性说明 });

双月多选模式

<calendar id="calendar5" mode="range" days-of-other-month="hidden" months="2"></calendar>

INPUT 多选模式

<input type="calendar" name="calendar6" size="40" mode="range" months="2" days-of-other-month="hidden" init="0" />

可以通过 Calendar 的startDate和endDate属性获取选中的开始日期和结束日期。如

$calendar('calendar6').startDate; //返回选中的开始日期，格式`yyyy-MM-dd` $calendar('calendar6').endDate; //返回选中的结束日期，格式`yyyy-MM-dd`

日期时间选择框

<input id="calendar7" type="datetime" />

示例略。

整年模式

<calendar id="calendar8" mode="none" lunar="yes" holiday="yes" title-format="yyyy年" days-of-other-month="hidden" week-names="一,二,三,四,五,六,日" this-year-text="今年" month-names="一月,二月,三月,四月,五月,六月,七月,八月,九月,十月,十一月,十二月" corner-names="休,班" extension-api="/api/system/calendar?year=" months="12"></calendar>

示例略。

日期时间组合选择器

见 DateTimePicker 日期时间选择器组件。

标签和类

标签属性

标签属性可以在自定义标签 CALEDNAR 上进行设置。

基本设置

• id或name Calendar在页面上的唯一名称。
• mode Calendar日期的选择模式，可选值day、week、range、none，分别代表单选、周选、日期范围选择和仅事件模式，属性值不区分大小写。
• months 设置显示几个月的日历，默认值为1，如果设置为12，则显示整年日历。
• init 在多月模式下，初始月份的偏移值。例如在显示3个月的日历时，值为-1时默认显示上月、本月和下月，值为0显示本月、下月和下下月，值为-2显示上上月、上月和本月。
• first-day-of-week 每周的第一天是周几，默认周一，可选任意表示星期值，如MON、SUNDAY、星期二、周三、日、5等，如果是数字的话，0表示周日。

• days-of-other-month 是否在日历中显示其他月份的日期，可选值visible或hidden，默认为visible。每月日历都是6行7列，除当月的日期外，还会有部分上月和下月的日期，这个属性设置其他月的日期是否显示。

• quick-switch 是否启用快速切换，月历时点击月标题可快速切换年和月，年历时点击年标题可以快速切换年，默认为true。当可总年数小于4时或月数小于months+3时，这个属性会自动关闭。

• lunar 是否显示农历，默认false，需要扩展接口支持。作者没有使用农历算法进行转换，那个代码量要远远超过这个组件的代码本身。
• holiday 是否显示特殊工作日和特殊休息日（如法定节假日），默认false，需要扩展接口支持。

• extension-api 扩展接口地址，仅支持GET方式获取。接口数据已在压缩包中。仅lunar或holiday为true时才生效。

• icon 在INPUT模式下，会在输入框右侧显示一个图标，这个属性用来自定义图片地址或iconfont类名，如/images/calendar.png或icon-calendar。

• align 在INPUT模式下，日历弹出框的对齐方式，可选LEFT或RIGHT，即与输入框左侧对齐还是右侧对齐。没有居中对齐选项，真的不好看。

初始值

• min-date 设置允许选择的最小日期，格式yyyy-MM-dd，支持today关键字，默认值为1900-01-01。
• max-date 设置允许选择的最大日期，格式yyyy-MM-dd，支持today关键字，默认值为2100-12-31。
• date 在单选模式下，默认选中哪一天，格式yyyy-MM-dd，支持today关键字。
• week 在周选模式下，默认选中哪一周，格式yyyy-ww，ww代表周数，支持this-week关键词。
• start-date 在范围选择模式下，默认选中的开始日期，格式yyyy-MM-dd，支持today关键字。
• end-date 在范围选择模式下，默认选中的结束日期，格式yyyy-MM-dd，支持today关键字。

格式属性

• title-format 整年模式下，设置年份标题的格式，如yyyy年，默认为空，即不显示。
• head-format 单月或多月模式下，月历头的格式，默认yyyy-MM，如可以设置为yyyy年M月。
• value-format 单月单选模式下，返回值的格式，默认为yyyy-MM-dd，例如可以设置为yyyy/MM/dd。
• week-title 周选模式下，会有一列显示第几周，这个属性用来设置这一列的标题，默认值为Week，如可以设置为周。
• week-names 星期的表头名称，中文环境默认值一、二、三、四、五、六、日，其他语言环境默认值为Mon,Tue,Wed,Thu,Fri,Sat,Sun。
• month-names 年历模式下，每个月的月份名称，中文环境默认值为一月至十二月，其他语言环境默认值为January至December。
• corner-names 特殊工作日和特殊休息日（如法定节假日）的名称，中文环境默认值为班,假，其他语言环境默认值为W,R。

样式属性

样式属性一般不需要设置，可直接修改 calendar.css 中对应的样式即可。考虑到可能存在某些极端的情况，Calendar 提供了这些可设置样式的属性。或者要修改样式时可以根据说明去找。

• frame-class 整体日历框架的样式，默认值-calendar
• title-class 整个日历的标题框DIV样式，一般用于年历模式， 默认值-calendar-title
• title-text-class （年）标题文字样式， 默认值-calendar-title-text
• head-class 月历头样式，包含导航按钮和日历标题(年月)， 默认值-calendar-head
• nav-class 导航TABLE 框体样式，默认值-calendar-nav
• nav-month-button-class 月导航按钮（上一月/下一月）样式，默认值-calendar-nav-button
• nav-year-button-class 年导航按钮（上一年/下一年）样式，默认值-calendar-nav-year-button
• head-title-class 日历标题（年和月）样式，默认值-calendar-head-title
• body-class 日历主体DIV样式，默认值-calendar-body
• content-class 日历内容TABLE样式'，默认值-calendar-content
• corner-class 日历日期单元格的角标DIV样式（即特殊工作日和休息日），默认值-calendar-corner
• day-class 日期数字DIV样式，默认值-calendar-day
• lunar-class 农历文字样式，默认值-calendar-lunar
• today-class “今天”单元格TD样式，默认值-calendar-today
• holiday-class 休息日单元格TD样式，默认值-calendar-holiday
• workdayClass 工作日单元格TD样式，默认值-calendar-workday
• focus-day-Class 选中日期单元格TD样式，默认值-calendar-focus-day
• disabled-day-class 可选择日期区间外的日期样式，默认值-calendar-disabled-day
• days-of-other-month-class 月历中其他月的日期TD样式 -calendar-days-of-other-month
• focus-start-day-class 范围选择模式下选中的开始日期样式，默认值-calendar-focus-start-day
• focus-end-day-class范围选择模式下选中的结束日期样式，默认值也是'-calendar-focus-start-day'
• selection-day-class范围选择模式下选中的开始日期和结束日期之间的日期样式-calendar-selection-day
• week-head-class 周序号的表头TH样式，默认值-calendar-week-head
• week-name-class 周名称TH样式，默认值-calendar-week-name
• week-row-class 周选模式下默认的行TR样式，默认值-calendar-week-row
• week-focus-row-class 周选模式下选中行TR样式，默认值-calendar-week-focus-row
• week-of-year-class 周选模式下周数字TD样式，默认值-calendar-week-of-year
• week-of-year-focus-class 周选模式下选中状态下的周数字TD样式，默认值-calendar-week-of-year-focus
• foot-class 月历底部的DIV样式，默认值-calendar-foot
• foot-button-class 月历底部按钮BUTTON样式，如“今天”、“本月”等，默认值-calendar-foot-button
• switch-frame-class 快速切换年或月框体DIV样式，默认值-calendar-switch-frame
• switch-year-option-class 年快速切换框体中的年样式，默认值-calendar-switch-year-option
• switch-this-year-option-class 年快速切换框体中的今年样式，默认值-calendar-switch-this-year-option
• switch-year-checked-option-class 年快速切换框体中的选中年样式，默认值-calendar-switch-year-checked-option
• switch-year-head-class 月快速切换框体中的年份样式，默认值-calendar-switch-year-head
• switch-month-option-class 月快速切换框体中的月份选项样式，默认值-calendar-switch-month-option
• switch-this-month-option-class 月快速切换框体中的本月项样式，默认值-calendar-switch-this-month-option
• switch-month-checked-option-class 月快速切换框体中的选中月样式，默认值-calendar-switch-month-checked-option

样式属性的名称建议使用中横线连字符分隔的格式，不过去掉连字符也没什么问题。在使用 Javascript 操作这个 Calendar 对象时，可以通过camel格式属性进行调用 ，如focus-day-class对应属性focusDayClass，但是组件没有提供属性设置功能，如calendar.focusDayClass = 'other-class-name'是无效的。

选择器

因为属于自定义标签，不能通过原生的选择器如document.querySelector来操作这个标签。Calendar 对象提供了两种格式的选择器：

• $calendar('name') 这个选择器返回Calendar对象本身，然后可以访问Caldendar对象的属性、方法和事件。因为页面的加载顺序是页面加载完成 > 解析Calendar标签 > 通过$calendar选择，所以$calendar选择器要求在页面加载完成并且标签解析之后才能调用 ，一般放在$finish函数里面。如 $finish(function() { $calendar('name').date = '2020-09-21'; });
• $listen('name') 这个选择器主要用于为 Calendar 对象设置事件。 $listen('calendar1').on('DaySelected', function(day) { ... });

  当然也可以通过上一个选择器添加事件。

  $finish(function() { $calendar('calendar1').on('DaySelected', function(day) { ... }); $calendar('calendar1').onDaySelected = function(day) { ... }; });

  二者的区别是$listen无需要考虑页面是否加载完成，而$calendar必须在标签解析之后才能调用。

• 仍可以使用原生的选择器，但只支持按名选择，如$s('#Calendar1')、$a('#Calendar1,#Calendar2')。

类属性

在标签属性中已经介绍了很多属性，这些标签属性除了可以进行预设置外，都可以通过 Calendar 对象进行调用，不过标签属性在 Calenar 对象中大部分都是只读的。另外还有一些不是标签属性的 Calendar 对象属性。

几个重要的属性有：

• date 单选模式下获取或设置日历的选中日期，格式yyyy-MM-dd，可写
• startDate 范围选择模式下获取或设置选中的开始日期，格式yyyy-MM-dd，可写
• endDate 范围选择模式下获取或设置选中的结束日期，格式yyyy-MM-dd，可写
• week 周选模式下获取或设置日历的选中周，格式yyyy-ww，可写。注意在周选模式下，startDate和endDate可以获取值，表示选中周的开始日期和结束日期。
• year 当年日历中第一个月的年份，可写
• month 当前日历中第一个月的月份，可写
• minYear 最小可选择的年份，默认为1900，只读
• maxYear 最大可选择的年份，默认为2100，只读
• minMonth 最小可选择的月份，默认为1900-01，只读
• maxMonth 最大可选择的月份，默认为2100-12，只读

其他只读的需要在标签中进行设置且只读的属性有：

• name或id 获取日历在页面上的唯一名称
• mode 获取日历的选择模式，返回值有DAY、WEEK、RANGE和NONE
• months 获取日历同时可以显示几个月
• firstDayOfWeek 获取日历的第一天是周几
• daysOfOtherMonth 获取日历中其他月份的日期是否在显示，返回值有VISIBLE和HIDDEN
• minDate 获取可选择的最小日期，格式yyyy-MM-dd，默认值为1900-01-01
• maxDate 获取可选择的最大日期，格式yyyy-MM-dd，默认值为2100-12-31
• weekTitle 周选模式下周顺序号那一列的表头名称，默认值Week
• weekNames 周名称列表，默认值['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
• monthNames 月名称列表，年历的快速切换中使用，默认值['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
• cornerNames 工作日和休息日角标名称，默认值为['R', 'W']
• todayText “今天”的文字，默认为Today
• thisWeekText “本周”的文字，默认为This Week
• thisMonthText “本月”的文字，默认为This Month
• thisYearText “今年”的文字，默认为This Year
• quickSwitch 是否在显示快速切换，默认值为true
• lunar 是否在显示显示农历，默认值为false
• holiday 是否在显示特殊工作日和节假日角标，默认值为false
• extensionApi 扩展Api，用以读取农历和特殊工作日/休息日

另有所有的样式属性也都是只读的，不再一一列出。

方法

在 Calendar 对象中，私有方法居多，可用的方法比较少。

• getCell(date) 根据日期（格式yyyy-MM-dd）获取日历单元格，返回CalendarCell对象，见下面的说明。注意一定是可见的单元格。
• yearSwitchEnabled() 年模式下年快速切换是否可用，可用年数小于4时自动关闭。
• monthSwitchEnabled() 单月或多月模式下月快速切换是否可用，可用月数小于months+3时自动关闭，months为当前日历中可显示的月数。

事件

事件可以捕获用户对 Calendar 的操作。

• onNavPrevMonth 当月历导航到上一个月时触发，可传递参数prevMonth，参数格式为yyyy-MM。
• onNavNextMonth 当月历导航到下一个月时触发，可传递参数nextMonth，参数格式为yyyy-MM。
• onNavPrevYear 当年历导航到上一年时触发，可传递参数prevYear，格式为年份数字。
• onNavNextYear 当年历导航到下一年时触发，可传递参数nextYear，格式为年份数字。
• onDaySelected 单选模式下选中某一天时触发，可传递参数selectedDay，格式为yyyy-MM-dd。
• onDayClick 非选择模式下点击某一天时触发，可传递参数day，参数类型为CalendarCell。
• onWeekSelected 周选模式下选中某一周时触发，可传递4个参数：year, weekOfYear, startDate, endDate，其中year和weekOfYear是整数，startDate和endDate格式为yyyy-MM-dd，分别表示选中周的开始日期和结束日期。
• onRangeStartSelected 范围选择模式下，选中开始日期时触发，传递两个参数startDate、endDate。当没有结束时间选中时endDate为空。
• onRangeStartCanceled 范围选择模式下，取消选中开始日期时触发，传递参数endDate，当没有结束日期选中时endDate为空。
• onRangeEndSelected 范围选择模式下，选中结束日期时触发，传递两个参数startDate、endDate。
• onRangeEndCanceled 范围选择模式下，取消选中结束日期时触发，传递一个参数startDate
• onRangeSelected 范围选择模式下，选择了开始日期并选中了结束日期时触发，传递两个参数startDate、endDate
• onRangeCanceled 范围选择模式下，取消选择开始日期和结束日期时触发，无参数传递

另外还有一个事件onchange，当选择的日期改变时触发，目前仅适用于日期单选，和onDaySelected和onDayClick事件一起触发，但是相互独立。区别是onchange可以在属性中使用，其他的事件暂时不可以。

事件使用示例：

$listen('calendar1').on('WeekSelected', function(year, weekOfYear, startDate, endDate) { console.log(this.week); });

在事件函数中，this关键字指向当前 Calendar 对象

CalendarCell 类

CalendarCell 类主要用于操作每个日期项，比如设置角标、设置样式等，这个类的成员主要是属性。上面介绍过，通过 Calendar 对象的getCell(date)方法获取某个日期单元格，然后可以访问或设置这个单元格的各种属性。

• date 获取当前单元格的日期时间，DateTime类型，只读
• day 获取或设置当前单元格的日期数字，可写
• corner 获取或设置当前单元格的角标，可写
• lunar 获取或设置当前单元格的农历，可写
• className 获取或设置当前单元格的样式，可写
• dayClass 获取或设置当前单元格日期数字的样式，可写
• cornerClass 获取或设置当前单元格的角标样式，可写
• lunarClass 获取或设置当前单元格的农历样式，可写

通过这个类可以为日历添加更多的功能。

---

参考链接

• root.js 基础库
• Animation 动画库
• DateTime 日期时间类
• Clock 文字时钟组件
• Popup 弹出对话框组件