Vue3 emits 属性（千字长文）

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

• 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;
• 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 82w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 2900+ 小伙伴加入学习 ，欢迎点击围观

前言

在 Vue.js 开发中，父子组件间的通信是构建复杂应用的核心能力之一。Vue3 引入的 emits 属性，通过规范化事件命名和参数传递，为开发者提供了更安全、更易维护的通信方式。对于编程初学者，理解 emits 的工作原理能避免常见的事件绑定错误；而对中级开发者，掌握其高级用法能提升代码的健壮性和可扩展性。本文将从基础概念出发，结合实际案例，深入讲解如何在 Vue3 中高效使用 emits 属性。

Vue3 emits 属性的定义与作用

emits 属性是 Vue3 中用于声明组件可触发事件的列表，它类似于 Vue2 中的 $emit 方法，但增加了类型校验和代码规范功能。通过 emits，开发者可以：

1. 明确组件向外暴露的事件名称
2. 限制非声明事件的触发（生产模式下）
3. 结合 TypeScript 实现参数类型约束

形象比喻：
可以把 emits 想象为快递公司的包裹类型清单。例如，一个快递员只能接收“文件”或“包裹”两种类型，若有人试图寄送“活体动物”，系统会直接拦截。类似地，emits 确保组件只响应已声明的事件类型，避免意外事件污染。

基础用法：定义与触发事件

1. 在子组件中声明 events

在子组件中，通过 emits 选项列出所有可触发的事件名：

export default {
  name: 'ChildComponent',
  emits: ['form-submit', 'error-occurred'],
  // ...其他配置
}

此例中，子组件只能通过 $emit('form-submit') 或 $emit('error-occurred') 触发事件，其他名称的事件在生产模式下会被静默忽略。

2. 父组件监听事件

父组件通过 v-on 或 @ 符号监听子组件事件：

<template>
  <ChildComponent 
    @form-submit="handleFormSubmit" 
    @error-occurred="handleError"
  />
</template>

进阶用法：参数传递与类型约束

1. 传递事件参数

事件可以携带数据对象，父组件通过回调函数接收：
子组件触发事件：

// 子组件内部
this.$emit('form-submit', {
  username: this.username,
  email: this.email
});

父组件处理数据：

methods: {
  handleFormSubmit(formData) {
    console.log('Received:', formData);
    // 执行表单提交逻辑
  }
}

2. 结合 TypeScript 增强类型安全

通过 TypeScript 的类型注解，可定义事件参数的结构：

// 子组件声明
import type { DefineComponent } from 'vue';

const ChildComponent: DefineComponent<{
  emits: {
    (e: 'form-submit', payload: { username: string; email: string }): void
    (e: 'error-occurred', message: string): void
  }
}> = {
  // 组件逻辑
}

此时，IDE 会自动提示事件参数类型，避免运行时错误。

实际案例：表单提交功能实现

场景描述

构建一个包含用户名和邮箱输入的表单，子组件负责数据收集，父组件处理提交逻辑。

代码实现

子组件（ChildForm.vue）：

<template>
  <div>
    <input v-model="username" placeholder="Username" />
    <input v-model="email" placeholder="Email" />
    <button @click="handleSubmit">Submit</button>
  </div>
</template>

<script>
export default {
  name: 'ChildForm',
  emits: ['form-submit'],
  data() {
    return {
      username: '',
      email: ''
    };
  },
  methods: {
    handleSubmit() {
      if (this.username && this.email) {
        this.$emit('form-submit', {
          username: this.username,
          email: this.email
        });
      } else {
        this.$emit('error-occurred', 'Please fill all fields');
      }
    }
  }
};
</script>

父组件（ParentContainer.vue）：

<template>
  <ChildForm 
    @form-submit="handleSuccess"
    @error-occurred="handleError"
  />
</template>

<script>
export default {
  methods: {
    handleSuccess(formData) {
      console.log('Form submitted:', formData);
      // 调用 API 提交数据
    },
    handleError(message) {
      alert(`Error: ${message}`);
    }
  }
};
</script>

常见问题与解决方案

问题 1：事件未触发的排查

可能原因：

• 未在 emits 中声明事件名称
• 父组件监听的事件名拼写错误

解决方案：

1. 检查子组件的 emits 数组是否包含对应事件
2. 确保父组件使用 @ 符号时事件名与子组件完全一致

问题 2：事件参数丢失

可能原因：

• 父组件未正确接收参数
• 子组件触发事件时未传递参数

解决方案：
在子组件中通过 console.log 验证 $emit 的参数值，父组件回调函数使用默认参数值兜底：

handleFormSubmit(formData = {}) {
  console.log('Fallback data:', formData);
}

与 Vue2 的对比：关键改进

高级技巧：动态事件与组合式 API

1. 在 setup() 中使用 emits

通过组合式 API 定义事件时，需在 defineEmits 函数中声明：

<script setup>
import { defineEmits } from 'vue';

const emit = defineEmits(['custom-event']);
emit('custom-event', 'Hello from setup()!');
</script>

2. 动态触发事件（谨慎使用）

虽然 emits 强制声明，但可通过变量动态触发事件：

const dynamicEventName = 'item-selected';
this.$emit(dynamicEventName, selectedItem);

注意：动态事件名需预先包含在 emits 数组中。

总结与实践建议

Vue3 emits 属性 是构建健壮组件系统的关键工具，它通过显式声明和类型约束，降低了组件间通信的复杂度。对于开发者：

1. 养成声明习惯：始终在子组件中用 emits 列出所有事件
2. 善用 TypeScript：结合类型注解提升代码可靠性
3. 分层事件设计：复杂应用中可采用事件总线或状态管理库（如 Pinia）补充

通过本文的案例和技巧，读者可以快速掌握 Vue3 emits 属性 的核心用法，并在实际项目中应用这些规范，提升代码质量和团队协作效率。