萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery DataTables 伺服器端處理模式完整指南:sAjaxSource、bServerSide、fnServerData、fnServerParams

DataTables 的伺服器端處理模式(Server-side Processing)能應對百萬級資料,將分頁、排序、搜尋邏輯下推至後端。本文詳細解析核心參數、請求/回應格式、自訂 Ajax 與進階技巧。

核心參數速覽

參數類型說明
sAjaxSourceStringAjax 請求 URL,DataTables 會自動附加分頁/排序/搜尋參數
bServerSideBoolean`true` 啟用伺服器端模式,所有分頁/排序/搜尋由後端處理
fnServerDataFunction自訂 Ajax 請求函式,完全接管請求流程(加入 Token、錯誤處理、Loading)
fnServerParamsFunction在發送請求前,向參數陣列 `aoData` 推入額外參數

標準請求參數(DataTables 發送給後端)

{
  draw: 1,                    // 請求計數器,回應必須原樣返回
  start: 0,                   // 起始筆數(0-based)
  length: 10,                 // 每頁筆數
  search: { value: "", regex: false }, // 全域搜尋值
  order: [{ column: 0, dir: "asc" }],  // 排序欄位與方向
  columns: [                  // 每欄設定
    { data: "columnA", name: "", searchable: true, orderable: true, search: { value: "", regex: false } },
    { data: "columnB", name: "", searchable: true, orderable: true, search: { value: "", regex: false } }
  ]
}

標準回應格式(後端必須回傳)

{
  "draw": 1,                 // 必須與請求 draw 相同
  "recordsTotal": 57,        // 資料庫總筆數(無過濾)
  "recordsFiltered": 57,     // 過濾後總筆數(搜尋後)
  "data": [                  // 當頁資料陣列,每項對應 columns.data
    { "columnA": "valueA1", "columnB": "valueB1", ... },
    { "columnA": "valueA2", "columnB": "valueB2", ... }
  ],
  "error": ""                // 選填,錯誤訊息會顯示在表格
}

關鍵: 回應必須為合法 JSON,`data` 為陣列,每個元素為物件,屬性名對應 `columns.data`。

初始化範例

$('#example').DataTable({
  processing: true,           // 顯示 "Processing..." 指示器
  serverSide: true,           // 啟用伺服器端模式
  ajax: {
    url: '/api/data',
    type: 'POST',             // 大量參數建議 POST
    data: function(d) {       // fnServerParams 等效
      d.extraParam = 'myValue'; // 加入額外參數
      d._token = $('meta[name="csrf-token"]').attr('content'); // CSRF Token
    },
    dataSrc: function(json) { // fnServerData 部分邏輯:資料轉換
      if (json.error) {
        // 全域錯誤處理
        showError(json.error);
        return [];
      }
      return json.data;
    },
    error: function(xhr, error, thrown) {
      if (error === 'parsererror') {
        alert('伺服器回傳非合法 JSON,請檢查後端輸出');
      }
    }
  },
  columns: [
    { data: 'columnA', title: '欄位 A' },
    { data: 'columnB', title: '欄位 B' }
  ],
  order: [[0, 'asc']],        // 預設排序
  pageLength: 10,
  lengthMenu: [[10, 25, 50, -1], [10, 25, 50, "全部"]]
});

後端實作要點(以 Node.js/Express 為例)

app.post('/api/data', (req, res) => {
  const { draw, start, length, search, order, columns } = req.body;
  
  // 1. 建構查詢
  let query = db.select('*').from('my_table');
  
  // 2. 全域搜尋
  if (search.value) {
    const term = `%${search.value}%`;
    query.where(qb => {
      columns.forEach(col => {
        if (col.searchable) qb.orWhere(col.data, 'like', term);
      });
    });
  }
  
  // 3. 排序
  if (order && order.length) {
    const colIdx = order[0].column;
    const colName = columns[colIdx].data;
    const dir = order[0].dir === 'desc' ? 'desc' : 'asc';
    query.orderBy(colName, dir);
  }
  
  // 4. 總筆數(無過濾)
  const total = await db('my_table').count('* as cnt').first();
  const recordsTotal = parseInt(total.cnt);
  
  // 5. 過濾後總筆數
  const filtered = await query.clone().count('* as cnt').first();
  const recordsFiltered = parseInt(filtered.cnt);
  
  // 6. 分頁資料
  const data = await query.clone().offset(start).limit(length);
  
  // 7. 回應
  res.json({ draw: parseInt(draw), recordsTotal, recordsFiltered, data });
});

進階技巧

1. 管線化請求

DataTables 內建管線化(`$.fn.dataTable.pipeline`),減少重複請求:

$.fn.dataTable.pipeline = function(opts) {
  const conf = $.extend({ pages: 5, url: '', data: null, method: 'GET' }, opts);
  let requestQueue = [];
  let lastRequest = null;
  
  return function(request, drawCallback, settings) {
    const ajax = false;
    const requestStart = request.start;
    const requestLength = request.length;
    const requestEnd = requestStart + requestLength;
    
    if (lastRequest && requestStart >= lastRequest.start && requestEnd <= lastRequest.end) {
      // 從快取取得
      drawCallback(lastRequest.data);
      return;
    }
    
    // 新請求加入佇列...
    // 完整實作請參考 DataTables 官網 pipeline 範例
  };
};

// 使用
$('#example').DataTable({
  ajax: $.fn.dataTable.pipeline({ url: '/api/data', pages: 5 })
});

2. 子行明細(Row Details)

$('#example tbody').on('click', 'td.details-control', function() {
  const tr = $(this).closest('tr');
  const row = table.row(tr);
  if (row.child.isShown()) {
    row.child.hide();
    tr.removeClass('shown');
  } else {
    row.child(formatDetail(row.data())).show();
    tr.addClass('shown');
  }
});

3. 搭配 Editor 做編輯/新增/刪除

官方付費套件 DataTables Editor 提供完整 CRUD UI、驗證、彈出表單、多列編輯。

常見錯誤排查

現象原因解決
「Invalid JSON response」後端輸出非 JSON(HTML 錯誤頁、PHP Warning、BOM)檢查 `Content-Type: application/json`、關閉 PHP `display_errors`、移除 BOM
排序/搜尋不生效後端未實作對應邏輯解析 `order`、`search`、`columns` 參數建構 SQL
分頁筆數不對`recordsTotal`/`recordsFiltered` 計算錯誤分開查詢:總數用 `COUNT(*)`,分頁用 `LIMIT/OFFSET`
Draw 不匹配回應未回傳原始 `draw` 值確保 `res.json({ draw: parseInt(req.body.draw), ... })`
中文亂碼編碼不一致全鏈路 UTF-8,DB 連線 `charset=utf8mb4`

掌握伺服器端模式核心協定,即可輕鬆串接任何後端框架,打造高效能、大數據量的資料表格體驗。

copyright © 萬盛學電腦網 all rights reserved