基本概念和术语 | TanStack Form Svelte Docs

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

表单选项

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

示例：

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

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

表单实例

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

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

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

您也可以不使用 formOptions 创建表单实例：

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 属性，这是一个以字段对象作为参数的渲染属性函数。

示例：

svelte

<form.Field name="firstName">
  {#snippet children(field)}
    <input
      name={field.name}
      value={field.state.value}
      onblur={field.handleBlur}
      oninput={(e) => field.handleChange(e.target.value)}
    />
  {/snippet}
</form.Field>

<form.Field name="firstName">
  {#snippet children(field)}
    <input
      name={field.name}
      value={field.state.value}
      onblur={field.handleBlur}
      oninput={(e) => field.handleChange(e.target.value)}
    />
  {/snippet}
</form.Field>

字段状态

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

示例：

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

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

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

"isTouched"，在用户更改字段或字段失焦后
"isDirty"，在字段值被更改后，即使已恢复为默认值。与 isPristine 相反
"isPristine"，直到用户更改字段值。与 isDirty 相反
"isBlurred"，在字段失焦后

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"，字段的当前值是否为默认值

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 是在创建字段时传递给渲染属性函数的对象。它提供了用于处理字段状态的方法。

示例：

svelte

<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/svelte-form 开箱即用地提供同步和异步验证。验证函数可以使用 validators 属性传递给 form.Field 组件。

示例：

svelte

<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"'
    },
  }}
>
  {#snippet 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>
  {/snippet}
</form.Field>

<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"'
    },
  }}
>
  {#snippet 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>
  {/snippet}
</form.Field>

使用标准模式库进行验证

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

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

支持的库包括：

svelte

<script>
  import { z } from 'zod'

  // ...
</script>

<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"',
      },
    ),
  }}
>
  {#snippet 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>
  {/snippet}
</form.Field>

<script>
  import { z } from 'zod'

  // ...
</script>

<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"',
      },
    ),
  }}
>
  {#snippet 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>
  {/snippet}
</form.Field>

响应性

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

示例：

svelte

<script>
  //...
  const firstName = form.useStore((state) => state.values.firstName)
</script>

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

<script>
  //...
  const firstName = form.useStore((state) => state.values.firstName)
</script>

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

数组字段

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

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

示例：

svelte

<form.Field name="hobbies" mode="array">
  {#snippet children(hobbiesField)}
    <div>
      爱好
      <div>
        {#each hobbiesField.state.value as _, i}
            <div>
              <form.Field name={`hobbies[${i}].name`}>
                {#snippet children(field)}
                  <div>
                    <label for={field.name}>名称：</label>
                    <input
                      id={field.name}
                      name={field.name}
                      value={field.state.value}
                      onblur={field.handleBlur}
                      onchange={(e) => field.handleChange(e.target.value)}
                    />
                    <button
                      type="button"
                      onclick={() => hobbiesField.removeValue(i)}
                    >
                      X
                    </button>
                  </div>
                {/snippet}
              </form.Field>
              <form.Field name={`hobbies[${i}].description`}>
                {#snippet children(field)}
                    <div>
                      <label for={field.name}>描述：</label>
                      <input
                        id={field.name}
                        name={field.name}
                        value={field.state.value}
                        onblur={field.handleBlur}
                        onchange={(e) => field.handleChange(e.target.value)}
                      />
                    </div>
                {/snippet}
              </form.Field>
            </div>
          {:else}
            未找到爱好。
          {/each}
      </div>
      <button
        type="button"
        onclick={() =>
          hobbiesField.pushValue({
            name: '',
            description: '',
            yearsOfExperience: 0,
          })
        }
      >
        添加爱好
      </button>
    </div>
  {/snippet}
</form.Field>

<form.Field name="hobbies" mode="array">
  {#snippet children(hobbiesField)}
    <div>
      爱好
      <div>
        {#each hobbiesField.state.value as _, i}
            <div>
              <form.Field name={`hobbies[${i}].name`}>
                {#snippet children(field)}
                  <div>
                    <label for={field.name}>名称：</label>
                    <input
                      id={field.name}
                      name={field.name}
                      value={field.state.value}
                      onblur={field.handleBlur}
                      onchange={(e) => field.handleChange(e.target.value)}
                    />
                    <button
                      type="button"
                      onclick={() => hobbiesField.removeValue(i)}
                    >
                      X
                    </button>
                  </div>
                {/snippet}
              </form.Field>
              <form.Field name={`hobbies[${i}].description`}>
                {#snippet children(field)}
                    <div>
                      <label for={field.name}>描述：</label>
                      <input
                        id={field.name}
                        name={field.name}
                        value={field.state.value}
                        onblur={field.handleBlur}
                        onchange={(e) => field.handleChange(e.target.value)}
                      />
                    </div>
                {/snippet}
              </form.Field>
            </div>
          {:else}
            未找到爱好。
          {/each}
      </div>
      <button
        type="button"
        onclick={() =>
          hobbiesField.pushValue({
            name: '',
            description: '',
            yearsOfExperience: 0,
          })
        }
      >
        添加爱好
      </button>
    </div>
  {/snippet}
</form.Field>

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