radix-vue 组件封装利器 useEmitAsProps将 emits 一键转换为 props 事件处理器【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vueuseEmitAsProps是 radix-vue原 Radix Vue核心包提供的一个工具 composable用于把组件声明的emits事件集合自动转换为 Vue 组件可接受的onXxx形式的事件处理 props。本指南将围绕它的设计动机、源码实现、类型系统以及在仓库真实组件如 Drawer、DropdownMenu中的用法展开帮助你彻底解决“封装组件时逐个透传事件”的痛点写出更简洁、类型安全的包装组件。为什么需要 useEmitAsProps事件透传的痛点在使用 Vue 封装第三方组件即构建 wrapper时最大的麻烦之一就是事件的转发。假设你基于某个底层组件封装了一个高阶组件底层组件可能抛出update:modelValue、change、close等各类事件为了让上层使用者依然能监听这些事件你必须在模板里逐个手动编写template Comp update:model-value(v) emit(update:modelValue, v) change(v, extra) emit(change, v, extra) close(reason) emit(close, reason) / /template事件越多透传代码越冗长且很容易遗漏或写错事件名。Vue 核心本身并没有提供“事件透传”的内建机制可参考 vuejs/core#5917 中实现了useEmitAsProps它会读取你通过defineEmits声明的事件列表把每个事件转换为对应的onXxx处理器 props之后只需一次v-bind即可完成全部事件转发。基本用法声明 emits一行完成事件绑定根据官方文档 use-emit-as-props.md 的说明使用方式非常直观script setup langts import { useEmitAsProps } from reka-ui const emits defineEmitsCompEmitType() const emitsAsProps useEmitAsProps(emits) /script template Comp v-bindemitsAsProps ... /Comp /template核心逻辑就三步用defineEmitsCompEmitType()声明组件要透传的所有事件调用useEmitAsProps(emits)得到一个emitsAsProps对象其中每个事件名都被转换成了onXxx格式的处理器在模板中通过Comp v-bindemitsAsProps一次性把全部事件处理器传给底层组件。注意文档示例中的导入路径为reka-ui在当前仓库中该工具由核心包统一入口 packages/core/src/index.ts 通过export { type EmitAsProps, useEmitAsProps } from ./shared对外导出见 shared/index.ts实际安装后按你所使用的包名导入即可。源码剖析事件名到 onXxx 处理器的映射原理useEmitAsProps的实现非常精简其核心只有 20 余行见 useEmitAsProps.tsexport function useEmitAsPropsName extends string, Fn extends AnyFn AnyFn(emit: EmitName, Fn) { const vm getCurrentInstance() const events vm?.type.emits as Name[] const result: Recordstring, any {} if (!events?.length) { console.warn( No emitted event found. Please check component: ${vm?.type.__name}, ) } events?.forEach((ev) { result[toHandlerKey(camelize(ev))] (...arg: any) emit(ev, ...arg) }) return result as EmitAsPropsFn }逐行拆解其工作原理读取事件声明通过getCurrentInstance()拿到当前组件实例从vm.type.emits读取你在defineEmits中声明的事件名数组。Vue 会把defineEmits的声明挂载到组件的emits选项中因此这里能拿到完整的事件名列表。事件名驼峰化对每个事件名调用 Vue 的camelize把update:model-value、close这类写法统一转换为update:modelValue、close的驼峰形态。转换为处理器 key再调用 Vue 的toHandlerKey为驼峰事件名补上on前缀得到onUpdate:modelValue、onClose这样的 props 键名——这正是 Vue 子组件通过v-bind传递事件时使用的约定键名。闭包绑定 emit每个处理器内部执行emit(ev, ...arg)把收到的任意参数原样转发给事件名ev对应的 emit 调用。由于事件名在闭包中按项捕获即使底层组件同时触发多个不同事件也能各自正确路由。兜底警告如果组件没有声明任何 emits会通过console.warn输出No emitted event found. Please check component: 组件名提示开发者检查事件声明避免静默失败。类型层面的保证EmitAsProps 与重载事件推断useEmitAsProps的价值不止于运行时的事件映射它在 TypeScript 类型层面同样提供了完整的推断。函数返回类型EmitAsPropsFn见 useEmitAsProps.ts会根据 emit 函数的签名推导出每个事件对应的处理器 props 及其参数类型export type EmitAsPropsT extends AnyFn ExpandPartialMergeUnionEmitUnionOverloadUnionT类型链路上有多个关键环节HandlerKeyName在类型层面复刻了camelize与toHandlerKey的组合通过模板字面量类型把on-${Name}驼峰化例如update:modelValue会推导为onUpdate:modelValueEmitUnion将 emit 函数签名拆解为{ [K in HandlerKeyName]: (...args: Args) Return }的映射类型让每个事件都对应独立的处理器函数类型OverloadUnion/MergeUnion/Expand则用于合并 VuedefineEmits产生的重载签名把(e: update:modelValue, value: string) void、(e: change, value: number, extra: boolean) void等多个重载合并成一个同时包含onUpdate:modelValue与onChange的对象类型。这些类型断言并非空谈仓库提供了专门的编译期类型测试 useEmitAsProps.test-d.ts由vue-tsc在 type-check / build 阶段校验回归错误会直接导致构建失败。测试覆盖了三种典型场景// 重载 emit每个事件映射到其 onXxx 处理器 prop type _keys ExpectEqualkeyof Result, onUpdate:modelValue | onChange type _update ExpectEqualParametersNonNullableResult[onUpdate:modelValue], [value: string] type _change ExpectEqualParametersNonNullableResult[onChange], [value: number, extra: boolean] // 单一 emit type _keys ExpectEqualkeyof Result, onClose type _args ExpectEqualParametersNonNullableResult[onClose], [reason: string] // 宽松签名 (name: string, ...args: any[]) void 保持向后兼容 const result useEmitAsProps(looseEmit)这意味着在封装组件时不仅运行时会自动转发事件使用者通过change或:onChange监听时也能获得正确的参数类型提示实现“运行时 类型”双保险。配套组合技useForwardPropsEmits 一次转发 props 与 emits在实际封装中除了事件通常还需要透传 props。radix-vue 为此提供了useEmitAsProps的进阶版本useForwardPropsEmits见 useForwardPropsEmits.ts它内部同时调用useForwardProps解析并保留已赋值的 props与useEmitAsProps返回一个合并后的 computed 对象export function useForwardPropsEmitsT extends Recordstring, any( props: MaybeRefOrGetterT, emit?: EmitName, Fn, ) { const parsedProps useForwardProps(props) const emitsAsProps emit ? useEmitAsProps(emit) : {} return computed(() ({ ...parsedProps.value, ...emitsAsProps, })) }它的类型签名在传入 emit 时返回WithOptionalBooleansT EmitAsPropsFn即 props 与onXxx处理器同时被类型化不传 emit 时则只返回 props不会泄露多余的on*键这一行为同样在 useEmitAsProps.test-d.ts 中有断言。配套的useForwardProps位于 useForwardProps.ts会结合vm.type.props中的默认值与当前实例实际赋值的 props把未显式赋值的键剔除避免把未设置的值传给底层组件。仓库内的真实应用场景useEmitAsProps不是孤立的演示工具它在 radix-vue 的众多高阶组件中承担着事件透传的核心职责。以下两个例子展示了它在源码中的典型形态DropdownMenuItem 透传菜单事件见 DropdownMenuItem.vueconst emits defineEmitsDropdownMenuItemEmits() const emitsAsProps useEmitAsProps(emits)MenuItem v-bind{ ...props, ...emitsAsProps }DrawerContent 向底层实现组件透传关闭/交互事件见 DrawerContent.vue 与模板 L67-L94import { useEmitAsProps, useForwardExpose, useHideOthers } from /shared const props definePropsDrawerContentProps() const emits defineEmitsDrawerContentEmits() const rootContext injectDrawerRootContext() const emitsAsProps useEmitAsProps(emits)DrawerContentImpl v-ifisFullModal :refforwardRef v-bind{ ...props, ...emitsAsProps, ...$attrs } :trap-focusshouldTrapFocus :disable-outside-pointer-eventstrue 在 Drawer 的案例中DrawerContent与DrawerContentImpl之间隔着Presence进场/离场动画层事件无法通过组件树自动冒泡传递useEmitAsProps恰好解决了这种“跨层透传”的难题——外层把自身声明的emits如closeAutoFocus、interactOutside、pointerDownOutside等转换为 props通过v-bind传给内层实现组件。类似的使用还出现在 Dialog/DialogContent.vue、Menubar/MenubarItem.vue、ContextMenu/ContextMenuItem.vue、Toolbar/ToolbarToggleGroup.vue 等大量组件中是仓库内部“包装组件模式”的通用基础设施。使用要点与注意事项结合源码实现使用时有几点值得留意必须配合defineEmits使用useEmitAsProps依赖vm.type.emits读取事件声明因此传入的 emit 必须来自同组件的defineEmits如果组件没有声明任何事件控制台会输出警告返回对象为空。必须在组件 setup 作用域内调用实现依赖getCurrentInstance()在生命周期函数、事件回调或普通函数中调用会拿不到组件实例也就无法读取emits声明。事件名到 key 的转换规则事件名会先驼峰化再加on前缀因此update:model-value、close分别对应onUpdate:modelValue、onClose与 Vue 模板中update:model-value、close的绑定方式完全一致。优先与useForwardProps/useForwardPropsEmits组合如果封装场景同时需要透传 props直接使用useForwardPropsEmits一次完成两者还能获得布尔 props 可选化WithOptionalBooleans等额外的类型修正。总结useEmitAsProps用极简的实现解决了 Vue 组件封装中最繁琐的事件透传问题运行时通过camelizetoHandlerKey将每个声明的事件转换为onXxx处理器 props类型层面通过EmitAsProps及配套的重载合并工具提供完整的参数推断再结合useForwardPropsEmits即可一行代码同时完成 props 与事件的双向透传。无论是构建可复用的业务包装组件还是像 radix-vue 内部那样分层实现复杂 UI 组件它都是值得加入工具箱的高频工具。【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
radix-vue 组件封装利器 useEmitAsProps将 emits 一键转换为 props 事件处理器【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vueuseEmitAsProps是 radix-vue原 Radix Vue核心包提供的一个工具 composable用于把组件声明的emits事件集合自动转换为 Vue 组件可接受的onXxx形式的事件处理 props。本指南将围绕它的设计动机、源码实现、类型系统以及在仓库真实组件如 Drawer、DropdownMenu中的用法展开帮助你彻底解决“封装组件时逐个透传事件”的痛点写出更简洁、类型安全的包装组件。为什么需要 useEmitAsProps事件透传的痛点在使用 Vue 封装第三方组件即构建 wrapper时最大的麻烦之一就是事件的转发。假设你基于某个底层组件封装了一个高阶组件底层组件可能抛出update:modelValue、change、close等各类事件为了让上层使用者依然能监听这些事件你必须在模板里逐个手动编写template Comp update:model-value(v) emit(update:modelValue, v) change(v, extra) emit(change, v, extra) close(reason) emit(close, reason) / /template事件越多透传代码越冗长且很容易遗漏或写错事件名。Vue 核心本身并没有提供“事件透传”的内建机制可参考 vuejs/core#5917 中实现了useEmitAsProps它会读取你通过defineEmits声明的事件列表把每个事件转换为对应的onXxx处理器 props之后只需一次v-bind即可完成全部事件转发。基本用法声明 emits一行完成事件绑定根据官方文档 use-emit-as-props.md 的说明使用方式非常直观script setup langts import { useEmitAsProps } from reka-ui const emits defineEmitsCompEmitType() const emitsAsProps useEmitAsProps(emits) /script template Comp v-bindemitsAsProps ... /Comp /template核心逻辑就三步用defineEmitsCompEmitType()声明组件要透传的所有事件调用useEmitAsProps(emits)得到一个emitsAsProps对象其中每个事件名都被转换成了onXxx格式的处理器在模板中通过Comp v-bindemitsAsProps一次性把全部事件处理器传给底层组件。注意文档示例中的导入路径为reka-ui在当前仓库中该工具由核心包统一入口 packages/core/src/index.ts 通过export { type EmitAsProps, useEmitAsProps } from ./shared对外导出见 shared/index.ts实际安装后按你所使用的包名导入即可。源码剖析事件名到 onXxx 处理器的映射原理useEmitAsProps的实现非常精简其核心只有 20 余行见 useEmitAsProps.tsexport function useEmitAsPropsName extends string, Fn extends AnyFn AnyFn(emit: EmitName, Fn) { const vm getCurrentInstance() const events vm?.type.emits as Name[] const result: Recordstring, any {} if (!events?.length) { console.warn( No emitted event found. Please check component: ${vm?.type.__name}, ) } events?.forEach((ev) { result[toHandlerKey(camelize(ev))] (...arg: any) emit(ev, ...arg) }) return result as EmitAsPropsFn }逐行拆解其工作原理读取事件声明通过getCurrentInstance()拿到当前组件实例从vm.type.emits读取你在defineEmits中声明的事件名数组。Vue 会把defineEmits的声明挂载到组件的emits选项中因此这里能拿到完整的事件名列表。事件名驼峰化对每个事件名调用 Vue 的camelize把update:model-value、close这类写法统一转换为update:modelValue、close的驼峰形态。转换为处理器 key再调用 Vue 的toHandlerKey为驼峰事件名补上on前缀得到onUpdate:modelValue、onClose这样的 props 键名——这正是 Vue 子组件通过v-bind传递事件时使用的约定键名。闭包绑定 emit每个处理器内部执行emit(ev, ...arg)把收到的任意参数原样转发给事件名ev对应的 emit 调用。由于事件名在闭包中按项捕获即使底层组件同时触发多个不同事件也能各自正确路由。兜底警告如果组件没有声明任何 emits会通过console.warn输出No emitted event found. Please check component: 组件名提示开发者检查事件声明避免静默失败。类型层面的保证EmitAsProps 与重载事件推断useEmitAsProps的价值不止于运行时的事件映射它在 TypeScript 类型层面同样提供了完整的推断。函数返回类型EmitAsPropsFn见 useEmitAsProps.ts会根据 emit 函数的签名推导出每个事件对应的处理器 props 及其参数类型export type EmitAsPropsT extends AnyFn ExpandPartialMergeUnionEmitUnionOverloadUnionT类型链路上有多个关键环节HandlerKeyName在类型层面复刻了camelize与toHandlerKey的组合通过模板字面量类型把on-${Name}驼峰化例如update:modelValue会推导为onUpdate:modelValueEmitUnion将 emit 函数签名拆解为{ [K in HandlerKeyName]: (...args: Args) Return }的映射类型让每个事件都对应独立的处理器函数类型OverloadUnion/MergeUnion/Expand则用于合并 VuedefineEmits产生的重载签名把(e: update:modelValue, value: string) void、(e: change, value: number, extra: boolean) void等多个重载合并成一个同时包含onUpdate:modelValue与onChange的对象类型。这些类型断言并非空谈仓库提供了专门的编译期类型测试 useEmitAsProps.test-d.ts由vue-tsc在 type-check / build 阶段校验回归错误会直接导致构建失败。测试覆盖了三种典型场景// 重载 emit每个事件映射到其 onXxx 处理器 prop type _keys ExpectEqualkeyof Result, onUpdate:modelValue | onChange type _update ExpectEqualParametersNonNullableResult[onUpdate:modelValue], [value: string] type _change ExpectEqualParametersNonNullableResult[onChange], [value: number, extra: boolean] // 单一 emit type _keys ExpectEqualkeyof Result, onClose type _args ExpectEqualParametersNonNullableResult[onClose], [reason: string] // 宽松签名 (name: string, ...args: any[]) void 保持向后兼容 const result useEmitAsProps(looseEmit)这意味着在封装组件时不仅运行时会自动转发事件使用者通过change或:onChange监听时也能获得正确的参数类型提示实现“运行时 类型”双保险。配套组合技useForwardPropsEmits 一次转发 props 与 emits在实际封装中除了事件通常还需要透传 props。radix-vue 为此提供了useEmitAsProps的进阶版本useForwardPropsEmits见 useForwardPropsEmits.ts它内部同时调用useForwardProps解析并保留已赋值的 props与useEmitAsProps返回一个合并后的 computed 对象export function useForwardPropsEmitsT extends Recordstring, any( props: MaybeRefOrGetterT, emit?: EmitName, Fn, ) { const parsedProps useForwardProps(props) const emitsAsProps emit ? useEmitAsProps(emit) : {} return computed(() ({ ...parsedProps.value, ...emitsAsProps, })) }它的类型签名在传入 emit 时返回WithOptionalBooleansT EmitAsPropsFn即 props 与onXxx处理器同时被类型化不传 emit 时则只返回 props不会泄露多余的on*键这一行为同样在 useEmitAsProps.test-d.ts 中有断言。配套的useForwardProps位于 useForwardProps.ts会结合vm.type.props中的默认值与当前实例实际赋值的 props把未显式赋值的键剔除避免把未设置的值传给底层组件。仓库内的真实应用场景useEmitAsProps不是孤立的演示工具它在 radix-vue 的众多高阶组件中承担着事件透传的核心职责。以下两个例子展示了它在源码中的典型形态DropdownMenuItem 透传菜单事件见 DropdownMenuItem.vueconst emits defineEmitsDropdownMenuItemEmits() const emitsAsProps useEmitAsProps(emits)MenuItem v-bind{ ...props, ...emitsAsProps }DrawerContent 向底层实现组件透传关闭/交互事件见 DrawerContent.vue 与模板 L67-L94import { useEmitAsProps, useForwardExpose, useHideOthers } from /shared const props definePropsDrawerContentProps() const emits defineEmitsDrawerContentEmits() const rootContext injectDrawerRootContext() const emitsAsProps useEmitAsProps(emits)DrawerContentImpl v-ifisFullModal :refforwardRef v-bind{ ...props, ...emitsAsProps, ...$attrs } :trap-focusshouldTrapFocus :disable-outside-pointer-eventstrue 在 Drawer 的案例中DrawerContent与DrawerContentImpl之间隔着Presence进场/离场动画层事件无法通过组件树自动冒泡传递useEmitAsProps恰好解决了这种“跨层透传”的难题——外层把自身声明的emits如closeAutoFocus、interactOutside、pointerDownOutside等转换为 props通过v-bind传给内层实现组件。类似的使用还出现在 Dialog/DialogContent.vue、Menubar/MenubarItem.vue、ContextMenu/ContextMenuItem.vue、Toolbar/ToolbarToggleGroup.vue 等大量组件中是仓库内部“包装组件模式”的通用基础设施。使用要点与注意事项结合源码实现使用时有几点值得留意必须配合defineEmits使用useEmitAsProps依赖vm.type.emits读取事件声明因此传入的 emit 必须来自同组件的defineEmits如果组件没有声明任何事件控制台会输出警告返回对象为空。必须在组件 setup 作用域内调用实现依赖getCurrentInstance()在生命周期函数、事件回调或普通函数中调用会拿不到组件实例也就无法读取emits声明。事件名到 key 的转换规则事件名会先驼峰化再加on前缀因此update:model-value、close分别对应onUpdate:modelValue、onClose与 Vue 模板中update:model-value、close的绑定方式完全一致。优先与useForwardProps/useForwardPropsEmits组合如果封装场景同时需要透传 props直接使用useForwardPropsEmits一次完成两者还能获得布尔 props 可选化WithOptionalBooleans等额外的类型修正。总结useEmitAsProps用极简的实现解决了 Vue 组件封装中最繁琐的事件透传问题运行时通过camelizetoHandlerKey将每个声明的事件转换为onXxx处理器 props类型层面通过EmitAsProps及配套的重载合并工具提供完整的参数推断再结合useForwardPropsEmits即可一行代码同时完成 props 与事件的双向透传。无论是构建可复用的业务包装组件还是像 radix-vue 内部那样分层实现复杂 UI 组件它都是值得加入工具箱的高频工具。【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
