@canvas-components/list-table 0.3.18 → 0.3.20

package/dist/index.d.ts

@@ -1,21 +1,20 @@
+import * as antDesignIcons from '@ant-design/icons-svg';
+import { CanvasChartPieOption, CanvasChartRadarOption, CanvasChartGaugeOption, CanvasChartSparklineOption } from '@canvas-components/chart';
 import { CanvasScrollbarOptions, XlsxExportOptions } from '@canvas-components/utils';
 export { CanvasScrollbarAxisOptions as ListTableScrollbarAxisOptions } from '@canvas-components/utils';
-import { CanvasChartSparklineOption } from '@canvas-components/chart';
 
 /**
  * 排序状态。
  */
-interface ListTableSortState {
-    key: string | null;
-    order: "ascend" | "descend" | null;
-}
+type ListTableSortState = ListTableSortItem[];
 /**
  * 多列排序项。
  */
 interface ListTableSortItem {
     key: string;
     order: "ascend" | "descend";
-    priority: number;
+    /** 配置了多列排序时的优先级；未配置表示单列排序。 */
+    priority?: number;
 }
 /**
  * 过滤匹配模式。
@@ -174,7 +173,7 @@ interface ListTableQueryChangeExtra<RecordType> {
     filteredDataSource: RecordType[];
     rawFilters: ListTableFilterState;
     sorter: ListTableSortState;
-    sorters?: ListTableSortItem[];
+    sorters: ListTableSortItem[];
 }
 
 /**
@@ -293,6 +292,53 @@ interface ListTableDebugSnapshot {
     hitTest?: DebugHitTestResult;
 }
 
+/** 可单独控制持久化的表格配置；列设置及条件格式使用各自已有开关。 */
+type ListTableCacheCategory = "sort" | "filter" | "summary" | "alignment" | "dataFormat" | "density" | "zoom";
+/** 未指定的缓存类别默认开启，持久化需要 storageKey。 */
+type ListTableCachePreferences = Partial<Record<ListTableCacheCategory, boolean>>;
+
+/** 上传单元格的值，始终使用文件数组；selected 表示仅本地选择，尚未上传。 */
+interface ListTableUploadFile {
+    uid: string;
+    name: string;
+    type?: string;
+    size?: number;
+    url?: string;
+    thumbUrl?: string;
+    status?: "selected" | "uploading" | "done" | "error";
+    percent?: number;
+    error?: string;
+    response?: unknown;
+    originFileObj?: File;
+}
+/** 自定义上传请求，关闭编辑或移除文件时调用返回的 abort。 */
+interface ListTableUploadRequest {
+    file: File;
+    onProgress: (percent: number) => void;
+    onSuccess: (response: unknown) => void;
+    onError: (error: Error) => void;
+}
+/** 原生上传编辑配置，不依赖框架；未设置 action/customRequest 时仅选择本地文件。 */
+interface ListTableUploadConfig {
+    accept?: string;
+    multiple?: boolean;
+    maxCount?: number;
+    /** 文件大小上限，单位字节。 */
+    maxSize?: number;
+    action?: string;
+    name?: string;
+    headers?: Record<string, string>;
+    data?: Record<string, string | Blob>;
+    withCredentials?: boolean;
+    /** 返回 false 保留文件但不上传；抛出错误则拒绝文件。 */
+    beforeUpload?: (file: File) => boolean | void | Promise<boolean | void>;
+    customRequest?: (request: ListTableUploadRequest) => void | {
+        abort: () => void;
+    };
+    /** 默认读取响应对象的 url 字段，可按实际服务端协议覆盖。 */
+    getResponseUrl?: (response: unknown, file: File) => string | undefined;
+}
+
 /** Canvas 区域支持的 CSS 属性。长度支持数字（px）或 px 字符串，padding 支持 1～2 值。 */
 interface ListTableCSSProperties {
     backgroundColor?: string;
@@ -379,6 +425,61 @@ interface ListTableTheme {
     headerFontWeight: string;
 }
 
+/** 当前列原始值的条件比较方式。 */
+type ListTableConditionalOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "contains" | "empty" | "notEmpty";
+/** 当前列的一项比较条件。 */
+interface ListTableConditionalFormatCondition {
+    /** 与上一条件的关系；首项忽略。且优先于或，未指定时兼容规则的统一关系。 */
+    relation?: "and" | "or";
+    operator: ListTableConditionalOperator;
+    value?: string | number;
+    endValue?: string | number;
+}
+/** 条件格式规则，按数组顺序匹配，首条命中的背景生效。 */
+interface ListTableConditionalFormatRule {
+    id: string;
+    name?: string;
+    /** 兼容旧版单条件配置；conditions 存在时优先采用条件列表。 */
+    operator?: ListTableConditionalOperator;
+    value?: string | number;
+    endValue?: string | number;
+    conditions?: ListTableConditionalFormatCondition[];
+    /** 兼容旧版统一关系；各条件的 relation 优先，默认且。 */
+    conditionRelation?: "and" | "or";
+    backgroundColor: string;
+    /** 命中规则时的单元格文本颜色。 */
+    textColor: string;
+}
+
+/** 原有短名称，保留已经调整过的图形和评分外观。 */
+declare const listTableBuiltinIconNames: readonly ["star", "sun", "moon", "check", "close", "circle", "check-circle", "close-circle", "clock-circle", "info-circle", "question-circle", "warning", "loading", "plus", "minus", "plus-circle", "minus-circle", "up", "down", "left", "right", "arrow-up", "arrow-down", "arrow-left", "arrow-right", "search", "edit", "delete", "copy", "save", "upload", "download", "reload", "ellipsis", "file", "file-text", "file-pdf", "folder", "folder-open", "picture", "user", "team", "calendar", "filter", "sort-ascending", "sort-descending", "link", "eye", "lock", "unlock", "home", "mail", "setting", "header-sort", "header-sort-ascending", "header-sort-descending", "header-filter", "header-fixed"];
+/** 官方图标使用原始名称，例如 AccountBookOutlined、HeartFilled、SmileTwoTone。 */
+type ListTableAntdIconName = keyof typeof antDesignIcons;
+type ListTableBuiltinIconName = (typeof listTableBuiltinIconNames)[number];
+/** 全量官方图标定义为纯数据，不包含 React 运行时。 */
+declare const listTableAntdIconNames: ListTableAntdIconName[];
+/** 支持的全部单元格图标名称。 */
+type ListTableSymbolType = ListTableBuiltinIconName | ListTableAntdIconName;
+declare const listTableIconNames: readonly ListTableSymbolType[];
+/** 评分控件仅使用可部分填充的图形，不随普通图标扩展。 */
+type ListTableRateSymbolType = "star" | "sun" | "moon";
+
+/** TreeSelect 的原生树节点，value 在树内唯一。 */
+interface ListTableTreeSelectNode {
+    title: string;
+    value: string | number;
+    key?: string | number;
+    disabled?: boolean;
+    selectable?: boolean;
+    children?: ListTableTreeSelectNode[];
+}
+/** 排序配置；compare 按升序返回负数、零、正数，降序由表格自动反转。 */
+type ListTableSorter<RecordType> = boolean | {
+    /** 多列排序优先级，数值越大越优先。 */
+    multiple?: number;
+    /** 自定义记录比较，优先于 sortValueGetter；大数据使用主线程可取消分片。 */
+    compare?: (a: RecordType, b: RecordType) => number;
+};
 /**
  * 汇总类型说明：
  * - `sum`：对当前列做求和
@@ -431,6 +532,8 @@ interface ListTableSummaryConfig<RecordType = Record<string, unknown>> {
     roundingMode?: ListTableSummaryRoundingMode;
     /** 是否保留精度补齐产生的无效零，默认不保留。 */
     preserveTrailingZeros?: boolean;
+    /** 是否展示“求和: ”等汇总方式前缀，默认开启。 */
+    showTypePrefix?: boolean;
 }
 /**
  * 路径索引定义。
@@ -461,12 +564,9 @@ type ListTableSparklineSize = "small" | "medium" | number | [number, number] | {
     width?: number;
     height?: number;
 };
-type ListTableChartType = "sparkline" | (string & {});
+type ListTableChartType = "sparkline" | "pie" | "radar" | "gauge" | (string & {});
 type ListTableChartSize = ListTableSparklineSize;
 type ListTableRateSize = "small" | "medium" | "large" | number;
-type ListTableRateSymbolType = "star" | "sun" | "moon";
-/** 单元格内置图标名称。 */
-type ListTableSymbolType = ListTableRateSymbolType | "check" | "close";
 type ListTableButtonType = "primary" | "default" | "dashed" | "text" | "link";
 type ListTableButtonSize = "small" | "middle" | "medium" | "large";
 /**
@@ -620,6 +720,34 @@ interface ListTableProgressCellContent<RecordType = any> extends ListTableBaseCe
     successColor?: string;
     strokeWidth?: number;
 }
+/** 时间轴节点；title 为时间标签，content 为事件描述，不接受 ReactNode。 */
+interface ListTableTimelineItem {
+    title?: string;
+    content: string;
+    /** 支持 blue、green、red、gray 以及自定义颜色。 */
+    color?: string;
+    position?: "start" | "end";
+    /** 进行中节点使用缺口圆环和虚线连接，不创建持续动画。 */
+    loading?: boolean;
+    /** 可复用全部内置图标；clock、cross 保留为时间轴快捷名称。 */
+    icon?: ListTableSymbolType | "clock" | "cross";
+}
+/** 原生纵向时间轴。配合 rowHeight: "auto" 展示完整内容。 */
+interface ListTableTimelineCellContent<RecordType = any> extends ListTableBaseCellContent<RecordType> {
+    type: "timeline";
+    items: ListTableTimelineItem[];
+    mode?: "start" | "end" | "alternate";
+    reverse?: boolean;
+    variant?: "outlined" | "filled";
+    /** 默认宽度 220，窄列自动收缩并换行。 */
+    width?: number;
+    /** 节点之间的额外留白，默认 12px。 */
+    itemGap?: number;
+    /** 节点图标直径，默认 16px，最大不超过文字行高。 */
+    dotSize?: number;
+    lineColor?: string;
+    titleColor?: string;
+}
 /**
  * 通用单元格图表片段基类。
  */
@@ -628,6 +756,8 @@ interface ListTableBaseChartCellContent<RecordType = any, ChartType extends stri
     /** 是否允许点击预览，默认开启。 */
     preview?: boolean;
     chartType: ChartType;
+    /** 仅保留主要图形；折线图只绘制折线。 */
+    simple?: boolean;
     option: Option;
     size?: ListTableChartSize;
 }
@@ -644,6 +774,8 @@ interface ListTableSparklineChartCellContent<RecordType = any> extends ListTable
     /** 是否允许点击预览，默认开启。 */
     preview?: boolean;
     chartType: "sparkline";
+    /** 仅绘制折线或柱体，隐藏坐标轴、图例等辅助元素。 */
+    simple?: boolean;
     option?: CanvasChartSparklineOption;
     values?: number[];
     min?: number;
@@ -660,7 +792,13 @@ interface ListTableSparklineChartCellContent<RecordType = any> extends ListTable
 /**
  * 单元格图表片段。
  */
-type ListTableChartCellContent<RecordType = any> = ListTableSparklineChartCellContent<RecordType> | ListTableCustomChartCellContent<RecordType>;
+type ListTablePieChartCellContent<RecordType = any> = ListTableBaseChartCellContent<RecordType, "pie", CanvasChartPieOption>;
+/** 单元格雷达图配置。 */
+type ListTableRadarChartCellContent<RecordType = any> = ListTableBaseChartCellContent<RecordType, "radar", CanvasChartRadarOption>;
+/** 单元格仪表盘配置。 */
+type ListTableGaugeChartCellContent<RecordType = any> = ListTableBaseChartCellContent<RecordType, "gauge", CanvasChartGaugeOption>;
+/** 单元格内置及自定义图表。 */
+type ListTableChartCellContent<RecordType = any> = ListTablePieChartCellContent<RecordType> | ListTableRadarChartCellContent<RecordType> | ListTableGaugeChartCellContent<RecordType> | ListTableSparklineChartCellContent<RecordType> | ListTableCustomChartCellContent<RecordType>;
 /**
  * 单元格评分片段。
  */
@@ -684,6 +822,8 @@ interface ListTableRateCellContent<RecordType = any> extends ListTableBaseCellCo
 interface ListTableIconCellContent<RecordType = any> extends ListTableBaseCellContent<RecordType> {
     type: "icon";
     icon: ListTableSymbolType;
+    /** 官方 TwoTone 图标的主色，或 [主色, 副色]；未指定时使用 color。 */
+    twoToneColor?: string | [string, string];
     color?: string;
     size?: number;
 }
@@ -813,6 +953,8 @@ interface ListTableNestedTableColumn {
     formItemProps?: ListTableFormItemProps<Record<string, unknown>>;
     fixed?: "left" | "right";
     allowSort?: boolean;
+    /** 配置 multiple 开启多列排序，数值越大优先级越高。 */
+    sorter?: ListTableSorter<Record<string, unknown>>;
     sortValueGetter?: (record: Record<string, unknown>) => string | number | null | undefined;
     defaultSortOrder?: "ascend" | "descend";
     allowFilter?: boolean;
@@ -847,7 +989,7 @@ interface ListTableNestedTableCellContent<RecordType = any> extends ListTableBas
 /**
  * 单元格内容定义。
  */
-type ListTableCellContent<RecordType = any> = ListTableArrowCellContent<RecordType> | ListTableIconCellContent<RecordType> | ListTableTextCellContent<RecordType> | ListTableMoneyCellContent<RecordType> | ListTableLinkCellContent<RecordType> | ListTableImageCellContent<RecordType> | ListTableProgressCellContent<RecordType> | ListTableChartCellContent<RecordType> | ListTableRateCellContent<RecordType> | ListTableButtonCellContent<RecordType> | ListTableQrCodeCellContent<RecordType> | ListTableBarcodeCellContent<RecordType> | ListTableColorCellContent<RecordType> | ListTableTagCellContent<RecordType> | ListTableSelectionCellContent<RecordType> | ListTableSwitchCellContent<RecordType> | ListTableNestedTableCellContent<RecordType>;
+type ListTableCellContent<RecordType = any> = ListTableArrowCellContent<RecordType> | ListTableIconCellContent<RecordType> | ListTableTextCellContent<RecordType> | ListTableMoneyCellContent<RecordType> | ListTableLinkCellContent<RecordType> | ListTableImageCellContent<RecordType> | ListTableProgressCellContent<RecordType> | ListTableTimelineCellContent<RecordType> | ListTableChartCellContent<RecordType> | ListTableRateCellContent<RecordType> | ListTableButtonCellContent<RecordType> | ListTableQrCodeCellContent<RecordType> | ListTableBarcodeCellContent<RecordType> | ListTableColorCellContent<RecordType> | ListTableTagCellContent<RecordType> | ListTableSelectionCellContent<RecordType> | ListTableSwitchCellContent<RecordType> | ListTableNestedTableCellContent<RecordType>;
 /**
  * 单元格跨度配置。
  *
@@ -869,13 +1011,17 @@ type ListTableCellRender<RecordType> = (value: unknown, record: RecordType, rowI
  *
  * 采用可扩展枚举，便于后续继续补充原生编辑器实现。
  */
-type ListTableEditValueType = "text" | "number" | "input-range" | "year" | "quarter" | "month" | "time" | "datetime" | "timerange" | "date" | "date-range" | "datetime-range" | "color" | "select" | "auto-complete";
+type ListTableEditValueType = "text" | "number" | "input-range" | "year" | "quarter" | "month" | "time" | "datetime" | "timerange" | "date" | "date-range" | "datetime-range" | "color" | "select" | "cascader" | "tree-select" | "upload" | "auto-complete";
 /**
  * 下拉编辑选项。
  */
 interface ListTableEditOption {
     label: string;
     value: string | number;
+    /** 是否禁用该选项及其下级。 */
+    disabled?: boolean;
+    /** Cascader 的下级选项。 */
+    children?: ListTableEditOption[];
 }
 /**
  * 下拉编辑选项过滤函数。
@@ -900,6 +1046,26 @@ interface ListTableFormItemPropsConfig<RecordType = Record<string, unknown>> {
     max?: number | string;
     step?: number | string;
     options?: ListTableEditOption[];
+    /** TreeSelect 树节点，使用 title/value/children，value 在树内唯一。 */
+    treeData?: ListTableTreeSelectNode[];
+    /** 原生文件上传配置。 */
+    upload?: ListTableUploadConfig;
+    /** TreeSelect 初始展开全部节点。 */
+    treeDefaultExpandAll?: boolean;
+    /** TreeSelect 初始展开节点 key，未指定 key 时使用 value。 */
+    treeDefaultExpandedKeys?: (string | number)[];
+    /** Cascader 是否允许选择非末级，默认 false。 */
+    changeOnSelect?: boolean;
+    /** 开启多选：Cascader 使用二维路径数组，TreeSelect 使用节点值数组。 */
+    multiple?: boolean;
+    /** 多选回填策略：完整父级或末级路径，默认 SHOW_PARENT。 */
+    showCheckedStrategy?: "SHOW_PARENT" | "SHOW_CHILD";
+    /** Cascader 展开下级的方式，默认 click。 */
+    expandTrigger?: "click" | "hover";
+    /** Cascader / TreeSelect 是否允许清空，默认 true。 */
+    allowClear?: boolean;
+    /** Cascader 路径显示文本，默认使用 / 分隔。 */
+    displayRender?: (labels: string[], selectedOptions: ListTableEditOption[]) => string;
     /** 是否开启下拉选项搜索。 */
     showSearch?: boolean;
     /** 自定义下拉选项过滤逻辑，仅在开启搜索时生效。 */
@@ -965,7 +1131,8 @@ interface ListTableColumn<RecordType = Record<string, unknown>> {
     allowSort?: boolean;
     sortValueGetter?: (record: RecordType) => string | number | null | undefined;
     defaultSortOrder?: "ascend" | "descend";
-    sortPriority?: number;
+    /** 配置 multiple 开启多列排序，数值越大优先级越高。 */
+    sorter?: ListTableSorter<RecordType>;
     allowFilter?: boolean;
     filterModes?: Array<"fuzzy" | "exact">;
     filterValueGetter?: (record: RecordType) => unknown;
@@ -979,12 +1146,16 @@ interface ListTableColumn<RecordType = Record<string, unknown>> {
      * 用法参考 AntD Table 的 `onCell`。
      */
     onCell?: (value: unknown, record: RecordType, rowIndex: number, column: ListTableColumn<RecordType>) => ListTableCellSpan | null | undefined;
-    cellType?: "text" | "money" | "link" | "image" | "qrcode" | "barcode" | "color" | "progress" | "chart" | "rate" | "checkbox" | "radio" | "switch" | "tag" | "button" | "custom";
+    cellType?: "text" | "money" | "link" | "image" | "qrcode" | "barcode" | "color" | "progress" | "timeline" | "chart" | "rate" | "checkbox" | "radio" | "switch" | "tag" | "button" | "custom";
     cellStyle?: ListTableCellStyle;
     /** 金额单元格格式配置，仅在 `cellType: "money"` 时生效。 */
     moneyFormat?: ListTableMoneyFormatOptions;
     /** 通过列设置覆盖的数据显示格式。 */
     dataFormat?: ListTableDataFormat;
+    /** 仅当前列数据单元格生效的条件背景规则，首条命中优先。 */
+    conditionalFormats?: ListTableConditionalFormatRule[];
+    /** 是否缓存当前列条件格式，默认开启；持久化需要 storageKey。 */
+    cacheConditionalFormats?: boolean;
     headerStyle?: ListTableCellStyle;
     /** 汇总单元格样式，优先于表格 styles.summary。 */
     summaryStyle?: ListTableCellStyle;
@@ -1108,6 +1279,12 @@ interface ListTableDangerConfirmRequest {
     onConfirm: () => void;
     onCancel: () => void;
 }
+/** 导出前确认文件名称。 */
+interface ListTableExportNameRequest {
+    fileName: string;
+    onConfirm: (fileName: string) => void;
+    onCancel: () => void;
+}
 interface HeaderContextMenuColumnItem {
     key: string;
     title: string;
@@ -1118,6 +1295,11 @@ interface HeaderContextMenuColumnItem {
 }
 type HeaderContextMenuDensity = "comfortable" | "middle" | "compact" | "ultra-compact" | "auto";
 interface HeaderContextMenuConfig {
+    conditionalFormats?: ListTableConditionalFormatRule[];
+    cacheConditionalFormats?: boolean;
+    /** 是否已配置持久化存储标识。 */
+    conditionalFormatCacheAvailable?: boolean;
+    onChangeConditionalFormats?: (rules: ListTableConditionalFormatRule[], cache?: boolean) => void;
     x: number;
     y: number;
     columns?: HeaderContextMenuColumnItem[];
@@ -1131,6 +1313,10 @@ interface HeaderContextMenuConfig {
     onCopyRowText?: () => void;
     onCopyRowJson?: () => void;
     onCopySelection?: () => void;
+    /** 复制表格为 PNG 图片。 */
+    onCopyImage?: (scope: "all" | "selection" | "viewport") => void;
+    onExportImage?: (scope: "all" | "selection" | "viewport") => void;
+    canCopySelectionImage?: boolean;
     onOpenSearch?: () => void;
     customSelection?: {
         startRow: number;
@@ -1184,6 +1370,11 @@ interface HeaderContextMenuConfig {
      */
     onChangeZoom?: (zoom: number) => void;
     onToggleColumn?: (columnKey: string, visible: boolean) => void;
+    cacheColumnSettings?: boolean;
+    columnSettingsCacheAvailable?: boolean;
+    onChangeColumnSettingsCache?: (enabled: boolean) => void;
+    cachePreferences?: ListTableCachePreferences;
+    onChangeCachePreference?: (category: ListTableCacheCategory, enabled: boolean) => void;
     alignment?: {
         headerHorizontal: ListTableHorizontalAlign;
         headerVertical: "top" | "middle" | "bottom";
@@ -1200,6 +1391,7 @@ interface HeaderContextMenuConfig {
     summaryPrecision?: number;
     summaryRoundingMode?: ListTableSummaryRoundingMode;
     summaryPreserveTrailingZeros?: boolean;
+    summaryShowTypePrefix?: boolean;
     onToggleSummary?: () => void;
     onChangeSummaryTitle?: (title: string) => void;
     onClearSummary?: () => void;
@@ -1207,6 +1399,7 @@ interface HeaderContextMenuConfig {
     onChangeSummaryPrecision?: (precision: number | undefined) => void;
     onChangeSummaryRoundingMode?: (mode: ListTableSummaryRoundingMode) => void;
     onChangeSummaryPreserveTrailingZeros?: (value: boolean) => void;
+    onChangeSummaryShowTypePrefix?: (value: boolean) => void;
     onClose: () => void;
 }
 interface ListTableSearchRequest {
@@ -1234,10 +1427,14 @@ interface PaginationConfig {
     onChange?: (page: number, pageSize: number) => void;
     onPageSizeChange?: (page: number, pageSize: number) => void;
 }
-type ListTableEditorValueType = "text" | "number" | "input-range" | "year" | "quarter" | "month" | "time" | "datetime" | "timerange" | "date" | "date-range" | "datetime-range" | "color" | "select" | "auto-complete";
+type ListTableEditorValueType = "text" | "number" | "input-range" | "year" | "quarter" | "month" | "time" | "datetime" | "timerange" | "date" | "date-range" | "datetime-range" | "color" | "select" | "cascader" | "tree-select" | "upload" | "auto-complete";
 interface ListTableEditorOption {
     label: string;
     value: string | number;
+    /** 是否禁用该选项及其下级。 */
+    disabled?: boolean;
+    /** Cascader 的下级选项。 */
+    children?: ListTableEditorOption[];
 }
 type ListTableEditorFilterOption = (input: string, option: ListTableEditorOption) => boolean;
 /**
@@ -1245,6 +1442,7 @@ type ListTableEditorFilterOption = (input: string, option: ListTableEditorOption
  */
 type ListTableEditorAutoCompleteEnter = (input: string) => ListTableEditorOption[] | void | Promise<ListTableEditorOption[] | void>;
 interface ListTableEditorConfig {
+    upload?: ListTableUploadConfig;
     valueType?: ListTableEditorValueType;
     format?: ListTableFormItemFormatter<any>;
     placeholder?: string;
@@ -1252,6 +1450,24 @@ interface ListTableEditorConfig {
     max?: number | string;
     step?: number | string;
     options?: ListTableEditorOption[];
+    /** TreeSelect 树节点。 */
+    treeData?: ListTableTreeSelectNode[];
+    /** 初始展开全部树节点。 */
+    treeDefaultExpandAll?: boolean;
+    /** 初始展开节点 key。 */
+    treeDefaultExpandedKeys?: (string | number)[];
+    /** Cascader 是否允许选择非末级。 */
+    changeOnSelect?: boolean;
+    /** 开启多选：Cascader 使用二维路径数组，TreeSelect 使用节点值数组。 */
+    multiple?: boolean;
+    /** 多选回填策略，默认 SHOW_PARENT。 */
+    showCheckedStrategy?: "SHOW_PARENT" | "SHOW_CHILD";
+    /** Cascader 展开下级的方式。 */
+    expandTrigger?: "click" | "hover";
+    /** Cascader / TreeSelect 是否允许清空。 */
+    allowClear?: boolean;
+    /** Cascader 路径显示文本。 */
+    displayRender?: (labels: string[], selectedOptions: ListTableEditorOption[]) => string;
     showSearch?: boolean;
     filterOption?: ListTableEditorFilterOption;
     onPressEnter?: ListTableEditorAutoCompleteEnter;
@@ -1332,6 +1548,8 @@ interface ListTablePaginationAdapter {
     destroy(): void;
 }
 interface CreateCellEditorSessionParams {
+    /** 聚焦时是否全选内容；空单元格由首次键入打开时为 false。 */
+    selectOnFocus?: boolean;
     rect: ListTableEditorRect;
     clipRect?: ListTableEditorRect;
     hostRect?: ListTableEditorRect;
@@ -1345,6 +1563,8 @@ interface CreateCellEditorSessionParams {
 }
 type ListTableEditorNavigateDirection = "up" | "down" | "prev" | "next";
 interface ListTableEditorRequest {
+    /** 聚焦时是否全选内容；false 时光标置于输入内容末尾。 */
+    selectOnFocus?: boolean;
     /** 当前编辑单元格标识，用于切换单元格时重置编辑器状态。 */
     editorKey?: string;
     rect: ListTableEditorRect;
@@ -1505,7 +1725,7 @@ type ListTableHighlightMode = "cell" | "row" | "column" | "cross";
 /**
  * 右键菜单功能项。
  */
-type ListTableContextMenuFeature = "copy" | "search" | "export" | "downloadContent" | "rowCollapse" | "columnCollapse" | "freeze" | "reset" | "sort" | "density" | "zoom" | "columnWidth" | "alignment" | "dataFormat" | "grouping" | "columnVisibility";
+type ListTableContextMenuFeature = "copy" | "search" | "export" | "downloadContent" | "rowCollapse" | "columnCollapse" | "freeze" | "reset" | "sort" | "density" | "zoom" | "columnWidth" | "alignment" | "dataFormat" | "conditionalFormat" | "cache" | "grouping" | "columnVisibility";
 /**
  * 数据分组配置。
  */
@@ -1639,9 +1859,10 @@ type ListTableServerSummaryValues = ReadonlyMap<string, string | number | bigint
  * AntD 风格的排序结果。
  */
 interface ListTableQuerySorter {
-    columnKey: string | null;
+    columnKey: string;
     field?: TableColumnDataIndex;
-    order: ListTableSortState["order"];
+    order: "ascend" | "descend";
+    priority?: number;
 }
 /**
  * 分页配置。
@@ -1705,7 +1926,7 @@ interface ListTableRowSelectionOptions<RecordType> {
 /**
  * AntD 风格的四参数查询回调。
  */
-type ListTableQueryChange<RecordType> = (pagination: ListTableQueryPagination, filters: ListTableQueryFilters, sorter: ListTableQuerySorter, extra: ListTableQueryChangeExtra<RecordType>) => void;
+type ListTableQueryChange<RecordType> = (pagination: ListTableQueryPagination, filters: ListTableQueryFilters, sorter: ListTableQuerySorter[], extra: ListTableQueryChangeExtra<RecordType>) => void;
 /** 本地查询失败通知。 */
 interface ListTableQueryErrorInfo {
     /** 失败的查询动作。 */
@@ -1807,6 +2028,8 @@ interface ListTableExpandableOptions<RecordType = Record<string, unknown>> {
  * UI 适配层配置。
  */
 interface ListTableUiOptions {
+    /** 导出文件名输入弹窗；未提供时使用浏览器输入框。 */
+    onExportNameRequest?: (request: ListTableExportNameRequest | null) => void;
     editorFactory?: ListTableEditorFactory;
     paginationAdapter?: ListTablePaginationAdapter;
     onEditorRequest?: (request: ListTableEditorRequest | null) => void;
@@ -1821,6 +2044,10 @@ interface ListTableUiOptions {
     onDangerConfirmRequest?: (request: ListTableDangerConfirmRequest | null) => void;
     /** 持久化配置或内部操作改变表格密度时通知适配层。 */
     onDensityChange?: (density: 26 | 32 | 48 | 56 | "auto") => void;
+    /** 同步列设置缓存开关。 */
+    onColumnSettingsCacheChange?: (enabled: boolean) => void;
+    /** 同步各类配置的缓存偏好。 */
+    onCachePreferencesChange?: (preferences: ListTableCachePreferences) => void;
 }
 /**
  * 行选择器配置。
@@ -1844,6 +2071,11 @@ interface ListTableImagePreviewRequest {
  * 表格配置。
  */
 interface ListTableOptions<RecordType = Record<string, unknown>> {
+    /** 工具栏、实例与右键导出的默认文件名及弹窗开关。 */
+    exportOptions?: {
+        fileName?: string;
+        promptFileName?: boolean;
+    };
     type?: "list";
     rowKey?: TableColumnDataIndex | ((record: RecordType, index: number) => string | number);
     /**
@@ -1932,6 +2164,10 @@ interface ListTableOptions<RecordType = Record<string, unknown>> {
      * 分页尺寸单独保存到 localStorage，初始化时恢复；显式 pagination.pageSize 优先于缓存。
      */
     storageKey?: string;
+    /** 是否缓存列宽、显隐、固定与顺序，默认开启；需要 storageKey。 */
+    cacheColumnSettings?: boolean;
+    /** 分类缓存开关；不影响当前展示，只控制保存与刷新恢复。 */
+    cachePreferences?: ListTableCachePreferences;
     /**
      * 受控列设置的修订号。修订号变化时以当前传入的列配置为准并写回持久化存储。
      *
@@ -1977,9 +2213,11 @@ type ListTableDensity = 26 | 32 | 48 | 56 | "auto";
  * XLSX 导出参数。
  */
 interface ListTableExportXlsxOptions extends XlsxExportOptions {
+    /** 导出前输入文件名称，默认 true。 */
+    promptFileName?: boolean;
     /** 导出文件名，可省略 `.xlsx` 扩展名。 */
     fileName?: string;
-    /** 是否在数据末尾追加按当前列配置计算的汇总行。 */
+    /** 是否在数据末尾追加按当前列配置计算的汇总行，默认跟随表格汇总行的显示状态。 */
     includeSummary?: boolean;
     /** 导出失败通知；已保存的分文件不会撤回，取消不触发此回调。 */
     onError?: (error: unknown) => void;
@@ -2067,6 +2305,8 @@ declare class ListTable<RecordType = Record<string, unknown>> {
      * 设置并持久化内置表格密度。
      */
     changeDensity(density: ListTableDensity): void;
+    /** 设置列设置缓存开关，不改变当前列展示。 */
+    setColumnSettingsCache(enabled: boolean): void;
     /**
      * 销毁实例。
      */
@@ -2139,4 +2379,4 @@ interface ListTableValidationTarget {
     columnKey: string;
 }
 
-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 ListTableCSSProperties, 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 ListTablePaginationCSSProperties, type ListTablePaginationOptions, type ListTablePaginationStyleSlot, type ListTablePaginationStyles, 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 ListTableScrollbarCSSProperties, type ListTableScrollbarOptions, type ListTableSearchRequest, type ListTableSelectionState, type ListTableServerSummaryValues, type ListTableSortItem, type ListTableSortState, type ListTableSparklineChartCellContent, type ListTableSparklineSize, type ListTableStyles, 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, getListTableStoredPageSize, resetListTableStoredColumnConfig };
+export { type CreateCellEditorSessionParams, type DebugHitTestResult, EXPAND_COLUMN, type FilterPanelConfig, type FilterPanelOptionItem, type FilterPanelTexts, type FixedPopupConfig, type HeaderContextMenuColumnItem, type HeaderContextMenuConfig, type HeaderContextMenuDensity, ListTable, type ListTableAntdIconName, type ListTableAutoMergeRule, type ListTableBarcodeCellContent, type ListTableBarcodeFormat, type ListTableBuiltinIconName, type ListTableButtonCellContent, type ListTableButtonPopconfirmOptions, type ListTableButtonSize, type ListTableButtonType, type ListTableCSSProperties, type ListTableCacheCategory, type ListTableCachePreferences, type ListTableCarouselScrollOptions, type ListTableCellContent, type ListTableCellContentClickContext, type ListTableCellEditorSession, type ListTableCellSpan, type ListTableCellStyle, type ListTableChartCellContent, type ListTableChartSize, type ListTableChartType, type ListTableColorCellContent, type ListTableColumn, type ListTableConditionalFormatCondition, type ListTableConditionalFormatRule, type ListTableConditionalOperator, 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 ListTableExportNameRequest, 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 ListTableGaugeChartCellContent, 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 ListTablePaginationCSSProperties, type ListTablePaginationOptions, type ListTablePaginationStyleSlot, type ListTablePaginationStyles, type ListTablePerformanceMetric, type ListTablePieChartCellContent, type ListTableProgressCellContent, type ListTableProgressShape, type ListTableProgressSize, type ListTableQrCodeCellContent, type ListTableQrCodeLevel, type ListTableQueryChange, type ListTableQueryChangeExtra, type ListTableQueryFilters, type ListTableQueryOptions, type ListTableQueryPagination, type ListTableQuerySorter, type ListTableRadarChartCellContent, 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 ListTableScrollbarCSSProperties, type ListTableScrollbarOptions, type ListTableSearchRequest, type ListTableSelectionState, type ListTableServerSummaryValues, type ListTableSortItem, type ListTableSortState, type ListTableSorter, type ListTableSparklineChartCellContent, type ListTableSparklineSize, type ListTableStyles, type ListTableSummaryConfig, type ListTableSummaryRoundingMode, type ListTableSummaryType, type ListTableSymbolType, type ListTableTagCellContent, type ListTableTheme, type ListTableTimelineCellContent, type ListTableTimelineItem, type ListTableTooltipAdapter, type ListTableTooltipRequest, type ListTableTreeSelectNode, type ListTableUiOptions, type ListTableUploadConfig, type ListTableUploadFile, type ListTableUploadRequest, type ListTableValidationError, type ListTableValidationErrorField, type ListTableValidationFailure, type ListTableValidationTarget, type PaginationConfig, ROW_SELECTION_COLUMN, type RenderCellDescriptor, SELECTION_COLUMN, getListTableStoredPageSize, listTableAntdIconNames, listTableBuiltinIconNames, listTableIconNames, resetListTableStoredColumnConfig };