Ant Design Form.Provider 跨表单联动实战：如何在表单外部触发表单提交与数据流转

导读

在 Ant Design（antd）的实际项目中，常会遇到「一个页面上存在多张独立表单、它们之间需要互相读写数据」的场景，典型如：主表 + 弹窗子表，子表确认后要把数据回填到主表。本文以 components/form/demo/form-context.md 这一官方 Demo 为主体，系统讲解 Form.Provider 的 API 语义、form.submit() 在表单外部触发提交的原理，以及「Modal 确认按钮在 Form 之外」这类结构的推荐写法，并结合 antd 源码说明其底层实现，帮助你在自己的项目里实现表单间数据联动。

场景定位：表单在内部、提交按钮在外部

antd 官方给出的入门建议是：提交按钮通常放在 <Form> 内部，并通过原生 <Button htmlType="submit" /> 触发 Web 原生表单提交逻辑，这样 <Form> 的 onFinish 会自动拿到校验后的数据。

但真实业务中常有例外——例如把表单放进 Modal，确认按钮却属于 Modal 的 footer，物理上位于 <Form> 之外。此时原生 submit 链路无法直接生效，antd 提供 form.submit() 方法：它等价于点击了一次 submit 按钮，会先触发字段校验，校验通过后调用 onFinish。这正是 components/form/demo/form-context.md 所示范的核心结构。

两条提交路径对比

触发方式	适用结构	行为
<Button htmlType="submit" />	按钮位于 <Form> 内部	走 Web 原生表单提交，自动完成校验并触发 onFinish，官方推荐
form.submit()	按钮位于 <Form> 外部（如 Modal footer、Drawer footer）	通过 form 实例命令式提交，校验逻辑一致，也触发 onFinish

完整代码见 form-context demo，能力说明见 Form API 文档。

Form.Provider 是什么

Form.Provider 用于在表单之间建立联动关系：当一个带 name 的子表单发生字段更新或完成提交时，会自动触发 Provider 上的对应事件。官方将其挂载在 Form 命名空间下（Form.Provider = FormProvider），这一点可以从 components/form/index.tsx 的赋值语句直接得到验证。

其 API 只有两个回调：

属性	说明	类型
onFormChange	任一子表单字段更新时触发	function(formName: string, info: { changedFields, forms })
onFormFinish	任一子表单提交完成时触发	function(formName: string, info: { values, forms })

两种回调都会收到两个关键参数：

• formName：本次触发事件的子表单的 name，用于区分事件来自哪张表；
• info：内含本次提交的 values，以及一个 forms 注册表对象，通过它可以在任意位置拿到其他表单实例（form），从而跨表单读写字段。

基本用法示例（摘自 Form API 文档）：

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

Demo 逐段拆解：主表收集、弹窗录入、联动回填

form-context Demo 的完整业务闭环是：主表单填写组名（Group Name），点击 "Add User" 弹出子表单录入姓名与年龄，确认后数据以列表形式回填到主表单中，同时关闭弹窗。其完整代码见 form-context.tsx。

1. 弹窗子表单：用 form 实例把提交能力「带出」Form

子表单 ModalForm 内部通过 const [form] = Form.useForm() 创建实例并绑定到 <Form form={form}>：

const [form] = Form.useForm();

const onOk = () => {
  form.submit();
};

return (
  <Modal title="Basic Drawer" open={open} onOk={onOk} onCancel={onCancel}>
    <Form form={form} layout="vertical" name="userForm">
      <Form.Item name="name" label="User Name" rules={[{ required: true }]}>
        <Input />
      </Form.Item>
      <Form.Item name="age" label="User Age" rules={[{ required: true }]}>
        <InputNumber />
      </Form.Item>
    </Form>
  </Modal>
);

这里的 name="userForm" 至关重要——它是后面 Form.Provider 判别数据来源的唯一标识。Modal 的 onOk 调用 form.submit()，校验失败时错误会照常展示在对应 Form.Item 上；校验通过后，整个 Modal 内部 Form 的提交事件会被上层 Provider 捕获。

2. 关闭弹窗时重置表单：用 hooks 跟踪 open 变化

Demo 中定义了 useResetFormOnCloseModal，在弹窗从打开变为关闭时自动 form.resetFields()，避免下次打开时残留上次数据：

const useResetFormOnCloseModal = ({ form, open }) => {
  const prevOpenRef = useRef<boolean>(null);
  useEffect(() => {
    prevOpenRef.current = open;
  }, [open]);
  const prevOpen = prevOpenRef.current;

  useEffect(() => {
    if (!open && prevOpen) {
      form.resetFields();
    }
  }, [form, prevOpen, open]);
};

这段逻辑与 Form.Provider 本身无关，却是该场景下保证「弹窗数据流干净」的常见配套手段，值得在同类需求中直接复用。

3. Provider 统一收口：按 name 分流并回写主表

最外层用 <Form.Provider onFormFinish={...}> 包裹主表与弹窗子表。当 userForm 完成提交时，通过 info.forms 拿到 basicForm 实例，读取并更新其 users 字段：

<Form.Provider
  onFormFinish={(name, { values, forms }) => {
    if (name === 'userForm') {
      const { basicForm } = forms;
      const users = basicForm.getFieldValue('users') || [];
      basicForm.setFieldsValue({ users: [...users, values] });
      setOpen(false);
    }
  }}
>

这里可以看到 Form.Provider 联动的完整闭环：

• name 参数保证 Provider 可以为多张表单分别编写处理逻辑（if (name === 'xxx') 分流）；
• info.forms 是按 Form 的 name 索引的实例注册表，任何子表都能借此访问兄弟表单；
• getFieldValue / setFieldsValue 是跨表读写数据的标准姿势。

4. 主表单：隐藏字段承载数组 + shouldUpdate 驱动局部渲染

主表单 basicForm 需要「记住」已添加的用户。Demo 用一个 noStyle 的隐藏字段 users 作为数据容器：

{/* Create a hidden field to make Form instance record this */}
<Form.Item name="users" noStyle />

这里特意用 Form.Item + name（而非一个普通 state）来承载数组，是因为它必须进入表单的字段注册体系，才能被 getFieldValue 读取、被 setFieldsValue 更新，并在其他字段联动时保持一致。

随后用 shouldUpdate 的 Form.Item 订阅 users 变化并重新渲染用户列表——当 prevValues.users !== curValues.users 时重新执行 render props，把新增的用户以 Avatar 列表形式展示出来：

<Form.Item
  label="User List"
  shouldUpdate={(prevValues, curValues) => prevValues.users !== curValues.users}
>
  {({ getFieldValue }) => {
    const users = getFieldValue('users') || [];
    return users.length ? (
      <Flex vertical gap={8}>
        {users.map((user) => (
          <Space key={user.name}>
            <Avatar icon={<UserOutlined />} />
            {`${user.name} - ${user.age}`}
          </Space>
        ))}
      </Flex>
    ) : (
      <Typography.Text className="ant-form-text" type="secondary">
        ( <SmileOutlined /> No user yet. )
      </Typography.Text>
    );
  }}
</Form.Item>

主表单自身仍保留独立的能力：提交按钮 <Button htmlType="submit">Submit</Button> 位于 Form 内部，走原生提交路径触发主表 onFinish，并在控制台打印最终 values。整张主表单由 Form 实例统一管理，与子表单数据流互不干扰。

源码级原理：Provider 如何「看见」所有表单

从 rc-field-form 继承的联动内核

antd 的 Form.Provider 并不是从零实现的。查看 components/form/context.tsx 可以看到它的真实形态：

export interface FormProviderProps extends Omit<RcFormProviderProps, 'validateMessages'> {
  prefixCls?: string;
}

export const FormProvider: React.FC<FormProviderProps> = (props) => {
  const providerProps = omit(props, ['prefixCls']);
  return <RcFormProvider {...providerProps} />;
};

即 antd 的 FormProvider 只是对 @rc-component/form（表单逻辑的底层仓库组件）中 RcFormProvider 的薄封装，负责剔除 antd 层独有的 prefixCls 等 prop。因此 onFormChange / onFormFinish 的触发时机与 forms 注册表的维护逻辑，均由 rc 层统一实现。

Form 内部的 name 注册与事件冒泡

从源码结构看，antd 表单的联动是「双向」的：

• 每个 <Form> 组件内部（components/form/Form.tsx）通过 useForm 创建或接管实例，并把 form 的 __INTERNAL__.name 赋值为该 Form 的 name，即把「实例 ↔ 名字」的对应关系写入了实例内部；
• 每个 Form 渲染时都会套一层 FormProvider（见 components/form/Form.tsx），使得所有子表单都处于 Provider 的 React Context 可见范围内；
• 而用户显式书写的 <Form.Provider> 则位于更外层，从而可以统一接收内部各 Form 的字段变更/提交通知，并把以 name 为键的 forms 注册表暴露给回调使用。

由此可以推断整个数据流为：子表单字段更新或提交 → rc 层按 name 派发事件 → 外层 Form.Provider 的 onFormChange/onFormFinish 被触发 → 回调从 info.forms 取得目标表单实例 → 跨表单读写字段完成联动。

命令式提交的边界：form.submit 与原生 submit

form.submit 在 Form API 文档 中被明确描述为「与点击 submit 按钮等价」，antd 的 FormInstance 在 components/form/hooks/useForm.ts 中扩展了 scrollToField、focusField 等方法，但 submit、resetFields、setFieldsValue 等核心命令式方法直接继承自 rc 层实例。这就是为什么即使按钮渲染在 Modal footer（表单 DOM 之外），仍能获得与原生提交完全一致的校验行为。

最佳实践与常见坑

结合 Demo 与源码，在使用 Form.Provider 时值得记住以下几点：

1. 子表单必须带 name：Provider 通过 formName 参数区分来源，info.forms 也以 name 为键，匿名表单无法被联动机制正确索引。
2. 区分两种提交入口：htmlType="submit" 只对「按钮在 Form 内部」有效；Form 之外（Modal/Drawer footer、Toolbar 等）应使用 form.submit() 命令式触发。Demo 中主表与弹窗子表恰好各示范一种方式。
3. 弹窗表单记得复位：配合「关闭时 form.resetFields()」的习惯（如 useResetFormOnCloseModal），避免复用表单实例时残留脏数据。
4. 跨表数据尽量收敛在 Provider 层处理：把 setOpen(false)、回写数据等副作用集中在 onFormFinish 中，多表场景可依据 name 分流，逻辑更易维护。
5. 善用 shouldUpdate 驱动 UI 同步：隐藏字段（noStyle + name）+ shouldUpdate 局部渲染，是让 Form 实例数据驱动视图的标准组合，也保证了列表字段变更不会造成整表重渲染。

小结

Form.Provider 解决的是多表单实例间的「感知与协作」问题：onFormChange 监听字段流、onFormFinish 监听提交流，info.forms 则打通了任意表单之间的实例互访。配合 form.submit()，可以让「Modal 外置按钮提交内部表单」成为完全受控且校验完备的正式写法。需要深入其底层行为时，可继续阅读 Form API 文档 与 源码目录。