异常教程

jQuery EasyUI 数据网格 – 添加查询功能（长文解析）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言

在现代 Web 开发中，数据展示与交互是核心需求之一。jQuery EasyUI 数据网格（DataGrid）作为一款轻量级且功能强大的前端组件，常用于快速构建可排序、分页、筛选的表格界面。然而，许多开发者在初期使用时，可能对如何为数据网格添加查询功能感到困惑。本文将通过循序渐进的步骤，结合实际案例和代码示例，帮助读者掌握这一技能，同时融入动态交互和用户体验优化的进阶技巧。

环境准备与基础概念

在开始前，需确保已引入以下资源：

  1. jQuery（版本 1.7+）
  2. jQuery EasyUI（推荐使用最新稳定版）
  3. HTML5 环境

核心概念解析

  • 数据网格（DataGrid）：类似于 Excel 表格，支持动态加载数据、分页、排序和自定义渲染。
  • 查询功能：通过表单输入或按钮触发，将用户输入的条件传递给后端，返回筛选后的数据。
  • 比喻说明：可将数据网格想象为“超市货架”，而查询功能则是“分类标签”，帮助用户快速定位目标商品。

步骤 1：搭建基础数据网格

首先，我们需要创建一个最简单的数据网格。以下代码演示了如何通过 EasyUI 的 datagrid 插件初始化表格：

<table id="userGrid"></table>

<script>
$(function() {
    $('#userGrid').datagrid({
        url: '/api/users',        // 后端数据接口
        columns: [[
            {field: 'id', title: 'ID', width: 100},
            {field: 'name', title: '姓名', width: 150},
            {field: 'email', title: '邮箱', width: 200}
        ]],
        pagination: true          // 启用分页
    });
});
</script>

关键参数说明

  • url：数据源地址，支持 JSON 格式返回。
  • columns：定义表格列的字段和标题。
  • pagination：启用分页功能，默认显示页码、页面大小选择器等。

步骤 2：添加基础查询表单

接下来，我们通过表单控件（如输入框、下拉菜单）收集用户输入的查询条件。

<!-- 查询表单 -->
<div class="search-form">
    <input class="easyui-textbox" name="keyword" prompt="搜索姓名或邮箱" style="width:200px">
    <a href="javascript:void(0)" class="easyui-linkbutton" onclick="doSearch()">查询</a>
</div>

<!-- 数据网格 -->
<table id="userGrid"></table>

样式与布局

为确保表单与表格在视觉上协调，可添加以下 CSS：

.search-form {
    margin: 20px;
    padding: 10px;
    background: #f5f5f5;
    border-radius: 4px;
}

步骤 3：实现动态查询功能

核心方法：queryParams

queryParams 是 EasyUI DataGrid 的关键参数，用于定义每次请求携带的查询参数。我们可以通过 JavaScript 动态修改这些参数，从而实现条件筛选。

示例代码

function doSearch() {
    // 获取表单输入值
    var keyword = $('input[name="keyword"]').val();
    
    // 更新 queryParams 参数
    $('#userGrid').datagrid('options').queryParams = {
        keyword: keyword
    };
    
    // 刷新表格数据
    $('#userGrid').datagrid('reload');
}

关键点解释

  • queryParams 会作为查询参数附加到 url 请求的 URL 中。例如，若 keyword 的值为 "john"，则请求地址变为 /api/users?keyword=john。
  • datagrid('reload')：强制重新加载数据，应用新的查询条件。

进阶技巧：动态表单与复杂查询

1. 多条件查询表单

通过添加更多表单控件（如日期选择器、下拉框），实现多条件组合查询：

<div class="search-form">
    <input class="easyui-textbox" name="name" prompt="姓名" style="width:150px">
    <input class="easyui-datebox" name="startDate" prompt="开始日期" style="width:150px">
    <input class="easyui-datebox" name="endDate" prompt="结束日期" style="width:150px">
    <select class="easyui-combobox" name="status" style="width:150px">
        <option value="">全部状态</option>
        <option value="active">激活</option>
        <option value="inactive">未激活</option>
    </select>
    <a href="javascript:void(0)" class="easyui-linkbutton" onclick="doSearch()">查询</a>
</div>

2. 表单数据序列化

使用 serializeArray() 方法将表单数据转换为对象，再传递给 queryParams：

function doSearch() {
    var formData = $('.search-form').serializeArray();
    var params = {};
    
    // 将表单数据转换为键值对
    $.each(formData, function() {
        if (this.value !== '') {  // 过滤空值
            params[this.name] = this.value;
        }
    });
    
    // 更新并刷新
    $('#userGrid').datagrid('options').queryParams = params;
    $('#userGrid').datagrid('reload');
}

优化与用户体验提升

1. 重置按钮功能

添加“重置”按钮，清空表单并恢复默认查询：

<a href="javascript:void(0)" class="easyui-linkbutton" onclick="resetSearch()">重置</a>

function resetSearch() {
    $('.search-form')[0].reset();  // 重置表单
    doSearch();                   // 触发默认查询（keyword 空）
}

2. 远程搜索优化

对于大数据量场景，可通过 EasyUI 的 onBeforeLoad 事件实现输入框实时搜索：

$('#userGrid').datagrid({
    onBeforeLoad: function(params) {
        // 在输入框按下回车时自动触发搜索
        $('input[name="keyword"]').keydown(function(e) {
            if (e.keyCode === 13) {  // 回车键
                doSearch();
            }
        });
    }
});

常见问题与解决方案

问题 1：查询参数未传递到后端

原因：可能未正确设置 queryParams 或未调用 reload()。
解决：

// 确保在修改 queryParams 后调用 reload()
$('#userGrid').datagrid('options').queryParams = { keyword: 'test' };
$('#userGrid').datagrid('reload');

问题 2：分页功能失效

原因：默认分页参数可能被覆盖。
解决：在 queryParams 中保留分页参数 page 和 rows：

var originalParams = $('#userGrid').datagrid('options').queryParams;
var newParams = $.extend(originalParams, { keyword: 'test' });
$('#userGrid').datagrid('options').queryParams = newParams;

结论

通过本文的讲解，读者应能掌握如何为 jQuery EasyUI 数据网格 添加灵活的查询功能。从基础表单搭建到动态参数传递，再到用户体验优化，这一过程不仅提升了数据展示的实用性，也为后续开发复杂交互界面奠定了基础。

未来，开发者可进一步探索：

  • 结合 EasyUI 的工具栏（Toolbar） 实现按钮式快速筛选
  • 使用 远程搜索（Remote Searching） 减少客户端数据量
  • 结合 表单验证 提升输入可靠性

希望本文能成为您构建高效 Web 应用的实用指南！

最新发布

查看更多文章