企业官网建设流程全解析

TanStack Form 组合式表单开发指南：createFormHook、withForm 与 withFieldGroup 实战

【免费下载链接】form🤖 Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, and Lit.项目地址: https://gitcode.com/GitHub_Trending/form/form

本指南深入讲解 TanStack Form（React 版）的表单组合（Form Composition）体系。form.Field虽然能力最强，但开箱即用的冗余写法在生产中并不理想，因此本指南围绕createFormHook、withForm、withFieldGroup等组合 API，从零搭建一套"可预绑定组件、可拆分、可复用、可扩展、可 Tree-shaking"的应用级表单脚手架。读完本文，你将掌握自定义表单 Hook 的完整链路、大表单拆分方法论、字段组跨表单复用技巧以及面向数百个组件的性能优化手段。

为什么需要表单组合？

TanStack Form 常被诟病的一点是"开箱即用的冗余"。这种冗余在教育场景下是有价值的——它强迫开发者理解底层 API（form.Field、field.handleChange、field.state.value等）是如何协同工作的；但在生产代码中，同样的样板代码反复出现显然不理想。

为此，TanStack Form 在保留form.Field（最强大、最灵活的使用方式）的同时，提供了一系列包装它的高级 API，让应用代码变得简洁：

从源码结构看，这些组合 API 都收敛在 createFormHook.tsx 一个文件里（含useAppForm、withForm、withFieldGroup、useTypedAppFormContext、extendForm五个返回成员），并在 useFieldGroup.tsx 中实现字段组的底层"透镜"（lens）机制。

自定义表单 Hooks：createFormHook起步

组合表单最强大的方式是创建自定义表单 Hook。它允许你打造一个贴合应用需求、并且预绑定自定义 UI 组件的表单 Hook。

最基础的用法：createFormHook接收fieldContext和formContext，返回一个useAppFormHook。

未做任何定制时，这个useAppForm与useForm完全等价；但随着你向createFormHook添加更多选项，这种状况会迅速改变。

第一步，创建一个专门导出 Context 的文件：

import { createFormHookContexts } from '@tanstack/react-form' // export useFieldContext for use in your custom components export const { fieldContext, formContext, useFieldContext } = createFormHookContexts()

第二步，用这两个 Context 创建 AppForm：

import { createFormHook } from '@tanstack/react-form' import { createFormHookContexts } from './AppFormContext' const { useAppForm } = createFormHook({ fieldContext, formContext, // We'll learn more about these options later fieldComponents: {}, formComponents: {}, }) function App() { const form = useAppForm({ // Supports all useForm options defaultValues: { firstName: 'John', lastName: 'Doe', }, }) return <form.Field /> // ... }

从实现上看，createFormHook内部用createContext创建了 field/form 两个 Context（createFormHook.tsx），useAppForm首先调用标准的useForm(props)拿到 form 实例，再通过useMemo构造出AppForm（formContext.Provider）与AppField（form.Field+fieldContext.Provider），最后用Object.assign(form, { AppField, AppForm, ...formComponents })把注册的组件挂到 form 实例上（createFormHook.tsx）。这也是为什么文档中form.AppField、form.AppForm、form.SubscribeButton可以直接以点号访问。

预绑定 Field 组件

脚手架就绪后，就可以往表单 Hook 里添加自定义字段组件了。

注意：自定义组件中使用的useFieldContext必须与你自定义表单 Context 导出的是同一个。

import { useFieldContext } from './form-context.tsx' export function TextField({ label }: { label: string }) { // The `Field` infers that it should have a `value` type of `string` const field = useFieldContext<string>() return ( <label> <span>{label}</span> <input value={field.state.value} onChange={(e) => field.handleChange(e.target.value)} /> </label> ) }

然后在createFormHook的fieldComponents中注册它：

import { TextField } from './text-field.tsx' const { useAppForm } = createFormHook({ fieldContext, formContext, fieldComponents: { TextField, }, formComponents: {}, })

最后在表单中使用：

function App() { const form = useAppForm({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }) return ( // Notice the `AppField` instead of `Field`; `AppField` provides the required context <form.AppField name="firstName" children={(field) => <field.TextField label="First Name" />} /> ) }

注意这里用的是form.AppField而非form.Field：AppField负责提供组件所需的 Context。这样做不仅复用了共享组件的 UI，还完整保留了 TanStack Form 的类型安全——把firstName拼错会直接产生 TypeScript 编译错误。

真实的仓库示例可对照 examples/react/composition：AppForm.tsx中注册TextField与SubmitButton，页面通过form.AppField+<f.TextField label="first name" />使用，并可在AppField上直接配置validators（含onChange、onChangeAsync、onChangeAsyncDebounceMs等），见 index.tsx。

关于性能的说明

Context 是 React 生态中很有价值的工具，但许多用户担心：通过 Context 提供响应式值会引发不必要的重渲染。这是合理的顾虑，但对 TanStack Form 不构成问题——通过 Context 提供的值本身不是响应式的，而是带有响应式属性的静态类实例（底层由 TanStack Store 的信号实现驱动）。也就是说，Context 传递的是稳定的实例引用，值的订阅与更新发生在 Store 内部，从而避免了 Context 全树重渲染问题。该机制在 createFormHook.tsx 中体现为useMemo化的 Provider（AppForm/AppField只在 form 实例变化时重建）。

预绑定 Form 组件

form.AppField解决了字段层面的样板与复用问题，但还没解决表单层面的样板问题。一个典型场景是共享form.Subscribe实例来实现响应式的提交按钮：

function SubscribeButton({ label }: { label: string }) { const form = useFormContext() return ( <form.Subscribe selector={(state) => state.isSubmitting}> {(isSubmitting) => ( <button type="submit" disabled={isSubmitting}> {label} </button> )} </form.Subscribe> ) } const { useAppForm, withForm } = createFormHook({ fieldComponents: {}, formComponents: { SubscribeButton, }, fieldContext, formContext, }) function App() { const form = useAppForm({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }) return ( <form.AppForm> // Notice the `AppForm` component wrapper; `AppForm` provides the required context <form.SubscribeButton label="Submit" /> </form.AppForm> ) }

与AppField类似，form.AppForm是上下文包装器——SubscribeButton内部的useFormContext()依赖它来拿到 form 实例。测试用例中对这套机制有完整覆盖（含formId、Submit按钮与submissionAttempts联动），可参考 createFormHook.test.tsx。

扩展自定义 AppForm：extendForm

平台团队（platform teams）常常会发布预构建的 AppForm：它可以放在 monorepo 的某个库中导出，也可以作为 npm 上的独立包发布。

假设weyland-yutan-corp发布了如下两个模块：

export const { fieldContext, formContext, useFieldContext, useFormContext } = createFormHookContexts()

import { createFormHook } from '@tanstack/react-form' import { fieldContext, formContext } from 'weyland-yutan-corp/forms-context' // fields import { UserIdField } from './FieldComponents/UserIdField' // components import { SubmitButton } from './FormComponents/SubmitButton' const ProfileForm = createFormHook({ fieldContext, formContext, fieldComponents: { UserIdField }, formComponents: { SubmitButton }, }) export default ProfileForm

有时，某个字段只属于下游某个开发团队。此时可以像下面这样扩展 AppForm：

1 - 创建新的 AppForm 字段

// imported from the same AppForm you want to extend import { useFieldContext } from 'weyland-yutan-corp/forms-context' export function CustomTextField({ label }: { label: string }) { const field = useFieldContext<string>() return ( <div> <label>{/* rest of component */}</label> </div> ) }

2 - 扩展 AppForm

// notice the same import as above import ProfileForm from 'weyland-yutan-corp/forms' import { CustomTextField } from './FieldComponents/CustomTextField' import { SubmitButton } from './FormComponents/SubmitButton' export const { useAppForm } = ProfileForm.extendForm({ fieldComponents: { CustomTextField }, // Ts will error since the parent appForm already has a component called SubmitButton formComponents: { SubmitButton }, })

这样，团队可以只添加自己独有的字段，而不会让上游 AppForm 膨胀。源码层面，extendForm会展开合并新旧组件并通过类型层面的约束阻止重名：它要求扩展对象中每个键若与父级组件重名，类型必须是'Error: field component names must be unique — this key already exists in the base form'这样的字符串字面量，从而在编译期报错（createFormHook.tsx）。

值得提醒：AppForm扩展支持多次链式调用（base.extendForm(...).extendForm(...)），测试中也验证了链式扩展、扩展后继续使用withForm、以及扩展后的 Hook 再次暴露extendForm等场景（见 createFormHook.test.tsx）。但多次链式扩展会带来 TypeScript 性能下降：对大多数只需扩展一次的团队这不是问题，官方建议将扩展次数控制在 3–5 次以内。

用withForm把大表单拆成小块

表单有时会变得非常庞大。TanStack Form 对大型表单支持良好，但几百上千行代码堆在单个文件里绝不是什么愉快的体验。

为此，TanStack Form 提供了withForm高阶组件来把表单拆分成更小的片段：

const { useAppForm, withForm } = createFormHook({ fieldComponents: { TextField, }, formComponents: { SubscribeButton, }, fieldContext, formContext, }) const ChildForm = withForm({ // These values are only used for type-checking, and are not used at runtime // This allows you to `...formOpts` from `formOptions` without needing to redeclare the options defaultValues: { firstName: 'John', lastName: 'Doe', }, // Optional, but adds props to the `render` function in addition to `form` props: { // These props are also set as default values for the `render` function title: 'Child Form', }, render: function Render({ form, title }) { return ( <div> <p>{title}</p> <form.AppField name="firstName" children={(field) => <field.TextField label="First Name" />} /> <form.AppForm> <form.SubscribeButton label="Submit" /> </form.AppForm> </div> ) }, }) function App() { const form = useAppForm({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }) return <ChildForm form={form} title={'Testing'} /> }

withForm的render函数接收form（完整的、带类型信息的扩展 form 实例）以及props中声明的自定义属性。从实现看，withForm返回的组件本质上是一个包装Render，把props与传入的 props 合并后交给render执行（createFormHook.tsx）。

值得注意的是defaultValues的语义：它只用于类型检查，运行时不会生效。因此你可以在formOptions中声明一次默认值，然后通过...formOpts展开复用，避免重复声明（formOptions的实现见 formOptions.ts）。

withFormFAQ

> 为什么用高阶组件而不是 Hook？

虽然 Hook 是 React 的未来，但高阶组件在组合场景中仍是强大的工具。withForm的 API 尤其如此——它让你无需手动传泛型就能获得强类型安全。

> 为什么在render中使用 Hook 会触发 ESLint 报错？

ESLint 只在函数的顶层查找 Hook 调用，而render不一定被识别为顶层组件——这取决于你的定义方式：

// This will cause ESLint errors with hooks usage const ChildForm = withForm({ // ... render: ({ form, title }) => { // ... }, })

// This works fine const ChildForm = withForm({ // ... render: function Render({ form, title }) { // ... }, })

即：使用具名函数声明（function Render(...)）而非箭头函数即可规避该问题。测试用例中凡是需要useStore/useFieldContext的render都采用了function Render写法，例如 createFormHook.test.tsx 中"更新时保持焦点不丢失"的用例。

Context 作为最后手段：useTypedAppFormContext

某些场景下你无法通过withForm传递form——典型如那些不允许修改 props 的组件。例如下面这个 TanStack Router 用法：

function RouteComponent() { const form = useAppForm({...formOptions, /* ... */ }) // <Outlet /> cannot be customized or receive additional props return <Outlet /> }

<Outlet />无法定制也无法接收额外 props。在这种边缘情况下，可以退而使用基于 Context 的回退方案来获取 form 实例：

const { useAppForm, useTypedAppFormContext } = createFormHook({ fieldContext, formContext, fieldComponents: {}, formComponents: {}, })

[!IMPORTANT] 类型安全 这个机制仅仅是为了弥合集成约束而存在，只要能用withForm就应优先使用withForm。 Context 在类型不匹配时不会给出任何警告，使用这种实现方式有运行时错误的风险。

用法示例：

// sharedOpts.ts const formOpts = formOptions({ /* ... */ }) function ParentComponent() { const form = useAppForm({ ...formOptions /* ... */ }) return ( <form.AppForm> <ChildComponent /> </form.AppForm> ) } function ChildComponent() { const form = useTypedAppFormContext({ ...formOptions }) // You now have access to form components, field components and fields }

从源码看，useTypedAppFormContext只是useFormContext()的带类型版本：它忽略传入的 props（仅用于类型推断），从formContext中读取实例并以扩展后的 form 类型返回（createFormHook.tsx）。源码注释与测试都强调：没有<form.AppForm>包裹时调用useTypedAppFormContext会直接抛错（createFormHook.test.tsx 中有专门用例验证）。

用withFieldGroup在多个表单间复用字段组

有时两个字段紧密关联，值得把它们组合起来复用——例如关联字段指南中提到的密码示例。与其在多个表单里重复这套逻辑，不如使用withFieldGroup高阶组件。

与withForm不同，withFieldGroup不能指定校验器，校验器可以是任意值。 请确保你的字段组件能够接受未知（unknown）的错误类型。

用withFieldGroup重写密码示例：

const { useAppForm, withForm, withFieldGroup } = createFormHook({ fieldComponents: { TextField, ErrorInfo, }, formComponents: { SubscribeButton, }, fieldContext, formContext, }) type PasswordFields = { password: string confirm_password: string } // These default values are not used at runtime, but the keys are needed for mapping purposes. // This allows you to spread `formOptions` without needing to redeclare it. const defaultValues: PasswordFields = { password: '', confirm_password: '', } const FieldGroupPasswordFields = withFieldGroup({ defaultValues, // You may also restrict the group to only use forms that implement this submit meta. // If none is provided, any form with the right defaultValues may use it. // onSubmitMeta: { action: '' } // Optional, but adds props to the `render` function in addition to `form` props: { // These props are set as default values for the `render` function title: 'Password', }, // Internally, you will have access to a `group` instead of a `form` render: function Render({ group, title }) { // access reactive values using the group store const password = useSelector(group.store, (state) => state.values.password) // or the form itself const isSubmitting = useSelector( group.form.store, (state) => state.isSubmitting, ) return ( <div> <h2>{title}</h2> {/* Groups also have access to Field, Subscribe, Field, AppField and AppForm */} <group.AppField name="password"> {(field) => <field.TextField label="Password" />} </group.AppField> <group.AppField name="confirm_password" validators={{ onChangeListenTo: ['password'], onChange: ({ value, fieldApi }) => { // The form could be any values, so it is typed as 'unknown' const values: unknown = fieldApi.form.state.values // use the group methods instead if (value !== group.getFieldValue('password')) { return 'Passwords do not match' } return undefined }, }} > {(field) => ( <div> <field.TextField label="Confirm Password" /> <field.ErrorInfo /> </div> )} </group.AppField> </div> ) }, })

这里有几个关键点值得展开：

• render拿到的是group而不是form：group是FieldGroupApi的扩展实例。通过group.store可以订阅字段组的值，通过group.form可以访问父表单（例如isSubmitting状态）。
• 字段组拥有完整的表单式 API：group.Field、group.Subscribe、group.AppField、group.AppForm一应俱全。源码中useFieldGroup为每个 FieldGroupApi 实例注入这些能力：AppForm代理到form.AppForm，AppField/Field通过formLensApi.getFormFieldOptions(props)把字段组内部的字段名"翻译"成表单中的真实深路径（useFieldGroup.tsx）。
• 跨字段校验：onChangeListenTo: ['password']让confirm_password字段在password变化时也触发校验；由于字段组可能挂到任意表单上，fieldApi.form.state.values被推断为unknown，因此比较时应使用group.getFieldValue('password')这类组方法。
• onSubmitMeta约束（可选）：如果字段组声明了onSubmitMeta，则只有实现了该 meta 的表单才能使用它；不声明时任何 defaultValues 匹配的表单都能使用。对应的FieldGroupOptions.onSubmitMeta定义见 FieldGroupApi.ts。

现在，任何实现了对应 defaultValues 的表单都可以使用这组字段：

// You are allowed to extend the group fields as long as the // existing properties remain unchanged type Account = PasswordFields & { provider: string username: string } // You may nest the group fields wherever you want type FormValues = { name: string age: number account_data: PasswordFields linked_accounts: Account[] } const defaultValues: FormValues = { name: '', age: 0, account_data: { password: '', confirm_password: '', }, linked_accounts: [ { provider: 'TanStack', username: '', password: '', confirm_password: '', }, ], } function App() { const form = useAppForm({ defaultValues, // If the group didn't specify an `onSubmitMeta` property, // the form may implement any meta it wants. // Otherwise, the meta must be defined and match. onSubmitMeta: { action: '' }, }) return ( <form.AppForm> <FieldGroupPasswordFields form={form} // You must specify where the fields can be found fields="account_data" title="Passwords" /> <form.Field name="linked_accounts" mode="array"> {(field) => field.state.value.map((account, i) => ( <FieldGroupPasswordFields key={account.provider} form={form} // The fields may be in nested fields fields={`linked_accounts[${i}]`} title={account.provider} /> )) } </form.Field> </form.AppForm> ) }

注意两个细节：

1. fields属性声明字段组在表单中的挂载位置，可以是深路径字符串（account_data、linked_accounts[0]），因此字段组天然支持嵌套对象与数组场景；
2. 字段组可以任意嵌套——测试中甚至验证了"withFieldGroup里再套withFieldGroup"（LensWrapper内嵌LensNested），字段名会被正确拼成form.field.firstName这样的完整路径（见 createFormHook.test.tsx）。

把字段组值映射到不同的字段

你可能希望密码字段位于表单顶层，或为了语义清晰而重命名属性。通过修改fields属性，可以把字段组值映射到它们真正的位置：

[!IMPORTANT] 由于 TypeScript 的限制，字段映射仅对对象有效。你可以在字段组顶层使用记录（record）或数组，但无法对它们做字段映射。

// To have an easier form, you can keep the fields on the top level type FormValues = { name: string age: number password: string confirm_password: string } const defaultValues: FormValues = { name: '', age: 0, password: '', confirm_password: '', } function App() { const form = useAppForm({ defaultValues, }) return ( <form.AppForm> <FieldGroupPasswordFields form={form} // You can map the fields to their equivalent deep key fields={{ password: 'password', confirm_password: 'confirm_password', // or map them to differently named keys entirely // 'password': 'name' }} title="Passwords" /> </form.AppForm> ) }

如果你期望字段组永远挂在表单顶层，还可以用一个辅助函数快速生成映射：

const defaultValues: PasswordFields = { password: '', confirm_password: '', } const passwordFields = createFieldMap(defaultValues) /* This generates the following map: { 'password': 'password', 'confirm_password': 'confirm_password' } */ // Usage: <FieldGroupPasswordFields form={form} fields={passwordFields} title="Passwords" />

createFieldMap的完整定义可从 createFieldMap.md 文档查看，其实现位于 form-core 的 util-types 体系（FieldsMap类型，见 FieldGroupApi.ts 中的TFields泛型）。测试用例对"字符串路径映射"与"对象映射"两种方式都有验证，包括映射后onChangeListenTo/onBlurListenTo会被正确改写为映射后的真实字段名（见 createFormHook.test.tsx）。

对表单与字段组件做 Tree-shaking

上面的示例适合快速上手，但如果你的项目有成百上千个表单/字段组件，把它们全部打包进每个使用表单 Hook 的文件里显然不理想。

解决方案是：把createFormHook的 TanStack API 与 React 的lazy和Suspense组合使用。

// src/hooks/form-context.ts import { createFormHookContexts } from '@tanstack/react-form' export const { fieldContext, useFieldContext, formContext, useFormContext } = createFormHookContexts()

// src/components/text-field.tsx import { useFieldContext } from '../hooks/form-context.tsx' export default function TextField({ label }: { label: string }) { const field = useFieldContext<string>() return ( <label> <span>{label}</span> <input value={field.state.value} onChange={(e) => field.handleChange(e.target.value)} /> </label> ) }

// src/hooks/form.ts import { lazy } from 'react' import { createFormHook } from '@tanstack/react-form' const TextField = lazy(() => import('../components/text-fields.tsx')) const { useAppForm, withForm } = createFormHook({ fieldContext, formContext, fieldComponents: { TextField, }, formComponents: {}, })

// src/App.tsx import { Suspense } from 'react' import { PeoplePage } from './features/people/form.tsx' export default function App() { return ( <Suspense fallback={<p>Loading...</p>}> <PeoplePage /> </Suspense> ) }

当TextField组件仍在加载时，页面会先展示Suspense的 fallback（如<p>Loading...</p>），加载完成后表单随即渲染。这样每个用到表单 Hook 的文件只打包自己真正用到的组件，实现按需加载。

把一切组合起来：一个端到端示例

至此，把上面的内容整合到一个完整示例中——/src/hooks/form.ts作为全应用共享的表单脚手架：

// /src/hooks/form.ts, to be used across the entire app const { fieldContext, useFieldContext, formContext, useFormContext } = createFormHookContexts() function TextField({ label }: { label: string }) { const field = useFieldContext<string>() return ( <label> <span>{label}</span> <input value={field.state.value} onChange={(e) => field.handleChange(e.target.value)} /> </label> ) } function SubscribeButton({ label }: { label: string }) { const form = useFormContext() return ( <form.Subscribe selector={(state) => state.isSubmitting}> {(isSubmitting) => <button disabled={isSubmitting}>{label}</button>} </form.Subscribe> ) } const { useAppForm, withForm } = createFormHook({ fieldComponents: { TextField, }, formComponents: { SubscribeButton, }, fieldContext, formContext, }) // /src/features/people/shared-form.ts, to be used across `people` features const formOpts = formOptions({ defaultValues: { firstName: 'John', lastName: 'Doe', }, }) // /src/features/people/nested-form.ts, to be used in the `people` page const ChildForm = withForm({ ...formOpts, // Optional, but adds props to the `render` function outside of `form` props: { title: 'Child Form', }, render: ({ form, title }) => { return ( <div> <p>{title}</p> <form.AppField name="firstName" children={(field) => <field.TextField label="First Name" />} /> <form.AppForm> <form.SubscribeButton label="Submit" /> </form.AppForm> </div> ) }, }) // /src/features/people/page.ts const Parent = () => { const form = useAppForm({ ...formOpts, }) return <ChildForm form={form} title={'Testing'} /> }

可以看到，这套体系的分层非常清晰：

• /src/hooks/form.ts：定义useAppForm、withForm与共享组件，全应用复用；
• /src/features/people/shared-form.ts：用formOptions集中声明表单默认值等选项，跨页面复用；
• /src/features/people/nested-form.ts：用withForm拆分局部 UI；
• /src/features/people/page.ts：组装页面。

API 使用选择指引

下面的图表可以帮助你快速决定在什么场景下该使用哪些 API：

（该图表位于 docs/assets/react_form_composability.svg，完整呈现了createFormHook→useAppForm/withForm/withFieldGroup/useTypedAppFormContext/extendForm之间的选择路径。）

深入验证：测试与示例

如果你想在仓库中直接验证本文涉及的所有行为：

• 组合 API 行为测试：createFormHook.test.tsx 覆盖了useAppForm默认值、withForm、withFieldGroup（含嵌套、字段映射、校验器名称重映射、焦点保持）、useTypedAppFormContext（含缺少AppForm时抛错）、extendForm（含链式扩展与重名约束）等全部场景；
• 组合示例项目：examples/react/composition 是一个可直接运行的最小示例，展示了TextField/SubmitButton的注册、form.AppField使用以及表单提交流程；
• 字段组底层实现：FieldGroupApi的核心类型与getFieldValue、getFormFieldOptions等透镜方法定义在 FieldGroupApi.ts，React 侧封装在 useFieldGroup.tsx。

小结

表单组合是 TanStack Form 从"灵活"走向"工程化"的关键一环：createFormHook+createFormHookContexts提供了应用级表单脚手架的基石；fieldComponents/formComponents消除了字段与表单的样板代码；withForm解决大表单拆分；withFieldGroup让紧密关联的字段组在多个表单间自由复用与映射；extendForm支持平台级 AppForm 的按团队扩展；而lazy+Suspense的组合则为大规模组件库提供了按需加载的能力。理解并善用这套 API，你就能在生产环境中写出简洁、可复用且全程类型安全的 TanStack Form 代码。

【免费下载链接】form🤖 Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, and Lit.项目地址: https://gitcode.com/GitHub_Trending/form/form