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

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

@@ -0,0 +1,67 @@
+/**
+ * 表头分组配置类型定义
+ * 支持 AG-Grid 的单层和多层表头分组
+ */
+/**
+ * 扁平化列配置项
+ * 用于 UI 展示和编辑，通过 parentId 和 level 维护层级关系
+ */
+export interface FlatColumnItem {
+    /** 唯一标识 */
+    id: string;
+    /** 节点类型 */
+    type: 'group' | 'column';
+    /** 父节点 ID，undefined 表示根级别 */
+    parentId?: string;
+    /** 层级深度，0 为根级别 */
+    level: number;
+    /** 排序序号，用于维护节点顺序 */
+    order: number;
+    /** 显示名称 (当前值，可被用户修改) */
+    headerName: string;
+    /** 原始显示名称 (用于对比和重置) */
+    originalHeaderName?: string;
+    /** AG-Grid 分组标识（仅分组类型） */
+    groupId?: string;
+    /** 子列是否必须保持一起（仅分组类型） */
+    marryChildren?: boolean;
+    /** 列字段名（仅列类型） */
+    field?: string;
+    /** AG-Grid 列标识；业务控件列可以只有 colId，多列也可共用同一 field。@author nokecy */
+    colId?: string;
+    /** 列宽 */
+    width?: number;
+    /** 是否隐藏 */
+    hide?: boolean;
+    /** 固定位置 */
+    pinned?: 'left' | 'right' | 'notPinned';
+    /** 单元格样式类 */
+    cellClass?: string;
+    /** 是否占满剩余空间 */
+    flex?: number;
+    /** 是否可排序 */
+    sortable?: boolean;
+    /** 是否可过滤 */
+    filter?: boolean | string;
+    /** 是否显示列过滤按钮 */
+    suppressHeaderFilterButton?: boolean;
+    /** 是否新添加的节点（用于高亮显示） */
+    _isNew?: boolean;
+    /** 分组是否折叠（仅分组类型，临时状态不持久化） */
+    _collapsed?: boolean;
+}
+/**
+ * 旧版本列配置（用于数据迁移）
+ */
+export interface OldColumnState {
+    field: string;
+    headerName: string;
+    groupName?: string;
+    width?: number;
+    hide?: boolean;
+    pinned?: string;
+    cellClass?: string;
+    flex?: number;
+    suppressHeaderFilterButton?: boolean;
+    [key: string]: any;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,117 @@
+/**
+ * 表头分组配置工具函数
+ * 负责 Grid State 与扁平化配置之间的转换
+ */
+import { ColDef, ColGroupDef } from 'ag-grid-community';
+import type { FlatColumnItem, OldColumnState } from './columnGroupTypes';
+/**
+ * 生成唯一 ID
+ */
+export declare const generateId: () => string;
+/** 方案与 AG-Grid 使用相同的列标识规则。@author nokecy */
+export declare function getColumnIdentity(column: {
+    colId?: string;
+    field?: string;
+}): string | undefined;
+/** 递归匹配业务列；仅对缺失标识的已存方案使用唯一原始标题恢复。@author nokecy */
+export declare function findOriginalColumn(item: {
+    colId?: string;
+    field?: string;
+    originalHeaderName?: string;
+    headerName?: string;
+}, definitions?: (ColDef | ColGroupDef)[]): ColDef | undefined;
+/** 为列方案补齐业务列身份，保留用户的顺序、标题与布局设置。@author nokecy */
+export declare function normalizeColumnConfig(items: FlatColumnItem[], definitions?: (ColDef | ColGroupDef)[]): FlatColumnItem[];
+/**
+ * 去掉只做查询条件的列（hideInTable），含分组内的
+ * 这类列只进查询表单，不是表格列：列方案的还原、新增列检测都不能把它带进表格
+ * @author nokecy
+ */
+export declare function excludeQueryOnlyColumns<T extends ColDef | ColGroupDef>(defs?: T[]): T[] | undefined;
+/**
+ * 从已存的列方案中去掉只做查询条件的列
+ * 旧版本方案会把它们当新增列存进去，还原时要按当前列定义剔除
+ * @author nokecy
+ */
+export declare function dropQueryOnlyItems(flatConfig: FlatColumnItem[], originalColumnDefs?: (ColDef | ColGroupDef)[]): FlatColumnItem[];
+/**
+ * Grid State → 扁平化配置
+ * 将 AG-Grid 的树形结构转换为扁平化数组，用于 UI 展示和编辑
+ *
+ * @param columnDefs AG-Grid 列定义数组
+ * @param originalColumnDefs 原始列定义数组(可选),用于获取 originalHeaderName
+ * @returns 扁平化配置数组
+ */
+export declare function gridStateToFlatConfig(columnDefs: (ColDef | ColGroupDef)[], originalColumnDefs?: (ColDef | ColGroupDef)[]): FlatColumnItem[];
+/**
+ * 扁平化配置 → Grid State
+ * 将扁平化数组重建为 AG-Grid 的树形结构
+ *
+ * 【重要】如果提供了 originalColumnDefs，会合并原始列定义中的所有属性
+ * 这样可以保留 cellRenderer、valueFormatter、valueEnum 等自定义渲染属性
+ *
+ * 【重要】会自动检测并追加代码中新增的列（在 originalColumnDefs 中存在但 flatConfig 中不存在的列）
+ *
+ * @param flatConfig 扁平化配置数组
+ * @param originalColumnDefs 原始列定义数组（可选），用于保留自定义属性和检测新增列
+ * @returns AG-Grid 列定义数组
+ */
+export declare function flatConfigToGridState(flatConfig: FlatColumnItem[], originalColumnDefs?: (ColDef | ColGroupDef)[]): (ColDef | ColGroupDef)[];
+/**
+ * 旧版本数据迁移
+ * 将旧的 { groupName } 结构迁移为新的树形结构
+ *
+ * @param oldState 旧版本列配置数组
+ * @returns 扁平化配置数组
+ */
+export declare function migrateOldScheme(oldState: OldColumnState[]): FlatColumnItem[];
+/**
+ * 查找节点的所有后代节点的最后一个索引
+ * 用于在正确位置插入新子节点
+ *
+ * @param items 扁平化配置数组
+ * @param parentId 父节点 ID
+ * @returns 最后一个后代节点的索引，如果没有后代则返回父节点索引
+ */
+export declare function findLastDescendantIndex(items: FlatColumnItem[], parentId: string): number;
+/**
+ * 检查节点是否是其父节点的最后一个子节点
+ * 用于渲染缩进符号（├─ 或 └─）
+ *
+ * @param items 扁平化配置数组
+ * @param item 当前节点
+ * @returns 是否是最后一个子节点
+ */
+export declare function checkIsLastChild(items: FlatColumnItem[], item: FlatColumnItem): boolean;
+/**
+ * 重新计算所有节点的 order
+ * 确保 order 连续且与数组索引一致
+ *
+ * @param items 扁平化配置数组
+ */
+export declare function reorderItems(items: FlatColumnItem[]): void;
+/**
+ * 检查是否包含旧版本的 groupName 字段
+ * 用于判断是否需要数据迁移
+ *
+ * @param data 列配置数据
+ * @returns 是否是旧版本数据
+ */
+export declare function isOldSchemeData(data: any[]): boolean;
+/**
+ * 扁平化配置 → AG-Grid Column State
+ * 将扁平化数组转换为 AG-Grid 的 columnState 格式，用于控制列的顺序和属性
+ *
+ * 【重要】会自动检测并追加代码中新增的列（在 originalColumnDefs 中存在但 flatConfig 中不存在的列）
+ *
+ * @param flatConfig 扁平化配置数组
+ * @param originalColumnDefs 原始列定义数组（可选），用于检测新增列
+ * @returns AG-Grid columnState 数组
+ */
+export declare function flatConfigToColumnState(flatConfig: FlatColumnItem[], originalColumnDefs?: (ColDef | ColGroupDef)[]): any[];
+/**
+ * 把列上的 cellClass 归一为对齐下拉的三个选项值。
+ * 列定义里可能是 AG-Grid 数值类型自带的 ag-right-aligned-cell、ArrayTable 的 qc-array-table-align-right 等，
+ * 下拉只认 custom-cell-*，不归一就会把原始类名直接显示出来。@author nokecy
+ */
+export declare function normalizeCellAlign(cellClass: unknown): 'custom-cell-left' | 'custom-cell-centered' | 'custom-cell-right';