antd 实战：在 Modal 弹窗中内嵌 Form，用"弹窗 + 表单"模式实现列表页的新建项操作

2026-09-07 09:48:44作者：齐添朝

本指南聚焦 ant-design 官方示例"弹出层中的新建表单"（form-in-modal.md）所演示的核心模式：在用户查看列表页时，通过 Modal 弹出表单完成"新建"，全程不离开当前页面。读完本文你将掌握 Modal 与 Form 的组合套路、底部"确定"按钮驱动表单提交的底层原理，以及弹窗销毁时表单值清理的正确姿势，并能直接落地到自己的业务代码中。

一、典型业务场景：列表页内的"就地新建"

当用户访问一个展示列表的页面，想要新建一项、但又不想跳转页面时，产品上最常见的交互是：用 Modal 弹出一个表单，用户填写必要信息后点击创建，列表数据随即刷新。这一场景在原文档 form-in-modal.md 中有非常直白的描述：

当用户访问一个展示了某个列表的页面，想新建一项但又不想跳转页面时，可以用 Modal 弹出一个表单，用户填写必要信息后创建新的项。

这种"就地新建"相比跳转到一个独立的新建页，具备两个明显收益：

上下文不丢失：用户仍然停留在原列表的视觉上下文中，操作心智负担小；
路径更短：弹出 → 填写 → 提交 → 关闭，两个交互动作即可完成一次新建。

antd 对此场景提供了开箱即用的组合方案：Modal 负责弹出层容器，Form 负责字段收集与校验，二者通过 modalRender 实现桥接。官方把它收录为 Form 文档中的正式示例之一，中文标题为"弹出层中的新建表单"，英文为 "Form in Modal to Create"，见 components/form/index.zh-CN.md。

二、完整示例代码与逐段拆解

官方配套的完整示例位于 components/form/demo/form-in-modal.tsx，下面结合其代码逐段讲解这个模式的关键设计。

2.1 数据模型与状态声明

interface Values {
  title?: string;
  description?: string;
  modifier?: string;
}

Values 接口描述的是最终要提交给后端的表单数据结构，分别对应"标题、描述、可见范围"三个字段。它是类型安全的保障，Form.useForm<Values>() 的泛型、onFinish 回调入参都可以复用它。

const App: React.FC = () => {
  const [form] = Form.useForm();
  const [formValues, setFormValues] = useState<Values>();
  const [open, setOpen] = useState(false);
  // ...
};

这里声明了三样东西：

form：由 Form.useForm() 创建的表单控制实例，用于命令式地操作表单（校验、取值、重置）。实例通过 <Form form={form}> 传给表单，见 components/form/index.zh-CN.md 中 form 参数的说明——"经 Form.useForm() 创建的 form 控制实例，不提供时会自动创建"。
formValues：仅用于演示——把提交成功的值渲染到页面上，方便观察结果（真实项目中这里一般是调用接口、刷新列表）。
open：Modal 的可见性开关，由"New Collection"按钮控制。

2.2 提交回调

const onCreate = (values: Values) => {
  console.log('Received values of form: ', values);
  setFormValues(values);
  setOpen(false);
};

当表单校验通过并触发提交时，onFinish 会把收集到的字段值传给 onCreate。这里的职责有三个：接收数据（真实场景替换为调用创建接口）、记录结果、关闭弹窗。

2.3 Modal + Form 的组合骨架

<Modal
  open={open}
  title="Create a new collection"
  okText="Create"
  cancelText="Cancel"
  okButtonProps={{ autoFocus: true, htmlType: 'submit' }}
  onCancel={() => setOpen(false)}
  destroyOnHidden
  modalRender={(dom) => (
    <Form
      layout="vertical"
      form={form}
      name="form_in_modal"
      initialValues={{ modifier: 'public' }}
      clearOnDestroy
      onFinish={(values) => onCreate(values)}
    >
      {dom}
    </Form>
  )}
>
  {/* Form.Item 字段... */}
</Modal>

这是整个模式的核心，几个关键点逐一说清：

（1）让底部"确定"按钮成为表单提交按钮：okButtonProps={{ autoFocus: true, htmlType: 'submit' }} 通过 Modal 的 okButtonProps 把底部确认按钮的 htmlType 设置为 submit。由于 Modal 弹出的完整节点（含底部按钮区）被 modalRender 用 <Form> 包裹，按钮点击就会触发原生 form 的 submit，进而走到 antd Form 的校验与 onFinish 流程。autoFocus: true 让弹窗打开后焦点直接落在确认按钮上，键盘回车即可提交。

（2）modalRender 是组合的关键桥梁：modalRender 的类型是 (node: React.ReactNode) => React.ReactNode，见 components/modal/interface.ts。它的作用是把 Modal 内部渲染出的整棵节点树（包括头部、内容区与底部操作区）作为参数传入，允许你"包一层"再返回。在 components/modal/Modal.tsx 中可以看到实现是：

const modalRender = props.modalRender
  ? (node: React.ReactNode) => <div className={`${prefixCls}-render`}>{props.modalRender(node)}</div>
  : undefined;

也就是说 {dom} 展开的是完整弹窗，<Form> 包裹的就是整个弹窗节点，因此底部 OK 按钮天然位于 <form> 内部——这正是"不写任何手动关联，OK 点击即表单提交"的原理。

（3）表单的全局配置：

layout="vertical"：字段标签在上、控件在下，适合信息密度较高的弹窗表单；
name="form_in_modal"：表单名称，会作为字段 id 的前缀（见 Form 参数表）；
initialValues={{ modifier: 'public' }}：表单默认值，仅在初始化与重置时生效（见 Form 参数表），这里让"可见范围"默认选中 public；
clearOnDestroy：表单随弹窗卸载时自动清空值，配合 Modal 的 destroyOnHidden 使用，保证下次打开是"干净的新表单"，该参数自 5.18.0 起可用，默认 false（见 Form 参数表）；
onFinish：提交且校验成功后触发的回调（见 Form 参数表）。

（4）弹窗关闭即销毁：destroyOnHidden 表示 Modal 关闭动画结束后销毁内容 DOM。需要说明的是，它取代了旧的 destroyOnClose，后者已标记弃用（自 5.25.0 起新增，见 components/modal/interface.ts），Modal.tsx 中会在同时传入旧属性时给出 deprecation 提示。旧版 antd 项目迁移时请注意 API 名称变化。

2.4 弹窗内的表单项

<Form.Item
  name="title"
  label="Title"
  rules={[{ required: true, message: 'Please input the title of collection!' }]}
>
  <Input />
</Form.Item>
<Form.Item name="description" label="Description">
  <Input type="textarea" />
</Form.Item>
<Form.Item name="modifier" className="collection-create-form_last-form-item">
  <Radio.Group>
    <Radio value="public">Public</Radio>
    <Radio value="private">Private</Radio>
  </Radio.Group>
</Form.Item>

三个字段的职责差异正好覆盖了表单校验的典型用法：

title：带 required 校验规则的必填字段，未填写时点击 Create 会阻塞提交并展示 message 提示；
description：可选字段，作为说明性文本输入（示例用 Input type="textarea" 承载多行内容，等价于 <Input.TextArea />）；
modifier：单选字段。注意它没有 label 和校验规则，靠 initialValues 已有默认值 public。className 保留下来是为了兼容旧版本中"最后一项去掉多余底部间距"的样式定制需求。

从源码结构看，被 name 标记的 Form.Item 会自动接管子控件的 value 与 onChange，无需手写受控逻辑（参见 Form.Item 的说明）。

2.5 触发按钮与结果预览

<Button type="primary" onClick={() => setOpen(true)}>
  New Collection
</Button>
<pre>{JSON.stringify(formValues, null, 2)}</pre>

页面上放一个 type="primary" 的主按钮用于打开弹窗；<pre> 用缩进 JSON 的方式把最近一次提交的值打印出来，作为肉眼可验证的交互反馈，实际项目中此处即替换为数据请求逻辑。

三、底层原理：为什么 OK 按钮无需再手动调 `validateFields`

很多人在第一次尝试"Form in Modal"时，会习惯性地在 Modal 的 onOk 中写 form.validateFields()。而官方这个模式完全不需要，原因要从 Modal 的按钮渲染说起。

在 components/modal/Modal.tsx 中，底部操作栏是被渲染进整棵弹窗 DOM 的：

const dialogFooter =
  footer !== null && !loading ? (
    <Footer
      {...props}
      okButtonProps={{ ...contextOkButtonProps, ...okButtonProps }}
      onOk={handleOk}
      ...
    />
  ) : null;

handleOk 的实现是：

const handleOk = (e: React.MouseEvent<HTMLButtonElement>) => {
  onOk?.(e);
  onClose?.();
};

它本身不做任何表单操作。但由于示例把 OK 按钮的 htmlType 设成了 submit，且整个弹窗节点（含 Footer）都被 modalRender 包进了 <Form>，点击 OK 会触发浏览器原生表单提交事件，antd Form 拦截该事件后依次执行：校验 rules → 校验通过则触发 onFinish(values)。

因此这套模式的职责分工非常干净：

角色	负责什么
`Form`	字段注册、值收集、规则校验、提交分发（`onFinish`）
`okButtonProps.htmlType: 'submit'`	把"点击确定"翻译成"提交表单"
`modalRender`	让底部按钮与表单项处于同一个 `<form>` 作用域内
`onFinish`	唯一的数据出口，接收合法值并执行业务逻辑

一个值得注意的细节是：Modal 的 onOk 未在示例中定义，因为点击 OK 只触发表单提交；关闭动作放在 onFinish 里的 setOpen(false) 完成，从而避免出现"先关弹窗、后拿数据"的时序问题。如果你自定义 footer（例如放入自定义按钮），则需要自己负责在按钮上设置 htmlType="submit" 或手动调用表单实例方法。

四、资源清理与生命周期：destroyOnHidden + clearOnDestroy 配对使用

弹窗型表单最容易踩的坑是"残留脏数据"：上一次填了一半的值被带到下一次打开的表单里。官方示例用两个配置成对解决了它：

destroyOnHidden（Modal）：弹窗每次关闭后销毁 DOM。因为表单渲染在弹窗内，DOM 销毁意味着新的 Form 组件实例会重新挂载；
clearOnDestroy（Form）：Form 卸载时清空自身管理的字段值，即使 form 实例（useForm 创建的）仍被外层持有，也不会残留旧状态。

clearOnDestroy 需要与 destroyOnHidden 语义一致才最稳：如果 Modal 没有销毁而 Form 先卸载清空，就会导致"实例还在但值丢了"的错位。在 antd 的 Form 文档中，clearOnDestroy 的官方定位就是"当表单被卸载时清空表单值"（默认 false，5.18.0 起可用），而 destroyOnHidden 恰好触发"表单被卸载"这一前提，两者天然配对。

对于受控展示或回显场景，替代方案是使用 Form 的 preserve（字段删除时是否保留值）配合 setFieldsValue 在打开前回填，但那是"编辑既有数据"的模式；本文所述的新建场景，官方推荐就是"随开随建、关掉即清"。

五、常见问题与避坑提示

1. 弹窗未打开时调用 form 方法报"Instance created by useForm is not connect to any Form element"？

这是 antd Form FAQ 中专门记载的问题（见 components/form/index.zh-CN.md）：如果你在 Modal 尚未初始化渲染时就调用 form 方法（例如组件挂载后立即 setFieldsValue），会因表单未关联到任何 <Form> 而告警。解决方法是给 Modal 设置 forceRender 使其预渲染，或把取值/设值动作延后到弹窗打开之后。

2. 用 setState 改表单值不生效？

Form.Item 受控后，字段值由表单实例统一管理。不要用子控件的 defaultValue 或 setState 去设置，而应使用 form.setFieldsValue 动态更新（参见 Form.Item 的说明）。

3. 为什么 Modal 关闭后再次打开，表单校验错误还在？

通常是因为弹窗没有销毁、Form 未被卸载，校验状态残留在实例上。接入 destroyOnHidden + clearOnDestroy（或按业务需要自行调用 form.resetFields()）即可获得干净的新建体验。

4. 版本兼容性

示例依赖三个较新 API：modalRender（自 5.x 早期版本稳定提供）、Modal 的 destroyOnHidden（5.25.0 起，替代弃用的 destroyOnClose）、Form 的 clearOnDestroy（5.18.0 起）。使用较旧 antd 版本时，请将后两者替换为 destroyOnClose 配合 destroyOnClose 时手动 form.resetFields() 的等价写法，或直接升级依赖版本。

六、可验证性与延伸阅读

该示例本身已被纳入 antd 的自动化回归体系：在 components/form/tests/demo.test.tsx 中，demoTest('form', ...) 会对 form 组件下所有 demo（含本示例）执行渲染与基础交互冒烟测试，确保"Form in Modal"组合在每次迭代中都不会回归。你可以在本地运行对应测试命令来验证这一模式在自己的依赖版本下同样成立。

进一步在仓库中研读与本主题强相关的源码与文档，可以按下面的路径继续深入：

示例配套文档：components/form/demo/form-in-modal.md
可运行示例源码：components/form/demo/form-in-modal.tsx
Modal 属性全表（okButtonProps、destroyOnHidden、modalRender 等）：components/modal/interface.ts
Modal 底部按钮与 modalRender 实现：components/modal/Modal.tsx
Form 与 Form.Item 的完整参数表与 FAQ：components/form/index.zh-CN.md
Form 更多实战模式（受控 Hooks、校验、联动等）在 components/form/demo 目录下均有对应的可运行 demo 供对照学习。