@nokecy/qc-ui-components 0.0.0-stage → 2.0.0-beta.1

package/dist/esm/ag-grid-plus/setting/columnGroupUtils.js

@@ -0,0 +1,645 @@
+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 _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+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 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); }
+/**
+ * 表头分组配置工具函数
+ * 负责 Grid State 与扁平化配置之间的转换
+ */
+
+import { uniqueId } from 'lodash';
+import { logger } from "../utils/logger";
+/**
+ * 生成唯一 ID
+ */
+export var generateId = function generateId() {
+  return uniqueId('col_');
+};
+
+/** 方案与 AG-Grid 使用相同的列标识规则。@author nokecy */
+export function getColumnIdentity(column) {
+  return column.colId || column.field || undefined;
+}
+
+/** 递归匹配业务列；仅对缺失标识的已存方案使用唯一原始标题恢复。@author nokecy */
+export function findOriginalColumn(item, definitions) {
+  var columns = [];
+  var collect = function collect(defs) {
+    return defs.forEach(function (def) {
+      if ('children' in def && def.children) collect(def.children);else columns.push(def);
+    });
+  };
+  collect(definitions !== null && definitions !== void 0 ? definitions : []);
+  if (item.colId) return columns.find(function (column) {
+    return getColumnIdentity(column) === item.colId;
+  });
+  var title = item.originalHeaderName || item.headerName;
+  var candidates = item.field ? columns.filter(function (column) {
+    return column.field === item.field;
+  }) : columns.filter(function (column) {
+    return !!getColumnIdentity(column) && !!title && column.headerName === title;
+  });
+  if (candidates.length === 1) return candidates[0];
+  var named = candidates.filter(function (column) {
+    return !!title && column.headerName === title;
+  });
+  return named.length === 1 ? named[0] : undefined;
+}
+
+/** 不允许被隐藏的业务列（列定义声明 lockVisible）的列标识。@author nokecy */
+export function getLockedColumnIds(definitions) {
+  var ids = [];
+  var collect = function collect(defs) {
+    return defs.forEach(function (def) {
+      if ('children' in def && def.children) collect(def.children);else if (def.lockVisible) {
+        var id = getColumnIdentity(def);
+        if (id) ids.push(id);
+      }
+    });
+  };
+  collect(definitions !== null && definitions !== void 0 ? definitions : []);
+  return ids;
+}
+
+/** 为列方案补齐业务列身份，保留用户的顺序、标题与布局设置。@author nokecy */
+export function normalizeColumnConfig(items, definitions) {
+  return items.map(function (item) {
+    if (item.type !== 'column') return item;
+    var original = findOriginalColumn(item, definitions);
+    return original ? _objectSpread(_objectSpread({}, item), {}, {
+      colId: original.colId,
+      field: original.field,
+      originalHeaderName: original.headerName || item.originalHeaderName
+    }, original.lockVisible ? {
+      hide: false
+    } : {}) : item;
+  });
+}
+
+/**
+ * 去掉只做查询条件的列（hideInTable），含分组内的
+ * 这类列只进查询表单，不是表格列：列方案的还原、新增列检测都不能把它带进表格
+ * @author nokecy
+ */
+export function excludeQueryOnlyColumns(defs) {
+  return defs === null || defs === void 0 ? void 0 : defs.filter(function (def) {
+    return !def.hideInTable;
+  }).map(function (def) {
+    return 'children' in def && def.children ? _objectSpread(_objectSpread({}, def), {}, {
+      children: excludeQueryOnlyColumns(def.children)
+    }) : def;
+  });
+}
+
+/**
+ * 从已存的列方案中去掉只做查询条件的列
+ * 旧版本方案会把它们当新增列存进去，还原时要按当前列定义剔除
+ * @author nokecy
+ */
+export function dropQueryOnlyItems(flatConfig, originalColumnDefs) {
+  var queryOnlyFields = new Set();
+  var collect = function collect(defs) {
+    return defs.forEach(function (def) {
+      if ('children' in def && def.children) collect(def.children);else if (def.hideInTable && getColumnIdentity(def)) queryOnlyFields.add(getColumnIdentity(def));
+    });
+  };
+  collect(originalColumnDefs !== null && originalColumnDefs !== void 0 ? originalColumnDefs : []);
+  return flatConfig.filter(function (item) {
+    return item.type !== 'column' || !getColumnIdentity(item) || !queryOnlyFields.has(getColumnIdentity(item));
+  });
+}
+
+/**
+ * Grid State → 扁平化配置
+ * 将 AG-Grid 的树形结构转换为扁平化数组，用于 UI 展示和编辑
+ *
+ * @param columnDefs AG-Grid 列定义数组
+ * @param originalColumnDefs 原始列定义数组(可选),用于获取 originalHeaderName
+ * @returns 扁平化配置数组
+ */
+export function gridStateToFlatConfig(columnDefs, originalColumnDefs) {
+  var result = [];
+  var order = 0;
+
+  /**
+   * 递归遍历列定义树
+   */
+  function traverse(items, level, parentId) {
+    items.forEach(function (item) {
+      if (item.children && item.children.length > 0) {
+        // 这是一个分组节点
+        var groupId = generateId();
+        var headerName = item.headerName || '未命名分组';
+        result.push({
+          id: groupId,
+          type: 'group',
+          parentId: parentId,
+          level: level,
+          order: order++,
+          headerName: headerName,
+          originalHeaderName: headerName,
+          // 保存原始 headerName
+          groupId: item.groupId || item.field || generateId(),
+          marryChildren: item.marryChildren
+        });
+        // 递归处理子节点
+        traverse(item.children, level + 1, groupId);
+      } else {
+        var _findOriginalColumn;
+        // 这是一个列节点
+        var _headerName = item.headerName || item.field || '未命名列';
+        // 从原始列定义中获取 originalHeaderName,如果没有则使用当前 headerName
+        var originalHeaderName = ((_findOriginalColumn = findOriginalColumn(item, originalColumnDefs)) === null || _findOriginalColumn === void 0 ? void 0 : _findOriginalColumn.headerName) || _headerName;
+        result.push({
+          id: generateId(),
+          type: 'column',
+          parentId: parentId,
+          level: level,
+          order: order++,
+          field: item.field,
+          colId: item.colId,
+          headerName: _headerName,
+          originalHeaderName: originalHeaderName,
+          // 从原始定义获取,或使用当前值
+          width: item.width,
+          hide: item.hide,
+          pinned: item.pinned === null ? 'notPinned' : item.pinned,
+          cellClass: item.cellClass,
+          flex: item.flex,
+          suppressHeaderFilterButton: item.suppressHeaderFilterButton
+        });
+      }
+    });
+  }
+  traverse(columnDefs, 0);
+  return result;
+}
+
+/**
+ * 扁平化配置 → Grid State
+ * 将扁平化数组重建为 AG-Grid 的树形结构
+ *
+ * 【重要】如果提供了 originalColumnDefs，会合并原始列定义中的所有属性
+ * 这样可以保留 cellRenderer、valueFormatter、valueEnum 等自定义渲染属性
+ *
+ * 【重要】会自动检测并追加代码中新增的列（在 originalColumnDefs 中存在但 flatConfig 中不存在的列）
+ *
+ * @param flatConfig 扁平化配置数组
+ * @param originalColumnDefs 原始列定义数组（可选），用于保留自定义属性和检测新增列
+ * @returns AG-Grid 列定义数组
+ */
+export function flatConfigToGridState(flatConfig, originalColumnDefs) {
+  // 只做查询条件的列不进表格：方案里存过的剔除，也不当新增列补回 @author nokecy
+  flatConfig = dropQueryOnlyItems(normalizeColumnConfig(flatConfig, originalColumnDefs), originalColumnDefs);
+  originalColumnDefs = excludeQueryOnlyColumns(originalColumnDefs);
+
+  /**
+   * 递归收集所有列定义（包括分组内的列）
+   */
+  function collectAllColumns(defs) {
+    var columns = [];
+    var _iterator = _createForOfIteratorHelper(defs),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var def = _step.value;
+        if ('children' in def && def.children) {
+          columns.push.apply(columns, _toConsumableArray(collectAllColumns(def.children)));
+        } else {
+          columns.push(def);
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    return columns;
+  }
+
+  /**
+   * 递归构建树形结构
+   */
+  function buildTree(parentId) {
+    var children = flatConfig.filter(function (item) {
+      return item.parentId === parentId;
+    }).sort(function (a, b) {
+      return a.order - b.order;
+    });
+    return children.map(function (item) {
+      if (item.type === 'group') {
+        // 构建分组节点
+        return {
+          headerName: item.headerName,
+          groupId: item.groupId,
+          field: "".concat(item.groupId, "_header"),
+          // AG-Grid 要求有 field
+          marryChildren: item.marryChildren !== undefined ? item.marryChildren : true,
+          children: buildTree(item.id) // 递归构建子节点
+        };
+      } else {
+        // 构建列节点
+        // 查找原始列定义
+        var originalDef = findOriginalColumn(item, originalColumnDefs);
+
+        // 如果找到原始列定义，合并所有属性
+        if (originalDef) {
+          return _objectSpread(_objectSpread({}, originalDef), {}, {
+            // 保留所有原始属性（cellRenderer、valueFormatter、valueEnum 等）
+            // 只覆盖方案中保存的属性
+            headerName: item.headerName,
+            width: item.width,
+            hide: item.hide,
+            pinned: item.pinned === 'notPinned' ? null : item.pinned,
+            cellClass: item.cellClass,
+            flex: item.flex,
+            suppressHeaderFilterButton: item.suppressHeaderFilterButton
+          });
+        }
+
+        // 如果没有找到原始定义，使用基本属性
+        return {
+          field: item.field,
+          colId: item.colId,
+          headerName: item.headerName,
+          width: item.width,
+          hide: item.hide,
+          pinned: item.pinned === 'notPinned' ? null : item.pinned,
+          cellClass: item.cellClass,
+          flex: item.flex,
+          suppressHeaderFilterButton: item.suppressHeaderFilterButton
+        };
+      }
+    });
+  }
+  var result = buildTree();
+
+  // 【新增】检测并插入代码中新增的列到原始位置
+  // 场景：用户保存列配置后，开发者在代码中新增了列，这些列应该在其原始定义位置显示
+  if (originalColumnDefs && originalColumnDefs.length > 0) {
+    // 收集 flatConfig 中所有已存在的 field
+    var existingFields = new Set(flatConfig.filter(function (item) {
+      return item.type === 'column' && getColumnIdentity(item);
+    }).map(function (item) {
+      return getColumnIdentity(item);
+    }));
+
+    // 收集原始列定义中所有的列（保留顺序索引）
+    var allOriginalColumns = collectAllColumns(originalColumnDefs);
+
+    // 找出新增的列及其在原始定义中的索引
+    var newColumnsWithIndex = [];
+    allOriginalColumns.forEach(function (col, index) {
+      if (getColumnIdentity(col) && !existingFields.has(getColumnIdentity(col))) {
+        newColumnsWithIndex.push({
+          col: col,
+          originalIndex: index
+        });
+      }
+    });
+    if (newColumnsWithIndex.length > 0) {
+      logger.debug('[flatConfigToGridState] 检测到新增列，将插入到原始位置:', {
+        newColumnFields: newColumnsWithIndex.map(function (item) {
+          return item.col.field;
+        })
+      });
+
+      // 将新增列插入到正确位置（基于其在原始定义中的相对位置）
+      var _iterator2 = _createForOfIteratorHelper(newColumnsWithIndex),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _step2$value = _step2.value,
+            col = _step2$value.col,
+            originalIndex = _step2$value.originalIndex;
+          var insertIndex = 0; // 默认插入到开头
+
+          // 从该列之前的列开始查找，找到第一个在 result 中存在的列
+          var _loop = function _loop() {
+              var prevCol = allOriginalColumns[i];
+              if (!getColumnIdentity(prevCol)) return 0; // continue
+
+              // 在 result 中找到这个前置列的位置
+              var prevIndexInResult = result.findIndex(function (r) {
+                return getColumnIdentity(r) === getColumnIdentity(prevCol);
+              });
+              if (prevIndexInResult !== -1) {
+                insertIndex = prevIndexInResult + 1;
+                return 1; // break
+              }
+            },
+            _ret;
+          for (var i = originalIndex - 1; i >= 0; i--) {
+            _ret = _loop();
+            if (_ret === 0) continue;
+            if (_ret === 1) break;
+          }
+
+          // 在 insertIndex 位置插入新列
+          result.splice(insertIndex, 0, col);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * 旧版本数据迁移
+ * 将旧的 { groupName } 结构迁移为新的树形结构
+ *
+ * @param oldState 旧版本列配置数组
+ * @returns 扁平化配置数组
+ */
+export function migrateOldScheme(oldState) {
+  var groups = new Map();
+  var result = [];
+  var order = 0;
+
+  // 第一遍：创建所有分组节点
+  oldState.forEach(function (col) {
+    if (col.groupName && !groups.has(col.groupName)) {
+      var groupId = generateId();
+      groups.set(col.groupName, groupId);
+      result.push({
+        id: groupId,
+        type: 'group',
+        level: 0,
+        order: order++,
+        headerName: col.groupName,
+        groupId: groupId
+      });
+    }
+  });
+
+  // 第二遍：创建所有列节点
+  oldState.forEach(function (col) {
+    var parentId = col.groupName ? groups.get(col.groupName) : undefined;
+    result.push({
+      id: generateId(),
+      type: 'column',
+      parentId: parentId,
+      level: col.groupName ? 1 : 0,
+      order: order++,
+      field: col.field,
+      colId: col.colId,
+      headerName: col.headerName,
+      width: col.width,
+      hide: col.hide,
+      pinned: col.pinned === null ? 'notPinned' : col.pinned,
+      cellClass: col.cellClass,
+      flex: col.flex,
+      suppressHeaderFilterButton: col.suppressHeaderFilterButton
+    });
+  });
+  return result;
+}
+
+/**
+ * 查找节点的所有后代节点的最后一个索引
+ * 用于在正确位置插入新子节点
+ *
+ * @param items 扁平化配置数组
+ * @param parentId 父节点 ID
+ * @returns 最后一个后代节点的索引，如果没有后代则返回父节点索引
+ */
+export function findLastDescendantIndex(items, parentId) {
+  var parentIndex = items.findIndex(function (item) {
+    return item.id === parentId;
+  });
+  if (parentIndex === -1) return -1;
+  var lastIndex = parentIndex;
+
+  // 从父节点之后开始查找
+  for (var i = parentIndex + 1; i < items.length; i++) {
+    var item = items[i];
+    // 检查是否是后代节点（通过 level 判断）
+    if (item.level <= items[parentIndex].level) {
+      // 遇到同级或更高级别的节点，说明后代节点已结束
+      break;
+    }
+    lastIndex = i;
+  }
+  return lastIndex;
+}
+
+/**
+ * 检查节点是否是其父节点的最后一个子节点
+ * 用于渲染缩进符号（├─ 或 └─）
+ *
+ * @param items 扁平化配置数组
+ * @param item 当前节点
+ * @returns 是否是最后一个子节点
+ */
+export function checkIsLastChild(items, item) {
+  if (!item.parentId) return false;
+  var siblings = items.filter(function (i) {
+    return i.parentId === item.parentId;
+  });
+  if (siblings.length === 0) return false;
+  var lastSibling = siblings[siblings.length - 1];
+  return lastSibling.id === item.id;
+}
+
+/**
+ * 重新计算所有节点的 order
+ * 确保 order 连续且与数组索引一致
+ *
+ * @param items 扁平化配置数组
+ */
+export function reorderItems(items) {
+  items.forEach(function (item, index) {
+    item.order = index;
+  });
+}
+
+/**
+ * 检查是否包含旧版本的 groupName 字段
+ * 用于判断是否需要数据迁移
+ *
+ * @param data 列配置数据
+ * @returns 是否是旧版本数据
+ */
+export function isOldSchemeData(data) {
+  return data.some(function (item) {
+    return item.groupName !== undefined && item.type === undefined;
+  });
+}
+
+/**
+ * 扁平化配置 → AG-Grid Column State
+ * 将扁平化数组转换为 AG-Grid 的 columnState 格式，用于控制列的顺序和属性
+ *
+ * 【重要】会自动检测并追加代码中新增的列（在 originalColumnDefs 中存在但 flatConfig 中不存在的列）
+ *
+ * @param flatConfig 扁平化配置数组
+ * @param originalColumnDefs 原始列定义数组（可选），用于检测新增列
+ * @returns AG-Grid columnState 数组
+ */
+export function flatConfigToColumnState(flatConfig, originalColumnDefs) {
+  var _originalColumnDefs;
+  // 只做查询条件的列不进表格：方案里存过的剔除，也不当新增列补回 @author nokecy
+  flatConfig = dropQueryOnlyItems(normalizeColumnConfig(flatConfig, originalColumnDefs), originalColumnDefs);
+  originalColumnDefs = excludeQueryOnlyColumns(originalColumnDefs);
+
+  /**
+   * 递归收集所有列定义（包括分组内的列）
+   */
+  function collectAllColumns(defs) {
+    var columns = [];
+    var _iterator3 = _createForOfIteratorHelper(defs),
+      _step3;
+    try {
+      for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+        var def = _step3.value;
+        if ('children' in def && def.children) {
+          columns.push.apply(columns, _toConsumableArray(collectAllColumns(def.children)));
+        } else {
+          columns.push(def);
+        }
+      }
+    } catch (err) {
+      _iterator3.e(err);
+    } finally {
+      _iterator3.f();
+    }
+    return columns;
+  }
+
+  // 已保存的用户列方案可能早于页面 minWidth 调整。恢复时只保留顺序、显隐等用户偏好，
+  // 对显式声明最小宽度的列把历史窄宽度抬到当前下限，避免重要表头和数值被压缩。@author nokecy
+  var minimumWidths = new Map();
+  collectAllColumns((_originalColumnDefs = originalColumnDefs) !== null && _originalColumnDefs !== void 0 ? _originalColumnDefs : []).forEach(function (column) {
+    var identity = getColumnIdentity(column);
+    var minWidth = Number(column.minWidth);
+    if (identity && Number.isFinite(minWidth) && minWidth > 0) minimumWidths.set(identity, minWidth);
+  });
+  var result = flatConfig.filter(function (item) {
+    return item.type === 'column';
+  }) // 只处理列节点，分组不在 columnState 中
+  .filter(function (item) {
+    return getColumnIdentity(item);
+  }) // 控件列可只有 colId。@author nokecy
+  .sort(function (a, b) {
+    return a.order - b.order;
+  }) // 按 order 字段排序
+  .map(function (item) {
+    var state = {
+      colId: getColumnIdentity(item)
+    };
+
+    // 只设置有值的属性，undefined 表示不改变该属性
+    if (item.width !== undefined) {
+      var minWidth = minimumWidths.get(state.colId);
+      state.width = minWidth && Number.isFinite(item.width) ? Math.max(item.width, minWidth) : item.width;
+    }
+    if (item.hide !== undefined) state.hide = item.hide;
+    if (item.flex !== undefined) state.flex = item.flex;
+
+    // pinned 特殊处理：'notPinned' -> null
+    if (item.pinned !== undefined) {
+      state.pinned = item.pinned === 'notPinned' ? null : item.pinned;
+    }
+    return state;
+  });
+
+  // 【新增】检测并插入代码中新增的列到原始位置
+  if (originalColumnDefs && originalColumnDefs.length > 0) {
+    // 收集 flatConfig 中所有已存在的 field
+    var existingFields = new Set(flatConfig.filter(function (item) {
+      return item.type === 'column' && getColumnIdentity(item);
+    }).map(function (item) {
+      return getColumnIdentity(item);
+    }));
+
+    // 收集原始列定义中所有的列（保留顺序索引）
+    var allOriginalColumns = collectAllColumns(originalColumnDefs);
+
+    // 找出新增的列及其在原始定义中的索引
+    var newColumnsWithIndex = [];
+    allOriginalColumns.forEach(function (col, index) {
+      if (getColumnIdentity(col) && !existingFields.has(getColumnIdentity(col))) {
+        newColumnsWithIndex.push({
+          col: col,
+          originalIndex: index
+        });
+      }
+    });
+    if (newColumnsWithIndex.length > 0) {
+      logger.debug('[flatConfigToColumnState] 检测到新增列，将插入到原始位置:', {
+        newColumnFields: newColumnsWithIndex.map(function (item) {
+          return item.col.field;
+        })
+      });
+
+      // 将新增列插入到正确位置（基于其在原始定义中的相对位置）
+      var _iterator4 = _createForOfIteratorHelper(newColumnsWithIndex),
+        _step4;
+      try {
+        for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+          var _step4$value = _step4.value,
+            col = _step4$value.col,
+            originalIndex = _step4$value.originalIndex;
+          var insertIndex = 0; // 默认插入到开头
+
+          // 从该列之前的列开始查找，找到第一个在 result 中存在的列
+          var _loop2 = function _loop2() {
+              var prevCol = allOriginalColumns[i];
+              if (!getColumnIdentity(prevCol)) return 0; // continue
+
+              // 在 result 中找到这个前置列的位置
+              var prevIndexInResult = result.findIndex(function (r) {
+                return r.colId === getColumnIdentity(prevCol);
+              });
+              if (prevIndexInResult !== -1) {
+                insertIndex = prevIndexInResult + 1;
+                return 1; // break
+              }
+            },
+            _ret2;
+          for (var i = originalIndex - 1; i >= 0; i--) {
+            _ret2 = _loop2();
+            if (_ret2 === 0) continue;
+            if (_ret2 === 1) break;
+          }
+
+          // 在 insertIndex 位置插入新列状态
+          result.splice(insertIndex, 0, {
+            colId: getColumnIdentity(col)
+            // 新增列使用默认状态，不设置 hide/width 等
+          });
+        }
+      } catch (err) {
+        _iterator4.e(err);
+      } finally {
+        _iterator4.f();
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * 把列上的 cellClass 归一为对齐下拉的三个选项值。
+ * 列定义里可能是 AG-Grid 数值类型自带的 ag-right-aligned-cell、ArrayTable 的 qc-array-table-align-right 等，
+ * 下拉只认 custom-cell-*，不归一就会把原始类名直接显示出来。@author nokecy
+ */
+export function normalizeCellAlign(cellClass) {
+  var text = Array.isArray(cellClass) ? cellClass.join(' ') : typeof cellClass === 'string' ? cellClass : '';
+  if (/right/.test(text)) return 'custom-cell-right';
+  if (/cent/.test(text)) return 'custom-cell-centered';
+  return 'custom-cell-left';
+}

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

@@ -0,0 +1,11 @@
+import React from "react";
+import { GridApi } from 'ag-grid-community';
+declare const Setting: (props: {
+    gridKey?: string | undefined;
+    gridApi?: GridApi<any> | undefined;
+    gridApiState?: GridApi<any> | undefined;
+    allColDefs?: any[] | undefined;
+    onSaveColumnState?: ((state: any) => void) | undefined;
+    showQueryScheme?: boolean | undefined;
+}) => React.JSX.Element | null;
+export default Setting;