写一个“既能全量透传 Element Plus 所有 API又要塞进一套业务规则”的组件到底有多难受如果你也干过这件事那你大概率也踩过这几个坑属性透透传传着传着就把type丢了具名插槽在包了一层div之后无影无踪form 校验报错框错位排布TS 智能提示在二次封装后彻底失明。这篇文章就是我处理这些疑惑的实操记录包含完整代码示例和排查思路。如果你是刚接触 Vue3 Element Plus 二次封装的前端开发或者打算在公司内部沉淀一套业务组件库这些内容应该能帮你少走不少弯路。1. 二次封装到底在封什么先想清楚边界1.1 不要滥用“阉割式封装”我先说一个最常见的误区很多人做二次封装是把el-input拖进自己的组件里把用到的属性一个个defineProps写上然后模板里手动绑定。典型代码长这样script setup langts const props defineProps({ modelValue: String, clearable: Boolean, placeholder: String, disabled: Boolean, }); const emit defineEmits([update:modelValue]); /script template el-input :model-valuemodelValue :clearableclearable :placeholderplaceholder :disableddisabled update:model-valueemit(update:modelValue, $event) / /template这套写法的好处是直观坏处一样明显Element Plus 的el-input有几十个属性和事件每个都要手动抄一遍下游想用一个maxlength发现你没有透传那就只能干瞪眼。产品过来说“加个字数限制”你要么改公共组件要么让业务方绕开你总之维护成本爆炸。我个人的看法是除非你的封装目标本来就包含“屏蔽掉某些属性”的业务约束否则不建议做这种阉割式封装。真正要做的是把“不认识的属性和事件”全部透传下去同时把“自己认识的业务属性”挑出来处理。前端圈子常说的“包装组件”和“扩展组件”本质区别就在这里。1.2 三种常见的封装层次根据需求不同二次封装其实有三个层次每层的做法差别很大样式层封装不改组件逻辑只统一间距、圆角、主题色、整体视觉。操作上最轻用 CSS 变量或者全局覆盖类名就能实现不需要新组件一般直接用样式文件处理就够了。交互层封装给组件增加默认交互行为。比如封装一个“带清空确认”的el-select用户清空时先弹窗确认再触发更改。这种要把原组件事件拦截下来加工之后再对外抛事件。协议层封装把企业内部的字段命名、接口结构、校验规则和组件打通。比如封装一个FormItem组合组件内部根据接口返回的配置自动渲染控件这属于数据驱动的动态表单范畴。从“遇到疑惑”的角度来说大家最容易卡住的是第二个层次因为交互封装必然要动原组件的事件和数据流如果对 Vue3 的响应式原理和组件通信理解不透踩坑是难免的。下文我按实操路径来拆解。2. 透传机制把 attrs 丢给子组件之后我才发现自己对 inheritAttrs 的理解是错的2.1 非 prop 属性到底去哪了很多同学在 Vue2 时代习惯了$attrs到了 Vue3 也照样用但有个细节可能忽略了Vue3 的组件默认行为是组件根节点会自动继承没有声明为 props 的属性。也就是说如果我在自定义组件里写了一段script setup langts defineOptions({ name: MyInput }); defineProps({ modelValue: String }); /script template el-input :model-valuemodelValue / /template然后业务方使用my-input placeholder请输入昵称 /这个placeholder虽然没被声明成 prop但它默认会被加到组件根节点上。这里的根节点是谁如果模板只有一个根元素那根元素就是el-input本身于是placeholder会直接落到el-input上看起来“歪打正着”生效了。但一旦模板里出现了多个根节点或者最外层包了一个布局用的div情况就变了。Vue3 对多根组件不会自动继承 attrs此时placeholder会挂在外层div上但el-input并不认识它最终效果就是占位文案死活不出来。注意遇到这类问题时先不要急着怀疑 Element Plus打开 DevTools 看 DOM 属性到底挂在了哪个元素上比改十行代码都有用。解决方式也很简单用defineOptions把inheritAttrs关掉然后在真正需要接收属性的组件上手动挂一次template div classmy-input-wrapper el-input v-bind$attrs :model-valuemodelValue / /div /template这样所有非 prop 属性都会集中透传给el-input外层div只负责样式和布局不会被无关的属性污染。这是二次封装里最基础但也很关键的一步。2.2 v-bind 的合并顺序不是玄学把透传属性手动绑回去之后还有一个合并顺序问题。比如我在封装组件里写el-input v-bind$attrs classinner-input /业务方又传了classcustom-class最后哪个 class 生效答案是custom-class和inner-input会合并因为class和style这两个特殊属性在渲染时走的是合并逻辑不是替换逻辑。但type、maxlength这类普通属性后绑定的会覆盖前面。所以如果你在v-bind$attrs之后再额外写死某个属性比如el-input v-bind$attrs maxlength10 /当业务方传maxlength20时结果将是10生效。由于$attrs在前后面的静态绑定会把同名 key 覆盖掉。反过来如果你想强制某些参数不被业务覆盖那就把静态绑定放在$attrs之后这在做内部权限约束时是有意为之的做法。正常情况下我倾向于不写死这些可配置属性除非产品明确要求某个字段必须为公司统一值。2.3 Vue3 已经没有 listeners 这个概念了在 Vue2 里二次封装需要v-on$listeners才能把事件全部接住。换了 Vue3 之后很多人还习惯性地找$listeners但 Vue3 把它并进了$attrs所以事件监听器也会出现在$attrs里。这就是为什么要强调“透传 attrs 不只是传属性事件也一起传了”。例如focus事件一旦写成v-bind$attrs它自然会绑定到el-input上业务侧监听同样会触发。前提是inheritAttrs为 false并且没有更外层的组件中途把事件吃掉。这个机制理解后二次封装的透传思路就统一了不需要分别处理属性和事件全都交给$attrs只管额外处理的业务事件即可。顺便提一个容易出错的小细节如果外层组件里自定义了一个方法也叫 focus又透传了一个来自 $attrs 的 focus要小心作用域冲突。名字越通用越容易踩到这种雷。3. 插槽透传包一层 div 之后插槽为什么会“消失”3.1 默认插槽透传的写法组件封装里用户希望el-input的前缀图标、后缀按钮、前置内容都能继续用这就是插槽透传的需求。默认插槽很容易处理模板里写el-input v-bind$attrs template #default slot / /template /el-input但如果你忘记了slot /后果就是业务方在my-input里写的东西全部消失还不报错。排查这类“不报错但没效果”的问题最费时间建议先检查模板里有没有把插槽接住。3.2 具名插槽的动态透传别把 template 写死在模板里真正的坑在具名插槽。比如 Element Plus 的el-input提供prefix和suffix插槽我封装时希望外部调用方直接使用我组件的prefix插槽然后由我把内容“搬运”进el-input的prefix插槽。如果只是写死两个具名插槽也可以el-input v-bind$attrs template #prefix slot nameprefix / /template template #suffix slot namesuffix / /template /el-input这个方法在插槽数量少的时候没问题。但有些组件插槽贼多比如el-table-column这类一个一个写真的能写到怀疑人生。如果希望动态转发全部具名插槽需要用到动态插槽名el-input v-bind$attrs template v-for(_, name) in $slots #[name]slotProps slot :namename v-bindslotProps / /template /el-input这段代码的意思是遍历当前组件收到的所有插槽动态创建一个同名插槽并把作用域参数继续往下传。配合jsx也有类似的实现思路但模板语法这样写已经够用。这里要特别提醒动态插槽转发时作用域插槽的状态对象要原样透传不要在中间做解构否则内部组件拿到的值可能不是你期望的引用。举个例子假如el-select的options插槽会把当前选项对象传出来你在转发时多包了一层下游拿到的是你截断之后的字段就会造成取不到内部属性的问题。最佳做法是“拿什么就传什么”不在slotProps上做加工。3.3 “包 div 导致插槽消失”的真实原因很多人在封装时为了实现 tooltip 或 loading 效果会给组件外面再包一层。比如template el-tooltip :disabled!tooltip div classwrapper el-input v-bind$attrs template #prefix slot nameprefix / /template /el-input /div /el-tooltip /template如果这里没有处理插槽透传外部传入的前缀内容会照样出现在el-input里吗不会。因为你在封装组件内部只写了一个#prefix但你自己的组件并没有接收外部业务方的prefix插槽所以slot是空的。换句话说插槽是不会“穿透”中间层的每一层组件都收到一个插槽你必须显式把它继续下发否则内容就断在半路。这类问题我在实际项目里遇到过不止一次尤其是把多个业务字段封装成一个聚合组件时经常出现图标不显示、自定义节点不见了的情况。排查方法很简单打开 Vue DevTools检查组件树里插槽区域看看内容到底停在了哪一层。4. v-model 传递为什么二次封装后我组件的 v-model “偶发失效”4.1 modelValue 与 update:modelValue 的底层逻辑Element Plus 里的组件大部分都支持v-model落到 Vue3 上本质是两个东西modelValue属性和update:modelValue事件。你在封装组件里声明script setup langts const props defineProps({ modelValue: { type: [String, Number], default: }, }); const emit defineEmits([update:modelValue]); /script然后把el-input的model-value和update:model-value手动接上这样就能正常工作。但如果你用了defineModel()代码会简洁很多。Vue 3.4 开始defineModel()正式可用Element Plus 二次封装用它确实省事script setup langts const modelValue defineModelstring({ default: }); /script template el-input v-modelmodelValue / /template这里的v-modelmodelValue是原生的双向绑定不用手动前后抛。对于二次封装来说这是目前我比较推荐的写法前提是项目 Vue 版本在 3.4 及以上。项目如果还在用 3.3 或者更早版本老老实实写modelValueemit就行。4.2 多 v-model 绑定的处理方式有些组件支持多个v-model比如el-popover是visibleel-drawer是modelValue有些封装场景还会需要v-model:visible、v-model:keyword同时存在。Vue3 本身支持多个 v-model 绑定Element Plus 里也有不少这样的先例。二次封装时多 v-model 的处理和单 v-model 理论上一样每个都需要定义对应的 prop 和 update 事件script setup langts const visible defineModelboolean(visible, { default: false }); const keyword defineModelstring(keyword, { default: }); /script这里defineModel的第一个参数是 v-model 的 key最终外部使用方式就是v-model:visible和v-model:keyword。如果你仍然使用传统语法也完全可行const props defineProps({ visible: { type: Boolean, default: false }, keyword: { type: String, default: }, }); const emit defineEmits([update:visible, update:keyword]);两种写法的区别在于代码量和类型推导体验。我个人建议新项目直接用defineModel这个 API 出来就是服务这种场景的没必要绕远路。4.3 v-model 的值是“响应式代理”还是“原始值”还有一个很多人忽略的疑惑二次封装里父组件用v-model传给子组件的值在子组件里修改是否会直接改父组件的变量在 Vue3 里不会因为 v-model 的语义是propsemit子组件不应该直接修改 props。如果哪个同学在子组件里直接props.modelValue xxx或者在defineModel里对父组件的值做原地赋值控制台会给出警告严格模式下甚至直接报错。这里可以做一个类比props更像是一份“快递单”子组件只知道包裹会送到但快递单本身不能涂改你需要通过emit给快递公司发一个回执快递公司再重新生成一份正确的单子。defineModel之所以能让v-modelmodelValue看起来像直接赋值是因为它内部已经替你做了一次emit转发。理解这一点遇到“改一改不清醒、界面没刷新”的问题时你就知道先去检查是不是没有对外抛出事件而不是怀疑 Vue 的响应式坏了。5. 样式与类型细节这些文档不会细说但坑真的多5.1 样式覆盖为什么要用 :deep()Element Plus 的弹出层、下拉面板、日期选择面板这类内容很多是挂到 body 下的teleport 或 append-to-body 配置它们不在你组件内部 DOM 树里。用 scoped style 时组件根节点上会加上>style scoped .my-select-popper :deep(.el-select-dropdown__item) { font-size: 14px; } /style:deep()的作用是让选择器不再局限于当前组件作用域它最终会生成类似.my-select-popper[data-v-xxx] .el-select-dropdown__item的选择器只要最外层类名来自当前组件内部的 Element Plus DOM 即使没有>script setup langts defineProps({ modelValue: String, maxlength: Number, }); /script业务方使用my-input maxlength10 /时编辑器的类型提示只会提示maxlength是 number并不会联想到这是 Element Plus 的ElInput相关的 API更不会在输入clearable时给提示。封装的目的是让团队内使用更简单但类型体验反而退化这显然不理想。有两个改善方向使用extends类型把 Element Plus 组件的 props 类型继承过来。例如script setup langts import type { InputProps } from element-plus; definePropsPartialInputProps { customProp?: string }(); /script这样el-input支持的属性类型全部继承下来业务方使用时 TS 提示和原始组件基本一致。二选一的另一个做法是直接导出封装组件的实例类型让调用方在模板里也能获得类型提示但这件事做到位需要额外封装类型文件。如果你在做一个相对正式的组件库建议两种方式都考虑至少不能把组件封装成“类型黑洞”。5.3 组件 name 不设置会有什么隐蔽问题用script setup写组件时组件默认的 name 是推断出来的也就是文件名。如果你封装后想要配合keep-alive或者使用 DevTools 调试时看组件层级树name 是否有意义就很明显了。对于 Element Plus 二次封装name 还牵扯到一个具体场景el-form的校验机制依赖组件内部的prop而在某些表单校验错误跳转逻辑里组件的 name 会影响错误定位。我在封装业务表单控件时通常会这样设置script setup langts defineOptions({ name: BizInput, inheritAttrs: false, }); /scriptdefineOptions是 Vue 3.3 提供的编译宏专门用来替代原来的export default { name: ... }写法。二次封装组件时建议保留这个习惯一方面提升可维护性另一方面避免一些基于组件名做判断的逻辑失效。6. 我实际排查过的几个疑难问题6.1 问题一包了 el-form-item 后表单校验错误提示错位这是很多人在封装表单控件时遇到的头号问题。表现是你把el-input封装成BizInput然后在el-form-item里用el-form-item propusername biz-input v-modelform.username / /el-form-item页面正常但校验报错时红色提示文字的位置不对有时会挤到组件左侧有时直接消失。原因在于el-form-item做校验时是通过prop去查找关联的控件实例并给控件加错误提示样式。Element Plus 要求el-form-item的子组件能够正确暴露validate相关方法和validateState等上下文信息。如果你把el-input包在一个自定义组件里而自定义组件没有透传这些暴露项el-form-item就拿不到正确的控件信息错误提示自然跟着出错。针对这个问题的常规解决方案是内部直接使用el-input作为表单单元素同时继承el-form-item提供的上下文或者直接让自定义组件内部也包含el-form-item。但前者又回到“透传不干净”的尴尬局面所以我更推荐的做法是如果你封装的是“表单项组件”就把el-form-item直接集成进来对外暴露label、prop、rules等属性形成一个完整单元如果你封装的只是“输入控件”那就不要试图吞掉el-form-item保持表单结构的层级清晰。跟踪过这个问题之后我还发现一个细节Element Plus 的表单校验要求组件内部有validateMessage相关的渲染逻辑。如果二次封装时把el-input替换成了别的结构form-item的错误提示层可能不会停靠在预期位置。解决方法是增加一个错误文案插槽或者干脆用form-item自带槽位。6.2 问题二封装 Select 之后远程搜索的 loading 状态丢失业务场景是一个全局业务下拉框内部用el-select做远程搜索需要把 loading 状态显示在组件内部。我把el-select包进一个布局容器后发现图标不转了、下拉面板也能正常弹出来但 loading 效果消失。仔细排查后原因是el-select的loading属性和slot属性在透传过程中没有接住外层容器占住了default插槽的位置导致内部的下拉刷新的状态没有正确的传递位置。这个问题的排查路径和上一节的“插槽丢失”本质类似也给我提了个醒二次封装时凡是涉及到展示型状态的组件一定要先检查四类东西——props 是否透传、插槽是否透传、事件是否透传、类型是否能用。选型建议上如果远程搜索的请求逻辑在公司多个项目都要复用我会倾向于把请求逻辑放在封装组件内部而不是让每个业务重新实现一遍这样能大幅减少下游遗漏参数的可能。6.3 问题三回车键提交表单时事件触发了两次这个问题的表象是二次封装了一个BizInput页面里按下回车提交事件被触发了两次。在el-form里Element Plus 本身就会监听回车来触发提交如果你封装组件时又在里面额外监听了一个keyup.enter事件去 emit 给父组件父组件又在表单里绑定了submit两次提交就顺理成章出现了。事件的重复触发往往不是“某个库的 bug”而是自定义封装中多层监听的叠加。我的建议是封装组件时事件处理要做减法。如果底层已经提供了submit或者enter相关的合成事件那就不要在外层重复监听原生事件。这类问题在用 Native DOM 事件和组件 emit 混编时尤其常见。另外回车提交和中文输入法组合输入也有关系。如果你在封装搜索框时直接用keyup监听回车中文输入法下可能选字回车也会触发搜索导致搜索体验差。此时建议使用keyup.enter配合判断event.isComposing或者直接用compositionend事件来补偿判断逻辑。7. 这类封装还应该注意什么说说我沉淀出来的测试清单二次封装的内容并不复杂但牵涉的细节很多。踩过几轮坑之后我给自己整理了一个封装自测清单每次给团队交组件之前都会过一遍属性透传不认识的属性是否都挂到了实际组件上外层是否被多余 class/style 污染事件透传对外声明的事件都能触发吗是否出现重复触发插槽透传默认插槽和具名插槽都能显示吗作用域参数是否正确v-model双向绑定是否正常多 v-model 场景是否都能响应样式隔离scoped 样式是否被破坏弹层样式是否污染其他页面类型提示业务方写组件时是否还能获得比较完整的 TS 智能提示表单集成作为表单项使用时校验、错误提示、重置功能是否正常边界状态disabled、loading、clearable、autofocus 等常见状态是否仍然守约这套清单看着简单但每一条背后都是实际项目里出过问题的点。尤其是“插槽丢失”和“类型丢失”这两个问题往往不是一上来就能发现的等业务方接入后抱怨“怎么我的图标没出来”或者“编辑器不提示属性”时才会意识到封装的透传并不完整。二次封装最大的心智门槛不在于写多少代码而在于你是否理解 Vue3 的组件通信本质。属性、事件、插槽、类型这四个要素全部打通封装出来的组件才真的具备“像原生 Element Plus 一样好用”的底子。如果你正在为公司内部搭建业务组件库建议从小型表单控件开始尝试逐步积累遇到疑惑时优先研究透传逻辑绝大多数问题都能在这一步找到答案。
Vue3+Element Plus二次封装：透传、插槽与类型避坑指南
写一个“既能全量透传 Element Plus 所有 API又要塞进一套业务规则”的组件到底有多难受如果你也干过这件事那你大概率也踩过这几个坑属性透透传传着传着就把type丢了具名插槽在包了一层div之后无影无踪form 校验报错框错位排布TS 智能提示在二次封装后彻底失明。这篇文章就是我处理这些疑惑的实操记录包含完整代码示例和排查思路。如果你是刚接触 Vue3 Element Plus 二次封装的前端开发或者打算在公司内部沉淀一套业务组件库这些内容应该能帮你少走不少弯路。1. 二次封装到底在封什么先想清楚边界1.1 不要滥用“阉割式封装”我先说一个最常见的误区很多人做二次封装是把el-input拖进自己的组件里把用到的属性一个个defineProps写上然后模板里手动绑定。典型代码长这样script setup langts const props defineProps({ modelValue: String, clearable: Boolean, placeholder: String, disabled: Boolean, }); const emit defineEmits([update:modelValue]); /script template el-input :model-valuemodelValue :clearableclearable :placeholderplaceholder :disableddisabled update:model-valueemit(update:modelValue, $event) / /template这套写法的好处是直观坏处一样明显Element Plus 的el-input有几十个属性和事件每个都要手动抄一遍下游想用一个maxlength发现你没有透传那就只能干瞪眼。产品过来说“加个字数限制”你要么改公共组件要么让业务方绕开你总之维护成本爆炸。我个人的看法是除非你的封装目标本来就包含“屏蔽掉某些属性”的业务约束否则不建议做这种阉割式封装。真正要做的是把“不认识的属性和事件”全部透传下去同时把“自己认识的业务属性”挑出来处理。前端圈子常说的“包装组件”和“扩展组件”本质区别就在这里。1.2 三种常见的封装层次根据需求不同二次封装其实有三个层次每层的做法差别很大样式层封装不改组件逻辑只统一间距、圆角、主题色、整体视觉。操作上最轻用 CSS 变量或者全局覆盖类名就能实现不需要新组件一般直接用样式文件处理就够了。交互层封装给组件增加默认交互行为。比如封装一个“带清空确认”的el-select用户清空时先弹窗确认再触发更改。这种要把原组件事件拦截下来加工之后再对外抛事件。协议层封装把企业内部的字段命名、接口结构、校验规则和组件打通。比如封装一个FormItem组合组件内部根据接口返回的配置自动渲染控件这属于数据驱动的动态表单范畴。从“遇到疑惑”的角度来说大家最容易卡住的是第二个层次因为交互封装必然要动原组件的事件和数据流如果对 Vue3 的响应式原理和组件通信理解不透踩坑是难免的。下文我按实操路径来拆解。2. 透传机制把 attrs 丢给子组件之后我才发现自己对 inheritAttrs 的理解是错的2.1 非 prop 属性到底去哪了很多同学在 Vue2 时代习惯了$attrs到了 Vue3 也照样用但有个细节可能忽略了Vue3 的组件默认行为是组件根节点会自动继承没有声明为 props 的属性。也就是说如果我在自定义组件里写了一段script setup langts defineOptions({ name: MyInput }); defineProps({ modelValue: String }); /script template el-input :model-valuemodelValue / /template然后业务方使用my-input placeholder请输入昵称 /这个placeholder虽然没被声明成 prop但它默认会被加到组件根节点上。这里的根节点是谁如果模板只有一个根元素那根元素就是el-input本身于是placeholder会直接落到el-input上看起来“歪打正着”生效了。但一旦模板里出现了多个根节点或者最外层包了一个布局用的div情况就变了。Vue3 对多根组件不会自动继承 attrs此时placeholder会挂在外层div上但el-input并不认识它最终效果就是占位文案死活不出来。注意遇到这类问题时先不要急着怀疑 Element Plus打开 DevTools 看 DOM 属性到底挂在了哪个元素上比改十行代码都有用。解决方式也很简单用defineOptions把inheritAttrs关掉然后在真正需要接收属性的组件上手动挂一次template div classmy-input-wrapper el-input v-bind$attrs :model-valuemodelValue / /div /template这样所有非 prop 属性都会集中透传给el-input外层div只负责样式和布局不会被无关的属性污染。这是二次封装里最基础但也很关键的一步。2.2 v-bind 的合并顺序不是玄学把透传属性手动绑回去之后还有一个合并顺序问题。比如我在封装组件里写el-input v-bind$attrs classinner-input /业务方又传了classcustom-class最后哪个 class 生效答案是custom-class和inner-input会合并因为class和style这两个特殊属性在渲染时走的是合并逻辑不是替换逻辑。但type、maxlength这类普通属性后绑定的会覆盖前面。所以如果你在v-bind$attrs之后再额外写死某个属性比如el-input v-bind$attrs maxlength10 /当业务方传maxlength20时结果将是10生效。由于$attrs在前后面的静态绑定会把同名 key 覆盖掉。反过来如果你想强制某些参数不被业务覆盖那就把静态绑定放在$attrs之后这在做内部权限约束时是有意为之的做法。正常情况下我倾向于不写死这些可配置属性除非产品明确要求某个字段必须为公司统一值。2.3 Vue3 已经没有 listeners 这个概念了在 Vue2 里二次封装需要v-on$listeners才能把事件全部接住。换了 Vue3 之后很多人还习惯性地找$listeners但 Vue3 把它并进了$attrs所以事件监听器也会出现在$attrs里。这就是为什么要强调“透传 attrs 不只是传属性事件也一起传了”。例如focus事件一旦写成v-bind$attrs它自然会绑定到el-input上业务侧监听同样会触发。前提是inheritAttrs为 false并且没有更外层的组件中途把事件吃掉。这个机制理解后二次封装的透传思路就统一了不需要分别处理属性和事件全都交给$attrs只管额外处理的业务事件即可。顺便提一个容易出错的小细节如果外层组件里自定义了一个方法也叫 focus又透传了一个来自 $attrs 的 focus要小心作用域冲突。名字越通用越容易踩到这种雷。3. 插槽透传包一层 div 之后插槽为什么会“消失”3.1 默认插槽透传的写法组件封装里用户希望el-input的前缀图标、后缀按钮、前置内容都能继续用这就是插槽透传的需求。默认插槽很容易处理模板里写el-input v-bind$attrs template #default slot / /template /el-input但如果你忘记了slot /后果就是业务方在my-input里写的东西全部消失还不报错。排查这类“不报错但没效果”的问题最费时间建议先检查模板里有没有把插槽接住。3.2 具名插槽的动态透传别把 template 写死在模板里真正的坑在具名插槽。比如 Element Plus 的el-input提供prefix和suffix插槽我封装时希望外部调用方直接使用我组件的prefix插槽然后由我把内容“搬运”进el-input的prefix插槽。如果只是写死两个具名插槽也可以el-input v-bind$attrs template #prefix slot nameprefix / /template template #suffix slot namesuffix / /template /el-input这个方法在插槽数量少的时候没问题。但有些组件插槽贼多比如el-table-column这类一个一个写真的能写到怀疑人生。如果希望动态转发全部具名插槽需要用到动态插槽名el-input v-bind$attrs template v-for(_, name) in $slots #[name]slotProps slot :namename v-bindslotProps / /template /el-input这段代码的意思是遍历当前组件收到的所有插槽动态创建一个同名插槽并把作用域参数继续往下传。配合jsx也有类似的实现思路但模板语法这样写已经够用。这里要特别提醒动态插槽转发时作用域插槽的状态对象要原样透传不要在中间做解构否则内部组件拿到的值可能不是你期望的引用。举个例子假如el-select的options插槽会把当前选项对象传出来你在转发时多包了一层下游拿到的是你截断之后的字段就会造成取不到内部属性的问题。最佳做法是“拿什么就传什么”不在slotProps上做加工。3.3 “包 div 导致插槽消失”的真实原因很多人在封装时为了实现 tooltip 或 loading 效果会给组件外面再包一层。比如template el-tooltip :disabled!tooltip div classwrapper el-input v-bind$attrs template #prefix slot nameprefix / /template /el-input /div /el-tooltip /template如果这里没有处理插槽透传外部传入的前缀内容会照样出现在el-input里吗不会。因为你在封装组件内部只写了一个#prefix但你自己的组件并没有接收外部业务方的prefix插槽所以slot是空的。换句话说插槽是不会“穿透”中间层的每一层组件都收到一个插槽你必须显式把它继续下发否则内容就断在半路。这类问题我在实际项目里遇到过不止一次尤其是把多个业务字段封装成一个聚合组件时经常出现图标不显示、自定义节点不见了的情况。排查方法很简单打开 Vue DevTools检查组件树里插槽区域看看内容到底停在了哪一层。4. v-model 传递为什么二次封装后我组件的 v-model “偶发失效”4.1 modelValue 与 update:modelValue 的底层逻辑Element Plus 里的组件大部分都支持v-model落到 Vue3 上本质是两个东西modelValue属性和update:modelValue事件。你在封装组件里声明script setup langts const props defineProps({ modelValue: { type: [String, Number], default: }, }); const emit defineEmits([update:modelValue]); /script然后把el-input的model-value和update:model-value手动接上这样就能正常工作。但如果你用了defineModel()代码会简洁很多。Vue 3.4 开始defineModel()正式可用Element Plus 二次封装用它确实省事script setup langts const modelValue defineModelstring({ default: }); /script template el-input v-modelmodelValue / /template这里的v-modelmodelValue是原生的双向绑定不用手动前后抛。对于二次封装来说这是目前我比较推荐的写法前提是项目 Vue 版本在 3.4 及以上。项目如果还在用 3.3 或者更早版本老老实实写modelValueemit就行。4.2 多 v-model 绑定的处理方式有些组件支持多个v-model比如el-popover是visibleel-drawer是modelValue有些封装场景还会需要v-model:visible、v-model:keyword同时存在。Vue3 本身支持多个 v-model 绑定Element Plus 里也有不少这样的先例。二次封装时多 v-model 的处理和单 v-model 理论上一样每个都需要定义对应的 prop 和 update 事件script setup langts const visible defineModelboolean(visible, { default: false }); const keyword defineModelstring(keyword, { default: }); /script这里defineModel的第一个参数是 v-model 的 key最终外部使用方式就是v-model:visible和v-model:keyword。如果你仍然使用传统语法也完全可行const props defineProps({ visible: { type: Boolean, default: false }, keyword: { type: String, default: }, }); const emit defineEmits([update:visible, update:keyword]);两种写法的区别在于代码量和类型推导体验。我个人建议新项目直接用defineModel这个 API 出来就是服务这种场景的没必要绕远路。4.3 v-model 的值是“响应式代理”还是“原始值”还有一个很多人忽略的疑惑二次封装里父组件用v-model传给子组件的值在子组件里修改是否会直接改父组件的变量在 Vue3 里不会因为 v-model 的语义是propsemit子组件不应该直接修改 props。如果哪个同学在子组件里直接props.modelValue xxx或者在defineModel里对父组件的值做原地赋值控制台会给出警告严格模式下甚至直接报错。这里可以做一个类比props更像是一份“快递单”子组件只知道包裹会送到但快递单本身不能涂改你需要通过emit给快递公司发一个回执快递公司再重新生成一份正确的单子。defineModel之所以能让v-modelmodelValue看起来像直接赋值是因为它内部已经替你做了一次emit转发。理解这一点遇到“改一改不清醒、界面没刷新”的问题时你就知道先去检查是不是没有对外抛出事件而不是怀疑 Vue 的响应式坏了。5. 样式与类型细节这些文档不会细说但坑真的多5.1 样式覆盖为什么要用 :deep()Element Plus 的弹出层、下拉面板、日期选择面板这类内容很多是挂到 body 下的teleport 或 append-to-body 配置它们不在你组件内部 DOM 树里。用 scoped style 时组件根节点上会加上>style scoped .my-select-popper :deep(.el-select-dropdown__item) { font-size: 14px; } /style:deep()的作用是让选择器不再局限于当前组件作用域它最终会生成类似.my-select-popper[data-v-xxx] .el-select-dropdown__item的选择器只要最外层类名来自当前组件内部的 Element Plus DOM 即使没有>script setup langts defineProps({ modelValue: String, maxlength: Number, }); /script业务方使用my-input maxlength10 /时编辑器的类型提示只会提示maxlength是 number并不会联想到这是 Element Plus 的ElInput相关的 API更不会在输入clearable时给提示。封装的目的是让团队内使用更简单但类型体验反而退化这显然不理想。有两个改善方向使用extends类型把 Element Plus 组件的 props 类型继承过来。例如script setup langts import type { InputProps } from element-plus; definePropsPartialInputProps { customProp?: string }(); /script这样el-input支持的属性类型全部继承下来业务方使用时 TS 提示和原始组件基本一致。二选一的另一个做法是直接导出封装组件的实例类型让调用方在模板里也能获得类型提示但这件事做到位需要额外封装类型文件。如果你在做一个相对正式的组件库建议两种方式都考虑至少不能把组件封装成“类型黑洞”。5.3 组件 name 不设置会有什么隐蔽问题用script setup写组件时组件默认的 name 是推断出来的也就是文件名。如果你封装后想要配合keep-alive或者使用 DevTools 调试时看组件层级树name 是否有意义就很明显了。对于 Element Plus 二次封装name 还牵扯到一个具体场景el-form的校验机制依赖组件内部的prop而在某些表单校验错误跳转逻辑里组件的 name 会影响错误定位。我在封装业务表单控件时通常会这样设置script setup langts defineOptions({ name: BizInput, inheritAttrs: false, }); /scriptdefineOptions是 Vue 3.3 提供的编译宏专门用来替代原来的export default { name: ... }写法。二次封装组件时建议保留这个习惯一方面提升可维护性另一方面避免一些基于组件名做判断的逻辑失效。6. 我实际排查过的几个疑难问题6.1 问题一包了 el-form-item 后表单校验错误提示错位这是很多人在封装表单控件时遇到的头号问题。表现是你把el-input封装成BizInput然后在el-form-item里用el-form-item propusername biz-input v-modelform.username / /el-form-item页面正常但校验报错时红色提示文字的位置不对有时会挤到组件左侧有时直接消失。原因在于el-form-item做校验时是通过prop去查找关联的控件实例并给控件加错误提示样式。Element Plus 要求el-form-item的子组件能够正确暴露validate相关方法和validateState等上下文信息。如果你把el-input包在一个自定义组件里而自定义组件没有透传这些暴露项el-form-item就拿不到正确的控件信息错误提示自然跟着出错。针对这个问题的常规解决方案是内部直接使用el-input作为表单单元素同时继承el-form-item提供的上下文或者直接让自定义组件内部也包含el-form-item。但前者又回到“透传不干净”的尴尬局面所以我更推荐的做法是如果你封装的是“表单项组件”就把el-form-item直接集成进来对外暴露label、prop、rules等属性形成一个完整单元如果你封装的只是“输入控件”那就不要试图吞掉el-form-item保持表单结构的层级清晰。跟踪过这个问题之后我还发现一个细节Element Plus 的表单校验要求组件内部有validateMessage相关的渲染逻辑。如果二次封装时把el-input替换成了别的结构form-item的错误提示层可能不会停靠在预期位置。解决方法是增加一个错误文案插槽或者干脆用form-item自带槽位。6.2 问题二封装 Select 之后远程搜索的 loading 状态丢失业务场景是一个全局业务下拉框内部用el-select做远程搜索需要把 loading 状态显示在组件内部。我把el-select包进一个布局容器后发现图标不转了、下拉面板也能正常弹出来但 loading 效果消失。仔细排查后原因是el-select的loading属性和slot属性在透传过程中没有接住外层容器占住了default插槽的位置导致内部的下拉刷新的状态没有正确的传递位置。这个问题的排查路径和上一节的“插槽丢失”本质类似也给我提了个醒二次封装时凡是涉及到展示型状态的组件一定要先检查四类东西——props 是否透传、插槽是否透传、事件是否透传、类型是否能用。选型建议上如果远程搜索的请求逻辑在公司多个项目都要复用我会倾向于把请求逻辑放在封装组件内部而不是让每个业务重新实现一遍这样能大幅减少下游遗漏参数的可能。6.3 问题三回车键提交表单时事件触发了两次这个问题的表象是二次封装了一个BizInput页面里按下回车提交事件被触发了两次。在el-form里Element Plus 本身就会监听回车来触发提交如果你封装组件时又在里面额外监听了一个keyup.enter事件去 emit 给父组件父组件又在表单里绑定了submit两次提交就顺理成章出现了。事件的重复触发往往不是“某个库的 bug”而是自定义封装中多层监听的叠加。我的建议是封装组件时事件处理要做减法。如果底层已经提供了submit或者enter相关的合成事件那就不要在外层重复监听原生事件。这类问题在用 Native DOM 事件和组件 emit 混编时尤其常见。另外回车提交和中文输入法组合输入也有关系。如果你在封装搜索框时直接用keyup监听回车中文输入法下可能选字回车也会触发搜索导致搜索体验差。此时建议使用keyup.enter配合判断event.isComposing或者直接用compositionend事件来补偿判断逻辑。7. 这类封装还应该注意什么说说我沉淀出来的测试清单二次封装的内容并不复杂但牵涉的细节很多。踩过几轮坑之后我给自己整理了一个封装自测清单每次给团队交组件之前都会过一遍属性透传不认识的属性是否都挂到了实际组件上外层是否被多余 class/style 污染事件透传对外声明的事件都能触发吗是否出现重复触发插槽透传默认插槽和具名插槽都能显示吗作用域参数是否正确v-model双向绑定是否正常多 v-model 场景是否都能响应样式隔离scoped 样式是否被破坏弹层样式是否污染其他页面类型提示业务方写组件时是否还能获得比较完整的 TS 智能提示表单集成作为表单项使用时校验、错误提示、重置功能是否正常边界状态disabled、loading、clearable、autofocus 等常见状态是否仍然守约这套清单看着简单但每一条背后都是实际项目里出过问题的点。尤其是“插槽丢失”和“类型丢失”这两个问题往往不是一上来就能发现的等业务方接入后抱怨“怎么我的图标没出来”或者“编辑器不提示属性”时才会意识到封装的透传并不完整。二次封装最大的心智门槛不在于写多少代码而在于你是否理解 Vue3 的组件通信本质。属性、事件、插槽、类型这四个要素全部打通封装出来的组件才真的具备“像原生 Element Plus 一样好用”的底子。如果你正在为公司内部搭建业务组件库建议从小型表单控件开始尝试逐步积累遇到疑惑时优先研究透传逻辑绝大多数问题都能在这一步找到答案。
