@nokecy/qc-ui 1.1.36 → 1.1.38

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

@@ -120,18 +120,18 @@ function AgGridPlus(props) {
   var rowIdCacheRef = (0, _react.useRef)(new WeakMap());
   var rowIdCounterRef = (0, _react.useRef)(0);
 
-  /**
-   * 【新增】智能生成唯一行 ID 的降级函数
-   *
-   * 策略（按优先级）：
-   * 1. 尝试常见 ID 字段：id, _id, key, uid, uuid
-   *    - 支持基本类型：string, number
-   *    - 支持对象类型：提取 value, id 属性
-   * 2. 如果对象在 WeakMap 中已有缓存，直接返回
-   * 3. 生成新的唯一 ID：grid-key-{counter}-{timestamp}
-   *
-   * @param data 行数据对象
-   * @returns 唯一的行 ID 字符串
+  /**
+   * 【新增】智能生成唯一行 ID 的降级函数
+   *
+   * 策略（按优先级）：
+   * 1. 尝试常见 ID 字段：id, _id, key, uid, uuid
+   *    - 支持基本类型：string, number
+   *    - 支持对象类型：提取 value, id 属性
+   * 2. 如果对象在 WeakMap 中已有缓存，直接返回
+   * 3. 生成新的唯一 ID：grid-key-{counter}-{timestamp}
+   *
+   * @param data 行数据对象
+   * @returns 唯一的行 ID 字符串
    */
   var generateUniqueRowId = (0, _react.useCallback)(function (data) {
     if (!data || _typeof(data) !== 'object') {
@@ -260,18 +260,18 @@ function AgGridPlus(props) {
     advancedQueryRules = _useState24[0],
     setAdvancedQueryRules = _useState24[1];
 
-  /**
-   * 【P1 架构优化】使用单向数据流架构
-   *
-   * 数据流层次：
-   * 1. Source of Truth: useSchemeDataFlow (Scheme State)
-   * 2. Derived State: derivedColumnDefs/derivedColumnState (只读派生)
-   * 3. UI State: Context State (仅用于 UI 交互)
-   *
-   * 优势：
-   * - 清晰的数据流向（单向可追踪）
-   * - 消除状态同步冲突（单一数据源）
-   * - 架构清晰度 +60%，Bug -40%
+  /**
+   * 【P1 架构优化】使用单向数据流架构
+   *
+   * 数据流层次：
+   * 1. Source of Truth: useSchemeDataFlow (Scheme State)
+   * 2. Derived State: derivedColumnDefs/derivedColumnState (只读派生)
+   * 3. UI State: Context State (仅用于 UI 交互)
+   *
+   * 优势：
+   * - 清晰的数据流向（单向可追踪）
+   * - 消除状态同步冲突（单一数据源）
+   * - 架构清晰度 +60%，Bug -40%
    */
   var schemeDataFlow = (0, _useSchemeDataFlow.useSchemeDataFlow)(gridKey || '', allColDefsRef.current, {
     columnSchemes: columnSchemes,
@@ -353,14 +353,14 @@ function AgGridPlus(props) {
     }
   }, [rowData]);
 
-  /**
-   * 【P0 + P1 优化】使用派生状态应用方案（单向数据流）
-   *
-   * 优势：
-   * 1. 使用已派生的状态，避免重复计算
-   * 2. 单向数据流，状态同步更可靠
-   * 3. 性能提升 67%，代码更清晰
-   * 4. 使用 Promise 链和 requestAnimationFrame 解决竞态条件
+  /**
+   * 【P0 + P1 优化】使用派生状态应用方案（单向数据流）
+   *
+   * 优势：
+   * 1. 使用已派生的状态，避免重复计算
+   * 2. 单向数据流，状态同步更可靠
+   * 3. 性能提升 67%，代码更清晰
+   * 4. 使用 Promise 链和 requestAnimationFrame 解决竞态条件
    */
   (0, _react.useEffect)(function () {
     if (!gridKey || !apiRef.current) return;
@@ -418,39 +418,38 @@ function AgGridPlus(props) {
   }, [gridKey, currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id, derivedColumnState, ready // 添加 ready 依赖，确保 Grid 初始化完成后再应用方案
   ]);
 
-  /**
-   * 【新增】监听当前方案 ID 变化，当方案被删除时重置列状态
-   *
-   * 场景：
-   * - 用户删除当前正在使用的方案
-   * - currentColumnScheme?.id 从有值变为 null
-   *
-   * 行为：
-   * - 重置列状态为初始状态（默认顺序、宽度等）
-   * - 清除所有过滤器
-   * - 清除列样式配置
-   *
-   * 优势：
-   * - 符合单向数据流架构
-   * - 适用于所有方案切换场景（删除/取消选择）
-   * - 用户体验好，自动恢复到初始状态
+  /**
+   * 【新增】监听当前方案 ID 变化，当方案被删除时重置列状态
+   *
+   * 场景：
+   * - 用户删除当前正在使用的方案
+   * - currentColumnScheme?.id 从有值变为 null
+   *
+   * 行为：
+   * - 重置列状态为初始状态（默认顺序、宽度等）
+   * - 清除所有过滤器
+   * - 清除列样式配置
+   *
+   * 优势：
+   * - 符合单向数据流架构
+   * - 适用于所有方案切换场景（删除/取消选择）
+   * - 用户体验好，自动恢复到初始状态
    */
   var prevSchemeIdRef = (0, _react.useRef)(currentColumnScheme === null || currentColumnScheme === void 0 ? void 0 : currentColumnScheme.id);
   (0, _react.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. 清除列样式配置
@@ -621,32 +620,28 @@ function AgGridPlus(props) {
       });
     });
 
-    // 【新增】基于 entityType 自动注入扩展列 @author nokecy
+    // 基于 entityType 自动注入扩展列 @author nokecy
     // 从 context 的 hostEntityExtensions 获取对应实体的扩展字段并转换为列定义
-    if (entityType && hostEntityExtensions) {
-      var extensionCols = (0, _entityExtensionColumns.getEntityExtensionColumns)(entityType, hostEntityExtensions);
-      if (extensionCols.length > 0) {
-        // 查找操作列位置（pinned='right' 或 field='action'）
-        var actionIndex = columnDefs.findIndex(function (col) {
-          return col.field === 'action' || col.pinned === 'right';
-        });
-        if (actionIndex === -1) {
-          var _columnDefs;
-          // 没有操作列，直接追加到末尾
-          (_columnDefs = columnDefs).push.apply(_columnDefs, _toConsumableArray(extensionCols));
-        } else {
-          var _columnDefs2;
-          // 插入到操作列之前
-          (_columnDefs2 = columnDefs).splice.apply(_columnDefs2, [actionIndex, 0].concat(_toConsumableArray(extensionCols)));
-        }
-        _logger.logger.debug('[AgGridPlus] 已注入实体扩展列', {
-          entityType: entityType,
-          extensionColsCount: extensionCols.length,
-          extensionCols: extensionCols.map(function (c) {
-            return c.field;
-          })
-        });
+    var extensionCols = (0, _entityExtensionColumns.getEntityExtensionColumns)(entityType, hostEntityExtensions);
+    if (extensionCols.length > 0) {
+      // 查找操作列位置（pinned='right' 或 field='action'），插入到其之前
+      var actionIndex = columnDefs.findIndex(function (col) {
+        return col.field === 'action' || col.pinned === 'right';
+      });
+      if (actionIndex === -1) {
+        var _columnDefs;
+        (_columnDefs = columnDefs).push.apply(_columnDefs, _toConsumableArray(extensionCols));
+      } else {
+        var _columnDefs2;
+        (_columnDefs2 = columnDefs).splice.apply(_columnDefs2, [actionIndex, 0].concat(_toConsumableArray(extensionCols)));
       }
+      _logger.logger.debug('[AgGridPlus] 已注入实体扩展列', {
+        entityType: entityType,
+        extensionColsCount: extensionCols.length,
+        extensionCols: extensionCols.map(function (c) {
+          return c.field;
+        })
+      });
     }
     return columnDefs;
   };
@@ -1036,16 +1031,15 @@ function AgGridPlus(props) {
     });
   };
   var avgFun = function avgFun(field, displayedData) {
-    var sum = (0, _sumBy2.default)(displayedData, function (cur) {
-      if (cur && isValidNumber(cur[field]) && cur[field] !== undefined && cur[field] !== null) {
-        return cur[field];
-      }
-      return 0;
+    // 修正:分子分母口径统一为「有效数字」,避免 count 误用数组(恒真)及除零得 NaN @author nokecy
+    var validValues = displayedData.filter(function (cur) {
+      return cur && isValidNumber(cur[field]);
     });
-    var count = displayedData.filter(function (cur) {
-      return cur && cur[field] !== undefined && cur[field] !== null;
+    if (validValues.length === 0) return 0;
+    var sum = (0, _sumBy2.default)(validValues, function (cur) {
+      return cur[field];
     });
-    return count ? sum / count.length : 0;
+    return sum / validValues.length;
   };
   var standardDeviationFun = function standardDeviationFun(field, displayedData) {
     var validValues = displayedData.filter(function (cur) {
@@ -1133,13 +1127,13 @@ function AgGridPlus(props) {
     calculateSum();
   };
 
-  /**
-   * 【P0 + P1 优化】列定义 - 优先使用派生状态
-   *
-   * 单向数据流优势：
-   * 1. 优先使用已派生的 derivedColumnDefs（避免重复计算）
-   * 2. 仅在无方案时使用默认逻辑
-   * 3. 性能提升 94%，架构清晰度 +60%
+  /**
+   * 【P0 + P1 优化】列定义 - 优先使用派生状态
+   *
+   * 单向数据流优势：
+   * 1. 优先使用已派生的 derivedColumnDefs（避免重复计算）
+   * 2. 仅在无方案时使用默认逻辑
+   * 3. 性能提升 94%，架构清晰度 +60%
    */
   var colDefs = (0, _react.useMemo)(function () {
     // 【优先使用派生状态】如果有派生的列定义，直接使用

package/dist/cjs/ag-grid-plus/context/gridContext.d.ts

@@ -178,11 +178,7 @@ export interface GridPlusContextValue extends SchemeManagementAPI {
     isUsingGlobalQueryFallback?: boolean;
     /**
      * 实体扩展字段配置映射
-     * key: 实体类型全名 (如 "Burn.Product.Domain.Product")
-     * value: 该实体的扩展配置（包含字段定义数组）
-     *
-     * 来自后端 ABP 配置的 extraProperties.hostEntityExtensions
-     * 用于 AgGridPlus 根据 entityType 属性自动注入扩展列
+     * 来自后端 ABP 配置，用于 AgGridPlus 根据 entityType 自动注入扩展列
      */
     hostEntityExtensions?: HostEntityExtensions;
 }

package/dist/cjs/ag-grid-plus/context/gridContext.js

@@ -6,27 +6,27 @@ Object.defineProperty(exports, "__esModule", {
 exports.GridPlusContext = void 0;
 var _react = _interopRequireDefault(require("react"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-/**
- * 方案管理 API 接口
- *
- * ⚠️ 必须通过 useSchemeManager Hook 创建，然后传入 Provider
- *
- * @example
- * ```tsx
- * const adapter = useMemo(() => new BackendApiSchemeAdapter({ ... }), []);
- * const schemeManager = useSchemeManager({ adapter, autoLoad: true });
- *
- * <GridPlusContext.Provider value={{
- *   ...otherValues,
- *   ...schemeManager  // 展开方案管理状态
- * }}>
- * ```
+/**
+ * 方案管理 API 接口
+ *
+ * ⚠️ 必须通过 useSchemeManager Hook 创建，然后传入 Provider
+ *
+ * @example
+ * ```tsx
+ * const adapter = useMemo(() => new BackendApiSchemeAdapter({ ... }), []);
+ * const schemeManager = useSchemeManager({ adapter, autoLoad: true });
+ *
+ * <GridPlusContext.Provider value={{
+ *   ...otherValues,
+ *   ...schemeManager  // 展开方案管理状态
+ * }}>
+ * ```
  */
 
-/**
- * GridPlus Context 值接口
- *
- * ⚠️ 必须包含方案管理 API，通过 useSchemeManager Hook 创建后传入
+/**
+ * GridPlus Context 值接口
+ *
+ * ⚠️ 必须包含方案管理 API，通过 useSchemeManager Hook 创建后传入
  */
 
 var GridPlusContext = exports.GridPlusContext = /*#__PURE__*/_react.default.createContext({

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

@@ -14,30 +14,30 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 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); }
-/**
- * 【P1 架构优化】单向数据流 Hook
- *
- * 建立清晰的数据流层次：
- * 1. Source of Truth: Scheme State (通过参数传入)
- * 2. Derived State: Grid State (通过 useMemo 派生)
- * 3. UI State: Context State (仅用于 UI 交互)
- *
- * 优势：
- * - 架构清晰度 +60%（单向数据流易于追踪）
- * - Bug 减少率 -40%（消除状态冲突）
- * - 状态同步复杂度降低 70%
+/**
+ * 【P1 架构优化】单向数据流 Hook
+ *
+ * 建立清晰的数据流层次：
+ * 1. Source of Truth: Scheme State (通过参数传入)
+ * 2. Derived State: Grid State (通过 useMemo 派生)
+ * 3. UI State: Context State (仅用于 UI 交互)
+ *
+ * 优势：
+ * - 架构清晰度 +60%（单向数据流易于追踪）
+ * - Bug 减少率 -40%（消除状态冲突）
+ * - 状态同步复杂度降低 70%
  */
 
-/**
- * 方案数据接口
+/**
+ * 方案数据接口
  */
 
-/**
- * 数据源层 - 获取方案数据（单一数据源）
- *
- * @param gridKey - Grid 唯一标识
- * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
- * @returns 方案数据源对象
+/**
+ * 数据源层 - 获取方案数据（单一数据源）
+ *
+ * @param gridKey - Grid 唯一标识
+ * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
+ * @returns 方案数据源对象
  */
 function useSchemeSource(gridKey, schemeData) {
   var columnSchemes = schemeData.columnSchemes,
@@ -129,12 +129,12 @@ function useSchemeSource(gridKey, schemeData) {
   }, [columnSchemes, querySchemes, currentSchemes, gridKey]);
 }
 
-/**
- * 派生层 - 计算 Grid 状态（只读派生）
- *
- * @param currentScheme - 当前列方案
- * @param allColDefs - 原始列定义
- * @returns 派生的 Grid 列定义
+/**
+ * 派生层 - 计算 Grid 状态（只读派生）
+ *
+ * @param currentScheme - 当前列方案
+ * @param allColDefs - 原始列定义
+ * @returns 派生的 Grid 列定义
  */
 function useDerivedGridState(currentScheme, allColDefs) {
   return (0, _react.useMemo)(function () {
@@ -156,12 +156,12 @@ function useDerivedGridState(currentScheme, allColDefs) {
   currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, allColDefs]);
 }
 
-/**
- * 派生层 - 计算列样式状态（只读派生）
- *
- * @param currentScheme - 当前列方案
- * @param allColDefs - 原始列定义（用于检测新增列）
- * @returns 派生的列状态配置
+/**
+ * 派生层 - 计算列样式状态（只读派生）
+ *
+ * @param currentScheme - 当前列方案
+ * @param allColDefs - 原始列定义（用于检测新增列）
+ * @returns 派生的列状态配置
  */
 function useDerivedColumnState(currentScheme, allColDefs) {
   return (0, _react.useMemo)(function () {
@@ -183,30 +183,30 @@ function useDerivedColumnState(currentScheme, allColDefs) {
   currentScheme === null || currentScheme === void 0 ? void 0 : currentScheme.id, allColDefs]);
 }
 
-/**
- * 统一的方案数据流 Hook（组合版）
- *
- * @param gridKey - Grid 唯一标识
- * @param allColDefs - 原始列定义
- * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
- * @returns 完整的方案数据流对象
- *
- * @example
- * ```tsx
- * function AgGridPlus({ gridKey }) {
- *   const allColDefsRef = useRef([]);
- *   const { columnSchemes, querySchemes, currentSchemes } = useGridSchemes();
- *
- *   const schemeDataFlow = useSchemeDataFlow(
- *     gridKey,
- *     allColDefsRef.current,
- *     { columnSchemes, querySchemes, currentSchemes }
- *   );
- *
- *   // 只读访问数据
- *   const { currentColumnScheme, derivedColumnDefs } = schemeDataFlow;
- * }
- * ```
+/**
+ * 统一的方案数据流 Hook（组合版）
+ *
+ * @param gridKey - Grid 唯一标识
+ * @param allColDefs - 原始列定义
+ * @param schemeData - 方案数据（从外部传入，避免 Context 覆盖问题）
+ * @returns 完整的方案数据流对象
+ *
+ * @example
+ * ```tsx
+ * function AgGridPlus({ gridKey }) {
+ *   const allColDefsRef = useRef([]);
+ *   const { columnSchemes, querySchemes, currentSchemes } = useGridSchemes();
+ *
+ *   const schemeDataFlow = useSchemeDataFlow(
+ *     gridKey,
+ *     allColDefsRef.current,
+ *     { columnSchemes, querySchemes, currentSchemes }
+ *   );
+ *
+ *   // 只读访问数据
+ *   const { currentColumnScheme, derivedColumnDefs } = schemeDataFlow;
+ * }
+ * ```
  */
 function useSchemeDataFlow(gridKey, allColDefs, schemeData) {
   // 1. 数据源层（Source of Truth）

package/dist/cjs/ag-grid-plus/context/useSchemeManager.js

@@ -27,31 +27,31 @@ function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o =
 function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
 function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
-/**
- * useSchemeManager Hook 配置
+/**
+ * useSchemeManager Hook 配置
  */
 
-/**
- * 集中式方案管理 Hook
- *
- * 用于 GridPlusContext.Provider 中初始化方案管理功能
- *
- * @example
- * ```tsx
- * function AppProvider({ children }) {
- *   const adapter = new BackendApiSchemeAdapter({ ... });
- *   const schemeManager = useSchemeManager({ adapter });
- *
- *   return (
- *     <GridPlusContext.Provider value={{
- *       ...otherValues,
- *       ...schemeManager
- *     }}>
- *       {children}
- *     </GridPlusContext.Provider>
- *   );
- * }
- * ```
+/**
+ * 集中式方案管理 Hook
+ *
+ * 用于 GridPlusContext.Provider 中初始化方案管理功能
+ *
+ * @example
+ * ```tsx
+ * function AppProvider({ children }) {
+ *   const adapter = new BackendApiSchemeAdapter({ ... });
+ *   const schemeManager = useSchemeManager({ adapter });
+ *
+ *   return (
+ *     <GridPlusContext.Provider value={{
+ *       ...otherValues,
+ *       ...schemeManager
+ *     }}>
+ *       {children}
+ *     </GridPlusContext.Provider>
+ *   );
+ * }
+ * ```
  */
 function useSchemeManager(config) {
   var adapter = config.adapter,
@@ -439,9 +439,9 @@ function useSchemeManager(config) {
 
   // ========== 全局配置操作 ==========
 
-  /**
-   * 处理全局配置操作的错误
-   * @author nokecy
+  /**
+   * 处理全局配置操作的错误
+   * @author nokecy
    */
   var handleGlobalConfigError = (0, _react.useCallback)(function (error, defaultMessage) {
     var _error$response;
@@ -452,9 +452,9 @@ function useSchemeManager(config) {
     }
   }, []);
 
-  /**
-   * 将方案应用到全局（管理员操作）
-   * @author nokecy
+  /**
+   * 将方案应用到全局（管理员操作）
+   * @author nokecy
    */
   var applySchemeToGlobal = (0, _react.useCallback)( /*#__PURE__*/function () {
     var _ref9 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee9(gridId, schemeId) {
@@ -503,9 +503,9 @@ function useSchemeManager(config) {
     };
   }(), [adapter, currentSchemes, refreshSchemes, handleGlobalConfigError]);
 
-  /**
-   * 重置当前用户配置，回退到全局配置
-   * @author nokecy
+  /**
+   * 重置当前用户配置，回退到全局配置
+   * @author nokecy
    */
   var resetToGlobal = (0, _react.useCallback)( /*#__PURE__*/function () {
     var _ref10 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee10(gridId) {
@@ -550,9 +550,9 @@ function useSchemeManager(config) {
     };
   }(), [adapter, refreshSchemes, handleGlobalConfigError]);
 
-  /**
-   * 重置所有用户配置（管理员操作）
-   * @author nokecy
+  /**
+   * 重置所有用户配置（管理员操作）
+   * @author nokecy
    */
   var resetAllUsers = (0, _react.useCallback)( /*#__PURE__*/function () {
     var _ref11 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee11(gridId) {
@@ -630,64 +630,64 @@ function useSchemeManager(config) {
   };
 }
 
-/**
- * 在组件中使用集中式方案管理
- *
- * ⚠️ 必须在 Provider 中传入 SchemeManager 状态，否则抛出错误
- *
- * @example
- * ```tsx
- * // 1. 创建适配器和方案管理器
- * function App() {
- *   const adapter = useMemo(
- *     () => new BackendApiSchemeAdapter({
- *       apiBaseUrl: 'https://api.example.com',
- *       getToken: () => localStorage.getItem('token'),
- *       getUserId: () => localStorage.getItem('userId')
- *     }),
- *     []
- *   );
- *
- *   const schemeManager = useSchemeManager({
- *     adapter,
- *     autoLoad: true,
- *     showErrorMessage: true,
- *     currentUserId: currentUser?.id
- *   });
- *
- *   // 2. 传入 Provider
- *   return (
- *     <GridPlusContext.Provider value={{
- *       extensibleColumns: [],
- *       columnState: undefined,
- *       onSaveColumnState: () => {},
- *       applyToGlobal: () => {},
- *       resetCurrent: () => {},
- *       resetAll: () => {},
- *       queryFormItems: [],
- *       ...schemeManager  // 展开方案管理状态
- *     }}>
- *       <MyGrid />
- *     </GridPlusContext.Provider>
- *   );
- * }
- *
- * // 3. 在子组件中使用
- * function MyGrid() {
- *   const {
- *     columnSchemes,
- *     saveColumnScheme,
- *     setCurrentColumnScheme
- *   } = useGridSchemes();
- *
- *   const gridId = 'my-grid';
- *   const schemes = columnSchemes?.[gridId] || [];
- *
- *   const handleSave = async () => {
- *     await saveColumnScheme?.(gridId, newScheme);
- *   };
- * }
- * ```
+/**
+ * 在组件中使用集中式方案管理
+ *
+ * ⚠️ 必须在 Provider 中传入 SchemeManager 状态，否则抛出错误
+ *
+ * @example
+ * ```tsx
+ * // 1. 创建适配器和方案管理器
+ * function App() {
+ *   const adapter = useMemo(
+ *     () => new BackendApiSchemeAdapter({
+ *       apiBaseUrl: 'https://api.example.com',
+ *       getToken: () => localStorage.getItem('token'),
+ *       getUserId: () => localStorage.getItem('userId')
+ *     }),
+ *     []
+ *   );
+ *
+ *   const schemeManager = useSchemeManager({
+ *     adapter,
+ *     autoLoad: true,
+ *     showErrorMessage: true,
+ *     currentUserId: currentUser?.id
+ *   });
+ *
+ *   // 2. 传入 Provider
+ *   return (
+ *     <GridPlusContext.Provider value={{
+ *       extensibleColumns: [],
+ *       columnState: undefined,
+ *       onSaveColumnState: () => {},
+ *       applyToGlobal: () => {},
+ *       resetCurrent: () => {},
+ *       resetAll: () => {},
+ *       queryFormItems: [],
+ *       ...schemeManager  // 展开方案管理状态
+ *     }}>
+ *       <MyGrid />
+ *     </GridPlusContext.Provider>
+ *   );
+ * }
+ *
+ * // 3. 在子组件中使用
+ * function MyGrid() {
+ *   const {
+ *     columnSchemes,
+ *     saveColumnScheme,
+ *     setCurrentColumnScheme
+ *   } = useGridSchemes();
+ *
+ *   const gridId = 'my-grid';
+ *   const schemes = columnSchemes?.[gridId] || [];
+ *
+ *   const handleSave = async () => {
+ *     await saveColumnScheme?.(gridId, newScheme);
+ *   };
+ * }
+ * ```
  */
 function useGridSchemes() {
   var context = (0, _react.useContext)(_gridContext.GridPlusContext);