Form

Um componente de formulário com validação e tratamento de envio embutidos.

Uso

Use o componente Form para validar os dados do formulário usando qualquer biblioteca de validação que suporte o Standard Schema, como Valibot, Zod, Regle, Yup, Joi ou Superstruct, ou a sua própria lógica de validação.

Ele funciona com o componente FormField para exibir mensagens de erro ao redor dos elementos do formulário automaticamente.

Validação por schema

Ele exige duas props:

state - a reactive object holding the form's state.
schema - any Standard Schema or Superstruct.

No validation library is included by default, ensure you install the one you need.

Validação personalizada

Use a prop validate para aplicar a sua própria lógica de validação.

A função de validação precisa retornar uma lista de erros com os seguintes atributos:

message - the error message to display.
name - the name of the FormField to send the error to.

Ela pode ser usada junto com a prop schema para lidar com casos de uso complexos.

Relato de erros

Os erros são associados ao FormField correspondente por meio da prop name dele. Um erro no campo email é exibido por <FormField name="email">.

Campos aninhados são associados usando notação de ponto. Um schema como { user: z.object({ email: z.string() }) } será aplicado a <FormField name="user.email">.

Os erros em itens de array incluem o índice no nome (ex.: tags.0, tags.1) e não corresponderão a <FormField name="tags"> apenas pelo name. Use a prop error-pattern com uma expressão regular como /^tags\..+/ para capturá-los. Isso é especialmente útil para componentes como o InputTags.

Eventos de input

O componente Form dispara a validação automaticamente quando um input emite um evento input, change ou blur.

Validation on input occurs as you type.
Validation on change occurs when you commit to a value.
Validation on blur happens when an input loses focus.

Você pode controlar quando a validação acontece usando a prop validate-on.

O formulário sempre valida no envio.

validate-on

Você pode usar o composable useFormField para implementar isso dentro dos seus próprios componentes.

Evento de erro

Você pode escutar o evento @error para tratar os erros. Esse evento é disparado quando o formulário é enviado e contém um array de objetos FormError com os seguintes campos:

id - the input's id.
name - the name of the FormField
message - the error message to display.

Aqui está um exemplo que foca o primeiro elemento de input com erro após o envio do formulário:

Validação HTML5 4.5+

Ao chamar form.submit() programaticamente, o componente Form dispara automaticamente a validação nativa HTML5 antes do envio.

Isso é particularmente útil quando o botão de envio está fora do elemento de formulário, como no rodapé de um modal.

Formulários aninhados

Use a prop nested para aninhar vários componentes Form e vincular as funções de validação deles. Nesse caso, validar o formulário pai valida automaticamente todos os outros formulários dentro dele.

Formulários aninhados herdam diretamente o estado do pai, então você não precisa definir um estado separado para eles. Você pode usar a prop name para mirar um atributo aninhado dentro do estado do pai.

Ela pode ser usada para adicionar campos dinamicamente com base na entrada do usuário:

Ou para validar inputs de lista:

API

Props

Prop	Default	Type
`id`		`string \| number`
`schema`		`S` Schema to validate the form state. Supports Standard Schema objects, Yup, Joi, and Superstructs.
`state`		`N extends false ? Partial<InferInput<S>> : never` An object representing the current state of the form.
`validate`		`(state: Partial<InferInput<S>>): FormError<string>[] \| Promise<FormError<string>[]>` Custom validation function to validate the form state.
`validateOn`	`['blur', 'change', 'input']`	`FormInputEvents[]` The list of input events that trigger the form validation.
`disabled`		`boolean` Disable all inputs inside the form.
`name`		`string` The `name` attribute of the form element. For nested forms (`nested` is true), this is also used as the path of the form's state within its parent form.
`validateOnInputDelay`	`300`	`number` Delay in milliseconds before validating the form on input events.
`transform`	`true as T`	`T` If true, applies schema transformations on submit.
`nested`	`false`	`N` If true, this form will attach to its parent Form and validate at the same time.
`loadingAuto`	`true`	`boolean` When `true`, all form elements will be disabled on `@submit` event. This will cause any focused input elements to lose their focus state.
`acceptcharset`		`string`
`action`		`string`
`autocomplete`		`string`
`enctype`		`string`
`method`		`string`
`novalidate`		`false \| true \| "true" \| "false"`
`target`		`string`
`ui`		`{ base?: any; }`

Este componente também suporta todos os atributos HTML nativos de <form>.

Slots

Slot	Type
`default`	`{ errors: FormErrorWithId[]; loading: boolean; }`

Emits

Event	Type
`submit`	`[event: FormSubmitEvent<FormData<S, T>>]`
`error`	`[event: FormErrorEvent]`

Expose

Você pode acessar a instância tipada do componente usando useTemplateRef.

<script setup lang="ts">
const form = useTemplateRef('form')
</script>

<template>
  <NForm ref="form" />
</template>

Isso dará a você acesso ao seguinte:

Name	Type
`submit()`	`Promise<void>` Triggers form submission with HTML5 validation.
`validate(opts: { name?: keyof T \| (keyof T)[], silent?: boolean, nested?: boolean, transform?: boolean })`	`Promise<T>` Triggers form validation. Will raise any errors unless `opts.silent` is set to true.
`clear(path?: keyof T \| RegExp)`	`void` Clears form errors associated with a specific path. If no path is provided, clears all form errors.
`getErrors(path?: keyof T \| RegExp)`	`FormErrorWithId[]` Retrieves form errors associated with a specific path. If no path is provided, returns all form errors.
`setErrors(errors: FormError[], name?: keyof T \| RegExp)`	`void` Sets form errors for a given path. If no path is provided, overrides all errors.
`errors`	`Ref<FormErrorWithId[]>` A reference to the array containing validation errors. Use this to access or manipulate the error information.
`disabled`	`Ref<boolean>`
`dirty`	`Ref<boolean>` `true` if at least one form field has been updated by the user.
`dirtyFields`	`ReadonlySet<DeepReadonly<keyof T>>` Tracks fields that have been modified by the user.
`touchedFields`	`ReadonlySet<DeepReadonly<keyof T>>` Tracks fields that the user interacted with.
`blurredFields`	`ReadonlySet<DeepReadonly<keyof T>>` Tracks fields blurred by the user.

Tema

app.config.ts

export default defineAppConfig({
  ui: {
    form: {
      base: ''
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        form: {
          base: ''
        }
      }
    })
  ]
})

Changelog

No recent changes

FileUpload

Um elemento de input para enviar arquivos.

FormField

Um wrapper para elementos de formulário que fornece validação e tratamento de erros.