【Bootstrap-table】

　　顧名思義，這個組件專註於bootstrap風格的表格的設計，並且提供了很多表格的基礎和進階的功能，給我們開發前端的表格省下很多力氣。

　　本文主要參考這位博主的系列文章：

　　【http://www.cnblogs.com/landeanfen/p/5005367.html】

　　有興趣的可以移步看原版，我自己做一個筆記性質的東西。

■　　基本使用

　　和大多數bs組件一樣，首先我們要確保引入以下幾個基本文件：

<link href="/static/css/bootstrap.min.css" rel="stylesheet" />

<
 
script src="/static/js/jquery.min.js"></script>
<script src="/static/js/bootstrap.min.js"></script>

　　然後是引入bootstrap-table的一些文件：

<link href="/static/bootstrap-table/dist/bootstrap-table.min.css" rel="stylesheet" />

<script src="/static/bootstrap-table/dist/bootstrap-table.min.js"
 
></script>
<script src="/static/bootstrap-table/dist/locale/bootstrap-table-zh-CN.min.js"></script>

　　最後一個是國際化顯示文件，即支持組件顯示中文。

　　引入文件完畢之後，我們在HTML中簡單地寫上一個table標簽即可：

<table id="bsTableTest"></table>

　　然後在相應的js中寫如下內容：

$(document).ready(function(){
    $(‘#skillContentTable‘).bootstrapTable({
        url: querySkillUrl,
        columns: [...],
        resizable: 
 
true,
        pagination: true,
        sidePagination: ‘client‘,
        pageNumber: 1,
        pageSize: 10,
        pageList: [10,20,50,‘All‘],
        search: true,
        showRefresh: true,
        showToggle: true,
        showColumns: true,
    });
});

　　依次解釋一下各個參數的話：

　　url　　代表了表格加載數據（包括頁面的首次加載和點擊刷新按鈕等時機）時向後端某一個url索取數據。此參數和data參數可二選其一

　　columns　　指出了表格的<th>部分的結構，比較重要且似乎必須在前端寫出，這裏因為比較長沒有具體寫出來，下面再細說。

　　resizable　　可以讓用戶通過拖動調整各個列的列寬，需要其他組件的支持，上面也沒有寫出來，下面細說

　　pagination　　是否分頁。bootstrap-table可以自動給我們生成分頁，這個功能很好（回想起自己手動寫分頁的痛苦。。）

　　sidePagination　　bs-table中分頁分成兩種模式，即所謂的server模式和client模式。兩種模式下後端給出的數據結構不同，分頁運算也在不同的地方完成。至於結構如何不同後面細說

　　pageNumber，pageSize，pageList　　很顯然是一些分頁的參數，pageNumber是默認顯示第幾頁，一般設置成1；pageSize是默認一頁顯示多少行；pageList是提供給用戶可以調整的一頁顯示的行數，是個列表

　　search　　是否顯示搜索框，bs-table自帶一個搜索框，如果有需要可以直接在搜索框中進行模糊搜索

　　showRefresh　　是否顯示刷新按鈕，在右上角

　　showColumns　　是否顯示“顯示列控制"按鈕，通過這個按鈕可以調整頁面上顯示哪些字段而不顯示哪些

　　showToggle　　是否顯示試圖切換按鈕，通過這個按鈕可以在表格切換和卡片視圖間切換

　　除了上面這些還有一些基本的初始化參數：

　　striped　　設置為true時表格樣式為table-striped的樣子

　　classes　　渲染出的table的class，默認是table table-hover

　　strictSearch　　啟用完全匹配搜索而不是模糊搜索

　　undefinedText　　當數據為undefined時顯示的字符，默認是‘-‘。

　　uniqueId　　指定一列作為ID，但是沒有直接作用，在相關方法中才有用

　　height　　指出表格高度，當表格高度超過指定值時就有滾動條了。

■　　上述參數的細化說明

　　先來說說resizable吧，這個參數是設置為true之後還需要在頁面上引入下面兩個東西：

<script src="colResizable-1.6.min.js"></script>
<script src="bootstrap-table/dist/extensions/resizable/bootstrap-table-resizable.min.js"></script>

　　請註意，colResizable-1.6.min.js不是bootstrap-table的一部分，需要另外去網上找並且下載。這是一個jquery調整列寬的組件。而bootstrap-table-resizable.min.js是bootstrap-table中的一個擴展。在extensions目錄下。這個目錄中有很多好用的拓展，以後可能也會再說到。

　　再簡單說下data，data參數可以在js內部就給表格充實內容。但是由於很少會有在前端計算決定表格內容的場景，基本上都是用不到的，除了在測試或者幹嘛的時候用一下。

　　● columns參數說明

　　正如上面說明的，columns參數的值指出了這個表格<th>部分應該如何構建，其數據結構是這樣的：比如我要構建一張口袋妖怪的招式的統計表格：

columns: [{
            checkbox:true,
            align: ‘center‘
        },{
            field: ‘id‘,
            title: ‘編號‘,
            sortable: true
        },{
            field: ‘cn_name‘,
            title: ‘中文名‘,
            sortable: true
        },{
            field: ‘jp_name‘,
            title: ‘日文名‘
        },{
            field: ‘en_name‘,
            title: ‘英文名‘
        },{
            field: ‘nature‘,
            title: ‘屬性‘,
            sortable: true
        },{
            field: ‘generation‘,
            title: ‘世代‘,
            sortable: true
        },{
            field: ‘power‘,
            title: ‘威力‘
        },{
            field: ‘hirate‘,
            title: ‘命中‘
        },{
            field: ‘type‘,
            title: ‘攻擊類型‘
        },{
            field: ‘pp‘,
            title: ‘pp點數‘
        }],

　　可以看出其值是一個字典的列表（or you say object的數組），field指出了字段名而title指出了頁面上顯示的列名。此外還有額外的參數sortable指出了用戶可以點擊某列表頭，依此列對當前數據進行排序。另外還可以註意第一項的checkbox:true，這表示在開頭的第一列有一列checkbox，點擊每一行前面的可以選中這一行，而點擊表頭的checkbox更是可以全選。

　　除了上述列參數，還有很多其他的列參數，比如：

　　radio　　和checkbox類似，渲染出一列radio

　　align,vlign,halign　　指出了列的對其/垂直對其/水平對齊方式。

　　visible　　指出該列是否默認顯示，如果設置為false即隱藏了，那麽可以通過showColumns的那個按鈕再調出來

　　formatter　　是一個函數，可以對傳入此列所有單元格的數據做二次加工。這個函數接收三個參數value , row , index。這三個參數分別代表了單元格的值，單元格所在的行的行對象，單元格下標。

　　這裏也只是簡單的說了一些列參數，更完全的參數列表可以參考官方文檔【http://bootstrap-table.wenzhixin.net.cn/zh-cn/documentation/#%E5%88%97%E5%8F%82%E6%95%B0】

　　● sidePagination和後端傳來的數據格式

　　當設置sidePagination為client模式時，即所有分頁排序操作都在客戶端的瀏覽器中完成。當數據總量比較少時這種模式可以減少前後端多余的通信成本，比較適合。而且在這種模式下，後端傳來數據格式比較簡單。比如上面這個表，在後端的django框架中我可以這樣返回：

def query_for_skill(request):
    data_set = []
    for skill in Skill.objects.all():
        data_set.append(skill.getAttrs())

    # return HttpResponse(json.dumps({‘rows‘:data_set,‘total‘:len(data_set)}),content_type=‘application/json‘)
    return HttpResponse(json.dumps(data_set),content_type="application/json")

　　這裏模型類Skill還實現了一個方法getAttrs，這個方法是返回了模型類對象定義的各個字段和各自值對應的字典。所以當我們要把數據一股腦兒地傳遞給前端時，Skill.objects.all()是一個模型類對象的列表，前端尚無法識別，要我們做個小循環來處理下數據，這樣就傳遞給前端的數據就是JSON的，像這樣的: [{id: 1,cn_name: ‘xxx‘,power:xx...}, ...]。因為采取客戶端分頁排序的方式，所以一股腦兒把數據傳遞給前端之後，前端再進行分頁排序等操作時不會再向後端請求數據。效果：

　　同樣的分頁效果，還可以通過server的sidePagination來實現。

　　當通過server的sidePagination來做時需要註意後端返回的數據結構有變化，應該像上面view函數中被註釋掉的那個return的json串那樣。即返回一個字典，含有rows和total兩個key，前者的value和之前client模式的返回內容一樣，而後者的value是指出了所有記錄的總長度。

　　當采用server模式時，像上面那樣的view函數就不是很管用了。事實上，點擊server模式的分頁，會向後臺發出一個新的ajax請求來請求數據，其請求參數默認包含了limit,offset,search,sort,order，分別代表一頁顯示數目；跳過前offset條記錄；查找字符串內容；排序字段名；排序方式(‘asc‘或‘desc‘)。如果想要傳入更多的參數可以設置queryParams這個初始化參數。這個ajax請求默認是GET方法，如果想要用POST，可以在初始化參數method中指出

　　queryParams的值是一個函數對象。這個函數接受一個參數params，代表上面提到的那五個參數和各自值形成的對象（如果是空值則是undefined）。最終返回是一個經過函數處理的object作為真的請求參數發出請求。如果返回false則取消請求，所以也可以在這個函數中增加自定義過濾條件或進行查詢條件合法性的檢查。

　　對view函數的改造，很明顯應該適應於前端傳遞過來的參數。在後端做出一些過濾篩選後返回一個有限的結果集。比如像上面那個函數我們可以這麽改造來適應分頁、排序的需求：

def query_for_skill(request):
    data_set = []
    offset = request.GET.get(‘offset‘)
    limit = request.GET.get(‘limit‘)
    sort = request.GET.get(‘sort‘)
    order = request.GET.get(‘order‘)
    length = len(Skill.objects.all())
    if not offset or not limit:
        targets = Skill.objects.all()
        if sort:
            sort = sort if order == ‘asc‘ else ‘-‘+sort
            targets = targets.order_by(sort)
    else:
        offset = int(offset)
        limit = int(limit)
        if sort:
            sort = sort if order == ‘asc‘ else ‘-‘ + sort
            targets = Skill.objects.all().order_by(sort)[offset:offset+limit]
        else:
            targets = Skill.objects.all()[offset:offset+limit]
    for skill in targets:
        data_set.append(skill.getAttrs())
    return HttpResponse(json.dumps({‘rows‘:data_set,‘total‘:length}),content_type=‘application/json‘)

　　再額外提一句，在client模式中，search是直接在客戶端中完成搜索，不涉及額外通信以及耗費後臺資源。但是search該參數並沒有指出是search了哪個字段的內容，這就導致，如果在server模式下也用search的話，勢必要對整個表的所有字段進行檢查，來尋找和search給出的值相關的內容。這個不僅編程麻煩，還會給數據庫帶來很大負擔。所以不推薦用bootstrap-table自帶的search。如果有search的這需求，可以考慮通過在表格上面寫一個filter，然後在queryParams的函數中加上額外的參數來進行查詢。

■　　相關方法

　　和其他很多組件一樣，bs-table有自己的一些方法接口，可以讓程序員實現自己的邏輯。這些方法的調用方法主要是$(‘#bsTableTest‘).bootstrap(‘<方法名>‘,<一個object形式的參數>)。常用的方法有：

　　getOptions　　獲取表格的一些基本屬性，返回一個object，key有像conlumns，data，sortOrder，class這些

　　getSelections　　獲取被選中的（包括radio或者checkbox）各行對象組成的列表。

　　load,append,prepend　　這三個方法的參數都是data，即[{...},{...}...]形式的數據，load是清空當前表中所有數據，append是在表尾加，prepend是在第一行前面插入數據

　　remove　　參數是一個object，含有兩個字段，field和values。通過兩個字段的值可以定位一個或多個單元格，把這些單元格所在的行刪除。例如bootstrapTable(‘remove‘,{field:‘id‘,values:[3]})。需要註意的是即便是只定位一個單元格，即values後列表中只有一個值，那也要寫出是個列表，否則會識別失敗

　　insertRow,updateRow　　這兩個方法分別用於在指定位置插入一個新行或者更新指定行的信息。參數有index和row，如bootstrapTable(‘insertRow‘,{index:2,row:{id:99,name:‘New Row‘,desc:‘Test‘}})，需註意，如果某些字段沒有在params中給出值的話，那麽insert時默認這些字段為undefined，update時默認這些字段沒有改變。

　　getRowByUniqueId　　這個方法要配合初始化時的uniqueId參數指定的字段，參數為此字段的某個值，返回值等於參數中給出值的那一行的行對象

　　showRow,hideRow　　顯示隱藏行，參數可用index，也可用uniqueId，如bootstrapTable(‘showRow‘,{index:2})

　　showLoading,hideLoading　　顯示/隱藏加載狀態

　　mergeCells　　用於合並單元格，參數有四個，如果把合並後最左上角的那個單元格稱為初始單元格的話，那麽index是初始單元格的行的index，field是初始單元格所在列字段名。這兩個參數確定了一個起始單元格，然後還有兩個參數rowspan和colspan都是int型，指出了從初始單元格開始向下並幾行向右並幾列。

　　updateCell　　index，field和value三個參數用來更新單個單元格內的值

　　refresh　　刷新表格數據，可以加入參數url指定請求發向的url（可以是一個新的），silent:true時靜默更新，query:{} 可以指出一些新的ajax請求時的參數。　　

　　resetSearch　　可以設置搜索框中文字，這個方法比較特殊的是參數不是一個object而是單純的string。例如bootstrapTable(‘resetSearch‘,‘Hello‘)

　　checkAll,uncheckAll　　全選/全不選當前頁面中的行

　　check/uncheck　　選中/不選一行，同resetSearch一樣，不用傳遞object，直接寫int型的index數據即可例如 bootstrapTable(‘check‘,2)

　　checkBy/uncheckBy　　bootstrapTable(‘checkBy‘,{field:‘id‘,values:[1,3,5]})，選中部分，條件由參數給出

　　getHiddenRows/getHiddenColumns　　獲取隱藏著的行和列們

　　getScrollPosition/scrollTo　　當表格有滾動條時，前者返回滾動條滾動位置，後者設置。單位是px，scrollTo可以是‘bottom‘來拉到底

　　filterBy　　在客戶端進行數據過濾，參數是field和values

　　prevPage/nextPage/selectPage　　跳往前一頁/後一頁/指定頁

■　　相關事件

　　除了方法之外，組件另外一個重要的組成部分就是事件了。boostrap-table的事件的使用方法並不是經典的$(xxx).on(‘事件‘,function)，而是采用將事件作為初始化參數的一部分傳入初始化函數中。比如：

$(‘#bsTableTest‘).bootstrapTable({
    xxx: xxx,
    事件: function(params){...}
});

　　正如上面所示，事件會關聯一個函數，而不同的事件，關聯的函數有哪些參數也都是不一樣的。下面列出主要可能用到的事件：

　　onClickRow　　點擊一行時觸發的事件，參數有row , element , field三個，分別代表點擊行的行對象，點擊行的jquery<tr>對象，點擊的列的title

　　onDblClickRow　　雙擊行事件，參數和onDblClickRow一樣

　　onClickCell　　點擊單元格觸發的事件，參數包括field , value , row , element，分別表示點擊單元格所在列title,單元格的值，單元格所在行行對象，單元格的jquery<td>對象

　　onDblClickCell　　雙擊單元格事件，參數和onClickCell一樣

　　onSort　　點擊排序按鈕進行數據排序時觸發的事件，包括參數name和order分別代表排序字段名和排序方式（asc和desc）

　　onCheck/onUncheck　　當某一行被選中/取消選中時觸發事件，參數有row和element

　　onCheckAll/onUncheckAll　　參數是rows，一個被選中所有行對象的數組。需要註意，手動一個一個選擇時不會觸發這個事件，只有按表頭的那個全選，全選行時才會觸發。

　　onLoadSuccess/onLoadError　　當加載數據成功/失敗時觸發的事件，前者參數data，後者參數status（HTTP返回碼，如500,404之類的）

　　onColumnSwitch　　當設置某一列可見/不可見時觸發，參數是field和checked，field是被操作的字段title名，而checked是boolean值，表示操作後該字段是否是顯示狀態。

　　onPageChange　　換頁時觸發事件，參數有number和size，分別代表跳轉後位於第幾頁且頁面內有多少條記錄

　　onSearch　　使用bs-table自帶搜索框進行搜索時觸發事件，參數是text即搜索關鍵文

　　onRefresh　　刷新表格數據是觸發的事件，參數params是一個挺復雜的對象，包含了此次刷新的一些信息。不具體展開說了，有需要的話可以測試下

【Bootstrap】 bootstrap-table表格組件