基本概念和术语

本页介绍了 @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,
})

表单实例

表单实例 (Form Instance) 是代表单个表单的对象，并提供了用于处理表单的方法和属性。您可以使用 @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,
})

您也可以不使用 formOptions，而是通过使用独立的 TanStackFormController API 来创建表单实例。

tsx

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

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

字段

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

例如

 ${this.#form.field(
    {
      name: `firstName`,
      validators: {
        onChange: ({ value }) =>
          value.length < 3 ? "Not long enough" : undefined,
        },
      },
      (field: FieldApi<Employee, "firstName">) => {
        return html` <div>
          <label class="first-name-label">First Name</label>
          <input
           id="firstName"
           type="text"
           class="first-name-input"
           placeholder="First Name"
           @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 ? "Not long enough" : undefined,
        },
      },
      (field: FieldApi<Employee, "firstName">) => {
        return html` <div>
          <label class="first-name-label">First Name</label>
          <input
           id="firstName"
           type="text"
           class="first-name-input"
           placeholder="First Name"
           @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

// The following line will re-create the non-Persistent `dirty` functionality.
const nonPersistentIsDirty = !isDefaultValue

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

// The following line will re-create the non-Persistent `dirty` functionality.
const nonPersistentIsDirty = !isDefaultValue

Field states extended

表单选项

表单实例

字段

字段状态

理解不同库中的“isDirty”

订阅 Bytes

订阅 Bytes