第40课:Ant Design 高级组件——ProTable、ProForm
Ant Design 的标准组件已经覆盖了大部分 UI 需求,但在企业级后台场景中,表格和表单往往需要查询筛选、分页加载、行内编辑、批量操作等复合功能。Ant Design Pro 组件库(@ant-design/pro-components)在标准组件之上封装了两大核心组件:ProTable——将表格、查询表单、分页、工具栏融为一体的“超级表格”;ProForm——将表单布局、验证、提交、数据转换整合为声明式 JSON 配置的“智能表单”。本节课将分别深入这两个组件的核心 API 和实战模式。
1. ProTable:集查询、表格、分页于一体的超级组件
ProTable 解决的核心痛点是:每个列表页都要重复实现“查询表单 + 表格 + 分页”的组合逻辑。它将这三者封装为一个组件,通过声明列的 valueType 和 request 函数,只需少量代码即可完成一个完整的列表页。
1.1 安装 Pro Components
1 | pnpm add @ant-design/pro-components |
@ant-design/pro-components 是一个整合包,包含了 ProTable、ProForm、ProLayout 等全部 Pro 组件。也可以按需单独安装 @ant-design/pro-table、@ant-design/pro-form。
1.2 基础 ProTable:一个请求函数 + 列定义
1 | import React from 'react'; |
核心 API 解析:
| 属性 / 概念 | 说明 |
|---|---|
columns |
列定义数组。与 Ant Design Table 的 columns 完全兼容,但 ProTable 增加了 valueType、valueEnum、hideInSearch 等 Pro 专属属性。 |
request |
ProTable 的核心。一个异步函数,接收 params(包含分页、排序、查询表单数据),必须返回 { data, success, total } 格式。 |
valueType |
声明列的数据类型,ProTable 据此自动生成查询表单项和表格渲染格式。内置类型包括 text、digit、date、select、money 等 20+ 种。 |
valueEnum |
枚举值映射,配合 valueType: 'select' 使用,自动生成下拉筛选器和表格中的标签渲染。格式为 { key: { text: '显示文字' } } 或 { key: { text: '文字', status: 'Success' } }(status 会生成彩色标签)。 |
hideInSearch |
在自动生成的查询表单中隐藏该列(仅表格可见,不参与搜索)。 |
hideInTable |
在表格中隐藏该列(仅查询表单可见,如纯搜索字段)。 |
search |
查询表单配置:labelWidth 设置标签宽度,span 设置每行表单项数量,defaultCollapsed 是否默认收起。 |
pagination |
分页配置,与 Ant Design Table 的 pagination 一致。 |
toolBarRender |
自定义工具栏渲染函数,通常放置“新增”按钮。 |
rowSelection |
批量选择配置,支持多选和回调。 |
1.3 自动生成的查询表单
ProTable 会根据 columns 中未设置 hideInSearch: true 的列自动生成查询表单。表单的控件类型由 valueType 决定:
valueType |
生成的查询控件 |
|---|---|
text |
Input |
digit |
InputNumber |
select |
Select(选项来自 valueEnum) |
date |
DatePicker |
dateTime |
DatePicker(showTime) |
money |
InputNumber(带货币前缀) |
textarea |
Input.TextArea |
自定义查询表单项:如果内置的 valueType 不满足需求,可以使用 renderFormItem 自定义查询控件。
1 | { |
1.4 工具栏与批量操作
使用 toolBarRender 和 rowSelection 可实现带批量操作的列表页。
1 | <ProTable |
tableAlertRender:表格上方警告提示区域的内容(多选时显示)。tableAlertOptionRender:批量操作按钮区域。toolBarRender:表格工具栏,返回 React 元素数组。
1.5 可编辑表格(行内编辑)
ProTable 支持通过 editable 属性开启行内编辑,无需弹窗即可直接修改数据。
1 | const [editableKeys, setEditableRowKeys] = useState([]); |
editable 配置中的 type 可选 'single'(一次只能编辑一行)或 'multiple'(可同时编辑多行)。每一列可通过 editable: false 禁止编辑。
2. ProForm:声明式表单布局与验证
ProForm 在 Ant Design Form 的基础上提供了JSON 化配置、网格布局、查询表单模式、步骤表单等高级封装。其最大的特点是:表单的布局、验证、提交、数据转换都可以通过配置完成,减少样板代码。
2.1 基础 ProForm 与网格布局
1 | import { ProForm, ProFormText, ProFormSelect, ProFormDigit } from '@ant-design/pro-components'; |
核心 API:
| 组件 / 属性 | 说明 |
|---|---|
ProForm |
表单容器。onFinish 为提交回调(自动处理 validate)。autoFocusFirstInput 自动聚焦第一个输入框。 |
ProForm.Group |
表单分组容器,内部子项默认水平排列(Flex 布局)。 |
ProFormText |
文本输入框(封装 Input)。name 为字段名,label 为标签,rules 为验证规则。 |
ProFormSelect |
下拉选择框。valueEnum 与 ProTable 的列定义一致。 |
ProFormDigit |
数字输入框(封装 InputNumber)。min/max 控制范围。 |
ProForm 内置的常用字段组件:
| 组件 | 对应控件 | 专有属性 |
|---|---|---|
ProFormText |
Input |
— |
ProFormTextArea |
Input.TextArea |
— |
ProFormDigit |
InputNumber |
min、max、fieldProps.precision |
ProFormSelect |
Select |
valueEnum、fieldProps.mode |
ProFormDatePicker |
DatePicker |
— |
ProFormDateTimePicker |
DatePicker (showTime) |
— |
ProFormSwitch |
Switch |
— |
ProFormRadio |
Radio.Group |
options / valueEnum |
ProFormCheckbox |
Checkbox.Group |
options / valueEnum |
ProFormUploadButton |
Upload |
action、max |
ProFormMoney |
InputNumber(货币) |
自动格式化货币符号 |
ProFormCaptcha |
Input + 验证码按钮 |
onGetCaptcha 回调 |
2.2 查询表单模式:search 与 LightFilter
ProForm 内置了查询过滤器的预设样式。设置 layout="inline" 可水平排列,也可使用 search 属性快速生成标准查询表单。
1 | <ProForm |
2.3 动态表单项与依赖联动
利用 ProFormDependency 可以根据其他字段的值动态渲染表单项。
1 | import { ProForm, ProFormDependency, ProFormSelect, ProFormText } from '@ant-design/pro-components'; |
ProFormDependency 的 name 可以监听一个或多个字段,回调函数接收最新的字段值,根据值动态返回组件。
2.4 与 Modal 和 Drawer 的组合
ProForm 支持 modalProps 和 drawerProps,可以一键将表单嵌入到模态框或抽屉中。这使得“点击按钮 → 弹出表单 → 提交数据”的流程变得极为简洁。
1 | import { ProForm, ProFormText, ProFormSelect } from '@ant-design/pro-components'; |
当 modalProps.open 为 true 时,ProForm 会自动渲染为一个模态框。提交成功后,你只需在 onFinish 中调用 onOpenChange(false) 关闭弹窗。整个流程无需手动管理 Modal 的显示/隐藏状态和 Form 的交互。
3. 综合实战:用户管理页面(ProTable + ProForm Modal)
以下示例将 ProTable 和 ProForm 组合为一个完整的用户管理 CRUD 页面:
1 | import React, { useRef, useState } from 'react'; |
协同流程总结:
- ProTable 负责列表展示、查询筛选、分页。
actionRef可用于在外部调用reload()刷新表格。 - 新增/编辑 通过独立的
UserFormModal组件实现,该组件内部使用ProForm配合modalProps自动生成模态框。 - 数据流:父组件
UserManagement管理users状态,ProTable的request基于该状态进行前端筛选;保存表单时更新状态并调用reload()。
课后练习
一、概念自测(选择题 / 填空题)
(单选) ProTable 中,
request函数的返回值必须包含哪些字段?
A.{ data, total }
B.{ data, success, total }
C.{ list, success, total }
D.{ rows, total, pageSize }(单选) 在 ProTable 的列定义中,要让某列在表格中显示但在查询表单中隐藏,应设置哪个属性?
A.hideInTable: true
B.hideInSearch: true
C.search: false
D.hidden: true(填空) ProForm 中使用
______组件可以根据其他字段的值动态渲染表单项,实现字段间的联动。(多选) 以下哪些是 ProForm 内置的字段组件?
A.ProFormText
B.ProFormSelect
C.ProFormSlider
D.ProFormDigit
二、AI 编程任务:编写面向 AI 的提示词
场景:你需要实现一个文章管理页面,包含以下功能:
- 使用
ProTable展示文章列表,列包括:标题、分类(枚举:技术/生活/随笔)、状态(已发布/草稿)、发布时间、操作列(编辑/删除按钮)。 - 表格支持按标题模糊搜索、按分类和状态下拉筛选。
- 点击“新建文章”或“编辑”按钮,使用
ProForm配合modalProps弹出模态框表单,表单包含:标题输入框、分类选择、状态选择、内容文本域。 - 保存时更新列表数据(可使用本地 state 模拟,无需真实 API)。
- 删除时弹出确认提示,删除后刷新列表。
任务要求:请写出一段完整的中文提示词,发送给 AI,使其生成完整的 React 组件文件(可拆分为 2 个文件:列表页 + 表单弹窗)。提示词中需明确指定 ProTable 的列定义、查询筛选配置、ProForm 的字段与验证规则,以及新增/编辑/删除的数据流。
课后练习答案
一、概念自测答案
B
- 解析:ProTable 的
request必须返回{ data: any[], success: boolean, total: number }格式,缺一不可。
- 解析:ProTable 的
B
- 解析:
hideInSearch: true使列在自动生成的查询表单中不可见,但保留在表格中。hideInTable: true则相反。
- 解析:
ProFormDependency- 解析:
ProFormDependency监听一个或多个字段的值变化,回调中根据值动态渲染其他表单项。
- 解析:
A、B、D
- 解析:
ProFormText、ProFormSelect、ProFormDigit均为 ProForm 内置字段组件。ProFormSlider并非内置组件(Ant Design Pro 未提供该封装,需自行结合Slider与ProForm.Item实现)。
- 解析:
二、AI 编程任务参考答案(提示词示例)
示例提示词:
“请生成一个使用 Ant Design Pro Components 的文章管理页面,包含列表和表单弹窗两个组件。要求:
- 安装并使用
@ant-design/pro-components。- **列表组件
ArticleList.jsx**:
- 使用
ProTable,rowKey="id",search={{ labelWidth: 'auto' }}。- 列定义:
title(标题,valueType: 'text')、category(分类,valueType: 'select',valueEnum: { tech: '技术', life: '生活', essay: '随笔' })、status(状态,valueType: 'select',valueEnum: { published: { text: '已发布', status: 'Success' }, draft: { text: '草稿', status: 'Default' } })、publishDate(发布时间,valueType: 'date',hideInSearch: true)、操作列(valueType: 'option',render 返回编辑和删除链接)。request函数:基于本地useState数组articles模拟数据,支持按title(includes模糊匹配)、category、status筛选。初始化 3 条静态数据。toolBarRender返回一个“新建文章”按钮,点击时设置editingArticle为null并打开弹窗。actionRef用于在外部刷新表格。- 编辑:点击行内编辑链接,设置
editingArticle为当前行数据并打开弹窗。- 删除:点击删除链接,使用
Modal.confirm确认后从数组中移除并actionRef.current?.reload()。- **表单弹窗组件
ArticleFormModal.jsx**:
- 接收
open、onOpenChange、initialValues、onFinish四个 Props。- 使用
ProForm,modalProps绑定open、onCancel、title(根据initialValues判断“新建”还是“编辑”)、destroyOnClose。- 表单字段:
title(ProFormText,必填)、category(ProFormSelect,必填,valueEnum同列表)、status(ProFormSelect,必填)、content(ProFormTextArea,可选)。onFinish将表单值传给父组件的保存函数。- 代码完整可运行,组件拆分清晰。输出两个文件的完整内容。”