DataTables 控制元件使用和心得 (2)
什麼是DataTables引數(Options)
上篇我們說了,DataTables控制元件的載入函式dataTable()一般都有一個物件引數,這個物件引數就是整個DataTables控制元件的引數(Options),通過定義這個引數中的各種屬性,來靈活控制DataTable的初始效果. 樣例程式碼如下:
$('#example').dataTable({
“option1”:value1,
“option2”:value2,
…
});
下面是一些常用的引數列表,比較常用或者有價值的標示為綠色.
功能引數(Features)
|
引數名 |
說明 |
參考值 |
預設值 |
|
autoWidth |
定義是否由控制元件自動控制列寬 |
Boolean |
true |
|
deferRender |
定義在render時是否僅僅render顯示的dom,在顯示大量資料的情況下強烈建議設為true,顯示少量資料或者真翻頁方案可以設為false,注意在設為true時無法通過函式獲取所有行的dom物件—因為它們並不存在. |
Boolean |
false |
|
info |
控制總數資訊(標準介面右下角顯示總數和過濾條數的控制元件)的顯隱 |
Boolean |
true |
|
lengthChange |
控制是否能夠調整每頁的條數,如果設為false,標準的每頁條數控制控制元件也會被隱藏. |
Boolean |
true |
|
ordering |
全域性控制列表的所有排序功能. |
Boolean |
true |
|
paging |
全域性控制列表的翻頁功能,如果設為false,所有的預設翻頁控制元件會被隱藏 |
Boolean |
true |
|
processing |
控制是否在資料載入時出現”Processing”的提示,一般在遠端載入並且比較慢的情況下才會出現. 樣式需要定義,否則比較醜. |
Boolean |
false |
|
scrollX |
控制在列過多過寬是,是否出現水平滾動條.注意使用這個引數時最好關閉響應式設計 |
Boolean |
false |
|
scrollY |
定義一個高度,當列表內容超過這個高度時,顯示垂直滾動條,這個高度不算表頭和翻頁搜尋等工具條的空間.支援數字或者css寫法比如: 200或者’200px’ |
Number / String |
無 |
|
searching |
控制控制元件的搜尋功能,如果為false,控制元件的搜尋功能被完全禁用,而且預設搜尋元件會被隱藏. |
Boolean |
true |
|
serverSide |
當設為true時,列表的過濾,搜尋和排序資訊會傳遞到Server端進行處理,實現真翻頁方案的必需屬性.反之,所有的列表功能都在客戶端計算並執行 |
Boolean |
false |
資料引數(Data)
|
引數名 |
說明 |
參考值 |
|
data |
以Javascript陣列物件方式設定列表顯示資料 |
陣列物件 |
|
ajax |
String模式: 直接傳入一個string作為遠端ajax請求路徑 |
String |
|
物件模式: 支援JQuery.ajax函式的引數設定,支援type,url等標準引數. 例如: $('#example').dataTable( { "ajax": { "url": url, "type": "POST" } } ); |
JQuery ajax 函式對應引數 |
|
|
ajax.data |
和標準JQuery.ajax的data引數作用類似,但效果有所不同.僅當serverSide引數為true的時候,引數屬性才有意義,當serverSide開啟,DataTables元件會自行封裝一個資訊類傳送給服務端,而ajax.data僅僅是對這個資訊類進行調整和新增. 新增方式, ajax.data可以直接賦值一個物件,這個物件的屬性會新增到原資訊類裡面去一起傳送到服務端.例如: $('#example').dataTable( { "ajax": { "url": "data.json", "data": { "user_id": 451 } } } ); 另外一種選擇是傳入一個方法,方法的引數就是當前傳送到伺服器的資訊類,在方法中可以修改這個資訊類. $('#example').dataTable( { "ajax": { "url": "data.json", "data": function ( d ) { d.extra_search = $('#extra').val(); } } } ); |
物件或者方法 |
|
ajax.dataSrc |
定義伺服器返回物件裡面儲存資料的屬性名稱,預設為data,也即是說,在返回的Json資料中,所有列表資料儲存在data屬性中,這個屬性不太建議修改. |
配置引數(Options)
|
引數名 |
說明 |
參考值 |
預設值 |
|||
|
deferLoading |
這個引數只有在ServerSide為Ture的時候才有作用,主要是針對列表已經通過HTML顯示了一部分資料,而通知遠端載入可以忽略這部分資料,在實際使用中這種情況並不常見. |
Number /Array |
false |
|||
|
destroy |
設為ture時通知dataTable函式完全重新建立一個新的控制元件例項,在一個頁面內反覆對同一個控制元件載入dataTable函式並且想重新建立控制元件時使用. |
Boolean |
false |
|||
|
displayStart |
列表初始顯示的行索引,根據給出的行索引會自動翻頁,比如一個每頁10個的列表,那麼給出20可以讓其翻到第二頁 |
Number |
無 |
|||
|
dom |
比較複雜的配置項,簡言之就是通過一個自定義的字串來定義DataTables裡面所有元件的顯示,位置和顯隱. 具體請詳見: http://datatables.net/reference/option/dom |
String |
“lfrtip” |
|||
|
lengthMenu |
定義頁面長度元件裡面的選項. |
Array |
[ 10, 25, 50] |
|||
|
orderCellsTop |
當然表頭有多層td組成的時候,必須定義哪一個td的資料用於排序,false表示底部td,true表示頂部td. 比如以下情況:
true的時候排序會用2.1, false的時候排序會用2.2. |
Boolean |
false |
|||
|
orderClasses |
定義是否排序的列進行高亮顯示 |
Boolean |
true |
|||
|
order |
定義列表的初始排序設定,為一個2維陣列,子陣列包括2個值,列索引和排序方向(asc/desc): 例如 "order": [[ 0, 'asc' ], [ 1, 'asc' ]] |
Array |
[[0, 'asc']] |
|||
|
orderMulti |
控制是否支援多重排序,如果為true,可以通過shift+點選列頭實現多重排序,或者通過API實現,否則禁用該功能. |
Boolean |
true |
|||
|
orderFixed |
自定義固定的排序策略,該策略在任何排序操作中總是起效.可以通過對一個列的固定排序(可以是隱藏的列)來定義列表預設的排序策略. 陣列方式,定義優先排序策略,如: "orderFixed": [ 0, 'asc' ] 該引數說明無論如何排序,永遠先進行第一列的正向排序. 物件方式,可以利用關鍵字pre或post來定義這個規則是優先生效還是置後生效. "orderFixed": { "pre": [ 0, 'asc' ], "post": [ 1, 'asc' ] } |
Array/Object |
無 |
|||
|
pageLength |
定義初始的頁長 |
Number |
10 |
|||
|
pagingType |
定義翻頁元件的樣式(有4個選擇): simple - 只有上一頁和下一頁2個按鈕 simple_numbers – 上一頁,下一頁和頁碼 full – 首頁,末頁,上一頁,下一頁4個按鈕 full_numbers – 全部按鈕和頁面 |
String |
simple_numbers |
|||
|
scrollCollapse |
在設定了一定的scrollY值後起效,為true時,當列表內容不足以撐滿scrollY的設定值時,列表高度會自動適應內容. |
Boolean |
false |
|||
|
search |
定義列表的初始搜尋/過濾條件 Search物件可以有以下屬性: |
Object |
無 |
|||
|
search.search |
過濾字串,注意在預設設定下,所有列的資料都會參與過濾.比如當這個屬性為”a”的時候,任何一個列只要包含”a”的行就會被顯示.為空表示全部 |
String |
無 |
|||
|
search.caseInsensitive |
搜尋是是否忽略大小寫,true為忽略 |
Boolean |
true |
|||
|
search.regex |
定義搜尋字串是否為一個正則表示式 |
Boolean |
fasle |
|||
|
search.smart |
禁用獲取啟用DataTables控制元件內建的只能過濾演算法,這個演算法會把搜尋字串進行分割並只能搜尋,關閉這個演算法僅僅實現簡單的字串查詢,false為關閉 |
Boolean |
true |
|||
|
searchCols |
分別定義每個列的過濾條件.該引數是一個物件陣列,每個物件有2個屬性: search: 搜尋字串 escapeRegex: 是否是正則表示式 注意不需要設定過濾的列也需要用null佔位,比如: "searchCols": [ null, { "search": "My filter" }, null, { "search": "^[0-9]", "escapeRegex": false } ] |
Array |
無 |
|||
|
stripeClasses |
定義一個字串陣列,在顯示行的時候依次使用裡面的字串作為行的class |
Array |
‘odd’ & ‘even’ |
列定義引數(Columns)
|
引數名 |
說明 |
參考值 |
預設值 |
|
columns |
列的初始狀態的定義,該引數一個是物件陣列,每一個物件元素定義一個列.注意,不需定義的列也必須以null佔位,比如: "columns": [ { "searchable": false }, null, null ] |
Array |
無 |
|
columnDefs |
和columns設定非常類似,但可以通過targets屬性可以根據靈活的選擇需要設定的列.比columns更加靈活.比如: "columnDefs": [ { "targets": 0, "searchable": false } ] targets可以有多種寫法: 0或者正整數(可用陣列): 表示正向列的索引 負數(可用陣列): 表示反向列的索引 字串: 匹配th的class來選擇列. "_all": 所有列,也是預設值. |
||
|
columns.data |
列的資料名,對應資料裡面的屬性名 |
String |
無 |
|
columns.name |
給列設定獨立的名稱,目前看意義不大 |
String |
無 |
|
columns.orderable |
設定列是否允許排序 |
Boolean |
true |
|
columns.searchable |
設定列是否允許過濾 |
Boolean |
true |
|
columns.type |
通過設定列的型別讓控制元件在排序和過濾這個列是能更好的處理這個列的資料,比如日期,貨幣等.具體種類很多請參考這裡: http://datatables.net/reference/option/columns.type |
String |
無 |
|
columns.visible |
設定列的可見性,true為顯示 |
Boolean |
true |
|
columns.width |
強行設定列的寬度,支援數字和任何CSS寫法,比如20%. |
String |
無 |
|
columns.render |
非常有用的函式,自定義列的內容.該屬性比較常見的用法是函式用法,通過這個函式可以自定義改造列的任何內容,如果要在列中顯示比較複雜的內容,這是一個比較好的選擇.比如在列中加入功能按鈕. 例如: "render": function ( data, type, row, meta ) { return '<a href="'+data+'">Download</a>'; } 4個屬性的意思是: data : 當前單元格的資料 type: 當前列的型別 row: 當前行完整的資料物件 meta: 為一個子物件,包含3個屬性 row: 當前行的索引 col: 當前列的索引 settings: 當前DataTables控制元件的setttings物件 |
Function |
無 |
可以看到,DataTables的Options設定還是比較全面和豐富的,當然Options僅僅能在控制元件初始化的時候對控制元件進行控制和影響,如果要在控制元件使用過程中對它進行控制和變化,就需要用到DataTables的函式庫(API).這個我們將在下一篇文章中討論.