TanStack Form React 快速上手用 createFormHook 构建类型安全的表单状态管理【免费下载链接】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导读本文以 docs/framework/react/quick-start.md 为核心指南带你快速上手 TanStack Form 在 React 中的两种主流用法面向长期可维护性的createFormHook组合式写法以及适合一次性组件的useFormform.Field写法。读完本文你将掌握如何用约 60 行代码搭建一个具备完整类型推断、内置同步/异步校验与 Standard SchemaZod 等校验能力的生产级表单并理解form.AppField、form.AppForm背后基于 Context 与 TanStack Store 的实现原理。TanStack Form 与你之前用过的表单库不同它面向大规模生产场景设计把类型安全、性能与组合能力放在首位因此官方围绕其使用方式沉淀了一套 使用哲学重视可扩展性与长期开发体验而非追求短小精悍的示例代码。下面给出的示例遵循了其中的绝大多数最佳实践可以帮助你在短暂上手后快速开发出即使是高复杂度的表单。方式一使用 createFormHook 组合你的表单这是官方推荐的生产级写法。核心思想是把表单 UI 组件与表单状态逻辑解耦先用createFormHookContexts()创建字段/表单上下文再通过createFormHook把你自己实现的TextField、NumberField、SubmitButton等组件预绑定到表单上最终得到一个应用级的useAppFormHook。完整示例import React from react import ReactDOM from react-dom/client import { createFormHook, createFormHookContexts } from tanstack/react-form // Form components that pre-bind events from the form hook; check our Form Composition guide for more import { TextField, NumberField, SubmitButton } from ~our-app/ui-library // We also support Valibot, ArkType, and any other standard schema library import { z } from zod const { fieldContext, formContext } createFormHookContexts() // Allow us to bind components to the form to keep type safety but reduce production boilerplate // Define this once to have a generator of consistent form instances throughout your app const { useAppForm } createFormHook({ fieldComponents: { TextField, NumberField, }, formComponents: { SubmitButton, }, fieldContext, formContext, }) const PeoplePage () { const form useAppForm({ defaultValues: { username: , age: 0, }, validators: { // Pass a schema or function to validate onChange: z.object({ username: z.string(), age: z.number().min(13), }), }, onSubmit: ({ value }) { // Do something with form data alert(JSON.stringify(value, null, 2)) }, }) return ( form onSubmit{(e) { e.preventDefault() form.handleSubmit() }} h1Personal Information/h1 {/* Components are bound to form and field to ensure extreme type safety */} {/* Use form.AppField to render a component bound to a single field */} form.AppField nameusername children{(field) field.TextField labelFull Name /} / {/* The name property will throw a TypeScript error if typod */} form.AppField nameage children{(field) field.NumberField labelAge /} / {/* Components in form.AppForm have access to the form context */} form.AppForm form.SubmitButton / /form.AppForm /form ) } const rootElement document.getElementById(root)! ReactDOM.createRoot(rootElement).render(PeoplePage /)这段代码浓缩了 TanStack Form 的几个关键设计createFormHookContexts()创建一对fieldContext与formContext用于在字段组件/表单组件与form 实例之间传递数据createFormHook({ fieldComponents, formComponents, fieldContext, formContext })把 UI 组件注册进表单返回应用专属的useAppForm该 Hook 与useForm接受完全相同的选项defaultValues、validators、onSubmit等但在其返回的 form 上额外挂载了AppField、AppForm与所有formComponentsform.AppField渲染一个绑定到单个字段的组件name拼错时 TypeScript 会直接报错form.AppForm为formComponents如SubmitButton提供 form 上下文使其能通过useFormContext()读取表单状态例如isSubmitting。源码视角AppField 与 AppForm 是如何工作的从 packages/react-form/src/createFormHook.tsx 的源码可以看到createFormHook内部返回{ useAppForm, withForm, withFieldGroup, useTypedAppFormContext, extendForm }其中useAppForm通过如下方式扩展 form 实例它先调用useForm(props)得到基础 form 实例见 packages/react-form/src/useForm.tsx内部通过useState创建FormApi实例并挂载AppForm是一个用useMemo缓存的组件内部渲染formContext.Provider value{form}{children}/formContext.ProviderAppField内部渲染form.Field {...props}再把 field 实例放进fieldContext.Provider并通过Object.assign(field, fieldComponents)把注册的字段组件直接挂到 field 对象上——这正是children{(field) field.TextField .../}能够工作的原因最后Object.assign(form, { AppField, AppForm, ...formComponents })把扩展 API 合并回 form 实例。也就是说form.AppField等价于自带 Context 注入的form.Fieldform.AppForm等价于自带 form Context Provider 的容器。这套机制保证useFieldContext一定拿到的是当前字段的FieldApiuseFormContext一定拿到的是当前表单的FormApi类型在整条链路上全程可推断。这一组合能力的完整进阶用法自定义 Hook、预绑定字段/表单组件、withForm、withFieldGroup、extendForm、按需懒加载组件等可继续阅读 表单组合指南。方式二使用 useForm 与 form.Field 的一次性写法虽然官方长期更建议使用createFormHook来减少样板代码但库同样支持用useForm和form.Field编写一次性组件适合学习、原型或不需要复用的场景import React from react import ReactDOM from react-dom/client import { useForm } from tanstack/react-form const PeoplePage () { const form useForm({ defaultValues: { username: , age: 0, }, onSubmit: ({ value }) { // Do something with form data alert(JSON.stringify(value, null, 2)) }, }) return ( form.Field nameage validators{{ // We can choose between form-wide and field-specific validators onChange: ({ value }) value 13 ? undefined : Must be 13 or older, }} children{(field) ( input name{field.name} value{field.state.value} onBlur{field.handleBlur} typenumber onChange{(e) field.handleChange(e.target.valueAsNumber)} / {!field.state.meta.isValid ( em{field.state.meta.errors.join(,)}/em )} / )} / ) } const rootElement document.getElementById(root)! ReactDOM.createRoot(rootElement).render(PeoplePage /)两种写法的关系所有useForm的属性都可以用在useAppForm中所有form.Field的属性都可以用在form.AppField中。也就是说createFormHook不是另一套 API而是对useForm体系的组合增强。从源码上看useForm返回的是一个ReactFormExtendedApi见 packages/react-form/src/useForm.tsx它在FormApi基础上补充了 React 专属成员Field渲染单个字段的组件内部基于useFieldHook 创建FieldApi见 packages/react-form/src/useField.tsx并通过useSelector(fieldApi.store, ...)精细订阅 value、isTouched、isBlurred、isDirty、errorMap、isValidating等响应式状态避免无关重渲染FormGroup用于把一组字段组织成子表单Subscribe订阅 form 状态如state.canSubmit、state.isSubmitting的组件式 API适合在 UI 中做局部响应。在快速上手的示例中field.state.value与field.state.meta.errors都是响应式读取的errors是错误消息数组可直接join(,)渲染而field.state.meta.isValid为false表示当前字段校验未通过。校验从函数到 Standard Schema快速上手示例中把 Zod schema 直接传给了validators.onChangevalidators: { onChange: z.object({ username: z.string(), age: z.number().min(13), }), },TanStack Form 原生支持所有遵循 Standard Schema 规范 的校验库包括 Zod、Valibot、ArkType、Yup 等。你既可以像上面这样传整表单 schema错误会自动传播到对应字段也可以在字段级传入 schema 或函数validators{{ onChange: ({ value }) value 13 ? You must be 13 to make an account : undefined, }}校验时机由你决定——onChange每次输入、onBlur失焦、onSubmit提交甚至挂载时均可。同步与异步校验可以共存如onBluronBlurAsync异步校验还内置了防抖asyncDebounceMs与onChangeAsyncDebounceMs等逐项覆盖。更完整的校验方案请参阅 表单与字段校验指南。关于onSubmit与提交处理两种写法都通过onSubmit接收表单值onSubmit: ({ value }) { alert(JSON.stringify(value, null, 2)) },onSubmit中的value是当前表单全部值深拷贝后的最新状态类型由defaultValues自动推断。在onSubmit里做异步提交时建议声明为async函数并返回库会自动维护isSubmitting状态。提交相关的进阶处理onSubmitAsync、服务端校验、防止无效表单提交等可参考 提交处理指南。设计哲学与使用建议快速上手页强调先理解哲学再上手使用。TanStack Form 的核心哲学详见 docs/philosophy.md包括统一的 API不为了满足不同口味而碎片化 API宁可学习曲线稍高也要降低心智负担表单需要灵活性校验时机、作用范围字段级/表单级/子集、自定义校验逻辑、自定义错误消息、异步校验均开放受控即优雅Controlled is Cool状态可预测、易于测试、支持非 DOM 渲染器如 React Native便于做条件渲染与调试泛型是痛苦的Generics are grim你永远不需要手动传泛型库从运行时默认值推断一切类型// 不要这样 useFormMyForm() // 而应这样 interface Person { name: string age: number } const defaultPerson: Person { name: Bill Luo, age: 24 } useForm({ defaultValues: defaultPerson, })库是用来被包装的Libraries are liberatingTanStack Form 的设计目标之一就是被封装进你自己的组件体系或设计系统createFormHook正是为此而生——它导出的useAppForm与withForm可以带着预绑定组件在整个应用中保持一致。安装与下一步在 React 项目中安装npm install tanstack/react-form如果你想亲眼看到上述两种写法的完整可运行示例仓库中提供了对应的示例工程examples/react/simpleuseForm一次性写法、examples/react/compositioncreateFormHook组合写法以及大型表单 examples/react/large-form 等多步向导示例可直接安装依赖后本地运行。掌握快速上手后建议按顺序阅读 基础概念、表单组合 与 校验指南并在 useForm 参考 与 createFormHook 参考 中查阅完整 API 签名。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考