Vue 3 中 TypeScript 标注 emits 的核心是编译期校验事件参数名、类型与数量，主流写法有接口方式（适合多事件/可复用组件）和函数重载签名方式（适合少事件/结构清晰组件），二者按场景选用。
Vue 3 中用 TypeScript 标注 emits，核心是让子组件触发事件时参数名、类型、数量都受编译期检查——写错参数或漏传，IDE 就会报错，而不是等运行时才发现。
两种主流写法：对象式接口 vs 函数重载签名
推荐根据场景选择，不是非此即彼：
-
接口方式（interface）：适合事件多、需复用或继承的组件（比如表单基类、弹窗组件）。可扩展、易维护，支持
extends合并事件定义。 - 函数重载签名方式：适合事件少、结构清晰的组件。语法紧凑，每个事件单独声明，IDE 补全更直接，类型错误提示更精准。
接口方式：用 interface 明确事件结构
先定义接口，再传给 defineEmits：
interface MyComponentEmits {
// 无参事件
'open': []
// 单参数，带可读参数名（TS 支持，不参与运行时）
'update:visible': [visible: boolean]
// 多参数，含对象类型
'submit': [data: { name: string; age?: number }, meta: { from: 'user' | 'system' }]
// 自定义事件，返回 Promise 结果（可选）
'validate': [value: string, resolve: (valid: boolean) => void]
}
然后使用：
vue-component-analyzer
下载
递归分析 Vue 项目组件依赖，从入口文件生成组件层级图，支持 Vue 2/3，输出组件名、文件路径和属性。适用于分析组件结构、排查依赖或了解项目架构。
立即学习“前端免费学习笔记（深入）”；
const emit = defineEmits<MyComponentEmits>()
调用时必须严格匹配：
emit('update:visible', true) // ✅ 正确
emit('submit', { name: 'Alice' }, { from: 'user' }) // ✅ 正确
emit('submit', 'wrong') // ❌ 类型错误：期望对象，传了字符串
函数重载签名方式：更贴近“事件即函数”的直觉
把每个事件看作一个函数调用，直接写出所有可能的调用签名：
const emit = defineEmits<{
(e: 'open'): void
(e: 'update:visible', visible: boolean): void
(e: 'submit', data: { name: string }, meta: { from: string }): void
(e: 'error', code: number, msg: string): void
}>()
这种写法下，TypeScript 会为 emit 生成重载函数类型，调用时自动匹配对应签名。比如：
emit('error', 404, 'Not found') // ✅ 匹配第4个签名
emit('error', 'oops') // ❌ 缺少 code 参数，类型不满足任何签名
注意事项和避坑点
- 运行时数组写法（如
defineEmits(['click', 'input'])）不提供类型校验，仅用于快速原型，上线项目不建议用。 - 事件名含冒号（如
update:modelValue）必须加引号，否则 TS 解析为属性访问会报错。 - 不能在泛型中直接使用 import 的类型（如
defineEmits<ImportedEmits>()），Vue 编译器目前不追踪导入文件；应把接口定义在当前文件或通过export type+ 本地import type方式引入。 - 父组件监听时，回调函数参数类型由
emits类型反向推导，无需额外标注，IDE 也能自动补全。
