@zat-design/sisyphus-react 4.5.5 → 4.5.6-beta.2

package/es/ProTable/propsType.d.ts

@@ -0,0 +1,805 @@
+import { Key, ReactNode } from 'react';
+import type { TableProps, TooltipProps } from 'antd';
+import { NamePath } from 'antd/es/form/interface';
+import { FormInstance } from 'antd/es/form/Form';
+import { ColumnType, GetRowKey, RowSelectionType } from 'antd/es/table/interface';
+import type { TabsProps } from 'antd/es/tabs';
+import type { SegmentedProps } from 'antd/es/segmented';
+import type { ProFormColumnType } from '../ProForm/components/render/propsType';
+/**
+ * 单元格行内编辑时 onBlur 的回调函数类型
+ */
+export type TableOnBlurFn = (value: any, record: any, index: number) => void | Promise<void>;
+/**
+ * 单元格行内编辑配置
+ */
+export type EditTableCellConfig<Values = any> = Omit<ProFormColumnType<Values>, 'name' | 'label' | 'names' | 'fieldProps'> & {
+    fieldProps?: {
+        onBlur?: TableOnBlurFn;
+        [key: string]: any;
+    };
+};
+/**
+ * 合计栏的每列配置参数
+ */
+export interface ProTableSummaryColumnType {
+    /**
+     * 配置列的 key
+     * @description 对应表格列的 key
+     * @default undefined
+     */
+    key?: string | string[];
+    /**
+     * 配置列的 dataIndex
+     * @description 对应表格列的 dataIndex
+     * @default undefined
+     */
+    dataIndex?: string | string[];
+    /**
+     * 配置列的下标
+     * @description 列在表格中的索引位置
+     * @default undefined
+     */
+    index: number;
+    /**
+     * 配置列的自定义文本
+     * @description 自定义显示的文本内容
+     * @default undefined
+     */
+    title?: string;
+    /**
+     * 配置列的跨度
+     * @description 占表格的几列
+     * @default undefined
+     */
+    colSpan?: number;
+    /**
+     * 同可编辑表格类型
+     * @description 快捷转换数字类型
+     * @default undefined
+     */
+    valueType?: string;
+    /**
+     * 数字精度
+     * @description 小数点后保留的位数
+     * @default undefined
+     */
+    precision?: number;
+    /**
+     * 自定义前缀
+     * @description 显示在值前面的文本或节点
+     * @default undefined
+     */
+    prefix?: ReactNode | string;
+    /**
+     * 自定义后缀
+     * @description 显示在值后面的文本或节点
+     * @default undefined
+     */
+    suffix?: ReactNode | string;
+}
+/**
+ * 合计栏的配置参数
+ */
+export interface ProTableSummaryType {
+    /**
+     * 每列的配置信息
+     * @description 配置合计栏中每一列的展示方式
+     * @default []
+     */
+    columns: ProTableSummaryColumnType[];
+    /**
+     * 是否开启自动计算
+     * @description 启用后将自动计算列值的总和
+     * @default true
+     */
+    total?: boolean;
+    /**
+     * 合计栏位置
+     * @description 控制合计栏的固定位置
+     * @default true
+     */
+    fixed?: boolean;
+}
+/**
+ * ProTable 列定义
+ */
+export interface ProTableColumnType extends Omit<ColumnType<any>, 'dataIndex'> {
+    /**
+     * 列数据在数据项中对应的路径
+     * @description 支持通过数组表示嵌套路径
+     * @default undefined
+     */
+    dataIndex?: string | string[];
+    /**
+     * 列宽度
+     * @description 设置列的宽度
+     * @default undefined
+     */
+    width?: number | string;
+    /**
+     * 列最小宽度
+     * @description 透传至 antd Table column.minWidth（antd 5.21+），用于 tableLayout='auto' 下计算最小列宽；同时作为列宽拖拽下限
+     * @default undefined
+     */
+    minWidth?: number;
+    /**
+     * 值类型
+     * @description 快捷转换不同类型数据的展示方式
+     * @default undefined
+     */
+    valueType?: ProTableValueType;
+    /**
+     * 日期格式
+     * @description 设置日期格式
+     * @default 'YYYY-MM-DD HH:mm:ss'
+     */
+    format?: string;
+    /**
+     * 数值精度
+     * @description 设置数值精度
+     * @default undefined
+     */
+    precision?: number;
+    /**
+     * 枚举code
+     * @description 用于枚举类型的值映射
+     * @default undefined
+     */
+    code?: string | string[] | ((text: any, record: any) => string);
+    /**
+     * 枚举数据源
+     * @description 枚举 code 数据源
+     * @default undefined
+     */
+    codeValues?: {
+        label: string;
+        value: string | number;
+    }[];
+    /**
+     * 是否可复制
+     * @description 开启字段复制功能
+     * @default false
+     */
+    copyable?: boolean;
+    /**
+     * 自定义前缀
+     * @description 用于 valueType 转换时的前缀添加，render 开启时会失效
+     * @default undefined
+     */
+    prefix?: string | ReactNode | ((value: any, record?: any, index?: number) => any);
+    /**
+     * 自定义后缀
+     * @description 用于 valueType 转换时的后缀添加，render 开启时会失效
+     * @default undefined
+     */
+    suffix?: string | ReactNode | ((value: any, record?: any, index?: number) => any);
+    /**
+     * 列头提示
+     * @description 列头是否开启提示
+     * @default undefined
+     */
+    tooltip?: ReactNode | {
+        title?: ReactNode;
+        icon?: ReactNode;
+    };
+    /**
+     * 提示组件属性
+     * @description 传递给 Tooltip 组件的属性
+     * @default undefined
+     */
+    toolTipProps?: TooltipProps & React.RefAttributes<unknown>;
+    /**
+     * 地址转换
+     * @description valueType 为 address 时可用，用于对地址的转换
+     * @default undefined
+     */
+    transform?: (value: any, record?: any) => string[];
+    /**
+     * 列隐藏（antd 5.13+ 原生支持）
+     * @description 控制列是否隐藏；优先级高于 show
+     * @default undefined
+     */
+    hidden?: boolean;
+    /**
+     * 列头显示控制
+     * @deprecated 请改用 column.hidden（antd 5.13+ 原生支持）。show 将在后续版本移除。
+     * @description 控制列是否显示；当 hidden 缺省时回退此字段
+     * @default true
+     */
+    show?: boolean | (() => boolean);
+    /**
+     * 自定义比较函数
+     * @description 自定义如何比较数据差异，触发条件必须写render
+     * @default undefined
+     */
+    onDiff?: ({ value, record, index, originValue, originRecord }: any) => any;
+    /**
+     * 自定义比对渲染
+     * @description 用于开启比对时，自定义 render 渲染初始值，触发条件必须写render
+     * @default undefined
+     */
+    viewRender?: ({ value, record, index, originValue, originRecord, }: any) => 'same' | 'changed' | 'add' | undefined;
+    /**
+     * 是否已更改
+     * @description 标记列值是否已变更
+     * @default undefined
+     */
+    isChanged?: boolean | null;
+    /**
+     * 子列
+     * @description 用于表头分组
+     * @default undefined
+     */
+    children?: ProTableColumnType[];
+    /**
+     * 表格滚动配置
+     * @description table透传下来的scroll配置
+     * @default undefined
+     */
+    scroll?: any;
+    /**
+     * 行内编辑配置
+     * @description 配置后单元格支持点击图标进入编辑态
+     * @default undefined
+     */
+    editConfig?: EditTableCellConfig;
+}
+/**
+ * 从数组创建树形结构的选项
+ */
+export interface ProTableCreateTreeFromArrayType {
+    /**
+     * 项目键
+     * @description 用作标识项目的属性名
+     * @default 'id'
+     */
+    itemKey?: string;
+    /**
+     * 父项键
+     * @description 指向父项的属性名
+     * @default 'parentId'
+     */
+    parentKey?: string;
+    /**
+     * 子项键
+     * @description 存储子项的属性名
+     * @default 'children'
+     */
+    childrenKey?: string;
+}
+/**
+ * 拖拽通用守卫属性
+ */
+export interface ProTableDragCommonGuardType<T> {
+    /**
+     * 事件对象
+     * @description 拖拽事件对象
+     * @default undefined
+     */
+    event: T;
+}
+/**
+ * 拖拽结束守卫属性
+ */
+export interface ProTableDragEndGuardType {
+    /**
+     * 开始拖拽的元素
+     * @description 被拖拽的数据项
+     * @default undefined
+     */
+    activeObject: any;
+    /**
+     * 最终置放的元素
+     * @description 放置目标的数据项
+     * @default undefined
+     */
+    overObject?: any;
+    /**
+     * 数据源
+     * @description 当前表格的数据源
+     * @default []
+     */
+    currentDataSource: any[];
+}
+/**
+ * 拖拽开始守卫属性
+ */
+export interface ProTableDragStartGuardType {
+    /**
+     * 开始拖拽的元素
+     * @description 被拖拽的数据项
+     * @default undefined
+     */
+    activeObject: any;
+    /**
+     * 数据源
+     * @description 当前表格的数据源
+     * @default []
+     */
+    currentDataSource: any[];
+}
+/**
+ * 表单比对配置
+ */
+export interface ProTableDiffConfigType {
+    /**
+     * 比对原始数据源
+     * @description 用于和当前数据比对的数据源
+     * @default undefined
+     */
+    originalDataSource: any[];
+    /**
+     * 是否显示对比值气泡
+     * @description 控制是否显示对比信息的气泡提示
+     * @default true
+     */
+    toolTip?: boolean;
+    /**
+     * 变更提示颜色
+     * @description 数据变更时的背景颜色
+     * @default '#fffaa1'
+     */
+    changeTipColor?: string;
+    /**
+     * 新增提示颜色
+     * @description 新增数据时的背景颜色
+     * @default '#d2fff4'
+     */
+    addTipColor?: string;
+}
+export interface ProTableTabsType {
+    /**
+     * 激活的 key
+     * @description 激活的 key
+     * @default undefined
+     */
+    activeKey?: string;
+    /**
+     * 枚举 code
+     * @description 枚举 code
+     * @default undefined
+     */
+    code?: string;
+    /**
+     * 枚举数据源
+     * @description 枚举数据源
+     * @default undefined
+     */
+    dataSource?: {
+        label: string;
+        value: string;
+    }[];
+    /**
+     * 转换查询参数
+     * @description 转换查询参数
+     * @default undefined
+     */
+    transformParams?: (params: any) => any;
+    /**
+     * 枚举数据源转换
+     * @description 枚举数据源转换
+     * @default undefined
+     */
+    transformResponse?: (dataSource: {
+        label: string;
+        value: string;
+    }[], useAntdTableProps: ProTableUseAntdTableType<any, any>) => {
+        key: string;
+        label: string | ReactNode;
+    }[];
+    /**
+     * 标签属性
+     * @description 标签属性
+     * @default undefined
+     */
+    tabsProps?: TabsProps;
+    /**
+     * 展示模式
+     * @description Tab 卡片页签 / Segmented 分段控制器
+     * @default 'Segmented'
+     */
+    mode?: 'Tab' | 'Segmented';
+    /**
+     * Segmented 属性
+     * @description mode 为 Segmented 时透传给 antd Segmented 的属性
+     * @default undefined
+     */
+    segmentedProps?: SegmentedProps;
+    /**
+     * 表单字段名
+     * @description 表单字段名
+     * @default undefined
+     */
+    name: NamePath;
+    [key: string]: any;
+}
+/**
+ * ProTable 主要属性
+ */
+export interface ProTableType<T = any> extends Omit<TableProps<any>, 'summary' | 'columns'> {
+    /**
+     * table 唯一标识
+     * @description 用于缓存和获取 columns 配置，在开启 resizeColumn/columnConfig 功能时需要传递以保证缓存和获取到正确的 columns 配置
+     * @default -
+     */
+    tableId?: string;
+    /**
+     * 表格 tabs查询 配置
+     * @description 用于配置表格的 tabs 选项
+     * @default -
+     */
+    tabs?: ProTableTabsType;
+    /**
+     * 表格行 key 的取值
+     * @description 表格行数据的唯一标识字段
+     * @default -
+     */
+    rowKey?: string | GetRowKey<any>;
+    /**
+     * 自定义 table header 左侧渲染
+     * @description 可以是 ReactNode 或返回 ReactNode 的函数
+     * @default -
+     */
+    headerRender?: ReactNode | (() => ReactNode);
+    /**
+     * 全局快速 config 开关
+     * @description 快速开启自定义列、缓存列配置功能
+     * @default false
+     */
+    quickConfig?: boolean;
+    /**
+     * 是否开启可伸缩列功能
+     * @description 开启伸缩列功能时，需要在 columns 中设置列宽，否则伸缩列功能不生效
+     * @default false
+     */
+    resizeColumn?: boolean;
+    /**
+     * 行排序方式
+     * @description 控制表格行的排序方式
+     * @default false
+     */
+    sortRow?: boolean | 'drag' | 'move';
+    /**
+     * 是否开启列配置功能
+     * @description 开启列配置功能时默认开启缓存，cacheTime 为 true
+     * @default false
+     */
+    columnConfig?: boolean | {
+        onColumnOk: (cacheColumns: any, columns: ProTableColumnType[]) => Promise<void>;
+    };
+    /**
+     * 是否开启缓存列配置和列宽度功能
+     * @description 开启时默认缓存时间为一天，可以自定义缓存时间，单位为天
+     * @default false
+     */
+    cacheTime?: number | boolean;
+    /**
+     * 排序列文本
+     * @description 排序列按钮的文本
+     * @default '排序'
+     */
+    sortColumnText?: string;
+    /**
+     * 浏览器缓存位置
+     * @description 用于设置表格列配置的存储位置；'indexedDB' 走异步存储，容量大且不阻塞主线程；其他两种走同步 Web Storage。
+     * @default 'localStorage'
+     */
+    storage?: 'localStorage' | 'sessionStorage' | 'indexedDB';
+    /**
+     * 自定义 table footer 左侧渲染
+     * @description 可以是 ReactNode 或返回 ReactNode 的函数
+     * @default -
+     */
+    footerRender?: ReactNode | (() => ReactNode);
+    /**
+     * 空数据文案
+     * @description 表格无数据时显示的内容
+     * @default '暂无数据'
+     */
+    emptyText?: string | ReactNode | (() => ReactNode);
+    /**
+     * 总结栏
+     * @description 表格底部汇总行
+     * @default true
+     */
+    summary?: ProTableSummaryType | TableProps<any>['summary'];
+    /**
+     * 排序开关
+     * @description 是否启用拖拽排序功能
+     * @default false
+     */
+    draggable?: boolean;
+    /**
+     * 是否禁用
+     * @description 全局禁用表格交互
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 是否为查看模式
+     * @description 开启后表格将以只读模式显示
+     * @default false
+     */
+    isView?: boolean;
+    /**
+     * 行禁用判断
+     * @description 判断指定行是否禁用
+     * @default -
+     */
+    rowDisabled?: (record?: T) => string | boolean;
+    /**
+     * 是否为斑马纹 table
+     * @description 启用后表格将显示交替的行背景色
+     * @default true
+     */
+    stripe?: boolean;
+    /**
+     * 表格列配置
+     * @description 定义表格的列结构
+     * @default []
+     */
+    columns: ProTableColumnType[];
+    /**
+     * 表单比对配置
+     * @description 用于标记数据变化的配置
+     * @default -
+     */
+    diffConfig?: ProTableDiffConfigType;
+    /**
+     * 开始拖拽回调
+     * @description 拖拽开始时触发
+     * @default -
+     */
+    onDragStart?: ProTableDragStartGuardType;
+    /**
+     * 结束拖拽回调
+     * @description 拖拽结束时触发，务必返回变更后的数据源
+     * @default -
+     */
+    onDragEnd?: ProTableDragEndGuardType;
+    /**
+     * tip 是否跟随父节点
+     * @description 提示气泡是否附加到父元素
+     * @default true
+     */
+    scrollFollowParent?: boolean;
+    /**
+     * 行内编辑 Form 模式
+     * @description
+     * - 'per-cell-form'（默认）：每个 cell 独立 Form 实例，行为与重构前一致
+     * - 'shared-form'：ProTable 顶层创建共享 Form，所有 cell 复用，并自动注入 column.shouldCellUpdate 实现单 cell 精确更新
+     * @default 'per-cell-form'
+     */
+    editMode?: 'per-cell-form' | 'shared-form';
+    [key: string]: any;
+}
+/**
+ * ProTable 值类型
+ * @description 定义表格单元格内容的展示类型
+ */
+export type ProTableValueType = 'percentage' | 'permillage' | 'thousandth' | 'datePicker' | 'enumName' | 'enumCodeName' | 'address' | 'thousandthCNY' | 'date' | 'dateTime' | 'dateStartTime' | 'dateEndTime' | 'dateStartEndTime';
+/**
+ * 请求响应接口
+ */
+export interface ProTableResponseType<T = any> {
+    /**
+     * 响应数据
+     * @description 服务器返回的数据
+     * @default undefined
+     */
+    data: T;
+    /**
+     * 状态码
+     * @description 用于标识错误类型的代码
+     * @default undefined
+     */
+    status: number;
+    /**
+     * 消息
+     * @description 显示给用户的消息
+     * @default ''
+     */
+    message: string;
+}
+/**
+ * 分页属性
+ */
+export interface ProTablePaginationType {
+    /**
+     * 当前页码
+     * @description 显示的页数
+     * @default 1
+     */
+    pageNum: number;
+    /**
+     * 每页条数
+     * @description 每页显示的记录数
+     * @default 10
+     */
+    pageSize: number;
+}
+/**
+ * 使用 antd表格 的选择类型
+ */
+type RowSelectionTypeWithPick = Pick<TableProps<any>, 'rowSelection'>['rowSelection'];
+/**
+ * 请求选项
+ */
+export interface ProTableRequestOptionsType<T, R> {
+    /**
+     * 查询表单实例
+     * @description 用于获取和设置表单值
+     * @default undefined
+     */
+    form?: FormInstance;
+    /**
+     * 重置时是否重新查询
+     * @description 控制表单重置后是否自动发起查询
+     * @default false
+     */
+    isResetQuery?: boolean;
+    /**
+     * 表格行 key 的取值
+     * @description 表格行数据的唯一标识字段
+     * @default undefined
+     */
+    rowKey?: string | GetRowKey<R>;
+    /**
+     * 行选择配置
+     * @description 控制表格行的选择功能
+     * @default false
+     */
+    rowSelection?: boolean | RowSelectionTypeWithPick;
+    /**
+     * 选择功能类型
+     * @description 控制选择为多选或单选
+     * @default 'checkbox'
+     */
+    rowSelectType?: RowSelectionType;
+    /**
+     * 选择扩展下拉
+     * @description 启用选择当前页、选择全部、取消选择下拉菜单
+     * @default false
+     */
+    rowSelections?: boolean | object[];
+    /**
+     * 额外参数
+     * @description 无法通过搜索表单设置的值,此值变更时也会重新发起请求,重置表单不会被清空
+     * @default undefined
+     */
+    extraParams?: Partial<T>;
+    /**
+     * 分页配置
+     * @description 设置初始分页参数
+     * @default { pageNum: 1, pageSize: 10 }
+     */
+    page?: ProTablePaginationType;
+    /**
+     * 是否支持跨页勾选
+     * @description 启用后可在不同页面间保持选中状态
+     * @default false
+     */
+    crossPageSelect?: boolean;
+    /**
+     * 页码改变回调
+     * @description 页码或每页条数变化时的回调函数
+     * @default undefined
+     */
+    onPageChange?: (page: ProTablePaginationType) => void;
+    /**
+     * 转换请求参数
+     * @description 在发送请求前转换参数
+     * @default undefined
+     */
+    transformParams?: (params: any) => any;
+    /**
+     * 转换响应数据
+     * @description 处理服务器返回的数据
+     * @default undefined
+     */
+    transformResponse?: (res: any) => ProTableListResponseType<R>;
+    /**
+     * 行禁用判断
+     * @description 判断指定行是否禁用
+     * @default undefined
+     */
+    disabled?: (record: any) => boolean;
+}
+/**
+ * 参数接口
+ */
+export interface ProTableParamsType<T = any> extends ProTablePaginationType {
+    /**
+     * 查询参数
+     * @description 包含查询条件的对象
+     * @default undefined
+     */
+    queryBean?: Partial<T>;
+    /**
+     * 其他参数
+     * @description 任意其他参数
+     * @default undefined
+     */
+    [key: string]: any;
+}
+/**
+ * 列表数据结构
+ */
+export interface ProTableListType<T> {
+    /**
+     * 当前页码
+     * @description 当前页数
+     * @default undefined
+     */
+    pageNum?: number;
+    /**
+     * 每页条数
+     * @description 每页显示的记录数
+     * @default undefined
+     */
+    pageSize?: number;
+    /**
+     * 总条数
+     * @description 符合条件的记录总数
+     * @default 0
+     */
+    total: number;
+    /**
+     * 数据列表
+     * @description 当前页的数据记录
+     * @default []
+     */
+    list: T[];
+}
+/**
+ * 列表响应类型
+ */
+export type ProTableListResponseType<T> = ProTableResponseType<ProTableListType<T>>;
+/**
+ * 服务调用函数类型
+ */
+export type ProTableServiceType<Req, Res> = (params?: ProTableParamsType<Req>) => Promise<ProTableListResponseType<Res>>;
+/**
+ * useAntdTable 状态
+ */
+export interface ProTableUseAntdTableType<I, R> {
+    /**
+     * 表格数据
+     * @description 当前表格显示的数据
+     * @default []
+     */
+    data: R[];
+    /**
+     * 总记录数
+     * @description 符合条件的记录总数
+     * @default 0
+     */
+    total: number;
+    /**
+     * 已选择的记录
+     * @description 当前已选中的表格行数据
+     * @default []
+     */
+    selectedRecords: R[];
+    /**
+     * 已选择的行键值
+     * @description 当前已选中的表格行键值
+     * @default []
+     */
+    selectedRowKeys: Key[];
+    /**
+     * 额外过滤条件
+     * @description 表单之外的额外过滤条件
+     * @default {}
+     */
+    extraFilter: any;
+    /**
+     * 是否全选
+     * @description 是否选中了所有数据
+     * @default false
+     */
+    allSelected: boolean;
+    [key: string]: any;
+}
+export {};