Vue / 系统课时

Emits 事件类型

Emits 事件类型

组件向父级发送事件时,真正需要约束的不只是事件名,还包括每个事件携带的参数。使用 TypeScript 为 defineEmits 声明类型后,子组件触发事件和父组件处理事件都围绕同一份契约工作,可以更早发现名称拼写和参数类型错误。

学习目标

  • 使用 defineEmits 为组件事件声明名称与参数类型。
  • 正确触发带参数和不带参数的自定义事件。
  • 理解事件类型契约能检查什么,以及哪些边界仍需自行设计。

事件契约包含什么

一个组件事件至少包含两个信息:事件名称和参数列表。例如保存事件可以规定为 save(id: number, draft: boolean),取消事件则没有额外参数。

类型契约的价值在于把这两个信息固定下来。子组件调用 emit 时,TypeScript 会检查事件名是否存在、参数个数是否匹配、参数类型是否正确;父组件编写处理函数时,也能更明确地知道应接收哪些数据。

用 defineEmits 声明并触发事件

片段示例:以下两段需配套放入现有 Vue 3 + TypeScript 项目中。先创建子组件 EditorActions.vue:

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>

再在父组件中监听事件:

vue
<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>

预期结果

text
点击“保存草稿”后,控制台输出:
save 42, draft=true

点击“取消”后,控制台输出:
cancel

如果把子组件中的调用改成不存在的事件名,或者把 id 传成字符串,在启用了 Vue TypeScript 类型检查的 IDE 或 vue-tsc 中会报告类型错误,从而在运行前发现契约不一致。

设计事件时保持契约清晰

事件名应该表达“发生了什么”,例如 save、select、remove,而不是暴露子组件内部实现细节。参数只传父组件真正需要的数据;如果父组件只需要记录 ID,就没有必要把整个内部状态对象都作为事件参数暴露出去。

当事件参数较多时,可以改为传递一个有明确类型的对象,避免位置参数难以阅读。对象字段也更容易向后扩展,但仍应控制大小,避免把组件内部模型直接泄漏成公共 API。

类型检查的边界

defineEmits 的类型声明主要服务于编译期,它不会自动把 TypeScript 类型变成运行时数据校验。若事件参数来自不可信外部输入,仍应在进入组件状态或业务逻辑时进行必要的运行时校验。

把事件看成组件的上行 API,会更容易做出稳定设计:事件名是方法名,参数类型是调用约定,父组件是调用方。只要这份契约保持小而明确,组件重构时就更容易判断哪些改动会影响外部使用者。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Emits 事件类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通