Composables

useValidation

Composable per la validazione reattiva di singoli campi con supporto regole pipe-separated e integrazione i18n.

Panoramica

useValidation fornisce validazione reattiva per un singolo campo o valore. Supporta watch automatico su una ref, validazione manuale on-demand, e restituisce chiavi i18n come errori — pronte per essere tradotte con t() di @pzeta/vue-i18n.

È il composable da usare quando si costruisce un componente form personalizzato o si vuole validare un campo fuori da DynamicFormLayouts.

API

import { useValidation } from '@pzeta/vue-form'

export function useValidation(
  modelValue?: Ref<unknown> | UseValidationOptions,
  validationRules?: string,
): UseValidationReturn

Tipi

export interface UseValidationOptions {
  rules?: string
  validateOnChange?: boolean // default: true
}

export interface UseValidationReturn {
  errors: Ref<string[]>
  isValid: Ref<boolean>
  firstError: ComputedRef<string | undefined>
  validate: (value?: unknown, customRules?: string) => { isValid: boolean; errors: string[] }
  clearErrors: () => void
}

Parametri

Parametro	Tipo	Default	Descrizione
`modelValue`	`Ref<unknown> \| UseValidationOptions`	—	Ref del valore da validare (per watch reattivo) oppure oggetto opzioni
`validationRules`	`string`	—	Regole pipe-separated (es. `'required\|email\|min:5'`)

Opzioni (quando si passa un oggetto)

Opzione	Tipo	Default	Descrizione
`rules`	`string`	—	Regole di validazione
`validateOnChange`	`boolean`	`true`	Se `false`, disabilita il watch automatico sulla ref

Valore di ritorno

Proprietà	Tipo	Descrizione
`errors`	`Ref<string[]>`	Array di chiavi i18n degli errori correnti
`isValid`	`Ref<boolean>`	`true` se non ci sono errori
`firstError`	`ComputedRef<string \| undefined>`	Prima chiave errore, o `undefined` se valido
`validate`	`(value?, customRules?) => { isValid, errors }`	Esegue validazione manuale e aggiorna lo stato
`clearErrors`	`() => void`	Azzera tutti gli errori

Esempi

Validazione reattiva con ref

Il composable mette in watch automatico la ref. Ogni volta che il valore cambia, la validazione viene ri-eseguita.

Disabilitare il watch automatico

const valore = ref('')
const { validate, errors } = useValidation(
  { rules: 'required|min:3', validateOnChange: false }
)

// La validazione parte solo quando chiamata esplicitamente
const onBlur = () => validate(valore.value)

Validazione manuale senza ref

Utile per validare valori non reattivi o per validazioni on-submit.

const { validate, clearErrors } = useValidation()

const onSubmit = () => {
  const result = validate(formData.value.nome, 'required|min:2|max:100')
  if (!result.isValid) {
    console.error(result.errors)
  }
}

Override delle regole al momento della validazione

const { validate } = useValidation()

// Regole diverse a seconda del contesto
const validateField = (value: string, isAdmin: boolean) => {
  const rules = isAdmin ? 'required' : 'required|min:8'
  return validate(value, rules)
}

Integrazione con i18n — traduzione degli errori

Gli errori restituiti sono chiavi i18n nel formato validation.core.required. Per mostrarli in italiano (o in qualsiasi lingua configurata), usare t():

<script setup lang="ts">
import { ref } from 'vue'
import { useValidation } from '@pzeta/vue-form'
import { useI18n } from '@pzeta/vue-i18n'

const { t } = useI18n()
const password = ref('')
const { firstError, errors, isValid } = useValidation(password, 'required|min:8|password')
</script>

<template>
  <input v-model="password" type="password" />

  <!-- Mostra primo errore tradotto -->
  <p v-if="firstError" class="text-red-500 text-sm">
    {{ t(firstError) }}
  </p>

  <!-- Oppure lista tutti gli errori -->
  <ul v-if="!isValid">
    <li v-for="err in errors" :key="err" class="text-red-400 text-xs">
      {{ t(err) }}
    </li>
  </ul>
</template>

Note

Le chiavi errore hanno il formato "validation.categoria.chiave|param:valore". La parte dopo il | contiene i parametri da passare a t() per la sostituzione dei placeholder (es. {min}).
Per la traduzione automatica di errori con parametri, usare ValidationService.translateError() invece di t() diretto.
clearErrors() è utile per resettare lo stato quando l'utente abbandona un campo o il form viene reimpostato.

useUiTranslations

Accesso alle traduzioni UI integrate di @pzeta/vue-form per componenti custom e applicazioni che non usano @pzeta/vue-i18n.

Services

API di servizio di @pzeta/vue-form.