Bootstrap Table 分頁失效？後端分頁模式下 total 字段與參數傳遞完整指南

問題現象

使用 Bootstrap Table 插件，後端已正確分頁返回 JSON（含 total 總記錄數），前端初始化顯示第一頁 10 條正常，**但翻頁欄不顯示，無法翻頁**。

根本原因排查

Bootstrap Table 判斷是否顯示分頁器的邏輯：total > pageSize。常見導致「以為只有一頁」的原因：

1. total 字段名不匹配

默認期望響應結構：

{
  "total": 100,
  "rows": [...]
}

若後端返回 { "count": 100, "data": [...] }，需配置：

$('#table').bootstrapTable({
  responseHandler: function(res) {
    return { total: res.count, rows: res.data };
  }
});

2. 查詢參數名不匹配

默認發送參數：pageNumber=1&pageSize=10（非 page=1&rows=10）。

若後端固定要求 page/rows，需重寫 queryParams：

queryParams: function(params) {
  return {
    page: params.pageNumber,
    rows: params.pageSize,
    sort: params.sortName,
    order: params.sortOrder
    // 其他業務參數...
  };
}

3. sidePagination 設置錯誤

後端分頁必須設置：

sidePagination: 'server'  // 默認 'client' 會導致前端以為數據已全量加載

4. dataField 指向錯誤

若數據在嵌套對象中：

dataField: 'result.list'  // 對應 { "result": { "list": [...], "total": 100 } }

完整初始化示例

$('#table').bootstrapTable({
  url: '/api/data',
  method: 'post',
  sidePagination: 'server',        // ★ 關鍵：後端分頁
  pagination: true,                // 顯示分頁條
  pageNumber: 1,
  pageSize: 10,
  pageList: [10, 25, 50, 100],
  queryParams: function(params) {  // ★ 參數映射
    return {
      page: params.pageNumber,
      rows: params.pageSize
    };
  },
  responseHandler: function(res) { // ★ 響應格式適配
    return {
      total: res.total,
      rows: res.rows
    };
  },
  columns: [{ field: 'id', title: 'ID' }, { field: 'name', title: '姓名' }]
});

調試技巧

1. 打開瀏覽器 Network 面板，檢查請求參數是否為 pageNumber/pageSize。
2. 檢查響應 JSON 結構，確認 total 為數字類型且大於 pageSize。
3. 控制台輸入 $('#table').bootstrapTable('getOptions') 查看實際生效配置。

總結

Bootstrap Table 不顯示分頁 90% 因 sidePagination: 'server' 缺失 或 total/rows 字段映射錯誤。對齊參數名、響應結構、分頁模式三要素即可解決。