TanStack Form Preact 组合式表单基石:createFormHookContexts 深度解析
TanStack Form Preact 组合式表单基石:createFormHookContexts 深度解析
createFormHookContexts() 是 @tanstack/preact-form 表单组合(Form Composition)体系的核心入口之一,负责创建一套贯穿「表单实例 ↔ 字段实例 ↔ 自定义组件」的上下文基座。本文以 createFormHookContexts 参考文档 为骨架,结合 源码实现 与 Form Composition 指南,完整讲解该函数的返回值、类型签名、底层原理与实战接入方式,读完你将能搭建出类型安全、可复用、低样板代码的 Preact 企业级表单体系。
一、createFormHookContexts 是什么:组合式表单的上下文基座
在 TanStack Form 的 Preact 适配层中,createFormHook 负责把自定义的字段组件与表单组件「绑定」到 form 实例上,从而在保留强类型推导的同时大幅削减生产代码中的样板。而这一切的连通媒介,就是 createFormHookContexts() 创建的 Preact Context。
该函数定义于 packages/preact-form/src/createFormHook.tsx:91,其类型签名十分简洁:
function createFormHookContexts(): object;
调用它不需要任何参数,返回一个包含两个 Context 与两个 Hook 的对象,它们是后续一切组合能力的基础:
| 返回值 | 类型 | 用途 |
|---|---|---|
fieldContext |
Context<AnyFieldApi> |
向自定义字段组件提供当前 FieldApi 实例 |
formContext |
Context<AnyFormApi> |
向自定义表单组件提供当前 FormApi 实例 |
useFieldContext() |
Hook | 在字段组件内部取回类型化后的 FieldApi |
useFormContext() |
Hook | 在表单组件内部取回 PreactFormExtendedApi |
一个典型的初始化片段(通常放在独立的 form-context.tsx 中)如下:
import { createFormHookContexts } from '@tanstack/preact-form'
// export useFieldContext 供自定义组件使用
export const { fieldContext, formContext, useFieldContext, useFormContext } =
createFormHookContexts()
这一点在仓库的 multi-step-wizard 示例 与 quick-start 文档 中都有完全一致的用法:先导出一份「上下文单例」,再交给 createFormHook 消费。
二、返回值逐项解析(含类型签名)
参考文档对该函数的四个返回值给出了精确的类型声明,下面逐一拆解。
fieldContext:字段上下文
fieldContext: Context<AnyFieldApi> = FieldContext;
它是一个携带 AnyFieldApi 类型的 Preact Context,类型实参取自 @tanstack/form-core 的 AnyFieldApi。createFormHook 在渲染 <form.AppField> 时,会把当前字段对应的 FieldApi 实例放入该 Context(见下文源码分析),自定义字段组件即可通过 useFieldContext 取回它。
formContext:表单上下文
formContext: Context<AnyFormApi> = FormContext;
类型实参为 AnyFormApi。createFormHook 生成的 <form.AppForm> 组件会把自己持有的 form 实例注入该 Context,使得任意深度的子组件都能访问到 form,而无需层层透传 props。
useFieldContext():字段侧取值 Hook
useFieldContext: <TData>() => FieldApi<any, string, TData, any, any, ...>;
- Type Parameters:
TData—— 当前字段的值类型。 - Returns:
FieldApi,其中第三个类型参数被具体化为TData,其余泛型参数保持宽松的any。
也就是说,在自定义字段组件中通过 useFieldContext<string>() 显式传入值类型,编译器便能推断出 field.state.value 是 string,field.handleChange 接受 string 参数:
import { useFieldContext } from './form-context.tsx'
export function TextField({ label }: { label: string }) {
// 这里 `Field` 会被推断为 value 类型为 string 的字段
const field = useFieldContext<string>()
return (
<label>
<span>{label}</span>
<input
value={field.state.value}
onInput={(e) => field.handleChange(e.currentTarget.value)}
/>
</label>
)
}
useFormContext():表单侧取值 Hook
useFormContext: () => PreactFormExtendedApi<Record<string, never>, any, any, any, any, any, any, any, any, any, any, any>;
- Returns:
PreactFormExtendedApi(FormApi与 Preact 专属的Field/FormGroup/Subscribe能力的交集类型),其TFormData被固定为Record<string, never>。
注意这个设计取舍:源码注释明确写道「如果你需要访问表单数据,请改用 withForm」('If you need access to the form data, you need to use withForm instead')。因为 Context 无法携带编译期已知的具体表单数据类型,所以 useFormContext 返回的 form 被擦除为 Record<string, never> 的宽松形态——它适合做「绑定到 form 但不读取具体值」的通用组件,比如订阅 state.isSubmitting 的提交按钮:
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>
)
}
三、源码级实现原理:Context 单例与守护式 Hook
查看 packages/preact-form/src/createFormHook.tsx 可知,两个 Context 是模块级创建的全局单例(第 24–25 行):
// 我们永远不会命中这里的 null 分支
const FieldContext = createContext<AnyFieldApi>(null as never)
const FormContext = createContext<AnyFormApi>(null as never)
createFormHookContexts 则把它们与两个闭包内定义的 Hook 组装后返回(第 91–135 行):
export function createFormHookContexts() {
function useFieldContext<TData>() {
const field = useContext(FieldContext)
// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
if (!field) {
throw new Error(
'`fieldContext` only works when within a `fieldComponent` passed to `createFormHook`',
)
}
return field as FieldApi<any, string, TData, any, ...>
}
return {
fieldContext: FieldContext,
useFieldContext,
useFormContext,
formContext: FormContext,
}
}
从实现可以提炼出三点关键事实:
-
守卫式错误提示:
useFieldContext与useFormContext都在取不到值时抛出明确错误。例如useFormContext在无 form 时抛出'formContext' only works when within a 'formComponent' passed to 'createFormHook'(第 68–72 行)。这保证你误用(如把useFieldContext用在<form.AppForm>之外)时能立刻得到可读的报错信息,而不是静默返回空值。 -
Context 承载的是「静态类实例」:注入 Context 的
FieldApi/FormApi本身是稳定不变的类实例,真正响应式的是实例内部由 TanStack Store 驱动的 store 属性。因此经 Context 传递不会像传递裸响应式值那样引发无谓的整树重渲染——这是 Form Composition 指南中明确解释的性能要点:form.Field之类的组件通过useSelector订阅 store 的局部切片,实现精确粒度的更新。 -
Context 与
createFormHook的配对约束:指南强调「useFieldContext必须与你自定义 form context 导出的是同一个」——即组件中引用的useFieldContext必须来自你调用createFormHookContexts()得到的那份导出,不能混用不同模块里的副本,否则 Context 键不一致,取值会失败。
四、完整接入流程:从 Context 到 AppForm
createFormHookContexts 单独使用没有意义,它必须与 createFormHook 协同。完整链条如下:
import { createFormHook, createFormHookContexts } from '@tanstack/preact-form'
// 1. 创建并导出上下文基座
export const { fieldContext, formContext, useFieldContext, useFormContext } =
createFormHookContexts()
// 2. 注册自定义字段/表单组件
const { useAppForm, withForm } = createFormHook({
fieldContext,
formContext,
fieldComponents: {
TextField,
},
formComponents: {
SubscribeButton,
},
})
// 3. 在页面中使用
function App() {
const form = useAppForm({
defaultValues: {
firstName: 'John',
lastName: 'Doe',
},
})
return (
<form.AppField
name="firstName"
children={(field) => <field.TextField label="First Name" />}
/>
)
}
上下文在底层如何注入
createFormHook 内部(createFormHook.tsx 第 294 行起)做了三件关键的事:
AppForm组件用formContext.Provider包裹 children,值为useForm(props)返回的 form(第 350–356 行);AppField组件通过form.Field拿到字段实例后,用fieldContext.Provider包裹,并把fieldComponents合并到字段实例上(第 358–385 行),所以字段组件可以写成<field.TextField />;- 最终用
Object.assign把AppField、AppForm与formComponents合并进 form,得到扩展后的useAppForm返回值(第 387–393 行)。
这也解释了为什么 useFieldContext 只能在 fieldComponent 内工作、useFormContext 只能在 formComponent 内工作——它们取值的时机恰好在 Provider 注入之后的子树渲染阶段。
五、类型安全的红利:错误字段名在编译期被拦截
组合体系的另一大卖点是类型安全不因抽象而损失。form.AppField 的 name 直接来自表单 defaultValues 的深路径推导,拼错字段名(例如 firstName 打成 fristName)会直接触发 TypeScript 报错;同样,useFieldContext<TData>() 传入错误的值类型也会导致 field.state.value 的类型不匹配。这在 quick-start 文档 中被明确强调:"The name property will throw a TypeScript error if typo'd"。
与 withForm / useTypedAppFormContext 的分工
Form Composition 指南给出了 API 决策建议:
- 能显式传
formprops 时,优先用withForm(它是类型最安全的 HOC 组合方式); - 只有组件无法接收额外 props(如 TanStack Router 的
<Outlet />)等边缘场景,才退回到formContext这条 Context 通路; useTypedAppFormContext是createFormHook提供的「最后手段」,它从 Context 取回表单并配合formOptions重新注入具体类型,但源码与文档均标注警告:「Context 不会在类型不对齐时给出提示,你有运行时出错的风险」(参见 createFormHook 参考文档 中useTypedAppFormContext的 ⚠️ 说明)。
也就是说,createFormHookContexts 暴露的 useFormContext 是这条兜底链路的原始通道,而 withForm 才是官方推荐的主流路径。
六、错误使用场景与排查要点
结合源码中的守卫逻辑与 测试用例,以下错误场景都有明确的行为:
| 场景 | 行为 |
|---|---|
在 <form.AppForm> 之外调用 useFormContext |
抛错:'formContext' only works when within a 'formComponent' passed to 'createFormHook' |
在 fieldComponent 之外调用 useFieldContext |
抛错:'fieldContext' only works when within a 'fieldComponent' passed to 'createFormHook' |
混用两份不同来源的 useFieldContext |
取不到值,运行时抛错(Context 键不同) |
在 useTypedAppFormContext 之外缺少 AppForm 包裹 |
测试明确验证 render(<Parent />) 会 toThrow() |
对应的测试用例可以在 packages/preact-form/tests/createFormHook.test.tsx:633-668 中找到,它验证了「未用 AppForm 包裹时 useTypedAppFormContext 抛错」这一行为,可作为你排查问题的参照。
七、仓库实证:示例与测试中的标准姿势
仓库为这套 API 提供了多份可直接对照的实证:
- 示例:examples/preact/multi-step-wizard/src/hooks/form-context.tsx 中一行
createFormHookContexts()导出四个成员,是整个向导表单复用的上下文单例; - 测试:packages/preact-form/tests/createFormHook.test.tsx 覆盖了「默认值注入」「withForm 类型」「withFieldGroup 类型」「字段名重映射」「useTypedAppFormContext 正常/异常路径」等场景,其中
useFieldContext<string>()的TextField组件模式与实战完全一致; - 文档:Form Composition 指南 还演示了如何结合
preact/compat的lazy与Suspense对字段组件做按需加载(tree-shaking),form-context.ts中依旧从createFormHookContexts()导出fieldContext/formContext供createFormHook消费——上下文基座在任何组合策略下都是稳定的第一环。
八、小结:为什么先建 Context 再建 Hook
createFormHookContexts 的价值在于把「组件树通信机制」从「表单实例化逻辑」中分离出来:Context 负责跨层传递,createFormHook 负责按应用需求把组件绑定进 form。两者结合后,你可以获得:
- 一次声明,全局复用:
form-context.tsx在应用内只创建一份,所有自定义字段/表单组件共享同一套上下文; - 类型安全不打折:
useFieldContext<TData>()与AppField的深路径name推导保持完整; - 渲染性能可控:Context 中传递的是静态类实例,响应式更新仍由 TanStack Store 的细粒度订阅驱动;
- 代码拆分友好:上下文基座与组件注册分离,配合
lazy可实现字段组件按需加载。
当你开始使用 @tanstack/preact-form 构建生产级表单时,从一行 createFormHookContexts() 起步,就是通往整套组合式表单体系最标准的打开方式。