Vue / 系统课时
Emits 事件类型
Emits 事件类型
组件向父级发送事件时,真正需要约束的不只是事件名,还包括每个事件携带的参数。使用 TypeScript 为 defineEmits 声明类型后,子组件触发事件和父组件处理事件都围绕同一份契约工作,可以更早发现名称拼写和参数类型错误。
学习目标
- 使用
defineEmits为组件事件声明名称与参数类型。 - 正确触发带参数和不带参数的自定义事件。
- 理解事件类型契约能检查什么,以及哪些边界仍需自行设计。
事件契约包含什么
一个组件事件至少包含两个信息:事件名称和参数列表。例如保存事件可以规定为 save(id: number, draft: boolean),取消事件则没有额外参数。
类型契约的价值在于把这两个信息固定下来。子组件调用 emit 时,TypeScript 会检查事件名是否存在、参数个数是否匹配、参数类型是否正确;父组件编写处理函数时,也能更明确地知道应接收哪些数据。
用 defineEmits 声明并触发事件
片段示例:以下两段需配套放入现有 Vue 3 + TypeScript 项目中。先创建子组件 EditorActions.vue:
<script setup lang="ts">
const emit = defineEmits<{
(event: 'save', id: number, draft: boolean): void
(event: 'cancel'): void
}>()
function saveDraft(): void {
emit('save', 42, true)
}
function cancelEdit(): void {
emit('cancel')
}
</script>
<template>
<div>
<button type="button" @click="saveDraft">保存草稿</button>
<button type="button" @click="cancelEdit">取消</button>
</div>
</template>再在父组件中监听事件:
<script setup lang="ts">
import EditorActions from './EditorActions.vue'
function handleSave(id: number, draft: boolean): void {
console.log(`save ${id}, draft=${draft}`)
}
function handleCancel(): void {
console.log('cancel')
}
</script>
<template>
<EditorActions
@save="handleSave"
@cancel="handleCancel"
/>
</template>预期结果
点击“保存草稿”后,控制台输出:
save 42, draft=true
点击“取消”后,控制台输出:
cancel如果把子组件中的调用改成不存在的事件名,或者把 id 传成字符串,在启用了 Vue TypeScript 类型检查的 IDE 或 vue-tsc 中会报告类型错误,从而在运行前发现契约不一致。
设计事件时保持契约清晰
事件名应该表达“发生了什么”,例如 save、select、remove,而不是暴露子组件内部实现细节。参数只传父组件真正需要的数据;如果父组件只需要记录 ID,就没有必要把整个内部状态对象都作为事件参数暴露出去。
当事件参数较多时,可以改为传递一个有明确类型的对象,避免位置参数难以阅读。对象字段也更容易向后扩展,但仍应控制大小,避免把组件内部模型直接泄漏成公共 API。
类型检查的边界
defineEmits 的类型声明主要服务于编译期,它不会自动把 TypeScript 类型变成运行时数据校验。若事件参数来自不可信外部输入,仍应在进入组件状态或业务逻辑时进行必要的运行时校验。
把事件看成组件的上行 API,会更容易做出稳定设计:事件名是方法名,参数类型是调用约定,父组件是调用方。只要这份契约保持小而明确,组件重构时就更容易判断哪些改动会影响外部使用者。