ProTable - 高级表格

ProTable 的诞生是为了解决项目中需要写很多 table 的样板代码的问题,所以在其中做了封装了很多常用的逻辑。这些封装可以简单的分类为预设行为与预设逻辑。

依托于 ProForm 的能力,ProForm 拥有多种形态,可以切换查询表单类型,设置变形成为一个简单的 Form 表单,执行新建等功能。

layout\n

若您是内网用户,欢迎使用我们的 TechUI Studio 可视化配置生成初始代码。

何时使用

当你的表格需要与服务端进行交互或者需要多种单元格样式时,ProTable 是不二选择。

代码演示

查询表格

高级表格
标题
状态
标签
创建时间
操作
1
未解决
bug
2020-05-26
2
未解决
bug
2020-05-26
3
未解决
question
2020-05-26
4
未解决
question
2020-05-26
5
未解决
bug
2020-05-26
  • 第 1-5 条/总共 30 条
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6

查询(无按钮)表格

表格标题
应用名称
容器数量
状态创建者
创建时间
备注操作
AppName14已上线林东东2022-08-30
AppName6关闭曲丽丽2022-08-30
AppName7已上线付小小2022-08-30
AppName3异常兼某某2022-08-30
AppName0异常林东东2022-08-30
  • 第 1-5 条/总共 5 条
  • 1

无查询表单

表格标题
应用名称
容器数量
状态创建者
创建时间
备注操作
AppName19异常林东东2022-08-30简短备注文案
AppName6运行中陈帅帅2022-08-30很长很长很长很长很长很长很长的文字要展示但是要留下尾巴
AppName8运行中陈帅帅2022-08-30简短备注文案
AppName10异常林东东2022-08-30很长很长很长很长很长很长很长的文字要展示但是要留下尾巴
AppName17运行中兼某某2022-08-30简短备注文案
  • 第 1-5 条/总共 5 条
  • 1

轻量筛选替换查询表单

应用名称创建者
创建时间
操作
AppName林东东2022-08-30
AppName林东东2022-08-30
AppName付小小2022-08-30
AppName付小小2022-08-30
AppName曲丽丽2022-08-30
  • 第 1-5 条/总共 5 条
  • 1

无 ToolBar 的表格

成员名称账号手机号角色权限范围操作
巴巴
[email protected]12345678910管理员 所有权限
测试
[email protected]10923456789操作员 权限点名称1、权限点名称4
测试2
[email protected]109654446789操作员 权限点名称1
测试3
[email protected]109223346789操作员
巴巴
[email protected]12345678910操作员
  • 第 1-5 条/总共 5 条
  • 1

必填的查询表单

尽量使用 initialValue 来解决问题,必填项挫败感比较强

高级表格
标题
状态
标签创建时间
🐛 [BUG]yarn install命令 antd2.4.5会报错
未解决
bug
1594-02-02
  • 第 1-1 条/总共 1 条
  • 1
高级表格
标题
状态
标签创建时间
🐛 [BUG]yarn install命令 antd2.4.5会报错
未解决
bug
1594-02-02
  • 第 1-1 条/总共 1 条
  • 1

嵌套表格

嵌套表格
应用名称状态
容器数量
创建者
创建时间
操作
AppName失败12付小小2022-08-30
AppName失败10陈帅帅2022-08-30
AppName失败6付小小2022-08-30
AppName失败15曲丽丽2022-08-30
AppName进行中1付小小2022-08-30
  • 第 1-5 条/总共 5 条
  • 1

左右结构

IPCPUMemDisk
106.14.98.10410%20%30%
106.14.98.11410%20%30%
106.14.98.12410%20%30%
106.14.98.13410%20%30%
106.14.98.14410%20%30%
106.14.98.15410%20%30%
106.14.98.16410%20%30%
106.14.98.17410%20%30%
106.14.98.18410%20%30%
106.14.98.19410%20%30%
0.0.0.0
时间点代码操作
2022-08-30 10:38:32
const getData = async params => {
          const data = await getData(params);
          return { list: data.data, ...data };
        };
2022-08-30 10:38:27
const getData = async params => {
          const data = await getData(params);
          return { list: data.data, ...data };
        };
2022-08-30 10:38:34
const getData = async params => {
          const data = await getData(params);
          return { list: data.data, ...data };
        };
  • 第 1-3 条/总共 15 条
  • 1
  • 2
  • 3
  • 4
  • 5

表格批量操作

批量操作
应用名称
容器数量
调用次数执行进度创建者
创建时间
备注操作
AppName12289
54%
兼某某2022-08-30简短备注文案
AppName10682
84%
曲丽丽2022-08-30很长很长很长很长很长很长很长的文字要展示但是要留下尾巴
AppName111104
付小小2022-08-30简短备注文案
AppName6477
87%
陈帅帅2022-08-30很长很长很长很长很长很长很长的文字要展示但是要留下尾巴
AppName11849
曲丽丽2022-08-30简短备注文案
  • 第 1-5 条/总共 5 条
  • 1

通过 formRef 来操作查询表单

表单赋值
标题创建时间
TradeCode 12020-10-13
  • 第 1-1 条/总共 1 条
  • 1
  • 20 条/页

RTL (النسخة العربية)

RTL means right-to-left.

نموذج احترافي
العنوان
الحالة
التسميةالتشغيل
لا توجد بيانات

受控的表格设置栏

可以默认隐藏某些栏,但是在操作栏中可以选择

受控模式
状态
更新时间操作
关闭2022-08-30
关闭2022-08-30
  • 第 1-2 条/总共 2 条
  • 1

表格轮询

上次更新时间:10:38:35
序号
状态
进度更新时间创建时间
暂无数据

dateFormatter - 日期格式化

日期格式化为字符串
标题创建时间
TradeCode 12022-09-22
  • 第 1-1 条/总共 1 条
  • 1
  • 20 条/页
日期格式化为数字
标题创建时间
TradeCode 12022-09-22
  • 第 1-1 条/总共 1 条
  • 1
  • 20 条/页
使用自定义函数进行日期格式化
标题创建时间
TradeCode 12022-09-22
  • 第 1-1 条/总共 1 条
  • 1
  • 20 条/页

搜索表单自定义

当内置的表单项无法满足我们的基本需求,这时候我们就需要来自定义一下默认的组件,我们可以通过 fieldPropsrenderFormItem 配合来使用。

fieldProps 可以把 props 透传,可以设置 select 的样式和多选等问题。

renderFormItem 可以完成重写渲染逻辑,传入 item 和 props 来进行渲染,需要注意的是我们必须要将 props 中的 valueonChange 必须要被赋值,否则 form 无法拿到参数。如果你需要自定义需要先了解 antd 表单的工作原理

renderFormItem: (_, { type, defaultRender, formItemProps, fieldProps, ...rest }, form) => {
if (type === 'form') {
return null;
}
const status = form.getFieldValue('state');
if (status !== 'open') {
return (
// value 和 onchange 会通过 form 自动注入。
<Input
// 组件的配置
{...fieldProps}
// 自定义配置
placeholder="请输入test"
/>
);
}
return defaultRender(_);
};

renderFormItem 的定义, 具体的值可以打开控制台查看。

renderFormItem?: (
item: ProColumns<T>,
config: {
value?: any;
onSelect?: (value: any) => void;
type: ProTableTypes;
defaultRender: (newItem: ProColumns<any>) => JSX.Element | null;
},
form: FormInstance,
) => JSX.Element | false | null;
动态自定义搜索栏
序号标题状态
1
TradeCode 1closed
  • 第 1-1 条/总共 1 条
  • 1

FAQ

为什么不能自己设置 value 和 onchange

被 ProTable 包装的控件,表单控件会自动添加 value(或 valuePropName 指定的其他属性) onChange(或 trigger 指定的其他属性),数据同步将被 Form 接管,这会导致以下结果:

  • 你不再需要也不应该用 onChange 来做数据收集同步(你可以使用 Form 的 onValuesChange),但还是可以继续监听 onChange 事件。

  • 你不能用控件的 value 或 defaultValue 等属性来设置表单域的值,默认值可以用 Form 里的 initialValues 来设置。注意 initialValues 不能被 setState 动态更新,你需要用 setFieldsValue 来更新。

  • 你不应该用 setState,可以使用 form.setFieldsValue 来动态改变表单值。

为什么设置 defaultValue 不生效?#

因为 ProTable 子组件会转为受控模式。因而 defaultValue 不会生效。你需要在 Form 上通过 initialValues 设置默认值。

表单操作自定义

查询 Table
indexTitleMoney
1
TradeCode 1¥62.79
  • 第 1-1 条/总共 1 条
  • 1

Toolbar 自定义

使用 toolbar属性扩展配置工具栏渲染。

响应日期
应用名称创建者
状态
容器数量
创建时间
操作
AppName付小小发布成功42022-08-30
AppName曲丽丽发布中142022-08-30
AppName曲丽丽发布失败152022-08-30
AppName陈帅帅发布中182022-08-30
AppName陈帅帅发布成功82022-08-30
  • 第 1-5 条/总共 5 条
  • 1

表格主体自定义

Row2
CreatedLili Qu
Association421421
Creation Time2017-01-10
Effective Time2017-10-10
自定义表格主体
序号更新时间执行进度
1
2022-08-30
88%
2
2022-08-30
74%
  • 第 1-2 条/总共 2 条
  • 1
  • 20 条/页

卡片表格

有些业务有自己的定制逻辑,可以不完全遵循 ProTable 的设计规则,但可以利用 ProTable 的 API 实现。如通过 cardProps 配置卡片属性,通过 headTitle 配置行动点在左侧。

业务定制
应用名称
容器数量
创建者操作
AppName4陈帅帅
AppName11曲丽丽
AppName1林东东
AppName14林东东
AppName5陈帅帅
  • 第 1-5 条/总共 5 条
  • 1
卡片表格

使用卡片标题,行动点在左侧。

国际化相关的配置

ProTable 内置了国际化的支持,作为一个文本量比较少的组件,我们可以自行实现国际化,成本也很低。

这里是全量的文本

const enLocale = {
tableForm: {
search: 'Query',
reset: 'Reset',
submit: 'Submit',
collapsed: 'Expand',
expand: 'Collapse',
inputPlaceholder: 'Please enter',
selectPlaceholder: 'Please select',
},
alert: {
clear: 'Clear',
},
tableToolBar: {
leftPin: 'Pin to left',
rightPin: 'Pin to right',
noPin: 'Unpinned',
leftFixedTitle: 'Fixed the left',
rightFixedTitle: 'Fixed the right',
noFixedTitle: 'Not Fixed',
reset: 'Reset',
columnDisplay: 'Column Display',
columnSetting: 'Settings',
fullScreen: 'Full Screen',
exitFullScreen: 'Exit Full Screen',
reload: 'Refresh',
density: 'Density',
densityDefault: 'Default',
densityLarger: 'Larger',
densityMiddle: 'Middle',
densitySmall: 'Compact',
},
};
// 生成 intl 对象
const enUSIntl = createIntl('en_US', enUS);
import { ConfigProvider } from '@ant-design/pro-provide';
// 使用
<ConfigProvider
value={{
intl: enUSIntl,
}}
>
<ProTable />
</ConfigProvider>;
Basic Table
zhCNIntl
indexTitleMoney
1
TradeCode 1¥63.22
  • 第 1-1 条/总共 1 条
  • 1

使用自带 keyWords 搜索的 table

值类型示例

valueType - 日期类

日期类
创建时间日期区间时间区间更新时间更新时间关闭时间操作
2022-08-30 10:38:33
2022-08-30
2022-08-30
2022-08-30 10:38:33
2022-08-30 10:38:33
2022-08-30a few seconds ago10:38:33
2022-08-30 10:38:33
2022-08-30
2022-08-30
2022-08-30 10:38:33
2022-08-30 10:38:33
2022-08-30a few seconds ago10:38:34

valueType - 数字类

数字类
进度金额数字数字百分比操作
51%
¥0.0000秒10.37%
57%
¥317.003175分钟17秒20.30%

valueType - 样式类

样式类
序号border 序号代码头像图片操作
1
1
const getData = async params => {
  const data = await getData(params);
  return { list: data.data, ...data };
};
预览
2
2
const getData = async params => {
  const data = await getData(params);
  return { list: data.data, ...data };
};
预览

valueType - 选择类

样式类
状态单选状态单选按钮状态多选状态级联选择器树形下拉框操作
已上线已上线已上线
已上线
front end
,
Javascript
front end
,
Javascript
运行中运行中运行中
运行中
front end
,
Javascript
front end
,
Javascript
  • 第 1-2 条/总共 2 条
  • 1

自定义错误边界

API

ProTable 在 antd 的 Table 上进行了一层封装,支持了一些预设,并且封装了一些行为。这里只列出与 antd Table 不同的 api。

request

request 是 ProTable 最重要的 API,request 会接收一个对象。对象中必须要有 datasuccess,如果需要手动分页 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

属性描述类型默认值
request获取 dataSource 的方法(params?: {pageSize,current},sort,filter) => {data,success,total}-
params用于 request 查询的额外参数,一旦变化会触发重新加载object-
postData对通过 request 获取的数据进行处理(data: T[]) => T[]-
defaultData默认的数据T[]-
dataSourceTable 的数据,protable 推荐使用 request 来加载T[]-
onDataSourceChangeTable 的数据发生改变时触发(dataSource: T[]) => void-
actionRefTable action 的引用,便于自定义触发MutableRefObject<ActionType>-
formRef可以获取到查询表单的 form 实例,用于一些灵活的配置MutableRefObject<FormInstance>-
toolBarRender渲染工具栏,支持返回一个 dom 数组,会自动增加 margin-right(action) => ReactNode[]-
onLoad数据加载完成后触发,会多次触发(dataSource: T[]) => void-
onLoadingChangeloading 被修改时触发,一般是网络请求导致的(loading:boolean)=>void-
onRequestError数据加载失败时触发(error) => void-
tableClassName封装的 table 的 classNamestring-
tableStyle封装的 table 的 styleCSSProperties-
optionstable 工具栏,设为 false 时不显示.传入 function 会点击时触发{{ density?: boolean, fullScreen: boolean | function, reload: boolean | function, setting: boolean | SettingOptionType }}{ fullScreen: false, reload: true, setting: true }
search是否显示搜索表单,传入对象时为搜索表单的配置false | SearchConfig-
defaultSize默认的 sizeSizeType-
dateFormatter转化 moment 格式数据为特定类型,false 不做转化"string" | "number" | ((value: Moment, valueType: string) => string | number) | false"string"
beforeSearchSubmit搜索之前进行一些修改(params:T)=>T-
onSizeChangetable 尺寸发生改变(size: 'default' | 'middle' | 'small') => void-
typepro-table 类型"form"-
formantd form 的配置FormProps-
onSubmit提交表单时触发(params: U) => void-
onReset重置表单时触发() => void-
columnEmptyText空值时的显示,不设置时显示 -, false 可以关闭此功能string | falsefalse
tableRender自定义渲染表格函数(props,dom,domList:{ toolbar,alert,table}) => ReactNode-
toolbar透传 ListToolBar 配置项ListToolBarProps-
tableExtraRender自定义表格的主体函数(props: ProTableProps<T, U>, dataSource: T[]) => ReactNode;-
manualRequest是否需要手动触发首次请求, 配置为 true 时不可隐藏搜索表单booleanfalse
editable可编辑表格的相关配置TableRowEditable-
cardBorderedTable 和 Search 外围 Card 组件的边框boolean | {search?: boolean, table?: boolean}false
debounceTime防抖时间number10
revalidateOnFocus窗口聚焦时自动重新请求booleantrue
columnsState受控的列状态,可以操作显示隐藏columnsStateType-
ErrorBoundary自带了错误处理功能,防止白屏,ErrorBoundary=false 关闭默认错误边界ReactNode内置 ErrorBoundary

RecordCreator

属性描述类型默认值
record需要新增的行数据,一般来说包含唯一 keyT{}
position行增加在哪里,开始或者末尾top | bottombottom
(...buttonProps)antd 的 ButtonPropsButtonProps

ColumnsStateType

属性描述类型默认值
defaultValue列状态的默认值,只有初次生效Record<string, ColumnsState>;-
value列状态的值,支持受控模式Record<string, ColumnsState>;-
onChange列状态的值发生改变之后触发(value:Record<string, ColumnsState>)=>void-
persistenceKey持久化列的 key,用于判断是否是同一个 tablestring | number-
persistenceType持久化列的类类型, localStorage 设置在关闭浏览器后也是存在的,sessionStorage 关闭浏览器后会丢失localStorage | sessionStorage-

Search 搜索表单

属性描述类型默认值
filterType过滤表单类型'query' | 'light''query'
searchText查询按钮的文本string查询
resetText重置按钮的文本string重置
submitText提交按钮的文本string提交
labelWidth标签的宽度'number' |