Ant Design 中 Form.List 与 initialValues 的配合使用注意事项

问题背景

在使用 Ant Design 的表单组件时，开发者经常会遇到需要动态增减表单项的场景。Ant Design 提供了 Form.List 组件来支持这种需求，它允许用户动态添加、删除和修改一组表单项。

核心问题

当开发者尝试为 Form.List 设置初始值时，可能会遇到一个常见误区：直接为 initialValues 属性传递数组类型的数据。这种用法会导致表单行为异常，表现为动态添加的表单项无法正常工作或数据绑定出现问题。

正确用法

Ant Design 的 Form 组件在设计上要求 initialValues 必须是一个对象（Object），而不是数组（Array）。对于 Form.List 的初始值设置，应该遵循以下规范：

1. 将 Form.List 的字段名作为对象的属性名
2. 该属性对应的值才是数组类型的数据

示例代码

<Form
  initialValues={{
    listName: [  // listName 是 Form.List 的 name 属性值
      { field1: 'value1', field2: 'value2' },
      { field1: 'value3', field2: 'value4' }
    ]
  }}
>
  <Form.List name="listName">
    {(fields, { add, remove }) => (
      // 表单项渲染逻辑
    )}
  </Form.List>
</Form>

底层原理

这种设计源于 Ant Design 表单数据管理的内部机制。整个表单的数据被存储在一个单一的状态对象中，每个字段（包括 Form.List）都是这个对象的一个属性。Form.List 虽然管理的是数组数据，但在表单的顶层数据结构中，它仍然表现为对象的一个属性。

最佳实践

1. 始终确保 initialValues 是一个对象
2. Form.List 的初始值应该作为对象的一个属性存在
3. 对于复杂的嵌套结构，保持每一层都是对象，只有最内层才是数组
4. 使用 TypeScript 可以获得更好的类型提示，避免这类错误

总结

理解 Ant Design 表单数据结构的组织方式对于正确使用动态表单功能至关重要。记住 initialValues 必须是一个对象这一基本原则，可以避免许多常见的表单使用问题。当遇到 Form.List 表现异常时，首先检查 initialValues 的结构是否符合要求，这往往能快速定位并解决问题。