DataTables 的伺服器端處理模式(Server-side Processing)能應對百萬級資料,將分頁、排序、搜尋邏輯下推至後端。本文詳細解析核心參數、請求/回應格式、自訂 Ajax 與進階技巧。
| 參數 | 類型 | 說明 |
|---|---|---|
sAjaxSource | String | Ajax 請求 URL,DataTables 會自動附加分頁/排序/搜尋參數 |
bServerSide | Boolean | `true` 啟用伺服器端模式,所有分頁/排序/搜尋由後端處理 |
fnServerData | Function | 自訂 Ajax 請求函式,完全接管請求流程(加入 Token、錯誤處理、Loading) |
fnServerParams | Function | 在發送請求前,向參數陣列 `aoData` 推入額外參數 |
{
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, "全部"]]
});
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 });
});
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 })
});
$('#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');
}
});
官方付費套件 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` |
掌握伺服器端模式核心協定,即可輕鬆串接任何後端框架,打造高效能、大數據量的資料表格體驗。