@aimerthyr/virtual-table 1.0.0 → 1.1.1

package/dist/index.d.ts

@@ -4,7 +4,6 @@ import { ColumnFiltersState } from '@tanstack/vue-table';
 import { ColumnPinningState } from '@tanstack/vue-table';
 import { ColumnSizingState } from '@tanstack/vue-table';
 import { ComponentCustomProps } from 'vue';
-import { CSSProperties } from 'vue';
 import { ExpandedState } from '@tanstack/vue-table';
 import { HTMLAttributes } from 'vue';
 import { PaginationState } from '@tanstack/vue-table';
@@ -43,7 +42,7 @@ declare const _default: <TData extends VTableData>(__VLS_props: NonNullable<Awai
         defaultColumnPinning?: ColumnPinningState;
         defaultColumnSizing?: ColumnSizingState;
     } & VTableProps<TData>) & Partial<{}>> & PublicProps;
-    expose(exposed: ShallowUnwrapRef<VTableInstance>): void;
+    expose(exposed: ShallowUnwrapRef<VTableInstance<TData>>): void;
     attrs: any;
     slots: any;
     emit: ((evt: "update:defaultFilter", value: ColumnFiltersState) => void) & ((evt: "update:defaultSort", value: SortingState) => void) & ((evt: "update:defaultPagination", value: PaginationState) => void) & ((evt: "update:defaultExpanded", value: ExpandedState) => void) & ((evt: "update:defaultSelection", value: RowSelectionState) => void) & ((evt: "update:defaultColumnPinning", value: ColumnPinningState) => void) & ((evt: "update:defaultColumnSizing", value: ColumnSizingState) => void);
@@ -53,6 +52,9 @@ declare const _default: <TData extends VTableData>(__VLS_props: NonNullable<Awai
 export { _default as VTable }
 export default _default;
 
+/** 默认主题配置 */
+export declare const defaultThemeConfig: VTableThemeConfig;
+
 /** 展开列 */
 export declare const EXPAND_COLUMN_KEY = "EXPAND_COLUMN_KEY";
 
@@ -62,24 +64,46 @@ export declare const EXPAND_ROW_DATA_INDEX = "_expandChildren";
 /** 是否是展开行 */
 export declare const EXPAND_ROW_KEY = "_isExpandRow";
 
-/** 表格默认样式 */
-export declare const TABLE_DEFAULT_STYLE: CSSProperties;
+export declare interface VTableBodyCellProps<TData = any> {
+    columnKey: string;
+    column: VTableColumn;
+    row: TData;
+    rowIndex: number;
+}
+
+/** 表体样式配置 */
+export declare interface VTableBodyStyle {
+    /** 表体字体颜色 */
+    color: string;
+    /** 表体背景颜色 */
+    backgroundColor: string;
+    /** 表体内边距 */
+    padding: number;
+}
 
-export declare type VTableBorderConfig = {
+export declare interface VTableBorderConfig {
     /** 是否显示边框 */
     enabled?: boolean;
     /** 边框样式 */
     borderStyle?: 'solid' | 'dashed';
     /** 边框颜色 */
     borderColor?: string;
-};
+}
+
+/** 边框样式配置 */
+export declare interface VTableBorderStyle {
+    /** 边框样式 */
+    borderStyle: 'solid' | 'dashed';
+    /** 边框颜色 */
+    borderColor: string;
+}
 
 /** 表格状态（分页，排序，筛选） */
-export declare type VTableChangeState = {
+export declare interface VTableChangeState {
     pagination: VTablePaginationState;
     sortList: VTableSortingState;
     filterList: VTableColumnFiltersState;
-};
+}
 
 /**
  * Checkbox 自定义组件接口定义
@@ -117,14 +141,19 @@ export declare interface VTableColumn<TData = any> {
     columnMaxWidth?: number;
     /** 列宽最小值 (默认 50px) */
     columnMinWidth?: number;
-    /** 可自行拓展字段 */
-    [key: string]: any;
+    /** 子列（用于表头分组） */
+    columnChildren?: VTableColumn<TData>[];
 }
 
+/** 筛选状态 */
 export declare type VTableColumnFiltersState = ColumnFiltersState;
 
+/** 固定列状态 */
 export declare type VTableColumnPinningState = ColumnPinningState;
 
+/** 列宽状态 */
+export declare type VTableColumnSizingState = ColumnSizingState;
+
 export declare type VTableData<T = Record<string, any>> = T & {
     /** 当前行是否展开 */
     [EXPAND_ROW_KEY]?: boolean;
@@ -141,7 +170,7 @@ export declare const vTableDefaultProps: {
     loading?: boolean | ((props: VTableProps<any>) => boolean) | undefined;
     fixedHeader?: boolean | ((props: VTableProps<any>) => boolean) | undefined;
     enableSortingRemoval?: boolean | ((props: VTableProps<any>) => boolean) | undefined;
-    borderConfig?: ((props: VTableProps<any>) => VTableBorderConfig) | undefined;
+    bordered?: boolean | ((props: VTableProps<any>) => boolean) | undefined;
     rowSelectionConfig?: ((props: VTableProps<any>) => VTableRowSelectionConfig<any>) | undefined;
     loadMoreConfig?: ((props: VTableProps<any>) => VTableLoadMoreConfig) | undefined;
     paginationConfig?: ((props: VTableProps<any>) => VTablePaginationConfig) | undefined;
@@ -151,31 +180,61 @@ export declare const vTableDefaultProps: {
     adaptiveColumnWidth?: number | ((props: VTableProps<any>) => number) | undefined;
     defaultExpandAllRows?: boolean | ((props: VTableProps<any>) => boolean) | undefined;
     columnResizeMode?: "onChange" | "onEnd" | ((props: VTableProps<any>) => "onChange" | "onEnd") | undefined;
-    customRow?: ((row: any, rowIndex: number) => HTMLAttributes) | ((props: VTableProps<any>) => (row: any, rowIndex: number) => HTMLAttributes) | undefined;
-    customHeaderCell?: ((column: VTableColumn, colIndex: number) => ThHTMLAttributes) | ((props: VTableProps<any>) => (column: VTableColumn, colIndex: number) => ThHTMLAttributes) | undefined;
-    customCell?: ((column: VTableColumn, colIndex: number) => TdHTMLAttributes) | ((props: VTableProps<any>) => (column: VTableColumn, colIndex: number) => TdHTMLAttributes) | undefined;
+    fixedFooter?: boolean | ((props: VTableProps<any>) => boolean) | undefined;
+    themeConfig?: ((props: VTableProps<any>) => VTableThemeConfig) | undefined;
+    defaultCheckboxColumnWidth?: number | ((props: VTableProps<any>) => number) | undefined;
+    defaultExpandColumnWidth?: number | ((props: VTableProps<any>) => number) | undefined;
+    customRowAttributes?: ((row: any, rowIndex: number) => HTMLAttributes) | ((props: VTableProps<any>) => (row: any, rowIndex: number) => HTMLAttributes) | undefined;
+    customHeaderCellAttributes?: ((column: VTableColumn, colIndex: number) => ThHTMLAttributes) | ((props: VTableProps<any>) => (column: VTableColumn, colIndex: number) => ThHTMLAttributes) | undefined;
+    customCellAttributes?: ((row: any, column: VTableColumn, rowIndex: number, colIndex: number) => TdHTMLAttributes | null) | ((props: VTableProps<any>) => (row: any, column: VTableColumn, rowIndex: number, colIndex: number) => TdHTMLAttributes | null) | undefined;
     onTableChange?: ((data: VTableChangeState) => void) | ((props: VTableProps<any>) => (data: VTableChangeState) => void) | undefined;
     onScrollToBottom?: (() => void) | ((props: VTableProps<any>) => () => void) | undefined;
     onExpandedRowsChange?: ((expandState: VTableExpandedState) => void) | ((props: VTableProps<any>) => (expandState: VTableExpandedState) => void) | undefined;
+    onColumnSizingChange?: ((columnSizing: VTableColumnSizingState) => void) | ((props: VTableProps<any>) => (columnSizing: VTableColumnSizingState) => void) | undefined;
 };
 
+/** 展开状态 */
 export declare type VTableExpandedState = ExpandedState;
 
+/** 展开图标自定义组件接口定义 */
+export declare interface VTableExpandIconProps {
+    expand: boolean;
+    onExpandChange: () => void;
+}
+
+/** 表头样式配置 */
+export declare interface VTableHeaderStyle {
+    /** 表头字体颜色 */
+    color: string;
+    /** 表头背景颜色 */
+    backgroundColor: string;
+    /** 表头圆角大小 */
+    borderRadius: number;
+    /** 表头分割线颜色 */
+    splitColor: string;
+    /** 表头图标颜色 */
+    headerIconColor: string;
+    /** 表头内边距 */
+    padding: number;
+}
+
 /** VTable 实例类型定义 */
-export declare interface VTableInstance {
-    /** 滚动到指定行 */
-    scrollToIndex: (index: number) => void;
+export declare interface VTableInstance<TData = any> {
+    /** tanstack 表格实例 */
+    tanstackTable: Table<TData>;
+    /** 滚动到指定下标(从 0 开始，默认是平滑滚动) */
+    scrollToIndex: (index: number, behavior?: 'auto' | 'smooth') => void;
 }
 
-export declare type VTableLoadMoreConfig = {
+export declare interface VTableLoadMoreConfig {
     /** 是否显示"没有更多了"提示 */
     showNoMore?: boolean;
     /** 自定义"没有更多了"文本 */
     noMoreText?: string;
-};
+}
 
-export declare type VTablePaginationConfig = {
-    /** 总数（必须要传） */
+export declare interface VTablePaginationConfig {
+    /** 总数（必须要传, 客户端分页可以不传，自动以传入的 data 长度作为总数） */
     total: number;
     /** 是否开启分页 */
     enabled?: boolean;
@@ -185,7 +244,7 @@ export declare type VTablePaginationConfig = {
     mode?: 'client' | 'server';
     /** 分页器额外属性（如果你自己定义了分页器组件，则用于回传给你自己定义的组件） */
     paginationExtraProps?: Record<string, any>;
-};
+}
 
 /**
  * Pagination 自定义组件接口定义
@@ -201,6 +260,7 @@ export declare interface VTablePaginationProps {
     onPageChange: (pageIndex: number, pageSize: number) => void;
 }
 
+/** 分页状态 */
 export declare type VTablePaginationState = PaginationState;
 
 /**
@@ -233,8 +293,8 @@ export declare interface VTableProps<TData = any> {
     fixedHeader?: boolean;
     /** 是否允许取消排序 */
     enableSortingRemoval?: boolean;
-    /** 边框样式配置 */
-    borderConfig?: VTableBorderConfig;
+    /** 是否显示边框 */
+    bordered?: boolean;
     /** 选择行功能配置 */
     rowSelectionConfig?: VTableRowSelectionConfig<TData>;
     /** 加载更多配置 */
@@ -245,7 +305,7 @@ export declare interface VTableProps<TData = any> {
     treeConfig?: VTableTreeConfig;
     /** 是否启用展开行功能 */
     enableExpandRow?: boolean;
-    /** 是否启用 行 hover 高亮 */
+    /** 是否启用行 hover 高亮 */
     enableRowHover?: boolean;
     /** 自适应列宽（当列数很多时，会出现横向滚动条，那么就需要设置自适应列的最小列宽） */
     adaptiveColumnWidth?: number;
@@ -253,60 +313,69 @@ export declare interface VTableProps<TData = any> {
     defaultExpandAllRows?: boolean;
     /** 列宽调整模式 */
     columnResizeMode?: 'onChange' | 'onEnd';
+    /** 是否固定表尾（表尾不随着滚动） */
+    fixedFooter?: boolean;
+    /** 自定义主题配置（可覆盖默认配置） */
+    themeConfig?: VTableThemeConfig;
+    /** 默认 checkbox 列宽 */
+    defaultCheckboxColumnWidth?: number;
+    /** 默认展开列的列宽 */
+    defaultExpandColumnWidth?: number;
     /** 自定义数据行属性 */
-    customRow?: (row: TData, rowIndex: number) => HTMLAttributes;
+    customRowAttributes?: (row: TData, rowIndex: number) => HTMLAttributes;
     /** 自定义表头单元格属性 */
-    customHeaderCell?: (column: VTableColumn, colIndex: number) => ThHTMLAttributes;
-    /** 自定义表体单元格属性 */
-    customCell?: (column: VTableColumn, colIndex: number) => TdHTMLAttributes;
+    customHeaderCellAttributes?: (column: VTableColumn, colIndex: number) => ThHTMLAttributes;
+    /**
+     * 自定义表体单元格属性（包括合并单元格）
+     * 当返回的属性中 colspan 或 rowspan 为 0 时，该单元格不会被渲染
+     */
+    customCellAttributes?: (row: TData, column: VTableColumn, rowIndex: number, colIndex: number) => TdHTMLAttributes | null;
     /** 表格状态变化（筛选，排序，分页） */
     onTableChange?: (data: VTableChangeState) => void;
     /** 滚动到表格底部 */
     onScrollToBottom?: () => void;
     /** 展开行变化回调 */
     onExpandedRowsChange?: (expandState: VTableExpandedState) => void;
+    /** 列宽调整回调 */
+    onColumnSizingChange?: (columnSizing: VTableColumnSizingState) => void;
 }
 
 export declare type VTableRowKey<TData> = string | number | ((row: TData) => string | number);
 
-export declare type VTableRowSelectionConfig<TData> = {
+export declare interface VTableRowSelectionConfig<TData> {
     /** 是否开启 checkbox 列 */
     enabled?: boolean;
     /** 判断该行是否禁用选择 */
     getRowCheckDisabled?: (row: TData) => boolean;
     /** 选择行变化回调 */
     onChange?: (selectedRows: TData[]) => void;
-};
+}
 
+/** 选择状态 */
 export declare type VTableSelectionState = RowSelectionState;
 
 /** slots 类型定义 */
 export declare interface VTableSlots<TData = any> {
     /** 自定义头部渲染 */
-    customHeader?: (data: {
+    customHeader?: (props: {
         columns: VTableColumn[];
         table: Table<TData>;
     }) => VNode_2;
     /** 自定义单元格 */
-    bodyCell?: (data: {
-        columnKey: string;
-        column: VTableColumn;
-        row: TData;
-        rowIndex: number;
-    }) => VNode_2;
+    bodyCell?: (props: VTableBodyCellProps<TData>) => VNode_2;
     /** 自定义列头 */
-    headerCell?: (data: {
+    headerCell?: (props: {
         columnKey: string;
         column: VTableColumn;
     }) => VNode_2;
     /** 自定义筛选图标 */
-    customFilterIcon?: (data: {
+    customFilterIcon?: (props: {
         columnKey: string;
         filtered: boolean;
         column: VTableColumn;
     }) => VNode_2;
     /** 自定义筛选下拉 */
-    customFilterDropdown?: (data: {
+    customFilterDropdown?: (props: {
         confirm: () => void;
         reset: () => void;
         setFilterValue: (value: any) => void;
@@ -314,16 +383,11 @@ export declare interface VTableSlots<TData = any> {
         filterModelValue: any;
     }) => VNode_2;
     /** 自定义展开行 */
-    expandedRowRender?: (data: {
+    expandedRowRender?: (props: {
         row: TData;
     }) => VNode_2;
     /** 自定义 Popover */
-    customPopover?: (props: {
-        open: boolean;
-        onOpenChange: (value: boolean) => void;
-        trigger: () => VNode_2;
-        content: () => VNode_2;
-    }) => VNode_2;
+    customPopover?: (props: VTablePopoverProps) => VNode_2;
     /** 自定义分页器 */
     customPagination?: (props: VTablePaginationProps) => VNode_2;
     /** 自定义 checkbox */
@@ -332,18 +396,58 @@ export declare interface VTableSlots<TData = any> {
     customEmpty?: () => VNode_2;
     /** 自定义 loading 图标 */
     customLoadingIcon?: () => VNode_2;
+    /** 自定义加载没有更多区域 */
+    customLoadNoMore?: () => VNode_2;
+    /** 自定义表尾 */
+    customFooter?: () => VNode_2;
+    /** 自定义展开图标 */
+    customExpandIcon?: (props: VTableExpandIconProps) => VNode_2;
+    /** 自定义组件图标 */
+    customSorterIcon?: (props: VTableSorterIconProps) => VNode_2;
     [key: string]: ((...args: any[]) => VNode_2) | undefined;
 }
 
+/** 排序图标自定义组件接口定义 */
+export declare interface VTableSorterIconProps {
+    sort: 'asc' | 'desc' | null;
+}
+
+/** 排序状态 */
 export declare type VTableSortingState = SortingState;
 
-export declare type VTableTreeConfig = {
+/** 表格主题配置 */
+export declare interface VTableThemeConfig {
+    /** 主色 */
+    primaryColor?: string;
+    /** 表头样式 */
+    header?: Partial<VTableHeaderStyle>;
+    /** 表体样式 */
+    body?: Partial<VTableBodyStyle>;
+    /** 边框样式 */
+    border?: Partial<VTableBorderStyle>;
+    /** 行 hover 颜色 */
+    rowHoverColor?: string;
+    /** z-index 层级配置 */
+    zIndex?: VTableZIndexConfig;
+}
+
+export declare interface VTableTreeConfig {
     /** 是否启用树形结构 */
     enabled?: boolean;
     /** 子节点字段名，默认为 'children' */
     childrenKey?: string;
     /** 缩进距离 */
     indentSize?: number;
-};
+}
+
+/** z-index 层级配置 */
+export declare interface VTableZIndexConfig {
+    /** 固定列（左右固定） */
+    pinnedColumn?: number;
+    /** 固定表头 */
+    fixedHeader?: number;
+    /** 固定表尾 */
+    fixedFooter?: number;
+}
 
 export { }