写 Vue 组件的人迟早都会跟$emit打交道。$emit是 Vue 实例上的一个内置方法专门用来在当前组件上触发自定义事件让父组件能够通过事件监听器接收到子组件发出的信号。在 Vue 的组件通信体系里它有独特的位置props 负责父传子$emit负责子传父。无论你用 Options API 还是 Composition API无论你写的是传统业务组件还是通用基础组件都绕不开它。这篇文章想拆开讲讲$emit的机制、命名规范、常见用法以及那些在官方文档里不容易看到的实操心得适合刚入门 Vue 的新人也适合写了很久组件但偶尔还会踩事件坑的同学。1. 为什么组件通信需要 $emit1.1 单向数据流的设计逻辑Vue 的数据流动有一个底层约定状态只能从父组件通过 props 流向子组件子组件不能直接修改 props。直接给 props 赋值运行时会在控制台打出警告而且一旦组件层级变深数据源就会变得混乱排查问题的时候根本分不清是哪个组件改了状态。那子组件想通知父组件“用户操作了”“数据加载完了”“某个状态需要重置”该怎么办答案就是触发一个事件。$emit不会去改动父组件的状态它只是发出一个信号由父组件决定如何响应。这个设计和 DOM 原生事件非常像按钮自己不知道页面其他地方发生了什么它只是把 click 事件抛出去监听者自己去处理后续逻辑。打个比方下级向上级汇报工作下级只负责把情况说明白拍板决定是上级的事。如果下级直接替上级改决策整个工作流就乱套了。$emit就是这个“汇报动作”它保证了数据流的单向性也让组件之间的契约变得清晰父组件通过 props 下发数据子组件通过事件上报行为两边各司其职。1.2 组件通信方案对比$emit 的定位Vue 的组件通信方式不止一种常见的还有provide/inject、事件总线Event Bus、Vuex / Pinia 状态管理。很多人一开始会纠结“该用哪个”其实它们的适用场景差异很明显。通信方式数据方向典型场景优点缺点props $emit父子双向基础组件、表单控件、业务组件显式、可追踪、类型友好层级深了会繁琐provide / inject祖先到后代跨多层传递配置、主题、服务实例穿透层级写法简洁数据流不直观响应式需额外处理Event Bus任意方向非父子组件通信使用简单无需引入状态库事件满天飞难以调试易产生内存泄漏Vuex / Pinia任意组件全局共享状态、复杂业务数据集中管理可观测、可调试样板代码多不适合简单场景$emit的核心优势是两个一是显式组件到底抛出哪些事件看emits声明就知道二是就近父子之间直接通信不需要引入额外依赖。项目里大部分组件交互其实都是父子关系所以$emit的使用频率远超其他方案。我的经验是能就近用 props/$emit解决的绝不往上引状态管理只有状态要被很多组件共享再考虑 Pinia。2. $emit 的核心机制与实操细节2.1 先声明 emits再谈触发很多老项目里能看到这种写法在 methods 里直接this.$emit(some-event, payload)组件上也没有任何声明。这种写法能用但不是一个好习惯。在 Vue 3 中官方推荐在组件上显式声明emits选项。作用有三个第一把组件对外暴露的接口列出来阅读代码的人一眼就知道这个组件能抛什么事件第二Vue 可以据此判断某个落在组件上的事件监听器是自定义事件还是原生 DOM 事件避免误绑第三支持事件参数校验和 props 校验类似可以提前暴露数据类型问题。Options API 的写法export default { emits: [search, clear], methods: { handleSearch() { this.$emit(search, { keyword: this.keyword }) } } }Composition API 配合script setup的写法更简洁script setup const emit defineEmits([search, clear]) function handleSearch() { emit(search, { keyword: vue }) } /scriptdefineEmits返回的是一个emit函数组件里所有需要上报的信号都通过它触发。注意在script setup中使用defineEmits时不需要导入它是编译器宏。我个人习惯是在每个组件文件里都给emits做声明即使当时只有一两个事件。因为组件的接口就像函数的签名后面维护的人改起来会非常感谢你。如果你写的是通用组件库还建议加上事件参数校验script setup const emit defineEmits({ search: (payload) { if (payload typeof payload.keyword string) { return true } else { console.warn(search 事件的载荷必须是包含 keyword 字段的对象) return false } } }) /script校验不通过时 Vue 会在开发环境给出警告这玩意在多人协作时特别有用。2.2 事件命名kebab-case 是最稳的选择事件命名是$emit最容易踩坑的地方。Vue 官方文档反复强调事件名和 props 不一样不会自动做大小写转换。组件上监听的事件名必须和$emit触发的事件名完全一致。官方推荐的写法是始终用 kebab-case也就是全小写加短横线。原因很简单在模板里my-event是合法写法而myEvent在 HTML 环境中会被浏览器自动转成小写myevent导致大小写不匹配。虽然 Vue 模板编译器对组件监听器做了不少兼容处理但为了跨环境稳妥kebab-case 是零风险选择。下面这个例子在实际项目中经常见到属于典型的“看着对跑起来不响”// 子组件里触发 this.$emit(myEvent)!-- 父组件里监听 -- MyComponent my-eventhandleIt /如果子组件触发的是myEvent父组件监听的是my-event在很多场景下这个事件就是静默丢失的。虽然某些 Vue 版本做了兼容处理但你不能把“兼容”当“保证”。统一策略触发和监听都用 kebab-case。// 子组件 emit(my-event) // 父组件 MyComponent my-eventhandleIt /问为什么文档不推荐 camelCase因为事件名不是 JavaScript 标识符它没必要跟变量名保持一致。kebab-case 在模板里看起来也更自然接近于原生 HTML 事件的观感。2.3 载荷参数单参数、多参数与 $event$emit的第二个及以后参数都会传给父组件的监听函数。传一个参数最常用script setup const emit defineEmits([select]) function onSelect(item) { emit(select, item) } /script父组件接收时模板里可以直接用$event拿到载荷Child selecthandleSelect /function handleSelect(item) { console.log(item) }如果需要传多个独立参数也完全支持emit(page-change, pageNum, pageSize)父组件监听函数里按位置接收function onPageChange(pageNum, pageSize) { // ... }这是一个常常被忽略的细节如果不确定后续会不会增加参数建议直接传一个对象载荷。对象的好处是字段可以随时扩充且不需要调整监听函数的参数顺序。项目里我几乎只传两种形式单个基本类型值或者一个包含完整上下文的对象。传多个散参数的情况尽量避免因为人数一多“第三个参数到底是啥”就成了新的讨论话题。另一个容易被忽视的点$event只是模板里的语法糖它代表事件监听函数收到的第一个参数。如果监听函数本身写在了模板里且需要同时访问事件载荷和组件自身的数据可以写成Child select(item) handleSelect(item, localData) /这样item是子组件传上来的载荷localData是当前组件作用域里的数据。3. 实战构建一个可复用的搜索框组件3.1 需求拆解与事件设计理论说再多不如上手写一个。我们做一个搜索框组件需求如下输入框内容与父组件状态双向同步用户输入完成后按回车触发搜索输入框有内容时显示“清空”按钮点击后清空输入并通知父组件搜索时把关键词上报父组件自行处理请求逻辑这个组件涉及三个对外事件update:modelValue用于 v-model 同步、search回车搜索、clear点击清空。事件设计的原则是组件只上报“发生了什么”不在内部做请求等副作用操作。3.2 组件编码实现创建SearchBox.vuetemplate div classsearch-box input :valuemodelValue typetext placeholder输入关键词搜索 inputonInput keyup.enteronSearch / button v-ifmodelValue classclear-btn clickonClear清空/button /div /template script setup const props defineProps({ modelValue: { type: String, default: } }) const emit defineEmits([update:modelValue, search, clear]) function onInput(e) { // 输入时同步给父组件这也是 v-model 的工作方式 emit(update:modelValue, e.target.value) } function onSearch() { // 回车时上报搜索动作具体请求由父组件完成 emit(search, props.modelValue) } function onClear() { // 两种做法先清空再通知 emit(update:modelValue, ) emit(clear) } /script这个组件的输出接口非常清晰三个事件各有各的职责父组件愿意监听哪个就监听哪个不强制父组件必须处理search或者clear。这种松耦合设计就是$emit的典型用法——子组件把“信号”发出来父组件自己决定要不要响应。有一个细节值得注意onSearch里读取的是props.modelValue而不是输入框的 DOM 值。因为:value绑定的值已经是最新的输入内容而输入框的值同步到这个 prop 有一个时间差直接读props.modelValue更可靠。3.3 父组件接入与事件接收父组件使用SearchBox时v-model 负责双向绑定其他事件按需处理template div SearchBox v-modelkeyword searchfetchSearch clearhandleClear / p当前关键词{{ keyword }}/p /div /template script setup import { ref } from vue import SearchBox from ./SearchBox.vue const keyword ref() const results ref([]) async function fetchSearch(keyword) { if (!keyword.trim()) return // 这里才真正发起请求 const { data } await api.search(keyword) results.value data } function handleClear() { // 可以在这里做统计、重置列表等操作 results.value [] } /script注意searchfetchSearch这里子组件search事件的载荷直接作为第一个参数传给了fetchSearch也就是关键词字符串。如果你在处理函数里不需要这个参数比如handleClear那就直接不写参数。实际项目里我还会给这个搜索框加一个防抖输入时不立即同步而是由父组件决定是否延迟处理。防抖逻辑放在子组件还是父组件取决于你的场景。如果只是做搜索联想放在父组件处理update:modelValue时做防抖更合适如果每个输入框都有这个需求封装进子组件更划算。不过要注意子组件内部做了防抖会影响 v-model 的即时性这个取舍要结合业务来看。4. 进阶用 $emit 打通 v-model4.1 update:modelValue 约定v-model 是 Vue 的双向绑定语法糖剥开看它的底层就是$emit。Vue 3 中在组件上使用v-modelkeyword等价于SearchBox :modelValuekeyword update:modelValuekeyword $event /所以子组件里实现 v-model 的核心就是接收modelValue这个 prop并在变化时触发update:modelValue事件。第三节的SearchBox就是这么实现的没有依赖任何魔法。Vue 2 的用户可能会奇怪当年不是流行.sync修饰符吗其实 Vue 2 的.sync就是update:propName事件的语法糖Vue 3 干脆把.sync能力并进了 v-model多个 v-model 的写法也更自然。在 Vue 3 中你甚至还能给 v-model 起名字。4.2 多个 v-model 绑定一个组件需要同步多个值时不用再写一个对象然后到处解构Vue 3 支持多个 v-modelUserForm v-model:namename v-model:ageage v-model:emailemail /对应的子组件实现script setup const props defineProps({ name: String, age: Number, email: String }) const emit defineEmits([update:name, update:age, update:email]) function updateName(e) { emit(update:name, e.target.value) } // age、email 同理 /script这里每个update:xxx都是一个独立事件互不干扰。这种写法在表单类组件、配置面板类组件里特别好用比传一个大型响应式对象然后靠深比较稳定得多。4.3 Vue 3.4 的 defineModel 简化Vue 3.4 推出了defineModel宏专门简化单向 v-model 组件的写法。上面的SearchBox如果改用defineModel可以省掉 props 和 emit 的声明script setup const modelValue defineModel({ type: String, default: }) // modelValue 是一个 ref直接读取和赋值即可 /script赋值时不需要再手动触发update:modelValue因为defineModel自动完成了这个动作。但如果你还有其他自定义事件比如search、clear仍然需要单独声明emit。也就是说script setup const modelValue defineModel({ type: String, default: }) const emit defineEmits([search, clear]) function onSearch() { emit(search, modelValue.value) } function onClear() { modelValue.value emit(clear) } /scriptdefineModel目前在生产项目里已经很稳了如果你用的是 Vue 3.4推荐在新组件里使用。它能让你少写不少模板代码而且对 TypeScript 的支持也更好。5. 常见问题与排查实录5.1 事件没触发按这几步排查这是群里被问烂的问题“为什么我在子组件里$emit了父组件监听不到”我的排查顺序很固定先确认事件名完全一致。把子组件的$emit(search)和父组件的search拿出来逐字符比对包括短横线和大小写。这是最高频的错误来源。确认监听位置正确。如果你用的是普通原生元素而不是组件search监听的是原生 DOM 的search事件和自定义事件完全是两码事。组件事件必须写在组件标签上。确认 emits 声明没有拼错。Vue 3 里如果emits声明了[search]你却触发了seach事件不会报错但父组件那边就是收不到。确认 emit 函数来自 defineEmits。在script setup中如果你从别的地方解构了一个emit或者写成了this.$emit在组合式 API 里就是无效的。检查父子组件是否真的注册成功。组件没注册、引用了错误的路径、父组件里根本没挂载子组件这些低级问题也会导致事件静默丢失。如果是 Options API 的this.$emit还要确认this指向当前组件实例。在setTimeout或者普通函数回调里this可能已经变了用箭头函数或者提前保存this可以规避。5.2 自定义事件和原生事件冲突子组件根节点上有原生事件同时自定义事件也叫这个名字容易发生混淆。比如你写了一个按钮组件希望点击时既触发原生 click 又抛出一个自定义clicktemplate button clickhandleClick slot / /button /template script setup const emit defineEmits([click]) function handleClick(e) { emit(click, e) } /script父组件MyButton clickhandleButtonClick按钮/MyButton这个写法在 Vue 3 中能不能正常工作答案是能但很容易出问题。因为默认情况下emits里声明了clickVue 就认为组件标签上的click是自定义事件而不会把它当作原生事件透传到根节点。这其实是你要的行为。但如果你声明漏了click会被透传到根button上变成一个原生监听器行为就完全不一样了。这个例子很好地说明了emits声明的额外价值它决定了一个事件监听器该走组件事件通道还是原生事件通道。所以组件上每个自定义事件都在emits里声明不是形式主义而是功能需要。5.3 什么时候不要用 $emit$emit虽好用也不是万能解药。遇到下面这些场景我建议换一种方案深层嵌套的组件需要共享状态爷爷传爸爸、爸爸传儿子、儿子再往上抛中间那层如果完全不关心这个数据纯属当传话筒。这种情况用provide/inject更干净或者直接把状态放到 Pinia。兄弟组件之间通信A 组件触发事件给父组件父组件再转手传给 B太绕了。直接抽一个共享状态出来或者用事件总线代码会清爽很多。高频更新的全局状态比如用户登录信息、主题配置、窗口尺寸。这类数据用$emit一级一级传组件每次重渲染都会消耗性能建议直接 Pinia。mixin / 插件内部的跨实例调用这种情况你需要的是全局事件系统而不是组件事件。选通信方案的判断标准就一句话数据需要在“谁”和“谁”之间流动路径越短越好。$emit只擅长处理父子之间的直接通信超出这个范围就别硬用了。6. 我的实操心得做了这么多年 Vue 项目我对$emit最大的体会是它是一个接口设计工具而不只是一个方法。写组件的时候我习惯先想清楚这个组件对外要暴露哪些事件再动手写模板。事件设计得好组件复用性就高事件设计得乱后面每个对接的人都会骂。具体操作上我有几个固定的习惯所有事件名统一 kebab-case不写 camelCase所有emits都显式声明不管项目有没有开启严格模式载荷能传对象就传对象给未来留扩展余地每个事件在注释里说明触发时机和载荷结构。这些习惯看起来很繁琐但它们帮我避开了大量“事件不触发”的午夜排查。另外建议你在项目里加一条代码规范自定义事件必须有统一前缀比如on-或select-这样在模板里一眼就能分清哪些是原生事件、哪些是组件自定义事件。比如change可能是原生 input 事件也可能是组件抛出的业务事件前缀区分能大大降低阅读成本。$emit本身没什么高深原理它就是 Vue 事件机制的暴露口。真正值钱的是你怎么用它来组织组件之间的对话。把这套思路想清楚了写组件会顺手很多也少走很多弯路。
Vue组件通信：深入$emit机制、命名规范与实战技巧
写 Vue 组件的人迟早都会跟$emit打交道。$emit是 Vue 实例上的一个内置方法专门用来在当前组件上触发自定义事件让父组件能够通过事件监听器接收到子组件发出的信号。在 Vue 的组件通信体系里它有独特的位置props 负责父传子$emit负责子传父。无论你用 Options API 还是 Composition API无论你写的是传统业务组件还是通用基础组件都绕不开它。这篇文章想拆开讲讲$emit的机制、命名规范、常见用法以及那些在官方文档里不容易看到的实操心得适合刚入门 Vue 的新人也适合写了很久组件但偶尔还会踩事件坑的同学。1. 为什么组件通信需要 $emit1.1 单向数据流的设计逻辑Vue 的数据流动有一个底层约定状态只能从父组件通过 props 流向子组件子组件不能直接修改 props。直接给 props 赋值运行时会在控制台打出警告而且一旦组件层级变深数据源就会变得混乱排查问题的时候根本分不清是哪个组件改了状态。那子组件想通知父组件“用户操作了”“数据加载完了”“某个状态需要重置”该怎么办答案就是触发一个事件。$emit不会去改动父组件的状态它只是发出一个信号由父组件决定如何响应。这个设计和 DOM 原生事件非常像按钮自己不知道页面其他地方发生了什么它只是把 click 事件抛出去监听者自己去处理后续逻辑。打个比方下级向上级汇报工作下级只负责把情况说明白拍板决定是上级的事。如果下级直接替上级改决策整个工作流就乱套了。$emit就是这个“汇报动作”它保证了数据流的单向性也让组件之间的契约变得清晰父组件通过 props 下发数据子组件通过事件上报行为两边各司其职。1.2 组件通信方案对比$emit 的定位Vue 的组件通信方式不止一种常见的还有provide/inject、事件总线Event Bus、Vuex / Pinia 状态管理。很多人一开始会纠结“该用哪个”其实它们的适用场景差异很明显。通信方式数据方向典型场景优点缺点props $emit父子双向基础组件、表单控件、业务组件显式、可追踪、类型友好层级深了会繁琐provide / inject祖先到后代跨多层传递配置、主题、服务实例穿透层级写法简洁数据流不直观响应式需额外处理Event Bus任意方向非父子组件通信使用简单无需引入状态库事件满天飞难以调试易产生内存泄漏Vuex / Pinia任意组件全局共享状态、复杂业务数据集中管理可观测、可调试样板代码多不适合简单场景$emit的核心优势是两个一是显式组件到底抛出哪些事件看emits声明就知道二是就近父子之间直接通信不需要引入额外依赖。项目里大部分组件交互其实都是父子关系所以$emit的使用频率远超其他方案。我的经验是能就近用 props/$emit解决的绝不往上引状态管理只有状态要被很多组件共享再考虑 Pinia。2. $emit 的核心机制与实操细节2.1 先声明 emits再谈触发很多老项目里能看到这种写法在 methods 里直接this.$emit(some-event, payload)组件上也没有任何声明。这种写法能用但不是一个好习惯。在 Vue 3 中官方推荐在组件上显式声明emits选项。作用有三个第一把组件对外暴露的接口列出来阅读代码的人一眼就知道这个组件能抛什么事件第二Vue 可以据此判断某个落在组件上的事件监听器是自定义事件还是原生 DOM 事件避免误绑第三支持事件参数校验和 props 校验类似可以提前暴露数据类型问题。Options API 的写法export default { emits: [search, clear], methods: { handleSearch() { this.$emit(search, { keyword: this.keyword }) } } }Composition API 配合script setup的写法更简洁script setup const emit defineEmits([search, clear]) function handleSearch() { emit(search, { keyword: vue }) } /scriptdefineEmits返回的是一个emit函数组件里所有需要上报的信号都通过它触发。注意在script setup中使用defineEmits时不需要导入它是编译器宏。我个人习惯是在每个组件文件里都给emits做声明即使当时只有一两个事件。因为组件的接口就像函数的签名后面维护的人改起来会非常感谢你。如果你写的是通用组件库还建议加上事件参数校验script setup const emit defineEmits({ search: (payload) { if (payload typeof payload.keyword string) { return true } else { console.warn(search 事件的载荷必须是包含 keyword 字段的对象) return false } } }) /script校验不通过时 Vue 会在开发环境给出警告这玩意在多人协作时特别有用。2.2 事件命名kebab-case 是最稳的选择事件命名是$emit最容易踩坑的地方。Vue 官方文档反复强调事件名和 props 不一样不会自动做大小写转换。组件上监听的事件名必须和$emit触发的事件名完全一致。官方推荐的写法是始终用 kebab-case也就是全小写加短横线。原因很简单在模板里my-event是合法写法而myEvent在 HTML 环境中会被浏览器自动转成小写myevent导致大小写不匹配。虽然 Vue 模板编译器对组件监听器做了不少兼容处理但为了跨环境稳妥kebab-case 是零风险选择。下面这个例子在实际项目中经常见到属于典型的“看着对跑起来不响”// 子组件里触发 this.$emit(myEvent)!-- 父组件里监听 -- MyComponent my-eventhandleIt /如果子组件触发的是myEvent父组件监听的是my-event在很多场景下这个事件就是静默丢失的。虽然某些 Vue 版本做了兼容处理但你不能把“兼容”当“保证”。统一策略触发和监听都用 kebab-case。// 子组件 emit(my-event) // 父组件 MyComponent my-eventhandleIt /问为什么文档不推荐 camelCase因为事件名不是 JavaScript 标识符它没必要跟变量名保持一致。kebab-case 在模板里看起来也更自然接近于原生 HTML 事件的观感。2.3 载荷参数单参数、多参数与 $event$emit的第二个及以后参数都会传给父组件的监听函数。传一个参数最常用script setup const emit defineEmits([select]) function onSelect(item) { emit(select, item) } /script父组件接收时模板里可以直接用$event拿到载荷Child selecthandleSelect /function handleSelect(item) { console.log(item) }如果需要传多个独立参数也完全支持emit(page-change, pageNum, pageSize)父组件监听函数里按位置接收function onPageChange(pageNum, pageSize) { // ... }这是一个常常被忽略的细节如果不确定后续会不会增加参数建议直接传一个对象载荷。对象的好处是字段可以随时扩充且不需要调整监听函数的参数顺序。项目里我几乎只传两种形式单个基本类型值或者一个包含完整上下文的对象。传多个散参数的情况尽量避免因为人数一多“第三个参数到底是啥”就成了新的讨论话题。另一个容易被忽视的点$event只是模板里的语法糖它代表事件监听函数收到的第一个参数。如果监听函数本身写在了模板里且需要同时访问事件载荷和组件自身的数据可以写成Child select(item) handleSelect(item, localData) /这样item是子组件传上来的载荷localData是当前组件作用域里的数据。3. 实战构建一个可复用的搜索框组件3.1 需求拆解与事件设计理论说再多不如上手写一个。我们做一个搜索框组件需求如下输入框内容与父组件状态双向同步用户输入完成后按回车触发搜索输入框有内容时显示“清空”按钮点击后清空输入并通知父组件搜索时把关键词上报父组件自行处理请求逻辑这个组件涉及三个对外事件update:modelValue用于 v-model 同步、search回车搜索、clear点击清空。事件设计的原则是组件只上报“发生了什么”不在内部做请求等副作用操作。3.2 组件编码实现创建SearchBox.vuetemplate div classsearch-box input :valuemodelValue typetext placeholder输入关键词搜索 inputonInput keyup.enteronSearch / button v-ifmodelValue classclear-btn clickonClear清空/button /div /template script setup const props defineProps({ modelValue: { type: String, default: } }) const emit defineEmits([update:modelValue, search, clear]) function onInput(e) { // 输入时同步给父组件这也是 v-model 的工作方式 emit(update:modelValue, e.target.value) } function onSearch() { // 回车时上报搜索动作具体请求由父组件完成 emit(search, props.modelValue) } function onClear() { // 两种做法先清空再通知 emit(update:modelValue, ) emit(clear) } /script这个组件的输出接口非常清晰三个事件各有各的职责父组件愿意监听哪个就监听哪个不强制父组件必须处理search或者clear。这种松耦合设计就是$emit的典型用法——子组件把“信号”发出来父组件自己决定要不要响应。有一个细节值得注意onSearch里读取的是props.modelValue而不是输入框的 DOM 值。因为:value绑定的值已经是最新的输入内容而输入框的值同步到这个 prop 有一个时间差直接读props.modelValue更可靠。3.3 父组件接入与事件接收父组件使用SearchBox时v-model 负责双向绑定其他事件按需处理template div SearchBox v-modelkeyword searchfetchSearch clearhandleClear / p当前关键词{{ keyword }}/p /div /template script setup import { ref } from vue import SearchBox from ./SearchBox.vue const keyword ref() const results ref([]) async function fetchSearch(keyword) { if (!keyword.trim()) return // 这里才真正发起请求 const { data } await api.search(keyword) results.value data } function handleClear() { // 可以在这里做统计、重置列表等操作 results.value [] } /script注意searchfetchSearch这里子组件search事件的载荷直接作为第一个参数传给了fetchSearch也就是关键词字符串。如果你在处理函数里不需要这个参数比如handleClear那就直接不写参数。实际项目里我还会给这个搜索框加一个防抖输入时不立即同步而是由父组件决定是否延迟处理。防抖逻辑放在子组件还是父组件取决于你的场景。如果只是做搜索联想放在父组件处理update:modelValue时做防抖更合适如果每个输入框都有这个需求封装进子组件更划算。不过要注意子组件内部做了防抖会影响 v-model 的即时性这个取舍要结合业务来看。4. 进阶用 $emit 打通 v-model4.1 update:modelValue 约定v-model 是 Vue 的双向绑定语法糖剥开看它的底层就是$emit。Vue 3 中在组件上使用v-modelkeyword等价于SearchBox :modelValuekeyword update:modelValuekeyword $event /所以子组件里实现 v-model 的核心就是接收modelValue这个 prop并在变化时触发update:modelValue事件。第三节的SearchBox就是这么实现的没有依赖任何魔法。Vue 2 的用户可能会奇怪当年不是流行.sync修饰符吗其实 Vue 2 的.sync就是update:propName事件的语法糖Vue 3 干脆把.sync能力并进了 v-model多个 v-model 的写法也更自然。在 Vue 3 中你甚至还能给 v-model 起名字。4.2 多个 v-model 绑定一个组件需要同步多个值时不用再写一个对象然后到处解构Vue 3 支持多个 v-modelUserForm v-model:namename v-model:ageage v-model:emailemail /对应的子组件实现script setup const props defineProps({ name: String, age: Number, email: String }) const emit defineEmits([update:name, update:age, update:email]) function updateName(e) { emit(update:name, e.target.value) } // age、email 同理 /script这里每个update:xxx都是一个独立事件互不干扰。这种写法在表单类组件、配置面板类组件里特别好用比传一个大型响应式对象然后靠深比较稳定得多。4.3 Vue 3.4 的 defineModel 简化Vue 3.4 推出了defineModel宏专门简化单向 v-model 组件的写法。上面的SearchBox如果改用defineModel可以省掉 props 和 emit 的声明script setup const modelValue defineModel({ type: String, default: }) // modelValue 是一个 ref直接读取和赋值即可 /script赋值时不需要再手动触发update:modelValue因为defineModel自动完成了这个动作。但如果你还有其他自定义事件比如search、clear仍然需要单独声明emit。也就是说script setup const modelValue defineModel({ type: String, default: }) const emit defineEmits([search, clear]) function onSearch() { emit(search, modelValue.value) } function onClear() { modelValue.value emit(clear) } /scriptdefineModel目前在生产项目里已经很稳了如果你用的是 Vue 3.4推荐在新组件里使用。它能让你少写不少模板代码而且对 TypeScript 的支持也更好。5. 常见问题与排查实录5.1 事件没触发按这几步排查这是群里被问烂的问题“为什么我在子组件里$emit了父组件监听不到”我的排查顺序很固定先确认事件名完全一致。把子组件的$emit(search)和父组件的search拿出来逐字符比对包括短横线和大小写。这是最高频的错误来源。确认监听位置正确。如果你用的是普通原生元素而不是组件search监听的是原生 DOM 的search事件和自定义事件完全是两码事。组件事件必须写在组件标签上。确认 emits 声明没有拼错。Vue 3 里如果emits声明了[search]你却触发了seach事件不会报错但父组件那边就是收不到。确认 emit 函数来自 defineEmits。在script setup中如果你从别的地方解构了一个emit或者写成了this.$emit在组合式 API 里就是无效的。检查父子组件是否真的注册成功。组件没注册、引用了错误的路径、父组件里根本没挂载子组件这些低级问题也会导致事件静默丢失。如果是 Options API 的this.$emit还要确认this指向当前组件实例。在setTimeout或者普通函数回调里this可能已经变了用箭头函数或者提前保存this可以规避。5.2 自定义事件和原生事件冲突子组件根节点上有原生事件同时自定义事件也叫这个名字容易发生混淆。比如你写了一个按钮组件希望点击时既触发原生 click 又抛出一个自定义clicktemplate button clickhandleClick slot / /button /template script setup const emit defineEmits([click]) function handleClick(e) { emit(click, e) } /script父组件MyButton clickhandleButtonClick按钮/MyButton这个写法在 Vue 3 中能不能正常工作答案是能但很容易出问题。因为默认情况下emits里声明了clickVue 就认为组件标签上的click是自定义事件而不会把它当作原生事件透传到根节点。这其实是你要的行为。但如果你声明漏了click会被透传到根button上变成一个原生监听器行为就完全不一样了。这个例子很好地说明了emits声明的额外价值它决定了一个事件监听器该走组件事件通道还是原生事件通道。所以组件上每个自定义事件都在emits里声明不是形式主义而是功能需要。5.3 什么时候不要用 $emit$emit虽好用也不是万能解药。遇到下面这些场景我建议换一种方案深层嵌套的组件需要共享状态爷爷传爸爸、爸爸传儿子、儿子再往上抛中间那层如果完全不关心这个数据纯属当传话筒。这种情况用provide/inject更干净或者直接把状态放到 Pinia。兄弟组件之间通信A 组件触发事件给父组件父组件再转手传给 B太绕了。直接抽一个共享状态出来或者用事件总线代码会清爽很多。高频更新的全局状态比如用户登录信息、主题配置、窗口尺寸。这类数据用$emit一级一级传组件每次重渲染都会消耗性能建议直接 Pinia。mixin / 插件内部的跨实例调用这种情况你需要的是全局事件系统而不是组件事件。选通信方案的判断标准就一句话数据需要在“谁”和“谁”之间流动路径越短越好。$emit只擅长处理父子之间的直接通信超出这个范围就别硬用了。6. 我的实操心得做了这么多年 Vue 项目我对$emit最大的体会是它是一个接口设计工具而不只是一个方法。写组件的时候我习惯先想清楚这个组件对外要暴露哪些事件再动手写模板。事件设计得好组件复用性就高事件设计得乱后面每个对接的人都会骂。具体操作上我有几个固定的习惯所有事件名统一 kebab-case不写 camelCase所有emits都显式声明不管项目有没有开启严格模式载荷能传对象就传对象给未来留扩展余地每个事件在注释里说明触发时机和载荷结构。这些习惯看起来很繁琐但它们帮我避开了大量“事件不触发”的午夜排查。另外建议你在项目里加一条代码规范自定义事件必须有统一前缀比如on-或select-这样在模板里一眼就能分清哪些是原生事件、哪些是组件自定义事件。比如change可能是原生 input 事件也可能是组件抛出的业务事件前缀区分能大大降低阅读成本。$emit本身没什么高深原理它就是 Vue 事件机制的暴露口。真正值钱的是你怎么用它来组织组件之间的对话。把这套思路想清楚了写组件会顺手很多也少走很多弯路。
