jQuery EasyUI数据网格怎么做？datagrid用法、数据加载与避坑指南一次讲清

做后台管理系统，十个需求里有八个都要求数据列表展示：分页、排序、搜索、复选框一应俱全。jQuery EasyUI的datagrid组件把这一整套功能都封装好了，配置几行参数就能得到一个功能完整的表格。但很多人第一次用的时候会遇到表格空白、分页不生效、列显示错位等各种问题，根源大多在于对datagrid的数据交互机制不够了解。这篇文章从创建方式、数据加载、列配置到常见坑点，把datagrid的用法完整梳理一遍。

一、创建datagrid的两种方式

datagrid支持两种创建方式。第一种是HTML声明式写法，直接在<table>标签上通过class声明，EasyUI解析到该标签后会自动渲染成表格：

<table id="dg" class="easyui-datagrid"
       title="用户列表" style="width:700px;height:400px"
       data-options="singleSelect:true,collapsible:true,
       url:'/user/list',pagination:true,
       pageSize:20,pageList:[10,20,30,50]">
    <thead>
        <tr>
            <th data-options="field:'id',width:80">编号</th>
            <th data-options="field:'userName',width:120">用户名</th>
            <th data-options="field:'email',width:200">邮箱</th>
            <th data-options="field:'createTime',width:160">创建时间</th>
        </tr>
    </thead>
</table>

这种写法直观，适合静态页面。但列比较多、需要动态生成列时，声明式写法就不灵活了，这时候用JavaScript初始化更合适：

$('#dg').datagrid({
    title: '用户列表',
    width: 700,
    height: 400,
    fitColumns: true,          // 列宽自适应
    singleSelect: true,        // 只允许单选
    pagination: true,          // 开启分页
    pageSize: 20,
    url: '/user/list',         // 远程数据地址
    columns: [[
        { field: 'ck', checkbox: true },
        { field: 'id', title: '编号', width: 80, align: 'center' },
        { field: 'userName', title: '用户名', width: 120 },
        { field: 'email', title: '邮箱', width: 200 },
        { field: 'status', title: '状态', width: 80,
          formatter: function(value) {
              return value == 1 ? '启用' : '禁用';
          }
        }
    ]]
});

两种方式底层逻辑一致，最终都会调用同一个组件。实际项目里推荐JS初始化，因为列定义、事件绑定、方法调用都在一处，维护起来更清晰。还需要注意，datagrid依赖EasyUI的核心样式和脚本文件，引入顺序必须是jQuery在前、easyui.min.js在后，顺序反了会直接报错。

二、数据加载方式与分页机制

datagrid获取数据主要有三种方式。第一种是url参数，组件初始化后自动向该地址发POST或GET请求，这是最常用的方式。第二种是loadData方法，直接把本地JSON数组塞进表格，适合前端已持有全部数据的场景。第三种是load方法，带参数重新发起url请求，常配合搜索框使用：

// 方式一：本地数据填充
$('#dg').datagrid('loadData', [
    { id: 1, userName: '张三', email: 'zhangsan@ipipp.com' },
    { id: 2, userName: '李四', email: 'lisi@ipipp.com' }
]);

// 方式二：带查询条件重新加载远程数据
$('#dg').datagrid('load', {
    keyword: $('#kw').val(),
    status: 1
});

// 方式三：重新加载当前页（保留原查询条件）
$('#dg').datagrid('reload');

用url方式时，datagrid默认会向服务端传两个分页参数：page（当前页码）和rows（每页条数）。服务端拿到这两个参数后做物理分页查询，然后返回特定格式的JSON。这个格式是新手最容易栽跟头的地方：必须返回{total: 总条数, rows: [数据数组]}的结构，total是满足条件的记录总数，rows是当前页数据。如果只返回一个数组，表格能显示数据但分页条会显示0条记录；如果字段名拼错，表格直接空白。

// 服务端必须返回的结构
{
    "total": 135,
    "rows": [
        { "id": 1, "userName": "张三", "email": "zhangsan@ipipp.com" },
        { "id": 2, "userName": "李四", "email": "lisi@ipipp.com" }
    ]
}

需要自定义分页参数名的话，可以在初始化时配置pagination相关的请求前处理，或者直接改queryParams。另外如果接口分页参数叫pageNum、pageSize这类命名，建议在服务端做兼容，前端强行改参数名反而容易把维护搞乱。

三、列属性formatter与styler的实战用法

formatter用于格式化单元格显示内容，参数依次是当前值、当前行数据、行索引，返回的字符串会直接渲染进单元格。常见的用法包括状态翻译、金额格式化、拼接操作按钮等：

columns: [[
    { field: 'amount', title: '金额', width: 100,
      formatter: function(value, row, index) {
          if (value == null) return '-';
          return '¥' + value.toFixed(2);
      }
    },
    { field: 'operate', title: '操作', width: 150,
      formatter: function(value, row, index) {
          var html = '';
          html += '<a href="javascript:void(0)" onclick="editRow(' + row.id + ')">编辑</a> ';
          html += '<a href="javascript:void(0)" onclick="delRow(' + row.id + ')">删除</a>';
          return html;
      }
    }
]]

styler则用来给单元格加样式，返回的是style字符串或者css类名。比如让异常数据标红、超期任务标黄：

{ field: 'days', title: '剩余天数', width: 100,
  styler: function(value, row, index) {
      if (value < 0) {
          return 'background-color:#ffcccc;color:#cc0000;';
      } else if (value < 3) {
          return 'background-color:#fff2cc;';
      }
  }
}

有一个细节要提醒：formatter返回的内容是被当作HTML渲染的，如果字段值里包含用户输入的内容，务必先做HTML转义，否则会有XSS风险。操作列里拼onclick事件时，参数尽量只用id这类数字，不要直接拼字符串字段值。

四、常见坑点与解决思路

坑一：表格空白但请求正常。九成原因是返回的JSON结构不符合要求，或者是字段名与columns里的field对不上。打开浏览器控制台看Network面板，确认响应里有total和rows，且rows内的键名和field完全一致，注意大小写。

坑二：宽高设置不生效。datagrid的宽高需要在初始化时明确指定，或者在CSS里给容器定宽高。若想表格撑满父容器，可以设置fit: true；想列自动填满表格宽度用fitColumns: true，但两者不要和固定width混用，混用会出现列挤压或横向滚动条异常。

坑三：选中行数据取不到。获取选中行要用$('#dg').datagrid('getSelected')，多选用getSelections。有人在行点击事件里自己维护选中数组，和组件内部的选中状态不同步，翻页后就错乱了，正确做法是始终通过组件方法取数据。翻页后想保留选中，可以监听onSelect和onUnselectAll事件自行缓存id，回翻时恢复。

坑四：分页条中文乱码或显示异常。EasyUI默认语言是英文，引入中文语言包即可：easyui-lang-zh_CN.js，注意语言包要在easyui.min.js之后引入，否则覆盖不生效。

总的来说，datagrid的功能远不止这些，编辑表格、冻结列、分组视图、视图自定义都有对应的配置项。把本文的数据交互机制吃透之后，再去查文档扩展其他功能会顺畅很多。核心记住一点：datagrid的一切行为都围绕total加rows的数据结构展开，遇到问题先检查数据格式，往往问题就出在那里。

jQuery EasyUIdatagrid数据网格修改时间：2026-09-04 23:54:48