bw-pro-table 0.0.1

package/dist/types/types.d.ts

@@ -0,0 +1,567 @@
+import type { VNode } from 'vue';
+import type { TableColumnType, TablePaginationConfig } from 'ant-design-vue';
+import type { TableRowSelection, ExpandableConfig, GetRowKey } from 'ant-design-vue/es/table/interface';
+/** 排序方向 */
+export type SortOrder = 'ascend' | 'descend' | null;
+/** 筛选值类型 */
+export type FilterValue = (string | number)[] | null;
+/** 行 Key 类型 */
+export type Key = string | number;
+import type { CSSProperties } from 'vue';
+/** 支持的 valueType 预设值 */
+export type ValueType = 'text' | 'number' | 'date' | 'tag' | 'image' | 'link' | 'progress' | 'avatar' | 'action' | 'index' | 'currency' | 'boolean';
+/** valueEnum 映射定义 */
+export interface ValueEnumItem {
+    text: string;
+    status?: 'Success' | 'Processing' | 'Error' | 'Default' | 'Warning';
+    color?: string;
+}
+export type ValueEnumMap = Record<string | number, ValueEnumItem | string>;
+/** 列头搜索配置 */
+export interface HeaderSearchConfig {
+    /** 是否启用列头搜索（默认 false） */
+    enabled?: boolean;
+    /** 搜索框占位文本 */
+    placeholder?: string;
+    /** 搜索按钮文本 */
+    searchText?: string;
+    /** 重置按钮文本 */
+    resetText?: string;
+}
+/** ProColumn 类型 — 在 ant-design-vue TableColumnType 基础上扩展 ProTable 特有字段 */
+export interface ProColumnType<RecordType = any> extends Omit<TableColumnType<RecordType>, 'children'> {
+    /** 列类型预设值 */
+    valueType?: ValueType;
+    /** 枚举列的值映射 */
+    valueEnum?: ValueEnumMap;
+    /** 日期格式（valueType='date' 时生效） */
+    dateFormat?: string;
+    /** 小数精度（valueType='number'/'currency' 时生效） */
+    precision?: number;
+    /** 货币前缀符号 */
+    currencyPrefix?: string;
+    /** 货币后缀符号 */
+    currencySuffix?: string;
+    /** 空单元格占位符，覆盖全局配置 */
+    emptyText?: string;
+    /** 溢出策略 */
+    overflow?: 'ellipsis' | 'wrap' | 'clip';
+    /** 表头说明文字 */
+    description?: string;
+    /** 操作列按钮配置（valueType='action' 时生效） */
+    actions?: ActionItem<RecordType>[];
+    /** 图片宽度（valueType='image' 时生效） */
+    imageWidth?: number;
+    /** 图片高度（valueType='image' 时生效） */
+    imageHeight?: number;
+    /** 链接列配置（valueType='link' 时生效） */
+    linkProps?: {
+        href?: string;
+        target?: string;
+        onClick?: (record: RecordType, event: Event) => void;
+    };
+    /** 进度列配置（valueType='progress' 时生效） */
+    progressProps?: {
+        strokeColor?: string;
+    };
+    /** 头像列配置（valueType='avatar' 时生效） */
+    avatarProps?: {
+        srcField?: string;
+        nameField?: string;
+        showName?: boolean;
+        size?: number;
+        shape?: 'circle' | 'square';
+    };
+    /** 布尔列使用 Switch 开关 */
+    booleanSwitch?: boolean;
+    /** 列级表单校验规则 */
+    formRules?: FormRule[];
+    /** 列级权限标识 */
+    authority?: string | string[];
+    /** 是否可编辑 */
+    editable?: boolean | ((record: RecordType) => boolean);
+    /** 编辑态组件类型 */
+    editComponent?: string;
+    /** 编辑态组件的额外 props */
+    editComponentProps?: Record<string, any>;
+    /** 子列 */
+    children?: ProColumnsType<RecordType>;
+    /** 是否隐藏该列 */
+    hidden?: boolean;
+    /** 列所属分组 */
+    columnGroup?: string;
+    /** 列头搜索配置（true 或 HeaderSearchConfig 对象启用；仅对 valueType='text' 生效） */
+    headerSearch?: boolean | HeaderSearchConfig;
+    /** 自定义搜索栏表单渲染器。若提供则优先于 valueType 自动匹配，允许任意表单控件。
+     * 示例：
+     * ```ts
+     * {
+     *   title: '状态',
+     *   dataIndex: 'status',
+     *   valueType: 'customStatus' as any,
+     *   renderFormItem: ({ model, search }) => {
+     *     return h(aSelect, {
+     *       value: model.status,
+     *       'onUpdate:value': (v) => { model.status = v; search(); },
+     *     });
+     *   },
+     * }
+     * ```
+     */
+    renderFormItem?: (context: {
+        /** 当前搜索表单 model（可直接读写） */
+        model: Record<string, any>;
+        /** 触发搜索 */
+        search: () => void;
+        /** 清除指定字段值 */
+        resetField: (dataIndex: string) => void;
+    }) => VNode;
+}
+/** 操作列按钮项 */
+export interface ActionItem<RecordType = any> {
+    label: string;
+    type?: 'primary' | 'dashed' | 'link' | 'text' | 'default';
+    /** 危险操作样式，对应 ant-design-vue Button 的 danger 属性 */
+    danger?: boolean;
+    icon?: string;
+    confirm?: string;
+    authority?: string | string[];
+    disabled?: boolean | ((record: RecordType) => boolean);
+    hidden?: boolean | ((record: RecordType) => boolean);
+    onClick?: (record: RecordType, index: number) => void | Promise<void>;
+}
+export type ProColumnsType<RecordType = any> = ProColumnType<RecordType>[];
+export interface FormRule {
+    required?: boolean;
+    message?: string;
+    type?: 'string' | 'number' | 'boolean' | 'email' | 'url';
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+    validator?: (value: any, record: any) => Promise<void> | void;
+}
+export interface EditConfig<RecordType = any> {
+    /** 编辑模式 */
+    mode?: 'cell' | 'row';
+    /** 新增行时的默认值 */
+    newRecord?: Partial<RecordType>;
+    /** 编辑前回调 */
+    onEditStart?: (record: RecordType, field?: string) => Promise<boolean> | boolean;
+    /** 保存回调 */
+    onSave?: (record: RecordType, isNew: boolean) => Promise<void> | void;
+    /** 删除回调 */
+    onDelete?: (keys: (string | number)[]) => Promise<void> | void;
+    /** 是否允许新增 */
+    addable?: boolean;
+    /** 是否允许删除 */
+    deletable?: boolean;
+}
+/** 撤销/重做 Command */
+export interface EditCommand<RecordType = any> {
+    type: 'update' | 'add' | 'delete';
+    rowKey: string | number;
+    field?: string;
+    oldValue?: any;
+    newValue?: any;
+    record?: RecordType;
+    /** 行在 dataSource 中的原始索引（delete/undo 恢复位置用） */
+    index?: number;
+}
+export interface ContextMenuItem {
+    key: string;
+    label: string;
+    icon?: string;
+    disabled?: boolean;
+    danger?: boolean;
+    children?: ContextMenuItem[];
+}
+export type ContextMenuType = 'row' | 'cell' | 'header';
+export interface ContextMenuConfig {
+    /** 行右键菜单项 */
+    row?: ContextMenuItem[];
+    /** 单元格右键菜单项 */
+    cell?: ContextMenuItem[];
+    /** 表头右键菜单项 */
+    header?: ContextMenuItem[];
+}
+export interface ViewConfig {
+    id?: string;
+    name: string;
+    tableId: string;
+    isDefault: boolean;
+    columns: {
+        key: string;
+        checked: boolean;
+        order: number;
+        width?: number;
+    }[];
+    filterState: Record<string, FilterValue | null>;
+    sortState: {
+        field: string;
+        order: SortOrder;
+    } | null;
+    pageSize: number;
+}
+export interface DragConfig {
+    /** 允许行拖拽 */
+    rowDraggable?: boolean;
+    /** 允许列拖拽 */
+    columnDraggable?: boolean;
+    /** 拖拽范围约束 */
+    dragConstraint?: 'same-table' | 'cross-table';
+    /** 拖拽回调 */
+    onRowDragEnd?: (fromIndex: number, toIndex: number) => void;
+    /** 跨表格拖拽回调 */
+    onCrossTableDrop?: (record: any, targetTableId: string) => void;
+}
+export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'greaterThan' | 'lessThan' | 'between' | 'in' | 'isEmpty' | 'isNotEmpty';
+export interface AdvancedFilterCondition {
+    id: string;
+    field: string;
+    operator: FilterOperator;
+    value: any;
+    valueEnd?: any;
+    logic?: 'AND' | 'OR';
+}
+export interface AdvancedFilterGroup {
+    id: string;
+    logic: 'AND' | 'OR';
+    conditions: AdvancedFilterCondition[];
+    groups?: AdvancedFilterGroup[];
+}
+export interface ExportConfig {
+    /** 导出文件名 */
+    filename?: string;
+    /** 分片大小 */
+    chunkSize?: number;
+    /** 最大导出行数 */
+    maxRows?: number;
+    /** 导出选项 */
+    type?: 'xlsx' | 'csv';
+    /** 自定义列映射 */
+    columnMapping?: Record<string, string>;
+    /** 导出前回调 */
+    beforeExport?: () => Promise<boolean> | boolean;
+}
+export interface ImportConfig {
+    /** 列映射 */
+    columnMapping?: Record<string, string>;
+    /** 校验规则 */
+    validateRules?: FormRule[];
+    /** 导入前回调 */
+    beforeImport?: (data: any[]) => Promise<any[]> | any[];
+    /** 导入回调 */
+    onImport?: (data: any[]) => Promise<void> | void;
+}
+/** 跨页多选配置 */
+export interface CrossPageSelectionConfig {
+    /** 是否启用跨页多选（默认 false） */
+    enabled?: boolean;
+    /** 选择所有页回调（Request 模式下必需），接收当前搜索/筛选/排序参数，返回所有匹配数据的主键数组 */
+    onSelectAllPages?: (searchParams: Record<string, any>) => Promise<(string | number)[]> | (string | number)[];
+    /** 最大选择数量上限（0 表示不限制） */
+    maxSelectCount?: number;
+}
+/**
+ * BwProTable 语言包接口。
+ * 与 locales/zh-CN.ts 结构对齐，外部可通过覆盖任意字段实现国际化。
+ */
+export interface BwProTableLocale {
+    search: {
+        reset: string;
+        search: string;
+        expand: string;
+        collapse: string;
+        placeholder: string;
+        selectPlaceholder: string;
+        datePlaceholder: string;
+        inputPlaceholder: string;
+        selectPlaceholderWithTitle: string;
+    };
+    toolbar: {
+        refresh: string;
+        density: string;
+        densityDefault: string;
+        densityMiddle: string;
+        densitySmall: string;
+        fullscreen: string;
+        exitFullscreen: string;
+        columnSetting: string;
+        export: string;
+        clearFilter: string;
+        search: string;
+        border: string;
+        striped: string;
+        on: string;
+        off: string;
+        selected: string;
+        clearSelection: string;
+    };
+    table: {
+        total: string;
+        emptyText: string;
+        triggerAsc: string;
+        triggerDesc: string;
+        cancelSort: string;
+        paginationTotal: string;
+    };
+    columnSetting: {
+        title: string;
+        reset: string;
+        apply: string;
+        cancel: string;
+    };
+    edit: {
+        save: string;
+        cancel: string;
+        delete: string;
+        confirmDelete: string;
+        add: string;
+        batchEdit: string;
+        undo: string;
+        redo: string;
+        pleaseSelectField: string;
+        modifyField: string;
+        modifyValue: string;
+        selectedData: string;
+        placeholder: string;
+        selectPlaceholder: string;
+        validation: {
+            required: (field: string) => string;
+            number: (field: string) => string;
+            min: (field: string, min: number) => string;
+            max: (field: string, max: number) => string;
+            pattern: (field: string) => string;
+        };
+    };
+    /** @deprecated 使用 locale.export 代替 */
+    export: {
+        excel: string;
+        csv: string;
+        selected: string;
+        success: string;
+        failed: string;
+        noData: string;
+        tooLarge: (count: number) => string;
+        selectFirst: string;
+    };
+    import: {
+        title: string;
+        selectFile: string;
+        preview: string;
+        columnMapping: string;
+        confirm: string;
+        cancel: string;
+        success: (count: number) => string;
+        failed: string;
+        template: string;
+        parseError: string;
+        emptyFile: string;
+        emptyValueField: string;
+    };
+    contextMenu: {
+        noActions: string;
+        view: string;
+        edit: string;
+        copy: string;
+        clone: string;
+        delete: string;
+        copyCell: string;
+        filterByCell: string;
+        sortAsc: string;
+        sortDesc: string;
+        hideColumn: string;
+        pinLeft: string;
+        pinRight: string;
+        autoSize: string;
+    };
+    view: {
+        save: string;
+        load: string;
+        delete: string;
+        setDefault: string;
+        name: string;
+        saved: string;
+        deleted: string;
+        switched: (name: string) => string;
+        enterName: string;
+        exists: string;
+        overWrite: (name: string) => string;
+    };
+    error: {
+        loadFailed: string;
+        retry: string;
+        required: (field: string) => string;
+        formatError: (field: string) => string;
+    };
+    selection: {
+        selectAllPages: string;
+        clearAll: string;
+        selectCurrentPage: string;
+        invertCurrentPage: string;
+        selectedCount: (n: number) => string;
+        clear: string;
+    };
+    filter: {
+        title: string;
+        equals: string;
+        notEquals: string;
+        contains: string;
+        greaterThan: string;
+        lessThan: string;
+        between: string;
+        isEmpty: string;
+        isNotEmpty: string;
+        field: string;
+        condition: string;
+        value: string;
+        startValue: string;
+        endValue: string;
+        addCondition: string;
+        reset: string;
+        apply: string;
+        and: string;
+        or: string;
+    };
+    boolean: {
+        true: string;
+        false: string;
+        placeholder: string;
+    };
+}
+export interface BwProTableProps<RecordType = any> {
+    /** 表格唯一标识，用于持久化命名空间 */
+    tableId?: string;
+    /** 列定义 */
+    columns: ProColumnsType<RecordType>;
+    /** 数据请求函数 */
+    request?: (params: {
+        current: number;
+        pageSize: number;
+        [key: string]: any;
+    }) => Promise<{
+        data: RecordType[];
+        total: number;
+        success: boolean;
+    }>;
+    /** 静态数据源（与 request 二选一） */
+    dataSource?: RecordType[];
+    /** 行 key 属性 */
+    rowKey?: string | GetRowKey<RecordType>;
+    /** 搜索栏配置 */
+    search?: false | {
+        labelWidth?: number;
+        defaultCollapsed?: boolean;
+        resetText?: string;
+        searchText?: string;
+        collapsedCount?: number;
+    };
+    /** 列头搜索全局配置（false 禁用所有列的 headerSearch，对象覆写默认值） */
+    columnSearch?: false | HeaderSearchConfig;
+    /** 工具栏配置 */
+    toolbar?: false | {
+        refresh?: boolean;
+        density?: boolean;
+        fullscreen?: boolean;
+        columnSetting?: boolean;
+        export?: boolean | ExportConfig;
+        clearFilter?: boolean;
+        import?: boolean | ImportConfig;
+        viewManager?: boolean;
+    };
+    /** 编辑配置 */
+    editConfig?: EditConfig<RecordType>;
+    /** 右键菜单配置 */
+    contextMenu?: ContextMenuConfig;
+    /** 拖拽配置 */
+    dragConfig?: DragConfig;
+    /** 表格标题 */
+    title?: string;
+    /** 表格边框 */
+    bordered?: boolean;
+    /** 斑马纹 */
+    striped?: boolean;
+    /** 表格尺寸 */
+    size?: 'small' | 'middle' | 'default';
+    /** 空单元格占位符 */
+    defaultEmptyText?: string;
+    /** 列配置缓存标识 */
+    cacheKey?: string;
+    /** 持久化配置（false 表示禁用） */
+    persistence?: false | PersistenceConfig;
+    /** 语言包（覆盖默认中文文案），传入部分字段即可完成局部覆写 */
+    locale?: Partial<BwProTableLocale>;
+    /** 加载态 */
+    loading?: boolean;
+    /** 分页配置 */
+    pagination?: false | TablePaginationConfig;
+    /** 行选择 */
+    rowSelection?: TableRowSelection<RecordType>;
+    /** 跨页多选配置（false 表示禁用） */
+    crossPageSelection?: false | CrossPageSelectionConfig;
+    /** 可展开行 */
+    expandable?: ExpandableConfig<RecordType>;
+    /** 滚动 */
+    scroll?: {
+        x?: number | string | true;
+        y?: number | string;
+    };
+    /** 固定表头 */
+    sticky?: boolean | {
+        offsetHeader?: number;
+    };
+    /** 表格 CSS 类名 */
+    class?: string;
+    /** 表格样式 */
+    style?: CSSProperties;
+}
+export type TableStatus = 'loading' | 'success' | 'error';
+export interface TableState {
+    status: TableStatus;
+    errorMessage: string;
+    errorReload: null | (() => void | Promise<void>);
+}
+export interface PersistedColumnState {
+    key: string;
+    checked: boolean;
+    order: number;
+    width?: number;
+}
+/** 当前持久化数据版本（已迁移到 constants.ts，保留向后兼容 re-export） */
+export { PERSISTED_DATA_VERSION } from './constants';
+export interface PersistedTableState {
+    /** 数据版本号，用于版本迁移 */
+    version: string;
+    tableId: string;
+    columns: PersistedColumnState[];
+    pageSize: number;
+    /** 当前页码 */
+    current?: number;
+    density?: 'small' | 'middle' | 'default';
+    /** 筛选状态 */
+    filters?: Record<string, FilterValue | null>;
+    /** 排序状态 */
+    sorter?: {
+        field: string;
+        order: SortOrder;
+    } | null;
+}
+/** 自定义存储适配器接口 */
+export interface StorageAdapter {
+    get: (key: string) => PersistedTableState | null;
+    set: (key: string, value: PersistedTableState) => void;
+    remove: (key: string) => void;
+}
+/** 持久化配置 */
+export interface PersistenceConfig {
+    /** 是否启用持久化（默认 true） */
+    enabled?: boolean;
+    /** 存储方式 */
+    storage?: 'localStorage' | 'sessionStorage' | StorageAdapter;
+    /** 键名前缀（默认 bw-pro-table） */
+    keyPrefix?: string;
+    /** 存储失败回调 */
+    onError?: (error: Error, operation: 'get' | 'set' | 'remove') => void;
+    /** 是否启用调试模式（默认 false），调试模式下输出详细日志 */
+    debug?: boolean;
+}