在日历上能够让用户直观了解日常安排并进行规划。ZUI提供了实用简单的日历插件。

实例

在下面的示例中展示了按月展示的日程安排。点击日历上方的操作按钮切换月份,拖动日历中的事件到其他位置来重新安排时间。

按周或查看某一天的日程视图将在后续版本中到来。

<!-- HTML 代码 -->
<div id="calendar" class="calendar"></div>

/* JS 代码 */
$('#calendar').calendar();

使用方法

启动参数

参数 说明
startView
  • "month" (默认),月份视图
起始视图,默认为月份视图
startDate
  • "today" (默认),其实日期为当天
  • "2014-8-14",表示日期的字符串
  • 一个Date实例
起始视图所在的日期
limitEventTitle
  • true (默认)
  • false
是否限制事件标题长度,如果为true则会限制事件标题在一行显示,超出部分将隐藏
storage
  • true (默认)
  • false
是否启用本地存储来增强体验,如果为ture则会记录用户所在的视图和日期,刷新或关闭浏览器再次访问会重现最后的视图
withHeader
  • true (默认)
  • false
是否显示带操作栏的头部,如果为true则会显示头部,包含切换视图或日期的按钮
dragThenDrop
  • true (默认)
  • false
是否启用事件拖放功能,如果为true则能够拖拽一个事件到另一个日期方框内来更改事件日程
lang
  • null (默认)
  • "zh-cn"
当前界面所使用的语言,如果留空则会从html标签上读取lang属性
data {calendars: {}, events: []} 初始加载的日历数据

方法

日历插件提供一组方法来向日历添加新的时间、更改已有事件或者删除已有事件。

获取日历对象实例

要使用日历对象方法,需要首先获取日历对象实例。每一个日历对象示例的引用都存储在对应的jQuery对象的data中,名称为zui.calendar

/* 获取日历对象实例 */
var calendar = $('#calendar').data('zui.calendar');
切换或刷新视图

要切换不同的视图或所显示的日期范围,请使用日历对象的display(view, date)方法。

/* 切换视图或刷新视图 */
var calendar = $('#calendar').data('zui.calendar');
calendar.display('month', '2014-8-14');   // 切换视图为月份视图,并将日期范围限定为2014年8月
calendar.display('month');                // 切换视图为月份视图,使用当前日期范围
calendar.display();                       // 重新刷新当前视图
增加事件
增加一个事件

将一个新的事件对象作为参数来调用addEvents方法。

/* 增加一个事件 */
var calendar = $('#calendar').data('zui.calendar');
var newEvent = {title: '吃饭了', desc: '要吃更多', start: '2014-8-14 12:00', end: '2014-8-14 13:00'};
calendar.addEvents(newEvent);
增加多个事件

将包含一组事件的数组作为参数调用addEvents方法则可以一次性添加多个事件。

/* 增加多个事件 */
var calendar = $('#calendar').data('zui.calendar');
var newEvents =
[
  {title: '吃饭了', desc: '要吃更多', start: '2014-8-14 12:00', end: '2014-8-14 13:00'},
  {title: '学习了', desc: '要学更多', start: '2014-8-14 13:00', end: '2014-8-14 17:00'}
];
calendar.addEvents(newEvents);
事件对象

事件对象实例可以指定以下属性:

属性 说明
title 字符串 事件标题
desc 字符串, 可选 事件描述
allDay
  • true
  • false (默认)
是否为全天事件
start
  • "2014-8-14",表示日期的字符串
  • 一个Date实例
事件开始的时间
end
  • "2014-8-14",表示日期的字符串
  • 一个Date实例
事件结束的时间,如果allDay属性为true(即为全天事件)时该属性可选
calendar 字符串,可选 事件所在的日历
data 任何值 一个额外的属性用来存储其他与该事件关联的数据
移除事件

指定需要移除的事件的id属性,或者同时指定多个id并放在一个数组中作为参数来调用removeEvents方法。

/* 移除事件 */
var calendar = $('#calendar').data('zui.calendar');
calendar.removeEvents('4343');                   // 移除id为4343的事件
calendar.removeEvents(['4343', '4344', '4345']); // 一次性移除多个事件
更新事件
更新事件属性

将更新对象或者由包含更新对象的数组作为参数来调用方法updateEvents

/* 移除事件 */
var calendar = $('#calendar').data('zui.calendar');
calendar.updateEvents(    // 更新一个事件
{
    event: '343', // 要更新的事件
    changes:
    [
       {
          change: 'title',          // 要更改的属性名称,
          to:     '一个新的事件标题'  // 更改后的值
       },
       {                            // 同时更改另一个属性
          change: 'start',          // 要更改的属性名称,
          to:     '2014-8-15 9:00'  // 更改后的值
       }
    ]
});
calendar.updateEvents(    // 一次性更新多个事件
[
    {
        event: '343', // 更新第一个事件
        changes:
        [
           {
              change: 'title',          // 要更改的属性名称,
              to:     '一个新的事件标题'  // 更改后的值
           },
           {                            // 同时更改另一个属性
              change: 'start',          // 要更改的属性名称,
              to:     '2014-8-15 9:00'  // 更改后的值
           }
        ]
    },
    {
        event: '344', // 更新另一个事件
        changes:
        [
            // ...
        ]
    },
]);
增加日历
增加一个日历

将一个新的日历对象作为参数来调用addCalendars方法。

/* 增加一个日历 */
var calendar = $('#calendar').data('zui.calendar');
var newCalendar = {name: 'work', title: '工作', desc: '这是一个工作日历', color: '#ff0000'};
calendar.addCalendars(newCalendar);
增加多个日历

将包含一组日历的数组作为参数调用addCalendars方法则可以一次性添加多个日历。

/* 增加多个日历 */
var calendar = $('#calendar').data('zui.calendar');
var newCalendars =
[
  {name: 'work', title: '工作', desc: '这是一个工作日历', color: '#ff0000'},
  {name: 'home', title: '家庭', desc: '这是一个家庭日历', color: '#00ff00'}
];
calendar.addCalendars(newCalendars);
日历对象

日历对象实例可以指定以下属性:

属性 说明
name 字符串,为全英文标识 日历名称
title 字符串,可选 日历标题
desc 字符串, 可选 日历描述
color 表示十六进制颜色值的字符串,可选 日历颜色
获取和同步数据

当进行日历事件的添加、更新或者移除操作时注意同步数据。

你随时可以获取当前所有日历或事件的数据。

/* 获取日历数据 */
var calendar  = $('#calendar').data('zui.calendar');
var calendars = calendar.calendars; // 获取所有日历对象实例
var events    = calendar.events;    // 获取所有事件对象实例

当前获取了日历事件数据后可以手动直接更改所有属性,不过需要调用display()方法才能够将更改应用到界面中。

事件

日历中的事件既可以使用jQuery原生方法来绑定,也可以写在启动参数中。

事件名称 jQuery事件名称 说明 特别的事件参数
clickTodayBtn "clickTodayBtn.zui.calendar" 点击日历头部的当天按钮时发生
clickNextBtn "clickNextBtn.zui.calendar" 点击当前视图下一个日期范围按钮时发生
clickPrevBtn "clickPrevBtn.zui.calendar" 点击当前视图上一个日期范围按钮时发生
clickEvent "clickEvent.zui.calendar" 当点击一个事件时发生
  • event.element 获取当前点击的DOM对象实例
  • event.event 事件对象实例,当前点击的事件对象实例
  • event.events 事件对象实例数组,当前所有事件
beforeAddCalendars "beforeAddCalendars.zui.calendar" 在向日历添加一个新的日历之前发生,如果在该事件处理函数中返回false,则会取消添加
  • event.newCalendar 新的日历对象实例
  • event.data 所有日历事件数据
addCalendars "addCalendars.zui.calendar" 在向日历添加一个新的日历之后发生
  • event.newCalendars 所有新的日历对象实例
  • event.data 所有日历事件数据
beforeAddEvent "beforeAddEvent.zui.calendar" 在向日历添加一个新的事件之前发生,如果在该事件处理函数中返回false,则会取消添加
  • event.newEvent 新的事件对象实例
  • event.data 所有日历事件数据
addEvents "addEvents.zui.calendar" 在向日历添加一个或多个新的事件之后发生
  • event.newEvents 所有新的事件对象实例
  • event.data 所有日历事件数据
beforeRemoveEvent "beforeRemoveEvent.zui.calendar" 在向日历移除一个事件之前发生,如果在该事件处理函数中返回false,则会取消移除
  • event.event 需要移除的事件对象实例
  • event.eventId 需要移除的事件id
  • event.data 所有日历事件数据
removeEvents "removeEvents.zui.calendar" 在向日历移除一个或多个事件之后发生
  • event.removedEvents 所有需要移除的事件对象实例
  • event.data 所有日历事件数据
beforeChange "beforeChange.zui.calendar" 更改一个事件之前发生,如果在该事件处理函数中返回false,则会取消本次更改
  • event.event 要更改的事件对象实例
  • event.change 要更改的属性名称
  • event.from 更改之前该属性的值
  • event.to 更改之后新的值
change "change.zui.calendar" 当一个或多个事件发生更改时发生
  • event.data 所有日历事件数据
  • event.changes 数组,所有更改明细,每一项包含下列属性:
    • event.event 要更改的事件对象实例
    • event.change 要更改的属性名称
    • event.from 更改之前该属性的值
    • event.to 更改之后新的值
beforeDisplay "beforeDisplay.zui.calendar" 在重新显示视图之前发生,如果在该事件处理函数中返回false,则会取消显示
  • event.view 字符串,要显示的视图名称
  • event.date 日期事件对象实例,要显示的日期
display "display.zui.calendar" 在重新显示视图之后发生
  • event.view 字符串,要显示的视图名称
  • event.date 日期事件对象实例,要显示的日期
clickCell "clickCell.zui.calendar" 当点击一个日期单元格时发生
  • event.element 获取被点击的单元格实例
  • event.view 字符串,当前视图名称
  • event.date 日期事件对象实例,当前单元格的日期
使用启动参数处理事件
$('calendar').calendar(
{
    clickEvent: function(event)
    {
        console.log(event);
        // console.log("你点击了一个事件");
        // 处理 clickEvent 事件
        // ...
    }
});
使用jQuery方法绑定事件处理函数
$('calendar').calendar().on("clickEvent.zui.calendar", function(event)
{
    console.log(event);
    // console.log("你点击了一个事件");
    // 处理 clickEvent 事件
    // ...
});