TanStackForm v1
自动
框架
版本
菜单
入门
指南
API 参考
社区资源
示例

React 元框架使用

TanStack Form 开箱即用地与 React 兼容，支持 SSR 并且与框架无关。但是，根据您选择的框架，需要特定的配置。

目前我们支持以下元框架：

在 TanStack Start 中使用 TanStack Form

本节重点介绍将 TanStack Form 与 TanStack Start 集成。

TanStack Start 先决条件

Start 集成

让我们首先创建一个 formOption，我们将使用它在客户端和服务器之间共享表单的形状。

typescript
// app/routes/index.tsx，但可以提取到任何其他路径
import { formOptions } from '@tanstack/react-form'

// 您可以在这里传递其他表单选项
export const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    age: 0,
  },
})

// app/routes/index.tsx，但可以提取到任何其他路径
import { formOptions } from '@tanstack/react-form'

// 您可以在这里传递其他表单选项
export const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    age: 0,
  },
})

接下来，我们可以创建一个 Start 服务器函数，它将在服务器上处理表单提交。

typescript
// app/routes/index.tsx，但可以提取到任何其他路径
import {
  createServerValidate,
  ServerValidateError,
} from '@tanstack/react-form/start'

const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.age < 12) {
      return '服务器验证：您必须至少 12 岁才能注册'
    }
  },
})

export const handleForm = createServerFn({
  method: 'POST',
})
  .validator((data: unknown) => {
    if (!(data instanceof FormData)) {
      throw new Error('Invalid form data')
    }
    return data
  })
  .handler(async (ctx) => {
    try {
      const validatedData = await serverValidate(ctx.data)
      console.log('validatedData', validatedData)
      // 将表单数据持久化到数据库
      // await sql`
      //   INSERT INTO users (name, email, password)
      //   VALUES (${validatedData.name}, ${validatedData.email}, ${validatedData.password})
      // `
    } catch (e) {
      if (e instanceof ServerValidateError) {
        // 在这里记录表单错误或执行任何其他逻辑
        return e.response
      }

      // 解析表单时发生了其他错误
      console.error(e)
      setResponseStatus(500)
      return '发生了内部错误'
    }

    return '表单验证成功'
  })

// app/routes/index.tsx，但可以提取到任何其他路径
import {
  createServerValidate,
  ServerValidateError,
} from '@tanstack/react-form/start'

const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.age < 12) {
      return '服务器验证：您必须至少 12 岁才能注册'
    }
  },
})

export const handleForm = createServerFn({
  method: 'POST',
})
  .validator((data: unknown) => {
    if (!(data instanceof FormData)) {
      throw new Error('Invalid form data')
    }
    return data
  })
  .handler(async (ctx) => {
    try {
      const validatedData = await serverValidate(ctx.data)
      console.log('validatedData', validatedData)
      // 将表单数据持久化到数据库
      // await sql`
      //   INSERT INTO users (name, email, password)
      //   VALUES (${validatedData.name}, ${validatedData.email}, ${validatedData.password})
      // `
    } catch (e) {
      if (e instanceof ServerValidateError) {
        // 在这里记录表单错误或执行任何其他逻辑
        return e.response
      }

      // 解析表单时发生了其他错误
      console.error(e)
      setResponseStatus(500)
      return '发生了内部错误'
    }

    return '表单验证成功'
  })

然后我们需要建立一种方法，使用另一个服务器操作从 serverValidate 的 response 中获取表单数据：

typescript
// app/routes/index.tsx，但可以提取到任何其他路径
import { getFormData } from '@tanstack/react-form/start'

export const getFormDataFromServer = createServerFn({ method: 'GET' }).handler(
  async () => {
    return getFormData()
  },
)

// app/routes/index.tsx，但可以提取到任何其他路径
import { getFormData } from '@tanstack/react-form/start'

export const getFormDataFromServer = createServerFn({ method: 'GET' }).handler(
  async () => {
    return getFormData()
  },
)

最后，我们将在加载器中使用 getFormDataFromServer 将状态从服务器获取到客户端，并在客户端表单组件中使用 handleForm。

tsx
// app/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import {
  mergeForm,
  useForm,
  useStore,
  useTransform,
} from '@tanstack/react-form'

export const Route = createFileRoute('/')({
  component: Home,
  loader: async () => ({
    state: await getFormDataFromServer(),
  }),
})

function Home() {
  const { state } = Route.useLoaderData()
  const form = useForm({
    ...formOpts,
    transform: useTransform((baseForm) => mergeForm(baseForm, state), [state]),
  })

  const formErrors = useStore(form.store, (formState) => formState.errors)

  return (
    <form action={handleForm.url} method="post" encType={'multipart/form-data'}>
      {formErrors.map((error) => (
        <p key={error as string}>{error}</p>
      ))}

      <form.Field
        name="age"
        validators={{
          onChange: ({ value }) =>
            value < 8 ? '客户端验证：您必须至少 8 岁' : undefined,
        }}
      >
        {(field) => {
          return (
            <div>
              <input
                name="age"
                type="number"
                value={field.state.value}
                onChange={(e) => field.handleChange(e.target.valueAsNumber)}
              />
              {field.state.meta.errors.map((error) => (
                <p key={error as string}>{error}</p>
              ))}
            </div>
          )
        }}
      </form.Field>
      <form.Subscribe
        selector={(formState) => [formState.canSubmit, formState.isSubmitting]}
      >
        {([canSubmit, isSubmitting]) => (
          <button type="submit" disabled={!canSubmit}>
            {isSubmitting ? '...' : '提交'}
          </button>
        )}
      </form.Subscribe>
    </form>
  )
}

// app/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import {
  mergeForm,
  useForm,
  useStore,
  useTransform,
} from '@tanstack/react-form'

export const Route = createFileRoute('/')({
  component: Home,
  loader: async () => ({
    state: await getFormDataFromServer(),
  }),
})

function Home() {
  const { state } = Route.useLoaderData()
  const form = useForm({
    ...formOpts,
    transform: useTransform((baseForm) => mergeForm(baseForm, state), [state]),
  })

  const formErrors = useStore(form.store, (formState) => formState.errors)

  return (
    <form action={handleForm.url} method="post" encType={'multipart/form-data'}>
      {formErrors.map((error) => (
        <p key={error as string}>{error}</p>
      ))}

      <form.Field
        name="age"
        validators={{
          onChange: ({ value }) =>
            value < 8 ? '客户端验证：您必须至少 8 岁' : undefined,
        }}
      >
        {(field) => {
          return (
            <div>
              <input
                name="age"
                type="number"
                value={field.state.value}
                onChange={(e) => field.handleChange(e.target.valueAsNumber)}
              />
              {field.state.meta.errors.map((error) => (
                <p key={error as string}>{error}</p>
              ))}
            </div>
          )
        }}
      </form.Field>
      <form.Subscribe
        selector={(formState) => [formState.canSubmit, formState.isSubmitting]}
      >
        {([canSubmit, isSubmitting]) => (
          <button type="submit" disabled={!canSubmit}>
            {isSubmitting ? '...' : '提交'}
          </button>
        )}
      </form.Subscribe>
    </form>
  )
}

在 Next.js App Router 中使用 TanStack Form

在阅读本节之前，建议您了解 React Server Components 和 React Server Actions 的工作原理。查看此博客系列了解更多信息

本节重点介绍将 TanStack Form 与 Next.js 集成，特别是使用 App Router 和 Server Actions。

Next.js 先决条件
  • 启动一个新的 Next.js 项目，按照 Next.js 文档 中的步骤进行。确保在设置过程中为 Would you like to use App Router? 选择 yes，以访问 Next.js 提供的所有新功能。
  • 安装 @tanstack/react-form
  • 安装您选择的任何表单验证器。[可选]

App Router 集成

让我们首先创建一个 formOption，我们将使用它在客户端和服务器之间共享表单的形状。

typescript
// shared-code.ts
// 注意导入路径与客户端不同
import { formOptions } from '@tanstack/react-form/nextjs'

// 您可以在这里传递其他表单选项
export const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    age: 0,
  },
})

// shared-code.ts
// 注意导入路径与客户端不同
import { formOptions } from '@tanstack/react-form/nextjs'

// 您可以在这里传递其他表单选项
export const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    age: 0,
  },
})

接下来，我们可以创建一个 React Server Action，它将在服务器上处理表单提交。

typescript
// action.ts
'use server'

// 注意导入路径与客户端不同
import {
  ServerValidateError,
  createServerValidate,
} from '@tanstack/react-form/nextjs'
import { formOpts } from './shared-code'

// 创建将从 `formOpts` 推断表单类型的服务器操作
const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.age < 12) {
      return '服务器验证：您必须至少 12 岁才能注册'
    }
  },
})

export default async function someAction(prev: unknown, formData: FormData) {
  try {
    const validatedData = await serverValidate(formData)
    console.log('validatedData', validatedData)
    // 将表单数据持久化到数据库
    // await sql`
    //   INSERT INTO users (name, email, password)
    //   VALUES (${validatedData.name}, ${validatedData.email}, ${validatedData.password})
    // `
  } catch (e) {
    if (e instanceof ServerValidateError) {
      return e.formState
    }

    // 验证表单时发生了其他错误
    throw e
  }

  // 您的表单已成功验证！
}

// action.ts
'use server'

// 注意导入路径与客户端不同
import {
  ServerValidateError,
  createServerValidate,
} from '@tanstack/react-form/nextjs'
import { formOpts } from './shared-code'

// 创建将从 `formOpts` 推断表单类型的服务器操作
const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.age < 12) {
      return '服务器验证：您必须至少 12 岁才能注册'
    }
  },
})

export default async function someAction(prev: unknown, formData: FormData) {
  try {
    const validatedData = await serverValidate(formData)
    console.log('validatedData', validatedData)
    // 将表单数据持久化到数据库
    // await sql`
    //   INSERT INTO users (name, email, password)
    //   VALUES (${validatedData.name}, ${validatedData.email}, ${validatedData.password})
    // `
  } catch (e) {
    if (e instanceof ServerValidateError) {
      return e.formState
    }

    // 验证表单时发生了其他错误
    throw e
  }

  // 您的表单已成功验证！
}

最后，我们将在客户端表单组件中使用 someAction。

tsx
// client-component.tsx
'use client'

import { useActionState } from 'react'
import { initialFormState } from '@tanstack/react-form/nextjs'
// 注意导入来自 `react-form`，而不是 `react-form/nextjs`
import {
  mergeForm,
  useForm,
  useStore,
  useTransform,
} from '@tanstack/react-form'
import someAction from './action'
import { formOpts } from './shared-code'

export const ClientComp = () => {
  const [state, action] = useActionState(someAction, initialFormState)

  const form = useForm({
    ...formOpts,
    transform: useTransform((baseForm) => mergeForm(baseForm, state!), [state]),
  })

  const formErrors = useStore(form.store, (formState) => formState.errors)

  return (
    <form action={action as never} onSubmit={() => form.handleSubmit()}>
      {formErrors.map((error) => (
        <p key={error as string}>{error}</p>
      ))}

      <form.Field
        name="age"
        validators={{
          onChange: ({ value }) =>
            value < 8 ? '客户端验证：您必须至少 8 岁' : undefined,
        }}
      >
        {(field) => {
          return (
            <div>
              <input
                name="age"
                type="number"
                value={field.state.value}
                onChange={(e) => field.handleChange(e.target.valueAsNumber)}
              />
              {field.state.meta.errors.map((error) => (
                <p key={error as string}>{error}</p>
              ))}
            </div>
          )
        }}
      </form.Field>
      <form.Subscribe
        selector={(formState) => [formState.canSubmit, formState.isSubmitting]}
      >
        {([canSubmit, isSubmitting]) => (
          <button type="submit" disabled={!canSubmit}>
            {isSubmitting ? '...' : '提交'}
          </button>
        )}
      </form.Subscribe>
    </form>
  )
}

// client-component.tsx
'use client'

import { useActionState } from 'react'
import { initialFormState } from '@tanstack/react-form/nextjs'
// 注意导入来自 `react-form`，而不是 `react-form/nextjs`
import {
  mergeForm,
  useForm,
  useStore,
  useTransform,
} from '@tanstack/react-form'
import someAction from './action'
import { formOpts } from './shared-code'

export const ClientComp = () => {
  const [state, action] = useActionState(someAction, initialFormState)

  const form = useForm({
    ...formOpts,
    transform: useTransform((baseForm) => mergeForm(baseForm, state!), [state]),
  })

  const formErrors = useStore(form.store, (formState) => formState.errors)

  return (
    <form action={action as never} onSubmit={() => form.handleSubmit()}>
      {formErrors.map((error) => (
        <p key={error as string}>{error}</p>
      ))}

      <form.Field
        name="age"
        validators={{
          onChange: ({ value }) =>
            value < 8 ? '客户端验证：您必须至少 8 岁' : undefined,
        }}
      >
        {(field) => {
          return (
            <div>
              <input
                name="age"
                type="number"
                value={field.state.value}
                onChange={(e) => field.handleChange(e.target.valueAsNumber)}
              />
              {field.state.meta.errors.map((error) => (
                <p key={error as string}>{error}</p>
              ))}
            </div>
          )
        }}
      </form.Field>
      <form.Subscribe
        selector={(formState) => [formState.canSubmit, formState.isSubmitting]}
      >
        {([canSubmit, isSubmitting]) => (
          <button type="submit" disabled={!canSubmit}>
            {isSubmitting ? '...' : '提交'}
          </button>
        )}
      </form.Subscribe>
    </form>
  )
}

在这里，我们使用 React 的 useActionState 钩子 和 TanStack Form 的 useTransform 钩子将从服务器操作返回的状态与表单状态合并。

如果您在 Next.js 应用程序中遇到以下错误：

typescript
x You're importing a component that needs `useState`. This React hook only works in a client component. To fix, mark the file (or its parent) with the `"use client"` directive.

x You're importing a component that needs `useState`. This React hook only works in a client component. To fix, mark the file (or its parent) with the `"use client"` directive.

这是因为您没有从 @tanstack/react-form/nextjs 导入服务器端代码。确保您根据环境导入正确的模块。

这是 Next.js 的限制。其他元框架可能不会有同样的问题。

在 Remix 中使用 TanStack Form

在阅读本节之前，建议您了解 Remix actions 的工作原理。查看 Remix 的文档了解更多信息

Remix 先决条件
  • 启动一个新的 Remix 项目，按照 Remix 文档 中的步骤进行。
  • 安装 @tanstack/react-form
  • 安装您选择的任何表单验证器。[可选]

Remix 集成

让我们首先创建一个 formOption，我们将使用它在客户端和服务器之间共享表单的形状。

typescript
// routes/_index/route.tsx
import { formOptions } from '@tanstack/react-form/remix'

// 您可以在这里传递其他表单选项
export const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    age: 0,
  },
})

// routes/_index/route.tsx
import { formOptions } from '@tanstack/react-form/remix'

// 您可以在这里传递其他表单选项
export const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    age: 0,
  },
})

接下来，我们可以创建一个 action，它将在服务器上处理表单提交。

tsx
// routes/_index/route.tsx

import {
  ServerValidateError,
  createServerValidate,
  formOptions,
} from '@tanstack/react-form/remix'

import type { ActionFunctionArgs } from '@remix-run/node'

// export const formOpts = formOptions({

// 创建将从 `formOpts` 推断表单类型的服务器操作
const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.age < 12) {
      return '服务器验证：您必须至少 12 岁才能注册'
    }
  },
})

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData()
  try {
    const validatedData = await serverValidate(formData)
    console.log('validatedData', validatedData)
    // 将表单数据持久化到数据库
    // await sql`
    //   INSERT INTO users (name, email, password)
    //   VALUES (${validatedData.name}, ${validatedData.email}, ${validatedData.password})
    // `
  } catch (e) {
    if (e instanceof ServerValidateError) {
      return e.formState
    }

    // 验证表单时发生了其他错误
    throw e
  }

  // 您的表单已成功验证！
}

// routes/_index/route.tsx

import {
  ServerValidateError,
  createServerValidate,
  formOptions,
} from '@tanstack/react-form/remix'

import type { ActionFunctionArgs } from '@remix-run/node'

// export const formOpts = formOptions({

// 创建将从 `formOpts` 推断表单类型的服务器操作
const serverValidate = createServerValidate({
  ...formOpts,
  onServerValidate: ({ value }) => {
    if (value.age < 12) {
      return '服务器验证：您必须至少 12 岁才能注册'
    }
  },
})

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData()
  try {
    const validatedData = await serverValidate(formData)
    console.log('validatedData', validatedData)
    // 将表单数据持久化到数据库
    // await sql`
    //   INSERT INTO users (name, email, password)
    //   VALUES (${validatedData.name}, ${validatedData.email}, ${validatedData.password})
    // `
  } catch (e) {
    if (e instanceof ServerValidateError) {
      return e.formState
    }

    // 验证表单时发生了其他错误
    throw e
  }

  // 您的表单已成功验证！
}

最后，当表单提交时将调用 action。

tsx
// routes/_index/route.tsx
import { Form, useActionData } from '@remix-run/react'

import {
  mergeForm,
  useForm,
  useStore,
  useTransform,
} from '@tanstack/react-form'
import {
  ServerValidateError,
  createServerValidate,
  formOptions,
  initialFormState,
} from '@tanstack/react-form/remix'

import type { ActionFunctionArgs } from '@remix-run/node'

// export const formOpts = formOptions({

// const serverValidate = createServerValidate({

// export async function action({request}: ActionFunctionArgs) {

export default function Index() {
  const actionData = useActionData<typeof action>()

  const form = useForm({
    ...formOpts,
    transform: useTransform(
      (baseForm) => mergeForm(baseForm, actionData ?? initialFormState),
      [actionData],
    ),
  })

  const formErrors = useStore(form.store, (formState) => formState.errors)

  return (
    <Form method="post" onSubmit={() => form.handleSubmit()}>
      {formErrors.map((error) => (
        <p key={error as string}>{error}</p>
      ))}

      <form.Field
        name="age"
        validators={{
          onChange: ({ value }) =>
            value < 8 ? '客户端验证：您必须至少 8 岁' : undefined,
        }}
      >
        {(field) => {
          return (
            <div>
              <input
                name="age"
                type="number"
                value={field.state.value}
                onChange={(e) => field.handleChange(e.target.valueAsNumber)}
              />
              {field.state.meta.errors.map((error) => (
                <p key={error as string}>{error}</p>
              ))}
            </div>
          )
        }}
      </form.Field>
      <form.Subscribe
        selector={(formState) => [formState.canSubmit, formState.isSubmitting]}
      >
        {([canSubmit, isSubmitting]) => (
          <button type="submit" disabled={!canSubmit}>
            {isSubmitting ? '...' : '提交'}
          </button>
        )}
      </form.Subscribe>
    </Form>
  )
}

// routes/_index/route.tsx
import { Form, useActionData } from '@remix-run/react'

import {
  mergeForm,
  useForm,
  useStore,
  useTransform,
} from '@tanstack/react-form'
import {
  ServerValidateError,
  createServerValidate,
  formOptions,
  initialFormState,
} from '@tanstack/react-form/remix'

import type { ActionFunctionArgs } from '@remix-run/node'

// export const formOpts = formOptions({

// const serverValidate = createServerValidate({

// export async function action({request}: ActionFunctionArgs) {

export default function Index() {
  const actionData = useActionData<typeof action>()

  const form = useForm({
    ...formOpts,
    transform: useTransform(
      (baseForm) => mergeForm(baseForm, actionData ?? initialFormState),
      [actionData],
    ),
  })

  const formErrors = useStore(form.store, (formState) => formState.errors)

  return (
    <Form method="post" onSubmit={() => form.handleSubmit()}>
      {formErrors.map((error) => (
        <p key={error as string}>{error}</p>
      ))}

      <form.Field
        name="age"
        validators={{
          onChange: ({ value }) =>
            value < 8 ? '客户端验证：您必须至少 8 岁' : undefined,
        }}
      >
        {(field) => {
          return (
            <div>
              <input
                name="age"
                type="number"
                value={field.state.value}
                onChange={(e) => field.handleChange(e.target.valueAsNumber)}
              />
              {field.state.meta.errors.map((error) => (
                <p key={error as string}>{error}</p>
              ))}
            </div>
          )
        }}
      </form.Field>
      <form.Subscribe
        selector={(formState) => [formState.canSubmit, formState.isSubmitting]}
      >
        {([canSubmit, isSubmitting]) => (
          <button type="submit" disabled={!canSubmit}>
            {isSubmitting ? '...' : '提交'}
          </button>
        )}
      </form.Subscribe>
    </Form>
  )
}

在这里，我们使用 Remix 的 useActionData 钩子 和 TanStack Form 的 useTransform 钩子将从服务器操作返回的状态与表单状态合并。

在 GitHub 上编辑
React Native
调试