基本概念和术语

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

表单实例

表单实例是一个对象，它表示单个表单，并提供用于处理表单的方法和属性。您可以使用 TanStackFormController 接口创建表单实例，该接口由 @tanstack/lit-form 提供。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(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 属性访问字段的状态。

tsx

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

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

有三种字段状态对于了解用户如何与字段交互非常有用。当用户单击/Tab 键进入字段时，该字段是“已触摸”的；在用户更改字段中的值之前，该字段是“原始”的；在值更改之后，该字段是“脏”的。您可以通过 isTouched、isPristine 和 isDirty 标志来检查这些状态，如下所示。

tsx

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

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

Field states

表单选项

表单实例

字段

字段状态

订阅 Bytes

订阅 Bytes