Form
interfaz Desde 1.2.0 Sin import
Estado de un formulario que devuelve useForm. fields son señales escribibles, una por
campo; las demás propiedades son señales de sólo lectura.
Se autoimporta en los componentes y en app/.
import type { Form } from "@meekojs/meeko/framework";Código fuente src/app/composables/useForm.ts:66
Declaración #
interface Form<Values, Result> {
readonly fields: { readonly [K in keyof Values]: Signal<Values[K]> }
readonly errors: ReadonlySignal<{ readonly [P in Paths<Values>]?: string }>
readonly error: ReadonlySignal<string | null>
readonly failure: ReadonlySignal<Error | null>
readonly pending: ReadonlySignal<boolean>
readonly submitted: ReadonlySignal<boolean>
readonly dirty: ReadonlySignal<boolean>
readonly submit: (event?: Event) => Promise<Result | undefined>
readonly reset: { (values?: Partial<Values>): void; (event: Event): void }
readonly load: (values: Partial<Values>) => void
readonly trySubmit: (event?: Event) => Promise<FormSubmission<Result>>
readonly commit: (values?: Partial<Values>) => void
readonly field: <K extends keyof Values & string>(name: K) => FormField<Values[K]>
readonly csrfToken: string | undefined
}Parámetros de tipo #
-
Values Valores de los campos: la entrada del schema o, sin schema, el tipo de
initial.-
Result Lo que devuelve
submitcuando el envío termina bien.
Ejemplo #
<!-- app/components/NameField.meeko: un campo que recibe el formulario del padre -->
<script lang="ts">
import type { Form } from "@meekojs/meeko/framework";
const props = defineProps<{ form: Form<{ name: string }, unknown> }>();
</script>
<template>
<input model="props.form.fields.name" bind:aria-invalid="props.form.errors.value.name ? 'true' : null">
<p if:when="props.form.errors.value.name">{props.form.errors.value.name}</p>
</template>Propiedades #
fields
#
readonly fields: { readonly [K in keyof Values]: Signal<Values[K]> }Una señal escribible por campo, con el valor de initial; se usa con model y model:value.
errors
#
readonly errors: ReadonlySignal<{ readonly [P in Paths<Values>]?: string }>Primer mensaje de cada campo con un error, por ruta ("name", "items.0.name"): de la
validación del navegador o de los issues de un 400 del servidor. Un campo sin error no
tiene clave.
error
#
readonly error: ReadonlySignal<string | null>Mensaje del formulario completo, o null: un issue con ruta "" o de un campo que el
formulario no tiene, o el texto de un error que no es de validación (véase errorMessage).
failure
#
readonly failure: ReadonlySignal<Error | null>Error original del último envío fallido (también el ClientError de un 400), o null.
pending
#
readonly pending: ReadonlySignal<boolean>true mientras se valida de forma asíncrona o se ejecuta submit.
submitted
#
readonly submitted: ReadonlySignal<boolean>true cuando el último envío terminó bien; vuelve a false al enviar de nuevo y con reset.
dirty
#
readonly dirty: ReadonlySignal<boolean>true si algún campo difiere (comparando arrays y objetos por contenido) de los valores iniciales.
submit
#
readonly submit: (event?: Event) => Promise<Result | undefined>Envía el formulario: llama a event.preventDefault(), valida con el schema, ejecuta submit
con su salida y lleva los errores a errors y error. Resuelve con lo que devuelve submit,
o con undefined si los datos no son válidos, si el envío falla o si ya hay uno en curso (se
ignora). Nunca rechaza. En SSR no hace nada.
reset
#
readonly reset: { (values?: Partial<Values>): void; (event: Event): void }Vuelve a initial, o a initial combinado con values. Borra los errores y el estado del
último envío. También sirve como handler de reset en un <form> nativo.
load
#
readonly load: (values: Partial<Values>) => voidCarga valores en los campos (por ejemplo, un registro para editar). Las claves omitidas
conservan su valor actual. Los valores cargados son la nueva referencia de dirty, pero
reset() siempre vuelve al initial declarado. Limpia errores y estado del último envío.
trySubmit
#
readonly trySubmit: (event?: Event) => Promise<FormSubmission<Result>>Envía el formulario como submit, pero resuelve con un FormSubmission que dice cómo
terminó: { ok: true, result }, o { ok: false, reason } con "invalid", "error" o
"skipped". Nunca rechaza.
commit
#
readonly commit: (values?: Partial<Values>) => voidEscribe values en sus campos y toma los valores de todos los campos como los nuevos valores
iniciales de dirty: dirty vuelve a false. A diferencia de reset, no
borra submitted, errors, error ni failure. Sirve tras guardar, para que lo guardado sea
la nueva referencia sin perder el «Guardado».
field
#
readonly field: <K extends keyof Values & string>(name: K) => FormField<Values[K]>Las piezas de un campo para cablearlo en un componente propio: su señal, su mensaje, si es
inválido, su name y unos id estables entre SSR e hidratación (véase FormField).
Devuelve siempre el mismo objeto para el mismo campo.
csrfToken
#
readonly csrfToken: string | undefinedToken CSRF de la sesión para el campo oculto _csrf de un formulario nativo, o undefined
sin sesión: en SSR, el de la petición; en el navegador, el de la meta meeko-csrf-token. Un
envío con JavaScript no lo necesita, porque lo envía en la cabecera.
Véase también #
- Formularios: useForm Framework full-stack