#ProTable - 高级表格
ProTable 的诞生是为了解决项目中需要写很多 table 的样板代码的问题,所以在其中封装了很多常用的逻辑。这些封装可以简单的分类为预设行为与预设逻辑。
依托于 ProForm 的能力,ProTable 的查询区可切换多种形态(如 QueryFilter / LightFilter),也可在 type="form" 等场景下更像普通表单使用。

#何时使用
当你的表格需要与服务端进行交互或者需要多种单元格样式时,ProTable 是不二选择。
#Issue 回归场景
#API
ProTable 在 antd 的 Table 上进行了一层封装,支持了一些预设,并且封装了一些行为。这里只列出与 antd Table 不同的 API。
#request
request 是 ProTable 最重要的 API,request 会接收一个对象。对象中必须要有 data 和 success,如果需要手动分页 total 也是必需的。request 会接管 loading 的设置,同时在查询表单查询时和 params 参数发生修改时重新执行。同时查询表单的值和 params 参数也会带入。以下是一个例子:
<ProTable<DataType, Params>
// params 是需要自带的参数
// 这个参数优先级更高,会覆盖查询表单的参数
params={params}
request={async (
// 第一个参数 params 查询表单和 params 参数的结合
// 第一个参数中一定会有 pageSize 和 current ,这两个参数是 antd 的规范
params: T & {
pageSize: number;
current: number;
},
sort,
filter,
) => {
// 这里需要返回一个 Promise,在返回之前你可以进行数据转化
// 如果需要转化参数可以在这里进行修改
const msg = await myQuery({
page: params.current,
pageSize: params.pageSize,
});
return {
data: msg.result,
// success 请返回 true,
// 不然 table 会停止解析数据,即使有数据
success: boolean,
// 不传会使用 data 的长度,如果是分页一定要传
total: number,
};
}}
/>列配置中也支持 request,但是只有几种 valueType 支持。
#ProTable
| 属性 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| actionRef | Table action 的引用,便于自定义触发 | React.Ref<ActionType | undefined> | - | - |
| beforeSearchSubmit | 搜索之前进行一些修 改 | (params: Partial<U>) => any | - | - |
| cardBordered | Table 和 Search 外围 Card 组件的边框 | boolean | {search?: boolean, table?: boolean} | false | - |
| cardProps | table 外面卡片的设置 | ProCardProps | false | - | - |
| columns | 列配置能力,支持一个数组 | ProColumns<T, ValueType>[] | - | - |
| columnEmptyText | 空值时的显示,不设置时显示 -,false 可以关闭此功能 | ProFieldEmptyText | '-' | - |
| columnsState | 受控的列状态,可以操作显示隐藏 | ColumnStateType | - | - |
| dataSource | Table 的数据,ProTable 推荐使用 request 来加载 | T[] | - | - |
| dateFormatter | 转化 dayjs 格式数据为特定类型,false 不做转化 | 'string' | 'number' | ((value: dayjs.Dayjs, valueType: string) => string | number) | false | 'string' | - |
| defaultData | 默认的数据 | T[] | - | - |
| defaultSize | 默认的 size | SizeType | - | - |
| debounceTime | 防抖时间 | number | 20 | - |
| editable | 可编辑表格的相关配置,支持 type="multiple" 等。配置详情 | RowEditableConfig<T> | - | - |
| ErrorBoundary | 自带了错误处理功能,防止白屏,ErrorBoundary=false 关闭默认错误边界 | React.ComponentClass<any, any> | false | 内置 ErrorBoundary | - |
| form | type="form" 和搜索表单的 Form 配置,ignoreRules: false 可开启查询表单校验,详见此处 | Omit<ProFormProps & QueryFilterProps, 'form'> | - | - |
| formRef | 可以获取到查询表单的 form 实例,用于一些灵活的配置 | TableFormItem<T>['formRef'] | - | - |
| ghost | 幽灵模式,即是否取消表格区域的 padding | boolean | false | - |
| headerTitle | 左上角的 title | ReactNode | - | - |
| manualRequest | 是否需要手动触发首次请求,配置为 true 时不可隐藏搜索表单 | boolean | false | - |
| mergeFields | 同值单元格纵向自动合并的字段列表(对应列的 dataIndex),数组顺序即多级合并顺序;只合并当前页内连续同值,排序、筛选、分页后自动重算;合并场景建议配合 bordered 全边框使用;本地排序/筛选激活时,若数据源被翻页或刷新替换,该页会跳过自动合并,待下一次表格变更捕获新数据后恢复 | string[] | - | - |
| name | 可编辑表格的 name,通过这个 name 可以直接与 form 通信,无需嵌套 | NamePath | - | - |
| onDataSourceChange | Table 的数据发生改变时触发 | (dataSource: T[]) => void | - | - |
| onLoad | 数据加载完成后触发,会多次触发 | (dataSource: T[]) => void | - | - |
| onLoadingChange | loading 被修改时触发,一般是网络请求导致的 | (loading: boolean | SpinProps | undefined) => void | - | - |
| onRequestError | 数据加载失败时触发 | (error: Error) => void | - | - |
| onReset | 重置表单时触发 | () => void | - | - |
| onSizeChange | table 尺寸发生改变 | (size: DensitySize) => void | - | - |
| onSubmit | 提交表单时触发 | (params: U) => void | - | - |
| options | table 工具栏,设为 false 时不显示,传入 function 会点击时触发 | {{ density?: boolean, fullScreen?: boolean | function, reload?: boolean | function, reloadIcon?: React.ReactNode, densityIcon?: React.ReactNode, setting?: boolean | SettingOptionType }} | { reload: true, density: true, setting: true, search: false, fullScreen: false } | - |
| optionsRender | 自定义渲染工具栏选项 | ToolBarProps<T>['optionsRender'] | - | - |
| pagination | 分页器的配置,current 和 pageSize 会被 request 接管 | TablePaginationConfig | false | - | - |
| params | 用于 request 查询的额外参数,一旦变化会触发重新加载 | U | - | - |
| polling | 是否轮询,polling 表示轮询的时间间隔,0 表示关闭轮询,大于 0 表示开启轮询,最小的轮询时间为 2000ms | number | ((dataSource: T[]) => number) | undefined | - | - |
| postData | 对通过 request 获取的数据进行处理 | (data: T[]) => T[] | - | - |
| request | 获取 dataSource 的方法 | (params: U & {pageSize?: number, current?: number, keyword?: string}, sort: Record<string, SortOrder>, filter: Record<string, FilterValue>) => Promise<{data: T[], success?: boolean, total?: number}> | - | - |
| revalidateOnFocus | 窗口聚焦时自动重新请求 | boolean | false | - |
| rowSelection | 选择项配置 | TableProps<T>['rowSelection'] & {alwaysShowAlert?: boolean} | false | - | - |
| search | 是否显示搜索表单,传入对象时为搜索表单的配置 | false | SearchConfig | - | - |
| searchFormRender | 渲染搜索表单 | (props: ProTableProps<T, U, ValueType>, defaultDom: JSX.Element) => ReactNode | - | - |
| style | 外层容器的样式 | React.CSSProperties | - | - |
| tableClassName | 封装的 table 的 className | string | - | - |
| tableExtraRender | table 和搜索表单之间的 dom 渲染 | (props: ProTableProps<T, U, ValueType>, dataSource: T[]) => ReactNode | - | - |
| tableRender | 自定义渲染表格函数 | (props: ProTableProps<T, U, ValueType>, defaultDom: ReactNode, domList: {toolbar: ReactNode, alert: ReactNode, table: ReactNode}) => ReactNode | - | - |
| tableStyle | 封装的 table 的 style | CSSProperties | - | - |
| tableViewRender | 渲染 table 视图,用于定制 ProList,不推荐直接使用;defaultDom 可为惰性函数,仅在需要默认 Table 时调用(见 resolveTableViewDefaultDom) | (props: TableProps<DataSource>, defaultDom: JSX.Element | (() => JSX.Element)) => JSX.Element | undefined | - | - |
| toolBarRender | 渲染工具栏,支持返回一个 dom 数组,会自动增加 margin-right | ToolBarProps<T>['toolBarRender'] | false | - | - |
| toolbar | 透传 ListToolBar 配置项 | ListToolBarProps | - | - |
| tooltip | 标题旁边的 tooltip | string | LabelTooltipType | - | - |
| type | pro-table 类型 | ProSchemaComponentTypes | - | - |
#RecordCreator (EditableProTable)
| 属性 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| (...buttonProps) | antd 的 ButtonProps | ButtonProps | - | - |
| position | 行增加在哪里,开始或者末尾 | 'top' | 'bottom' | 'bottom' | - |
| record | 需要新增的行数据,一般来说包含唯一 key,支持传入函数 | T | ((index: number, dataSource: T[]) => T) | {} | - |
| newRecordType | 新增行的类型,dataSource 直接写入数据,cache 写入缓存取消后消失 | 'dataSource' | 'cache' | - | - |
| parentKey | 要增加到哪个节点下,一般用于多重嵌套表格 | React.Key | ((index: number, dataSource: T[]) => React.Key) | - | - |
#ColumnStateType
| 属性 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| defaultValue | 列状态的默认值,只有初次生效,并用于重置使用 | Record<string, ColumnsState> | - | - |
| onChange | 列状态的值发生改变之后触发 | (value: Record<string, ColumnsState>) => void | - | - |
| persistenceKey | 持久化列的 key,用于判断是否是同一个 table | string | number | - | - |
| persistenceType | 持久化列的类型,localStorage 设置在关闭浏览器后也是存在的,sessionStorage 关闭浏览器后会丢失 | 'localStorage' | 'sessionStorage' | - | - |
| value | 列状态的值,支持受控模式 | Record<string, ColumnsState> | - | - |
#Search 搜索表单
| 属性 | 描述 |
|---|