EasyUI DataGrid 數據格式規範：必須使用 JSONObject 包裝 JSONArray

EasyUI DataGrid 組件對後端返回數據格式有嚴格要求：必須是 JSONObject，內層包含 total 和 rows 字段，rows 為 JSONArray。直接返回 JSONArray 會導致表格無數據、分頁失效。本文給出正確結構、錯誤對比、Java 代碼實現與前端列定義。

正確數據結構

{
  "total": 100,           // 總記錄數（分頁必需）
  "rows": [               // JSONArray，當頁數據
    {"id":1,"name":"張三","age":25},
    {"id":2,"name":"李四","age":30}
  ]
}

• total：Integer，後端查詢 count(*) 結果。
• rows：JSONArray，每個元素為 JSONObject，鍵與 DataGrid field 屬性一一對應。

錯誤示範（直接返回 JSONArray）

[ {"id":1,"name":"張三"}, {"id":2,"name":"李四"} ]  // 錯誤：DataGrid 解析失敗，顯示空白

Java 後端實現（以 Json-lib 為例）

import net.sf.json.JSONArray;
import net.sf.json.JSONObject;
import java.util.List;
public class DataGridResult {
    private long total;
    private List rows;
    // getter/setter
    public JSONObject toJson() {
        JSONObject json = new JSONObject();
        json.put("total", total);
        json.put("rows", JSONArray.fromObject(rows)); // List 自動轉 JSONArray
        return json;
    }
}
// Controller
@RequestMapping("/list")
@ResponseBody
public JSONObject list(@RequestParam int page, @RequestParam int rows) {
    List data = userService.pageQuery(page, rows);
    long total = userService.count();
    return new DataGridResult(total, data).toJson();
}

前端 DataGrid 列定義對應

<table id="dg" title="用戶列表" class="easyui-datagrid"
       url="/user/list" pagination="true" pageSize="20"
       rownumbers="true" fitColumns="true" singleSelect="true">
  <thead>
    <tr>
      <th field="id" width="50">ID</th>
      <th field="name" width="100">姓名</th>
      <th field="age" width="50" align="right">年齡</th>
    </tr>
  </thead>
</table>

• field 值必須與 JSON 對象鍵完全一致（區分大小寫）。
• pagination="true" 依賴 total 字段渲染分頁條。

常見坑點

1. 忘記 total：分頁條顯示「共 0 頁」，翻頁無效。
2. 字段名不匹配：如 JSON 鍵 userName，列 field="name" → 顯示空白。
3. 日期/數字格式：JSON 傳字符串，前端用 formatter 格式化：formatter: function(v){ return new Date(v).format('yyyy-MM-dd'); }。
4. 大數據量：關閉 fitColumns、開啟 virtualScroll 或服務端分頁（已示例）。

Spring MVC 直接返回對象（Jackson 自動序列化）

@Data
public class GridData {
    private long total;
    private List rows;
}
@RestController
public class UserController {
    @GetMapping("/list")
    public GridData list(@RequestParam int page, @RequestParam int rows) {
        return new GridData<>(userService.count(), userService.pageQuery(page, rows));
    }
}

Jackson 會自動將 GridData 序列化為標準 {total:..., rows:[...]}，無需手動構建 JSONObject。

記住「JSONObject 包裝 total + rows」，EasyUI DataGrid 數據綁定零故障。