@canvas-components/list-table 0.3.12 → 0.3.13

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { CanvasChartSparklineOption } from '@canvas-components/chart';
+import { XlsxExportOptions } from '@canvas-components/utils';
 
 /**
  * 排序状态。
@@ -125,17 +126,41 @@ interface ListTableDebugOptions {
  * 列表表格性能阶段指标。
  */
 interface ListTablePerformanceMetric {
-    phase: "grouping" | "snapshot" | "render";
+    phase: "query" | "grouping" | "snapshot" | "render" | "publish" | "offscreen";
     durationMs: number;
     inputRowCount: number;
     outputRowCount: number;
     cacheHit?: boolean;
+    /** 快照缓存未命中的首个输入原因。 */
+    cacheMissReason?: string;
     groupedRowCount?: number;
     scrollOnly?: boolean;
+    /** 本帧由动画扫描与绘制共享的单元格内容缓存命中数。 */
+    cellContentCacheHits?: number;
+    /** 本帧实际执行单元格内容解析的次数。 */
+    cellContentCacheMisses?: number;
+    /** 本帧结束时保留的单元格内容缓存项数。 */
+    cellContentCacheEntries?: number;
     batchCount?: number;
     indexNodeCount?: number;
     cancelledCount?: number;
     status?: "ready" | "cancelled" | "error";
+    /** 查询实际使用的执行器。 */
+    executor?: "none" | "worker" | "main" | "mixed";
+    /** Worker 回退主线程的原因；多阶段回退时使用逗号分隔。 */
+    fallbackReason?: string;
+    /** 单次查询发生的执行器回退次数。 */
+    fallbackCount?: number;
+    /** 主线程协作式计算主动让步次数。 */
+    sliceCount?: number;
+    /** 字段缓存命中次数。 */
+    fieldCacheHitCount?: number;
+    /** 字段缓存未命中次数。 */
+    fieldCacheMissCount?: number;
+    /** 最近一次字段缓存未命中原因。 */
+    fieldCacheMissReason?: string;
+    /** 查询各阶段耗时，单位毫秒。 */
+    stageDurationsMs?: Partial<Record<"filter" | "sort" | "fieldExtraction" | "workerTransfer" | "workerCompute" | "indexMapping" | "materialization" | "resultApply", number>>;
 }
 /**
  * 查询回调扩展参数。
@@ -748,6 +773,10 @@ interface ListTableNestedTableColumn {
     filterValueGetter?: (record: Record<string, unknown>) => unknown;
     filterOptionValueGetter?: (record: Record<string, unknown>) => unknown;
     filterOptions?: Array<string | ListTableFilterOption>;
+    /** 子表格汇总行配置。设为 `true` 等效于 `{ type: "sum" }`。 */
+    summary?: boolean | ListTableSummaryConfig<Record<string, unknown>>;
+    /** 子表格汇总行标题。 */
+    summaryTitle?: string;
 }
 /**
  * 单元格内嵌表格片段。
@@ -862,6 +891,13 @@ interface ListTableColumn<RecordType = Record<string, unknown>> {
     headerAlign?: ListTableHorizontalAlign;
     fixed?: "left" | "right";
     hidden?: boolean;
+    /**
+     * 是否将行展开按钮绘制在当前业务列中。
+     *
+     * 多列设为 `true` 时使用可见顺序中的第一列；设为 `false` 时，
+     * 当前列不会成为未指定目标时的默认内嵌列。
+     */
+    showExpandIcon?: boolean;
     /** 列设置中使用的标题，未传时使用 `title`。 */
     settingTitle?: string;
     /** 首次创建表格时是否默认隐藏。显式传入 `hidden` 时以 `hidden` 为准。 */
@@ -1114,11 +1150,14 @@ interface HeaderContextMenuConfig {
     onChangeDataFormat?: (dataFormat: ListTableDataFormat) => void;
     summaryVisible?: boolean;
     summaryColumnKey?: string;
+    summaryTitle?: string;
     summaryType?: ListTableSummaryType;
     summaryPrecision?: number;
     summaryRoundingMode?: ListTableSummaryRoundingMode;
     summaryPreserveTrailingZeros?: boolean;
     onToggleSummary?: () => void;
+    onChangeSummaryTitle?: (title: string) => void;
+    onClearSummary?: () => void;
     onChangeSummaryType?: (type: ListTableSummaryType) => void;
     onChangeSummaryPrecision?: (precision: number | undefined) => void;
     onChangeSummaryRoundingMode?: (mode: ListTableSummaryRoundingMode) => void;
@@ -1548,6 +1587,8 @@ type ListTableQueryPagination = false | {
  * AntD 风格的过滤结果。
  */
 type ListTableQueryFilters = Record<string, string[] | null>;
+/** 服务端返回的汇总结果，键使用列 key，值为最终展示内容。 */
+type ListTableServerSummaryValues = ReadonlyMap<string, string | number | bigint | null | undefined> | Readonly<Record<string, string | number | bigint | null | undefined>>;
 /**
  * AntD 风格的排序结果。
  */
@@ -1619,11 +1660,43 @@ interface ListTableRowSelectionOptions<RecordType> {
  * AntD 风格的四参数查询回调。
  */
 type ListTableQueryChange<RecordType> = (pagination: ListTableQueryPagination, filters: ListTableQueryFilters, sorter: ListTableQuerySorter, extra: ListTableQueryChangeExtra<RecordType>) => void;
+/** 本地查询失败通知。 */
+interface ListTableQueryErrorInfo {
+    /** 失败的查询动作。 */
+    action: "sort" | "filter";
+    /** 查询链抛出的原始错误。 */
+    error: unknown;
+    /**
+     * 人工重试本次查询。仅当失败任务仍是最新任务时返回 true 并启动重试；
+     * 查询状态已变化、实例已重置或销毁时返回 false。
+     */
+    retry: () => boolean;
+}
 interface ListTableQueryOptions<RecordType> {
     enabled?: boolean;
     mode?: "local" | "remote";
     dataSource?: RecordType[];
     optionThreshold?: number;
+    /**
+     * 是否允许本地大数据查询使用 Worker。
+     *
+     * - `"auto"` / `undefined`：达到内部阈值时自动启用。
+     * - `true`：不受行数阈值限制，优先尝试 Worker。
+     * - `false`：始终使用可取消的主线程分片路径。
+     */
+    worker?: boolean | "auto";
+    /** 自动模式下启用 Worker 的最小数据行数，默认 50000。 */
+    workerThreshold?: number;
+    /**
+     * 是否缓存本地查询提取出的字段快照。启用时应同时维护 `dataVersion`，
+     * 原地编辑数据后递增版本以避免复用旧值。
+     * @default false
+     */
+    fieldCache?: boolean;
+    /** 本地数据内容修订号，用于主动失效字段缓存。 */
+    dataVersion?: string | number;
+    /** 字段缓存容量上限（估算字节数），默认 32 MiB。 */
+    fieldCacheMaxBytes?: number;
     /**
      * 点击过滤候选项后是否立即应用过滤，并保持过滤面板打开。
      *
@@ -1631,7 +1704,32 @@ interface ListTableQueryOptions<RecordType> {
      */
     filterOptionImmediateApply?: boolean;
     mergeCell?: ListTableMergeCellOptions;
+    /**
+     * 服务端汇总结果。传入后直接用于汇总行，不再对当前 dataSource 本地计算。
+     *
+     * 键应使用列 key；未配置显式 key 时通常与 dataIndex 相同。
+     */
+    summaryValues?: ListTableServerSummaryValues;
     onChange?: ListTableQueryChange<RecordType>;
+    /** 本地排序或过滤最终失败后的统一通知；不会因 Worker 回退自动触发。 */
+    onError?: (info: ListTableQueryErrorInfo) => void;
+}
+/** OffscreenCanvas 实验状态。 */
+interface ListTableOffscreenCanvasStatusInfo {
+    status: "active" | "unsupported" | "fallback" | "destroyed";
+    reason?: string;
+}
+/** 尚未默认启用的渲染实验。 */
+interface ListTableExperimentalOptions {
+    /**
+     * 把最终可视帧交给 OffscreenCanvas Worker 呈现。
+     *
+     * 该开关仅在实例挂载前读取；能力不足或运行失败时自动恢复主线程画布。
+     * @default false
+     */
+    offscreenCanvas?: boolean;
+    /** OffscreenCanvas 启用、回退和销毁状态通知。 */
+    onOffscreenCanvasStatus?: (info: ListTableOffscreenCanvasStatusInfo) => void;
 }
 /**
  * 可展开行配置。
@@ -1646,7 +1744,13 @@ interface ListTableExpandableOptions<RecordType = Record<string, unknown>> {
     expandedRowRender?: (record: RecordType, index: number) => ListTableRenderResult<RecordType> | ListTableRenderResult<RecordType>[];
     expandedRowHeight?: number | ((record: RecordType, index: number) => number);
     indentSize?: number;
-    showExpandIcon?: boolean;
+    /**
+     * 是否展示展开按钮。传入回调时可按行控制按钮可见性。
+     *
+     * 隐藏按钮不会改变该行的可展开状态，仍可配合 `expandRowByClick`
+     * 或受控的 `expandedRowKeys` 使用。
+     */
+    showExpandIcon?: boolean | ((record: RecordType, index: number) => boolean);
     showExpandColumn?: boolean;
     columnWidth?: number;
     fixed?: "left" | "right";
@@ -1706,6 +1810,13 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     height?: number | string;
     columns: ListTableColumn<RecordType>[];
     dataSource: RecordType[];
+    /**
+     * 数据是否仍在加载或分批生成。
+     * 加载期间保留汇总行及标题，不统计临时数据或展示旧结果。
+     * 完整数据就绪后设为 false，表格自动计算汇总或展示服务端汇总。
+     * @default false
+     */
+    loading?: boolean;
     /** 顶部分组栏与数据分组配置。 */
     /** 数据分组配置；不传时不启用分组功能。 */
     grouping?: ListTableGroupingOptions;
@@ -1744,6 +1855,8 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     summaryRowHeight?: number;
     overscanRowCount?: number;
     query?: ListTableQueryOptions<RecordType>;
+    /** 实验能力，仅用于验证，不保证默认启用。 */
+    experimental?: ListTableExperimentalOptions;
     /**
      * 是否展示最左侧的空白行选择器列。
      * 传入对象时可配置列宽，默认宽度为 `12px`。
@@ -1808,17 +1921,43 @@ type ListTableDensity = 26 | 32 | 48 | 56 | "auto";
 /**
  * XLSX 导出参数。
  */
-interface ListTableExportXlsxOptions {
+interface ListTableExportXlsxOptions extends XlsxExportOptions {
     /** 导出文件名，可省略 `.xlsx` 扩展名。 */
     fileName?: string;
     /** 是否在数据末尾追加按当前列配置计算的汇总行。 */
     includeSummary?: boolean;
+    /** 导出失败通知；已保存的分文件不会撤回，取消不触发此回调。 */
+    onError?: (error: unknown) => void;
 }
 
 /**
  * ListTable 原生入口。
  */
 declare class ListTable<RecordType = Record<string, unknown>> {
+    /** 在 columns 中声明独立展开列位置的占位符。 */
+    static readonly EXPAND_COLUMN: Readonly<{
+        key: "__row_expand__";
+        dataIndex: "__row_expand__";
+        title: "";
+        hideInSetting: true;
+        disableHide: true;
+    }>;
+    /** 在 columns 中声明行选择列位置的占位符。 */
+    static readonly SELECTION_COLUMN: Readonly<{
+        key: "__row_selection__";
+        dataIndex: "__row_selection__";
+        title: "";
+        hideInSetting: true;
+        disableHide: true;
+    }>;
+    /** `SELECTION_COLUMN` 的语义化别名。 */
+    static readonly ROW_SELECTION_COLUMN: Readonly<{
+        key: "__row_selection__";
+        dataIndex: "__row_selection__";
+        title: "";
+        hideInSetting: true;
+        disableHide: true;
+    }>;
     private readonly container;
     private options;
     private core;
@@ -1867,6 +2006,8 @@ declare class ListTable<RecordType = Record<string, unknown>> {
      * 重置筛选状态。
      */
     resetFilter(): void;
+    /** 人工重试最近一次仍有效的本地查询失败。 */
+    retryQuery(): boolean;
     /**
      * 设置并持久化内置表格密度。
      */
@@ -1877,6 +2018,31 @@ declare class ListTable<RecordType = Record<string, unknown>> {
     destroy(): void;
 }
 
+/** 在 columns 中声明独立展开列位置的占位符，使用方式与 AntD 一致。 */
+declare const EXPAND_COLUMN: Readonly<{
+    key: "__row_expand__";
+    dataIndex: "__row_expand__";
+    title: "";
+    hideInSetting: true;
+    disableHide: true;
+}>;
+/** 在 columns 中声明行选择列位置的占位符，使用方式与 AntD 一致。 */
+declare const SELECTION_COLUMN: Readonly<{
+    key: "__row_selection__";
+    dataIndex: "__row_selection__";
+    title: "";
+    hideInSetting: true;
+    disableHide: true;
+}>;
+/** `SELECTION_COLUMN` 的语义化别名。 */
+declare const ROW_SELECTION_COLUMN: Readonly<{
+    key: "__row_selection__";
+    dataIndex: "__row_selection__";
+    title: "";
+    hideInSetting: true;
+    disableHide: true;
+}>;
+
 /**
  * 将持久化的列设置恢复为传入列定义中的宽度、显隐和固定状态。
  * 排序、过滤、缩放、密度以及其他列展示配置保持不变。
@@ -1915,4 +2081,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 ListTableDataFormat, type ListTableDataFormatOptions, type ListTableDataFormatType, type ListTableDebugOptions, type ListTableDebugSnapshot, type ListTableDensity, 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 ListTableFilterCondition$1 as ListTableFilterCondition, 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 ListTableRateSymbolType, 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, resetListTableStoredColumnConfig };
+export { type CreateCellEditorSessionParams, type DebugHitTestResult, EXPAND_COLUMN, 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 ListTableDensity, 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 ListTableExperimentalOptions, type ListTableExportXlsxOptions, type ListTableFilterCondition$1 as ListTableFilterCondition, 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 ListTableOffscreenCanvasStatusInfo, 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 ListTableRateSymbolType, 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 ListTableServerSummaryValues, 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, ROW_SELECTION_COLUMN, type RenderCellDescriptor, SELECTION_COLUMN, resetListTableStoredColumnConfig };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CanvasChartSparklineOption } from '@canvas-components/chart';
+import { XlsxExportOptions } from '@canvas-components/utils';
 
 /**
  * 排序状态。
@@ -125,17 +126,41 @@ interface ListTableDebugOptions {
  * 列表表格性能阶段指标。
  */
 interface ListTablePerformanceMetric {
-    phase: "grouping" | "snapshot" | "render";
+    phase: "query" | "grouping" | "snapshot" | "render" | "publish" | "offscreen";
     durationMs: number;
     inputRowCount: number;
     outputRowCount: number;
     cacheHit?: boolean;
+    /** 快照缓存未命中的首个输入原因。 */
+    cacheMissReason?: string;
     groupedRowCount?: number;
     scrollOnly?: boolean;
+    /** 本帧由动画扫描与绘制共享的单元格内容缓存命中数。 */
+    cellContentCacheHits?: number;
+    /** 本帧实际执行单元格内容解析的次数。 */
+    cellContentCacheMisses?: number;
+    /** 本帧结束时保留的单元格内容缓存项数。 */
+    cellContentCacheEntries?: number;
     batchCount?: number;
     indexNodeCount?: number;
     cancelledCount?: number;
     status?: "ready" | "cancelled" | "error";
+    /** 查询实际使用的执行器。 */
+    executor?: "none" | "worker" | "main" | "mixed";
+    /** Worker 回退主线程的原因；多阶段回退时使用逗号分隔。 */
+    fallbackReason?: string;
+    /** 单次查询发生的执行器回退次数。 */
+    fallbackCount?: number;
+    /** 主线程协作式计算主动让步次数。 */
+    sliceCount?: number;
+    /** 字段缓存命中次数。 */
+    fieldCacheHitCount?: number;
+    /** 字段缓存未命中次数。 */
+    fieldCacheMissCount?: number;
+    /** 最近一次字段缓存未命中原因。 */
+    fieldCacheMissReason?: string;
+    /** 查询各阶段耗时，单位毫秒。 */
+    stageDurationsMs?: Partial<Record<"filter" | "sort" | "fieldExtraction" | "workerTransfer" | "workerCompute" | "indexMapping" | "materialization" | "resultApply", number>>;
 }
 /**
  * 查询回调扩展参数。
@@ -748,6 +773,10 @@ interface ListTableNestedTableColumn {
     filterValueGetter?: (record: Record<string, unknown>) => unknown;
     filterOptionValueGetter?: (record: Record<string, unknown>) => unknown;
     filterOptions?: Array<string | ListTableFilterOption>;
+    /** 子表格汇总行配置。设为 `true` 等效于 `{ type: "sum" }`。 */
+    summary?: boolean | ListTableSummaryConfig<Record<string, unknown>>;
+    /** 子表格汇总行标题。 */
+    summaryTitle?: string;
 }
 /**
  * 单元格内嵌表格片段。
@@ -862,6 +891,13 @@ interface ListTableColumn<RecordType = Record<string, unknown>> {
     headerAlign?: ListTableHorizontalAlign;
     fixed?: "left" | "right";
     hidden?: boolean;
+    /**
+     * 是否将行展开按钮绘制在当前业务列中。
+     *
+     * 多列设为 `true` 时使用可见顺序中的第一列；设为 `false` 时，
+     * 当前列不会成为未指定目标时的默认内嵌列。
+     */
+    showExpandIcon?: boolean;
     /** 列设置中使用的标题，未传时使用 `title`。 */
     settingTitle?: string;
     /** 首次创建表格时是否默认隐藏。显式传入 `hidden` 时以 `hidden` 为准。 */
@@ -1114,11 +1150,14 @@ interface HeaderContextMenuConfig {
     onChangeDataFormat?: (dataFormat: ListTableDataFormat) => void;
     summaryVisible?: boolean;
     summaryColumnKey?: string;
+    summaryTitle?: string;
     summaryType?: ListTableSummaryType;
     summaryPrecision?: number;
     summaryRoundingMode?: ListTableSummaryRoundingMode;
     summaryPreserveTrailingZeros?: boolean;
     onToggleSummary?: () => void;
+    onChangeSummaryTitle?: (title: string) => void;
+    onClearSummary?: () => void;
     onChangeSummaryType?: (type: ListTableSummaryType) => void;
     onChangeSummaryPrecision?: (precision: number | undefined) => void;
     onChangeSummaryRoundingMode?: (mode: ListTableSummaryRoundingMode) => void;
@@ -1548,6 +1587,8 @@ type ListTableQueryPagination = false | {
  * AntD 风格的过滤结果。
  */
 type ListTableQueryFilters = Record<string, string[] | null>;
+/** 服务端返回的汇总结果，键使用列 key，值为最终展示内容。 */
+type ListTableServerSummaryValues = ReadonlyMap<string, string | number | bigint | null | undefined> | Readonly<Record<string, string | number | bigint | null | undefined>>;
 /**
  * AntD 风格的排序结果。
  */
@@ -1619,11 +1660,43 @@ interface ListTableRowSelectionOptions<RecordType> {
  * AntD 风格的四参数查询回调。
  */
 type ListTableQueryChange<RecordType> = (pagination: ListTableQueryPagination, filters: ListTableQueryFilters, sorter: ListTableQuerySorter, extra: ListTableQueryChangeExtra<RecordType>) => void;
+/** 本地查询失败通知。 */
+interface ListTableQueryErrorInfo {
+    /** 失败的查询动作。 */
+    action: "sort" | "filter";
+    /** 查询链抛出的原始错误。 */
+    error: unknown;
+    /**
+     * 人工重试本次查询。仅当失败任务仍是最新任务时返回 true 并启动重试；
+     * 查询状态已变化、实例已重置或销毁时返回 false。
+     */
+    retry: () => boolean;
+}
 interface ListTableQueryOptions<RecordType> {
     enabled?: boolean;
     mode?: "local" | "remote";
     dataSource?: RecordType[];
     optionThreshold?: number;
+    /**
+     * 是否允许本地大数据查询使用 Worker。
+     *
+     * - `"auto"` / `undefined`：达到内部阈值时自动启用。
+     * - `true`：不受行数阈值限制，优先尝试 Worker。
+     * - `false`：始终使用可取消的主线程分片路径。
+     */
+    worker?: boolean | "auto";
+    /** 自动模式下启用 Worker 的最小数据行数，默认 50000。 */
+    workerThreshold?: number;
+    /**
+     * 是否缓存本地查询提取出的字段快照。启用时应同时维护 `dataVersion`，
+     * 原地编辑数据后递增版本以避免复用旧值。
+     * @default false
+     */
+    fieldCache?: boolean;
+    /** 本地数据内容修订号，用于主动失效字段缓存。 */
+    dataVersion?: string | number;
+    /** 字段缓存容量上限（估算字节数），默认 32 MiB。 */
+    fieldCacheMaxBytes?: number;
     /**
      * 点击过滤候选项后是否立即应用过滤，并保持过滤面板打开。
      *
@@ -1631,7 +1704,32 @@ interface ListTableQueryOptions<RecordType> {
      */
     filterOptionImmediateApply?: boolean;
     mergeCell?: ListTableMergeCellOptions;
+    /**
+     * 服务端汇总结果。传入后直接用于汇总行，不再对当前 dataSource 本地计算。
+     *
+     * 键应使用列 key；未配置显式 key 时通常与 dataIndex 相同。
+     */
+    summaryValues?: ListTableServerSummaryValues;
     onChange?: ListTableQueryChange<RecordType>;
+    /** 本地排序或过滤最终失败后的统一通知；不会因 Worker 回退自动触发。 */
+    onError?: (info: ListTableQueryErrorInfo) => void;
+}
+/** OffscreenCanvas 实验状态。 */
+interface ListTableOffscreenCanvasStatusInfo {
+    status: "active" | "unsupported" | "fallback" | "destroyed";
+    reason?: string;
+}
+/** 尚未默认启用的渲染实验。 */
+interface ListTableExperimentalOptions {
+    /**
+     * 把最终可视帧交给 OffscreenCanvas Worker 呈现。
+     *
+     * 该开关仅在实例挂载前读取；能力不足或运行失败时自动恢复主线程画布。
+     * @default false
+     */
+    offscreenCanvas?: boolean;
+    /** OffscreenCanvas 启用、回退和销毁状态通知。 */
+    onOffscreenCanvasStatus?: (info: ListTableOffscreenCanvasStatusInfo) => void;
 }
 /**
  * 可展开行配置。
@@ -1646,7 +1744,13 @@ interface ListTableExpandableOptions<RecordType = Record<string, unknown>> {
     expandedRowRender?: (record: RecordType, index: number) => ListTableRenderResult<RecordType> | ListTableRenderResult<RecordType>[];
     expandedRowHeight?: number | ((record: RecordType, index: number) => number);
     indentSize?: number;
-    showExpandIcon?: boolean;
+    /**
+     * 是否展示展开按钮。传入回调时可按行控制按钮可见性。
+     *
+     * 隐藏按钮不会改变该行的可展开状态，仍可配合 `expandRowByClick`
+     * 或受控的 `expandedRowKeys` 使用。
+     */
+    showExpandIcon?: boolean | ((record: RecordType, index: number) => boolean);
     showExpandColumn?: boolean;
     columnWidth?: number;
     fixed?: "left" | "right";
@@ -1706,6 +1810,13 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     height?: number | string;
     columns: ListTableColumn<RecordType>[];
     dataSource: RecordType[];
+    /**
+     * 数据是否仍在加载或分批生成。
+     * 加载期间保留汇总行及标题，不统计临时数据或展示旧结果。
+     * 完整数据就绪后设为 false，表格自动计算汇总或展示服务端汇总。
+     * @default false
+     */
+    loading?: boolean;
     /** 顶部分组栏与数据分组配置。 */
     /** 数据分组配置；不传时不启用分组功能。 */
     grouping?: ListTableGroupingOptions;
@@ -1744,6 +1855,8 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
     summaryRowHeight?: number;
     overscanRowCount?: number;
     query?: ListTableQueryOptions<RecordType>;
+    /** 实验能力，仅用于验证，不保证默认启用。 */
+    experimental?: ListTableExperimentalOptions;
     /**
      * 是否展示最左侧的空白行选择器列。
      * 传入对象时可配置列宽，默认宽度为 `12px`。
@@ -1808,17 +1921,43 @@ type ListTableDensity = 26 | 32 | 48 | 56 | "auto";
 /**
  * XLSX 导出参数。
  */
-interface ListTableExportXlsxOptions {
+interface ListTableExportXlsxOptions extends XlsxExportOptions {
     /** 导出文件名，可省略 `.xlsx` 扩展名。 */
     fileName?: string;
     /** 是否在数据末尾追加按当前列配置计算的汇总行。 */
     includeSummary?: boolean;
+    /** 导出失败通知；已保存的分文件不会撤回，取消不触发此回调。 */
+    onError?: (error: unknown) => void;
 }
 
 /**
  * ListTable 原生入口。
  */
 declare class ListTable<RecordType = Record<string, unknown>> {
+    /** 在 columns 中声明独立展开列位置的占位符。 */
+    static readonly EXPAND_COLUMN: Readonly<{
+        key: "__row_expand__";
+        dataIndex: "__row_expand__";
+        title: "";
+        hideInSetting: true;
+        disableHide: true;
+    }>;
+    /** 在 columns 中声明行选择列位置的占位符。 */
+    static readonly SELECTION_COLUMN: Readonly<{
+        key: "__row_selection__";
+        dataIndex: "__row_selection__";
+        title: "";
+        hideInSetting: true;
+        disableHide: true;
+    }>;
+    /** `SELECTION_COLUMN` 的语义化别名。 */
+    static readonly ROW_SELECTION_COLUMN: Readonly<{
+        key: "__row_selection__";
+        dataIndex: "__row_selection__";
+        title: "";
+        hideInSetting: true;
+        disableHide: true;
+    }>;
     private readonly container;
     private options;
     private core;
@@ -1867,6 +2006,8 @@ declare class ListTable<RecordType = Record<string, unknown>> {
      * 重置筛选状态。
      */
     resetFilter(): void;
+    /** 人工重试最近一次仍有效的本地查询失败。 */
+    retryQuery(): boolean;
     /**
      * 设置并持久化内置表格密度。
      */
@@ -1877,6 +2018,31 @@ declare class ListTable<RecordType = Record<string, unknown>> {
     destroy(): void;
 }
 
+/** 在 columns 中声明独立展开列位置的占位符，使用方式与 AntD 一致。 */
+declare const EXPAND_COLUMN: Readonly<{
+    key: "__row_expand__";
+    dataIndex: "__row_expand__";
+    title: "";
+    hideInSetting: true;
+    disableHide: true;
+}>;
+/** 在 columns 中声明行选择列位置的占位符，使用方式与 AntD 一致。 */
+declare const SELECTION_COLUMN: Readonly<{
+    key: "__row_selection__";
+    dataIndex: "__row_selection__";
+    title: "";
+    hideInSetting: true;
+    disableHide: true;
+}>;
+/** `SELECTION_COLUMN` 的语义化别名。 */
+declare const ROW_SELECTION_COLUMN: Readonly<{
+    key: "__row_selection__";
+    dataIndex: "__row_selection__";
+    title: "";
+    hideInSetting: true;
+    disableHide: true;
+}>;
+
 /**
  * 将持久化的列设置恢复为传入列定义中的宽度、显隐和固定状态。
  * 排序、过滤、缩放、密度以及其他列展示配置保持不变。
@@ -1915,4 +2081,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 ListTableDataFormat, type ListTableDataFormatOptions, type ListTableDataFormatType, type ListTableDebugOptions, type ListTableDebugSnapshot, type ListTableDensity, 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 ListTableFilterCondition$1 as ListTableFilterCondition, 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 ListTableRateSymbolType, 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, resetListTableStoredColumnConfig };
+export { type CreateCellEditorSessionParams, type DebugHitTestResult, EXPAND_COLUMN, 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 ListTableDensity, 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 ListTableExperimentalOptions, type ListTableExportXlsxOptions, type ListTableFilterCondition$1 as ListTableFilterCondition, 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 ListTableOffscreenCanvasStatusInfo, 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 ListTableRateSymbolType, 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 ListTableServerSummaryValues, 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, ROW_SELECTION_COLUMN, type RenderCellDescriptor, SELECTION_COLUMN, resetListTableStoredColumnConfig };