`<t:dgCol>`标签中`query="true"`未生效，无法触发查询条件

Question

在使用 `` 标签时，常出现查询条件未生效的问题，表现为前端未生成对应查询输入框或点击查询无响应。主要原因为：`` 所在的 `` 未启用 `queryMode="single"` 或 `query="true"`，导致 query 属性不被解析；此外，字段未设置 `title` 或 `field` 属性，或 `field` 与实体字段不匹配，也会使查询功能失效。部分框架版本还存在对自定义查询操作需配合 `queryParam` 手动注册的限制。建议检查 datagrid 的 query 配置、字段映射及框架文档兼容性，确保 query 模式正确开启。

Answer 1

一、问题背景与常见现象

在使用前端数据表格组件（如DataGrid）进行开发时，开发者常通过``标签定义查询字段。然而，实际运行中经常出现“查询条件未生效”的问题，具体表现为：

• 前端未生成对应的查询输入框；
• 点击查询按钮无响应或参数未传递；
• 后端接收不到预期的查询参数；
• 页面渲染正常但交互功能缺失。

这些问题严重影响了系统的可用性和开发效率，尤其在复杂业务场景下更易暴露配置疏漏。

二、核心原因分析（由浅入深）

1. 未启用查询模式：DataGrid 的列定义中，若未设置 queryMode="single" 或 query="true"，框架将不会解析该列为可查询字段。
2. 属性缺失或拼写错误：缺少 title（显示名称）或 field（绑定字段名），导致无法生成表单控件。
3. 字段映射不一致：field 值与后端实体类字段不匹配，造成参数传输失败或被忽略。
4. 版本兼容性限制：部分旧版框架要求手动注册 queryParam 才能支持自定义查询逻辑。
5. 动态列加载问题：异步获取列配置时未正确触发 query 机制重初始化。

三、典型代码示例对比

配置项	错误示例	正确示例
query 属性	{ field: 'userName' }	{ field: 'userName', query: true }
queryMode 设置	<DataGrid />	<DataGrid queryMode="single" />
字段绑定	{ title: '', field: 'user_name_db' }	{ title: '用户名', field: 'userName' }

四、解决方案与最佳实践

// 正确的列定义方式
const columns = [
  {
    title: '用户姓名',
    field: 'realName',
    query: true,
    component: 'input'
  },
  {
    title: '注册时间',
    field: 'createTime',
    query: true,
    component: 'datePicker',
    queryParam: 'startTime' // 自定义参数名
  }
];

// DataGrid 主容器必须开启 queryMode
<DataGrid 
  data={data} 
  columns={columns} 
  queryMode="single" 
  onQuery={handleQuery}
/>
    

五、调试流程图

graph TD
            A[开始] --> B{DataGrid 是否设置 queryMode?}
            B -- 否 --> C[添加 queryMode="single"]
            B -- 是 --> D{列定义是否包含 query=true?}
            D -- 否 --> E[为需要查询的列添加 query=true]
            D -- 是 --> F{field 与后端字段是否匹配?}
            F -- 否 --> G[调整 field 映射或使用 queryParam 转换]
            F -- 是 --> H[检查组件渲染及事件绑定]
            H --> I[完成修复]

六、高级注意事项

• 某些框架（如 iBoxDB、EasyUI Fork 版本）需显式引入 QueryPlugin 插件才能启用高级查询。
• 使用 TypeScript 时建议定义 IQueryColumn 接口以约束列配置结构。
• 对于复合查询（如区间日期），应使用 range: true 并配合双字段绑定。
• 国际化环境下，title 应通过语言包注入，避免硬编码影响可维护性。
• 可通过覆写 transformQueryParams 方法统一处理参数格式化。
• 建议在开发阶段启用 debug 模式，输出 query 构建日志便于排查。