@canvas-components/list-table 0.2.3 → 0.2.5

package/dist/index.d.cts

@@ -58,6 +58,28 @@ type ListTableFilterState = Record<string, ListTableFilterValue$1>;
 interface ListTableSelectionState {
     rowIndex: number | null;
     columnKey: string | null;
+    /** 当前活动单元格内模拟的文本选区。 */
+    textSelection?: ListTableTextSelectionState | null;
+}
+/**
+ * Canvas 文本选区状态。
+ */
+interface ListTableTextSelectionState {
+    fragments: ListTableTextSelectionFragment[];
+    anchorFragmentIndex: number;
+    focusFragmentIndex: number;
+    anchorOffset: number;
+    focusOffset: number;
+}
+/**
+ * 单元格内一个可选择的可视文本片段。
+ */
+interface ListTableTextSelectionFragment {
+    rowIndex?: number;
+    columnKey?: string;
+    contentIndex: number;
+    fragmentKey: string;
+    text: string;
 }
 /**
  * 表头 action 显隐状态。
@@ -82,6 +104,26 @@ interface ListTableDebugOptions {
     showHeaderActionOverlay?: boolean;
     logDrawCalls?: boolean;
     logStateChanges?: boolean;
+    /**
+     * 性能阶段埋点回调。仅在配置后执行，不影响默认渲染路径。
+     */
+    onPerformance?: (metric: ListTablePerformanceMetric) => void;
+}
+/**
+ * 列表表格性能阶段指标。
+ */
+interface ListTablePerformanceMetric {
+    phase: "grouping" | "snapshot" | "render";
+    durationMs: number;
+    inputRowCount: number;
+    outputRowCount: number;
+    cacheHit?: boolean;
+    groupedRowCount?: number;
+    scrollOnly?: boolean;
+    batchCount?: number;
+    indexNodeCount?: number;
+    cancelledCount?: number;
+    status?: "ready" | "cancelled" | "error";
 }
 /**
  * 查询回调扩展参数。
@@ -110,7 +152,7 @@ interface Rect {
  * 命中结果。
  */
 interface DebugHitTestResult {
-    area: "header" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "sort-trigger" | "filter-trigger" | "fixed-trigger" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary" | "summary" | "empty";
+    area: "header" | "grouping-bar" | "grouping-tag" | "grouping-remove" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "sort-trigger" | "filter-trigger" | "fixed-trigger" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary" | "summary" | "empty";
     scrollbarRole?: "thumb" | "track" | "decrease-button" | "increase-button";
     columnKey?: string;
     rowIndex?: number;
@@ -128,6 +170,13 @@ interface DebugHitTestResult {
     rect?: Rect;
     tooltipText?: string;
     tooltipVariant?: "default" | "error";
+    textSelectionText?: string;
+    textSelectionFont?: string;
+    textSelectionFragmentKey?: string;
+    textSelectionOriginX?: number;
+    /** 表头文本所属层级，用于跨层拖选时区分行。 */
+    textSelectionRowIndex?: number;
+    textSelectionRect?: Rect;
 }
 /**
  * action 类型。
@@ -137,7 +186,7 @@ type HeaderActionType = "sort" | "filter" | "fixed";
  * 渲染矩形描述。
  */
 interface RenderCellDescriptor {
-    kind: "header" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "header-action" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary";
+    kind: "header" | "grouping-bar" | "grouping-tag" | "grouping-remove" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "header-action" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary";
     rect: Rect;
     columnKey?: string;
     rowIndex?: number;
@@ -153,6 +202,17 @@ interface RenderCellDescriptor {
     cursor?: string;
     tooltipText?: string;
     tooltipVariant?: "default" | "error";
+    /** 可参与 Canvas 文本选择的实际绘制文本。 */
+    textSelectionText?: string;
+    /** 文本命中时使用的 Canvas 字体。 */
+    textSelectionFont?: string;
+    /** 同一单元格内文本布局片段的稳定标识。 */
+    textSelectionFragmentKey?: string;
+    /** 文本未裁剪前的绘制起点。 */
+    textSelectionOriginX?: number;
+    /** 表头文本所属层级，用于跨层拖选时区分行。 */
+    textSelectionRowIndex?: number;
+    textSelectionRect?: Rect;
     actionType?: HeaderActionType;
     scrollbarRole?: "thumb" | "track" | "decrease-button" | "increase-button";
     visibilityState?: HeaderActionVisibilityState;
@@ -213,6 +273,7 @@ interface ListTableTheme {
     frozenRowBackgroundColor: string;
     hoverBackgroundColor: string;
     selectionBackgroundColor: string;
+    textSelectionBackgroundColor?: string;
     emptyBackgroundColor: string;
     emptyTextColor: string;
     debugStrokeColor: string;
@@ -234,8 +295,25 @@ interface ListTableTheme {
  * - `max`：取当前列最大值
  */
 type ListTableSummaryType = "sum" | "avg" | "count" | "unionCount" | "rowCount" | "mergedRowCount" | "min" | "max";
+/** 汇总结果的小数取整方式。 */
+type ListTableSummaryRoundingMode = "round" | "floor" | "ceil" | "truncate";
 type ListTableHorizontalAlign = "left" | "center" | "right";
-type ListTableDataFormatType = "default" | "number" | "thousands" | "money";
+type ListTableDataFormatType = "default" | "text" | "number" | "thousands" | "decimal" | "percent" | "percentDecimal" | "scientific" | "numberToChineseUpper" | "chineseUpperToNumber" | "cny" | "cnyDecimal" | "usd" | "usdDecimal" | "dateSlash" | "dateDash" | "dateFullCN" | "dateYearMonthCN" | "dateMonthDayCN" | "dateSlashWeek" | "dateDashWeek" | "dateWeekdayCNFull" | "dateWeekdayCNShort" | "time" | "timeShort" | "time12" | "time12Seconds" | "timeMillisecond" | "time12Millisecond" | "timeChineseHour" | "timeChineseSecond" | "time12ChineseHour" | "time12ChineseSecond" | "datetime" | "datetime12" | "datetime12Seconds" | "custom" | "money";
+/** 可持久化的数据显示格式配置。 */
+interface ListTableDataFormatOptions {
+    /** 基础格式类型。 */
+    type: ListTableDataFormatType;
+    /** 小数位数，支持 0 到 20。 */
+    decimalPlaces?: number;
+    /** 是否显示千分位分隔符。 */
+    useGrouping?: boolean;
+    /** 货币符号。 */
+    symbol?: string;
+    /** 日期、时间或自定义格式模式。 */
+    pattern?: string;
+}
+/** 数据显示格式，字符串用于快捷格式，对象用于精确格式配置。 */
+type ListTableDataFormat = ListTableDataFormatType | ListTableDataFormatOptions;
 type ListTableFilterOptionValue = string | number | null;
 interface ListTableFilterOption {
     label: string;
@@ -251,8 +329,12 @@ interface ListTableSummaryConfig<RecordType = Record<string, unknown>> {
     valueGetter?: (record: RecordType) => string | number | null | undefined;
     /** 值格式化函数。 */
     formatter?: (value: string | number, records: RecordType[], column: ListTableColumn<RecordType>) => string;
-    /** 小数精度（四舍五入），不传则整数不保留小数、非整数保留两位。 */
+    /** 小数精度，不传则整数不保留小数、非整数保留两位。 */
     precision?: number;
+    /** 小数取整方式，默认四舍五入。 */
+    roundingMode?: ListTableSummaryRoundingMode;
+    /** 是否保留精度补齐产生的无效零，默认不保留。 */
+    preserveTrailingZeros?: boolean;
 }
 /**
  * 路径索引定义。
@@ -329,7 +411,7 @@ type ListTableFormRules<RecordType = Record<string, unknown>> = ListTableFormRul
  * 单元格内容片段样式。
  */
 interface ListTableContentStyle {
-    display?: "block" | "inline-block";
+    display?: "none" | "block" | "inline-block";
     textAlign?: CanvasTextAlign;
     fontSize?: number;
     fontWeight?: string;
@@ -348,6 +430,8 @@ interface ListTableContentStyle {
  */
 interface ListTableBaseCellContent<RecordType = any> {
     key?: string;
+    /** 是否展示内容，默认展示。 */
+    visible?: boolean;
     style?: ListTableContentStyle;
     cursor?: string;
     onClick?: (context: ListTableCellContentClickContext<RecordType>) => void;
@@ -777,7 +861,7 @@ interface ListTableColumn<RecordType = Record<string, unknown>> {
     /** 金额单元格格式配置，仅在 `cellType: "money"` 时生效。 */
     moneyFormat?: ListTableMoneyFormatOptions;
     /** 通过列设置覆盖的数据显示格式。 */
-    dataFormat?: ListTableDataFormatType;
+    dataFormat?: ListTableDataFormat;
     headerStyle?: ListTableCellStyle;
     /** 汇总行配置。设为 `true` 等效于 `{ type: "sum" }`。 */
     summary?: boolean | ListTableSummaryConfig<RecordType>;
@@ -917,6 +1001,7 @@ interface HeaderContextMenuConfig {
     onCopyRowText?: () => void;
     onCopyRowJson?: () => void;
     onCopySelection?: () => void;
+    onOpenSearch?: () => void;
     customSelection?: {
         startRow: number;
         startColumn: number;
@@ -948,7 +1033,21 @@ interface HeaderContextMenuConfig {
     onUnfreezeRow?: () => void;
     onResetFilter?: () => void;
     onResetSort?: () => void;
+    onSortAscend?: () => void;
+    onSortDescend?: () => void;
+    onClearSort?: () => void;
+    onFixLeft?: () => void;
+    onFixRight?: () => void;
+    onUnfix?: () => void;
     onResetHeader?: () => void;
+    onResetGrouping?: () => void;
+    onResetSummary?: () => void;
+    onResetAlignment?: () => void;
+    onResetDataFormat?: () => void;
+    onAutoFitCurrentColumn?: () => void;
+    onAutoFitAllColumns?: () => void;
+    groupingBarVisible?: boolean;
+    onToggleGroupingBar?: () => void;
     onChangeDensity?: (density: HeaderContextMenuDensity) => void;
     /**
      * 调整表格缩放。
@@ -962,15 +1061,28 @@ interface HeaderContextMenuConfig {
         bodyVertical: "top" | "middle" | "bottom";
     };
     onChangeAlignment?: (area: "header" | "body", axis: "horizontal" | "vertical", value: ListTableHorizontalAlign | "top" | "middle" | "bottom") => void;
-    dataFormat?: ListTableDataFormatType;
-    onChangeDataFormat?: (dataFormat: ListTableDataFormatType) => void;
+    dataFormat?: ListTableDataFormat;
+    onChangeDataFormat?: (dataFormat: ListTableDataFormat) => void;
     summaryVisible?: boolean;
     summaryColumnKey?: string;
     summaryType?: ListTableSummaryType;
     summaryPrecision?: number;
+    summaryRoundingMode?: ListTableSummaryRoundingMode;
+    summaryPreserveTrailingZeros?: boolean;
     onToggleSummary?: () => void;
     onChangeSummaryType?: (type: ListTableSummaryType) => void;
     onChangeSummaryPrecision?: (precision: number | undefined) => void;
+    onChangeSummaryRoundingMode?: (mode: ListTableSummaryRoundingMode) => void;
+    onChangeSummaryPreserveTrailingZeros?: (value: boolean) => void;
+    onClose: () => void;
+}
+interface ListTableSearchRequest {
+    keyword: string;
+    matchCount: number;
+    currentIndex: number;
+    /** 提交关键词并重新计算匹配项。 */
+    onSubmit: (keyword: string) => void;
+    onNavigate: (direction: "previous" | "next") => void;
     onClose: () => void;
 }
 interface PaginationConfig {
@@ -1259,7 +1371,18 @@ type ListTableHighlightMode = "cell" | "row" | "column" | "cross";
 /**
  * 右键菜单功能项。
  */
-type ListTableContextMenuFeature = "copy" | "export" | "downloadContent" | "rowCollapse" | "columnCollapse" | "freeze" | "reset" | "density" | "zoom" | "alignment" | "dataFormat" | "columnVisibility";
+type ListTableContextMenuFeature = "copy" | "search" | "export" | "downloadContent" | "rowCollapse" | "columnCollapse" | "freeze" | "reset" | "sort" | "density" | "zoom" | "columnWidth" | "alignment" | "dataFormat" | "grouping" | "columnVisibility";
+/**
+ * 数据分组配置。
+ */
+interface ListTableGroupingOptions {
+    /** 是否初始显示顶部的分组栏，默认 false。 */
+    visible?: boolean;
+    /** 初始分组列 key，顺序表示分组层级。 */
+    columnKeys?: string[];
+    /** 分组列变化回调。 */
+    onChange?: (columnKeys: string[]) => void;
+}
 /**
  * 右键菜单配置。
  */
@@ -1432,7 +1555,7 @@ interface ListTableRowSelectionOptions<RecordType> {
     /**
      * 点击普通表体区域时是否切换当前行选择状态。
      *
-     * @default false
+     * @default true
      */
     selectRowByClick?: boolean;
     selectedRowKeys?: Array<string | number>;
@@ -1494,9 +1617,23 @@ interface ListTableUiOptions {
     onFilterPanelRequest?: (request: FilterPanelConfig | null) => void;
     onFixedPopupRequest?: (request: FixedPopupConfig | null) => void;
     onHeaderContextMenuRequest?: (request: HeaderContextMenuConfig | null) => void;
+    onSearchRequest?: (request: ListTableSearchRequest | null) => void;
     onImagePreviewRequest?: (request: ListTableImagePreviewRequest | null) => void;
     onDangerConfirmRequest?: (request: ListTableDangerConfirmRequest | null) => void;
 }
+/**
+ * 行选择器配置。
+ *
+ * 行选择器是位于表格最左侧的空白系统列，仅用于快速选中整行，
+ * 不参与 checkbox/radio 行数据选择。
+ */
+interface ListTableRowSelectorOptions {
+    /**
+     * 选择器列宽度。
+     * @default 12
+     */
+    width?: number;
+}
 interface ListTableImagePreviewRequest {
     src: string;
     alt?: string;
@@ -1519,6 +1656,9 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     height?: number | string;
     columns: ListTableColumn<RecordType>[];
     dataSource: RecordType[];
+    /** 顶部分组栏与数据分组配置。 */
+    /** 数据分组配置；不传时不启用分组功能。 */
+    grouping?: ListTableGroupingOptions;
     /** AntD Table 风格的行事件配置。 */
     onRow?: (record: RecordType, rowIndex: number) => ListTableRowEventProps | null | undefined;
     emptyText?: string;
@@ -1552,6 +1692,12 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     summaryRowHeight?: number;
     overscanRowCount?: number;
     query?: ListTableQueryOptions<RecordType>;
+    /**
+     * 是否展示最左侧的空白行选择器列。
+     * 传入对象时可配置列宽，默认宽度为 `12px`。
+     * @default false
+     */
+    rowSelector?: boolean | ListTableRowSelectorOptions;
     rowSelection?: ListTableRowSelectionOptions<RecordType>;
     expandable?: ListTableExpandableOptions<RecordType>;
     pagination?: false | ListTablePaginationOptions;
@@ -1696,4 +1842,4 @@ interface ListTableValidationTarget {
     columnKey: string;
 }
 
-export { type CreateCellEditorSessionParams, type DebugHitTestResult, type FilterPanelConfig, type FilterPanelOptionItem, type FilterPanelTexts, type FixedPopupConfig, type HeaderContextMenuColumnItem, type HeaderContextMenuConfig, type HeaderContextMenuDensity, ListTable, type ListTableAutoMergeRule, type ListTableBarcodeCellContent, type ListTableBarcodeFormat, type ListTableButtonCellContent, type ListTableButtonPopconfirmOptions, type ListTableButtonSize, type ListTableButtonType, type ListTableCarouselScrollOptions, type ListTableCellContent, type ListTableCellContentClickContext, type ListTableCellEditorSession, type ListTableCellSpan, type ListTableCellStyle, type ListTableChartCellContent, type ListTableChartSize, type ListTableChartType, type ListTableColorCellContent, type ListTableColumn, type ListTableContextMenuFeature, type ListTableContextMenuOptions, type ListTableCustomChartCellContent, type ListTableDangerConfirmRequest, type ListTableDataFormatType, type ListTableDebugOptions, type ListTableDebugSnapshot, type ListTableEditAutoCompleteEnter, type ListTableEditFilterOption, type ListTableEditOption, type ListTableEditValueType, type ListTableEditable, type ListTableEditorAutoCompleteEnter, type ListTableEditorConfig, type ListTableEditorFactory, type ListTableEditorFilterOption, type ListTableEditorNavigateDirection, type ListTableEditorOption, type ListTableEditorRect, type ListTableEditorRequest, type ListTableEditorTheme, type ListTableEditorValueType, type ListTableExportXlsxOptions, type ListTableFilterConditionOperator, type ListTableFilterConditionRelation, type ListTableFilterMatchMode, type ListTableFilterOption, type ListTableFilterOptionValue, type ListTableFilterPanelAdapter, type ListTableFilterState, type ListTableFilterType, type ListTableFilterValue$1 as ListTableFilterValue, type ListTableFixedPopupAdapter, type ListTableFormItemProps, type ListTableFormItemPropsConfig, type ListTableFormRule, type ListTableFormRules, type ListTableHeaderContextMenuAdapter, type ListTableHighlightMode, type ListTableHorizontalAlign, type ListTableIconCellContent, type ListTableImageCellContent, type ListTableImageObjectFit, type ListTableImagePreviewRequest, type ListTableLoadingAdapter, type ListTableLoadingRequest, type ListTableMergeCellOptions, type ListTableNestedTableCellContent, type ListTableNestedTableColumn, type ListTableOptions, type ListTablePaginationAdapter, type ListTablePaginationOptions, type ListTableProgressCellContent, type ListTableProgressShape, type ListTableProgressSize, type ListTableQrCodeCellContent, type ListTableQrCodeLevel, type ListTableQueryChange, type ListTableQueryChangeExtra, type ListTableQueryFilters, type ListTableQueryOptions, type ListTableQueryPagination, type ListTableQuerySorter, type ListTableRateCellContent, type ListTableRateSize, type ListTableRowDragMode, type ListTableRowDragOptions, type ListTableRowDragPayload, type ListTableRowDragSourceInfo, type ListTableRowDragZone, type ListTableRowEventProps, type ListTableRowSelectionChangeInfo, type ListTableRowSelectionOptions, type ListTableScrollToOptions, type ListTableScrollbarOptions, type ListTableSelectionState, type ListTableSortItem, type ListTableSortState, type ListTableSparklineChartCellContent, type ListTableSparklineSize, type ListTableSymbolType, type ListTableTagCellContent, type ListTableTheme, type ListTableTooltipAdapter, type ListTableTooltipRequest, type ListTableUiOptions, type ListTableValidationError, type ListTableValidationErrorField, type ListTableValidationFailure, type ListTableValidationTarget, type PaginationConfig, type RenderCellDescriptor };
+export { type CreateCellEditorSessionParams, type DebugHitTestResult, type FilterPanelConfig, type FilterPanelOptionItem, type FilterPanelTexts, type FixedPopupConfig, type HeaderContextMenuColumnItem, type HeaderContextMenuConfig, type HeaderContextMenuDensity, ListTable, type ListTableAutoMergeRule, type ListTableBarcodeCellContent, type ListTableBarcodeFormat, type ListTableButtonCellContent, type ListTableButtonPopconfirmOptions, type ListTableButtonSize, type ListTableButtonType, type ListTableCarouselScrollOptions, type ListTableCellContent, type ListTableCellContentClickContext, type ListTableCellEditorSession, type ListTableCellSpan, type ListTableCellStyle, type ListTableChartCellContent, type ListTableChartSize, type ListTableChartType, type ListTableColorCellContent, type ListTableColumn, type ListTableContextMenuFeature, type ListTableContextMenuOptions, type ListTableCustomChartCellContent, type ListTableDangerConfirmRequest, type ListTableDataFormat, type ListTableDataFormatOptions, type ListTableDataFormatType, type ListTableDebugOptions, type ListTableDebugSnapshot, type ListTableEditAutoCompleteEnter, type ListTableEditFilterOption, type ListTableEditOption, type ListTableEditValueType, type ListTableEditable, type ListTableEditorAutoCompleteEnter, type ListTableEditorConfig, type ListTableEditorFactory, type ListTableEditorFilterOption, type ListTableEditorNavigateDirection, type ListTableEditorOption, type ListTableEditorRect, type ListTableEditorRequest, type ListTableEditorTheme, type ListTableEditorValueType, type ListTableExportXlsxOptions, type ListTableFilterConditionOperator, type ListTableFilterConditionRelation, type ListTableFilterMatchMode, type ListTableFilterOption, type ListTableFilterOptionValue, type ListTableFilterPanelAdapter, type ListTableFilterState, type ListTableFilterType, type ListTableFilterValue$1 as ListTableFilterValue, type ListTableFixedPopupAdapter, type ListTableFormItemProps, type ListTableFormItemPropsConfig, type ListTableFormRule, type ListTableFormRules, type ListTableGroupingOptions, type ListTableHeaderContextMenuAdapter, type ListTableHighlightMode, type ListTableHorizontalAlign, type ListTableIconCellContent, type ListTableImageCellContent, type ListTableImageObjectFit, type ListTableImagePreviewRequest, type ListTableLoadingAdapter, type ListTableLoadingRequest, type ListTableMergeCellOptions, type ListTableNestedTableCellContent, type ListTableNestedTableColumn, type ListTableOptions, type ListTablePaginationAdapter, type ListTablePaginationOptions, type ListTablePerformanceMetric, type ListTableProgressCellContent, type ListTableProgressShape, type ListTableProgressSize, type ListTableQrCodeCellContent, type ListTableQrCodeLevel, type ListTableQueryChange, type ListTableQueryChangeExtra, type ListTableQueryFilters, type ListTableQueryOptions, type ListTableQueryPagination, type ListTableQuerySorter, type ListTableRateCellContent, type ListTableRateSize, type ListTableRowDragMode, type ListTableRowDragOptions, type ListTableRowDragPayload, type ListTableRowDragSourceInfo, type ListTableRowDragZone, type ListTableRowEventProps, type ListTableRowSelectionChangeInfo, type ListTableRowSelectionOptions, type ListTableRowSelectorOptions, type ListTableScrollToOptions, type ListTableScrollbarOptions, type ListTableSearchRequest, type ListTableSelectionState, type ListTableSortItem, type ListTableSortState, type ListTableSparklineChartCellContent, type ListTableSparklineSize, type ListTableSummaryConfig, type ListTableSummaryRoundingMode, type ListTableSummaryType, type ListTableSymbolType, type ListTableTagCellContent, type ListTableTheme, type ListTableTooltipAdapter, type ListTableTooltipRequest, type ListTableUiOptions, type ListTableValidationError, type ListTableValidationErrorField, type ListTableValidationFailure, type ListTableValidationTarget, type PaginationConfig, type RenderCellDescriptor };

package/dist/index.d.ts

@@ -58,6 +58,28 @@ type ListTableFilterState = Record<string, ListTableFilterValue$1>;
 interface ListTableSelectionState {
     rowIndex: number | null;
     columnKey: string | null;
+    /** 当前活动单元格内模拟的文本选区。 */
+    textSelection?: ListTableTextSelectionState | null;
+}
+/**
+ * Canvas 文本选区状态。
+ */
+interface ListTableTextSelectionState {
+    fragments: ListTableTextSelectionFragment[];
+    anchorFragmentIndex: number;
+    focusFragmentIndex: number;
+    anchorOffset: number;
+    focusOffset: number;
+}
+/**
+ * 单元格内一个可选择的可视文本片段。
+ */
+interface ListTableTextSelectionFragment {
+    rowIndex?: number;
+    columnKey?: string;
+    contentIndex: number;
+    fragmentKey: string;
+    text: string;
 }
 /**
  * 表头 action 显隐状态。
@@ -82,6 +104,26 @@ interface ListTableDebugOptions {
     showHeaderActionOverlay?: boolean;
     logDrawCalls?: boolean;
     logStateChanges?: boolean;
+    /**
+     * 性能阶段埋点回调。仅在配置后执行，不影响默认渲染路径。
+     */
+    onPerformance?: (metric: ListTablePerformanceMetric) => void;
+}
+/**
+ * 列表表格性能阶段指标。
+ */
+interface ListTablePerformanceMetric {
+    phase: "grouping" | "snapshot" | "render";
+    durationMs: number;
+    inputRowCount: number;
+    outputRowCount: number;
+    cacheHit?: boolean;
+    groupedRowCount?: number;
+    scrollOnly?: boolean;
+    batchCount?: number;
+    indexNodeCount?: number;
+    cancelledCount?: number;
+    status?: "ready" | "cancelled" | "error";
 }
 /**
  * 查询回调扩展参数。
@@ -110,7 +152,7 @@ interface Rect {
  * 命中结果。
  */
 interface DebugHitTestResult {
-    area: "header" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "sort-trigger" | "filter-trigger" | "fixed-trigger" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary" | "summary" | "empty";
+    area: "header" | "grouping-bar" | "grouping-tag" | "grouping-remove" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "sort-trigger" | "filter-trigger" | "fixed-trigger" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary" | "summary" | "empty";
     scrollbarRole?: "thumb" | "track" | "decrease-button" | "increase-button";
     columnKey?: string;
     rowIndex?: number;
@@ -128,6 +170,13 @@ interface DebugHitTestResult {
     rect?: Rect;
     tooltipText?: string;
     tooltipVariant?: "default" | "error";
+    textSelectionText?: string;
+    textSelectionFont?: string;
+    textSelectionFragmentKey?: string;
+    textSelectionOriginX?: number;
+    /** 表头文本所属层级，用于跨层拖选时区分行。 */
+    textSelectionRowIndex?: number;
+    textSelectionRect?: Rect;
 }
 /**
  * action 类型。
@@ -137,7 +186,7 @@ type HeaderActionType = "sort" | "filter" | "fixed";
  * 渲染矩形描述。
  */
 interface RenderCellDescriptor {
-    kind: "header" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "header-action" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary";
+    kind: "header" | "grouping-bar" | "grouping-tag" | "grouping-remove" | "body" | "body-content" | "body-control" | "expand-trigger" | "collapse-trigger" | "column-collapse-trigger" | "expanded-row" | "header-selection" | "header-action" | "resize-handle" | "horizontal-scrollbar" | "vertical-scrollbar" | "summary";
     rect: Rect;
     columnKey?: string;
     rowIndex?: number;
@@ -153,6 +202,17 @@ interface RenderCellDescriptor {
     cursor?: string;
     tooltipText?: string;
     tooltipVariant?: "default" | "error";
+    /** 可参与 Canvas 文本选择的实际绘制文本。 */
+    textSelectionText?: string;
+    /** 文本命中时使用的 Canvas 字体。 */
+    textSelectionFont?: string;
+    /** 同一单元格内文本布局片段的稳定标识。 */
+    textSelectionFragmentKey?: string;
+    /** 文本未裁剪前的绘制起点。 */
+    textSelectionOriginX?: number;
+    /** 表头文本所属层级，用于跨层拖选时区分行。 */
+    textSelectionRowIndex?: number;
+    textSelectionRect?: Rect;
     actionType?: HeaderActionType;
     scrollbarRole?: "thumb" | "track" | "decrease-button" | "increase-button";
     visibilityState?: HeaderActionVisibilityState;
@@ -213,6 +273,7 @@ interface ListTableTheme {
     frozenRowBackgroundColor: string;
     hoverBackgroundColor: string;
     selectionBackgroundColor: string;
+    textSelectionBackgroundColor?: string;
     emptyBackgroundColor: string;
     emptyTextColor: string;
     debugStrokeColor: string;
@@ -234,8 +295,25 @@ interface ListTableTheme {
  * - `max`：取当前列最大值
  */
 type ListTableSummaryType = "sum" | "avg" | "count" | "unionCount" | "rowCount" | "mergedRowCount" | "min" | "max";
+/** 汇总结果的小数取整方式。 */
+type ListTableSummaryRoundingMode = "round" | "floor" | "ceil" | "truncate";
 type ListTableHorizontalAlign = "left" | "center" | "right";
-type ListTableDataFormatType = "default" | "number" | "thousands" | "money";
+type ListTableDataFormatType = "default" | "text" | "number" | "thousands" | "decimal" | "percent" | "percentDecimal" | "scientific" | "numberToChineseUpper" | "chineseUpperToNumber" | "cny" | "cnyDecimal" | "usd" | "usdDecimal" | "dateSlash" | "dateDash" | "dateFullCN" | "dateYearMonthCN" | "dateMonthDayCN" | "dateSlashWeek" | "dateDashWeek" | "dateWeekdayCNFull" | "dateWeekdayCNShort" | "time" | "timeShort" | "time12" | "time12Seconds" | "timeMillisecond" | "time12Millisecond" | "timeChineseHour" | "timeChineseSecond" | "time12ChineseHour" | "time12ChineseSecond" | "datetime" | "datetime12" | "datetime12Seconds" | "custom" | "money";
+/** 可持久化的数据显示格式配置。 */
+interface ListTableDataFormatOptions {
+    /** 基础格式类型。 */
+    type: ListTableDataFormatType;
+    /** 小数位数，支持 0 到 20。 */
+    decimalPlaces?: number;
+    /** 是否显示千分位分隔符。 */
+    useGrouping?: boolean;
+    /** 货币符号。 */
+    symbol?: string;
+    /** 日期、时间或自定义格式模式。 */
+    pattern?: string;
+}
+/** 数据显示格式，字符串用于快捷格式，对象用于精确格式配置。 */
+type ListTableDataFormat = ListTableDataFormatType | ListTableDataFormatOptions;
 type ListTableFilterOptionValue = string | number | null;
 interface ListTableFilterOption {
     label: string;
@@ -251,8 +329,12 @@ interface ListTableSummaryConfig<RecordType = Record<string, unknown>> {
     valueGetter?: (record: RecordType) => string | number | null | undefined;
     /** 值格式化函数。 */
     formatter?: (value: string | number, records: RecordType[], column: ListTableColumn<RecordType>) => string;
-    /** 小数精度（四舍五入），不传则整数不保留小数、非整数保留两位。 */
+    /** 小数精度，不传则整数不保留小数、非整数保留两位。 */
     precision?: number;
+    /** 小数取整方式，默认四舍五入。 */
+    roundingMode?: ListTableSummaryRoundingMode;
+    /** 是否保留精度补齐产生的无效零，默认不保留。 */
+    preserveTrailingZeros?: boolean;
 }
 /**
  * 路径索引定义。
@@ -329,7 +411,7 @@ type ListTableFormRules<RecordType = Record<string, unknown>> = ListTableFormRul
  * 单元格内容片段样式。
  */
 interface ListTableContentStyle {
-    display?: "block" | "inline-block";
+    display?: "none" | "block" | "inline-block";
     textAlign?: CanvasTextAlign;
     fontSize?: number;
     fontWeight?: string;
@@ -348,6 +430,8 @@ interface ListTableContentStyle {
  */
 interface ListTableBaseCellContent<RecordType = any> {
     key?: string;
+    /** 是否展示内容，默认展示。 */
+    visible?: boolean;
     style?: ListTableContentStyle;
     cursor?: string;
     onClick?: (context: ListTableCellContentClickContext<RecordType>) => void;
@@ -777,7 +861,7 @@ interface ListTableColumn<RecordType = Record<string, unknown>> {
     /** 金额单元格格式配置，仅在 `cellType: "money"` 时生效。 */
     moneyFormat?: ListTableMoneyFormatOptions;
     /** 通过列设置覆盖的数据显示格式。 */
-    dataFormat?: ListTableDataFormatType;
+    dataFormat?: ListTableDataFormat;
     headerStyle?: ListTableCellStyle;
     /** 汇总行配置。设为 `true` 等效于 `{ type: "sum" }`。 */
     summary?: boolean | ListTableSummaryConfig<RecordType>;
@@ -917,6 +1001,7 @@ interface HeaderContextMenuConfig {
     onCopyRowText?: () => void;
     onCopyRowJson?: () => void;
     onCopySelection?: () => void;
+    onOpenSearch?: () => void;
     customSelection?: {
         startRow: number;
         startColumn: number;
@@ -948,7 +1033,21 @@ interface HeaderContextMenuConfig {
     onUnfreezeRow?: () => void;
     onResetFilter?: () => void;
     onResetSort?: () => void;
+    onSortAscend?: () => void;
+    onSortDescend?: () => void;
+    onClearSort?: () => void;
+    onFixLeft?: () => void;
+    onFixRight?: () => void;
+    onUnfix?: () => void;
     onResetHeader?: () => void;
+    onResetGrouping?: () => void;
+    onResetSummary?: () => void;
+    onResetAlignment?: () => void;
+    onResetDataFormat?: () => void;
+    onAutoFitCurrentColumn?: () => void;
+    onAutoFitAllColumns?: () => void;
+    groupingBarVisible?: boolean;
+    onToggleGroupingBar?: () => void;
     onChangeDensity?: (density: HeaderContextMenuDensity) => void;
     /**
      * 调整表格缩放。
@@ -962,15 +1061,28 @@ interface HeaderContextMenuConfig {
         bodyVertical: "top" | "middle" | "bottom";
     };
     onChangeAlignment?: (area: "header" | "body", axis: "horizontal" | "vertical", value: ListTableHorizontalAlign | "top" | "middle" | "bottom") => void;
-    dataFormat?: ListTableDataFormatType;
-    onChangeDataFormat?: (dataFormat: ListTableDataFormatType) => void;
+    dataFormat?: ListTableDataFormat;
+    onChangeDataFormat?: (dataFormat: ListTableDataFormat) => void;
     summaryVisible?: boolean;
     summaryColumnKey?: string;
     summaryType?: ListTableSummaryType;
     summaryPrecision?: number;
+    summaryRoundingMode?: ListTableSummaryRoundingMode;
+    summaryPreserveTrailingZeros?: boolean;
     onToggleSummary?: () => void;
     onChangeSummaryType?: (type: ListTableSummaryType) => void;
     onChangeSummaryPrecision?: (precision: number | undefined) => void;
+    onChangeSummaryRoundingMode?: (mode: ListTableSummaryRoundingMode) => void;
+    onChangeSummaryPreserveTrailingZeros?: (value: boolean) => void;
+    onClose: () => void;
+}
+interface ListTableSearchRequest {
+    keyword: string;
+    matchCount: number;
+    currentIndex: number;
+    /** 提交关键词并重新计算匹配项。 */
+    onSubmit: (keyword: string) => void;
+    onNavigate: (direction: "previous" | "next") => void;
     onClose: () => void;
 }
 interface PaginationConfig {
@@ -1259,7 +1371,18 @@ type ListTableHighlightMode = "cell" | "row" | "column" | "cross";
 /**
  * 右键菜单功能项。
  */
-type ListTableContextMenuFeature = "copy" | "export" | "downloadContent" | "rowCollapse" | "columnCollapse" | "freeze" | "reset" | "density" | "zoom" | "alignment" | "dataFormat" | "columnVisibility";
+type ListTableContextMenuFeature = "copy" | "search" | "export" | "downloadContent" | "rowCollapse" | "columnCollapse" | "freeze" | "reset" | "sort" | "density" | "zoom" | "columnWidth" | "alignment" | "dataFormat" | "grouping" | "columnVisibility";
+/**
+ * 数据分组配置。
+ */
+interface ListTableGroupingOptions {
+    /** 是否初始显示顶部的分组栏，默认 false。 */
+    visible?: boolean;
+    /** 初始分组列 key，顺序表示分组层级。 */
+    columnKeys?: string[];
+    /** 分组列变化回调。 */
+    onChange?: (columnKeys: string[]) => void;
+}
 /**
  * 右键菜单配置。
  */
@@ -1432,7 +1555,7 @@ interface ListTableRowSelectionOptions<RecordType> {
     /**
      * 点击普通表体区域时是否切换当前行选择状态。
      *
-     * @default false
+     * @default true
      */
     selectRowByClick?: boolean;
     selectedRowKeys?: Array<string | number>;
@@ -1494,9 +1617,23 @@ interface ListTableUiOptions {
     onFilterPanelRequest?: (request: FilterPanelConfig | null) => void;
     onFixedPopupRequest?: (request: FixedPopupConfig | null) => void;
     onHeaderContextMenuRequest?: (request: HeaderContextMenuConfig | null) => void;
+    onSearchRequest?: (request: ListTableSearchRequest | null) => void;
     onImagePreviewRequest?: (request: ListTableImagePreviewRequest | null) => void;
     onDangerConfirmRequest?: (request: ListTableDangerConfirmRequest | null) => void;
 }
+/**
+ * 行选择器配置。
+ *
+ * 行选择器是位于表格最左侧的空白系统列，仅用于快速选中整行，
+ * 不参与 checkbox/radio 行数据选择。
+ */
+interface ListTableRowSelectorOptions {
+    /**
+     * 选择器列宽度。
+     * @default 12
+     */
+    width?: number;
+}
 interface ListTableImagePreviewRequest {
     src: string;
     alt?: string;
@@ -1519,6 +1656,9 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     height?: number | string;
     columns: ListTableColumn<RecordType>[];
     dataSource: RecordType[];
+    /** 顶部分组栏与数据分组配置。 */
+    /** 数据分组配置；不传时不启用分组功能。 */
+    grouping?: ListTableGroupingOptions;
     /** AntD Table 风格的行事件配置。 */
     onRow?: (record: RecordType, rowIndex: number) => ListTableRowEventProps | null | undefined;
     emptyText?: string;
@@ -1552,6 +1692,12 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     summaryRowHeight?: number;
     overscanRowCount?: number;
     query?: ListTableQueryOptions<RecordType>;
+    /**
+     * 是否展示最左侧的空白行选择器列。
+     * 传入对象时可配置列宽，默认宽度为 `12px`。
+     * @default false
+     */
+    rowSelector?: boolean | ListTableRowSelectorOptions;
     rowSelection?: ListTableRowSelectionOptions<RecordType>;
     expandable?: ListTableExpandableOptions<RecordType>;
     pagination?: false | ListTablePaginationOptions;
@@ -1696,4 +1842,4 @@ interface ListTableValidationTarget {
     columnKey: string;
 }
 
-export { type CreateCellEditorSessionParams, type DebugHitTestResult, type FilterPanelConfig, type FilterPanelOptionItem, type FilterPanelTexts, type FixedPopupConfig, type HeaderContextMenuColumnItem, type HeaderContextMenuConfig, type HeaderContextMenuDensity, ListTable, type ListTableAutoMergeRule, type ListTableBarcodeCellContent, type ListTableBarcodeFormat, type ListTableButtonCellContent, type ListTableButtonPopconfirmOptions, type ListTableButtonSize, type ListTableButtonType, type ListTableCarouselScrollOptions, type ListTableCellContent, type ListTableCellContentClickContext, type ListTableCellEditorSession, type ListTableCellSpan, type ListTableCellStyle, type ListTableChartCellContent, type ListTableChartSize, type ListTableChartType, type ListTableColorCellContent, type ListTableColumn, type ListTableContextMenuFeature, type ListTableContextMenuOptions, type ListTableCustomChartCellContent, type ListTableDangerConfirmRequest, type ListTableDataFormatType, type ListTableDebugOptions, type ListTableDebugSnapshot, type ListTableEditAutoCompleteEnter, type ListTableEditFilterOption, type ListTableEditOption, type ListTableEditValueType, type ListTableEditable, type ListTableEditorAutoCompleteEnter, type ListTableEditorConfig, type ListTableEditorFactory, type ListTableEditorFilterOption, type ListTableEditorNavigateDirection, type ListTableEditorOption, type ListTableEditorRect, type ListTableEditorRequest, type ListTableEditorTheme, type ListTableEditorValueType, type ListTableExportXlsxOptions, type ListTableFilterConditionOperator, type ListTableFilterConditionRelation, type ListTableFilterMatchMode, type ListTableFilterOption, type ListTableFilterOptionValue, type ListTableFilterPanelAdapter, type ListTableFilterState, type ListTableFilterType, type ListTableFilterValue$1 as ListTableFilterValue, type ListTableFixedPopupAdapter, type ListTableFormItemProps, type ListTableFormItemPropsConfig, type ListTableFormRule, type ListTableFormRules, type ListTableHeaderContextMenuAdapter, type ListTableHighlightMode, type ListTableHorizontalAlign, type ListTableIconCellContent, type ListTableImageCellContent, type ListTableImageObjectFit, type ListTableImagePreviewRequest, type ListTableLoadingAdapter, type ListTableLoadingRequest, type ListTableMergeCellOptions, type ListTableNestedTableCellContent, type ListTableNestedTableColumn, type ListTableOptions, type ListTablePaginationAdapter, type ListTablePaginationOptions, type ListTableProgressCellContent, type ListTableProgressShape, type ListTableProgressSize, type ListTableQrCodeCellContent, type ListTableQrCodeLevel, type ListTableQueryChange, type ListTableQueryChangeExtra, type ListTableQueryFilters, type ListTableQueryOptions, type ListTableQueryPagination, type ListTableQuerySorter, type ListTableRateCellContent, type ListTableRateSize, type ListTableRowDragMode, type ListTableRowDragOptions, type ListTableRowDragPayload, type ListTableRowDragSourceInfo, type ListTableRowDragZone, type ListTableRowEventProps, type ListTableRowSelectionChangeInfo, type ListTableRowSelectionOptions, type ListTableScrollToOptions, type ListTableScrollbarOptions, type ListTableSelectionState, type ListTableSortItem, type ListTableSortState, type ListTableSparklineChartCellContent, type ListTableSparklineSize, type ListTableSymbolType, type ListTableTagCellContent, type ListTableTheme, type ListTableTooltipAdapter, type ListTableTooltipRequest, type ListTableUiOptions, type ListTableValidationError, type ListTableValidationErrorField, type ListTableValidationFailure, type ListTableValidationTarget, type PaginationConfig, type RenderCellDescriptor };
+export { type CreateCellEditorSessionParams, type DebugHitTestResult, type FilterPanelConfig, type FilterPanelOptionItem, type FilterPanelTexts, type FixedPopupConfig, type HeaderContextMenuColumnItem, type HeaderContextMenuConfig, type HeaderContextMenuDensity, ListTable, type ListTableAutoMergeRule, type ListTableBarcodeCellContent, type ListTableBarcodeFormat, type ListTableButtonCellContent, type ListTableButtonPopconfirmOptions, type ListTableButtonSize, type ListTableButtonType, type ListTableCarouselScrollOptions, type ListTableCellContent, type ListTableCellContentClickContext, type ListTableCellEditorSession, type ListTableCellSpan, type ListTableCellStyle, type ListTableChartCellContent, type ListTableChartSize, type ListTableChartType, type ListTableColorCellContent, type ListTableColumn, type ListTableContextMenuFeature, type ListTableContextMenuOptions, type ListTableCustomChartCellContent, type ListTableDangerConfirmRequest, type ListTableDataFormat, type ListTableDataFormatOptions, type ListTableDataFormatType, type ListTableDebugOptions, type ListTableDebugSnapshot, type ListTableEditAutoCompleteEnter, type ListTableEditFilterOption, type ListTableEditOption, type ListTableEditValueType, type ListTableEditable, type ListTableEditorAutoCompleteEnter, type ListTableEditorConfig, type ListTableEditorFactory, type ListTableEditorFilterOption, type ListTableEditorNavigateDirection, type ListTableEditorOption, type ListTableEditorRect, type ListTableEditorRequest, type ListTableEditorTheme, type ListTableEditorValueType, type ListTableExportXlsxOptions, type ListTableFilterConditionOperator, type ListTableFilterConditionRelation, type ListTableFilterMatchMode, type ListTableFilterOption, type ListTableFilterOptionValue, type ListTableFilterPanelAdapter, type ListTableFilterState, type ListTableFilterType, type ListTableFilterValue$1 as ListTableFilterValue, type ListTableFixedPopupAdapter, type ListTableFormItemProps, type ListTableFormItemPropsConfig, type ListTableFormRule, type ListTableFormRules, type ListTableGroupingOptions, type ListTableHeaderContextMenuAdapter, type ListTableHighlightMode, type ListTableHorizontalAlign, type ListTableIconCellContent, type ListTableImageCellContent, type ListTableImageObjectFit, type ListTableImagePreviewRequest, type ListTableLoadingAdapter, type ListTableLoadingRequest, type ListTableMergeCellOptions, type ListTableNestedTableCellContent, type ListTableNestedTableColumn, type ListTableOptions, type ListTablePaginationAdapter, type ListTablePaginationOptions, type ListTablePerformanceMetric, type ListTableProgressCellContent, type ListTableProgressShape, type ListTableProgressSize, type ListTableQrCodeCellContent, type ListTableQrCodeLevel, type ListTableQueryChange, type ListTableQueryChangeExtra, type ListTableQueryFilters, type ListTableQueryOptions, type ListTableQueryPagination, type ListTableQuerySorter, type ListTableRateCellContent, type ListTableRateSize, type ListTableRowDragMode, type ListTableRowDragOptions, type ListTableRowDragPayload, type ListTableRowDragSourceInfo, type ListTableRowDragZone, type ListTableRowEventProps, type ListTableRowSelectionChangeInfo, type ListTableRowSelectionOptions, type ListTableRowSelectorOptions, type ListTableScrollToOptions, type ListTableScrollbarOptions, type ListTableSearchRequest, type ListTableSelectionState, type ListTableSortItem, type ListTableSortState, type ListTableSparklineChartCellContent, type ListTableSparklineSize, type ListTableSummaryConfig, type ListTableSummaryRoundingMode, type ListTableSummaryType, type ListTableSymbolType, type ListTableTagCellContent, type ListTableTheme, type ListTableTooltipAdapter, type ListTableTooltipRequest, type ListTableUiOptions, type ListTableValidationError, type ListTableValidationErrorField, type ListTableValidationFailure, type ListTableValidationTarget, type PaginationConfig, type RenderCellDescriptor };