CLNDR.js中文文档

by · 2016年01月01日 · 3157 Words · ~7min reading time | Improve on

原文链接： CLNDR.js中文文档

CLNDR 是一个jQuery日历插件。由于缺少真正动态的前端日历插件，无奈之下，创作了CLNDR。

查看demo: kylestetz.github.io/CLNDR/

下载
依赖
- 使用Bower
- 结合Angular使用
引言：标签由你来定
- days 数组
- 传入你的事件
使用
- 多天事件
- 限制和Datepickers
- 返回实例/API
- Template Requirements
配置
- 模板渲染引擎
- 国际化
- Underscore 模板定界符
- IE 兼容问题

##下载

开发环境 ~ clndr.js
生产环境 ~ clndr.min.js

##依赖
CLNDR依赖jQuery和Moment.js。默认情况下，CLNDR尝试使用Underscore 的_.template()函数，不过，如果你指定了自定义的渲染函数（下文有介绍），Underscore就不必要了。

因为和Underscore的API一致，Lo-Dash的_.template()函数也能正常工作。可以用Lo-Dash代替underscore。

###使用Bower
你可以通过Bower安装CLNDR：

bower install clndr

默认情况下没有安装Underscore。这允许你使用任何想用的渲染引擎。如果你想通过underscore使用默认的模板选项，安装underscore即可

bower install underscore

###结合Angular使用
如果你想把CLNDR集成到一个使用Angular的站点，通过指令angular-clndr开始.

##引言：标签由你来定
有很多美妙的并且功能强大的日历模块，它们有个相同的问题就是：它们给你定义了标签（和一堆js）,你不得不work with and style。这导致了很多的hacking, pushing, pulling,和烦人的‘为什们我不能做我想要的’场景

CLNDR不产生标签（好吧，它是有一些默认标签，但这不是一码事）。相反，CLNDR要求你创建template，它会给你的模板提供一系列对象，只需几行代码，这些对象就可以让你做出你想要的。

###days 数组
下面是一个典型的CLNDR模板。由控制部分和网格部分组成。

<div class="clndr-controls">
  <div class="clndr-previous-button">&lsaquo;</div>
  <div class="month"><%= month %></div>
  <div class="clndr-next-button">&rsaquo;</div>
</div>
<div class="clndr-grid">
  <div class="days-of-the-week">
    <% _.each(daysOfTheWeek, function(day) { %>
      <div class="header-day"><%= day %></div>
    <% }); %>
    <div class="days">
      <% _.each(days, function(day) { %>
        <div class="<%= day.classes %>"><%= day.day %></div>
      <% }); %>
    </div>
  </div>
</div>

days 数组包含着做一个日历所需的绝大部分信息，它的结构大致如下：

{
  day: 5,
  classes: "day",
  events: [],
  date: moment("2013-05-29")
}

通过它可以快速的创建出日历网格。days.classes会根据不同的情形包含额外的类名：如果某个日期是今天，则会包含today类。event类也是同样，如果某天带有事件，则会包含event类

###传入你的事件
CLNDR接受对象数组格式的事件：

events = [
  { date: "YYYY-MM-DD or some other ISO Date format", and: "anything else" }
]

CLNDR会遍历事件数组，查找date属性，除非你指定了，否则它将使用dateParameter选项。在你的模板中，days数组会自动包含这些事件对象。查看demo，看看events如何填充days数组。

##使用
CLNDR依赖underscore.js 和moment.js(除非你使用了另外的渲染引擎，那样的话underscore就不需要了)。确保在<head>标签里引入clndr.js之前引入这些依赖，当然别忘了jQuery。

最少代码如下（CLNDR包含一个默认的模板）

$('.parent-element').clndr();

所有的可配置项：

$('.parent-element').clndr({

  // 模板可以保存在script标签里。<script type="text/template"></script>
  // 或者以字符串形式引入
  template: clndrTemplate,

  // 设置一周的开始，0为周日开始，1为周一开始，默认是周日。
  weekOffset: 0,

  // 设置初始的月份，值为日期字符串或者moment对象
  startWithMonth: "YYYY-MM-DD" or moment(),

  // 设置星期的缩写，如果你设置moment.js为不同的语言，它会自动推断。
  // 如果因为某些原因，不能正常推断，用它手动设置。
  // 这个数组必须以周日开始（结合weekOffset使用可以改变成以周一开始）
  daysOfTheWeek: ['D', 'L', 'M', 'M', 'J', 'V', 'S'],

  // CLNDR会寻找目标类名来绑定事件
  // 下面是默认的：
  targets: {
    nextButton: 'clndr-next-button',
    previousButton: 'clndr-previous-button',
    nextYearButton: 'clndr-next-year-button',
    previousYearButton: 'clndr-previous-year-button',
    todayButton: 'clndr-today-button',
    day: 'day',
    empty: 'empty'
  },
  // 点击事件的回调函数! 在所有的回调函数中， `this` 指向clndr实例
  clickEvents: {
    // fired whenever a calendar box is clicked.
    // returns a 'target' object containing the DOM element, any events,
    // and the date as a moment.js object.
    click: function(target){ },
    // 用户点击下个月时触发
    // 返回一个设置为下个月的moment对象
    nextMonth: function(month){ },
    // 用户点击上个月时触发
    // 返回一个设置为上个月的moment对象
    previousMonth: function(month){ },
    // 用户点击明年时触发
    // 返回一个设置为明年当前月的moment对象
    nextYear: function(month) { },
    // 用户点击去年时触发
    // 返回一个设置为去年当前月的moment对象
    previousYear: function(month) { },
    // 点击导致月份发生变化时触发
    // 返回一个设置为正确月份的moment对象
    onMonthChange: function(month) { },
    // fires any time the year changes as a result of a click action.
    // if onMonthChange is also set, it is fired BEFORE onYearChange.
    // returns a moment.js object set to the correct month and year.
    //点击导致年份变化时触发，如果同时设置了onMonthChange，那么它将先于onYearChange触发，返回一个设置为正确年月的moment对象。
    onYearChange: function(month) { },
    // fired when a user goes to the current month & year.
    // returns a moment.js object set to the correct month.
    //当用户回到当前年月时触发，返回一个设置为正确月份的moment对象
    today: function(month){ }
  },

  // this is called only once after clndr has been initialized and rendered.
  // use this to bind custom event handlers that don't need to be re-attached
  // every time the month changes (most event handlers fall in this category).
  // hint: this.element refers to the parent element that holds the clndr,
  // and is a great place to attach handlers that don't get tossed out every
  // time the clndr is re-rendered.
  //该方法只会在clndr初始化并且渲染完成后调用一次，用它来绑定自定义事件处理器（适用于那些当月份变化时不用重新绑定的事件处理器，大部分事件处理器都属于这一类），提示：this.element 引用承载clndr的父元素，这是一个绑定事件的好地方，因为它不会再clndr重新渲染时被销毁。
  ready: function() { },
  // a callback when the calendar is done rendering.
  // This is a good place to bind custom event handlers
  // (also see the 'ready' option above).
  //当clndr渲染完成时的回调函数。同样是用来绑定自定义事件处理器。
  doneRendering: function(){ },

  // 事件对象的数组
  events: [],
  // if you're supplying an events array, dateParameter points to the
  // field in your event object containing a date string.
  // It's set to 'date' by default.
  //如果你提供了一个事件数组，dateParameter指向了你事件对象里包含时间的域，默认是date
  dateParameter: 'date',
  // show the numbers of days in months adjacent to the current month
  // (and populate them with their events). defaults to true.
  // CLNDR can accept events lasting more than one day!
  // just pass in the multiDayEvents option and specify what the start and
  // end fields are called within your event objects. See the example file
  // for a working instance of this.
  multiDayEvents: {
    startDate: 'startDate',
    endDate: 'endDate'
  },

  // show the dates of days in months adjacent to the current month.
  // defaults to true.
  showAdjacentMonths: true,
  // when days from adjacent months are clicked, switch the current month.
  // fires nextMonth/previousMonth/onMonthChange click callbacks. defaults to false.
  adjacentDaysChangeMonth: false,
  // always make the calendar six rows tall (42 days) so that every month has a
  // consistent height. defaults to 'false'.
  forceSixRows: false,

  // anything you want access to in your template
  extras: { }

  // if you want to use a different templating language, here's your ticket.
  // Precompile your template (before you call clndr),
  // pass the data from the render function into your template,
  // and return the result. The result must be a string containing valid markup.
  // The keyword 'this' is set to the clndr instance
  // in case you need access to any other properties.
  // More under 'Template Rendering Engine' below.
  render: function(data){
    return '<div class="html data as a string"></div>';
  },

  // if you want to prevent the user from navigating the calendar outside
  // of a certain date range (e.g. if you are making a datepicker), specify
  // either the startDate, endDate, or both in the constraints option. You
  // can change these while the calendar is on the page... See documentation
  // below for more on this!
  constraints: {
    startDate: '2017-12-22',
    endDate: '2018-01-09'
  }
});

在你的模板里，你可以使用的变量如下：

// day-of-the-week 缩写的数组,
// shifted as requested using the weekOffset parameter.
daysOfTheWeek: ['S', 'M', 'T', etc...]
// the number of 7-block calendar rows,
// in the event that you want to do some looping with it
numberOfRows: 5
// the days object, documented in more detail above
days: [ { day, classes, id, events, date } ]
// the month name- don't forget that you can do things like
// month.substring(0, 1) and month.toLowerCase() in your template
month: "May"
// the year that the calendar is currently focused on
year: "2013"
// all of the events happening this month
eventsThisMonth: [ ],
// all of the events happening last month
eventsLastMonth: [ ],
// all of the events happening next month
eventsNextMonth: [ ],
// anything you passed into the 'extras' property when creating the clndr
extras: { }

###多日事件
CLNDR现在可以接受持续多天的时间。你只需告诉它如何得到事件的开始和结束日期。

var lotsOfEvents = [
  { start: '2013-11-04', end: '2013-11-08', title: 'Monday to Friday Event' },
  { start: '2013-11-15', end: '2013-11-20', title: 'Another Long Event' }
];

$('#calendar').clndr({
  events: lotsOfEvents,
  multiDayEvents: {
    startDate: 'start',
    endDate: 'end'
  }
});

##配置
###模板渲染引擎
###国际化
Clndr对国际化支持的程度与Moment.js是一致的。
###Underscore模板定界符
如果你不喜欢<% %>和<%= %>风格的定界符，你可以正则表达式的形式给Underscore.js提供替代方案。
interpolate：输出字符串(默认是<%= %>)
escape：用来escaping html (默认是<%- %>)
evaluate：用来执行javascript(默认是<% %>)
如果你更习惯Jinja2/Twig/Nunjucks风格的定界符，只需在实例化你的clndr之前先调用下面的代码

// switch to Jinja2/Twig/Nunjucks-style delimiters
_.templateSettings = {
  interpolate: /\{\{(.+?)\}\}/g,
  escape: /\{\{\-(.+?)\}\}/g,
  evaluate: /\{\%(.+?)\%\}/g
};

###IE兼容问题
如果你打算支持IE8或更低，你需要注意版本问题。

CLNDR.js中文文档

分类

标签云