Formularios reactivos y v-model avanzado

v-model a fondo

v-model es açúcar sintáctico sobre :value + @input para inputs nativos. Pero el tipo de evento varía según el elemento:

Vue maneja estas diferencias automáticamente:

<script setup lang="ts">
import { ref } from 'vue'

const texto = ref('')
const activo = ref(false)
const opcionRadio = ref('a')
const seleccionMultiple = ref<string[]>([])
</script>

<template>
  <!-- Text input -->
  <input v-model="texto" />

  <!-- Checkbox — enlaza con boolean -->
  <input v-model="activo" type="checkbox" />

  <!-- Radio buttons — enlaza con string -->
  <input v-model="opcionRadio" type="radio" value="a" />
  <input v-model="opcionRadio" type="radio" value="b" />

  <!-- Select múltiple — enlaza con array -->
  <select v-model="seleccionMultiple" multiple>
    <option>Vue</option>
    <option>React</option>
    <option>Angular</option>
  </select>
</template>

Modificadores de v-model

.trim — eliminar espacios

<input v-model.trim="nombre" />
<!-- nombre nunca tendrá espacios al inicio o al final -->

.number — convertir a número

<input v-model.number="edad" type="number" />
<!-- edad será siempre un número (o NaN si el campo está vacío) -->

.lazy — actualizar en blur

<!-- Actualiza el ref solo cuando el input pierde el foco -->
<input v-model.lazy="busqueda" />

Combinar modificadores:

<input v-model.trim.lazy="nombre" />
<!-- Elimina espacios Y solo actualiza en blur -->

Checkbox con valores personalizados

Por defecto, un checkbox enlaza a true/false. Puedes personalizar los valores:

<script setup lang="ts">
import { ref } from 'vue'
const estado = ref<'activo' | 'inactivo'>('inactivo')
</script>

<template>
  <input
    v-model="estado"
    type="checkbox"
    true-value="activo"
    false-value="inactivo"
  />
  <p>Estado: {{ estado }}</p>
</template>

Construir formularios complejos sin librerías

Para formularios simples, reactive() con validación manual es suficiente:

interface FormRegistro {
  nombre: string
  email: string
  password: string
  confirmar: string
}

function useFormRegistro() {
  const datos = reactive<FormRegistro>({
    nombre: '',
    email: '',
    password: '',
    confirmar: '',
  })

  const errores = reactive<Partial<Record<keyof FormRegistro, string>>>({})
  const tocados = reactive<Partial<Record<keyof FormRegistro, boolean>>>({})

  function validar(campo: keyof FormRegistro): boolean {
    tocados[campo] = true

    switch (campo) {
      case 'nombre':
        errores.nombre = datos.nombre.trim().length >= 2
          ? undefined
          : 'Mínimo 2 caracteres'
        break
      case 'email':
        errores.email = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(datos.email)
          ? undefined
          : 'Email inválido'
        break
      case 'password':
        errores.password = datos.password.length >= 8
          ? undefined
          : 'Mínimo 8 caracteres'
        if (tocados.confirmar) validar('confirmar')
        break
      case 'confirmar':
        errores.confirmar = datos.confirmar === datos.password
          ? undefined
          : 'Las contraseñas no coinciden'
        break
    }

    return !errores[campo]
  }

  function validarTodo(): boolean {
    const campos: (keyof FormRegistro)[] = ['nombre', 'email', 'password', 'confirmar']
    return campos.every(validar)
  }

  function resetear(): void {
    Object.assign(datos, { nombre: '', email: '', password: '', confirmar: '' })
    Object.keys(errores).forEach(k => delete (errores as Record<string, unknown>)[k])
    Object.keys(tocados).forEach(k => delete (tocados as Record<string, unknown>)[k])
  }

  return { datos, errores, tocados, validar, validarTodo, resetear }
}

VeeValidate — validación declarativa

VeeValidate v4 es la librería de formularios más popular para Vue:

npm install vee-validate zod @vee-validate/zod

useForm() — gestión del formulario completo

<script setup lang="ts">
import { useForm } from 'vee-validate'
import { toTypedSchema } from '@vee-validate/zod'
import { z } from 'zod'

const schema = toTypedSchema(z.object({
  nombre: z.string().min(2, 'Mínimo 2 caracteres'),
  email: z.string().email('Email inválido'),
  edad: z.number().min(18, 'Debe ser mayor de edad'),
}))

const { handleSubmit, defineField, errors, resetForm } = useForm({
  validationSchema: schema,
  initialValues: { nombre: '', email: '', edad: 0 },
})

// defineField crea el binding para v-model
const [nombre, nombreProps] = defineField('nombre')
const [email, emailProps] = defineField('email')

const onSubmit = handleSubmit((valores) => {
  console.log('Válido:', valores) // TypeScript conoce los tipos exactos
})
</script>

<template>
  <form @submit="onSubmit">
    <input v-model="nombre" v-bind="nombreProps" />
    <span v-if="errors.nombre">{{ errors.nombre }}</span>

    <input v-model="email" v-bind="emailProps" type="email" />
    <span v-if="errors.email">{{ errors.email }}</span>

    <button type="submit">Enviar</button>
    <button type="button" @click="resetForm()">Resetear</button>
  </form>
</template>

Accesibilidad en formularios

Un formulario accesible requiere:

<template>
  <form @submit.prevent="enviar" novalidate aria-label="Formulario de contacto">
    <div role="group">
      <label for="nombre">
        Nombre
        <span aria-hidden="true">*</span>
      </label>
      <input
        id="nombre"
        v-model.trim="form.nombre"
        type="text"
        autocomplete="given-name"
        required
        :aria-required="true"
        :aria-invalid="!!errores.nombre || undefined"
        :aria-describedby="errores.nombre ? 'error-nombre' : undefined"
        @blur="validarCampo('nombre')"
      />
      <span
        v-if="errores.nombre"
        id="error-nombre"
        role="alert"
        aria-live="polite"
      >
        {{ errores.nombre }}
      </span>
    </div>
  </form>
</template>

Cargar y guardar datos del formulario

Patrón común para formularios de edición:

<script setup lang="ts">
import { reactive, onMounted } from 'vue'

const { id } = defineProps<{ id: number }>()

const form = reactive({
  nombre: '',
  email: '',
  cargando: false,
  guardando: false,
})

onMounted(async () => {
  form.cargando = true
  const res = await fetch(`/api/usuarios/${id}`)
  const datos = await res.json() as { nombre: string; email: string }
  form.nombre = datos.nombre
  form.email = datos.email
  form.cargando = false
})

async function guardar(): Promise<void> {
  form.guardando = true
  await fetch(`/api/usuarios/${id}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ nombre: form.nombre, email: form.email }),
  })
  form.guardando = false
}
</script>

Práctica

1. Formulario de contacto: Construye un formulario con nombre, email, asunto y mensaje. Valida en blur, muestra errores accesibles con role="alert". Deshabilita el botón de envío hasta que todo sea válido.
2. Formulario multi-paso: Implementa un formulario de registro en 3 pasos (datos personales, credenciales, preferencias). Guarda el estado entre pasos con reactive(). Valida cada paso antes de avanzar.
3. Integración con VeeValidate + Zod: Convierte el formulario de contacto para usar VeeValidate y Zod. Compara la experiencia con la validación manual.

En la siguiente lección aprenderemos a manejar datos asíncronos con composables y el componente Suspense.