> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # ProTable - 高级表格 ProTable 的诞生是为了解决项目中需要写很多 table 的样板代码的问题，所以在其中封装了很多常用的逻辑。这些封装可以简单的分类为预设行为与预设逻辑。 依托于 ProForm 的能力，**ProTable** 的查询区可切换多种形态（如 QueryFilter / LightFilter），也可在 `type="form"` 等场景下更像普通表单使用。 ![layout](https://gw.alipayobjects.com/zos/antfincdn/Hw%26ryTueTW/bianzu%2525204.png) ## 何时使用 当你的表格需要与服务端进行交互或者需要多种单元格样式时，ProTable 是不二选择。 ## Issue 回归场景 ## API ProTable 在 antd 的 Table 上进行了一层封装，支持了一些预设，并且封装了一些行为。这里只列出与 antd Table 不同的 API。 ### request `request` 是 ProTable 最重要的 API，`request` 会接收一个对象。对象中必须要有 `data` 和 `success`，如果需要手动分页 `total` 也是必需的。`request` 会接管 `loading` 的设置，同时在查询表单查询时和 `params` 参数发生修改时重新执行。同时查询表单的值和 `params` 参数也会带入。以下是一个例子： ```tsx | pure // 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](/components/schema-form.md#常见-valuetype) 支持。 ### ProTable | 属性 | 描述 | 类型 | 默认值 | 版本 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -- | | actionRef | Table action 的引用，便于自定义触发 | `React.Ref` | - | - | | beforeSearchSubmit | 搜索之前进行一些修改 | `(params: Partial) => any` | - | - | | cardBordered | Table 和 Search 外围 Card 组件的边框 | `boolean \| {search?: boolean, table?: boolean}` | false | - | | cardProps | table 外面卡片的设置 | `ProCardProps \| false` | - | - | | columns | 列配置能力，支持一个数组 | `ProColumns[]` | - | - | | 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"` 等。[配置详情](/components/editable-table.md) | `RowEditableConfig` | - | - | | ErrorBoundary | 自带了错误处理功能，防止白屏，`ErrorBoundary=false` 关闭默认错误边界 | `React.ComponentClass \| false` | 内置 ErrorBoundary | - | | form | type="form" 和搜索表单的 Form 配置，`ignoreRules: false` 可开启查询表单校验，[详见此处](#搜索表单的-rules-校验) | `Omit` | - | - | | formRef | 可以获取到查询表单的 form 实例，用于一些灵活的配置 | `TableFormItem['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](#菜单栏-options-配置) `}}` | `{ reload: true, density: true, setting: true, search: false, fullScreen: false }` | - | | optionsRender | 自定义渲染工具栏选项 | `ToolBarProps['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, filter: Record) => Promise<{data: T[], success?: boolean, total?: number}>` | - | - | | revalidateOnFocus | 窗口聚焦时自动重新请求 | `boolean` | false | - | | rowSelection | 选择项配置 | `TableProps['rowSelection'] & {alwaysShowAlert?: boolean} \| false` | - | - | | search | 是否显示搜索表单，传入对象时为搜索表单的配置 | `false` \| [SearchConfig](#search-搜索表单) | - | - | | searchFormRender | 渲染搜索表单 | `(props: ProTableProps, defaultDom: JSX.Element) => ReactNode` | - | - | | style | 外层容器的样式 | `React.CSSProperties` | - | - | | tableClassName | 封装的 table 的 className | `string` | - | - | | tableExtraRender | table 和搜索表单之间的 dom 渲染 | `(props: ProTableProps, dataSource: T[]) => ReactNode` | - | - | | tableRender | 自定义渲染表格函数 | `(props: ProTableProps, defaultDom: ReactNode, domList: {toolbar: ReactNode, alert: ReactNode, table: ReactNode}) => ReactNode` | - | - | | tableStyle | 封装的 table 的 style | [CSSProperties](https://www.htmlhelp.com/reference/css/properties.html) | - | - | | tableViewRender | 渲染 table 视图，用于定制 ProList，不推荐直接使用；`defaultDom` 可为惰性函数，仅在需要默认 Table 时调用（见 `resolveTableViewDefaultDom`） | `(props: TableProps, defaultDom: JSX.Element \| (() => JSX.Element)) => JSX.Element \| undefined` | - | - | | toolBarRender | 渲染工具栏，支持返回一个 dom 数组，会自动增加 margin-right | `ToolBarProps['toolBarRender'] \| false` | - | - | | toolbar | 透传 `ListToolBar` 配置项 | [ListToolBarProps](#listtoolbarprops) | - | - | | tooltip | 标题旁边的 tooltip | `string \| LabelTooltipType` | - | - | | type | pro-table 类型 | `ProSchemaComponentTypes` | - | - | #### RecordCreator (EditableProTable) | 属性 | 描述 | 类型 | 默认值 | 版本 | | ---------------- | ------------------------------------------------------------------ | -------------------------------------------------------------- | ---------- | -- | | (...buttonProps) | antd 的 [ButtonProps](https://ant.design/components/button-cn/#API) | 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` | - | - | | onChange | 列状态的值发生改变之后触发 | `(value: Record) => void` | - | - | | persistenceKey | 持久化列的 key，用于判断是否是同一个 table | `string \| number` | - | - | | persistenceType | 持久化列的类型，localStorage 设置在关闭浏览器后也是存在的，sessionStorage 关闭浏览器后会丢失 | `'localStorage' \| 'sessionStorage'` | - | - | | value | 列状态的值，支持受控模式 | `Record` | - | - | #### Search 搜索表单 | 属性 | 描述 | 类型 | 默认值 | 版本 | | ---------------------- | --------------------------------------------------- | -------------------------------------------------------------------------- | --------- | -- | | className | 封装的搜索 Form 的 className | `string` | - | - | | collapseRender | 收起按钮的 render | `(collapsed: boolean, showCollapseButton?: boolean) => ReactNode \| false` | - | - | | collapsed | 是否收起 | `boolean` | - | - | | defaultCollapsed | 默认是否收起 | `boolean` | true | - | | defaultColsNumber | 默认一行显示几个表单项（查询表单分栏数） | `number` | - | - | | defaultFormItemsNumber | 默认展示几个表单项 | `number` | - | - | | filterType | 过滤表单类型 | `'query' \| 'light'` | `'query'` | - | | labelWidth | 标签的宽度 | `number \| 'auto'` | 80 | - | | layout | 搜索表单布局 | `'horizontal' \| 'inline' \| 'vertical'` | - | - | | split | 每一行之前是否有分割线，`layout` 为 `vertical` 时生效 | `boolean` | - | - | | onCollapse | 收起按钮的事件 | `(collapsed: boolean) => void` | - | - | | optionRender | 自定义操作栏 | `(searchConfig, formProps, dom) => ReactNode[] \| false` | - | - | | resetText | 重置按钮的文本 | `string` | `'重置'` | - | | searchText | 查询按钮的文本 | `string` | `'查询'` | - | | searchGutter | 查询表单栅格间隔 | `RowProps['gutter']` | - | - | | showHiddenNum | 是否显示收起之后显示隐藏个数 | `boolean` | false | - | | span | 配置查询表单的列数，支持按断点配置（xs/sm/md/lg/xl/xxl），未配置时按屏幕宽度自动分行 | `number \| SpanConfig` | 响应式默认值 | - | `optionRender: false` 只会隐藏操作按钮。如需在输入或选择后自动查询，可在 `form.onValuesChange` 中调用 `formRef.current?.submit()`；请使用 ProTable 的 `debounceTime` 配置请求防抖。 #### 搜索表单的 rules 校验 查询表单为了不阻塞搜索，默认忽略列配置 `formItemProps.rules` 中的校验规则（ProTable 会为查询表单自动注入 `ignoreRules: true`）。如果希望查询表单也执行校验，需要显式开启： ```tsx | pure ``` 开启后列上的 `formItemProps.rules`（如 `required`）会在提交查询时生效；校验不通过将阻止搜索请求。可编辑表格（`editable`）中的行内校验不受此配置影响。 #### ColConfig ```tsx | pure const defaultSpanConfig = { xs: 24, sm: 24, md: 12, lg: 12, xl: 8, xxl: 6, }; ``` > 实际断点值来自 antd 设计 token（screenSMMin 等），可通过 ConfigProvider 主题定制；以上为默认 token 下的参考值。 #### 菜单栏 options 配置 ```tsx | pure export type OptionsType = | ((e: React.MouseEvent, action?: ActionType) => void) | boolean; export type OptionConfig = { density?: boolean; fullScreen?: OptionsType; reload?: OptionsType; setting?: boolean | SettingOptionType; search?: (OptionSearchProps & { name?: string }) | boolean; reloadIcon?: React.ReactNode; densityIcon?: React.ReactNode; }; export type SettingOptionType = { draggable?: boolean; checkable?: boolean; showListItemOption?: boolean; checkedReset?: boolean; listsHeight?: number; extra?: React.ReactNode; children?: React.ReactNode; settingIcon?: React.ReactNode; /** #9620: 自定义列设置面板列表项标题渲染，可取消固定宽度实现单行自适应 */ listItemTitleRender?: ( title: React.ReactNode, column: { key?: React.Key; title?: React.ReactNode; [key: string]: any }, ) => React.ReactNode; }; ``` #### ActionRef 手动触发 有时我们要手动触发 table 的 reload 等操作，可以使用 actionRef。 | 方法 | 描述 | 类型 | | -------------- | -------------------- | -------------------------------------------------------------------------------- | | reload | 刷新表格，如果传入 true 则重置页码 | `(resetPageIndex?: boolean) => Promise` | | reloadAndRest | 刷新并清空，页码也会重置，不包括表单 | `() => Promise` | | reset | 重置到默认值，包括表单 | `() => void` | | clearSelected | 清空选中项 | `() => void` | | startEditable | 开始编辑行 | `(rowKey: Key) => boolean` | | cancelEditable | 取消编辑行 | `(rowKey: Key) => boolean` | | scrollTo | 滚动到指定位置 | `(arg: number \| { index?: number; key?: Key; top?: number }) => void` | | fullScreen | 切换全屏 | `() => void` | | setPageInfo | 设置分页信息 | `(page: Partial) => void` | ```tsx | pure // 示例 const ref = useRef(); ; // 刷新 ref.current?.reload(); // 刷新并清空,页码也会重置，不包括表单 ref.current?.reloadAndRest(); // 重置到默认值，包括表单 ref.current?.reset(); // 清空选中项 ref.current?.clearSelected(); // 开始编辑 ref.current?.startEditable(rowKey); // 结束编辑 ref.current?.cancelEditable(rowKey); ``` ### Columns 列定义 > 请求远程数据比较复杂，详细可以看[这里](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params)。 > **💡** 本地排序/筛选与 request > 当你提供了 `request` 时，ProTable 默认会在筛选/排序变化后触发一次重新请求，并把服务端需要的 `sort` / `filter` 透传给 `request(params, sort, filter)`。 如果你希望**前端本地**排序/筛选（不触发 `request`），请使用以下写法： - **本地筛选**：同时配置 `filters` + `onFilter`（函数或 `true`）。 - **本地排序**：将 `sorter` 设为比较函数，或 `{ compare }`。不要使用 `sorter: true`（这代表服务端排序）。 排序后 Ant Design 会为当前方向添加 `.ant-table-column-sorter-up.active` 或 `.ant-table-column-sorter-down.active`，并在表头设置 `aria-sort`。如排序正常但颜色不变，请优先检查业务全局 CSS 是否覆盖 `.active`，以及 ConfigProvider 的主题 token。 ::: | 属性 | 描述 | 类型 | 默认值 | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------ | | title | 与 antd 中基本相同，但是支持通过传入一个方法 | `ReactNode \| ((config: ProColumnType, type: ProTableTypes) => ReactNode)` | - | | tooltip | 会在 title 之后展示一个 icon，hover 之后提示一些信息 | `LabelTooltipType \| string` | - | | ellipsis | 是否自动省略超出列宽的内容。`true` 且未开启 `copyable` 时使用 antd Table 原生 CSS 省略，不提供 Tooltip 浮层，但可能显示浏览器原生 title 提示。传入对象或同时开启 `copyable` 时，默认只读内容使用 Typography 渲染，内容被省略后悬浮显示提示；对象中的 `tooltip` 默认为开启，设为 `false` 可关闭，或传入 Tooltip 属性自定义提示 | `boolean \| { tooltip?: boolean \| TooltipProps }` | - | | copyable | 是否支持复制 | `boolean` | - | | autoMerge | 同值单元格纵向自动合并：当前页内该列连续相同值的单元格自动合并；用户 `onCell` 显式返回的 `rowSpan` 优先 | `boolean` | - | | valueEnum | 值的枚举，会自动转化把值当成 key 来取出要显示的内容 | [valueEnum](/components/schema-form.md#valueenum) | - | | valueType | 值的类型，会生成不同的渲染器 | [`valueType`](/components/schema-form.md#常见-valuetype) | `text` | | order | 查询表单中的权重，权重大排序靠前 | `number` | - | | fieldProps | 查询表单的 props，会透传给表单项，如果渲染出来是 Input，就支持 Input 的所有 props，同理如果是 select，也支持 select 的所有 props。也支持方法传入 | `(form,config)=>Record \| Record` | - | | `formItemProps` | 传递给 Form.Item 的配置，可以配置 rules，但查询表单默认忽略 rules，需配置 [`form={{ ignoreRules: false }}`](#搜索表单的-rules-校验) | `(form,config)=>formItemProps` \| `formItemProps` | - | | renderText | 类似 table 的 render，但是必须返回 string，如果只是希望转化枚举，可以使用 [valueEnum](/components/schema-form.md#valueenum) | `(text: any,record: T,index: number,action: UseFetchDataAction) => string` | - | | render | 类似 table 的 render，第一个参数变成了 dom，增加了第四个参数 action | `(text: ReactNode,record: T,index: number,action: UseFetchDataAction) => ReactNode \| ReactNode[]` | - | | formItemRender | 渲染查询表单的输入组件 | `(item,{ type, defaultRender, formItemProps, fieldProps, ...rest },form,action) => ReactNode` | - | | search | 配置列的搜索相关，false 为隐藏 | `boolean` \| `{ transform: (value: any) => any }` | true | | sorter | 与 antd 中基本相同，新增支持字串覆盖该栏位请求时字段 | `function \| boolean \| string \| { compare: function, multiple: number }` | - | | search.transform | 转化值的 key, 一般用于时间区间的转化 | `(value: any) => any` | - | | [editable](/components/editable-table.md) | 在编辑表格中是否可编辑的，函数的参数和 table 的 render 一样 | `boolean` \| `(text: any, record: T,index: number) => boolean` | - | | colSize | 一个表单项占用的格子数量，`占比= colSize*span`，`colSize` 默认为 1 ，`span` 为 8，`span`是`form={{span:8}}` 全局设置的 | `number` | - | | hideInTable | 在 Table 中不展示此列 | `boolean` | - | | hideInForm | 在 Form 中不展示此列 | `boolean` | - | | hideInDescriptions | 在 Descriptions 中不展示此列 | `boolean` | - | | hideInSetting | 不在配置工具中显示 | `boolean` | - | | filters | 表头的筛选菜单项，当值为 true 时，自动使用 valueEnum 生成 | `boolean` \| `object[]` | false | | onFilter | 筛选表单，为 true 时使用 ProTable 自带的，为 false 时关闭本地筛选 | `(value, record) => boolean` \| `false` | false | | onCell | 与 antd Table 相同，设置单元格属性，返回 `colSpan` / `rowSpan` 可实现合并单元格（值为 0 时不渲染该单元格），写法与 [antd 合并单元格示例](https://ant.design/components/table-cn#components-table-demo-colspan-rowspan) 完全一致 | `(record: T, index?: number) => React.TdHTMLAttributes` | - | | request | 从服务器请求枚举 | [request](https://procomponents.ant.design/components/schema#request-%E5%92%8C-params) | - | | initialValue | 查询表单项初始值 | `any` | - | | disable | 列设置中`disabled`的状态 | `boolean` \| `{ checkbox: boolean; }` | - | | readonly | 只读 | `boolean` | - | | listSlot | 列表键（ProList 插槽），指定该列映射到列表项的插槽位置，如 `title`、`avatar`、`description`、`subTitle`、`content`、`actions`、`aside`、`type`，私有属性 | `string` | - | #### 合并单元格示例 列配置 `autoMerge` 或表级 `mergeFields` 可按字段自动合并当前页连续同值的单元格（类似 Excel 单元格合并），无需手动计算 `rowSpan`；排序、筛选、分页切换后自动重算。合并场景建议开启 `bordered` 全边框，合并区域视觉边界更完整（bordered 与合并逻辑正交，不默认开启）。注意：树形数据（children）下不生效；可编辑表格中编辑中的行不参与合并；本地排序/筛选激活时，若数据源被翻页或刷新替换，该页会跳过自动合并以避免按过期顺序计算，待下一次表格变更捕获新数据后自动恢复。 ```tsx file="/demos/table/auto-merge.tsx" title="autoMerge / mergeFields：同值单元格自动合并" preview import type { ProColumns } from '@ant-design/pro-components'; import { ProTable } from '@ant-design/pro-components'; import { Divider } from 'antd'; type Row = { key: string; city: string; area: string; name: string; amount: number; }; const dataSource: Row[] = [ { key: '1', city: '上海', area: '浦东', name: '张三', amount: 100 }, { key: '2', city: '上海', area: '浦东', name: '李四', amount: 200 }, { key: '3', city: '上海', area: '闵行', name: '赵六', amount: 150 }, { key: '4', city: '北京', area: '海淀', name: '王五', amount: 300 }, { key: '5', city: '北京', area: '朝阳', name: '孙七', amount: 260 }, ]; /** 列配置 align: 'center' 让单元格内容水平居中(antd 原生列能力) */ const columns: ProColumns[] = [ { title: '城市', dataIndex: 'city', align: 'center' }, { title: '区域', dataIndex: 'area', align: 'center' }, { title: '姓名', dataIndex: 'name', align: 'center' }, { title: '金额', dataIndex: 'amount', align: 'center' }, ]; /** * 同值单元格纵向自动合并（#9770）： * - 列维度：ProColumns 上配置 autoMerge: true * - 表维度：mergeFields 按数组顺序多级依次合并（先城市、后区域） * 只合并当前页内连续同值，排序、筛选、分页切换后自动重算； * 手动 onCell 显式返回的 rowSpan 优先于自动合并结果。 * * bordered 与合并逻辑正交、不默认开启；合并场景建议开启全边框， * 合并区域视觉边界更完整（见前两个示例），第三个示例为无边框效果。 */ export default () => ( <> columns={columns.map((column) => column.dataIndex === 'city' ? { ...column, autoMerge: true } : column, )} dataSource={dataSource} rowKey="key" search={false} options={false} pagination={false} bordered headerTitle="列配置 autoMerge（建议开启全边框）" /> columns={columns} mergeFields={['city', 'area']} dataSource={dataSource} rowKey="key" search={false} options={false} pagination={false} bordered headerTitle="mergeFields 多级合并（建议开启全边框）" /> columns={columns} mergeFields={['city', 'area']} dataSource={dataSource} rowKey="key" search={false} options={false} pagination={false} headerTitle="未开启 bordered 的合并（antd 默认无边框）" /> ); ``` `onCell` 返回 `rowSpan` 可纵向合并团队单元格；被覆盖的下一行返回 0。 ```tsx file="/demos/table/colspan-rowspan.tsx" title="onCell.rowSpan：纵向合并" preview import type { ProColumns } from '@ant-design/pro-components'; import { ProTable } from '@ant-design/pro-components'; type Row = { key: string; team: string; member: string; task: string; }; const dataSource: Row[] = [ { key: '1', team: '前端组', member: '张三', task: '首页' }, { key: '2', team: '', member: '李四', task: '表单' }, { key: '3', team: '后端组', member: '王五', task: '接口' }, ]; const columns: ProColumns[] = [ { title: '团队', dataIndex: 'team', onCell: (_, index = 0) => index === 0 ? { rowSpan: 2 } : index === 1 ? { rowSpan: 0 } : {}, }, { title: '成员', dataIndex: 'member' }, { title: '任务', dataIndex: 'task' }, ]; export default () => ( columns={columns} dataSource={dataSource} rowKey="key" search={false} options={false} pagination={false} scroll={{ x: 480 }} /> ); ``` `onCell` 返回 `colSpan` 可横向合并“项目”和“明细”两列；被覆盖的单元格返回 0。 ```tsx file="/demos/table/colspan.tsx" title="onCell.colSpan：横向合并" preview import type { ProColumns } from '@ant-design/pro-components'; import { ProTable } from '@ant-design/pro-components'; type Row = { key: string; item: string; detail: string; count: number; }; const dataSource: Row[] = [ { key: '1', item: '本周合计', detail: '', count: 8 }, { key: '2', item: '首页', detail: '设计任务', count: 3 }, ]; const columns: ProColumns[] = [ { title: '项目', dataIndex: 'item', onCell: (record) => (record.key === '1' ? { colSpan: 2 } : {}), }, { title: '明细', dataIndex: 'detail', onCell: (record) => (record.key === '1' ? { colSpan: 0 } : {}), }, { title: '数量', dataIndex: 'count' }, ]; export default () => ( columns={columns} dataSource={dataSource} rowKey="key" search={false} options={false} pagination={false} scroll={{ x: 480 }} /> ); ``` ### valueType 值类型 ProTable 封装了一些常用的值类型来减少重复的 `render` 操作，配置一个 [`valueType`](/components/schema-form.md#常见-valuetype) 即可展示格式化响应的数据。 ### 批量操作 与 antd 相同，批量操作需要设置 `rowSelection` 来开启，与 antd 不同的是，pro-table 提供了一个 alert 用于承载一些信息。你可以通过 `tableAlertRender`和 `tableAlertOptionRender` 来对它进行自定义。设置或者返回 false 即可关闭。 | 属性 | 描述 | 类型 | 默认值 | 版本 | | ---------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- | --- | -- | | alwaysShowAlert | 总是展示 alert，默认无选择不展示（`rowSelection` 内置属性） | `boolean` | - | - | | tableAlertOptionRender | 自定义批量操作工具栏右侧选项区域，false 时不显示 | `({ selectedRowKeys: Key[], selectedRows: T[], onCleanSelected: () => void }) => ReactNode \| false` | - | - | | tableAlertRender | 自定义批量操作工具栏左侧信息区域，false 时不显示 | `({ selectedRowKeys: Key[], selectedRows: T[], onCleanSelected: () => void }) => ReactNode \| false` | - | - | ### 搜索表单 ProTable 会根据列来生成一个 Form，用于筛选列表数据，最后的值会根据通过 `request` 的第一个参数返回，看起来就像。 ```jsx | pure {all params}}> ``` 按照规范，table 的表单不需要任何的必选参数，所有点击搜索和重置都会触发 `request` 来发起一次查询。 Form 的列是根据 `valueType` 来生成不同的类型，详细的值类型请查看[通用配置](/components/schema-form.md#常见-valuetype)。 > valueType 为 index, indexBorder, option 或者没有 dataIndex 和 key 的列将会被忽略。 ### 列表工具栏 用于自定义表格的工具栏部分。 #### ListToolBarProps 列表和表格的工具栏配置属性 | 参数 | 说明 | 类型 | 默认值 | 版本 | | ------------ | ------------------------------------------ | -------------------------------------------------- | ----- | -- | | actions | 操作区 | `ReactNode[]` | - | - | | filter | 过滤区，通常配合 `LightFilter` 使用 | `ReactNode` | - | - | | menu | 菜单配置 | `ListToolBarMenu` | - | - | | multipleLine | 是否多行展示 | `boolean` | false | - | | search | 查询区，支持传入 Input.Search 配置或自定义节点，`false` 时隐藏 | `SearchProps & {onSearch} \| ReactNode \| boolean` | - | - | | onSearch | 查询区搜索触发 | `(keyWords: string) => void` | - | - | | settings | 设置区 | `(ReactNode \| Setting)[]` | - | - | | subTitle | 子标题 | `ReactNode` | - | - | | tabs | 标签页配置，仅当 `multipleLine` 为 true 时有效 | `ListToolBarTabs` | - | - | | title | 标题 | `ReactNode` | - | - | | tooltip | tooltip 描述 | `string \| LabelTooltipType` | - | - | SearchProps 为 antd 的 [Input.Search](https://ant.design/components/input-cn/#Input.Search) 的属性。 #### Setting | 参数 | 说明 | 类型 | 默认值 | 版本 | | ------- | ---------- | ---------------------------- | --- | -- | | icon | 图标 | `ReactNode` | - | - | | key | 操作唯一标识 | `string` | - | - | | onClick | 设置被触发 | `(key: string) => void` | - | - | | tooltip | tooltip 描述 | `LabelTooltipType \| string` | - | - | #### ListToolBarMenu | 参数 | 说明 | 类型 | 默认值 | 版本 | | --------- | ------- | ------------------------------------------------------------ | ---------- | -- | | activeKey | 当前值 | `React.Key` | - | - | | items | 菜单项 | `{ key: React.Key; label: ReactNode; disabled?: boolean }[]` | - | - | | onChange | 切换菜单的回调 | `(activeKey: React.Key) => void` | - | - | | type | 类型 | `'inline' \| 'dropdown' \| 'tab'` | `'inline'` | - | #### ListToolBarTabs | 参数 | 说明 | 类型 | 默认值 | 版本 | | --------- | ------- | ----------------------------------- | --- | -- | | activeKey | 当前选中项 | `string` | - | - | | items | 菜单项 | `TabPaneProps & { key?: string }[]` | - | - | | onChange | 切换菜单的回调 | `(activeKey: string) => void` | - | - | #### TableDropdown | 参数 | 说明 | 类型 | 默认值 | 版本 | | -------- | ------- | -------------------------------------------------------- | --- | -- | | menus | 菜单配置 | `{ key: string; name: ReactNode; disabled?: boolean }[]` | - | - | | onSelect | 选中菜单的回调 | `(key: string) => void` | - | - |