高性能表单控件，自带数据域管理。包含数据录入、校验以及对应样式。

何时使用

• 用于创建一个实体或收集信息。
• 需要对输入的数据类型进行校验时。

代码演示

API

通用属性参考：通用属性

Form

validateMessages

Form 为验证提供了默认的错误提示信息，你可以通过配置 validateMessages 属性，修改对应的提示模板。一种常见的使用方式，是配置国际化提示信息：

const validateMessages = {
  required: "'${name}' 是必选字段",
  // ...
};

<Form validateMessages={validateMessages} />;

此外，ConfigProvider 也提供了全局化配置方案，允许统一配置错误提示模板：

const validateMessages = {
  required: "'${name}' 是必选字段",
  // ...
};

<ConfigProvider form={{ validateMessages }}>
  <Form />
</ConfigProvider>;

Form.Item

表单字段组件，用于数据双向绑定、校验、布局等。

被设置了 name 属性的 Form.Item 包装的控件，表单控件会自动添加 value（或 valuePropName 指定的其他属性） onChange（或 trigger 指定的其他属性），数据同步将被 Form 接管，这会导致以下结果：

1. 你不再需要也不应该用 onChange 来做数据收集同步（你可以使用 Form 的 onValuesChange），但还是可以继续监听 onChange 事件。
2. 你不能用控件的 value 或 defaultValue 等属性来设置表单域的值，默认值可以用 Form 里的 initialValues 来设置。注意 initialValues 不能被 setState 动态更新，你需要用 setFieldsValue 来更新。
3. 你不应该用 setState，可以使用 form.setFieldsValue 来动态改变表单值。

dependencies

当字段间存在依赖关系时使用。如果一个字段设置了 dependencies 属性。那么它所依赖的字段更新时，该字段将自动触发更新与校验。一种常见的场景，就是注册用户表单的“密码”与“确认密码”字段。“确认密码”校验依赖于“密码”字段，设置 dependencies 后，“密码”字段更新会重新触发“校验密码”的校验逻辑。你可以参考具体例子。

dependencies 不应和 shouldUpdate 一起使用，因为这可能带来更新逻辑的混乱。

FeedbackIcons

({ status: ValidateStatus, errors: ReactNode, warnings: ReactNode }) => Record<ValidateStatus, ReactNode>

shouldUpdate

Form 通过增量更新方式，只更新被修改的字段相关组件以达到性能优化目的。大部分场景下，你只需要编写代码或者与 dependencies 属性配合校验即可。而在某些特定场景，例如修改某个字段值后出现新的字段选项、或者纯粹希望表单任意变化都对某一个区域进行渲染。你可以通过 shouldUpdate 修改 Form.Item 的更新逻辑。

当 shouldUpdate 为 true 时，Form 的任意变化都会使该 Form.Item 重新渲染。这对于自定义渲染一些区域十分有帮助，要注意 Form.Item 里包裹的子组件必须由函数返回，否则 shouldUpdate 不会起作用：

相关issue：#34500

<Form.Item shouldUpdate>
  {() => {
    return <pre>{JSON.stringify(form.getFieldsValue(), null, 2)}</pre>;
  }}
</Form.Item>

你可以参考示例查看具体使用场景。

当 shouldUpdate 为方法时，表单的每次数值更新都会调用该方法，提供原先的值与当前的值以供你比较是否需要更新。这对于是否根据值来渲染额外字段十分有帮助：

<Form.Item shouldUpdate={(prevValues, curValues) => prevValues.additional !== curValues.additional}>
  {() => {
    return (
      <Form.Item name="other">
        <Input />
      </Form.Item>
    );
  }}
</Form.Item>

你可以参考示例查看具体使用场景。

messageVariables

你可以通过 messageVariables 修改 Form.Item 的默认验证信息。

<Form>
  <Form.Item
    messageVariables={{ another: 'good' }}
    label="user"
    rules={[{ required: true, message: '${another} is required' }]}
  >
    <Input />
  </Form.Item>
  <Form.Item
    messageVariables={{ label: 'good' }}
    label={<span>user</span>}
    rules={[{ required: true, message: '${label} is required' }]}
  >
    <Input />
  </Form.Item>
</Form>

Form.List

为字段提供数组化管理。

<Form.List>
  {(fields) =>
    fields.map((field) => (
      <Form.Item {...field}>
        <Input />
      </Form.Item>
    ))
  }
</Form.List>

注意：Form.List 下的字段不应该配置 initialValue，你始终应该通过 Form.List 的 initialValue 或者 Form 的 initialValues 来配置。

operation

Form.List 渲染表单相关操作函数。

Form.ErrorList

4.7.0 新增。错误展示组件，仅限配合 Form.List 的 rules 一同使用。参考示例。

Form.Provider

提供表单间联动功能，其下设置 name 的 Form 更新时，会自动触发对应事件。查看示例。

<Form.Provider
  onFormFinish={(name) => {
    if (name === 'form1') {
      // Do something...
    }
  }}
>
  <Form name="form1">...</Form>
  <Form name="form2">...</Form>
</Form.Provider>

FormInstance

validateFields

export interface ValidateConfig {
  // 5.5.0 新增。仅校验内容而不会将错误信息展示到 UI 上。
  validateOnly?: boolean;
  // 5.9.0 新增。对提供的 `nameList` 与其子路径进行递归校验。
  recursive?: boolean;
  // 5.11.0 新增。校验 dirty 的字段（touched + validated）。
  // 使用 `dirty` 可以很方便的仅校验用户操作过和被校验过的字段。
  dirty?: boolean;
}

返回示例：

validateFields()
  .then((values) => {
    /*
  values:
    {
      username: 'username',
      password: 'password',
    }
  */
  })
  .catch((errorInfo) => {
    /*
    errorInfo:
      {
        values: {
          username: 'username',
          password: 'password',
        },
        errorFields: [
          { name: ['password'], errors: ['Please input your Password!'] },
        ],
        outOfDate: false,
      }
    */
  });

Hooks

Form.useForm

type Form.useForm = (): [FormInstance]

创建 Form 实例，用于管理所有数据状态。

Form.useFormInstance

type Form.useFormInstance = (): FormInstance

4.20.0 新增，获取当前上下文正在使用的 Form 实例，常见于封装子组件消费无需透传 Form 实例：

const Sub = () => {
  const form = Form.useFormInstance();

  return <Button onClick={() => form.setFieldsValue({})} />;
};

export default () => {
  const [form] = Form.useForm();

  return (
    <Form form={form}>
      <Sub />
    </Form>
  );
};

Form.useWatch

type Form.useWatch = (namePath: NamePath, formInstance?: FormInstance | WatchOptions): Value

用于直接获取 form 中字段对应的值。通过该 Hooks 可以与诸如 useSWR 进行联动从而降低维护成本：

const Demo = () => {
  const [form] = Form.useForm();
  const userName = Form.useWatch('username', form);

  const { data: options } = useSWR(`/api/user/${userName}`, fetcher);

  return (
    <Form form={form}>
      <Form.Item name="username">
        <AutoComplete options={options} />
      </Form.Item>
    </Form>
  );
};

如果你的组件被包裹在 Form.Item 内部，你可以省略第二个参数，Form.useWatch 会自动找到上层最近的 FormInstance。

useWatch 默认只监听在 Form 中注册的字段，如果需要监听非注册字段，可以通过配置 preserve 进行监听：

const Demo = () => {
  const [form] = Form.useForm();

  const age = Form.useWatch('age', { form, preserve: true });
  console.log(age);

  return (
    <div>
      <Button onClick={() => form.setFieldValue('age', 2)}>Update</Button>
      <Form form={form}>
        <Form.Item name="name">
          <Input />
        </Form.Item>
      </Form>
    </div>
  );
};

Form.Item.useStatus

type Form.Item.useStatus = (): { status: ValidateStatus | undefined, errors: ReactNode[], warnings: ReactNode[] }

4.22.0 新增，可用于获取当前 Form.Item 的校验状态，如果上层没有 Form.Item，status 将会返回 undefined。5.4.0 新增 errors 和 warnings，可用于获取当前 Form.Item 的错误信息和警告信息：

const CustomInput = ({ value, onChange }) => {
  const { status, errors } = Form.Item.useStatus();
  return (
    <input
      value={value}
      onChange={onChange}
      className={`custom-input-${status}`}
      placeholder={(errors.length && errors[0]) || ''}
    />
  );
};

export default () => (
  <Form>
    <Form.Item name="username">
      <CustomInput />
    </Form.Item>
  </Form>
);

与其他获取数据的方式的区别

Form 仅会对变更的 Field 进行刷新，从而避免完整的组件刷新可能引发的性能问题。因而你无法在 render 阶段通过 form.getFieldsValue 来实时获取字段值，而 useWatch 提供了一种特定字段访问的方式，从而使得在当前组件中可以直接消费字段的值。同时，如果为了更好的渲染性能，你可以通过 Field 的 renderProps 仅更新需要更新的部分。而当当前组件更新或者 effect 都不需要消费字段值时，则可以通过 onValuesChange 将数据抛出，从而避免组件更新。

Interface

NamePath

string | number | (string | number)[]

GetFieldsValue

getFieldsValue 提供了多种重载方法：

getFieldsValue(nameList?: true | NamePath[], filterFunc?: FilterFunc)

当不提供 nameList 时，返回所有注册字段，这也包含 List 下所有的值（即便 List 下没有绑定 Item）。

当 nameList 为 true 时，返回 store 中所有的值，包含未注册字段。例如通过 setFieldsValue 设置了不存在的 Item 的值，也可以通过 true 全部获取。

当 nameList 为数组时，返回规定路径的值。需要注意的是，nameList 为嵌套数组。例如你需要某路径值应该如下：

// 单个路径
form.getFieldsValue([['user', 'age']]);

// 多个路径
form.getFieldsValue([
  ['user', 'age'],
  ['preset', 'account'],
]);

getFieldsValue({ strict?: boolean, filter?: FilterFunc })

5.8.0 新增接受配置参数。当 strict 为 true 时会仅匹配 Item 的值。例如 { list: [{ bamboo: 1, little: 2 }] } 中，如果 List 仅绑定了 bamboo 字段，那么 getFieldsValue({ strict: true }) 会只获得 { list: [{ bamboo: 1 }] }。

FilterFunc

用于过滤一些字段值，meta 会返回字段相关信息。例如可以用来获取仅被用户修改过的值等等。

type FilterFunc = (meta: { touched: boolean; validating: boolean }) => boolean;

FieldData

Rule

Rule 支持接收 object 进行配置，也支持 function 来动态获取 form 的数据：

type Rule = RuleConfig | ((form: FormInstance) => RuleConfig);

WatchOptions

主题变量（Design Token）

FAQ

Switch、Checkbox 为什么不能绑定数据？

Form.Item 默认绑定值属性到 value 上，而 Switch、Checkbox 等组件的值属性为 checked。你可以通过 valuePropName 来修改绑定的值属性。

<Form.Item name="fieldA" valuePropName="checked">
  <Switch />
</Form.Item>

自定义 validator 没有效果

这是由于你的 validator 有错误导致 callback 没有执行到。你可以选择通过 async 返回一个 promise 或者使用 try...catch 进行错误捕获：

validator: async (rule, value) => {
  throw new Error('Something wrong!');
}

// or

validator(rule, value, callback) => {
  try {
    throw new Error('Something wrong!');
  } catch (err) {
    callback(err);
  }
}

name 为数组时的转换规则？

当 name 为数组时，会按照顺序填充路径。当存在数字且 form store 中没有该字段时会自动转变成数组。因而如果需要数组为 key 时请使用 string 如：['1', 'name']。

为何在 Modal 中调用 form 控制台会报错？

Warning: Instance created by useForm is not connect to any Form element. Forget to pass form prop?

这是因为你在调用 form 方法时，Modal 还未初始化导致 form 没有关联任何 Form 组件。你可以通过给 Modal 设置 forceRender 将其预渲染。示例点击此处。

为什么 Form.Item 下的子组件 defaultValue 不生效？

当你为 Form.Item 设置 name 属性后，子组件会转为受控模式。因而 defaultValue 不会生效。你需要在 Form 上通过 initialValues 设置默认值。

为什么第一次调用 ref 的 Form 为空？

ref 仅在节点被加载时才会被赋值，请参考 React 官方文档：https://reactjs.org/docs/refs-and-the-dom.html#accessing-refs

为什么 resetFields 会重新 mount 组件？

resetFields 会重置整个 Field，因而其子组件也会重新 mount 从而消除自定义组件可能存在的副作用（例如异步数据、状态等等）。

Form 的 initialValues 与 Item 的 initialValue 区别？

在大部分场景下，我们总是推荐优先使用 Form 的 initialValues。只有存在动态字段时你才应该使用 Item 的 initialValue。默认值遵循以下规则：

1. Form 的 initialValues 拥有最高优先级
2. Field 的 initialValue 次之 *. 多个同 name Item 都设置 initialValue 时，则 Item 的 initialValue 不生效

为什么 getFieldsValue 在初次渲染的时候拿不到值？

getFieldsValue 默认返回收集的字段数据，而在初次渲染时 Form.Item 节点尚未渲染，因而无法收集到数据。你可以通过 getFieldsValue(true) 来获取所有字段数据。

为什么 setFieldsValue 设置字段为 undefined 时，有的组件不会重置为空？

在 React 中，value 从确定值改为 undefined 表示从受控变为非受控，因而不会重置展示值（但是 Form 中的值确实已经改变）。你可以通过 HOC 改变这一逻辑：

const MyInput = ({
  // 强制保持受控逻辑
  value = '',
  ...rest
}) => <input value={value} {...rest} />;

<Form.Item name="my">
  <MyInput />
</Form.Item>;

为什么字段设置 rules 后更改值 onFieldsChange 会触发三次？

字段除了本身的值变化外，校验也是其状态之一。因而在触发字段变化会经历以下几个阶段：

1. Trigger value change
2. Rule validating
3. Rule validated

在触发过程中，调用 isFieldValidating 会经历 false > true > false 的变化过程。

为什么 Form.List 不支持 label 还需要使用 ErrorList 展示错误？

Form.List 本身是 renderProps，内部样式非常自由。因而默认配置 label 和 error 节点很难与之配合。如果你需要 antd 样式的 label，可以通过外部包裹 Form.Item 来实现。

为什么 Form.Item 的 dependencies 对 Form.List 下的字段没有效果？

Form.List 下的字段需要包裹 Form.List 本身的 name，比如：

<Form.List name="users">
  {(fields) =>
    fields.map((field) => (
      <React.Fragment key={field.key}>
        <Form.Item name={[field.name, 'name']} {...someRest1} />
        <Form.Item name={[field.name, 'age']} {...someRest1} />
      </React.Fragment>
    ))
  }
</Form.List>

依赖则是：['users', 0, 'name']

为什么 normalize 不能是异步方法？

React 中异步更新会导致受控组件交互行为异常。当用户交互触发 onChange 后，通过异步改变值会导致组件 value 不会立刻更新，使得组件呈现假死状态。如果你需要异步触发变更，请通过自定义组件实现内部异步状态。

scrollToFirstError 和 scrollToField 失效？

1. 使用了自定义表单控件

类似问题：#28370 #27994

滚动依赖于表单控件元素上绑定的 id 字段，如果自定义控件没有将 id 赋到正确的元素上，这个功能将失效。你可以参考这个 codesandbox。

2. 页面内有多个表单

页面内如果有多个表单，且存在表单项 name 重复，表单滚动定位可能会查找到另一个表单的同名表单项上。需要给表单 Form 组件设置不同的 name 以区分。

继上，为何不通过 ref 绑定元素？

当自定义组件不支持 ref 时，Form 无法获取子元素真实 DOM 节点，而通过包裹 Class Component 调用 findDOMNode 会在 React Strict Mode 下触发警告。因而我们使用 id 来进行元素定位。

setFieldsValue 不会触发 onFieldsChange 和 onValuesChange？

是的，change 事件仅当用户交互才会触发。该设计是为了防止在 change 事件中调用 setFieldsValue 导致的循环问题。如果仅仅需要组件内消费，可以通过 useWatch 或者 Field.renderProps 来实现。

为什么 Form.Item 嵌套子组件后，不更新表单值？

Form.Item 在渲染时会注入 value 与 onChange 事件给子元素，当你的字段组件被包裹时属性将无法传递。所以以下代码是不会生效的：

<Form.Item name="input">
  <div>
    <h3>I am a wrapped Input</h3>
    <Input />
  </div>
</Form.Item>

你可以通过 HOC 自定义组件形式来解决这个问题：

const MyInput = (props) => (
  <div>
    <h3>I am a wrapped Input</h3>
    <Input {...props} />
  </div>
);

<Form.Item name="input">
  <MyInput />
</Form.Item>;

有更多参考文档吗？

• 你可以阅读《antd v4 Form 使用心得》获得一些使用帮助以及建议。
• 想在 DatePicker、Switch 也使用 before、after？可以参考《如何优雅的对 Form.Item 的 children 增加 before、after》。
• 优雅的 Form + Modal 结合使用方案《如何优雅的使用 Form + Modal》。