TanStack Form Preact 组合式表单基石:createFormHookContexts 深度解析

原创2026-09-16 17:51:011,921 阅读
文章标签:前端UI组件

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,
  }
}

从实现可以提炼出三点关键事实:

  1. 守卫式错误提示:useFieldContext 与 useFormContext 都在取不到值时抛出明确错误。例如 useFormContext 在无 form 时抛出 'formContext' only works when within a 'formComponent' passed to 'createFormHook'(第 68–72 行)。这保证你误用(如把 useFieldContext 用在 <form.AppForm> 之外)时能立刻得到可读的报错信息,而不是静默返回空值。

  2. Context 承载的是「静态类实例」:注入 Context 的 FieldApi / FormApi 本身是稳定不变的类实例,真正响应式的是实例内部由 TanStack Store 驱动的 store 属性。因此经 Context 传递不会像传递裸响应式值那样引发无谓的整树重渲染——这是 Form Composition 指南中明确解释的性能要点:form.Field 之类的组件通过 useSelector 订阅 store 的局部切片,实现精确粒度的更新。

  3. 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 决策建议:

  • 能显式传 form props 时,优先用 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() 起步,就是通往整套组合式表单体系最标准的打开方式。

登录后查看全文
form