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

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

表单选项

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

示例：

tsx

const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    lastName: '',
    employed: false,
    jobTitle: '',
  } as Employee,
})

const formOpts = formOptions({
  defaultValues: {
    firstName: '',
    lastName: '',
    employed: false,
    jobTitle: '',
  } as Employee,
})

表单实例

表单实例是一个代表单个表单的对象，提供用于处理表单的方法和属性。您可以使用 @tanstack/lit-form 提供的 TanStackFormController 接口创建表单实例。TanStackFormController 使用当前表单的（this）类和一些默认表单选项进行实例化。它初始化表单状态，处理表单提交，并提供管理表单字段及其验证的方法。

tsx

#form = new TanStackFormController(this, {
  defaultValues: {
    firstName: '',
    lastName: '',
    employed: false,
    jobTitle: '',
  } as Employee,
})

#form = new TanStackFormController(this, {
  defaultValues: {
    firstName: '',
    lastName: '',
    employed: false,
    jobTitle: '',
  } as Employee,
})

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

tsx

#form = new TanStackFormController(this, {
  ...formOpts,
})

#form = new TanStackFormController(this, {
  ...formOpts,
})

字段

字段代表单个表单输入元素，如文本输入或复选框。字段使用表单实例提供的 field(FieldOptions, callback) 创建。该组件接受一个 FieldOptions 对象和一个接收 FieldApi 对象的回调函数。此对象提供获取字段当前值、处理输入更改和处理失焦事件的方法。

示例：

 ${this.#form.field(
    {
      name: `firstName`,
      validators: {
        onChange: ({ value }) =>
          value.length < 3 ? "长度不够" : undefined,
        },
      },
      (field: FieldApi<Employee, "firstName">) => {
        return html` <div>
          <label class="first-name-label">名字</label>
          <input
           id="firstName"
           type="text"
           class="first-name-input"
           placeholder="名字"
           @blur="${() => field.handleBlur()}"
           .value="${field.state.value}"
           @input="${(event: InputEvent) => {
           if (event.currentTarget) {
            const newValue = (event.currentTarget as HTMLInputElement).value;
            field.handleChange(newValue);
           }
          }}"
        />
      </div>`;
    },
)}

 ${this.#form.field(
    {
      name: `firstName`,
      validators: {
        onChange: ({ value }) =>
          value.length < 3 ? "长度不够" : undefined,
        },
      },
      (field: FieldApi<Employee, "firstName">) => {
        return html` <div>
          <label class="first-name-label">名字</label>
          <input
           id="firstName"
           type="text"
           class="first-name-input"
           placeholder="名字"
           @blur="${() => field.handleBlur()}"
           .value="${field.state.value}"
           @input="${(event: InputEvent) => {
           if (event.currentTarget) {
            const newValue = (event.currentTarget as HTMLInputElement).value;
            field.handleChange(newValue);
           }
          }}"
        />
      </div>`;
    },
)}

字段状态

每个字段都有自己的状态，包括当前值、验证状态、错误消息和其他元数据。您可以使用 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