TanStack Form 嵌套数组操作中的常见问题解析

问题现象

在使用 TanStack Form（原 React Form）处理嵌套数组表单时，开发者可能会遇到一个典型问题：当尝试向父级数组添加新元素时，界面会崩溃并报错"TypeError: Cannot convert undefined or null to object in Function.keys"。这个问题在严格模式下尤为常见。

问题本质

这个错误的根本原因在于 TanStack Form 内部的状态管理机制与 React 严格模式的兼容性问题。具体来说：

1. 在严格模式下，React 会故意双重调用某些函数（如渲染函数、副作用等）以帮助发现副作用问题
2. TanStack Form 在处理数组字段时，会使用 Object.keys() 来获取数组长度
3. 当初始值为 undefined 或 null 时，Object.keys() 会抛出错误

解决方案

临时解决方案

最简单的解决方法是移除 React.StrictMode 包裹：

// 修改前
ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)

// 修改后
ReactDOM.createRoot(document.getElementById('root')).render(<App />)

更健壮的解决方案

1. 确保初始值不为空：在定义表单时，始终为数组字段提供初始值（空数组）

useForm({
  defaultValues: {
    people: [] // 确保数组字段初始化为空数组而非undefined
  }
})

2. 使用类型保护：在处理数组字段时，添加类型检查

const people = form.getFieldValue('people') || []

深入理解

TanStack Form 在处理数组字段时，内部会执行以下操作：

1. 通过 useStore 监听字段状态变化
2. 在数组模式下，会使用 Object.keys() 获取数组长度来触发重新渲染
3. 当值为 undefined 或 null 时，Object.keys() 无法工作

这种设计在大多数情况下是合理的，因为表单字段通常应该有明确的初始状态。但在严格模式下，React 的额外渲染可能会导致中间状态出现问题。

最佳实践

1. 始终为表单字段提供明确的初始值
2. 在开发环境中使用严格模式，但要注意这类边界情况
3. 对于复杂嵌套表单，考虑使用更精细的状态管理
4. 在访问可能为 undefined 的字段值时，总是提供回退值

总结

TanStack Form 是一个强大的表单管理库，但在处理嵌套数组时需要注意初始状态的设置。理解其内部工作原理有助于避免这类边界情况问题。通过提供合理的初始值和适当的类型保护，可以确保表单在各种环境下都能稳定工作。