@nokecy/qc-ui 1.1.86 → 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/errors/types.d.ts

@@ -51,6 +51,15 @@ export declare class GridPlusError extends Error {
      * 获取用户友好的错误消息
      */
     getUserMessage(): string;
+    /**
+     * 获取 ABP 远程服务返回的业务错误，供提示和列表空态保留准确原因。
+     *
+     * @author nokecy
+     */
+    getRemoteServiceError(): {
+        code?: string;
+        message?: string;
+    } | undefined;
     /**
      * 获取错误详情(用于日志)
      */

package/dist/esm/ag-grid-plus/errors/types.js

@@ -84,6 +84,12 @@ export var GridPlusError = /*#__PURE__*/function (_Error) {
   _createClass(GridPlusError, [{
     key: "getUserMessage",
     value: function getUserMessage() {
+      var _this$getRemoteServic;
+      var remoteMessage = (_this$getRemoteServic = this.getRemoteServiceError()) === null || _this$getRemoteServic === void 0 ? void 0 : _this$getRemoteServic.message;
+      if (remoteMessage) {
+        return remoteMessage;
+      }
+
       // 在生产环境下,返回更友好的消息
       if (process.env.NODE_ENV === 'production') {
         switch (this.type) {
@@ -106,6 +112,20 @@ export var GridPlusError = /*#__PURE__*/function (_Error) {
       return this.message;
     }
 
+    /**
+     * 获取 ABP 远程服务返回的业务错误，供提示和列表空态保留准确原因。
+     *
+     * @author nokecy
+     */
+  }, {
+    key: "getRemoteServiceError",
+    value: function getRemoteServiceError() {
+      var _this$context$origina, _this$context, _response;
+      var originalError = (_this$context$origina = (_this$context = this.context) === null || _this$context === void 0 ? void 0 : _this$context.originalError) !== null && _this$context$origina !== void 0 ? _this$context$origina : this.originalError;
+      var remoteError = originalError === null || originalError === void 0 || (_response = originalError.response) === null || _response === void 0 || (_response = _response.data) === null || _response === void 0 ? void 0 : _response.error;
+      return remoteError && _typeof(remoteError) === 'object' ? remoteError : undefined;
+    }
+
     /**
      * 获取错误详情(用于日志)
      */

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
      */