react-forms

在 React 中实现 TanStack Form v1：核心钩子（`useForm()`、`useField()`、`form.Field`、`form.Subscribe`）、原生 Standard Schema 验证（Zod ~12KB、Yup ~40KB、Valibot ~6KB、ArkType、Effect Schema——无需适配器包）、防抖异步验证，以及通过 `useActionState` 集成 React 19 Server Actions。

还涵盖数组／嵌套字段（使用点号表示法）、用于副作用的监听器（onMount/onChange/onBlur，支持防抖）、关联／跨字段验证、通过 useStore 选择器实现响应式、Reset API、SSR／水合（TanStack Start）、devtools 和 React Native 模式。这是适用于 TanStack Form 的 React 技能——Next.js Server Actions 专用变体请参阅 nextjs-tanstack-form；SOLID 文件组织规则请参阅 solid-react。

TanStack Form v1 核心功能

Agent 工作流（强制）

任何实现开始前，必须并行启动 3 个 Agent，每个使用一次带有 name 的 Agent 调用：

1. fuse-ai-pilot:explore-codebase - 分析现有表单组件和验证模式
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 查证最新的 TanStack Form v1 文档
3. mcp__context7__query-docs - 检查 Zod 验证和 React 19 Server Actions 模式

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

强制要求：SOLID 原则

始终应用 solid-react 技能中的 SOLID 原则。

→ 完整规则请参阅 ../solid-react/SKILL.md

关键规则：

• 源文件不得超过 FUSE_SOLID_MAX_LINES，内聚性下降时按职责拆分
• 接口放在 modules/[feature]/src/interfaces/
• 所有导出项都必须编写 JSDoc
• 组件中不得包含业务逻辑

---

核心钩子

钩子	用途	指南
useForm()	初始化带验证的表单	references/tanstack-form-basics.md
useField()	订阅单个字段	references/tanstack-form-basics.md
form.Field	用于字段的渲染属性组件	references/tanstack-form-basics.md
form.Subscribe	监听表单状态变化	references/tanstack-form-basics.md

→ 详细用法请参阅 references/tanstack-form-basics.md

---

验证适配器

TanStack Form v1（@tanstack/react-form 1.33.x）原生支持 Standard Schema——将 schema 本身传给 validators（onChange: userSchema）。无需适配器：validatorAdapter 和 @tanstack/zod-form-adapter（最后一个版本为 0.42.1，属于 v1 之前版本，且仅支持 Zod 3）已移除／过时。

库	用法	最低版本	包体积
Zod	validators: { onChange: schema }	3.24.0	~12KB
Yup	validators: { onChange: schema }	1.7.0	~40KB
Valibot	validators: { onChange: schema }	1.0.0	~6KB

→ Zod 模式请参阅 references/zod-validation.md → 其他选项请参阅 references/yup-valibot.md

---

主要功能

异步验证

支持防抖和加载状态的服务端检查。 → 请参阅 references/async-validation.md

Server Actions（React 19）

与 useActionState 集成并支持渐进增强。 → 请参阅 references/server-actions.md

数组与嵌套字段

动态字段数组，以及用于嵌套对象的点号表示法。 → 请参阅 references/arrays-nested.md

TypeScript 集成

从 Zod schema 和 defaultValues 完整推断类型。 → 请参阅 references/typescript.md

shadcn/ui 集成

采用 shadcn 样式的字段包装组件。 → 请参阅 references/shadcn-integration.md

监听器（副作用）

支持防抖的 onMount、onChange、onBlur、onSubmit。 → 请参阅 references/listeners.md

关联字段

跨字段验证和依赖下拉菜单。 → 请参阅 references/linked-fields.md

响应式与性能

使用 useStore 选择器和细粒度订阅。 → 请参阅 references/reactivity.md

Reset API

重置表单和字段，并设置自定义值。 → 请参阅 references/reset-api.md

SSR 与水合

TanStack Start 集成与服务端状态合并。 → 参见 references/ssr-hydration.md

开发工具

使用 @tanstack/react-form-devtools 调试表单状态。 → 参见 references/devtools.md

React Native

使用 TextInput 的移动端专属模式。 → 参见 references/react-native.md

Standard Schema

支持 ArkType 和 Effect Schema。 → 参见 references/standard-schema.md

---

模板

模板	用途
templates/basic-form.md	使用 Zod 实现登录／注册
templates/multi-step-form.md	带分步验证的向导
templates/dynamic-fields.md	添加／移除字段数组
templates/file-upload-form.md	带预览的文件输入
templates/server-action-form.md	React 19 Server Actions
templates/optimistic-form.md	useOptimistic 集成
templates/nested-form.md	使用点号表示法处理嵌套字段
templates/search-form.md	防抖搜索
templates/conditional-fields.md	根据值显示／隐藏字段
templates/form-composition.md	可复用字段组件
templates/listeners-form.md	副作用与自动保存
templates/linked-fields-form.md	跨字段验证
templates/reactivity-form.md	性能优化
templates/reset-form.md	表单／字段重置模式
templates/ssr-form.md	SSR 与水合
templates/devtools-form.md	开发工具集成
templates/react-native-form.md	React Native 表单

---

最佳实践

1. 验证：使用 Zod/Yup/Valibot，而非自定义正则表达式
2. 异步：对服务端验证进行防抖（300-500ms）
3. 错误：显示 field.state.meta.errors
4. 嵌套：使用点号表示法（address.street）
5. 数组：将 mode="array" 与 pushValue/removeValue 搭配使用
6. TypeScript：使用 z.infer<typeof schema> 推断类型

---

禁止做法（反模式）

• ❌ 使用 useState 管理表单状态 → 使用 useForm()
• ❌ 使用正则表达式验证 → 使用 Zod/Yup/Valibot
• ❌ 异步操作未使用防抖 → 使用 onChangeAsyncDebounceMs
• ❌ 在组件中进行验证 → 移至 Schema
• ❌ 直接使用 onChange → 使用 field.handleChange
• ❌ 未定义 TypeScript 类型 → 使用 z.infer<typeof schema>