FullCalendar日歷插件說明文檔
阿新 • • 發佈：2017-06-05
short 不一定 tick name 當前日期 slot 內容 mmm get
FullCalendar提供了豐富的屬性設置和方法調用，開發者可以根據FullCalendar提供的API快速完成一個日歷日程的開發，本文將FullCalendar的常用屬性和方法、回調函數等整理成中文文檔，以供參閱。當前版本1.6.4。
普通顯示設置
| 屬性 | 描述 | 默認值 |
| header | 設置日歷頭部信息。 如果設置為false，則不顯示頭部信息。包括left，center,right左中右三個位置，每個位置都可以對應以下不同的配置： title: 顯示當前月份/周/日信息 prev: 用於切換到上一月/周/日視圖的按鈕 next: 用於切換到下一月/周/日視圖的按鈕 prevYear：用於切換到上一年視圖的按鈕 nextYear：用於切換到下一年視圖的按鈕 | { left: ‘title‘, center: ‘‘, right: ‘today prev,next‘ } |
| theme | 是否允許使用jquery的ui主題，如果設置為true，則需要加載jquery ui相關css和js文件。 查看演示 | false |
| buttonIcons | 設置header中使用的prev, next等變量對應按鈕的樣式，只有當theme為true時才有效，如果你調用了jQuery ui樣式但又不想使用它的圖標樣式，可以將此屬性設置為false | { prev: ‘circle-triangle-w‘, next: ‘circle-triangle-e‘ } |
| firstDay | 設置一周中顯示的第一天是哪天，周日是0，周一是1，類推。 | 0 |
| isRTL | 設置為ture時則日歷從右往左顯示，貌似是針對阿拉伯人設計的。 | false |
| weekends | 是否顯示周末，設為false則不顯示周六和周日。 | true |
| hiddenDays | 隱藏一周中的某一天或某幾天，數組形式，如隱藏周二和周五：[2,5]，默認不隱藏，除非weekends設置為false。 | [] |
| weekMode | 在月視圖裏顯示周的模式，因為每月周數可能不同，所以月視圖高度不一定。 fixed：固定顯示6周高，日歷高度保持不變 liquid：不固定周數，高度隨周數變化 variable：不固定周數，但高度固定 | ‘fixed‘ |
| weekNumbers | 是否在日歷中顯示周次(一年中的第幾周)，如果設置為true，則會在月視圖的左側、周視圖和日視圖的左上角顯示周數。 | false |
| weekNumberCalculation | 周次的顯示格式。 | "iso" |
| height | 設置日歷的高度，包括header日歷頭部，默認未設置，高度根據aspectRatio值自適應。 | |
| contentHeight | 設置日歷主體內容的高度，不包括header部分，默認未設置，高度根據aspectRatio值自適應。 | |
| aspectRatio | 設置日歷單元格寬度與高度的比例。 | 1.35 |
| handleWindowResize | 是否隨瀏覽器窗口大小變化而自動變化。 | true |
| windowResize | callback，當瀏覽器窗口變化時觸發function，使用： $(‘#calendar‘).fullCalendar({ windowResize: function(view) { alert(‘The calendar has adjusted to a window resize‘); } }); |
|
| render | method，綁定日歷到id上。 $(‘#id‘).fullCalendar(‘render‘); |
|
| destroy | method，銷毀id日歷，把日歷回復到初始化前狀態。 $(‘#id‘).fullCalendar(‘destroy‘); |
|
視圖
FullCalendar提供五種可用視圖，包括month（月視圖），basicWeek（基本周視圖，左側不顯示具體時間），basicDay（基本日視圖，左側不顯示具體時間），agendaWeek（周視圖），agendaDay（日視圖）。
View視圖對象的屬性：
| 屬性 | 描述 |
| name | 包括month,basicWeek,basicDay,agendaWeek,agendaDay |
| title | 標題內容(例如"2013年9月" or "Sep 7 - 13 2013") |
| start | Date類型, 該view下的第一天 |
| end | Date類型, 該view下的最後一天. 由於是一個閉合的值, 所以, 比如在month view下, 10月這個月份, 那麽end對應的應該是11月的第一天 |
| visStart | Date類型. 在該view下第一個可以訪問的day. month view下, 該值是當月的第一天, week view下, 則通常和start一致 |
| visEnd | Date類型, 最後一個可訪問的day |
View其他屬性和方法
| 屬性 | 描述 | 默認值 |
| defaultView | 日歷初始化時默認視圖 | ‘month‘ |
| getView | method，取得視圖對象信息，如獲取當前視圖的標題內容： var view = $(‘#calendar‘).fullCalendar(‘getView‘); alert("The view‘s title is " + view.title); |
|
| changeView | method，切換視圖 .fullCalendar(‘changeView‘,viewName) viewName為5種視圖中的一種 |
|
日程選項
以下選項設置適用於agendaWeek和agendaDay視圖裏。
| 屬性 | 描述 | 默認值 |
| allDaySlot | 在agenda視圖模式下，是否在日歷上方顯示all-day(全天) | true |
| allDayText | 定義日歷上方顯示全天信息的文本 | ‘all-day‘ |
| axisFormat | 設置日歷agenda視圖下左側的時間顯示格式，默認顯示如：5:30pm | ‘h(:mm)tt‘ |
| slotMinutes | 在agenda的視圖中, 兩個時間之間的間隔(分鐘) | 30 |
| defaultEventMinutes | 事件默認的時間執行長度，如果事件對象沒有指定執行多長時間，則默認執行兩個小時 | 120 |
| firstHour | 當切換到agenda時，初始滾動條滾動到的時間位置，默認在6點鐘的位置 | 6 |
| minTime | 設置顯示的時間從幾點開始 | 0 |
| maxTime | 設置顯示的時間從幾天結束 | 24 |
| slotEventOverlap | 設置視圖中的事件顯示是否可以重疊覆蓋 | true |
當前日期設置
| 屬性 | 描述 | 默認值 |
| year | 設置日歷年份，必須為4位如：2013，如果不設置則默認為當前年份 | |
| month | 設置初始化日歷的月份，從0開始，如果年份和月份都未指定，則從一月開始。 | |
| date | 設置日歷初始化時的日期，只有在周視圖和日視圖中有效 | |
| prev | method，進入到上一月（周、天）視圖 $(‘#calendar‘).fullCalendar(‘prev‘); |
|
| next | method，進入到下一月（周、天）視圖 $(‘#calendar‘).fullCalendar(‘next‘); |
|
| prevYear | method，進入上一年視圖 | |
| nextYear | method，進入下一年視圖 | |
| today | method，進入當天 | |
| gotoDate | method，指定進入日歷中的某一天 $(‘#calendar‘).fullCalendar( ‘gotoDate‘, year [, month, [ date ]] ) |
|
| incrementDate | method， 以當前時間為軸, 將日歷向前, 或向後移動指定長度的時間, 比如: $(‘#calendar‘).fullCalendar(‘incrementDate’, -3, 2, -5)就表示將日歷年份向前移動3年, 月份向後移動2月, day(天數)向前移動5天。 | |
| getDate | method，返回當前日歷中的日期 | |
文本與時間定制
你可以根據項目需求設置日歷顯示的文本信息，如中文的月份等。
| 屬性 | 描述 | 默認值 |
| timeFormat | 設置顯示的日程事件的時間格式，如timeFormat: ‘H:mm‘ 則顯示24小時制的像10:30 | {agenda: ‘h:mm{ - h:mm}} |
| columnFormat | 設置顯示日歷每列表頭信息的格式文本，默認： { month: ‘ddd‘, // Mon week: ‘ddd M/d‘, // Mon 9/7 day: ‘dddd M/d‘ // Monday 9/7 } |
見描述 |
| titleFormat | 設置用於顯示日歷頭部的文本信息，默認： { month: ‘MMMM yyyy‘, // September 2013 week: "MMM d[ yyyy]{ ‘—‘[ MMM] d yyyy}", // Sep 7 - 13 2013 day: ‘dddd, MMM d, yyyy‘ // Tuesday, Sep 8, 2013 } |
見描述 |
| buttonText | 設置日歷頭部各按鈕的顯示文本信息，默認： { prev: ‘?‘, // ? next: ‘?‘, // ? prevYear: ‘?‘, // ? nextYear: ‘?‘, // ? today: ‘today‘, month: ‘month‘, week: ‘week‘, day: ‘day‘ } |
見描述 |
| monthNames | 月份全稱，默認： [‘January‘, ‘February‘, ‘March‘, ‘April‘, ‘May‘, ‘June‘, ‘July‘, ‘August‘, ‘September‘, ‘October‘, ‘November‘, ‘December‘] |
見描述 |
| monthNamesShort | 月份名稱簡寫，默認：[‘Jan‘, ‘Feb‘, ‘Mar‘, ‘Apr‘, ‘May‘, ‘Jun‘ ‘Jul‘, ‘Aug‘, ‘Sep‘, ‘Oct‘, ‘Nov‘, ‘Dec‘] | 見描述 |
| dayNames | 星期全稱，默認：[‘Sunday‘, ‘Monday‘, ‘Tuesday‘, ‘Wednesday‘, ‘Thursday‘, ‘Friday‘, ‘Saturday‘] | 見描述 |
| dayNamesShort | 星期名稱簡寫，默認：[‘Sun‘, ‘Mon‘, ‘Tue‘, ‘Wed‘, ‘Thu‘, ‘Fri‘, ‘Sat‘] | 見描述 |
| weekNumberTitle | 周次，即一年中的第幾周 | "W" |
鼠標單擊和滑過
以下列出的是當鼠標單擊或者滑過日歷中的某個元素時，回調的函數callback。
| 屬性 | 描述 |
| dayClick | 當單擊日歷中的某一天時，觸發callback，用法： $(‘#calendar‘).fullCalendar({ dayClick: function(date, allDay, jsEvent, view) { do something... } }); date是點擊的day的時間(如果在agenda view, 還包含時間)，在月view下點擊一天時，allDay是true，在agenda模式下，點擊all-day的窄條時，allDay是true，點擊其他的agenda view下的day則為false，jsEvent就是一個普通的javascript事件，包含的是click事件的基礎信息。 |
| eventClick | 當點擊日歷中的某一日程（事件）時，觸發此操作，用法： $(‘#calendar‘).fullCalendar({ dayClick: function(event, jsEvent, view) { do something... } }); event是日程（事件）對象，jsEvent是個javascript事件，view是當前視圖對象。 |
| eventMouseover eventMouseout |
鼠標劃過和離開的事件，用法和參數同上 |
選擇操作
| 屬性 | 描述 | 默認值 |
| selectable | 是否允許用戶通過單擊或拖動選擇日歷中的對象，包括天和時間。 | false |
| selectHelper | 當點擊或拖動選擇時間時，顯示默認加載的提示信息，該屬性只在周/天視圖裏可用。 | false |
| unselectAuto | 當點擊頁面日歷以外的位置時，是否自動取消當前的選中狀態。 | true |
| unselectCancel | 指定哪些元素不會清空當前的選中，以JQUERY選擇器的方式指定 ‘#someId‘。 | ‘‘ |
| select | callback，被選中的函數回調，使用方法： function( startDate, endDate, allDay, jsEvent, view ) startDate：被選中區域的開始時間 endDate：被選中區域的結束時間 allDay：是否為全天事件 startDate：jascript對象 startDate：當前視圖對象 |
|
| unselect | callback，選中被取消時的回調，使用方法： function( view, jsEvent ) |
|
| select | method，選中某個時間，使用方法： $(‘#calendar‘).fullCalendar( ‘select‘, startDate, endDate, allDay ) |
|
| unselect | method，取消選中，使用方法： $(‘#calendar‘).fullCalendar( ‘unselect‘ ) |
|
日程事件數據
FullCalendar最重要的部分，設置用於日程事件相關信息。
Event Object，事件對象，用來存儲一個日歷事件信息的標準對象，只有title和start是必須的
| 屬性 | 描述 |
| id | 可選，事件唯一標識，重復的事件具有相同的id |
| title | 必須，事件在日歷上顯示的title |
| allDay | 可選，true or false，是否是全天事件。 |
| start | 必須，事件的開始時間。 |
| end | 可選，結束時間。 |
| url | 可選，當指定後，事件被點擊將打開對應url。 |
| className | 指定事件的樣式。 |
| editable | 事件是否可編輯，可編輯是指可以移動, 改變大小等。 |
| source | 指向次event的eventsource對象。 |
| color | 背景和邊框顏色。 |
| backgroundColor | 背景顏色。 |
| borderColor | 邊框顏色。 |
| textColor | 文本顏色。 |
事件源對象
事件源即日歷中的數據來源，FullCalendar提供了數組、函數調用、以及JSON數據的形式，當然也可以通過Google Calendar feed獲取數據接口。helloweba.com後面會有文章專門介紹事件數據的操作，包括數據的查詢、寫入、更新和刪除操作。
以下是Event事件相關的參數屬性說明。
| 屬性 | 描述 | 默認值 |
| eventSources | 事件源，存儲數組對象，可以是Arrays/Functions/URLs。 | |
| allDayDefault | 是否為全天日程事件，顯示這一天中所做的事情。 | true |
| ignoreTimezone | 是否忽略時區。 | true |
| startParam | 在使用URL方式獲取events數據源的時候, 自動插入到URL中的參數, 表示當前需要抓取的日程事件的起始時間。 | ‘start‘ |
| endParam | 和startParam參數意義相同, 表示要抓取的日程事件的終止時間。 | ‘end‘ |
| lazyFetching | 是否從緩存信息獲取event。比如從月視圖切換到周視圖。 | true |
| eventDataTransform | callback，將外部數據源轉換成Fullcalendar可以處理的數據 | |
| loading | callback，日歷開始加載的時候，isLoading參數為true觸發一次，日歷加載完畢，isLoading參數為false觸發一次，用法： function(isLoading, view) |
|
| updateEvent | method，更新日歷空間中的一個日程事件，如果是重復的日程事件，則都更新。用法： $(‘#calendar‘).fullCalendar( ‘updateEvent‘, event ) |
|
| clientEvents | method，返回FullCalendar已經存儲到客戶端的CalEvents對象數組， 第二個參數和removeEvents方法的第二個參數意義相同， 只不過在過濾器中， 如果返回true， 則該CalEvent對象將被加入到返回的數組中。 | |
| removeEvents | method，從日歷中刪除一個日程事件. 第二個參數可以不填， 可以填id， 可以是一個過濾器(一個函數， 接受CalEvent對象作為參數)。用法： $(‘#calendar‘).fullCalendar( ‘removeEvents‘ [, idOrFilter ] ) |
|
| refetchEvents | method，重新抓取所有的日程事件源上的日程事件並渲染它們。 | |
| addEventSource | method，添加一個日程事件源，添加之後， FullCalendar會馬上從該源獲取日程事件， 並加載到日歷中。第二個參數和定義Calendar時候使用的url參數一致。 | |
| removeEventSource | method，移除一個日程事件源，該源上獲取得到的日程時間也將被馬上從日歷中移除。 | |
事件渲染
| 屬性 | 描述 |
| eventColor eventBackgroundColor eventBorderColor eventTextColor |
設置日程事件的背景色和邊框色，以及文本顏色。可以使用任意支持css的顏色方式，如 #f00, #ff0000, rgb(255,0,0), or red。 |
| eventRender | callback，當日程事件渲染時觸發，用法： function(calEvent, element, view) |
| eventAfterRender | callback，當日程事件被渲染後觸發，用法： function( event, element, view ) { } |
| eventDestroy | callback，當日程事件移出時觸發，用法： function( event, element, view ) { } |
| renderEvent | method，一旦日歷重新取得日程源，則原有日程將消失，當指定stick為true時，日程將永久的保存到日歷上。 |
| rerenderEvents | method，重新渲染所有事件。 |
日程事件拖動和縮放
拖動和縮放功能依賴於jQuery ui的draggable和resizable，所以在使用時要提前加載jQuery ui相關插件。
| 屬性 | 描述 | 默認值 |
| editable | 是否可編輯，即進行可拖動和縮放操作。 | false |
| eventStartEditable | 是否讓事件在開始時就可以拖動。 | true |
| dragRevertDuration | 如果拖拽不成功，多久回復原狀，毫秒 | 500 |
| dragOpacity | 拖動時候的不透明度。 { agenda:.5 //對於agenda試圖 ‘‘:1.0 //其他視圖 } |
見描述 |
| eventDragStart, eventDragStop |
callback，日程事件被拖動之前和之後觸發。這裏的拖動不一定是一個有效的拖動，只要日程事件的控件被拖著動了，事件就觸發。 可以從該對象中獲取位移，位置等數據。用法： function( event, jsEvent, ui, view ) { } | |
| eventDrop | callback，當拖拽完成並且時間改變時觸發，用法： function( event, dayDelta, minuteDelta, allDay, revertFunc, jsEvent, ui, view ) { } ayDelta 保存日程向前或者向後移動了多少天 minuteDelta 這個值只有在agenda視圖有效，移動的時間 allDay 如果是月視圖，或者是agenda視圖的全天日程，此值為true,否則為false |
|
| eventResizeStart, eventResizeStop |
callback，在一個日程事件改變大小之前之後發生(不一定要改變成功)，用法： function( event, jsEvent, ui, view ) { } |
|
| eventResize | callback，在日程事件改變大小並成功後調用, 參數和eventDrop參數用法一致。用法： function( event, dayDelta, minuteDelta, revertFunc, jsEvent, ui, view ) { } |
|
日期工具
| 函數 | 描述 |
| formatDate | 格式化日期，通過指定的格式格式化一個日期，返回一個字符串。options選項是一個對象，其中設置本地化變量支持的屬性值. 比如{ monthNames : [‘一月‘，‘二月‘，……]，dayNames: [‘周日‘，‘周一‘，…..]}，用法： $.fullCalendar.formatDate( date，formatString [,options ] ) |
| formatDates | 一次格式化兩個日期，和上一個格式化日期類似，只不過，這裏在formatString中使用大括號{…}來描述第二個日期的格式化方式。用法： $.fullCalendar.formatDates( date1，date2，formatString [,options ] ) |
| parseDate | 解析日期，將一個字符串格式成一個javascript的Date對象，這個string可以是ISO8601，IETF，UNIX時間戳三種格式。用法: $.fullCalendar.parseDate( string ) |
| parseISO8601 | 將一個ISO8601字符串轉換成一個javascript 的Date對象。用法： $.fullCalendar.parseISO8601( string [,ignoreTimezone ] ) |
參考文獻：
FullCalendar日歷插件說明文檔