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

基本概念和术语

本页面介绍了 @tanstack/solid-form 库中使用的基本概念和术语。熟悉这些概念将帮助您更好地理解和使用该库。

表单选项

您可以使用 formOptions 函数为表单创建选项，以便在多个表单之间共享。

示例：

tsx
const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    lastName: '',
    hobbies: [],
  } as Person,
})

const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    lastName: '',
    hobbies: [],
  } as Person,
})

表单实例

表单实例是一个代表单个表单的对象，提供用于处理表单的方法和属性。您可以使用表单选项提供的 createForm 钩子创建表单实例。该钩子接受一个包含 onSubmit 函数的对象，该函数在表单提交时被调用。

tsx
const form = createForm(() => ({
  ...formOpts,
  onSubmit: async ({ value }) => {
    // 对表单数据进行处理
    console.log(value)
  },
}))

const form = createForm(() => ({
  ...formOpts,
  onSubmit: async ({ value }) => {
    // 对表单数据进行处理
    console.log(value)
  },
}))

您也可以使用独立的 createForm API 创建表单实例，而无需使用 formOptions：

tsx
const form = createForm<Person>(() => ({
  onSubmit: async ({ value }) => {
    // 对表单数据进行处理
    console.log(value)
  },
  defaultValues: {
    firstName: '',
    lastName: '',
    hobbies: [],
  },
}))

const form = createForm<Person>(() => ({
  onSubmit: async ({ value }) => {
    // 对表单数据进行处理
    console.log(value)
  },
  defaultValues: {
    firstName: '',
    lastName: '',
    hobbies: [],
  },
}))

字段

字段代表单个表单输入元素，如文本输入或复选框。字段使用表单实例提供的 form.Field 组件创建。该组件接受一个 name 属性，应该与表单默认值中的键匹配。它还接受一个 children 属性，这是一个渲染属性函数，以字段对象作为参数。

示例：

tsx
<form.Field
  name="firstName"
  children={(field) => (
    <input
      name={field().name}
      value={field().state.value}
      onBlur={field().handleBlur}
      onInput={(e) => field().handleChange(e.target.value)}
    />
  )}
/>

<form.Field
  name="firstName"
  children={(field) => (
    <input
      name={field().name}
      value={field().state.value}
      onBlur={field().handleBlur}
      onInput={(e) => field().handleChange(e.target.value)}
    />
  )}
/>

字段状态

每个字段都有自己的状态，包括当前值、验证状态、错误消息和其他元数据。您可以使用 field().state 属性访问字段的状态。

示例：

ts
const {
  value,
  meta: { errors, isValidating },
} = field().state

const {
  value,
  meta: { errors, isValidating },
} = field().state

元数据中有四个状态可以用来了解用户如何与字段交互：

  • "isTouched"，在用户更改字段或字段失焦后
  • "isDirty"，在字段值被更改后，即使已恢复为默认值。与 isPristine 相反
  • "isPristine"，直到用户更改字段值。与 isDirty 相反
  • "isBlurred"，在字段失焦后
ts
const { isTouched, isDirty, isPristine, isBlurred } = field().state.meta

const { isTouched, isDirty, isPristine, isBlurred } = field().state.meta

Field states

理解不同库中的 'isDirty'

非持久 dirty 状态

  • 库：React Hook Form (RHF)、Formik、Final Form。
  • 行为：如果字段值与默认值不同，则字段为 'dirty'。恢复为默认值会使其再次变为 'clean'。

持久 dirty 状态

  • 库：Angular Form、Vue FormKit。
  • 行为：字段一旦更改就保持 'dirty'，即使恢复为默认值。

我们选择了持久 'dirty' 状态模型。为了同时支持非持久 'dirty' 状态，我们引入了一个额外的标志：

  • "isDefaultValue"，字段的当前值是否为默认值
ts
const { isDefaultValue, isTouched } = field().state.meta

// 以下行将重新创建非持久 `dirty` 功能。
const nonPersistentIsDirty = !isDefaultValue

const { isDefaultValue, isTouched } = field().state.meta

// 以下行将重新创建非持久 `dirty` 功能。
const nonPersistentIsDirty = !isDefaultValue

Field states extended

字段 API

字段 API 是在创建字段时传递给渲染属性函数的对象。它提供了用于处理字段状态的方法。

示例：

tsx
<input
  name={field().name}
  value={field().state.value}
  onBlur={field().handleBlur}
  onInput={(e) => field().handleChange(e.target.value)}
/>

<input
  name={field().name}
  value={field().state.value}
  onBlur={field().handleBlur}
  onInput={(e) => field().handleChange(e.target.value)}
/>

验证

@tanstack/solid-form 开箱即用地提供同步和异步验证。验证函数可以使用 validators 属性传递给 form.Field 组件。

示例：

tsx
<form.Field
  name="firstName"
  validators={{
    onChange: ({ value }) =>
      !value
        ? '名字是必需的'
        : value.length < 3
          ? '名字必须至少 3 个字符'
          : undefined,
    onChangeAsync: async ({ value }) => {
      await new Promise((resolve) => setTimeout(resolve, 1000))
      return value.includes('error') && '名字中不允许包含 "error"'
    },
  }}
  children={(field) => (
    <>
      <input
        name={field().name}
        value={field().state.value}
        onBlur={field().handleBlur}
        onInput={(e) => field().handleChange(e.target.value)}
      />
      <p>{field().state.meta.errors[0]}</p>
    </>
  )}
/>

<form.Field
  name="firstName"
  validators={{
    onChange: ({ value }) =>
      !value
        ? '名字是必需的'
        : value.length < 3
          ? '名字必须至少 3 个字符'
          : undefined,
    onChangeAsync: async ({ value }) => {
      await new Promise((resolve) => setTimeout(resolve, 1000))
      return value.includes('error') && '名字中不允许包含 "error"'
    },
  }}
  children={(field) => (
    <>
      <input
        name={field().name}
        value={field().state.value}
        onBlur={field().handleBlur}
        onInput={(e) => field().handleChange(e.target.value)}
      />
      <p>{field().state.meta.errors[0]}</p>
    </>
  )}
/>

使用标准模式库进行验证

除了手写的验证选项外，我们还支持 Standard Schema 规范。

您可以使用任何实现该规范的库定义模式，并将其传递给表单或字段验证器。

支持的库包括：

tsx
import { z } from 'zod'

// ...
;<form.Field
  name="firstName"
  validators={{
    onChange: z.string().min(3, '名字必须至少 3 个字符'),
    onChangeAsyncDebounceMs: 500,
    onChangeAsync: z.string().refine(
      async (value) => {
        await new Promise((resolve) => setTimeout(resolve, 1000))
        return !value.includes('error')
      },
      {
        message: '名字中不允许包含 "error"',
      },
    ),
  }}
  children={(field) => (
    <>
      <input
        name={field().name}
        value={field().state.value}
        onBlur={field().handleBlur}
        onInput={(e) => field().handleChange(e.target.value)}
      />
      <p>{field().state.meta.errors[0]}</p>
    </>
  )}
/>

import { z } from 'zod'

// ...
;<form.Field
  name="firstName"
  validators={{
    onChange: z.string().min(3, '名字必须至少 3 个字符'),
    onChangeAsyncDebounceMs: 500,
    onChangeAsync: z.string().refine(
      async (value) => {
        await new Promise((resolve) => setTimeout(resolve, 1000))
        return !value.includes('error')
      },
      {
        message: '名字中不允许包含 "error"',
      },
    ),
  }}
  children={(field) => (
    <>
      <input
        name={field().name}
        value={field().state.value}
        onBlur={field().handleBlur}
        onInput={(e) => field().handleChange(e.target.value)}
      />
      <p>{field().state.meta.errors[0]}</p>
    </>
  )}
/>

响应性

@tanstack/solid-form 提供了多种订阅表单和字段状态变化的方法，最著名的是 form.useStore 钩子和 form.Subscribe 组件。这些方法允许您通过仅在必要时更新组件来优化表单的渲染性能。

示例：

tsx
const firstName = form.useStore((state) => state.values.firstName)
//...
<form.Subscribe
  selector={(state) => ({
    canSubmit: state.canSubmit,
    isSubmitting: state.isSubmitting,
  })}
  children={(state) => (
    <button type="submit" disabled={!state().canSubmit}>
      {state().isSubmitting ? '...' : '提交'}
    </button>
  )}
/>

const firstName = form.useStore((state) => state.values.firstName)
//...
<form.Subscribe
  selector={(state) => ({
    canSubmit: state.canSubmit,
    isSubmitting: state.isSubmitting,
  })}
  children={(state) => (
    <button type="submit" disabled={!state().canSubmit}>
      {state().isSubmitting ? '...' : '提交'}
    </button>
  )}
/>

数组字段

数组字段允许您在表单中管理值列表，例如爱好列表。您可以使用带有 mode="array" 属性的 form.Field 组件创建数组字段。

在处理数组字段时，您可以使用字段的 pushValue、removeValue、swapValues 和 moveValue 方法来添加、删除和交换数组中的值。

示例：

tsx
<form.Field
  name="hobbies"
  mode="array"
  children={(hobbiesField) => (
    <div>
      爱好
      <div>
        <Show
          when={hobbiesField().state.value.length > 0}
          fallback={'未找到爱好。'}
        >
          <Index each={hobbiesField().state.value}>
            {(_, i) => (
              <div>
                <form.Field
                  name={`hobbies[${i}].name`}
                  children={(field) => (
                    <div>
                      <label for={field().name}>名称：</label>
                      <input
                        id={field().name}
                        name={field().name}
                        value={field().state.value}
                        onBlur={field().handleBlur}
                        onInput={(e) => field().handleChange(e.target.value)}
                      />
                      <button
                        type="button"
                        onClick={() => hobbiesField().removeValue(i)}
                      >
                        X
                      </button>
                    </div>
                  )}
                />
                <form.Field
                  name={`hobbies[${i}].description`}
                  children={(field) => {
                    return (
                      <div>
                        <label for={field().name}>描述：</label>
                        <input
                          id={field().name}
                          name={field().name}
                          value={field().state.value}
                          onBlur={field().handleBlur}
                          onInput={(e) => field().handleChange(e.target.value)}
                        />
                      </div>
                    )
                  }}
                />
              </div>
            )}
          </Index>
        </Show>
      </div>
      <button
        type="button"
        onClick={() =>
          hobbiesField().pushValue({
            name: '',
            description: '',
            yearsOfExperience: 0,
          })
        }
      >
        添加爱好
      </button>
    </div>
  )}
/>

<form.Field
  name="hobbies"
  mode="array"
  children={(hobbiesField) => (
    <div>
      爱好
      <div>
        <Show
          when={hobbiesField().state.value.length > 0}
          fallback={'未找到爱好。'}
        >
          <Index each={hobbiesField().state.value}>
            {(_, i) => (
              <div>
                <form.Field
                  name={`hobbies[${i}].name`}
                  children={(field) => (
                    <div>
                      <label for={field().name}>名称：</label>
                      <input
                        id={field().name}
                        name={field().name}
                        value={field().state.value}
                        onBlur={field().handleBlur}
                        onInput={(e) => field().handleChange(e.target.value)}
                      />
                      <button
                        type="button"
                        onClick={() => hobbiesField().removeValue(i)}
                      >
                        X
                      </button>
                    </div>
                  )}
                />
                <form.Field
                  name={`hobbies[${i}].description`}
                  children={(field) => {
                    return (
                      <div>
                        <label for={field().name}>描述：</label>
                        <input
                          id={field().name}
                          name={field().name}
                          value={field().state.value}
                          onBlur={field().handleBlur}
                          onInput={(e) => field().handleChange(e.target.value)}
                        />
                      </div>
                    )
                  }}
                />
              </div>
            )}
          </Index>
        </Show>
      </div>
      <button
        type="button"
        onClick={() =>
          hobbiesField().pushValue({
            name: '',
            description: '',
            yearsOfExperience: 0,
          })
        }
      >
        添加爱好
      </button>
    </div>
  )}
/>

这些是 @tanstack/solid-form 库中使用的基本概念和术语。理解这些概念将帮助您更有效地使用该库并轻松创建复杂的表单。

在 GitHub 上编辑
快速上手
表单验证