Vue 3 defineModel 完全指南

Vue 3 defineModel 完全指南

目录

1. 概述
2. 基础概念
3. 基本用法
4. 高级特性
5. [TypeScript 支持](#TypeScript 支持 "#typescript-%E6%94%AF%E6%8C%81")
6. 实战案例
7. 最佳实践
8. 常见问题
9. 与传统方式的对比
10. 总结

---

概述

defineModel 是 Vue 3.3 引入、3.4 稳定的一个编译器宏，用于简化组件的双向数据绑定实现。它让开发者能够更轻松地创建支持 v-model 的组件，减少了样板代码，提高了开发效率。

为什么需要 defineModel？

在 Vue 3.3 之前，实现一个支持 v-model 的组件需要：

// 传统方式 - 需要定义 props 和 emits
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])

const value = computed({
  get: () => props.modelValue,
  set: (value) => emit('update:modelValue', value)
})

而使用 defineModel 后：

// defineModel 方式 - 简洁明了
const modelValue = defineModel()

主要优势

• 简化代码：减少重复的样板代码
• 类型安全：更好的 TypeScript 支持
• 修饰符支持 ：内置对 v-model 修饰符的支持
• 性能优化：编译时优化，运行时开销更小

---

基础概念

什么是编译器宏？

defineModel 是一个编译器宏，这意味着它会在构建阶段被 Vue 编译器处理，转换为相应的运行时代码。编译器宏只在 <script setup> 中使用，不需要导入。

双向数据绑定原理

Vue 的 v-model 本质上是语法糖：

<!-- 父组件使用 -->
<ChildComponent v-model="count" />

<!-- 等价于 -->
<ChildComponent
  :model-value="count"
  @update:model-value="newValue => count = newValue"
/>

defineModel 自动处理这种 prop 和 emit 的配对关系。

---

基本用法

1. 简单的模型绑定

<!-- ChildComponent.vue -->
<script setup>
const modelValue = defineModel()
</script>

<template>
  <input
    v-model="modelValue"
    placeholder="输入内容..."
  />
</template>

<!-- ParentComponent.vue -->
<script setup>
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const message = ref('Hello World')
</script>

<template>
  <ChildComponent v-model="message" />
  <p>当前值: {{ message }}</p>
</template>

2. 命名模型

<!-- 自定义模型名称 -->
<script setup>
// 声明名为 'title' 的模型
const title = defineModel('title')

// 声明名为 'count' 的模型
const count = defineModel('count')
</script>

<template>
  <input v-model="title" placeholder="标题" />
  <input v-model="count" type="number" placeholder="数量" />
</template>

<!-- 父组件中使用 -->
<script setup>
import { ref } from 'vue'
import CustomModelComponent from './CustomModelComponent.vue'

const postTitle = ref('')
const postCount = ref(1)
</script>

<template>
  <CustomModelComponent
    v-model:title="postTitle"
    v-model:count="postCount"
  />
  <p>标题: {{ postTitle }}</p>
  <p>数量: {{ postCount }}</p>
</template>

3. 设置默认值和类型

<script setup>
// 带类型和默认值的模型
const name = defineModel({
  type: String,
  default: '匿名用户'
})

const age = defineModel({
  type: Number,
  default: 0
})

const isActive = defineModel({
  type: Boolean,
  default: false
})
</script>

<template>
  <div>
    <label>姓名: <input v-model="name" /></label>
    <label>年龄: <input v-model="age" type="number" /></label>
    <label>
      <input v-model="isActive" type="checkbox" />
      激活状态
    </label>
  </div>
</template>

---

高级特性

1. 模型修饰符

defineModel 内置对 v-model 修饰符的支持：

<!-- TextInput.vue -->
<script setup>
// 获取模型值和修饰符对象
const [modelValue, modelModifiers] = defineModel()

// 监听修饰符
watch(modelModifiers, (newModifiers) => {
  console.log('当前修饰符:', newModifiers)
})

// 使用修饰符处理数据
const processedValue = computed({
  get: () => modelValue.value,
  set: (value) => {
    if (modelModifiers.trim) {
      value = value.trim()
    }
    if (modelModifiers.upper) {
      value = value.toUpperCase()
    }
    modelValue.value = value
  }
})
</script>

<template>
  <input v-model="processedValue" />
  <p>修饰符: {{ JSON.stringify(modelModifiers) }}</p>
</template>

<!-- 使用修饰符 -->
<script setup>
import TextInput from './TextInput.vue'
const text = ref('')
</script>

<template>
  <TextInput v-model.trim.upper="text" />
  <p>处理后的值: {{ text }}</p>
</template>

2. 自定义修饰符

<!-- NumberInput.vue -->
<script setup>
const [modelValue, modelModifiers] = defineModel({
  // 自定义 getter/setter
  get(value) {
    // 处理自定义修饰符
    if (modelModifiers.currency) {
      return new Intl.NumberFormat('zh-CN', {
        style: 'currency',
        currency: 'CNY'
      }).format(value)
    }
    if (modelModifiers.percentage) {
      return `${value}%`
    }
    return value
  },
  set(value) {
    // 清理格式化后的值
    if (modelModifiers.currency) {
      return parseFloat(value.replace(/[¥,]/g, ''))
    }
    if (modelModifiers.percentage) {
      return parseFloat(value.replace('%', ''))
    }
    return parseFloat(value) || 0
  }
})
</script>

<template>
  <input v-model="modelValue" />
</template>

3. 复杂对象模型

<!-- UserProfile.vue -->
<script setup>
// 复杂对象的模型绑定
const user = defineModel({
  type: Object,
  default: () => ({
    name: '',
    email: '',
    age: 0,
    avatar: ''
  })
})

// 计算属性验证
const isFormValid = computed(() => {
  return user.value.name &&
         user.value.email &&
         user.value.email.includes('@') &&
         user.value.age > 0
})

// 方法
const resetForm = () => {
  user.value = {
    name: '',
    email: '',
    age: 0,
    avatar: ''
  }
}
</script>

<template>
  <div class="user-profile">
    <div class="form-group">
      <label>姓名:</label>
      <input v-model="user.name" />
    </div>

    <div class="form-group">
      <label>邮箱:</label>
      <input v-model="user.email" type="email" />
    </div>

    <div class="form-group">
      <label>年龄:</label>
      <input v-model="user.age" type="number" />
    </div>

    <div class="form-group">
      <label>头像URL:</label>
      <input v-model="user.avatar" />
    </div>

    <button @click="resetForm">重置</button>
    <p v-if="!isFormValid" class="error">
      请填写完整的用户信息
    </p>
  </div>
</template>

<style scoped>
.user-profile {
  max-width: 400px;
  margin: 0 auto;
}

.form-group {
  margin-bottom: 1rem;
}

.form-group label {
  display: block;
  margin-bottom: 0.5rem;
}

.form-group input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ddd;
  border-radius: 4px;
}

.error {
  color: red;
}
</style>

---

TypeScript 支持

1. 基本类型注解

<script setup lang="ts">
// 基本类型注解
const text = defineModel<string>()
const number = defineModel<number>()
const boolean = defineModel<boolean>()

// 数组类型
const items = defineModel<string[]>({ default: () => [] })

// 对象类型
interface User {
  id: number
  name: string
  email: string
}

const user = defineModel<User>({
  type: Object as PropType<User>,
  required: true
})
</script>

2. 复杂类型定义

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

interface FormField {
  id: string
  label: string
  type: 'text' | 'email' | 'number' | 'textarea'
  value: string | number
  required?: boolean
  placeholder?: string
  validation?: {
    min?: number
    max?: number
    pattern?: string
  }
}

const formFields = defineModel<FormField[]>({
  type: Array as PropType<FormField[]>,
  default: () => [],
  // 自定义验证函数
  validator: (value: FormField[]) => {
    return Array.isArray(value) &&
           value.every(field => field.id && field.label && field.type)
  }
})

// 获取修饰符的类型
const [modelValue, modelModifiers] = defineModel<string, {
  trim?: boolean
  uppercase?: boolean
  required?: boolean
}>()

// 类型安全的方法
const updateField = (index: number, value: string) => {
  if (formFields.value[index]) {
    formFields.value[index].value = value
  }
}
</script>

3. 泛型组件

<script setup lang="ts">
// 泛型模型组件
interface GenericModelProps<T> {
  value: T
  options?: T[]
}

// 使用泛型
const modelValue = defineModel<T>({
  type: [String, Number, Object, Array] as PropType<T>,
  required: true
})

// 类型推断
type ModelType = typeof modelValue extends { value: infer T } ? T : never
</script>

---

实战案例

案例1：自定义输入组件库

<!-- BaseInput.vue -->
<script setup lang="ts">
interface Props {
  type?: 'text' | 'email' | 'password' | 'number' | 'tel'
  placeholder?: string
  disabled?: boolean
  readonly?: boolean
  maxlength?: number
  minlength?: number
}

// 支持多种修饰符
const [modelValue, modelModifiers] = defineModel<string, {
  trim?: boolean
  uppercase?: boolean
  lowercase?: boolean
  number?: boolean
}>()

const props = withDefaults(defineProps<Props>(), {
  type: 'text',
  placeholder: '',
  disabled: false,
  readonly: false
})

const emit = defineEmits<{
  focus: [event: FocusEvent]
  blur: [event: FocusEvent]
  input: [event: Event]
  change: [event: Event]
}>()

// 处理修饰符
const processedValue = computed({
  get: () => {
    let value = modelValue.value || ''

    if (modelModifiers.uppercase) {
      value = value.toUpperCase()
    }
    if (modelModifiers.lowercase) {
      value = value.toLowerCase()
    }

    return value
  },
  set: (value: string) => {
    if (modelModifiers.trim) {
      value = value.trim()
    }
    if (modelModifiers.number) {
      value = value.replace(/[^\d.-]/g, '')
    }
    modelValue.value = value
  }
})

// 事件处理
const handleInput = (event: Event) => {
  const target = event.target as HTMLInputElement
  processedValue.value = target.value
  emit('input', event)
}

const handleChange = (event: Event) => {
  const target = event.target as HTMLInputElement
  processedValue.value = target.value
  emit('change', event)
}
</script>

<template>
  <div class="base-input">
    <input
      :type="type"
      :value="processedValue"
      :placeholder="placeholder"
      :disabled="disabled"
      :readonly="readonly"
      :maxlength="maxlength"
      :minlength="minlength"
      @input="handleInput"
      @change="handleChange"
      @focus="$emit('focus', $event)"
      @blur="$emit('blur', $event)"
      class="input-field"
    />
  </div>
</template>

<style scoped>
.base-input {
  position: relative;
  display: inline-block;
}

.input-field {
  width: 100%;
  padding: 8px 12px;
  border: 1px solid #dcdfe6;
  border-radius: 4px;
  font-size: 14px;
  transition: border-color 0.2s;
  box-sizing: border-box;
}

.input-field:focus {
  outline: none;
  border-color: #409eff;
}

.input-field:disabled {
  background-color: #f5f7fa;
  cursor: not-allowed;
}

.input-field:readonly {
  background-color: #f5f7fa;
}
</style>

案例2：可编辑表格组件

<!-- EditableTable.vue -->
<script setup lang="ts">
interface TableColumn {
  key: string
  title: string
  width?: string
  type?: 'text' | 'number' | 'select'
  options?: Array<{ label: string; value: any }>
  required?: boolean
}

interface TableRow {
  [key: string]: any
}

interface Props {
  columns: TableColumn[]
  data: TableRow[]
  editable?: boolean
  addable?: boolean
  deletable?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  editable: true,
  addable: true,
  deletable: true
})

// 双向绑定表格数据
const tableData = defineModel<TableRow[]>('data', {
  type: Array as PropType<TableRow[]>,
  required: true
})

// 计算属性
const hasData = computed(() => tableData.value && tableData.value.length > 0)

// 方法
const addRow = () => {
  const newRow: TableRow = {}
  props.columns.forEach(col => {
    newRow[col.key] = col.type === 'number' ? 0 : ''
  })
  tableData.value = [...tableData.value, newRow]
}

const deleteRow = (index: number) => {
  tableData.value = tableData.value.filter((_, i) => i !== index)
}

const updateCell = (rowIndex: number, columnKey: string, value: any) => {
  const newData = [...tableData.value]
  newData[rowIndex][columnKey] = value
  tableData.value = newData
}

// 验证
const validateRow = (row: TableRow): boolean => {
  return props.columns.every(col => {
    if (col.required && (!row[col.key] || row[col.key] === '')) {
      return false
    }
    return true
  })
}

const validateTable = (): boolean => {
  return tableData.value.every(row => validateRow(row))
}
</script>

<template>
  <div class="editable-table">
    <table class="table">
      <thead>
        <tr>
          <th v-for="column in columns" :key="column.key" :style="{ width: column.width }">
            {{ column.title }}
            <span v-if="column.required" class="required">*</span>
          </th>
          <th v-if="deletable" class="action-column">操作</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="(row, rowIndex) in tableData" :key="rowIndex" :class="{ 'invalid-row': !validateRow(row) }">
          <td v-for="column in columns" :key="column.key">
            <template v-if="editable">
              <input
                v-if="column.type === 'text' || !column.type"
                v-model="row[column.key]"
                @input="updateCell(rowIndex, column.key, ($event.target as HTMLInputElement).value)"
                type="text"
                class="cell-input"
              />
              <input
                v-else-if="column.type === 'number'"
                v-model.number="row[column.key]"
                @input="updateCell(rowIndex, column.key, ($event.target as HTMLInputElement).value)"
                type="number"
                class="cell-input"
              />
              <select
                v-else-if="column.type === 'select'"
                v-model="row[column.key]"
                @change="updateCell(rowIndex, column.key, ($event.target as HTMLSelectElement).value)"
                class="cell-select"
              >
                <option v-for="option in column.options" :key="option.value" :value="option.value">
                  {{ option.label }}
                </option>
              </select>
            </template>
            <template v-else>
              {{ row[column.key] }}
            </template>
          </td>
          <td v-if="deletable" class="action-column">
            <button @click="deleteRow(rowIndex)" class="delete-btn">删除</button>
          </td>
        </tr>
      </tbody>
    </table>

    <div v-if="addable" class="table-actions">
      <button @click="addRow" class="add-btn">添加行</button>
    </div>

    <div v-if="!validateTable()" class="validation-error">
      请填写所有必填字段
    </div>
  </div>
</template>

<style scoped>
.editable-table {
  width: 100%;
}

.table {
  width: 100%;
  border-collapse: collapse;
  margin-bottom: 1rem;
}

.table th,
.table td {
  border: 1px solid #ebeef5;
  padding: 8px 12px;
  text-align: left;
}

.table th {
  background-color: #f5f7fa;
  font-weight: 600;
}

.required {
  color: #f56c6c;
}

.cell-input,
.cell-select {
  width: 100%;
  padding: 4px 8px;
  border: 1px solid #dcdfe6;
  border-radius: 4px;
  font-size: 14px;
}

.cell-input:focus,
.cell-select:focus {
  outline: none;
  border-color: #409eff;
}

.invalid-row {
  background-color: #fef0f0;
}

.action-column {
  width: 100px;
  text-align: center;
}

.delete-btn {
  padding: 4px 8px;
  background-color: #f56c6c;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.delete-btn:hover {
  background-color: #f78989;
}

.table-actions {
  margin-bottom: 1rem;
}

.add-btn {
  padding: 8px 16px;
  background-color: #409eff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.add-btn:hover {
  background-color: #66b1ff;
}

.validation-error {
  color: #f56c6c;
  font-size: 14px;
  margin-top: 8px;
}
</style>

案例3：搜索筛选组件

<!-- SearchFilter.vue -->
<script setup lang="ts">
interface FilterOption {
  label: string
  value: any
  type?: 'text' | 'select' | 'date' | 'number'
  options?: Array<{ label: string; value: any }>
}

interface SearchFilterProps {
  filters: FilterOption[]
  placeholder?: string
  debounceTime?: number
}

const props = withDefaults(defineProps<SearchFilterProps>(), {
  placeholder: '搜索...',
  debounceTime: 300
})

// 搜索关键词模型
const searchKeyword = defineModel<string>('keyword', {
  default: ''
})

// 筛选条件模型
const filterValues = defineModel<Record<string, any>>('filters', {
  default: () => ({})
})

// 搜索状态
const isSearching = ref(false)

// 防抖搜索
const debouncedSearch = useDebounceFn(() => {
  isSearching.value = true
  setTimeout(() => {
    isSearching.value = false
  }, 500)
}, props.debounceTime)

// 监听搜索关键词变化
watch(searchKeyword, () => {
  debouncedSearch()
})

// 监听筛选条件变化
watch(filterValues, () => {
  debouncedSearch()
}, { deep: true })

// 重置搜索
const resetFilters = () => {
  searchKeyword.value = ''
  Object.keys(filterValues.value).forEach(key => {
    filterValues.value[key] = ''
  })
}

// 活跃筛选数量
const activeFilterCount = computed(() => {
  return Object.values(filterValues.value).filter(value =>
    value !== '' && value !== null && value !== undefined
  ).length + (searchKeyword.value ? 1 : 0)
})
</script>

<template>
  <div class="search-filter">
    <!-- 搜索输入框 -->
    <div class="search-input-wrapper">
      <div class="search-icon">
        <svg viewBox="0 0 24 24" width="16" height="16">
          <path fill="currentColor" d="M15.5 14h-.79l-.28-.27A6.471 6.471 0 0 0 16 9.5 6.5 6.5 0 1 0 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/>
        </svg>
      </div>
      <input
        v-model="searchKeyword"
        type="text"
        :placeholder="placeholder"
        class="search-input"
      />
      <div v-if="searchKeyword" class="clear-icon" @click="searchKeyword = ''">
        <svg viewBox="0 0 24 24" width="16" height="16">
          <path fill="currentColor" d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/>
        </svg>
      </div>
    </div>

    <!-- 筛选条件 -->
    <div v-if="filters.length > 0" class="filters-wrapper">
      <div v-for="filter in filters" :key="filter.label" class="filter-item">
        <label class="filter-label">{{ filter.label }}:</label>

        <template v-if="filter.type === 'select'">
          <select v-model="filterValues[filter.label]" class="filter-select">
            <option value="">全部</option>
            <option
              v-for="option in filter.options"
              :key="option.value"
              :value="option.value"
            >
              {{ option.label }}
            </option>
          </select>
        </template>

        <template v-else-if="filter.type === 'date'">
          <input
            v-model="filterValues[filter.label]"
            type="date"
            class="filter-input"
          />
        </template>

        <template v-else-if="filter.type === 'number'">
          <input
            v-model.number="filterValues[filter.label]"
            type="number"
            class="filter-input"
          />
        </template>

        <template v-else>
          <input
            v-model="filterValues[filter.label]"
            type="text"
            :placeholder="filter.label"
            class="filter-input"
          />
        </template>
      </div>
    </div>

    <!-- 操作按钮 -->
    <div class="filter-actions">
      <div v-if="activeFilterCount > 0" class="active-filters">
        已选择 {{ activeFilterCount }} 个筛选条件
      </div>
      <button
        v-if="searchKeyword || activeFilterCount > 0"
        @click="resetFilters"
        class="reset-btn"
      >
        重置
      </button>
    </div>

    <!-- 搜索状态指示器 -->
    <div v-if="isSearching" class="searching-indicator">
      搜索中...
    </div>
  </div>
</template>

<style scoped>
.search-filter {
  background-color: #f8f9fa;
  padding: 16px;
  border-radius: 8px;
  margin-bottom: 16px;
}

.search-input-wrapper {
  position: relative;
  margin-bottom: 12px;
}

.search-icon,
.clear-icon {
  position: absolute;
  top: 50%;
  transform: translateY(-50%);
  color: #6c757d;
}

.search-icon {
  left: 12px;
}

.clear-icon {
  right: 12px;
  cursor: pointer;
}

.clear-icon:hover {
  color: #495057;
}

.search-input {
  width: 100%;
  padding: 8px 40px;
  border: 1px solid #ced4da;
  border-radius: 4px;
  font-size: 14px;
}

.search-input:focus {
  outline: none;
  border-color: #007bff;
  box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
}

.filters-wrapper {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 12px;
  margin-bottom: 12px;
}

.filter-item {
  display: flex;
  flex-direction: column;
}

.filter-label {
  font-size: 12px;
  color: #6c757d;
  margin-bottom: 4px;
}

.filter-input,
.filter-select {
  padding: 6px 8px;
  border: 1px solid #ced4da;
  border-radius: 4px;
  font-size: 14px;
}

.filter-input:focus,
.filter-select:focus {
  outline: none;
  border-color: #007bff;
  box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
}

.filter-actions {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.active-filters {
  font-size: 12px;
  color: #007bff;
}

.reset-btn {
  padding: 6px 12px;
  background-color: #6c757d;
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 12px;
  cursor: pointer;
}

.reset-btn:hover {
  background-color: #5a6268;
}

.searching-indicator {
  margin-top: 8px;
  font-size: 12px;
  color: #007bff;
  text-align: center;
}
</style>

---

最佳实践

1. 组件设计原则

<!-- ✅ 好的实践：单一职责 -->
<script setup>
// 每个组件只负责一个主要功能
const value = defineModel<string>()

// 简单的数据处理逻辑
const processedValue = computed({
  get: () => value.value?.trim() || '',
  set: (val) => value.value = val.trim()
})
</script>

<!-- ❌ 避免的实践：过度复杂 -->
<script setup>
// 避免在同一个组件中定义太多模型
const model1 = defineModel('model1')
const model2 = defineModel('model2')
const model3 = defineModel('model3')
// ... 太多模型会导致组件难以维护
</script>

2. 类型安全

<!-- ✅ 推荐的做法：完整的类型定义 -->
<script setup lang="ts">
interface UserForm {
  name: string
  email: string
  age: number
  preferences: {
    theme: 'light' | 'dark'
    notifications: boolean
  }
}

const userForm = defineModel<UserForm>({
  type: Object as PropType<UserForm>,
  required: true,
  validator: (value: UserForm) => {
    return value.name &&
           value.email.includes('@') &&
           value.age > 0
  }
})
</script>

<!-- ❌ 不推荐的做法：缺少类型约束 -->
<script setup>
// 缺少类型定义，容易出现运行时错误
const data = defineModel() // 类型为 unknown
</script>

3. 默认值处理

<!-- ✅ 推荐的做法：合理的默认值 -->
<script setup>
// 对于复杂对象，使用函数返回默认值
const user = defineModel({
  type: Object,
  default: () => ({
    name: '',
    email: '',
    age: 0
  })
})

// 对于数组，使用空数组作为默认值
const items = defineModel({
  type: Array,
  default: () => []
})
</script>

<!-- ❌ 避免的做法：可变引用的默认值 -->
<script setup>
// 可能导致多个组件实例共享同一个对象引用
const user = defineModel({
  type: Object,
  default: { name: '', email: '' } // ❌ 错误：共享引用
})
</script>

4. 验证和错误处理

<script setup>
const email = defineModel<string>({
  type: String,
  required: true,
  validator: (value: string) => {
    // 自定义验证逻辑
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    return emailRegex.test(value)
  }
})

// 错误状态管理
const errorMessage = computed(() => {
  if (email.value && !validator(email.value)) {
    return '请输入有效的邮箱地址'
  }
  return ''
})

// 实时验证
const isValid = computed(() => {
  return !errorMessage.value
})
</script>

<template>
  <div class="form-group">
    <label>邮箱:</label>
    <input v-model="email" type="email" />
    <div v-if="errorMessage" class="error-message">
      {{ errorMessage }}
    </div>
  </div>
</template>

5. 性能优化

<script setup>
// ✅ 使用计算属性进行复杂的数据处理
const [modelValue, modelModifiers] = defineModel<string>()

const processedValue = computed({
  get: () => {
    let value = modelValue.value || ''

    // 复杂的格式化逻辑
    if (modelModifiers.currency) {
      value = Number(value).toLocaleString('zh-CN', {
        style: 'currency',
        currency: 'CNY'
      })
    }

    return value
  },
  set: (value: string) => {
    // 处理用户输入
    if (modelModifiers.currency) {
      value = value.replace(/[¥,]/g, '')
    }

    modelValue.value = value
  }
})

// ❌ 避免在模板中进行复杂计算
<template>
  <!-- 不推荐：在模板中进行复杂计算 -->
  <input :value="formatCurrency(modelValue)" @input="handleInput" />

  <!-- 推荐：使用计算属性 -->
  <input v-model="processedValue" />
</template>
</script>

---

常见问题

1. 为什么 defineModel 不工作？

问题 ：组件中使用 defineModel 但没有响应式效果

原因：

• Vue 版本低于 3.3
• 没有在 <script setup> 中使用
• 父组件没有正确绑定 v-model

解决方案：

<!-- 确保使用 Vue 3.3+ -->
<script setup>
// ✅ 正确使用
const modelValue = defineModel()
</script>

<!-- 父组件正确绑定 -->
<ChildComponent v-model="data" />
<!-- 而不是 -->
<ChildComponent :model-value="data" /> <!-- ❌ 缺少双向绑定 -->

2. 如何处理默认值的同步问题？

问题：子组件设置了默认值，但父组件没有提供值时出现同步问题

解决方案：

<script setup>
// ✅ 推荐做法：使用本地状态管理默认值
const props = defineProps({
  modelValue: String
})

const emit = defineEmits(['update:modelValue'])

// 使用计算属性处理默认值
const internalValue = computed({
  get: () => props.modelValue || '默认值',
  set: (value) => emit('update:modelValue', value)
})

// 或者使用 defineModel 的 default 选项
const modelValue = defineModel({
  type: String,
  default: '默认值'
})
</script>

3. TypeScript 类型推断失败

问题 ：TypeScript 无法正确推断 defineModel 的类型

解决方案：

<script setup lang="ts">
// ✅ 显式类型注解
const text = defineModel<string>()

interface FormData {
  name: string
  email: string
}

const formData = defineModel<FormData>({
  type: Object as PropType<FormData>
})

// ✅ 使用泛型约束
const model = defineModel<T extends string | number ? T : string>({
  type: [String, Number] as PropType<T>
})
</script>

4. 修饰符不生效

问题：自定义修饰符没有按预期工作

解决方案：

<script setup>
// ✅ 正确使用修饰符
const [modelValue, modelModifiers] = defineModel({
  // 在 set 函数中处理修饰符
  set(value) {
    if (modelModifiers.trim) {
      return value.trim()
    }
    return value
  }
})
</script>

<!-- 使用时添加修饰符 -->
<ChildComponent v-model.trim="data" />

5. 如何避免无限更新循环？

问题：在 getter 和 setter 中设置值时导致无限循环

解决方案：

<script setup>
const [modelValue, modelModifiers] = defineModel()

// ✅ 避免在 getter 中修改原值
const processedValue = computed({
  get: () => {
    // 只读取，不修改
    let value = modelValue.value || ''

    if (modelModifiers.uppercase) {
      return value.toUpperCase()
    }

    return value
  },
  set: (value) => {
    // 在 setter 中进行实际修改
    let finalValue = value

    if (modelModifiers.trim) {
      finalValue = value.trim()
    }

    // 直接设置，避免触发 getter
    modelValue.value = finalValue
  }
})
</script>

---

与传统方式的对比

1. 代码量对比

<!-- ❌ 传统方式：需要大量样板代码 -->
<script setup>
const props = defineProps({
  modelValue: String,
  title: String,
  count: Number
})

const emit = defineEmits([
  'update:modelValue',
  'update:title',
  'update:count'
])

const value = computed({
  get: () => props.modelValue,
  set: (value) => emit('update:modelValue', value)
})

const titleValue = computed({
  get: () => props.title,
  set: (value) => emit('update:title', value)
})

const countValue = computed({
  get: () => props.count,
  set: (value) => emit('update:count', value)
})
</script>

<!-- ✅ defineModel 方式：简洁明了 -->
<script setup>
const modelValue = defineModel()
const title = defineModel('title')
const count = defineModel('count')
</script>

2. 修饰符支持对比

<!-- ❌ 传统方式：需要手动处理修饰符 -->
<script setup>
const props = defineProps({
  modelValue: String,
  modelModifiers: {
    type: Object,
    default: () => ({})
  }
})

const emit = defineEmits(['update:modelValue'])

const value = computed({
  get: () => props.modelValue,
  set: (value) => {
    if (props.modelModifiers.trim) {
      value = value.trim()
    }
    emit('update:modelValue', value)
  }
})
</script>

<!-- ✅ defineModel 方式：内置修饰符支持 -->
<script setup>
const [modelValue, modelModifiers] = defineModel({
  set(value) {
    if (modelModifiers.trim) {
      return value.trim()
    }
    return value
  }
})
</script>

3. TypeScript 支持对比

<!-- ❌ 传统方式：类型推断不够直观 -->
<script setup lang="ts">
interface Props {
  modelValue?: string
}

const props = defineProps<Props>()
const emit = defineEmits<{
  'update:modelValue': [value: string]
}>()

const value = computed<string>({
  get: () => props.modelValue || '',
  set: (value) => emit('update:modelValue', value)
})
</script>

<!-- ✅ defineModel 方式：类型推断更直接 -->
<script setup lang="ts">
const value = defineModel<string>({
  default: ''
})
</script>

---

总结

defineModel 是 Vue 3 生态系统中的一个重要改进，它显著简化了组件双向数据绑定的实现。通过本文档的学习，我们了解到：

核心优势

1. 简化开发：大幅减少样板代码，提高开发效率
2. 类型安全：优秀的 TypeScript 支持，减少运行时错误
3. 性能优化：编译时优化，运行时开销更小
4. 功能丰富：内置修饰符支持和复杂的配置选项

适用场景

• 表单组件：输入框、选择器、日期选择器等
• 数据展示组件：需要编辑功能的数据表格
• 配置面板：各种设置和配置界面
• 搜索筛选：复杂的搜索和筛选组件

学习建议

1. 从基础开始 ：先掌握基本的 v-model 绑定
2. 逐步深入：学习修饰符和高级配置
3. 实践项目 ：在实际项目中应用 defineModel
4. 对比学习 ：了解传统方式的差异，更好地理解 defineModel 的优势

注意事项

• 确保 Vue 版本为 3.3 或更高
• 必须在 <script setup> 中使用
• 注意默认值的处理方式
• 合理使用 TypeScript 类型约束

defineModel 代表了 Vue.js 持续改进组件开发体验的努力，掌握这一特性将帮助开发者构建更简洁、更可维护的 Vue 应用程序。