Vue 3 Composition API 中强制要求组件 emit 特定事件

在 vue 3 Composition API 中，defineEmits 用于声明组件可以触发的事件。然而，仅仅声明事件并不能强制组件的使用者监听这些事件。为了确保关键事件被正确处理，我们需要一种机制来检查组件使用者是否提供了相应的事件监听器。本文将介绍如何通过自定义函数实现这一功能，并在开发环境下发出警告。

实现原理

Vue 在编译时会将 @foo 事件监听器转换为 vnode 上的 onFoo prop。因此，我们可以通过检查组件实例的 vnode props 中是否存在 onFoo 属性，来判断是否定义了 @foo 事件监听器。

实现步骤

立即学习“前端免费学习笔记（深入）”；

1. 创建 checkEmits 函数:

   import { getCurrentInstance } from 'vue';  function toPascalCase(str) {   return str.replace(/(?:^w|[A-Z]|bw|s+)/g, function(match, index) {     if (+match === 0) return ""; // or if (/s+/.test(match)) for white spaces     return index === 0 ? match.toLowerCase() : match.toUpperCase();   }).replace(/[s-]/g, ""); }  function checkEmits(...eventNames) {   let props;    if (import.meta.env.DEV && (props = getCurrentInstance()?.vnode.props)) {     for (const name of eventNames) {       const propName = 'on' + toPascalCase(name);       if (typeof props[propName] !== 'function')         console.warn(`${name} event listener is missing`);     }   }    return eventNames; }
   • getCurrentInstance(): 获取当前组件实例。
   • import.meta.env.DEV: 确保只在开发环境下进行检查。
   • vnode.props: 获取组件实例的 vnode props。
   • toPascalCase(name): 将事件名转换为 PascalCase 形式，例如将 handle-close 转换为 HandleClose。
   • 遍历 eventNames 数组，检查是否存在对应的 onEventName prop。
   • 如果 prop 不存在或类型不是函数，则发出警告。

2. 在组件中使用 checkEmits 函数:

   <script setup> import { defineEmits, getCurrentInstance } from 'vue';  function toPascalCase(str) {   return str.replace(/(?:^w|[A-Z]|bw|s+)/g, function(match, index) {     if (+match === 0) return ""; // or if (/s+/.test(match)) for white spaces     return index === 0 ? match.toLowerCase() : match.toUpperCase();   }).replace(/[s-]/g, ""); }  function checkEmits(...eventNames) {   let props;    if (import.meta.env.DEV && (props = getCurrentInstance()?.vnode.props)) {     for (const name of eventNames) {       const propName = 'on' + toPascalCase(name);       if (typeof props[propName] !== 'function')         console.warn(`${name} event listener is missing`);     }   }    return eventNames; }  const emit = defineEmits(['handleClose', 'customEvent']);  checkEmits('handleClose'); // 强制要求监听 handleClose 事件 checkEmits('customEvent'); // 强制要求监听 customEvent 事件  type Props = { isOpen: boolean }; defineProps<Props>();  const onClose = () => {   emit('handleClose'); };  const onCustomEvent = () => {     emit('customEvent'); } </script>  <template>   <button @click="onClose">Close</button>   <button @click="onCustomEvent">Custom Event</button> </template>
   • 在 defineEmits 声明事件之后，立即调用 checkEmits 函数，传入需要强制监听的事件名称。

注意事项

• 此方法仅在开发环境下生效，不会影响生产环境的性能。
• 可以根据实际需求修改 checkEmits 函数，例如自定义警告信息或添加更复杂的检查逻辑。
• 该方法主要用于提醒开发者，并不能完全阻止组件使用者忽略必要的事件监听。

总结

通过自定义 checkEmits 函数，我们可以在 Vue 3 Composition API 中实现强制要求组件使用者监听特定事件的功能。这有助于提高代码质量，减少潜在的错误，并增强组件的可维护性。 虽然不能完全强制，但可以起到很好的提示作用，帮助开发者避免遗漏关键事件的处理。