Grundlegende Konzepte und Terminologie
Diese Seite stellt die grundlegenden Konzepte und Terminologie vor, die in der @tanstack/solid-form Bibliothek verwendet werden. Wenn Sie sich mit diesen Konzepten vertraut machen, werden Sie die Bibliothek besser verstehen und damit arbeiten können.
Formularoptionen
Sie können Optionen für Ihr Formular erstellen, damit es von mehreren Formularen gemeinsam genutzt werden kann, indem Sie die Funktion formOptions verwenden.
Beispiel
const formOpts = formOptions({
defaultValues: {
firstName: '',
lastName: '',
hobbies: [],
} as Person,
})
const formOpts = formOptions({
defaultValues: {
firstName: '',
lastName: '',
hobbies: [],
} as Person,
})
Formularinstanz
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 mit dem Hook createForm, der von den Formularoptionen bereitgestellt wird. Der Hook akzeptiert ein Objekt mit einer onSubmit Funktion, die aufgerufen wird, wenn das Formular übermittelt wird.
const form = createForm(() => ({
...formOpts,
onSubmit: async ({ value }) => {
// Do something with form data
console.log(value)
},
}))
const form = createForm(() => ({
...formOpts,
onSubmit: async ({ value }) => {
// Do something with form data
console.log(value)
},
}))
Sie können auch eine Formularinstanz erstellen, ohne formOptions zu verwenden, indem Sie die eigenständige createForm API verwenden.
const form = createForm<Person>(() => ({
onSubmit: async ({ value }) => {
// Do something with form data
console.log(value)
},
defaultValues: {
firstName: '',
lastName: '',
hobbies: [],
},
}))
const form = createForm<Person>(() => ({
onSubmit: async ({ value }) => {
// Do something with form data
console.log(value)
},
defaultValues: {
firstName: '',
lastName: '',
hobbies: [],
},
}))
Field
Ein Feld repräsentiert ein einzelnes Formulareingabeelement, wie z. B. ein Textfeld oder eine Checkbox. Felder werden mit der Komponente form.Field erstellt, die von der Formularinstanz bereitgestellt wird. Die Komponente akzeptiert eine `name`-Prop, die einem Schlüssel in den Standardwerten des Formulars entsprechen sollte. Sie akzeptiert auch eine `children`-Prop, die eine Render-Prop-Funktion ist, die ein Feldobjekt als Argument erhält.
Beispiel
<form.Field
name="firstName"
children={(field) => (
<input
name={field().name}
value={field().state.value}
onBlur={field().handleBlur}
onInput={(e) => field().handleChange(e.target.value)}
/>
)}
/>
<form.Field
name="firstName"
children={(field) => (
<input
name={field().name}
value={field().state.value}
onBlur={field().handleBlur}
onInput={(e) => field().handleChange(e.target.value)}
/>
)}
/>
Feldstatus
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 die Eigenschaft field().state zugreifen.
Beispiel
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
Verständnis von 'isDirty' in verschiedenen Bibliotheken
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
Feld-API
Die Feld-API ist ein Objekt, das an die Render-Prop-Funktion übergeben wird, wenn ein Feld erstellt wird. Es stellt Methoden zur Bearbeitung des Feldzustands bereit.
Beispiel
<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)}
/>
Validierung
@tanstack/solid-form bietet sowohl synchrone als auch asynchrone Validierung "out of the box". Validierungsfunktionen können mit der validators-Prop an die Komponente form.Field übergeben werden.
Beispiel
<form.Field
name="firstName"
validators={{
onChange: ({ value }) =>
!value
? 'A first name is required'
: value.length < 3
? 'First name must be at least 3 characters'
: undefined,
onChangeAsync: async ({ value }) => {
await new Promise((resolve) => setTimeout(resolve, 1000))
return value.includes('error') && 'No "error" allowed in first name'
},
}}
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>
</>
)}
/>
<form.Field
name="firstName"
validators={{
onChange: ({ value }) =>
!value
? 'A first name is required'
: value.length < 3
? 'First name must be at least 3 characters'
: undefined,
onChangeAsync: async ({ value }) => {
await new Promise((resolve) => setTimeout(resolve, 1000))
return value.includes('error') && 'No "error" allowed in first name'
},
}}
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>
</>
)}
/>
Validierung mit Standard-Schema-Bibliotheken
Zusätzlich zu handgeschriebenen Validierungsoptionen unterstützen wir auch die Standard Schema Spezifikation.
Sie können ein Schema mit einer beliebigen der Bibliotheken definieren, die die Spezifikation implementieren, und es an einen Formular- oder Feldvalidator übergeben.
Unterstützte Bibliotheken umfassen:
- Zod (v3.24.0 oder höher)
- Valibot (v1.0.0 oder höher)
- ArkType (v2.1.20 oder höher)
- Yup (v1.7.0 oder höher)
import { z } from 'zod'
// ...
;<form.Field
name="firstName"
validators={{
onChange: z.string().min(3, 'First name must be at least 3 characters'),
onChangeAsyncDebounceMs: 500,
onChangeAsync: z.string().refine(
async (value) => {
await new Promise((resolve) => setTimeout(resolve, 1000))
return !value.includes('error')
},
{
message: 'No "error" allowed in first name',
},
),
}}
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>
</>
)}
/>
import { z } from 'zod'
// ...
;<form.Field
name="firstName"
validators={{
onChange: z.string().min(3, 'First name must be at least 3 characters'),
onChangeAsyncDebounceMs: 500,
onChangeAsync: z.string().refine(
async (value) => {
await new Promise((resolve) => setTimeout(resolve, 1000))
return !value.includes('error')
},
{
message: 'No "error" allowed in first name',
},
),
}}
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>
</>
)}
/>
Reaktivität
@tanstack/solid-form bietet verschiedene Möglichkeiten, sich an Änderungen des Formular- und Feldzustands anzumelden, am bemerkenswertesten den Hook form.useStore und die Komponente form.Subscribe. Diese Methoden ermöglichen es Ihnen, die Rendering-Performance Ihres Formulars zu optimieren, indem Sie Komponenten nur dann aktualisieren, wenn es notwendig ist.
Beispiel
const firstName = form.useStore((state) => state.values.firstName)
//...
<form.Subscribe
selector={(state) => ({
canSubmit: state.canSubmit,
isSubmitting: state.isSubmitting,
})}
children={(state) => (
<button type="submit" disabled={!state().canSubmit}>
{state().isSubmitting ? '...' : 'Submit'}
</button>
)}
/>
const firstName = form.useStore((state) => state.values.firstName)
//...
<form.Subscribe
selector={(state) => ({
canSubmit: state.canSubmit,
isSubmitting: state.isSubmitting,
})}
children={(state) => (
<button type="submit" disabled={!state().canSubmit}>
{state().isSubmitting ? '...' : 'Submit'}
</button>
)}
/>
Array-Felder
Array-Felder ermöglichen es Ihnen, eine Liste von Werten innerhalb eines Formulars zu verwalten, wie z. B. eine Liste von Hobbys. Sie können ein Array-Feld mit der form.Field Komponente mit der Prop mode="array" erstellen.
Wenn Sie mit Array-Feldern arbeiten, können Sie die Methoden pushValue, removeValue, swapValues und moveValue des Feldes verwenden, um Werte im Array hinzuzufügen, zu entfernen und zu tauschen.
Beispiel
<form.Field
name="hobbies"
mode="array"
children={(hobbiesField) => (
<div>
Hobbies
<div>
<Show
when={hobbiesField().state.value.length > 0}
fallback={'No hobbies found.'}
>
<Index each={hobbiesField().state.value}>
{(_, i) => (
<div>
<form.Field
name={`hobbies[${i}].name`}
children={(field) => (
<div>
<label for={field().name}>Name:</label>
<input
id={field().name}
name={field().name}
value={field().state.value}
onBlur={field().handleBlur}
onInput={(e) => field().handleChange(e.target.value)}
/>
<button
type="button"
onClick={() => hobbiesField().removeValue(i)}
>
X
</button>
</div>
)}
/>
<form.Field
name={`hobbies[${i}].description`}
children={(field) => {
return (
<div>
<label for={field().name}>Description:</label>
<input
id={field().name}
name={field().name}
value={field().state.value}
onBlur={field().handleBlur}
onInput={(e) => field().handleChange(e.target.value)}
/>
</div>
)
}}
/>
</div>
)}
</Index>
</Show>
</div>
<button
type="button"
onClick={() =>
hobbiesField().pushValue({
name: '',
description: '',
yearsOfExperience: 0,
})
}
>
Add hobby
</button>
</div>
)}
/>
<form.Field
name="hobbies"
mode="array"
children={(hobbiesField) => (
<div>
Hobbies
<div>
<Show
when={hobbiesField().state.value.length > 0}
fallback={'No hobbies found.'}
>
<Index each={hobbiesField().state.value}>
{(_, i) => (
<div>
<form.Field
name={`hobbies[${i}].name`}
children={(field) => (
<div>
<label for={field().name}>Name:</label>
<input
id={field().name}
name={field().name}
value={field().state.value}
onBlur={field().handleBlur}
onInput={(e) => field().handleChange(e.target.value)}
/>
<button
type="button"
onClick={() => hobbiesField().removeValue(i)}
>
X
</button>
</div>
)}
/>
<form.Field
name={`hobbies[${i}].description`}
children={(field) => {
return (
<div>
<label for={field().name}>Description:</label>
<input
id={field().name}
name={field().name}
value={field().state.value}
onBlur={field().handleBlur}
onInput={(e) => field().handleChange(e.target.value)}
/>
</div>
)
}}
/>
</div>
)}
</Index>
</Show>
</div>
<button
type="button"
onClick={() =>
hobbiesField().pushValue({
name: '',
description: '',
yearsOfExperience: 0,
})
}
>
Add hobby
</button>
</div>
)}
/>
Dies sind die grundlegenden Konzepte und Terminologie, die in der @tanstack/solid-form Bibliothek verwendet werden. Das Verständnis dieser Konzepte wird Ihnen helfen, effektiver mit der Bibliothek zu arbeiten und komplexe Formulare mühelos zu erstellen.
Bytes abonnieren
Ihre wöchentliche Dosis JavaScript-Nachrichten. Jeden Montag kostenlos an über 100.000 Entwickler geliefert.
Bytes abonnieren
Ihre wöchentliche Dosis JavaScript-Nachrichten. Jeden Montag kostenlos an über 100.000 Entwickler geliefert.