arthub-table 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/types/core/DataGrid.d.ts

@@ -12,7 +12,7 @@ import Histories from "./History";
 import { StyleManager, type TableTheme } from "./StyleManager";
 import EdgeScroller from "./EdgeScroller";
 import { type HeaderConfig } from "./util";
-import { type FooterCellClickInfo, type FooterData, type FooterCellData, type GroupHeaderCellClickInfo } from "./types";
+import { type FooterCellClickInfo, type FooterData, type FooterCellData, type GroupHeaderCellClickInfo, type FooterStatRefreshInfo, type GroupHeaderStatRefreshInfo } from "./types";
 import { type PerformanceMonitor } from "./PerformanceMonitor";
 interface Column extends HeaderConfig {
     children?: Column[];
@@ -60,6 +60,10 @@ interface RowDragState {
     isCtrlPressed: boolean;
     isShiftPressed: boolean;
     skipNextClick: boolean;
+    pendingCheckedRowDrag: boolean;
+    /** 当前鼠标位置（用于绘制拖拽幽灵元素） */
+    mouseX: number;
+    mouseY: number;
 }
 interface ColDragState {
     isDragging: boolean;
@@ -132,6 +136,11 @@ export interface DataGridOptions {
     borderWidth?: number;
     showCheckbox?: boolean;
     showTableIndex?: boolean;
+    /**
+     * 是否在表头左上角显示全选 checkbox
+     * 默认 false（不显示），设为 true 时表头左上角显示全选/半选 checkbox
+     */
+    showHeaderCheckbox?: boolean;
     /**
      * 索引列模式：
      * - 'auto'：自动模式，行号 = rowIndex + 1（默认）
@@ -247,6 +256,49 @@ export interface DataGridOptions {
             endRow: number;
             endCol: number;
         };
+        /** NestedGrid 实际渲染的数据数组（行索引与 autofillRange 完全一致） */
+        nestedGridData: any[];
+    }) => void;
+    /** 嵌套子表框选变化回调：选区跨子表或单子表变化时触发 */
+    onNestedSelectionChange?: (params: {
+        parentColKey: string;
+        selections: Array<{
+            parentRowData: any;
+            parentRowIndex: number;
+            parentColIndex: number;
+            selectionRange: {
+                startRow: number;
+                startCol: number;
+                endRow: number;
+                endCol: number;
+            };
+        }>;
+    }) => void;
+    /** 嵌套子表跨子表 autofill 结束回调 */
+    onNestedCrossAutofillEnd?: (params: {
+        parentColKey: string;
+        sourceSelections: Array<{
+            parentRowData: any;
+            parentRowIndex: number;
+            selectionRange: {
+                startRow: number;
+                startCol: number;
+                endRow: number;
+                endCol: number;
+            };
+        }>;
+        targetSelections: Array<{
+            parentRowData: any;
+            parentRowIndex: number;
+            autofillRange: {
+                startRow: number;
+                startCol: number;
+                endRow: number;
+                endCol: number;
+            };
+            /** NestedGrid 实际渲染的数据数组（行索引与 autofillRange 完全一致） */
+            nestedGridData: any[];
+        }>;
     }) => void;
     beforeCopy?: () => void;
     afterCopy?: () => void;
@@ -264,8 +316,32 @@ export interface DataGridOptions {
      * 默认 'controlled'
      */
     groupToggleMode?: 'controlled' | 'uncontrolled';
+    /**
+     * 分组维度数（由外部传入，优先级高于行数据遍历推断）。
+     * - 0 = 无分组
+     * - 1 = 一维分组
+     * - 2 = 二维分组
+     * - 3 = 三维分组
+     * 未传入时退化为遍历行数据推断（旧逻辑）。
+     */
+    groupDimension?: number;
     /** 是否启用内置键盘快捷键（默认 false） */
     enableKeyboardShortcuts?: boolean;
+    /**
+     * Whether to disable DataGrid's built-in "click outside to close editing" behavior.
+     *
+     * When true, handleDocumentMouseDown will NOT execute:
+     * - doneEdit() (close internal editor)
+     * - clearSelectedCols() (clear column selection)
+     * - clearCellSelection() (clear cell selection)
+     * - afterSelectCell(null) (notify external to close editor panel)
+     *
+     * Use this when the host application (e.g. AssetMatrix) manages "click outside"
+     * via its own mechanism (e.g. v-click-outside) with finer-grained exclusion logic.
+     *
+     * Default: false (preserves existing behavior for backward compatibility).
+     */
+    disableClickOutside?: boolean;
     onTreeExpand?: (rowData: RowData, expanded: boolean) => void;
     onCellTextClick?: (rowData: RowData, colId: string) => void;
     onCellTotalNumClick?: (rowData: RowData, colId: string) => void;
@@ -323,12 +399,20 @@ export interface DataGridOptions {
     debug?: boolean;
     /** WfState Viewer 显示样式：'icon'=图标+文字（默认），'tag'=色块标签 */
     wfStateStyle?: 'icon' | 'tag';
+    /** 列总宽小于表格可视区域宽度时，是否将剩余空间均分到每列（默认 false） */
+    autoFillTableWidth?: boolean;
     /** 是否显示底部统计行 */
     showFooter?: boolean;
+    /** 底部统计行高度（默认 FOOTER_HEIGHT = 36） */
+    footerHeight?: number;
     /** Footer 单元格点击回调 */
     onFooterCellClick?: (info: FooterCellClickInfo) => void;
     /** 组头单元格点击回调 */
     onGroupHeaderCellClick?: (info: GroupHeaderCellClickInfo) => void;
+    /** Footer 嵌套列统计刷新回调 */
+    onFooterStatRefresh?: (info: FooterStatRefreshInfo) => void;
+    /** 组头嵌套列统计刷新回调 */
+    onGroupHeaderStatRefresh?: (info: GroupHeaderStatRefreshInfo) => void;
     /** Viewer 编辑图标点击回调（拦截内置编辑器，由外部处理编辑） */
     onEditIconClick?: (info: {
         rowData: RowData;
@@ -410,6 +494,24 @@ export interface DataGridOptions {
         isNestedChild: boolean;
         nestedChildOffset: number;
     }) => void;
+    /** Cell hover 变化回调：当 hover 的单元格变化时通知外部（用于时间型字段 tooltip / 历史变更等） */
+    onCellHoverChange?: (info: {
+        show: boolean;
+        rowIndex: number;
+        colIndex: number;
+        colKey: string;
+        rowData: Record<string, any>;
+        position: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        canvasElement: HTMLCanvasElement;
+        displayText: string;
+        mouseX: number;
+        mouseY: number;
+    }) => void;
     /** Error icon hover 回调：当鼠标悬停在 warning icon 上时触发（用于外部 AlarmPopper） */
     onErrorIconHover?: (info: {
         show: boolean;
@@ -474,6 +576,48 @@ export interface DataGridOptions {
     onBeforeRowRender?: (rowIndex: number, rowData: RowData) => void;
     /** 嵌套表格渲染前回调：每个嵌套表格格子绘制前触发，用于分组表格管线列渐进式加载 */
     onBeforeNestedGridRender?: (rowIndex: number, rowData: RowData, colKey: string) => void;
+    /**
+     * 嵌套子表数据比对 key 列表（性能优化）。
+     * 在 loadData/refreshDataGrid 时，通过比较新旧嵌套数据中这些 key 的值来判断数据是否变化。
+     * 如果未变化，则复用旧的 NestedGrid 实例，跳过重建。
+     * 默认 ['id']——只比较子行 id 列表。
+     *
+     * 对应 DOM 版本的 REFRESH_TABLE_COMPARE_KEYS。
+     */
+    nestedDataCompareKeys?: string[];
+    /**
+     * 嵌套子表强制刷新 key 列表（性能优化）。
+     * 当新嵌套数据中任意一行包含这些 key 且有值时，跳过数据比对，强制重建 NestedGrid。
+     * 默认 []（不强制刷新）。
+     *
+     * 对应 DOM 版本的 FORCE_REFRESH_KEYS。
+     */
+    nestedForceRefreshKeys?: string[];
+    /** 普通行 checkbox 变更回调（受控模式下通知外部更新选中行列表） */
+    onRowCheckChange?: (info: {
+        rowId: string;
+        checked: boolean;
+        rowData: any;
+        selectedRowIds: string[];
+        event?: MouseEvent;
+    }) => void;
+    /** 组头 checkbox 变更回调（受控模式下通知外部更新组头选中状态） */
+    onGroupCheckboxChange?: (info: {
+        groupId: string | number;
+        checked: boolean;
+        data: any;
+        selectedRowIds: string[];
+    }) => void;
+    /**
+     * Cell value transformer callback.
+     * Called by Cell.drawWithViewer() before passing data to viewer.draw().
+     * Transforms raw cell values to display values (e.g. treeDropdown ID → display name + color).
+     * Return undefined to keep the original value.
+     *
+     * TODO: Migrate other viewer types (person, module, wf-state, task-node, dropdown, etc.)
+     *       from transformCellValues to this callback for full decoupling.
+     */
+    cellValueTransformer?: import('./viewers/types').CellValueTransformer;
 }
 declare class DataGrid {
     target: HTMLCanvasElement;
@@ -519,6 +663,8 @@ declare class DataGrid {
     borderWidth: number;
     showCheckbox: boolean;
     showTableIndex: boolean;
+    /** 是否在表头左上角显示全选 checkbox，默认 false */
+    showHeaderCheckbox: boolean;
     /** 索引列模式：'auto' = rowIndex+1，'data' = 从行数据 _tableIndex 读取 */
     tableIndexMode: 'auto' | 'data';
     headerHeight: number;
@@ -567,6 +713,8 @@ declare class DataGrid {
     onNestedAutofillStart?: DataGridOptions['onNestedAutofillStart'];
     onNestedAutofillDragging?: DataGridOptions['onNestedAutofillDragging'];
     onNestedAutofillEnd?: DataGridOptions['onNestedAutofillEnd'];
+    onNestedSelectionChange?: DataGridOptions['onNestedSelectionChange'];
+    onNestedCrossAutofillEnd?: DataGridOptions['onNestedCrossAutofillEnd'];
     beforeCopy: () => void;
     afterCopy: () => void;
     beforePaste: () => void;
@@ -580,8 +728,13 @@ declare class DataGrid {
     groupToggleMode: 'controlled' | 'uncontrolled';
     /** 是否启用内置键盘快捷键 */
     enableKeyboardShortcuts: boolean;
+    /** Whether to disable built-in "click outside to close editing" behavior */
+    disableClickOutside: boolean;
     /** 非受控模式下的完整数据（包含所有分组的子行） */
     private _fullData;
+    /** 双缓冲：离屏 canvas（避免每帧创建，懒初始化 + 复用） */
+    private _offscreenCanvas;
+    private _offscreenCtx;
     onTreeExpand?: (rowData: RowData, expanded: boolean) => void;
     onCellTextClick?: (rowData: RowData, colId: string) => void;
     onCellTotalNumClick?: (rowData: RowData, colId: string) => void;
@@ -608,9 +761,27 @@ declare class DataGrid {
     onScrollEnd?: () => void;
     private scrollEndTimer;
     private wasScrolling;
+    /** 列总宽小于表格可视区域宽度时，是否将剩余空间均分到每列（默认 false） */
+    autoFillTableWidth: boolean;
     showFooter: boolean;
+    /** 用户自定义的 footer 行高度（默认 FOOTER_HEIGHT） */
+    _footerHeight: number;
     onFooterCellClick?: (info: FooterCellClickInfo) => void;
     onGroupHeaderCellClick?: (info: GroupHeaderCellClickInfo) => void;
+    onFooterStatRefresh?: (info: FooterStatRefreshInfo) => void;
+    onGroupHeaderStatRefresh?: (info: GroupHeaderStatRefreshInfo) => void;
+    /** Footer 弹窗激活的列标识 key（弹窗打开时设置，关闭时清除），保持该列的下拉箭头和刷新图标始终显示 */
+    footerPopoverActiveKey: string | null;
+    /** 组头弹窗激活的列标识 key（弹窗打开时设置，关闭时清除） */
+    groupHeaderPopoverActiveKey: string | null;
+    /** 普通行 checkbox 变更回调（受控模式） */
+    onRowCheckChange?: (info: {
+        rowId: string;
+        checked: boolean;
+        rowData: any;
+        selectedRowIds: string[];
+        event?: MouseEvent;
+    }) => void;
     /** 组头 checkbox 变更回调（校验勾选） */
     onGroupCheckboxChange?: (info: {
         groupId: string | number;
@@ -653,11 +824,19 @@ declare class DataGrid {
     onBeforeRowRender?: (rowIndex: number, rowData: RowData) => void;
     /** 嵌套表格渲染前回调：每个嵌套表格格子绘制前触发，用于分组表格管线列渐进式加载 */
     onBeforeNestedGridRender?: (rowIndex: number, rowData: RowData, colKey: string) => void;
+    /** Cell value transformer (see DataGridOptions.cellValueTransformer) */
+    cellValueTransformer?: import('./viewers/types').CellValueTransformer;
+    nestedDataCompareKeys: string[];
+    nestedForceRefreshKeys: string[];
     range: RangeState;
     columns: HeaderConfig[];
     headers: HeaderConfig[];
     columnsLength: number;
     originFixedWidth: number;
+    /** Maximum group level in current data (-1=no groups, 0=1D, 1=2D, 2+=3D) */
+    maxGroupLevel: number;
+    /** Whether groupDimension was explicitly set from outside (disables auto-detection) */
+    private _groupDimensionFromOption;
     containerOriginX: number;
     containerOriginY: number;
     width: number;
@@ -680,8 +859,15 @@ declare class DataGrid {
     private loadingRotation;
     private loadingImage;
     private loadingAnimationId;
+    /** Footer/GroupRow 嵌套列刷新图标（预加载 SVG） */
+    private refreshIcon;
+    /** Footer/GroupRow loading 计数器（用于控制 loading 动画的启停） */
+    private footerLoadingCount;
     colResizeIndicatorX: number;
     private columnHighlightMap;
+    private headerTextColorMap;
+    private sortOrderMap;
+    private sortOrderCount;
     private _searchMatchColors;
     hoveredHeaderColId: string | null;
     onHeaderSortClick?: (info: {
@@ -705,6 +891,23 @@ declare class DataGrid {
         clientX: number;
         clientY: number;
     }) => void;
+    onCellHoverChange?: (info: {
+        show: boolean;
+        rowIndex: number;
+        colIndex: number;
+        colKey: string;
+        rowData: Record<string, any>;
+        position: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        canvasElement: HTMLCanvasElement;
+        displayText: string;
+        mouseX: number;
+        mouseY: number;
+    }) => void;
     onErrorIconHover?: (info: {
         show: boolean;
         position: {
@@ -820,6 +1023,12 @@ declare class DataGrid {
      * 列总宽小于可视区域宽度时，需要补齐
      */
     fillTableWidth(): void;
+    /**
+     * Clamp scrollX/scrollY to valid bounds after layout changes (column add/remove, resize, etc.).
+     * Prevents white gaps when total content size shrinks below the current scroll offset.
+     * Also updates scrollbar thumb positions.
+     */
+    clampScrollPosition(): void;
     resize(): void;
     /**
      * Restore all column widths (leaf and nested children) to their saved base values.
@@ -837,6 +1046,7 @@ declare class DataGrid {
      * Shared by row-header drag-select and edge-scroll callback.
      */
     selectRowRange(startIndex: number, endIndex: number): void;
+    private _nestedDebugLogged;
     selectCell({ colIndex, rowIndex }: {
         colIndex: number;
         rowIndex: number;
@@ -883,6 +1093,15 @@ declare class DataGrid {
      * 清除列选中状态
      */
     clearSelectedCols(): void;
+    /**
+     * Clear all row selection (checkbox) state.
+     * Clears selectedRowIds, unchecks all rows, syncs group headers, and updates header indeterminate.
+     */
+    clearRowSelection(): void;
+    /**
+     * Clear cell/multi-cell selection state (selector highlight and focus cell).
+     */
+    clearCellSelection(): void;
     /**
      * 判断列是否被选中（通过uniqueColKey判断，不随列排序变化）
      */
@@ -955,7 +1174,10 @@ declare class DataGrid {
     drawContainer(): void;
     draw(): void;
     /**
-     * 绘制嵌套列的彩色垂直边框，贯穿整个 body 区域（包括分组行和分隔行）
+     * 绘制嵌套列的彩色垂直边框。
+     * 在数据行（Row）、组头行（GroupRow）、加号行（AddTaskRow）和分隔行（SeparateRow）的 Y 范围内绘制。
+     * 相邻行的范围会合并，确保竖线连续不断裂。
+     * clip 到非冻结列区域，避免穿透到冻结列。
      */
     drawNestedColumnBorders(): void;
     /**
@@ -982,7 +1204,19 @@ declare class DataGrid {
     refreshSelectorFromSelectedCols(): void;
     loadData(data: RowData[], options?: {
         preserveSelection?: boolean;
+        groupDimension?: number;
     }): void;
+    /**
+     * 动态更新分组维度并触发完整重绘。
+     *
+     * 当外部分组方式变化（如从二维切到三维）时调用此方法，
+     * 会更新 maxGroupLevel、originFixedWidth，清空行缓存，
+     * 重建表头和表格尺寸，确保所有行（组头、数据行、+号行、分割行）
+     * 都使用新的分组维度样式重新绘制。
+     *
+     * @param dimension - 分组维度数（0=无分组, 1=一维, 2=二维, 3=三维）
+     */
+    setGroupDimension(dimension: number, skipRepaint?: boolean): void;
     /**
      * 增量刷新指定列的数据（不重建整张表）
      *
@@ -1142,6 +1376,16 @@ declare class DataGrid {
         maxScrollX: number;
         maxScrollY: number;
     };
+    /**
+     * 滚动到最右边（水平方向）
+     */
+    scrollToRight(): void;
+    /**
+     * 滚动到指定水平位置（使 left 位置出现在视口右边缘）
+     * 与 DOM 版本 fattable.scrollLeftTo(left) 语义一致：scrollLeft = left - clientWidth
+     * @param left 目标位置（正值，单位 px）
+     */
+    scrollLeftTo(left: number): void;
     /**
      * 判断指定 rowIndex 的行是否完全在可见视口内
      * @param rowIndex - data 数组中的行索引
@@ -1210,9 +1454,13 @@ declare class DataGrid {
      */
     scrollCellIntoViewById(rowId: string | number, colIndex: number): void;
     /**
-     * 预加载 loading 图片
+     * 预加载 loading 图片和刷新图标
      */
     private preloadLoadingImage;
+    /**
+     * 预加载刷新 SVG 图标（icon_backtodefault），转换为可绘制的 Image 对象
+     */
+    private preloadRefreshIcon;
     /**
      * 显示指定单元格的 loading 状态
      * @param rowIds 行的唯一标识数组（基于 rowKey 配置对应的行数据字段值）
@@ -1246,6 +1494,18 @@ declare class DataGrid {
      * 获取预加载的 loading 图片
      */
     getLoadingImage(): HTMLImageElement | null;
+    /**
+     * 获取预加载的刷新图标
+     */
+    getRefreshIcon(): HTMLImageElement | null;
+    /**
+     * 增加 footer/groupRow loading 引用计数，确保动画持续运行
+     */
+    addFooterLoading(): void;
+    /**
+     * 减少 footer/groupRow loading 引用计数
+     */
+    removeFooterLoading(): void;
     /**
      * 启动 loading 动画循环（轻量级：仅更新角度 + markDirty）
      */
@@ -1275,6 +1535,39 @@ declare class DataGrid {
      * @returns 高亮色字符串，未设置时返回空字符串
      */
     getColumnHighlightColor(columnKey: string): string;
+    /**
+     * 批量设置表头文字颜色（用于新加入字段紫色高亮等场景）
+     * @param colors 表头文字颜色映射对象：{ columnKey: color }，color 为空字符串表示清除
+     */
+    setHeaderTextColors(colors: Record<string, string>): void;
+    /**
+     * 获取指定列的表头文字颜色
+     * @param columnKey 列的 key 标识
+     * @returns 文字颜色字符串，未设置时返回空字符串
+     */
+    getHeaderTextColor(columnKey: string): string;
+    /**
+     * 批量设置排序状态（替换所有排序）
+     * @param orders 排序数组：[{ meta: string, type: 'asc'|'desc' }]
+     *   meta 对应列的 convertMeta，type 为排序方向
+     */
+    setSortOrders(orders: Array<{
+        meta: string;
+        type: 'asc' | 'desc';
+    }>): void;
+    /**
+     * 获取指定列的排序状态
+     * @param convertMeta 列的 convertMeta 标识
+     * @returns 排序状态对象，未排序时返回 null
+     */
+    getSortOrder(convertMeta: string): {
+        type: 'asc' | 'desc';
+        index: number;
+    } | null;
+    /**
+     * 获取当前排序列总数
+     */
+    getSortOrderCount(): number;
     /**
      * 设置搜索匹配颜色
      */
@@ -1457,9 +1750,20 @@ declare class DataGrid {
      * @returns Row index or -1 if not found
      */
     private findRowIndexById;
+    /**
+     * 根据数据中最大 groupLevel 动态计算 originFixedWidth（index 列宽度）
+     * 规则：
+     * - 非分组/一维分组(maxLevel=0): 52px
+     * - 二维分组(maxLevel=1): 62px
+     * - 三维分组(maxLevel>=2): 72px
+     * @param data 可选，如果不传则使用当前 this.data
+     */
+    recalcOriginFixedWidth(data?: RowData[]): void;
     /** 动态切换 footer 显示状态 */
     setShowTableIndex(show: boolean): void;
     setShowFooter(show: boolean): void;
+    /** 动态设置 footer 行高度 */
+    setFooterHeight(height: number): void;
     /** 一次性设置所有列的 footer 统计数据 */
     setFooterData(data: FooterData): void;
     /** 设置单列的 footer 统计数据 */
@@ -1468,6 +1772,24 @@ declare class DataGrid {
     setGroupHeaderStatData(groupId: string | number, data: FooterData): void;
     /** 设置指定分组指定列的组头统计数据 */
     setGroupHeaderStatCellData(groupId: string | number, columnKey: string, cellData: FooterCellData): void;
+    /**
+     * 设置所有组头行中指定列的 loading 状态
+     * @param columnKey - 列标识 key（嵌套列格式为 "moduleColKey::childKey"）
+     * @param loading - 是否设为 loading 状态
+     */
+    setGroupHeaderColumnLoading(columnKey: string, loading: boolean): void;
+    /**
+     * 设置 Footer 弹窗激活的列标识（弹窗打开时调用），
+     * 使该列的下拉箭头和刷新图标在鼠标移开后仍保持显示。
+     * 传 null 表示关闭弹窗、清除激活状态。
+     */
+    setFooterPopoverActive(key: string | null): void;
+    /**
+     * 设置组头弹窗激活的列标识（弹窗打开时调用），
+     * 使该列的下拉箭头和刷新图标在鼠标移开后仍保持显示。
+     * 传 null 表示关闭弹窗、清除激活状态。
+     */
+    setGroupHeaderPopoverActive(key: string | null): void;
     /** 从 body.data 中查找指定 groupId 的 GroupRowData */
     private findGroupRowData;
     /**

package/dist/types/core/Footer.d.ts

@@ -4,8 +4,10 @@ declare class Footer {
     grid: DataGrid;
     footerData: FooterData;
     hoverColIndex: number;
+    /** 当 hover 列为 nested 父列时，记录鼠标所在的子列偏移索引（-1 表示不在子列上） */
+    hoverSubColIndex: number;
     constructor(grid: DataGrid);
-    /** Footer 行高度 */
+    /** Footer 行高度（从 DataGrid._footerHeight 读取，支持自定义） */
     get height(): number;
     /** Footer Y 坐标（固定在可视区域底部，水平滚动条上方） */
     get y(): number;
@@ -17,20 +19,45 @@ declare class Footer {
     cleanupFooterData(existingKeys: Set<string>): void;
     /** 判断鼠标是否在 footer 区域内 */
     isInFooterArea(x: number, y: number): boolean;
-    /** 获取鼠标悬停所在的列索引（考虑固定列和滚动偏移） */
+    /** 获取鼠标悬停所在的列索引（考虑固定列和滚动偏移），同时更新 hoverSubColIndex */
     getHoverColumnIndex(mouseX: number): number;
+    /** 获取指定 nested 父列的所有子列列头 */
+    private getNestedChildHeaders;
+    /** 安全获取 canvas 元素的视口边界（测试环境中 target 可能不存在） */
+    private getCanvasRect;
     /** 获取列在屏幕上的实际 X 坐标 */
     private getColumnScreenX;
     /** 处理鼠标单击事件 */
     onClick(mouseX: number, mouseY: number, clientX: number, clientY: number): void;
+    /** 处理 nested 子列点击 */
+    private onNestedChildClick;
+    /**
+     * 检测鼠标是否在刷新图标区域内（嵌套子列的刷新按钮）
+     * 布局从右到左：[下拉箭头(ARROW_ICON_SIZE)] [刷新icon(REFRESH_ICON_PADDING + REFRESH_ICON_SIZE + REFRESH_ICON_PADDING)]
+     */
+    private isInsideRefreshIcon;
     /** 从列配置中查找指定索引的列 */
     private findColumnConfig;
     /** 绘制 footer */
     draw(): void;
     /** 绘制单个 footer 单元格 */
     private drawFooterCell;
+    /** 绘制 nested 列的子单元格拆分渲染 */
+    private drawNestedFooterCell;
     /** 绘制 "数据统计" 提示文字 */
     private drawHintText;
+    /** 绘制 "数据统计" 提示文字（指定最大宽度） */
+    private drawHintTextWithMaxWidth;
+    /**
+     * 绘制刷新图标（icon_backtodefault）
+     * @param x 刷新图标区域左边界（包含 padding）
+     */
+    private drawRefreshIcon;
+    /**
+     * 绘制 loading 旋转图标（替代刷新icon位置）
+     * @param x loading 图标区域左边界（包含 padding，与刷新icon位置对齐）
+     */
+    private drawLoadingIcon;
     /**
      * 截断文字并添加省略号，不压缩文字宽度
      */