@nokecy/qc-ui 1.1.87 → 1.1.88

package/dist/esm/ag-grid-plus/ag-gridPlus.js

@@ -77,6 +77,7 @@ function useDeepCompareStable(value) {
   return ref.current;
 }
 function AgGridPlus(props) {
+  var _ref;
   var gridTheme = useAgGridTheme();
   var _theme$useToken = theme.useToken(),
     token = _theme$useToken.token; // 高级筛选入口跟随主题及客户主色。@author nokecy
@@ -228,35 +229,6 @@ function AgGridPlus(props) {
     _useState28 = _slicedToArray(_useState27, 2),
     advancedQueryRules = _useState28[0],
     setAdvancedQueryRules = _useState28[1];
-
-  /**
-   * 【P1 架构优化】使用单向数据流架构
-   *
-   * 数据流层次：
-   * 1. Source of Truth: useSchemeDataFlow (Scheme State)
-   * 2. Derived State: derivedColumnDefs/derivedColumnState (只读派生)
-   * 3. UI State: Context State (仅用于 UI 交互)
-   *
-   * 优势：
-   * - 清晰的数据流向（单向可追踪）
-   * - 消除状态同步冲突（单一数据源）
-   * - 架构清晰度 +60%，Bug -40%
-   */
-  var schemeDataFlow = useSchemeDataFlow(gridKey || '', allColDefsRef.current, {
-    columnSchemes: columnSchemes,
-    querySchemes: querySchemes,
-    currentSchemes: currentSchemes
-  });
-
-  // 解构单向数据流的数据
-  var currentColumnSchemes = schemeDataFlow.columnSchemes,
-    currentColumnScheme = schemeDataFlow.currentColumnScheme,
-    currentQuerySchemes = schemeDataFlow.querySchemes,
-    currentQueryScheme = schemeDataFlow.currentQueryScheme,
-    derivedColumnDefs = schemeDataFlow.derivedColumnDefs,
-    derivedColumnState = schemeDataFlow.derivedColumnState,
-    isUsingGlobalFallback = schemeDataFlow.isUsingGlobalFallback,
-    isUsingGlobalQueryFallback = schemeDataFlow.isUsingGlobalQueryFallback;
   useImperativeHandle(propsGridRef, function () {
     return gridRef.current;
   });
@@ -313,117 +285,6 @@ function AgGridPlus(props) {
 
   // 用于列类型推断的首行数据。为什么必须是 state 而不是 ref,见该 hook 的注释。@author nokecy
   var typeInferenceRow = useTypeInferenceRow(rowData);
-
-  /**
-   * 【P0 + P1 优化】使用派生状态应用方案（单向数据流）
-   *
-   * 优势：
-   * 1. 使用已派生的状态，避免重复计算
-   * 2. 单向数据流，状态同步更可靠
-   * 3. 性能提升 67%，代码更清晰
-   * 4. 使用 Promise 链和 requestAnimationFrame 解决竞态条件
-   */
-  useEffect(function () {
-    if (!gridKey || !apiRef.current) return;
-
-    // 使用 Promise 链确保顺序执行，避免竞态条件
-    var cancelled = false;
-    Promise.resolve().then(function () {
-      if (cancelled || !apiRef.current) return;
-
-      // 1. 应用派生的列状态（使用 applyColumnState API）
-      if (derivedColumnState && derivedColumnState.length > 0) {
-        // 使用 applyColumnState 而不是 setGridOption("columnDefs")
-        apiRef.current.applyColumnState({
-          state: derivedColumnState,
-          applyOrder: true // 应用列顺序
-        });
-      }
-
-      // 2. 应用派生的列样式
-      if (derivedColumnState) {
-        setColumnCellClass(handelgridPlusColumnState(derivedColumnState));
-      }
-    }).then(function () {
-      // 等待 Grid 状态稳定（使用 requestAnimationFrame 而非固定延迟）
-      return new Promise(function (resolve) {
-        if (cancelled) {
-          resolve();
-          return;
-        }
-        requestAnimationFrame(function () {
-          // 双重 RAF 确保渲染完成
-          requestAnimationFrame(function () {
-            return resolve();
-          });
-        });
-      });
-    }).then(function () {
-      if (cancelled || !apiRef.current) return;
-
-      // 3. 应用过滤器（在列状态稳定后执行）
-      if (currentColumnScheme !== null && currentColumnScheme !== void 0 && currentColumnScheme.filterModel) {
-        apiRef.current.setFilterModel(currentColumnScheme.filterModel);
-      }
-    }).catch(function (error) {
-      if (!cancelled) {
-        console.error('[AgGridPlus] 应用方案失败:', error);
-        logger.error('[AgGridPlus] 应用方案失败', error);
-      }
-    });
-
-    // 清理函数：取消进行中的操作
-    return function () {
-      cancelled = true;
-    };
-  }, [gridKey, currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id, derivedColumnState, ready // 添加 ready 依赖，确保 Grid 初始化完成后再应用方案
-  ]);
-
-  /**
-   * 【新增】监听当前方案 ID 变化，当方案被删除时重置列状态
-   *
-   * 场景：
-   * - 用户删除当前正在使用的方案
-   * - currentColumnScheme?.id 从有值变为 null
-   *
-   * 行为：
-   * - 重置列状态为初始状态（默认顺序、宽度等）
-   * - 清除所有过滤器
-   * - 清除列样式配置
-   *
-   * 优势：
-   * - 符合单向数据流架构
-   * - 适用于所有方案切换场景（删除/取消选择）
-   * - 用户体验好，自动恢复到初始状态
-   */
-  var prevSchemeIdRef = useRef(currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id);
-  useEffect(function () {
-    if (!gridKey || !apiRef.current || !ready) return;
-    var prevSchemeId = prevSchemeIdRef.current;
-    var currentSchemeId = currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id;
-
-    // 检测方案被删除：从有值变为 null/undefined
-    if (prevSchemeId && !currentSchemeId) {
-      Promise.resolve().then(function () {
-        if (!apiRef.current) return;
-
-        // 1. 重置列状态为初始状态
-        apiRef.current.resetColumnState();
-
-        // 2. 清除所有过滤器
-        apiRef.current.setFilterModel(null);
-
-        // 3. 清除列样式配置
-        setColumnCellClass({});
-      }).catch(function (error) {
-        console.error('[AgGridPlus] 重置列状态失败:', error);
-        logger.error('[AgGridPlus] 重置列状态失败', error);
-      });
-    }
-
-    // 更新引用
-    prevSchemeIdRef.current = currentSchemeId;
-  }, [gridKey, currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id, ready]);
   useEffect(function () {
     setRowData(dataSource || propRowData || []);
   }, [dataSource, propRowData]);
@@ -562,6 +423,147 @@ function AgGridPlus(props) {
     return cols;
   }, [React.Children.count(children), props.columnDefs, extensibleColumns, gridKey, entityType, hostEntityExtensions, typeInferenceRow, valueEnumContrast ? token.colorBgContainer : undefined]);
 
+  // 方案派生依赖本轮源码列，避免读取尚未更新的 ref 快照。@author nokecy
+  /**
+   * 【P1 架构优化】使用单向数据流架构
+   *
+   * 数据流层次：
+   * 1. Source of Truth: useSchemeDataFlow (Scheme State)
+   * 2. Derived State: derivedColumnDefs/derivedColumnState (只读派生)
+   * 3. UI State: Context State (仅用于 UI 交互)
+   *
+   * 优势：
+   * - 清晰的数据流向（单向可追踪）
+   * - 消除状态同步冲突（单一数据源）
+   * - 架构清晰度 +60%，Bug -40%
+   */
+  var schemeDataFlow = useSchemeDataFlow(gridKey || '', allColDefs, {
+    columnSchemes: columnSchemes,
+    querySchemes: querySchemes,
+    currentSchemes: currentSchemes
+  });
+
+  // 解构单向数据流的数据
+  var currentColumnSchemes = schemeDataFlow.columnSchemes,
+    currentColumnScheme = schemeDataFlow.currentColumnScheme,
+    currentQuerySchemes = schemeDataFlow.querySchemes,
+    currentQueryScheme = schemeDataFlow.currentQueryScheme,
+    derivedColumnDefs = schemeDataFlow.derivedColumnDefs,
+    derivedColumnState = schemeDataFlow.derivedColumnState,
+    isUsingGlobalFallback = schemeDataFlow.isUsingGlobalFallback,
+    isUsingGlobalQueryFallback = schemeDataFlow.isUsingGlobalQueryFallback;
+
+  /**
+   * 【P0 + P1 优化】使用派生状态应用方案（单向数据流）
+   *
+   * 优势：
+   * 1. 使用已派生的状态，避免重复计算
+   * 2. 单向数据流，状态同步更可靠
+   * 3. 性能提升 67%，代码更清晰
+   * 4. 使用 Promise 链和 requestAnimationFrame 解决竞态条件
+   */
+  useEffect(function () {
+    if (!gridKey || !apiRef.current) return;
+
+    // 使用 Promise 链确保顺序执行，避免竞态条件
+    var cancelled = false;
+    Promise.resolve().then(function () {
+      if (cancelled || !apiRef.current) return;
+
+      // 1. 应用派生的列状态（使用 applyColumnState API）
+      if (derivedColumnState && derivedColumnState.length > 0) {
+        // 使用 applyColumnState 而不是 setGridOption("columnDefs")
+        apiRef.current.applyColumnState({
+          state: derivedColumnState,
+          applyOrder: true // 应用列顺序
+        });
+      }
+
+      // 2. 应用派生的列样式
+      if (derivedColumnState) {
+        setColumnCellClass(handelgridPlusColumnState(derivedColumnState));
+      }
+    }).then(function () {
+      // 等待 Grid 状态稳定（使用 requestAnimationFrame 而非固定延迟）
+      return new Promise(function (resolve) {
+        if (cancelled) {
+          resolve();
+          return;
+        }
+        requestAnimationFrame(function () {
+          // 双重 RAF 确保渲染完成
+          requestAnimationFrame(function () {
+            return resolve();
+          });
+        });
+      });
+    }).then(function () {
+      if (cancelled || !apiRef.current) return;
+
+      // 3. 应用过滤器（在列状态稳定后执行）
+      if (currentColumnScheme !== null && currentColumnScheme !== void 0 && currentColumnScheme.filterModel) {
+        apiRef.current.setFilterModel(currentColumnScheme.filterModel);
+      }
+    }).catch(function (error) {
+      if (!cancelled) {
+        console.error('[AgGridPlus] 应用方案失败:', error);
+        logger.error('[AgGridPlus] 应用方案失败', error);
+      }
+    });
+
+    // 清理函数：取消进行中的操作
+    return function () {
+      cancelled = true;
+    };
+  }, [gridKey, currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id, derivedColumnState, ready // 添加 ready 依赖，确保 Grid 初始化完成后再应用方案
+  ]);
+
+  /**
+   * 【新增】监听当前方案 ID 变化，当方案被删除时重置列状态
+   *
+   * 场景：
+   * - 用户删除当前正在使用的方案
+   * - currentColumnScheme?.id 从有值变为 null
+   *
+   * 行为：
+   * - 重置列状态为初始状态（默认顺序、宽度等）
+   * - 清除所有过滤器
+   * - 清除列样式配置
+   *
+   * 优势：
+   * - 符合单向数据流架构
+   * - 适用于所有方案切换场景（删除/取消选择）
+   * - 用户体验好，自动恢复到初始状态
+   */
+  var prevSchemeIdRef = useRef(currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id);
+  useEffect(function () {
+    if (!gridKey || !apiRef.current || !ready) return;
+    var prevSchemeId = prevSchemeIdRef.current;
+    var currentSchemeId = currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id;
+
+    // 检测方案被删除：从有值变为 null/undefined
+    if (prevSchemeId && !currentSchemeId) {
+      Promise.resolve().then(function () {
+        if (!apiRef.current) return;
+
+        // 1. 重置列状态为初始状态
+        apiRef.current.resetColumnState();
+
+        // 2. 清除所有过滤器
+        apiRef.current.setFilterModel(null);
+
+        // 3. 清除列样式配置
+        setColumnCellClass({});
+      }).catch(function (error) {
+        console.error('[AgGridPlus] 重置列状态失败:', error);
+        logger.error('[AgGridPlus] 重置列状态失败', error);
+      });
+    }
+
+    // 更新引用
+    prevSchemeIdRef.current = currentSchemeId;
+  }, [gridKey, currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id, ready]);
+
   // 稳定化 gridParams 和 sortColumn 的引用(深比较,内容不变即复用旧引用)
   var stableGridParams = useDeepCompareStable(gridParams);
   var stableSortColumn = useDeepCompareStable(sortColumn);
@@ -1010,10 +1012,11 @@ function AgGridPlus(props) {
 
   // 构建查询表单项（带 order 属性）
   var queryFormItems = useMemo(function () {
-    var _allColDefs$filter;
-    var items = (allColDefs === null || allColDefs === void 0 || (_allColDefs$filter = allColDefs.filter(function (col) {
+    var _flattenColumnState;
+    // 查询方案按叶列排序和隐藏，分组本身不作为查询字段。@author nokecy
+    var items = ((_flattenColumnState = flattenColumnState(allColDefs)) === null || _flattenColumnState === void 0 || (_flattenColumnState = _flattenColumnState.filter(function (col) {
       return col.filter !== false && !col.hideInSearch;
-    })) === null || _allColDefs$filter === void 0 ? void 0 : _allColDefs$filter.map(function (col) {
+    })) === null || _flattenColumnState === void 0 ? void 0 : _flattenColumnState.map(function (col) {
       var _col$queryField, _col$searchSort;
       return _objectSpread({
         field: (_col$queryField = col.queryField) !== null && _col$queryField !== void 0 ? _col$queryField : col.field,
@@ -1145,8 +1148,9 @@ function AgGridPlus(props) {
     }
   }, search == false ? null : /*#__PURE__*/React.createElement(FormRender, {
     colDefs: flattenColumnState(visibleFormItems),
+    effectiveColDefs: flattenColumnState(colDefs),
     defaultRows: queryDefaultRows,
-    columnStates: columnState || [],
+    columnStates: (_ref = derivedColumnState !== null && derivedColumnState !== void 0 ? derivedColumnState : columnState) !== null && _ref !== void 0 ? _ref : [],
     defaultExpand: defaultSearchExpand,
     gridApi: apiRef.current,
     onQuery: function onQuery(formValues) {

package/dist/esm/ag-grid-plus/context/useSchemeDataFlow.js

@@ -171,8 +171,8 @@ export function useDerivedGridState(currentScheme, allColDefs) {
       console.error('[useDerivedGridState] 转换失败:', error);
       return null;
     }
-  }, [// 使用 scheme.id 作为依赖，避免深度对象比较
-  currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, allColDefs]);
+  }, [// 同一方案的内容修改也要重新派生，保持表格与查询区使用相同快照。@author nokecy
+  currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.columnConfig, allColDefs]);
 }
 
 /**
@@ -207,8 +207,8 @@ export function useDerivedColumnState(currentScheme, allColDefs) {
       console.error('[useDerivedColumnState] 转换失败:', error);
       return null;
     }
-  }, [// 使用 scheme.id 作为依赖
-  currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, allColDefs]);
+  }, [// 同一方案保存后 columnConfig 会更新，不能只比较方案 ID。@author nokecy
+  currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.columnConfig, allColDefs]);
 }
 
 /**

package/dist/esm/ag-grid-plus/interface.d.ts

@@ -144,6 +144,8 @@ interface AgGridColumnPropsClone extends ColDef {
     hideInTable?: boolean;
     hideInSearch?: boolean;
     queryField?: string;
+    /** 查询区独立标题；优先于列方案中的表头名称。@author nokecy */
+    searchTitle?: string;
     /**
      * 是否文本缩略显示,并使用tooltip
      */

package/dist/esm/ag-grid-plus/queryForm/index.d.ts

@@ -5,6 +5,8 @@ declare const FormRender: (props: {
     className?: any;
     gridApi?: GridApi<any> | undefined;
     colDefs: ColDef[];
+    /** 与表格同轮渲染的生效列定义快照。@author nokecy */
+    effectiveColDefs?: ColDef<any, any>[] | undefined;
     columnStates: ColumnState[];
     defaultExpand?: Boolean | undefined;
     defaultRows?: number | undefined;

package/dist/esm/ag-grid-plus/queryForm/index.js

@@ -12,26 +12,28 @@ function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" !=
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { DatePicker, FormButtonGroup, FormGrid, FormItem, Form, Input, Select, Submit } from '@formily/antd-v5'; // @author nokecy
 import { createForm } from '@formily/core';
-import { onFieldInit } from '@formily/core';
 import { createSchemaField } from '@formily/react';
 import { Button, theme } from 'antd';
 import classNames from 'classnames';
 import React, { useEffect, useMemo, useRef, useState } from 'react';
 import QueryForm from "./queryForm";
 import { queryFormSchemaKey } from "./schemaKey";
+import { resolveQueryColumns } from "./queryColumns";
 import BoolSelect from "../_utils/boolSelect";
 import "./index.less";
 var FormRender = function FormRender(props) {
   var className = props.className,
-    gridApi = props.gridApi,
     colDefs = props.colDefs,
+    _props$effectiveColDe = props.effectiveColDefs,
+    effectiveColDefs = _props$effectiveColDe === void 0 ? colDefs : _props$effectiveColDe,
     columnStates = props.columnStates,
     onQuery = props.onQuery,
     _props$defaultRows = props.defaultRows,
     defaultRows = _props$defaultRows === void 0 ? 1 : _props$defaultRows;
   var _theme$useToken = theme.useToken(),
     token = _theme$useToken.token; // 筛选区跟随宿主主题。@author nokecy
-
+  var queryColumns = resolveQueryColumns(colDefs, effectiveColDefs, columnStates);
+  var schemaKey = queryFormSchemaKey(undefined, queryColumns);
   var _useState = useState({
       type: 'object',
       properties: {}
@@ -39,25 +41,11 @@ var FormRender = function FormRender(props) {
     _useState2 = _slicedToArray(_useState, 2),
     schema = _useState2[0],
     setSchema = _useState2[1];
+
+  // 表单与 SchemaField 实例保持稳定，元数据更新不清空已输入的查询值。@author nokecy
   var form = useMemo(function () {
-    return createForm({
-      effects: function effects() {
-        return [onFieldInit('queryForm', function (field) {
-          field.query('queryForm').take(function (node) {
-            node.setComponentProps({
-              onReset: onReset,
-              defaultExpand: props.defaultExpand
-            });
-          });
-        })];
-      }
-    });
+    return createForm();
   }, []);
-
-  // 【修复】移除此处的 onInit 调用
-  // 原因：此时 schema 尚未设置，form.values 为空，默认值还未应用
-  // 改为在下方 schema 设置完成后调用 onInit
-
   var SchemaField = useMemo(function () {
     return createSchemaField({
       components: {
@@ -73,7 +61,7 @@ var FormRender = function FormRender(props) {
         BoolSelect: BoolSelect
       }
     });
-  }, [schema]);
+  }, []);
   var onSubmit = function onSubmit() {
     onQuery && onQuery(form.values);
   };
@@ -113,47 +101,31 @@ var FormRender = function FormRender(props) {
       return component ? component : "Input";
     }
   };
-  var getSchema = function getSchema(reset) {
-    var _columns, _columns2;
+  var getSchema = function getSchema() {
     var rootSchema = {
       type: 'object',
       properties: {}
     };
-    if (!columnStates) {
-      return rootSchema;
-    }
     var gridSchema = {
       type: 'void',
       "name": 'queryForm',
       "x-component": 'QueryForm',
       properties: {},
       "x-component-props": {
-        defaultRows: defaultRows // 在这里添加defaultRows参数
+        defaultRows: defaultRows,
+        defaultExpand: props.defaultExpand,
+        onReset: onReset
       }
     };
-    var columns = colDefs === null || colDefs === void 0 ? void 0 : colDefs.map(function (colDef) {
-      var _searchComponentProps;
-      var state = columnStates.find(function (x) {
-        return x.colId == colDef.field;
-      });
-      var columnDefs = gridApi === null || gridApi === void 0 ? void 0 : gridApi.getColumnDef(colDef.field);
-      // 查询组件属性（下拉选项）以本次传入的列为准：AG Grid 在本副作用之后才应用新 columnDefs，此刻取到的还是上一版。@author nokecy
-      return _objectSpread(_objectSpread(_objectSpread(_objectSpread({}, colDef), columnDefs), state), {}, {
-        searchComponentProps: (_searchComponentProps = colDef.searchComponentProps) !== null && _searchComponentProps !== void 0 ? _searchComponentProps : columnDefs === null || columnDefs === void 0 ? void 0 : columnDefs.searchComponentProps
-      });
-    });
-    columns = columns ? (_columns = columns) === null || _columns === void 0 ? void 0 : _columns.filter(function (i) {
-      return (i === null || i === void 0 ? void 0 : i.visible) != false && !(i !== null && i !== void 0 && i.hide) && !(i !== null && i !== void 0 && i.hideInSearch) || (i === null || i === void 0 ? void 0 : i.hideInTable);
-    }) : [];
-    columns.map(function (col) {
-      var _colDef$queryField;
+    queryColumns.forEach(function (col) {
+      var _colDef$queryField, _colDef$searchTitle;
       var colDef = col;
       var name = (_colDef$queryField = colDef.queryField) !== null && _colDef$queryField !== void 0 ? _colDef$queryField : colDef.field;
-      var headerName = colDef.headerName;
+      var headerName = (_colDef$searchTitle = colDef.searchTitle) !== null && _colDef$searchTitle !== void 0 ? _colDef$searchTitle : colDef.headerName;
       //表单自定义组件
       var component = getComponent(colDef);
       if (colDef.filter != false) {
-        var _colDef$searchCompone, _colDef$searchCompone2, _colDef$searchCompone3;
+        var _colDef$searchCompone, _colDef$searchCompone2, _colDef$searchCompone3, _colDef$searchCompone4;
         // 为多选下拉框添加maxTagCount配置
         var componentProps = _objectSpread({
           placeholder: "\u8BF7\u8F93\u5165".concat(headerName),
@@ -175,7 +147,7 @@ var FormRender = function FormRender(props) {
           type: 'string',
           title: headerName,
           required: (colDef === null || colDef === void 0 || (_colDef$searchCompone = colDef.searchComponentProps) === null || _colDef$searchCompone === void 0 ? void 0 : _colDef$searchCompone.required) || false,
-          default: (colDef === null || colDef === void 0 || (_colDef$searchCompone2 = colDef.searchComponentProps) === null || _colDef$searchCompone2 === void 0 ? void 0 : _colDef$searchCompone2.default) || (colDef === null || colDef === void 0 || (_colDef$searchCompone3 = colDef.searchComponentProps) === null || _colDef$searchCompone3 === void 0 ? void 0 : _colDef$searchCompone3.defaultValue),
+          default: (_colDef$searchCompone2 = colDef === null || colDef === void 0 || (_colDef$searchCompone3 = colDef.searchComponentProps) === null || _colDef$searchCompone3 === void 0 ? void 0 : _colDef$searchCompone3.default) !== null && _colDef$searchCompone2 !== void 0 ? _colDef$searchCompone2 : colDef === null || colDef === void 0 || (_colDef$searchCompone4 = colDef.searchComponentProps) === null || _colDef$searchCompone4 === void 0 ? void 0 : _colDef$searchCompone4.defaultValue,
           enum: colDef === null || colDef === void 0 ? void 0 : colDef.enum,
           "x-component": component,
           "x-component-props": componentProps,
@@ -190,7 +162,7 @@ var FormRender = function FormRender(props) {
     });
     ///@ts-ignore
     rootSchema.properties["queryForm"] = gridSchema;
-    if (!((_columns2 = columns) !== null && _columns2 !== void 0 && _columns2.length)) {
+    if (!queryColumns.length) {
       ///@ts-ignore
       delete rootSchema.properties["queryForm"];
     }
@@ -199,18 +171,40 @@ var FormRender = function FormRender(props) {
 
   // 【新增】用于追踪是否已完成首次初始化
   var initializedRef = useRef(false);
+  var previousFieldsRef = useRef([]);
   useEffect(function () {
     var _new_schema$propertie, _new_schema$propertie2;
-    var new_schema = getSchema(onReset);
+    var new_schema = getSchema();
+    var fieldSchemas = (_new_schema$propertie = (_new_schema$propertie2 = new_schema.properties) === null || _new_schema$propertie2 === void 0 || (_new_schema$propertie2 = _new_schema$propertie2.queryForm) === null || _new_schema$propertie2 === void 0 ? void 0 : _new_schema$propertie2.properties) !== null && _new_schema$propertie !== void 0 ? _new_schema$propertie : {};
+    // 移除失效查询项的字段图和值，避免界面已经移除却仍提交旧筛选。@author nokecy
+    previousFieldsRef.current.filter(function (name) {
+      return !(name in fieldSchemas);
+    }).forEach(function (name) {
+      form.clearFormGraph(name);
+      form.deleteValuesIn(name);
+      form.deleteInitialValuesIn(name);
+    });
+    previousFieldsRef.current = Object.keys(fieldSchemas);
     setSchema(new_schema);
-    // Formily 只在字段首次创建时读取 schema：已有查询项要把新标题、组件属性（如下拉选项）写回字段。@author nokecy
-    Object.entries((_new_schema$propertie = (_new_schema$propertie2 = new_schema.properties) === null || _new_schema$propertie2 === void 0 || (_new_schema$propertie2 = _new_schema$propertie2.queryForm) === null || _new_schema$propertie2 === void 0 ? void 0 : _new_schema$propertie2.properties) !== null && _new_schema$propertie !== void 0 ? _new_schema$propertie : {}).forEach(function (_ref) {
+    // 已有字段同步元数据，不触碰仍有效字段的查询值，也不触发查询。@author nokecy
+    Object.entries(fieldSchemas).forEach(function (_ref) {
       var _ref2 = _slicedToArray(_ref, 2),
         name = _ref2[0],
         fieldSchema = _ref2[1];
       form.query(name).take(function (field) {
+        var _fieldSchema$enum;
         field.title = fieldSchema.title;
-        field.setComponentProps(fieldSchema['x-component-props']);
+        field.required = fieldSchema.required;
+        // Select 会把 dataSource 映射为 options；仅配置 options 时也同步该数据源。@author nokecy
+        field.dataSource = (_fieldSchema$enum = fieldSchema.enum) !== null && _fieldSchema$enum !== void 0 ? _fieldSchema$enum : fieldSchema['x-component-props'].options;
+        field.component = [fieldSchema['x-component'], fieldSchema['x-component-props']];
+      });
+    });
+    form.query('queryForm').take(function (field) {
+      return field.setComponentProps({
+        defaultRows: defaultRows,
+        defaultExpand: props.defaultExpand,
+        onReset: onReset
       });
     });
 
@@ -225,7 +219,7 @@ var FormRender = function FormRender(props) {
         }, 0);
       });
     }
-  }, [queryFormSchemaKey(columnStates, colDefs)]);
+  }, [schemaKey, defaultRows, props.defaultExpand]);
   return /*#__PURE__*/React.createElement("div", {
     className: classNames(className, "ag-grid-table-search ag-grid-table-search-query-filter"),
     style: {
@@ -234,6 +228,7 @@ var FormRender = function FormRender(props) {
   }, /*#__PURE__*/React.createElement(Form, {
     form: form,
     labelWidth: 100,
+    labelWrap: true,
     feedbackLayout: "none",
     onAutoSubmit: onSubmit
   }, /*#__PURE__*/React.createElement(SchemaField, {

package/dist/esm/ag-grid-plus/queryForm/queryColumns.d.ts

@@ -0,0 +1,8 @@
+import type { ColumnState } from 'ag-grid-community';
+import type { ExtendedColDef } from '../types';
+/**
+ * 从同一轮渲染的列定义快照派生查询项，不在副作用中读取 AG Grid 的上一轮定义。
+ * 表头名称跟随生效列方案；查询专用元数据和独立标题由页面声明。
+ * @author nokecy
+ */
+export declare const resolveQueryColumns: (sourceColumns: readonly ExtendedColDef[], effectiveColumns: readonly ExtendedColDef[], columnStates: readonly ColumnState[]) => ExtendedColDef[];

package/dist/esm/ag-grid-plus/queryForm/queryColumns.js

@@ -0,0 +1,46 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/**
+ * 从同一轮渲染的列定义快照派生查询项，不在副作用中读取 AG Grid 的上一轮定义。
+ * 表头名称跟随生效列方案；查询专用元数据和独立标题由页面声明。
+ * @author nokecy
+ */
+export var resolveQueryColumns = function resolveQueryColumns(sourceColumns, effectiveColumns, columnStates) {
+  var effectiveById = new Map();
+  effectiveColumns.forEach(function (column) {
+    if (column.colId) effectiveById.set(column.colId, column);
+    if (column.field) effectiveById.set(column.field, column);
+  });
+  var stateById = new Map(columnStates.map(function (state) {
+    return [state.colId, state];
+  }));
+  return sourceColumns.map(function (source) {
+    var _source$colId, _ref, _state$hide, _effective$headerName;
+    var columnId = (_source$colId = source.colId) !== null && _source$colId !== void 0 ? _source$colId : source.field;
+    var effective = columnId ? effectiveById.get(columnId) : undefined;
+    var state = columnId ? stateById.get(columnId) : undefined;
+    return _objectSpread(_objectSpread(_objectSpread({}, source), effective), {}, {
+      // 查询只使用列状态的显隐；null 表示沿用生效列定义。@author nokecy
+      hide: (_ref = (_state$hide = state === null || state === void 0 ? void 0 : state.hide) !== null && _state$hide !== void 0 ? _state$hide : effective === null || effective === void 0 ? void 0 : effective.hide) !== null && _ref !== void 0 ? _ref : source.hide,
+      // 查询元数据不从持久表格方案反向覆盖源码。@author nokecy
+      field: source.field,
+      queryField: source.queryField,
+      headerName: (_effective$headerName = effective === null || effective === void 0 ? void 0 : effective.headerName) !== null && _effective$headerName !== void 0 ? _effective$headerName : source.headerName,
+      searchTitle: source.searchTitle,
+      hideInSearch: source.hideInSearch,
+      hideInTable: source.hideInTable,
+      filter: source.filter,
+      type: source.type,
+      enum: source.enum,
+      searchComponent: source.searchComponent,
+      searchComponentProps: source.searchComponentProps
+    });
+  }).filter(function (column) {
+    var _column$queryField;
+    return Boolean((_column$queryField = column.queryField) !== null && _column$queryField !== void 0 ? _column$queryField : column.field) && column.filter !== false && !column.hideInSearch && (column.hideInTable || column.visible !== false && !column.hide);
+  });
+};