Grundlegende Konzepte und Terminologie

Diese Seite stellt die grundlegenden Konzepte und Terminologie vor, die in der @tanstack/lit-form Bibliothek verwendet werden. Wenn Sie sich mit diesen Konzepten vertraut machen, können Sie die Bibliothek und ihre Verwendung mit Lit besser verstehen und damit arbeiten.

Sie können Optionen für Ihr Formular erstellen, damit es von mehreren Formularen gemeinsam genutzt werden kann, indem Sie die Funktion formOptions verwenden.

Zum Beispiel

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

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

Eine Formularinstanz ist ein Objekt, das ein einzelnes Formular darstellt und Methoden und Eigenschaften für die Arbeit mit dem Formular bereitstellt. Sie erstellen eine Formularinstanz mithilfe der TanStackFormController Schnittstelle, die von @tanstack/lit-form bereitgestellt wird. Der TanStackFormController wird mit der Klasse des aktuellen Formulars (this) und einigen Standard-Formularoptionen instanziiert. Er initialisiert den Formularzustand, behandelt die Formularübermittlung und stellt Methoden zur Verwaltung von Formularfeldern und deren Validierung bereit.

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

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

Sie können auch eine Formularinstanz erstellen, ohne formOptions zu verwenden, indem Sie die eigenständige TanStackFormController API verwenden.

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

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

Ein Feld repräsentiert ein einzelnes Formulareingabeelement, z. B. eine Texteingabe oder eine Checkbox. Felder werden mithilfe der von der Formularinstanz bereitgestellten Funktion field(FieldOptions, callback) erstellt. Die Komponente akzeptiert ein FieldOptions Objekt und eine Callback-Funktion, die ein FieldApi Objekt erhält. Dieses Objekt bietet Methoden zum Abrufen des aktuellen Werts des Feldes, zum Behandeln von Eingabeänderungen und zum Behandeln von Blur-Ereignissen.

Zum Beispiel

 ${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>`;
    },
)}

Jedes Feld hat seinen eigenen Zustand, der seinen aktuellen Wert, seinen Validierungsstatus, Fehlermeldungen und andere Metadaten umfasst. Sie können auf den Zustand eines Feldes über seine Eigenschaft field.state zugreifen.

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

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

Es gibt vier Zustände in den Metadaten, die nützlich sein können, um zu sehen, wie der Benutzer mit einem Feld interagiert.

• "isTouched", nachdem der Benutzer das Feld geändert oder den Fokus darauf verloren hat.
• "isDirty", nachdem sich der Wert des Feldes geändert hat, auch wenn er auf den Standardwert zurückgesetzt wurde. Das Gegenteil von isPristine.
• "isPristine", bis der Benutzer den Feldwert ändert. Das Gegenteil von isDirty.
• "isBlurred", nachdem der Fokus vom Feld genommen wurde.

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

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

Nicht-persistenter dirty Zustand

• Bibliotheken: React Hook Form (RHF), Formik, Final Form.
• Verhalten: Ein Feld ist 'dirty' (geändert), wenn sein Wert vom Standard abweicht. Das Zurücksetzen auf den Standardwert macht es wieder 'clean' (unverändert).

Persistenter dirty Zustand

• Bibliotheken: Angular Form, Vue FormKit.
• Verhalten: Ein Feld bleibt 'dirty' (geändert), sobald es geändert wurde, auch wenn es auf den Standardwert zurückgesetzt wird.

Wir haben uns für das persistente 'dirty'-Zustandsmodell entschieden. Um auch einen nicht-persistenten 'dirty'-Zustand zu unterstützen, führen wir ein zusätzliches Flag ein.

• "isDefaultValue", ob der aktuelle Wert des Feldes der Standardwert ist.

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