本文介绍在 jqgrid 使用 toolbar search 时，调用 `reloadgrid()` 后搜索状态残留导致后续过滤仅作用于已过滤子集的问题，并提供通过 `cleartoolbar(true)` 和 `refreshfiltertoolbar()` 恢复原始数据源的完整解决方案。
在使用 jqGrid 的 Toolbar Search（工具栏搜索）功能时，一个常见但易被忽视的问题是：当用户输入搜索文本、触发前端或服务端过滤后，再执行 reloadGrid()（例如编辑完某行后刷新表格），jqGrid 默认会保留当前搜索条件，并在后续手动修改搜索框内容时，仅对已过滤后的结果集（如 26 条）进行二次过滤——而非回到原始数据源（如 100 条）重新筛选。这本质上是因 jqGrid 内部缓存了搜索状态，且未重置其过滤上下文。
要彻底解决该问题，关键在于显式清除搜索栏状态并同步重置过滤逻辑，而非仅刷新数据。以下是推荐的两步处理方案：
✅ 正确做法：清除搜索状态 + 刷新过滤器
function refreshGrid() {
// 步骤1：强制清空工具栏搜索值，并重置内部过滤状态
const grid = $("#grid_id")[0];
if (grid && typeof grid.clearToolbar === 'function') {
grid.clearToolbar(true); // true 表示同时触发 filterToolbar 重绘和参数重置
}
// 步骤2：更新请求参数（如需更换 URL 或参数）
$("#grid_id").jqGrid('setGridParam', {
datatype: 'json',
url: 'your-data-url.php' // 确保指向完整数据源接口
});
// 步骤3：触发重载 —— 此时将基于原始数据源重新加载，且搜索框已清空
$("#grid_id").trigger('reloadGrid');
}⚠️ 注意：clearToolbar(true) 是 Guriddo jqGrid（v5.0+）及部分兼容版本的关键方法；若使用旧版 free jqGrid 或 jqGrid 4.x，需改用 $("#grid_id").jqGrid('destroyFilterToolbar') 后重建，或手动清空搜索输入框并调用 trigger('reloadGrid', {current: true})。
? 进阶需求：保留搜索文本但重置过滤范围？
若业务要求保留用户输入的搜索文本（如用户不希望清空输入框），但希望下次按该文本过滤时仍基于全量数据（100 条），则应在 reloadGrid 前调用：
// 保持搜索框文本不变，但强制重新初始化过滤器逻辑
$("#grid_id")[0].refreshFilterToolbar();该方法会重新绑定搜索事件、重置内部过滤器状态，确保后续 onchange 或回车触发的搜索均作用于服务器返回的完整数据集。
? 总结与最佳实践
- ❌ 避免仅调用 reloadGrid()：它不重置搜索上下文，导致“过滤嵌套”；
- ✅ 每次需要回归原始数据源时，优先执行 clearToolbar(true)（清空+重置）或 refreshFilterToolbar()（保留文本+重置逻辑）；
- ✅ 确保 url 参数始终指向能返回全量数据（未预过滤）的服务端接口；
- ✅ 在模态框保存成功回调中统一调用上述刷新逻辑，避免状态不一致；
- ? 参考文档：Guriddo jqGrid – Toolbar Searching Methods
通过以上方式，即可彻底解决搜索状态“污染”原始数据源的问题，保障用户体验与数据一致性。
