Formulaires et validation

Ce que tu vas apprendre

• Assembler UForm, UFormField et des champs de saisie.
• Décrire les règles de validation avec un schéma.
• Récupérer les données validées à l'envoi.

Le formulaire complet

Voici un formulaire d'ajout de recette. Lis-le d'abord, on l'explique ensuite.

<script setup lang="ts">
import * as z from 'zod'

const schema = z.object({
  titre: z.string().min(3, 'Au moins 3 caractères'),
  description: z.string().optional()
})

const state = reactive({ titre: '', description: '' })

function envoyer(event: { data: z.output<typeof schema> }) {
  console.log(event.data)
}
</script>

<template>
  <UForm :schema="schema" :state="state" @submit="envoyer">
    <UFormField label="Titre" name="titre">
      <UInput v-model="state.titre" />
    </UFormField>
    <UFormField label="Description" name="description">
      <UTextarea v-model="state.description" />
    </UFormField>
    <UButton type="submit" label="Enregistrer" />
  </UForm>
</template>

Il faut installer la bibliothèque de validation : npm install zod.

Les pièces du formulaire

UFormField porte un label et un name. Le name relie le champ à la clé du schéma : c'est lui qui permet d'afficher le bon message d'erreur au bon endroit.

L'état du formulaire

state est un objet réactif : quand tu tapes dans un champ, sa valeur change, et inversement. Chaque champ s'y lie avec v-model.

const state = reactive({ titre: '', description: '' })

reactive est fourni par Vue et importé automatiquement par Nuxt. Les clés de state doivent porter les mêmes noms que celles du schéma.

Le schéma de validation

Un schéma décrit à quoi doit ressembler une donnée correcte. Nuxt UI accepte plusieurs bibliothèques ; l'exemple utilise Zod.

const schema = z.object({
  titre: z.string().min(3, 'Au moins 3 caractères'),
  description: z.string().optional()
})

• z.string() exige un texte.
• .min(3, '...') impose une longueur et fixe le message d'erreur.
• .optional() autorise un champ vide.

Si une règle échoue, le message apparaît sous le champ concerné.

Envoyer les données

L'événement @submit ne se déclenche que si la validation réussit. Il reçoit un objet event dont la clé data contient les valeurs validées.

function envoyer(event: { data: z.output<typeof schema> }) {
  console.log(event.data)
}

Pour sauvegarder la recette, remplace console.log par un appel à une route d'API, comme dans le cours Nuxt sur la récupération des données.

Valider plus finement

Un schéma peut contrôler le format d'un champ. Pour un champ de courriel :

const schema = z.object({
  courriel: z.string().email('Courriel invalide')
})

La prop validate-on de UForm règle le moment de la validation : à la sortie du champ (blur), à la modification (change) ou à la saisie (input).

Ajouter une case à cocher

<UFormField name="vegetarien">
  <UCheckbox v-model="state.vegetarien" label="Recette végétarienne" />
</UFormField>

Pense à ajouter vegetarien: z.boolean() au schéma et vegetarien: false à state.

À retenir

• UForm reçoit un schema et un state, et appelle @submit seulement si tout est valide.
• UFormField donne un label et un name ; le name reprend la clé du schéma.
• Les champs se lient à state avec v-model (UInput, UTextarea, UCheckbox).
• Le schéma décrit les règles et les messages d'erreur ; Zod est un choix possible parmi d'autres.
• event.data contient les valeurs validées.