Ant Design Form 使用完全指南：如何构建带数据校验的企业级表单-开发者社区

Ant Design Form 使用完全指南：如何构建带数据校验的企业级表单

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design

在企业级 React 项目中，表单是最高频的交互场景。Ant Design 的Form（表单）组件原生提供数据收集、数据校验与提交能力，内置输入框、单选、复选、下拉选择等控件，一套Form.create()+getFieldProps()+validateFields()的组合即可覆盖 90% 的业务需求。本指南面向新手和普通用户，带你快速上手 Ant Design Form，从零搭出一个带实时数据校验、提交拦截与重置功能的企业级表单。

一、3 分钟认识 Form 的核心结构

Form 组件由三部分组成：Form（容器）、Form.Item（表单域）、getFieldProps（双向绑定）。理解这三者，就理解了 Ant Design Form 的全部。

概念	作用	说明
`Form.create()`	增强类组件	包装后组件自动拥有`this.props.form`
`getFieldProps(id)`	双向绑定	为控件注入`value`与`onChange`，无需手写
`validateFields()`	数据校验	提交前统一校验并回传`errors`与`values`
`Form.Item`	表单域	负责标签布局、错误提示、校验状态图标

💡 关键认知：Ant Design Form 不直接管"值"，而是管"值的变化 + 校验规则"。你声明rules，它负责在合适的时机触发校验并渲染错误提示。

核心源码入口在 components/form/index.jsx，Form.create在此对rc-form的createDOMForm做了一层包装（见 index.jsx#L7-L15）。

二、一步到位：创建表单的完整步骤

1. 用 Form.create 包装组件

以类组件为例，最后用Form.create()增强，即可获得this.props.form。

class MyForm extends React.Component { // this.props.form 由此而来 } MyForm = Form.create()(MyForm);

2. 选择布局：水平 / 行内

Form 提供两种排列，通过horizontal与inline控制：

水平排列（horizontal）：label与控件同行，适合后台管理、注册页等标准表单；
行内排列（inline）：控件表现为inline-block，适合登录、搜索等紧凑场景。

两种布局分别可参考示例 demo/horizontal-form.md 与 demo/inline-form.md。布局类名的生成逻辑见 Form.jsx#L11-L23。

3. 绑定控件：getFieldProps

在render中调用getFieldProps(id, options)，把返回属性展开到控件上即可实现双向绑定，rules就在这里声明。

const { getFieldProps } = this.props.form; <Input type="password" {...getFieldProps('pass', { initialValue: '', rules: [{ required: true, whitespace: true, message: '请填写密码' }] })} />

⚠️ 注意：getFieldProps已注入value与onChange，不要再手动设置这两个属性；初始值用initialValue而非defaultValue。

三、数据校验：让表单真正"企业级"的关键

数据校验是 Ant Design Form 最核心的价值。它基于rules数组声明规则，由 Form 在不同trigger时机自动执行。

常用校验规则速查

规则	含义	示例
`required: true`	必填	`{ required: true, message: '用户名不能为空' }`
`min / max`	长度约束	`{ min: 5, message: '至少 5 个字符' }`
`type`	类型校验	`{ type: 'email', message: '请输入正确邮箱' }`
`whitespace`	不允许纯空格	`{ whitespace: true }`
`validator`	自定义函数校验	见下方

控制校验时机：trigger 与 validateTrigger

通过trigger决定何时收集值，validateTrigger决定何时校验。把"失焦必填 + 输入格式"组合，体验最友好：

getFieldProps('email', { validate: [ { rules: [{ required: true }], trigger: 'onBlur' }, { rules: [{ type: 'email', message: '请输入正确的邮箱地址' }], trigger: ['onBlur', 'onChange'] } ] });

自定义异步校验

对于"用户名是否被占用"这类需要请求后端才能判断的场景，用validator函数，在callback中返回错误即可。完整示例见 demo/validate-basic.md，其中userExists演示了setTimeout模拟异步返回"该用户名已被占用"。

联动校验：改密码时自动重校确认密码

当"密码"变化时主动触发"确认密码"重校，避免用户填完才报错。参考 demo/validate-customized.md，在checkPass中调用form.validateFields(['rePass'], { force: true })即可实现联动。

四、提交、取值与重置：三种常用操作

需求	方法	说明
提交前整体校验	`validateFields(callback)`	回调`(errors, values)`，有`errors`则拦截
只取值不校验	`getFieldsValue()`/`getFieldValue(id)`	弹窗、只读场景
一键重置	`resetFields()`	清空值与错误状态

提交的标准写法：

handleSubmit(e) { e.preventDefault(); this.props.form.validateFields((errors, values) => { if (!!errors) return; // 校验未通过，拦截提交 console.log('提交数据：', values); }); }

在弹窗里使用 Form 时，点击"确定"直接getFieldsValue()取值即可，见 demo/form-in-modal.md。

五、进阶：让错误提示与状态图标自动呈现

Form.Item会自动根据校验规则渲染help文案与validateStatus（success/warning/error/validating），无需手动计算。想让字段右侧显示校验状态图标，加上hasFeedback即可。

错误文案自动拼接逻辑：FormItem.jsx#L21-L29
校验状态判定逻辑：FormItem.jsx#L55-L68

Form.Item 属性	作用
`label`	标签文本
`labelCol`/`wrapperCol`	标签与控件的栅格布局
`help`	提示信息（不设置则由校验自动生成）
`extra`	额外提示，可与错误信息同时出现
`hasFeedback`	展示校验状态图标