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

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

@@ -0,0 +1,374 @@
+/**
+ * AG-Grid Plus 完整类型定义
+ *
+ * 此文件定义了 AgGridPlus 组件的所有核心类型接口,
+ * 用于替换代码中的 any 类型,提高类型安全性
+ */
+import { ColumnState, GridApi, ColDef, ICellRendererParams } from 'ag-grid-community';
+import { ReactNode, type JSX } from 'react';
+import type { StatusKey } from './utils/statusPill';
+/**
+ * 分页状态
+ */
+export interface PaginationState {
+    /** 当前页码 (1-based) */
+    current: number;
+    /** 每页显示条数 */
+    pageSize: number;
+    /** 总数据量 */
+    total: number;
+}
+/**
+ * 选中行状态
+ */
+export interface SelectionState {
+    /** 选中的行键值集合 */
+    [key: string]: boolean;
+}
+/**
+ * 查询过滤器状态
+ */
+export interface QueryFilterState {
+    /** 字段到过滤值的映射 */
+    [field: string]: any;
+}
+/**
+ * 列单元格样式配置
+ */
+export interface ColumnCellConfig {
+    /** 单元格样式类 */
+    cellClass?: string;
+    /** 是否禁用表头过滤按钮 */
+    suppressHeaderFilterButton?: boolean;
+    /** 分组名称 */
+    groupName?: string;
+}
+/**
+ * 列单元格配置映射
+ */
+export type ColumnCellConfigMap = Record<string, ColumnCellConfig>;
+/**
+ * 请求参数
+ */
+export interface RequestParams {
+    /** 跳过的记录数 (分页用) */
+    skipCount: number;
+    /** 最大返回记录数 (分页用) */
+    maxResultCount: number;
+    /** 当前页码 */
+    current: number;
+    /** 排序字段 */
+    sort?: string;
+    /** 过滤器参数 */
+    filter?: any;
+    /** 额外的网格参数 */
+    [key: string]: any;
+}
+/**
+ * 请求响应
+ */
+export interface RequestResponse<T = any> {
+    /** 数据列表 */
+    items: T[];
+    /** 总记录数 */
+    totalCount: number;
+    /** 错误信息 (可选) */
+    error?: string;
+    /** 响应状态码 (可选) */
+    statusCode?: number;
+}
+/**
+ * 请求函数签名
+ */
+export type RequestFunction<T = any> = (params: RequestParams, sort: string | undefined, filter: any) => Promise<RequestResponse<T>>;
+/**
+ * 树形数据节点
+ */
+export interface TreeNode<T = any> {
+    /** 节点唯一标识 */
+    [key: string]: any;
+    /** 子节点数组 */
+    children?: TreeNode<T>[];
+}
+/**
+ * 树形数据配置
+ */
+export interface TreeDataConfig {
+    /** 树节点键名 (默认: "id") */
+    treeKeyName?: string;
+    /** 父节点键名 (默认: "parentId") */
+    treeParentName?: string;
+}
+/**
+ * 枚举值项
+ */
+export interface ValueEnumItem {
+    /** 枚举值 */
+    value: any;
+    /** 显示标签 */
+    label: string;
+    /** 标签颜色 (可选) */
+    color?: string;
+    /**
+     * 状态语义（可选）。配置后渲染为「图标 + 文字 + 底色」的状态胶囊，优先于 `color`。
+     * wait 待处理 / running 进行中 / done 已完成 / warning 预警 / alarm 报警 / closed 已关闭。
+     */
+    status?: StatusKey;
+    /** 是否为默认值 (可选) */
+    default?: boolean;
+}
+/**
+ * 计算类型
+ */
+export type CalculationType = 'sum' | 'avg' | 'standardDeviation' | false;
+/**
+ * 扩展的列定义 (已在 interface.tsx 中定义为 AgGridColumnPropsClone)
+ * 此处提供类型引用和文档
+ */
+export interface ExtendedColDef extends ColDef {
+    /** 是否精确查询 */
+    exactQuery?: boolean;
+    /** 是否在表格中隐藏 */
+    hideInTable?: boolean;
+    /** 是否在搜索表单中隐藏 */
+    hideInSearch?: boolean;
+    /** 查询字段名 (不同于显示字段) */
+    queryField?: string;
+    /** 查询区独立标题；优先于列方案中的表头名称。@author nokecy */
+    searchTitle?: string;
+    /** 查询日期精度：按日或精确到秒；false 表示不按时刻查询。未声明时由 AgGridPlus 的 dateQueryPrecision 推断。@author nokecy */
+    queryDatePrecision?: 'date' | 'dateTime' | false;
+    /** 是否文本缩略显示并使用 tooltip */
+    ellipsis?: boolean;
+    /** 枚举值配置 */
+    valueEnum?: ValueEnumItem[];
+    /**
+     * `valueEnum` **未命中**时的渲染接管（`null` / `undefined` / 空串 / 后端新增码值都走这里）。
+     * 不传则原样输出该值（历史行为，向后兼容）。业务侧据此输出中性「—」/「未知（原码）」。
+     * 命中枚举项的渲染不受它影响。
+     */
+    enumFallbackRenderer?: (params: ICellRendererParams) => ReactNode;
+    /** 自定义搜索组件 */
+    searchComponent?: ReactNode | ((props: any) => JSX.Element);
+    /** 搜索组件属性 */
+    searchComponentProps?: any;
+    /** 查询组件的枚举数据源。@author nokecy */
+    enum?: any[];
+    /** 搜索表单排序顺序 */
+    searchSort?: number;
+    /** 列计算类型 */
+    calculateType?: CalculationType;
+    /** 计算结果小数位数 (默认: 2) */
+    transactionAmount?: number;
+    /** 是否使用千分位格式化 */
+    formatWithCommas?: boolean;
+    /** 自定义单元格渲染器 (用于跳过计算) */
+    customCellRenderer?: (params: any) => any;
+    /** 列分组的子列 (支持列分组功能) */
+    children?: ExtendedColDef[];
+}
+/**
+ * 扩展的列状态 (包含 AG-Grid 列状态 + 自定义属性)
+ */
+export interface ExtendedColumnState extends ColumnState {
+    /** 列字段名 */
+    field?: string;
+    /** 单元格样式类 */
+    cellClass?: string;
+    /** 是否禁用表头过滤按钮 */
+    suppressHeaderFilterButton?: boolean;
+    /** 分组名称 */
+    groupName?: string;
+    /** 其他自定义属性 */
+    [key: string]: any;
+}
+/**
+ * 工具栏渲染函数参数
+ */
+export interface ToolBarRenderParams {
+    /** Grid API 引用 */
+    gridApi?: GridApi;
+    /** 筛选字符串 */
+    filter?: string;
+    /** 查询过滤器对象 */
+    queryFilter?: QueryFilterState;
+    /** 分页信息 */
+    paginationInfo?: {
+        /** @deprecated 改用 page */
+        current: number;
+        /** @deprecated 改用 page/pageSize */
+        skipCount: number;
+        /** @deprecated 改用 page/pageSize */
+        maxResultCount: number;
+        /** 当前页码（1-based）
+         * @author nokecy */
+        page?: number;
+        /** 每页条数
+         * @author nokecy */
+        pageSize?: number;
+    };
+}
+/**
+ * 工具栏渲染函数签名
+ */
+export type ToolBarRenderFunction = (gridApi?: GridApi, filter?: string, queryFilter?: QueryFilterState, paginationInfo?: ToolBarRenderParams['paginationInfo']) => ReactNode[];
+/**
+ * 查询表单项
+ */
+export interface QueryFormItem {
+    /** 字段名 */
+    field: string;
+    /** 表头名称 */
+    headerName: string;
+    /** 查询区独立标题。@author nokecy */
+    searchTitle?: string;
+    /** 排序顺序 */
+    order: number;
+    /** 是否精确查询 */
+    exactQuery?: boolean;
+    /** 搜索组件 */
+    searchComponent?: ReactNode | ((props: any) => JSX.Element);
+    /** 搜索组件属性 */
+    searchComponentProps?: any;
+    /** 枚举值 */
+    valueEnum?: ValueEnumItem[];
+    /** 其他扩展属性 */
+    [key: string]: any;
+}
+/**
+ * 查询表单带顺序的项 (继承自 querySchemes)
+ */
+export interface QueryFormItemWithOrder extends QueryFormItem {
+    /** 显示顺序 */
+    order: number;
+}
+/**
+ * Grid 引用方法
+ */
+export interface GridRefMethods {
+    /** 刷新数据 */
+    onRefresh: () => void;
+}
+/**
+ * 数据类型推断结果
+ */
+export interface DataTypeInference {
+    /** 数据类型 */
+    type: 'number' | 'string' | 'boolean' | 'date';
+    /** 计算类型 (仅对数值类型有效) */
+    calculateType?: CalculationType;
+}
+/**
+ * Grid 上下文值
+ */
+export interface GridPlusContextValue {
+    /** 查询方案管理器 */
+    querySchemeManager?: any;
+    /** 列配置方案管理器 */
+    columnSchemeManager?: any;
+    /** Grid API 引用 */
+    gridApi?: GridApi;
+    /** 是否就绪 */
+    ready: boolean;
+}
+/**
+ * 分页大小选项
+ */
+export type PageSizeOptions = number[];
+/**
+ * 默认分页配置
+ */
+export interface DefaultPaginationConfig {
+    /** 默认分页大小 */
+    pageSize: number;
+    /** 分页大小选项 */
+    pageSizeOptions: PageSizeOptions;
+    /** 隐藏分页时的默认大小 */
+    hidePaginationSize: number;
+}
+/**
+ * 选中行变化回调
+ */
+export type OnSelectedRowsChange = (selectedRows: any[]) => void;
+/**
+ * Grid 就绪回调
+ */
+export type OnGridReady = (params: {
+    api: GridApi;
+    columnApi?: any;
+}) => void;
+/**
+ * 方案变化回调
+ */
+export type OnSchemeChange<T> = (scheme: T | null) => void;
+/**
+ * 方案保存回调
+ */
+export type OnSchemeSave<T> = (scheme: T) => void;
+/**
+ * 方案删除回调
+ */
+export type OnSchemeDelete = (schemeId: string) => void;
+/**
+ * 可空类型
+ */
+export type Nullable<T> = T | null | undefined;
+/**
+ * 记录类型 (键值对)
+ */
+export type RecordType<K extends string | number | symbol = string, V = any> = Record<K, V>;
+/**
+ * 深度部分可选
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * 列定义数组类型
+ */
+export type ColumnDefs = ExtendedColDef[];
+/**
+ * 列状态数组类型
+ */
+export type ColumnStates = ExtendedColumnState[];
+/**
+ * 行数据数组类型
+ */
+export type RowDataArray<T = any> = T[];
+/**
+ * 查询表单项数组类型
+ */
+export type QueryFormItems = QueryFormItem[];
+/**
+ * 扩展字段定义（来自后端 ABP 配置）
+ */
+export interface EntityExtensionField {
+    name: string;
+    displayName: string;
+    description?: string | null;
+    /** 数据类型: String, Int, Long, Decimal, Double, Float, Boolean, DateTime, Date, Guid, Enum, Text */
+    dataType: string;
+    maxLength?: number | null;
+    precision?: number | null;
+    scale?: number | null;
+    isRequired?: boolean;
+    sortOrder?: number;
+    uiComponent?: string | null;
+    placeholder?: string | null;
+    defaultValue?: any;
+    componentProps?: string | null;
+    validationRules?: string | null;
+}
+/**
+ * 单个实体的扩展配置
+ */
+export interface EntityExtensionConfig {
+    entityType: string;
+    displayName: string;
+    moduleName: string;
+    fields: EntityExtensionField[];
+}
+/**
+ * 实体扩展配置映射（key: 实体类型全名）
+ */
+export type HostEntityExtensions = Record<string, EntityExtensionConfig>;

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

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

package/dist/esm/ag-grid-plus/utils/agGridCompat.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AgGridPlus 与 AG-Grid 33 之间的兼容层（纯函数，无 React 依赖）。
+ *
+ * 1. qc-ui 专属 colDef / gridOptions 属性在传给 AG-Grid 之前集中剥离，否则 AG-Grid 会在控制台报
+ *    「invalid colDef / gridOptions property」。colDef 上的专属属性收进 `colDef.context[QC_COL_DEF_CONTEXT_KEY]`，
+ *    qc-ui 内部需要时通过 `getQcColDefProp` / `restoreQcColDef` 读回（renderDefaultCell、查询表单等）。
+ * 2. 调用方传入的 v32.2 以前的选择类旧选项映射为 v33 对象 API（rowSelection / cellSelection），业务写法保持有效。
+ * 3. getRowId 一律返回字符串（AG-Grid error #25），同一个解析器也供选中行比对使用，保证类型一致。
+ *
+ * 新增 qc-ui 专属属性时只需改下面两份清单。
+ *
+ * @author nokecy
+ */
+/** colDef.context 中存放被剥离的 qc-ui 专属列属性的键 */
+export declare const QC_COL_DEF_CONTEXT_KEY = "__qc";
+/**
+ * qc-ui 专属 colDef 属性清单（AG-Grid 不认识）。
+ * 注意：`fixed` / `pinned` 不在此列——列固定的别名处理不属于本层。
+ */
+export declare const QC_COL_DEF_ONLY_PROPS: readonly string[];
+/**
+ * qc-ui 专属 gridOptions 清单（AgGridPlus 自己消费，或历史文档遗留的无内部用途属性）。
+ * `enableQuerySchemes`、`defaultToolbarSlot` 目前没有内部消费者，仅为兼容旧写法而吞掉。
+ */
+export declare const QC_GRID_ONLY_PROPS: readonly string[];
+type AnyRecord = Record<string, any>;
+/** 剥离一组列定义中的 qc-ui 专属属性（幂等） */
+export declare function sanitizeColDefs<T>(defs: T): T;
+/** 读取列上的 qc-ui 专属属性：先看顶层（未净化的定义），再看 context（已净化的定义） */
+export declare function getQcColDefProp<T = any>(colDef: AnyRecord | null | undefined, key: string): T | undefined;
+/** 把 context 里的专属属性还原到顶层，供查询表单等只认顶层字段的内部代码使用 */
+export declare function restoreQcColDef<T extends AnyRecord | null | undefined>(colDef: T): T;
+/** 剥离 gridOptions 层的 qc-ui 专属属性 */
+export declare function sanitizeGridOptions<T extends AnyRecord>(options: T): Partial<T>;
+/**
+ * 创建 getRowId 解析器：返回值一律转字符串；用户函数返回 null/undefined 时回退默认生成，
+ * 避免出现 "undefined" / "null" 这类重复 ID。选中行比对与 AG-Grid 共用它，类型天然一致。
+ */
+export declare function createRowIdResolver(userGetRowId: ((params: any) => any) | undefined, fallback: (params: any) => string): (params: any) => string;
+export interface LegacySelectionInput {
+    rowSelection?: any;
+    /** 组件的 enableClickSelection prop；未传时由旧选项或默认值（true）决定 */
+    enableClickSelection?: boolean;
+    /** 透传给 AG-Grid 的其余 props（从中读取旧选项） */
+    legacy: AnyRecord;
+    columnDefs?: any;
+    autoGroupColumnDef?: AnyRecord;
+}
+export interface ResolvedSelectionOptions {
+    rowSelection: AnyRecord;
+    cellSelection: boolean | AnyRecord;
+    /** 净化后的 autoGroupColumnDef（去掉旧选择标志），没传则为 undefined */
+    autoGroupColumnDef?: AnyRecord;
+    /** 旧事件名映射出的新事件处理器 */
+    eventHandlers: AnyRecord;
+    /** 已被映射、需要从透传 props 里删除的旧选项键 */
+    consumedLegacyKeys: string[];
+}
+/** 从透传 props 中挑出旧版选择选项（体积很小，便于做深比较稳定引用） */
+export declare function pickLegacySelectionOptions(props: AnyRecord): AnyRecord;
+/**
+ * 把组件的选择相关输入（rowSelection 字符串/对象、enableClickSelection、旧版 gridOptions / colDef 选项）
+ * 统一解析成 AG-Grid 33 的 rowSelection 对象与 cellSelection。用户在对象里显式写的值优先于旧选项。
+ */
+export declare function resolveLegacySelectionOptions(input: LegacySelectionInput): ResolvedSelectionOptions;
+export {};