jquery.fullCalendar官方文檔翻譯(一款小巧好用的議程管理日曆, 可整合Google Calendar)

轉載請聲明出處: http://blog.csdn.net/lgg201

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>

<script type='text/javascript' src='../gcal.js'></script>  <!—如果需要使用google的同步賬戶才需要引入. -->

17. 主要概念:

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

17.2. 議程事件: 某一條議程記錄, 比如: 2009年11月16日星期一 晚上11點11分11秒111毫秒, 事件title為: “selfimpr, 需要做某某工作.  郵箱: lgg860911@yahoo.com.cn, Blog: http://blog.csdn.net/lgg201 ”

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. 領域模型:  呵呵, 自己根據自己的理解畫的, 希望可以幫到大家理解這個議程管理的概念.