Vue.js: Formulários e v-model

Q: P: Como se usa o v-model em componentes personalizados?

R: Use defineProps(['modelValue']) + defineEmits(['update:modelValue']) dentro do componente. Use v-model no componente pai. No Vue 3.4 ou superior, use defineModel para substituir 10 linhas por apenas 1.

Q: P: Por que o v-model.number não está funcionando?

R: Ele deve ser usado com type="number". Como alternativa, use parseFloat() manualmente.

Q: P: Como faço para enviar um arquivo e exibir uma pré-visualização?

R: Use FileReader.readAsDataURL() para ler o arquivo como uma string Base64 e, em seguida, atribua-o a <img src="...">. Use FormData para o envio.

Q: P: Qual é a diferença entre os modificadores .lazy e .debounce para o v-model?

R: O .lazy é acionado pelo evento change (após perder o foco), o que reduz a sobrecarga da validação em tempo real. O .debounce é um modificador personalizado que deve ser implementado no componente filho; ele aciona o último evento dentro de 300 ms.

Q: P: Como faço para serializar os dados do formulário em JSON para envio?

R: Basta usar JSON.stringify(form) (não é necessário usar FormData, a menos que você esteja enviando arquivos). O backend pode simplesmente receber o JSON.

Q: P: O defineModel substitui toda a sintaxe do v-model ?

R: Sim. defineModel('modelValue') is equivalent to the 10 lines of code in props.modelValue + emit('update:modelValue'). É totalmente compatível com versões anteriores.

Última atualização: 2026-08-26

Os formulários são a interação central das aplicações web — login, cadastro, pesquisa e configurações dependem, todos, do processamento de formulários. O v-model do Vue é um “açúcar sintático” para o processamento de formulários, tornando o código de vinculação bidirecional extremamente conciso (1 linha contra 5 linhas).

O defineModel no Vue 3.4+ simplifica ainda mais a implementação do v-model. Formulários complexos também exigem recursos avançados, como validação, serialização e envio de arquivos. Esta lição aborda cinco cenários principais relacionados a formulários.

1. O que você vai aprender

Como funciona o v-model (essencialmente, trata-se de um “açúcar sintático” para “props + emit”)
Componentes personalizados do modelo V
Simplificação do defineModel (Vue 3.4+)
Validação de formulários (VeeValidate / Personalizada)
Design de formulários complexos (campos aninhados/dinâmicos)
Serialização e envio de formulários
Envio e visualização de arquivos

(1) Desafio: 5 campos de formulário, 10 linhas de código v-model

O formulário de login da Alice tinha 5 campos, cada um com vinculação ao v-model:

VUE

<!-- ❌ The "Broken" Version: 5 fields + 5 refs + 5 v-model -->
<template>
  <form @submit.prevent="handleLogin">
    <input v-model="username">
    <input v-model="password" type="password">
    <input v-model="email" type="email">
    <input v-model="phone">
    <input v-model="captcha">
    <button>Login</button>
  </form>
</template>

<script setup>
import { ref } from 'vue'
const username = ref('')
const password = ref('')
const email = ref('')
const phone = ref('')
const captcha = ref('')
</script>

5 campos = 10 linhas de texto padrão. 10 campos equivalem a 20 linhas. Quanto mais complexo for o formulário, pior fica a situação.

(2) Abordagem avançada ao v-model do Vue: Objetos reativos + defineModel

VUE

<!-- ✅ Correct Version: 1 reactive Object -->
<template>
  <form @submit.prevent="handleLogin">
    <input v-model="form.username">
    <input v-model="form.password" type="password">
    <input v-model="form.email" type="email">
    <input v-model="form.phone">
    <input v-model="form.captcha">
    <button>Login</button>
  </form>
</template>

<script setup>
import { reactive } from 'vue'
const form = reactive({
  username: '',
  password: '',
  email: '',
  phone: '',
  captcha: ''
})
</script>

5 campos = 1 objeto. A programação reativa reduz a quantidade de código em 50%.

(3) Receita

Após a otimização do modelo V:

Quantidade de código: 10 linhas → 5 linhas (-50%)
Novos campos: 1 linha (campos reativos adicionados)
Enviar o formulário completo: Basta enviar o objeto do formulário
Validação: Processamento centralizado

3. Como funciona o V-Model

(1) A essência do modelo V

VUE

<!-- v-model is props + emit syntax sugar -->
<input v-model="searchQuery">

<!-- equivalent to -->
<input 
  :value="searchQuery" 
  @input="searchQuery = $event.target.value"
>

(2) Modelo V em componentes

VUE

<!-- Child component:CustomInput.vue -->
<template>
  <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)">
</template>

<script setup>
defineProps(['modelValue'])
defineEmits(['update:modelValue'])
</script>

VUE

<!-- Using Parent Components v-model -->
<CustomInput v-model="searchQuery" />

<!-- equivalent to -->
<CustomInput 
  :modelValue="searchQuery" 
  @update:modelValue="searchQuery = $event"
/>

(3) defineModel (Simplificado para o Vue 3.4+)

VUE

<!-- Vue 3.4+: 1 line replaces the 10 lines above -->
<template>
  <input v-model="value">
</template>

<script setup>
const value = defineModel('modelValue')
// Now value is ref, Sure:
// - Read: value.value
// - Write: value.value = 'new' (Automatic emit)
// - watch:watch(value, ...)
// - Parent Component v-model Two-way binding works as usual
</script>

4. 5 tipos de modelo V personalizado

(1) Dados básicos

VUE

<template>
  <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)">
</template>

<script setup>
defineProps(['modelValue'])
defineEmits(['update:modelValue'])
</script>

(2) mensagens de texto

VUE

<template>
  <textarea :value="modelValue" @input="$emit('update:modelValue', $event.target.value)" />
</template>

(3) selecionar

VUE

<template>
  <select 
    :value="modelValue" 
    @change="$emit('update:modelValue', $event.target.value)"
  >
    <option value="vue">Vue</option>
    <option value="react">React</option>
  </select>
</template>

(4) Caixa de seleção (seleções múltiplas)

VUE

<template>
  <div>
    <label v-for="option in options" :key="option">
      <input 
        type="checkbox" 
        :value="option" 
        :checked="modelValue.includes(option)"
        @change="onChange($event, option)"
      >
      {{ option }}
    </label>
  </div>
</template>

<script setup>
const props = defineProps({
  modelValue: Array,
  options: Array
})
const emit = defineEmits(['update:modelValue'])

function onChange(e, option) {
  const newValue = e.target.checked
    ? [...props.modelValue, option]
    : props.modelValue.filter(v => v !== option)
  emit('update:modelValue', newValue)
}
</script>

(5) Modificador personalizado (trim)

VUE

<!-- Parent Component:v-model.trim -->
<CustomInput v-model.trim="username" />

<!-- Child component:Processing trim Modifiers -->
<script setup>
const props = defineProps({
  modelValue: String,
  modelModifiers: { default: () => ({}) }
})
const emit = defineEmits(['update:modelValue'])

function onInput(e) {
  let value = e.target.value
  if (props.modelModifiers.trim) {
    value = value.trim()
  }
  emit('update:modelValue', value)
}
</script>

5. Validação de formulários

(1) Validação personalizada

// utils/validators.js
export function isEmail(value) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
}

export function isPhone(value) {
  return /^1[3-9]\d{9}$/.test(value)
}

export function minLength(value, min) {
  return value.length >= min
}

VUE

<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="form.email" @blur="validateField('email')">
    <p v-if="errors.email" class="error">{{ errors.email }}</p>
    
    <input v-model="form.password" type="password">
    <p v-if="errors.password">{{ errors.password }}</p>
    
    <button :disabled="!isValid">Submit</button>
  </form>
</template>

<script setup>
import { reactive, ref } from 'vue'
import { isEmail, minLength } from '@/utils/validators'

const form = reactive({
  email: '',
  password: ''
})

const errors = reactive({})
const isValid = ref(false)

function validateField(field) {
  if (field === 'email') {
    if (!form.email) {
      errors.email = 'Email is required'
    } else if (!isEmail(form.email)) {
      errors.email = 'Invalid email format'
    } else {
      delete errors.email
    }
  }
  
  if (field === 'password') {
    if (!form.password) {
      errors.password = 'Password is required'
    } else if (!minLength(form.password, 8)) {
      errors.password = 'Password must be 8+ characters'
    } else {
      delete errors.password
    }
  }
  
  isValid.value = Object.keys(errors).length === 0
}

function handleSubmit() {
  Object.keys(form).forEach(validateField)
  if (isValid.value) {
    console.log('Submit:', form)
  }
}
</script>

(2) A biblioteca VeeValidate (recomendada)

BASH

npm install vee-validate @vee-validate/rules

VUE

<template>
  <Form @submit="handleSubmit" :validation-schema="schema">
    <Field name="email" type="email" v-model="form.email" />
    <ErrorMessage name="email" />
    
    <Field name="password" type="password" v-model="form.password" />
    <ErrorMessage name="password" />
    
    <button>Submit</button>
  </Form>
</template>

<script setup>
import { Form, Field, ErrorMessage } from 'vee-validate'
import * as yup from 'yup'

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().min(8).required()
})

const form = reactive({ email: '', password: '' })

function handleSubmit(values) {
  console.log('Valid:', values)
}
</script>

6. Criação de formulários complexos

(1) Formulários aninhados

const form = reactive({
  user: {
    name: '',
    email: '',
    age: 0
  },
  address: {
    city: '',
    country: ''
  }
})

VUE

<template>
  <input v-model="form.user.name" placeholder="Name">
  <input v-model="form.user.email" placeholder="Email">
  <input v-model="form.address.city" placeholder="City">
</template>

(2) Campos dinâmicos (v-for)

const form = reactive({
  items: [
    { name: '', quantity: 1, price: 0 }
  ]
})

function addItem() {
  form.items.push({ name: '', quantity: 1, price: 0 })
}

function removeItem(index) {
  form.items.splice(index, 1)
}

VUE

<template>
  <div v-for="(item, index) in form.items" :key="index">
    <input v-model="item.name" placeholder="Item name">
    <input v-model.number="item.quantity" type="number">
    <input v-model.number="item.price" type="number">
    <button @click="removeItem(index)">Remove</button>
  </div>
  <button @click="addItem">Add Item</button>
</template>

(3) Os 5 principais modificadores de forma

VUE

<!-- 1. .lazy:change Event Trigger(No input) -->
<input v-model.lazy="email">

<!-- 2. .number:Automatically Convert to Numbers -->
<input v-model.number="age" type="number">

<!-- 3. .trim:Automatically Remove Spaces -->
<input v-model.trim="username">

<!-- 4. Custom Modifiers(CustomInput) -->
<CustomInput v-model.trim="text" />

<!-- 5. .debounce(Custom):300ms Image Stabilization -->
<DebouncedInput v-model:debounce="500" />

7. Envio de arquivos

(1) Upload de um único arquivo

VUE

<template>
  <input type="file" @change="handleFile" accept="image/*">
  <img v-if="preview" :src="preview" alt="Preview">
</template>

<script setup>
import { ref } from 'vue'

const preview = ref(null)

function handleFile(event) {
  const file = event.target.files[0]
  if (file) {
    // Local Preview
    const reader = new FileReader()
    reader.onload = (e) => {
      preview.value = e.target.result
    }
    reader.readAsDataURL(file)
    
    // Upload to the server
    const formData = new FormData()
    formData.append('file', file)
    fetch('/api/upload', { method: 'POST', body: formData })
  }
}
</script>

(2) Vários arquivos + arrastar e soltar

VUE

<template>
  <div 
    @dragover.prevent
    @drop.prevent="handleDrop"
    :class="{ dragging: isDragging }"
  >
    <input type="file" multiple @change="handleFiles" accept="image/*">
    <p>Drag files here or click to upload</p>
    
    <div v-for="file in files" :key="file.name">
      <img :src="file.preview" :alt="file.name">
      <p>{{ file.name }} ({{ file.size }} bytes)</p>
    </div>
  </div>
</template>

<script setup>
import { ref, reactive } from 'vue'

const files = reactive([])
const isDragging = ref(false)

function addFile(file) {
  if (!file.type.startsWith('image/')) return
  
  const reader = new FileReader()
  reader.onload = (e) => {
    files.push({
      name: file.name,
      size: file.size,
      preview: e.target.result
    })
  }
  reader.readAsDataURL(file)
}

function handleFiles(e) {
  Array.from(e.target.files).forEach(addFile)
}

function handleDrop(e) {
  isDragging.value = false
  Array.from(e.dataTransfer.files).forEach(addFile)
}
</script>

8. Exemplos completos: 5 cenários principais de forma

▶ Exemplo: 1. 5 Princípios básicos do modelo V

VUE

<!-- 1. text input -->
<input v-model="text">

<!-- 2. textarea -->
<textarea v-model="description"></textarea>

<!-- 3. checkbox -->
<input v-model="agreed" type="checkbox">

<!-- 4. radio -->
<input v-model="gender" type="radio" value="male">
<input v-model="gender" type="radio" value="female">

<!-- 5. select -->
<select v-model="selected">
  <option value="vue">Vue</option>
  <option value="react">React</option>
</select>

▶ Experimente

▶ Exemplo: 2. 5 Tipos de v-model personalizado

VUE

<!-- Child component:CustomInput.vue -->
<template>
  <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)">
</template>

<script setup>
defineProps(['modelValue'])
defineEmits(['update:modelValue'])
</script>

<!-- Parent Component -->
<CustomInput v-model="search" />
<!-- equivalent to -->
<CustomInput :modelValue="search" @update:modelValue="search = $event" />

▶ Experimente

▶ Exemplo: 3. 5 Cenários de validação

// 1. Required
if (!form.email) errors.email = 'Required'

// 2. Email
if (!isEmail(form.email)) errors.email = 'Invalid email'

// 3. Cell Phone
if (!isPhone(form.phone)) errors.phone = 'Invalid phone'

// 4. Length
if (form.password.length < 8) errors.password = 'Too short'

// 5. Confirm Password
if (form.password !== form.confirm) errors.confirm = 'Mismatch'

▶ Experimente

▶ Exemplo: 4. 5 Principais modificadores de forma

VUE

<!-- 1. .lazy:change Event -->
<input v-model.lazy="email">

<!-- 2. .number:Automatically Convert to Numbers -->
<input v-model.number="age" type="number">

<!-- 3. .trim:Automatic trim -->
<input v-model.trim="username">

<!-- 4. Combinations of Multiple Modifiers -->
<input v-model.lazy.trim="email">

<!-- 5. Custom Modifiers(Child component)-->
<CustomInput v-model.trim="text" />

▶ Experimente

▶ Exemplo: 5. Referência rápida para 5 erros comuns

Erro	Sintoma	Solução
v-model.number ainda é uma string	Erro de adição	type="number" + .number
O v-model não é atualizado	A referência fica inativa após a mudança para reativo	Mude para .value ou toRefs
Falha no envio do arquivo usando FormData	Erro entre domínios ou de método	fetch + FormData
Momento incorreto da validação	Exibir somente quando o foco for perdido	Usar @blur
Muito código padrão de campo	código prolixo	usando objetos reativos

▶ Exemplo: 6. 5 Principais comparações de desempenho

Padrão	Simplicidade	Desempenho	Aplicabilidade
Várias referências	❌ Duplicado	⭐⭐⭐⭐	1–2 campos
Objeto reativo	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	5 ou mais campos
FormData (Manual)	❌	⭐⭐⭐	Envio de arquivos
VeeValidate	⭐⭐⭐⭐	⭐⭐⭐	Validação complexa
defineModel	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	Componente Vue 3.4+

❓ Perguntas Frequentes

P: Como se usa o v-model em componentes personalizados? R: Use defineProps(['modelValue']) + defineEmits(['update:modelValue']) dentro do componente. Use v-model no componente pai. No Vue 3.4 ou superior, use defineModel para substituir 10 linhas por apenas 1.

P: Por que o v-model.number não está funcionando? R: Ele deve ser usado com type="number". Como alternativa, use parseFloat() manualmente.

P: Devo usar validação personalizada ou o VeeValidate para validar formulários? R: Use validação personalizada para formulários simples (< 5 campos); use o VeeValidate para formulários complexos (> 5 campos + campos aninhados + validação assíncrona).

P: Como faço para enviar um arquivo e exibir uma pré-visualização? R: Use FileReader.readAsDataURL() para ler o arquivo como uma string Base64 e, em seguida, atribua-o a <img src="...">. Use FormData para o envio.

P: Qual é a diferença entre os modificadores .lazy e .debounce para o v-model? R: O .lazy é acionado pelo evento change (após perder o foco), o que reduz a sobrecarga da validação em tempo real. O .debounce é um modificador personalizado que deve ser implementado no componente filho; ele aciona o último evento dentro de 300 ms.

P: Como faço para serializar os dados do formulário em JSON para envio? R: Basta usar JSON.stringify(form) (não é necessário usar FormData, a menos que você esteja enviando arquivos). O backend pode simplesmente receber o JSON.

P: O defineModel substitui toda a sintaxe do v-model? R: Sim. defineModel('modelValue') is equivalent to the 10 lines of code in props.modelValue + emit('update:modelValue'). É totalmente compatível com versões anteriores.

📖 Resumo

v-model é uma sintaxe simplificada para props e emit; no Vue 3.4 e versões posteriores, ela é substituída por uma única linha usando defineModel.
5 tipos de v-model personalizado: input / textarea / select / checkbox / modificadores
5 modificadores: .lazy / .number / .trim / Personalizado / Vários modificadores
Validação de formulários: Personalizada (simples) / VeeValidate (complexa)
5 tipos de formulários complexos: aninhados / dinâmicos / sequenciais / de validação / de arquivo
Objetos reativos + modelo V reduzem em 50% o código repetitivo
Envio de arquivos: FileReader + FormData

📝 Exercícios

Questões básicas (Dificuldade: ⭐)

Implemente um formulário de login simples:
- 5 campos (nome de usuário / senha / e-mail / telefone / captcha)
- v-model + reativo
- Imprimir todo o objeto do formulário após o envio
Problemas avançados (Dificuldade: ⭐⭐)

Implementação da validação de formulários:
- 5 campos + validação personalizada (formato de e-mail, formato de telefone, comprimento da senha)
- @blur aciona a validação
- Mensagem de erro exibida
- O botão “Enviar” fica ativado ou desativado de acordo com a propriedade isValid
Problema desafiador (Dificuldade: ⭐⭐⭐)

Implementar um sistema completo de formulários de “Cadastro de Usuário”:
1. 10 campos (incluindo objetos address aninhados e uma matriz dinâmica tags)
2. VeeValidate + esquema do Yup
3. Envio de arquivo (foto de perfil)
4. Cobertura total de 5 modificadores
5. defineModel é usado para componentes filhos
6. 5 Situações de erro
7. Tipagem forte do TypeScript

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós

Vue.js: Formulários e v-model

1. O que você vai aprender

2. O pesadelo das “5 seções padrão” em um formulário de login

(1) Desafio: 5 campos de formulário, 10 linhas de código v-model

(2) Abordagem avançada ao v-model do Vue: Objetos reativos + defineModel

(3) Receita

3. Como funciona o V-Model

(1) A essência do modelo V

(2) Modelo V em componentes

(3) defineModel (Simplificado para o Vue 3.4+)

4. 5 tipos de modelo V personalizado

(1) Dados básicos

(2) mensagens de texto

(3) selecionar

(4) Caixa de seleção (seleções múltiplas)

(5) Modificador personalizado (trim)

5. Validação de formulários

(1) Validação personalizada

(2) A biblioteca VeeValidate (recomendada)

6. Criação de formulários complexos

(1) Formulários aninhados

(2) Campos dinâmicos (v-for)

(3) Os 5 principais modificadores de forma

7. Envio de arquivos

(1) Upload de um único arquivo

(2) Vários arquivos + arrastar e soltar

8. Exemplos completos: 5 cenários principais de forma

▶ Exemplo: 1. 5 Princípios básicos do modelo V

▶ Exemplo: 2. 5 Tipos de v-model personalizado

▶ Exemplo: 3. 5 Cenários de validação

▶ Exemplo: 4. 5 Principais modificadores de forma

▶ Exemplo: 5. Referência rápida para 5 erros comuns

▶ Exemplo: 6. 5 Principais comparações de desempenho

❓ Perguntas Frequentes

📖 Resumo

📝 Exercícios