fullCalendar中文API官方文檔

2019-11-19 17:42:02

字體：大中小

來源：轉載

供稿：網友

1. 使用方式: 引入相關js, css后, $(‘#div_name').fullCalendar({//options}); 接受的是一個option對象

2. 普通屬性

　2.1. year, month, date: 整數, 初始化加載時的日期.

　2.2. defaultView: 字符串類型, 默認是'month;

　　2.2.1. 允許的views:

　　　2.2.1.1. month 一頁顯示一月, 日歷樣式

　　　2.2.1.2. basicWeek 一頁顯示一周, 無特殊樣式

　　　2.2.1.3. basicDay 一頁顯示一天, 無特殊樣式

　　　2.2.1.4. agendaWeek 一頁顯示一周, 顯示詳細的24小時安排(也就是議事日程)

　　　2.2.1.5. agendaDay 一頁顯示一天, 顯示詳細的24小時安排

　2.3. header: 定義按鈕/文本在日歷的頂部, false說明不使用header., 使用left, center, right三個屬性來進行布局, 默認是{left: ‘title', center: ‘', right: ‘today prev, next'}, 支持使用的屬性按鈕:

　　2.3.1. title: 一個包含當前日期的文本

　　2.3.2. prev: 根據view的不同, 返回上一月/周/天

　　2.3.3. next: 根據view的不同, 返回下一月/周/天

　　2.3.4. prevYear: 使日歷返回到上一年

　　2.3.5. nextYear: 使日歷返回下一年

　　2.3.6. today: 將日歷移動到當天.

　　2.3.7. view name: 上面列舉的支持views名稱, 用來切換views

　2.4. buttonText: 定義header中使用的按鈕的顯示文本: 接受的屬性名: prev, next, prevYear等等

　2.5. aspectRatio: 接受一個浮點參數, 調整寬高比例.

　2.6. allDayDefault: 布爾類型, 默認true, 決定每個CalEvent的allDay屬性的默認值. allDay標明一個日程事件是否是整天的, 也就是忽略具體的時間, 只計算天數. 默認情況下, 所有的新添加的日程時間不加說明, 都是allDay的, 可以通過設置allDayDefault, 使得新創建的日程時間, 默認情況下就是關注時間的.

　2.7. weekends: 布爾類型, 默認為true, 標識是否顯示周六和周日的列.

　　2.7.1. finxed: 每月固定顯示6周.

　　2.7.2. liquid: 可能會顯示4, 5, 6周, 依賴于月份, 每周的高度會拉長到填充可變高度, 視aspectRatio而定, 這里月份的高度是定的.

　　2.7.3. vairiable: 可能會顯示4, 5, 6周, 依賴于月份, 每周的高度會有一個固定值, 也就是說, 整個月份的高度會隨著有幾周的行數而變化.

　2.8. allDaySlot: 布爾值, 默認是true, 標明在agenda views模式下的時候, 上面的all-day小塊是否顯示.

　2.9. allDayText: allDay區域的文本內容.

　2.10. firstHour: 整型, 默認值為6. 表示在agenda的views中, 剛打開的時候顯示的是第n小時, 該table用scroll控制.

　2.11. slotMinutes: 整型, 默認值30, 表示在agenda的views中, 兩個時間之間的間隔. 也就是沒一個小時所在一行中另外分出來的每一個小行代表多少分鐘.

　2.12. defaultEventMinutes: 整型, 默認值120, 和事件有關, 功能不確定.

3. 日程編輯

　3.1. editable: Boolean類型, 默認值false, 用來設置日歷中的日程是否可以編輯. 可編輯是指可以移動, 改變大小等.

　3.2. disableDragging: Boolean類型, 默認false, 所有的event可以拖動, 必須editable = true

　3.3. diableResizing: Boolean, 默認false, 所有的event可以改變大小, 必須editable = true

　3.4. dragRevertDuration: 拖動恢復的時間, 默認500毫秒, 表示一個不成功的拖動之后, 控件回復到原始位置的時間.

　3.5. dragOpacity: Float類型, 表示拖動時候的不透明度. 指定一個float數值, 表示所有的views下都使用該不透明度, 也可以賦值為一個對象, 通過views hash來指定特定的views中的不透明度, 在以對象通過views hash指定不透明度時, 可以指定一部分, 然后, 其他的用'': float的方式來標明其他的所有的views下都使用該不透明度.

　　3.5.1. month

　　3.5.2. week: basicWeek和agendaWeek

　　3.5.3. day: basicDay和agendaDay

　　3.5.4. agenda: agendaDay和agendaWeek

　　3.5.5. agendaDay

　　3.5.6. agendaWeek

　　3.5.7. basic: basicWeek和basicDay

　　3.5.8. basicWeek

　　3.5.9. basicDay

　　3.5.10. ‘': 空的字符串, 表明所有其他的views

4. 時間和日期的格式化

　4.1. 支持的格式化占位符

　　4.1.1. s: 秒

　　4.1.2. ss: 秒, 兩位

　　4.1.3. m: 分鐘

　　4.1.4. mm: 分鐘, 兩位

　　4.1.5. h: 小時, 12小時制

　　4.1.6. hh: 小時, 12小時制, 兩位

　　4.1.7. H: 小時, 24小時制

　　4.1.8. HH: 小時, 24小時制, 兩位

　　4.1.9. d: 日期數字

　　4.1.10. dd: 日期數字, 兩位

　　4.1.11. ddd: 日期名稱, 縮寫

　　4.1.12. dddd: 日期名稱, 全名

　　4.1.13. M: 月份數字

　　4.1.14. MM: 月份數字, 兩位

　　4.1.15. MMM: 月份名稱, 縮寫

　　4.1.16. MMMM: 月份名稱, 全名

　　4.1.17. yy: 兩位的年份

　　4.1.18. yyyy: 4位的年份

　　4.1.19. t: 上下午加 a或者p

　　4.1.20. tt: 上下午加am或pm

　　4.1.21. T: 上下午加A 或者P

　　4.1.22. TT: 上下午加AM或PM

　　4.1.23. u: ISO8601格式

　　4.1.24. S: 給日期加上st, nd, rd, th等后綴, 表明是第幾天

　　4.1.25. 特殊字符:

　　　4.1.25.1. ‘…' 原意輸出文本

　　　4.1.25.2. ‘' 表示一個單引號

　　　4.1.25.3. (…), 括號內的占位符表示的格式化日期中, 至少有一個不為空, 才顯示括號內的這一組格式化字符串

　4.2. titleFormat: string/object: 確定header中的title展示日期的格式, 這里也可以使用view hash的方式通過對象進行配置, 如果使用view hash的方式, 配置, 則每種view中的title的格式都是不一樣的.

　4.3. columnFormat: string/object, 和titleFormat配置方式一樣, 影響各種view中的每列的表頭顯示文本. 文檔中關于allDay為false時的解釋不明白.

　4.4. timeFormat: 默認是{agenda: ‘h:mm{ - h:mm}}, 影響的是添加的具體的日程上顯示的時間格式.

　4.5. axisFormat: string, 默認h(:mm)tt, 影響agenda views下的最左的一列的時間顯示方式.

　4.6. views hash: 現在支持view hashes的選項有: dragOpacity, titleFormat, columnFormat, timeFormat

5. formatDates: $.fullCalendar.formatDates(date1, date2, formatString, [options]): 和formatDate類似, 但是接受兩個date, 在格式化字符串中, 使用{…}來格式化第二個date

6. Event sources:

　6.1. events: array/string/function:

　　6.1.1. 配置事件源

　　　6.1.1.1. 數組是硬編碼的日程事件.

　　　6.1.1.2. 提供一個URL, 該URL返回一個json或數組的日程事件組, GET參數視startParam和endParam選項而定.

　　　6.1.1.3. 提供一個函數, 以自定義的方式抓取數據, 該函數需要接受參數start, end, callback, 分別表示抓取的日程事件的開始時間, 結束時間, 抓取結束后的回調比如:

events: function(start, end, callback) {$.getJSON(“/myscript”, {start: start.getTime(), end: end.getTime()}, function(result) {callback(result);})}

　6.2. eventSources: Array, 就像events選項一樣, 但是, 這個用來配置多個日程事件數據來源.

　6.3. startParam: string, 默認值: start, 這個就是在使用URL方式獲取events數據源的時候, 自動插入到URL中的參數, 表示當前需要抓取的日程事件的起始時間

　6.4. endParam: string, 默認值: end, 和startParam參數意義相同, 表示要抓取的日程事件的終止時間

　6.5. cacheParam: 當使用JSON url方式獲取日程事件時, 為了防止ajax自身的緩存帶來的數據不同步問題, 加入的鑒別參數名, 值是由full calendar控制加入的當前時間. 不懂可以查詢ajax緩存解決方案.

7. CalEvent對象: 標準的當前使用的日程事件源(請注意區分這里的日程事件和計算機領域的事件之間的區別, 這里的事件是業務上的, 表明在某個時間做某事的一個記錄, 而計算機領域的事件則是用戶對計算機的一個動作)

　7.1. id: Integer/String: 日程事件的標識, repeat型的日程事件擁有相同的id

　7.2. title: string, 日程事件的標題

　7.3. allDay: Boolean, 默認true, 標明一個日程事件是否是關注具體時間的, 如果是true, 表明該日程事件不關注具體時間, 是當天所有時間都有的, 所以, 該日程事件的日期會被忽略, 在agenda view中通過專門的allDay區域顯示, 如果是false, 則是關注開始時間和結束時間的.

　7.4. date: Date類型, 是start屬性的別名

　7.5. start: Date類型, 一個JavaScript的Date對象, 方便起見, 可以使用IETF格式, ISO8601格式以及UNIX時間戳等多種方式的字符串表示.

　7.6. end: Date(可選的): 和start一樣, 不過表示日程時間的結束時間.

　　7.6.1. 如果對應的日程事件是allDay的, 那么10月1日8時到10月3日8時就表示跨度是3天

　　7.6.2. 如果對應的日程時間不是allDay的, 那么10月1日8時10月3日8時則表示跨度是48個小時.

　　7.6.3. url: string, 設置一個url, 該日程事件被點擊的時候使用, 新的頁面默認在當前窗口打開, 如果使用更復雜的事件處理, 要使用eventClick觸發動作(這份文檔中使用了Triggered Action來描述計算機領域的事件, 防止了和該插件所在領域的日程事件沖突.)

8. 方法: 方法調用的方式: $(‘.selector').fullCalendar(‘method_name')首先使用一個jQuery選擇器獲取日歷控件對象, 然后, 調用fullCalendar(), 參數是字符串形式的方法名

　8.1. prev, 跳轉到前一月/周/天, 根據當前的view決定

　8.2. next, 同prev, 是后一月/周/天

　8.3. today, 跳轉到今天.

　8.4. gotoDate: 調用方式: $(‘.selector').fullCalendar(‘gotoDate', year[, month[, date]])調用方法名為gotoDate, 后面三個參數傳遞年, 月, 日, 年是必選, 其他兩個可選. 其中的月month參數, 是以0開始計算的, 也就是說一月對應0. 該方法也可以使用單參數的方式調用, 傳遞一個javascript的Date對象.

　8.5. incrementDate: $(‘.selector').fullCalendar(‘incrementDate', years[, months[, days]]) 以當前時間為軸, 將日歷向前, 或向后移動指定長度的時間, 比如: $(‘.selector').fullCalendar(‘incrementDate', -3, 2, -5)就表示將日歷年份向前移動3年, 月份向后移動2月, day(天數???呵呵)向前移動5天.

　8.6. changeView: $(‘.selector').fullCalendar(‘changeView', viewName) 切換日歷的view, viewName必須是允許的views

　8.7. updateEvent: $(‘.selector').fullCalendar(‘updateEvent', calEvent) 更新日歷空間中的一個日程事件, 如果是repeat的日程事件, 則都更新. 這里更新的calEvent對象必須是Triggered Action(觸發事件)中作為參數傳遞的或clientEvents方法中返回的CalEvent實例, 也就是說必須是合法的, 在日歷中可檢索的.

　8.8. renderEvent: $(‘.selector').fullCalendar(‘renderEvent', calEvent, [stick]) 將一個新的CalEvent對象渲染到日歷中, 該對象至少要有title和start屬性. 默認情況下, 新渲染的這個CalEvent對象在日歷重新獲取日程事件源(比如prev, 或next調用)的時候, 會消失, 如果設置stick參數為true, 則會保證新渲染的CalEvent對象永久保留.

　8.9. removeEvents: $(‘.selector').fullCalendar(‘removeEvents', [idOrFilter]): 從日歷中刪除一個日程事件. 第二個參數可以不填, 可以填id, 可以是一個過濾器(一個函數, 接受CalEvent對象作為參數)

　　8.9.1. 不填: 所有的日程事件被移除

　　8.9.2. id: 指定id匹配的所有的日程事件被移除

　　8.9.3. 過濾器: 過濾器接受CalEvent對象作為參數, 在過濾器內部, 通過一些策略處理, 如果需要移除, 則返回true, 否則返回false.

　　8.9.4. clientEvents: $(‘.selector').fullCalendar(‘clientEvents', [idOrFilter]): 返回FullCalendar已經存儲到客戶端的CalEvents對象數組, 第二個參數和removeEvents方法的第二個參數意義相同, 只不過在過濾器中, 如果返回true, 則該CalEvent對象將被加入到返回的數組中

　　8.9.5. addEventSource: $(‘.selector').fullCalendar(‘addEventSource', source): 添加一個日程事件源, 添加之后, FullCalendar會馬上從該源獲取日程事件, 并加載到日歷中. 第二個參數和定義Calendar時候使用的url參數一致.

　　8.9.6. removeEventSource: $(‘.selector').fullCalendar(‘removeEventSource', source) 移除一個日程事件源, 該源上獲取得到的日程時間也將被馬上從日歷中移除.

　　8.9.7. rerenderEvents: $(‘.selector').fullCalendar(‘rerenderEvents') 重新渲染屏幕上的所有日程事件.

　　8.9.8. refetchEvents: $(‘.selector').fullCalendar(‘refetchEvents') 重新抓取所有的日程事件源上的日程事件并渲染它們.

　　8.9.9. render: $(‘.selector').fullCalendar(‘render'): 該方法用來立刻渲染整個日歷, 在一個可見的元素上調用fullCalendar的時候, 該方法會自動調用, 如果是在一個隱藏的元素上調用, 則需要盡快的手動調用使該元素可見并渲染.

9. 觸發事件(Triggered Action): 計算機領域中的事件

　9.1. viewDisplay: function(view)…..每次日歷加載以及日歷的view改變的時候觸發一次. 接受的view就是前面一直有提到的view對應的對象.

　9.2. loading: function(isLoading, view)…..日歷開始加載的時候, isLoading參數為true觸發一次, 日歷加載完畢, isLoading參數為false觸發一次.

　9.3. windowResize: function(view) 由于包含日歷的窗口大小發生變化導致日歷控件大小發生變化時觸發. (這個方法中的this變量指向哪個元素不清楚, 因為我這邊瀏覽器改變大小沒有導致日歷大小改變.)

　9.4. dayClick(dayDate, allDay, jsEvent, view): 用戶點擊day的時候觸發, dayDate是點擊的day的時間(如果在agenda view, 還包含時間), 在month view下點擊一天時, allDay是true, 在agenda模式下, 點擊all-day的窄條時, allDay是true, 點擊其他的agenda view下的day則為false, jsEvent就是一個普通的javascript事件, 包含的是click事件的基礎信息. 在這個方法中, this獲得的是一個普通的HTML的DOM元素, 是包含該日期的一個TD

　9.5. eventRender: function(calEvent, element, view): 日程事件渲染之前觸發. calEvent是一個CalEvent日程事件對象, element是calEvent對象對應的JQuery對象. view就是當前所處的view的實例對象, 這個方法中使用關鍵字this獲得的是calEvent對象的引用. 這個事件的處理方法如果返回false, 可以阻止渲染所有的日程事件. 該方法中可以通過修改jquery對象element來改變具體的渲染方式, 因此可以很好的和其他插件結合使用.

　9.6. eventClick, eventMouseover, eventMouseout: function(calEvent, jsEvent, view): 日程事件被點擊, 鼠標劃過, 鼠標離開的事件. 參數和上面介紹過的同名參數一致. 這里的eventClick事件如果返回false, 可以阻止瀏覽器跳轉到對應日程事件在初始配置時指定的url地址. 這種事件的阻止傳播可以參照DHTML文檔關于事件的傳播和原始響應.

　9.7. eventDragStart, eventDragStop: function(calEvent, jsEvent, ui, view)日程事件被拖動之前和之后觸發. 這里的拖動不一定是一個有效的拖動, 只要日程事件的控件被拖著動了, 事件就觸發. 同名參數和上面介紹過的一樣. UI保存的是一個JQuery的UI對象. 可以從該對象中獲取位移, 位置等數據.

　9.8. eventDrop: function(calEvent, dayDelta, minuteDelta, allDay, revertFunc, jsEvent, ui, view) 在一個日程事件被移動, 并成功移動到另外一個日期/時間.

　　9.8.1. dayDelta: 保存了這次拖動導致該日程事件移動了多少天, 向前為正數, 向后為負數.

　　9.8.2. minuteDelta: 保存了這次拖動導致該日程事件移動了多少分鐘, 向前為正數, 向后為負數. 該值只有在agenda view下有效.

　　9.8.3. allDay: 如果在month view下移動, 或在agenda view下移動到all-day區域, 則allDay為true, 移動到agenda view的其他區域則為false

　　9.8.4. revertFunc: 調用該方法, 可以將剛才的拖動恢復到原狀. 這個方法多用于ajax的提交, 移動之后, 提交數據到后臺, 如果后臺更新失敗, 根據返回消息, 調用這個方法, 可以使頁面回復原狀.

　　9.8.5. eventResizeStart, eventResizeStop: function(calEvent, jsEvent, ui, view): 在一個日程事件改變大小之前之后發生(不一定要改變成功.) calEvent保存了日程事件信息(date, title, 等等)

　　9.8.6. eventResize: function(calEvent, dayDelta, minuteDelta, revertFunc, jsEvent, ui, view): 在日程事件改變大小并成功后調用, 參數和eventDrop參數用法一致.

10. View 對象

　10.1. name: 前面列舉的那些view名稱

　10.2. title: string: 切換到view的時候, 可以在header中設置的title變量的值.

　10.3. start: Date類型, 該view下的第一天.

　10.4. end: Date類型, 該view下的最后一天. 由于是一個閉合的值, 所以, 比如在month view下, 10月這個月份, 那么end對應的應該是11月的第一天.

　10.5. visStart: Date類型. 在該view下第一個可以訪問的day. month view下, 該值是當月的第一天, week view下, 則通常和start一致.

　10.6. visEnd: Date類型, 最后一個可訪問的day

11. 顏色的修改: 通過重寫css實現

　11.1. 示例一:

.fc-event,.fc-agenda .fc-event-time,.fc-event a {  background-color: black; /* background color */  border-color: black;  /* border color (often same as background-color) */  color: red;    /* text color */  }

　11.2. 示例二

.holiday,.fc-agenda .holiday .fc-event-time,.holiday a {  background-color: green; /* background color */  border-color: green;  /* border color (often same as background-color) */  color: yellow;   /* text color */ }

12. 主題, 使用jquery ui提供的主題

　12.1. theme: Boolean, 默認false, 設置為true, 允許使用jquery的ui主題

　12.2. buttonIcons: Object, 改變header中使用的prev, next等變量對應按鈕的樣式, 默認的樣式是:

{  prev: 'circle-triangle-w',  next: 'circle-triangle-e'}

13. 本地化選項:

　13.1. firstDay: Integer類型, 默認值0. 一周中顯示的第一天是哪天. 星期天是0, 星期一是1, 類推.

　13.2. monthNames: Array, 月份全名使用的字符串, 默認是英文的月份名稱全稱.

　13.3. monthNamesShort: Array, 月份簡寫使用的字符串, 默認是英文月份名稱簡寫

　13.4. dayNames: Array, 星期的全名使用的字符串, 默認是英文的星期的名稱全稱.

　13.5. dayNamesShort: Array, 星期的簡寫使用的字符串, 默認是英文星期的名稱簡寫

　13.6. buttonText和allDayText在最初的2.4和2.9部分已經介紹.

14. 日期工具

　14.1. 格式化日期: $.fullCalendar.formatDate(date, formatString[, options]), 通過指定的格式格式化一個日期, 返回一個字符串. options選項是一個對象, 其中設置本地化變量支持的屬性值. 比如{ monthNames : [‘一月', ‘二月', ……], dayNames: [‘周日', ‘周一', …..]}

　14.2. 一次格式化兩個日期: $.fullCalendar.formatDate(date1, date2, formatString[, options]): 和上一個格式化日期類似, 只不過, 這里在formatString中使用大括號{…}來描述第二個日期的格式化方式.

　14.3. 解析日期: $.fullCalendar.parseDate(string): 將一個字符串格式成一個javascript的Date對象, 這個string可以是ISO8601, IETF, UNIX時間戳三種格式.

　14.4. parseISO8601: $fullCalendar.parseISO8601(string[, ignoreTimezone]) 將一個ISO8601字符串轉換成一個javascript 的Date對象.

15. 將日程和google的日程管理連接起來.

　15.1. 需要引入另外一個js文件: gcal.js

　15.2. events: $.fullCalendar.gcalFeed(‘自己的google calendar 的feed地址', {editable: false, className: ‘gcal-events', currentTimeZone: ‘自己在google calendar上設置的時區'}) 這樣就將自己的google calendar上的日程和自己的應用掛接起來了.

　15.3. 下面是我自己關聯自己的google calendar的代碼:

$(document).ready(function() { $('#calendar').fullCalendar({   defaultView: 'agendaWeek',   events: $.fullCalendar.gcalFeed(    'http://www.google.com/calendar/feeds/lgg860911%40yahoo.com.cn/private-184462b11481a96cf9835fbb6486dbe6/basic',     {       eidtable: true,       className: 'gcal-events',       //currentTimezone: 'Asia/Chongqing'       currentTimezone: 'Asia/Tokyo'     }   ) });});

16. 總結:

　16.1. 使用時, 下載發布版本, 而不是開發版本

　16.2. 需要引入的文件:

這個css可以根據自己的情況, 修改成自己喜歡的樣式. 500行的css, 修改量不是很大. 主要是理清關系.

<link rel='stylesheet' type='text/css' href='../fullcalendar.css' /><script type='text/javascript' src='../jquery/jquery.js'></script>

以下4個js文件是jquery-ui相關的包, 可以使用fullcalendar中自帶的, 也可以自己到jquery的ui官方庫自己訂閱一個合適自己使用的min版, 那樣, 就會得到一個有選擇的, 經過壓縮的單獨的一個js文件. 效率上比較高.

<script type='text/javascript' src='../jquery/ui.core.js'></script><script type='text/javascript' src='../jquery/ui.draggable.js'></script><script type='text/javascript' src='../jquery/ui.resizable.js'></script><script type='text/javascript' src='../fullcalendar.min.js'></script>

17. 主要概念:

　17.1. 日歷: 整個日歷控件的div, 也就是我們$(‘#calendar').fullCalendar這樣使用的時候id為calendar的容器.

　17.2. 日程事件: 某一條日程記錄, 比如: 2009年11月16日星期一晚上11點11分11秒111毫秒, 事件title為: “jb51, 需要做某某工作. ”

　17.3. 觸發動作: 經過Jquery封裝的javascript事件….

　17.4. jsEvent: 原始的javascript事件.

　17.5. 由于javascript是動態語言, 所以, 對于calEvent對象或其他任何對象而言, 想要保存一些數據, 直接設置就可以了, 比如, 你想在calEvent中保存女朋友的名字, 那就可以calEvent.girl_friend_name = ‘beautiful girl', 到你用的時候, 你就可以直接拿到了….用的時候, 最好這樣來用: my_girl_friend_name = calEvent.girl_friend_name || “another beautiful girl”; 這樣, 當你保存在calEvent中的女朋友因為中間操作丟失, 或者你根本沒有保存上你還不知道的時候, 你就可以得到another beautiful girl, 而不至于一無所獲, 甚至引發一些不必要的麻煩(瀏覽器上的警告, 說你試圖調用一個undefined對象的屬性).

18. 領域模型: 根據自己的理解畫的, 希望可以幫到大家理解這個日程管理的概念.