企业官网建设流程全解析

做前端这些年，组件封装里最磨人的一件事，就是写v-model。每次封装一个输入框、弹窗、下拉选择，都得先把modelValue的 props 声明好，再把update:modelValue的 emit 写上，最后还得在事件处理函数里手动派发一次。一个两个还好，组件多了以后，这套“三件套”操作简直是复制粘贴的重灾区。

Vue 3.4 正式发布的defineModel编译器宏，就是为了解决这个痛点来的。它把一个双向绑定需要的“props 声明 + emit 声明 + 事件处理”压缩成了一行代码，让组件封装回归到“直接用v-model”的直觉写法。这篇文章我会从v-model的底层原理讲起，再一步步演示defineModel的基础用法、带参数形式、自定义修饰符，最后结合我这半年来在真实项目里踩过的坑，给出一份可以直接照抄的实战参考。无论你是刚开始接触 Vue 3 的新手，还是维护着大量业务组件库的老手，这篇都能帮你把双向绑定的封装效率提上来。

1. 为什么需要 defineModel：先弄懂 v-model 的底层逻辑

1.1 v-model 不过是语法糖

很多同学天天用v-model，但如果被问到“它到底做了什么”，可能一时半会儿说不清楚。简单来说，v-model只是一个语法糖，它把两件事合并成了一个指令。

在原生元素上，它是这样的：

<input v-model="searchText" />

等价于：

<input :value="searchText" @input="searchText = $event.target.value" />

在自定义组件上，规则略有不同。Vue 规定，组件上的v-model默认会展开为一个名为modelValue的 prop，以及一个名为update:modelValue的自定义事件：

<Child v-model="pageTitle" />

等价于：

<Child :modelValue="pageTitle" @update:modelValue="(v) => (pageTitle = v)" />

也就是说，父组件通过modelValue把值传进去，子组件修改值时通过update:modelValue事件把新值抛出来。这套机制本身很清晰，问题出在“子组件接收端”的写法上——为了完成一次双向绑定，你得做三件事。

1.2 旧写法到底有多痛

在没有defineModel之前，一个最简单的输入框组件要这样写：

<template> <input :value="modelValue" @input="handleInput" /> </template> <script setup lang="ts"> const props = defineProps<{ modelValue: string }>() const emit = defineEmits<{ (e: 'update:modelValue', value: string): void }>() function handleInput(event: Event) { const value = (event.target as HTMLInputElement).value emit('update:modelValue', value) } </script>

这段代码有四个关键部分：props 声明、emits 声明、模板里的:value绑定、事件处理函数里的emit调用。说实话，真正核心的业务逻辑只有一行，剩下的全是为了对接v-model协议而写的样板代码。

更崩溃的是多v-model的情况。比如一个弹窗组件，需要同时控制visible、title、width，那就要写三组 props、三个 emit 事件、三个处理方法。代码量直接翻倍，而且稍不留神就容易把事件名写错——update:visible和update:title这种字符串事件名，编辑器还不会给你任何提示，只有运行时点了按钮发现没反应，才会恍然大误。

1.3 defineModel 解决什么问题

defineModel的思路很直接：把一个“可写的 ref”暴露给子组件。你在子组件里给它赋值，它自动帮你触发update:modelValue事件；你读它的值，它自动帮你从modelValue这个 prop 里取值。

这样封装组件时，就可以完全忘掉 props 和 emits 那套协议，把v-model当成一个普普通通的响应式变量来用。它解决的不只是少写几行代码的问题，更重要的是降低了心智负担——写组件的时候不用再想“我现在是在处理 prop 还是在处理事件”，只需要关心“当前的值是多少，怎么改”。

2. defineModel 基础用法：三行代码封装一个输入组件

2.1 环境准备：确认 Vue 版本

defineModel在 Vue 3.4 版本中正式成为稳定 API，所以在开始之前，建议先确认项目里的 Vue 版本：

npm ls vue

如果版本低于 3.4.0，需要先升级：

npm install vue@latest

另外，如果你在 TypeScript 项目里使用vue-tsc做类型检查，注意vue-tsc也需要升级到 1.8 以上，否则对defineModel的支持会有问题。这块我在后面“避坑指南”里还会专门提到。

2.2 最简实现：一个 custom-input

先说结论：有了defineModel，子组件内部只需要三行核心代码。

先看子组件CustomInput.vue：

<template> <input v-model="model" class="custom-input" /> </template> <script setup lang="ts"> const model = defineModel<string>() </script>

父组件里正常使用：

<template> <CustomInput v-model="keyword" placeholder="输入搜索关键词" /> <p>当前输入：{{ keyword }}</p> </template> <script setup lang="ts"> import { ref } from 'vue' import CustomInput from './CustomInput.vue' const keyword = ref('') </script>

跑起来你会发现，子组件内部文本框的输入会实时同步到父组件的keyword上，父组件修改keyword，子组件输入框也跟着变。整个链路完全打通，但子组件里没有任何 props 和 emit 的痕迹。

这里要特别说明两个使用细节：

1. defineModel()返回的是一个 ref 对象。在<template>里，ref 会自动解包，所以直接写v-model="model"就行；在<script>里操作，则需要写model.value。

2. 这个 ref 是“可写”的。把它赋值给原生输入框的v-model，输入框的input事件会自动触发update:modelValue事件，把新值同步回父组件。你不需要手动去监听任何事件。

2.3 带参数形式：v-model:title 与 defineModel('title')

单一的v-model只能绑定一个值，但真实业务里经常需要绑定多个。比如一个弹窗，既要有“是否打开”的状态，又要有“弹窗标题”，还可能要自定义宽度。

父组件里这样绑定：

<BaseDialog v-model:visible="dialogVisible" v-model:title="dialogTitle" />

子组件里用字符串参数来区分：

<script setup lang="ts"> const visible = defineModel<boolean>('visible', { default: false }) const title = defineModel<string>('title', { default: '' }) </script> <template> <div v-if="visible" class="dialog-mask"> <div class="dialog-panel"> <h3>{{ title }}</h3> <button @click="close">关闭</button> </div> </div> </template>

在子组件里控制关闭弹窗，只需要直接给visible赋值：

<script setup lang="ts"> function close() { visible.value = false } </script>

这比我以前写的方式真的省太多了。以前需要三个 props 加上三个 emits，事件名像update:visible、update:title，名称一长就特别容易写错。现在只剩三行defineModel，IDE 还能正确识别出类型，写起来非常顺畅。

2.4 约束类型和默认值

defineModel和defineProps一样，支持类型约束、默认值和required：

<script setup lang="ts"> // 基础类型 + 默认值 const count = defineModel<number>('count', { default: 0, }) // 引用类型，注意 default 必须用工厂函数 const config = defineModel<{ visible: boolean }>('config', { default: () => ({ visible: true }), }) // 必填项，父组件必须传 const name = defineModel<string>('name', { required: true, }) </script>

这里有一个很关键的点：引用类型（对象、数组）的default不能直接写成一个对象，必须写成一个返回对象的函数。这个规则和defineProps完全一致，目的是避免多个组件实例共享同一个对象引用，导致一个实例改了值，其他实例也跟着变。默认值的触发条件是父组件没有传对应的 prop，或者传了undefined；如果父组件明确传了null，则会保留null而不使用默认值。

3. 进阶玩法：多个 v-model、修饰符与业务拦截

3.1 多个 v-model 的场景

在实际项目中，多个v-model最常见的场景就是弹窗和抽屉这类复合组件。我最近重构项目里的一个筛选面板，就同时用了三个 v-model：

<FilterPanel v-model:keyword="keyword" v-model:categoryId="categoryId" v-model:pageSize="pageSize" />

子组件内部的实现思路非常统一：

<script setup lang="ts"> const keyword = defineModel<string>('keyword', { default: '' }) const categoryId = defineModel<number | null>('categoryId', { default: null }) const pageSize = defineModel<number>('pageSize', { default: 20 }) </script>

页面里筛选条件一多，传统写法会让组件接口变得异常臃肿，而defineModel让每个可控状态都变成了一个独立、清晰、带类型的绑定项。在父组件看来，它就是一个“可以双向设置属性”的组件，语义特别直观。

3.2 自定义修饰符 capitalize 的实现

v-model支持修饰符这件事，很多同学可能知道v-model.trim、v-model.number，但自定义修饰符在组件里的实现以前相当绕。defineModel把这套逻辑也简化了。

比如我想实现一个capitalize修饰符，让输入的内容自动首字母大写：

父组件：

<MyInput v-model.capitalize="name" />

子组件：

<script setup lang="ts"> const [model, modifiers] = defineModel<string>({ set(value) { if (modifiers.capitalize) { return value.charAt(0).toUpperCase() + value.slice(1) } return value } }) </script> <template> <input v-model="model" /> </template>

defineModel支持解构出两个值：第一个是那个可写的 ref，第二个是修饰符集合对象。在上面的例子里，capitalize这样没有参数修饰符，在modifiers对象里对应的值是布尔true。

需要特别注意set函数的返回值：set的返回值会作为最终同步给父组件的值，同时也会更新子组件内部 ref 的值。如果set里没有返回值，就相当于是undefined，很容易把父组件的值改坏。所以写自定义set时，一定要确保所有分支都有明确的返回值。

3.3 在 setter 里做业务拦截

自定义set函数除了实现修饰符，还有一个很实用的用途：在数据流向上做格式化、清洗、校验，而不是等到父组件拿到值之后再处理。

比如封装一个手机号输入框，要求只能输入数字，并且最多 11 位：

<script setup lang="ts"> const model = defineModel<string>({ default: '', set(value) { return value.replace(/\D/g, '').slice(0, 11) } }) </script> <template> <input v-model="model" /> </template>

再比如封装一个金额输入框，想把用户输入的非法字符全部过滤掉：

<script setup lang="ts"> const amount = defineModel<string>({ default: '', set(value) { // 只允许数字和一个小数点 return value.replace(/[^0-9.]/g, '').replace(/^\./, '') } }) </script>

这种写法的好处是：数据校验和格式化逻辑收敛在了组件内部，父组件拿到的永远是干净、合法的数据，不用在业务代码里到处补丁式地处理脏数据。父组件用起来和普通v-model完全无感，这非常符合组件封装“高内聚、低耦合”的原则。

3.4 与 TypeScript 结合的类型推导

defineModel本身是一个泛型函数，类型标注起来非常顺手：

<script setup lang="ts"> // 基础类型 const keyword = defineModel<string>() // 联合类型 const status = defineModel<'idle' | 'loading' | 'success'>('status', { default: 'idle', }) // 对象类型 const user = defineModel<{ id: number; name: string }>('user') </script>

这样父组件在使用v-model时，IDE 就能通过 vue-tsc 推导出完整类型，赋值时也会给出错误提示，比传统写法里的defineEmits那一长串函数重载签名要直观得多。

有一点需要留个心眼：如果某个 prop 是可选的非必填项，且没有默认值，它的实际类型应该包含undefined，所以我更推荐的做法是显式写成类似defineModel<string | undefined>()，或者干脆配合default使用，让类型更干净。

4. 避坑指南与问题排查

4.1 与 defineProps / defineEmits 重复声明的坑

defineModel在编译阶段会自动生成对应的 props 和 emits 声明。如果你画蛇添足，又在同一个组件里手动声明了modelValue的 props 或update:modelValue的 emit，编译器就会报出警告，轻则提示重复声明，重则直接抛错。

我自己第一次用的时候就不小心踩过这个坑，代码如下：

<script setup lang="ts"> // 错误示例：不要这样写 const model = defineModel<string>() const props = defineProps<{ modelValue: string }>() const emit = defineEmits<{ (e: 'update:modelValue', value: string): void }>() </script>

正确的姿势是用了defineModel，就不要再关心底层那套 props 和 emits。如果想约束类型和默认值，直接在defineModel的参数里配置，效果完全等价。

4.2 编译器宏的位置限制

defineModel和defineProps、defineEmits、defineExpose一样，都是编译器宏。所谓“宏”，意味着它是在代码编译阶段被静态替换的，所以它只能在<script setup>的顶层调用，不能放在条件分支、循环、函数体或者其他任何运行时位置。

下面的写法会直接报错：

<script setup lang="ts"> if (someCondition) { // 错误示例：不能在条件分支里调用 const model = defineModel<string>() } </script>

还有一点，defineModel必须只能在<script setup>中使用，传统的 Options API 写法是无法使用这个宏的。

4.3 直接改 ref 与 emit 的差异，以及 watch 触发时机

刚接触defineModel时，总有人担心：直接在子组件里给model.value赋值，会不会绕过父组件的逻辑，导致“数据不一致”？

其实不用焦虑。model.value = newVal编译后会等价地触发emit('update:modelValue', newVal)，父组件收到事件后更新父组件的数据，再流回子组件的 props。这条数据链是完整的，不存在绕过的问题。

但有一个体验细节需要注意：model.value = newVal之后，由于数据要从“子组件 → 父组件 → 子组件”走一个来回，如果你在子组件里用watch监听这个值的变化，它确实会触发回调，但触发时机是在 Vue 的更新流程当中。如果你在同一个事件处理函数里连续赋值两次，可能会只触发一次更新，这是 Vue 批量更新机制的正常表现，不算是 bug。

如果你真的需要“本地化”处理某个值，比较推荐的方式是包一层 computed：

<script setup lang="ts"> const model = defineModel<string>() const displayModel = computed({ get: () => model.value.trim(), set: (val) => (model.value = val), }) </script>

但说实话，这种“读的时候格式化、写的时候原样传”的模式，在业务里用多了反而容易造成展示值和实际值不一致的困惑。一般情况下，我更推荐用 setter 拦截，而不是 computed 包一层。

4.4 常见问题速查表

4.5 旧组件迁移到 defineModel 的完整对照

如果你手头有大量旧版封装组件，迁移逻辑其实是非常机械的。我总结了一个五步流程，照着做就行。

第一步，删掉defineProps中关于modelValue的部分。第二步，删掉defineEmits中关于update:modelValue的部分。第三步，添加一行const model = defineModel<类型>()，如果需要默认值就写在参数里。第四步，模板里所有原本绑定modelValue的位置，改成直接绑定model。第五步，脚本里所有emit('update:modelValue', newVal)的调用，替换为model.value = newVal。

举个完整例子，旧代码：

<template> <input :value="modelValue" @input="handleInput" /> </template> <script setup lang="ts"> const props = defineProps<{ modelValue: string }>() const emit = defineEmits<(e: 'update:modelValue', value: string) => void>() function handleInput(event: Event) { emit('update:modelValue', (event.target as HTMLInputElement).value) } </script>

迁移后：

<template> <input v-model="model" /> </template> <script setup lang="ts"> const model = defineModel<string>() </script>

代码量减少了一半以上，而且几乎不存在手写错事件名的风险。

5. 实战：封装一个可复用的手机号输入框

5.1 需求分析与组件设计

光说不练没意义，我拿一个最近在后台管理系统里真实做过的例子来收尾：封装一个手机号输入框。

需求是这样的：用户只能输入数字；自动过滤掉空格、横线等非法字符；最多 11 位；最后绑定到表单模型里。这套需求以前直接在页面里写，每个用到的地方都来一遍过滤逻辑，非常零散。现在封装成组件，所有逻辑收敛一处，各页面只需一行v-model。

组件实现：

<template> <input :value="model" @input="handleInput" v-bind="$attrs" class="phone-input" /> </template> <script setup lang="ts"> const model = defineModel<string>({ default: '', set(value) { return value.replace(/\D/g, '').slice(0, 11) } }) function handleInput(event: Event) { const raw = (event.target as HTMLInputElement).value model.value = raw } </script>

等等，细看这段代码，可能有人会问：既然已经写了set拦截，为什么handleInput里还要再写一次赋值？

这里算是一个小小的经验补充：set拦截是“值进入组件之后”的最终过滤网，而handleInput里的赋值是触发更新的源头。实际上，因为有set的存在，@input="model.value = $event.target.value"已经足够，我就不需要再额外写一个handleInput函数了。所以这个组件还可以更精简：

<template> <input v-model="model" v-bind="$attrs" class="phone-input" /> </template> <script setup lang="ts"> const model = defineModel<string>({ default: '', set(value) { return value.replace(/\D/g, '').slice(0, 11) } }) </script>

父组件使用：

<template> <PhoneInput v-model="phone" placeholder="请输入手机号" /> <p>表单值：{{ phone }}</p> </template> <script setup lang="ts"> import { ref } from 'vue' import PhoneInput from './PhoneInput.vue' const phone = ref('') </script>

用户输入138-1234-5678时，最终同步到phone的值会是13812345678，完全符合预期。如果按传统方式，过滤逻辑只能一边写在@input里，一边在外面再补一次格式化，很容易出现“页面显示了 A，表单值是 B”的尴尬。

5.2 在真实项目中适合用 defineModel 的场景

基于我这半年在多个项目里的实践，defineModel最适合的场景有这么几类：

一是二次封装 UI 组件库。不管你是封装 Element Plus 还是 Ant Design Vue 的组件，只要涉及值和值变更的透传，defineModel都能把那一大堆 props 和 events 的透传逻辑大幅压缩。

二是弹窗、抽屉这类可见性组件。v-model:visible几乎成了中后台项目的标配，用defineModel写起来非常自然。

三是分页、搜索条件这种“多个受控值协同”的组件。多个v-model替代一长串 props 和事件，接口签名更简洁，调用方读起来也更轻松。

四是在封装的业务组件里做数据校验和格式化。如 5.1 里的手机号输入框，把非法输入挡在组件内部，不让脏数据流到业务层。

但也别什么场景都往defineModel上套。如果数据需要跨多级组件传递（比如爷爷传给孙子），那仍然应该优先考虑provide/inject或者全局状态管理，硬生生每一层都写v-model只会让链路变得冗余难维护。另外，如果你只是想在某个时机通知父组件一下（比如组件挂载完成、按钮点击），那不叫双向绑定，直接用emit才是正确的做法。

5.3 用 defineModel 时的个人使用习惯

最后分享几个我个人的编码习惯，不一定适合所有人，但至少帮我少踩了很多坑。

第一，只要组件对外暴露“可写的受控值”，一律优先用defineModel，而不是手动写 props + emit。因为它让组件接口更收敛，也避免了手写事件名的低级错误。

第二，defineModel的参数尽量写全。类型、默认值都显式写上，一方面 IDE 推导更准确，另一方面后续同事接手时也能一眼看出这个值是什么类型、缺省时是什么表现。

第三，set里做格式化拦截时，有一个原则叫“宁严勿松”。手机号、金额、纯数字这类强规则输入，直接在set里过滤掉非法字符，父组件收到的值永远是干净的。但如果过滤逻辑会影响用户输入体验（比如输入一个带小数点的数字，你不想每次输入小数点都被吞掉），那就要仔细权衡，必要时还是改用@blur时格式化才合理。

第四，defineModel返回的 ref 在模板里直接用，在脚本里记得带.value。这个虽然听起来很基础，但确实是我实际见过最多的低级报错。

用了defineModel一段时间后，我再回去看旧代码里那些动辄十几个 props、七八个事件封装的组件，是真的有点看不下去。Vue 3.4 这个版本最大的幸福感，不在于某个炫酷的新特性，而在于像defineModel这样把日常开发里最琐碎的痛点在语法层面解决掉。如果你还没升级，趁着下一个需求迭代，把项目里最常用的那几个输入组件改成defineModel试试，我相信你会和我一样，再也回不去了。