tanstack-form

TanStack Form

当工作涉及 TanStack Form v1（npm latest）时使用此技能，尤其是涉及 @tanstack/react-form、表单状态、验证、可复用的应用表单钩子、SSR 适配器、从临时 React 表单处理方式迁移，或规划迁移到 v2 alpha。

工作流

1. 更改代码前，检查本地表单技术栈：
   • @tanstack/react-form、@tanstack/form-core、SSR 适配器、开发工具、React、架构库、UI 库和测试工具的版本。
   • 表单模式：一次性 useForm、全应用的 createFormHook、嵌套的 withForm、可复用的 withFieldGroup、SSR 适配器表单，或 React Native。
   • 验证需求：字段级、表单级、Standard Schema、异步验证、动态重新验证、服务端验证，或提交时错误。
   • 渲染约定：受控字段、标签、错误显示、焦点管理、提交状态和无障碍要求。
2. 行为或版本很重要时，查阅最新文档和软件包依据。请从 source-map.md 开始。
3. 关于安装、核心 API、useForm、form.Field、createFormHook、应用字段、订阅、异步默认值和 UI 库集成，请使用 setup-core.md。
4. 关于字段/表单验证、Standard Schema、异步验证、动态验证、服务端错误、自定义错误、提交元数据和转换后的值，请使用 validation-state.md。
5. 关于大型表单、可复用的应用表单钩子、withForm、withFieldGroup、数组、FormGroup、关联字段和监听器，请使用 composition-arrays-groups.md。
6. 关于 TanStack Start、Next.js App Router、Remix、服务端验证、开发工具、调试、无障碍和生产检查，请使用 ssr-production.md。
7. 只有当仓库安装了 2.0.0-alpha.* 或用户询问 Form v2 时，才使用 v2-alpha.md。不要将 v2 模式用于 v1 代码。

实现判断

• 优先从 defaultValues 或共享的 formOptions 推断类型。除非本地代码库已有此需求，否则避免添加宽泛的 useForm<MyType>() 泛型。
• 小型或一次性表单使用普通 useForm 和 form.Field。对于产品表单和设计系统集成，优先使用预先绑定字段和表单组件的 createFormHook。
• 将 TanStack Form 字段视为受控字段。显式将 value、onBlur 和 onChange 连接到字段 API。
• 有选择地订阅。使用 form.Subscribe 构建 UI 片段，使用 useSelector(form.store, selector) 编写组件逻辑。优先使用 useSelector，而非已弃用的 useStore。避免订阅整个 store。
• 明确设置验证时机。根据用户体验选择 onChange、onBlur、onSubmit、onMount、onDynamic 和异步验证器，不要仅凭习惯决定。
• Standard Schema 验证会检查输入值；它不会将转换后的输出传递给 onSubmit。如果转换后的架构输出很重要，请在 onSubmit 内解析。
• 使用 onChangeListenTo 或 onBlurListenTo 进行跨字段验证，使用 listeners 执行重置、分析或自动保存等副作用。
• 对于多步骤表单，如果需要单个最终提交值和共享验证状态，优先使用 FormGroup，而不是多个互相独立的表单。
• 在 SSR 框架中，通过适配器的 formOptions 共享表单结构，使用 createServerValidate 在服务端验证，并通过 mergeForm 和 useTransform 合并返回的表单状态。

验证

优先使用仓库中已有的检查。对于有意义的 TanStack Form 更改，请包含相关的检查子集：

• 针对字段名称、深层键、默认值、验证器、提交元数据、字段组和 SSR 适配器导入进行类型检查。
• 针对验证时机、异步防抖、提交错误、数组变更、关联字段、监听器副作用以及重置/默认行为进行专项测试。
• 对受控输入、错误呈现、禁用或 aria-disabled 提交行为、无效提交时的焦点、加载默认值以及服务端返回的错误进行浏览器冒烟测试。
• 更改 TanStack Start、Next.js 或 Remix 适配器流程时，进行 SSR/操作测试。
• 状态看起来过时时，使用开发工具或调试检查；除非明确订阅，否则表单状态不会响应式更新。