尧图网页设计 
1. 先搞明白属性透传到底透传了什么做 Vue 开发的朋友应该都遇到过这样一个场景你封装了一个BaseInput组件里面只是一层简单的包装结果别人用的时候根本不管你定义了哪些 props直接往组件上塞class、style、placeholder、maxlength这些属性然后你发现它们居然都生效了。初次接触时会觉得这不科学啊我没声明的 props 怎么会自动跑到 DOM 上这个机制就是属性透传Attribute Inheritance官方叫法叫做 fallthrough attributes。1.1 透传是默认行为不是 BugVue 组件的实例本身有两个边界需要分清一个是组件对外声明的接口也就是 props另一个是组件根节点最终要渲染的 DOM。当你在父组件里给子组件传了一个子组件没有声明为 props 的属性Vue 不会报错也不会丢掉它而是把这个多出来的属性自动合并到子组件的根元素上去。这个行为是刻意设计的。它解决的实际问题是当我们封装包装型组件比如给原生 input 加一层 label 和错误提示时不需要把所有原生属性都声明成 props使用者仍然可以像用原生元素一样传属性。比如这段代码!-- BaseInput.vue -- template div classform-field label{{ label }}/label input / /div /template script setup defineProps([label]) /script父组件这样使用BaseInput label用户名 placeholder请输入用户名 maxlength10 /这里placeholder和maxlength在BaseInput里根本没有声明但最终渲染出来的 DOM 是这样div classform-field label用户名/label input placeholder请输入用户名 maxlength10 / /div也就是说placeholder和maxlength这两个属性自动落到了根节点div上而不是input上。注意这里有个隐蔽点根节点是个 div你期望的属性跑到 div 上去了很可能不是你要的效果。1.2 用 inheritAttrs 关掉它会发生什么当你设置inheritAttrs: false在 script setup 中是defineOptions({ inheritAttrs: false })之后组件根节点就不再自动继承这些多余属性了。但这些属性并没有消失它们全部被收编进了一个叫$attrs的对象里。$attrs里装的东西比你想的要多所有没被声明为 props 的属性class、style、id、dataset、ARIA 属性等都在这。而且注意一点事件监听器也会进$attrs。比如父组件给子组件绑定了click、focus如果子组件没有通过defineEmits声明click和focus那这两个监听器也在$attrs里。这就引出了官方文档里一句话的重点透传的属性在 JavaScript 中可以通过$attrs完全拿到在模板里可以借助v-bind$attrs手动绑定到指定元素。template div classform-field label{{ label }}/label input v-bind$attrs / /div /template script setup defineOptions({ inheritAttrs: false }) defineProps([label]) /script这样placeholder就会精确地绑定到input上而不是外围的div。这个做法在封装表单控件时几乎是标配。1.3 $attrs 里到底装了什么我直接用一段代码验证一下因为很多人对$attrs的边界理解是模糊的!-- TestAttrs.vue -- template div classwrapper pre{{ attrsInfo }}/pre /div /template script setup import { useAttrs } from vue const attrs useAttrs() const props defineProps([title]) const attrsInfo JSON.stringify(Object.keys(attrs), null, 2) /script父组件传入一堆东西TestAttrs title我是一个 prop idmain-box classouter-cls >template li第一项/li li第二项/li /template此时 Vue 根本无法猜测该把透传属性放到哪个根节点上所以它会直接抛一个警告Extraneous non-props attributes were passed to component but could not be automatically inherited。所有透传属性都堆在$attrs里需要你自己决定绑给谁template li v-bind$attrs第一项/li li第二项/li /template这里我踩过一次坑写一个 dropdown option 组件模板是 icon 加文本两个 span 作为根节点想着反正.active类名加上去哪个节点都行结果渲染出来 class 没生效控制台还飘着黄色警告。原因就是多根节点必须手动指定不能靠默认透传。老老实实加个v-bind$attrs就好了。2.2 层层传递时 attrs 的合并与覆盖场景升级一下你封装了BaseInput然后你同事又基于BaseInput封装了PhoneInputPhoneInput内部把$attrs重新绑到了BaseInput上。此时透传会有一层合并的行为。给你一个具体例子。BaseInput里这样写input classbase-input v-bind$attrs /外面这层PhoneInput这样写BaseInput classphone-input v-bind$attrs /父组件最终传一个classouter-input。结果不用惊讶最终渲染到 DOM 上的 class 是这三个的合并base-input phone-input outer-input。Vue 对class和style做的是合并而不是覆盖这是刻意的因为这两个属性的语义本来就是可叠加的。但对于普通属性比如id、title、disabled透传时遵循的是就近原则——最里层组件上的显式值覆盖外层透传值。这背后的规则值得记一下透传属性在每一层如果被v-bind$attrs展开都会和当前组件根节点上已有的同名属性做合并class/style合并普通属性取组件内显式绑定的值。如果你想让某个属性彻底不可被外部覆盖用defineProps把它声明成 prop 再内部控制而不是依赖透传规则。2.3 透传失败的常见排查路径我把自己遇到过的属性透传失效的场景汇总了一下按出现频率排序现象原因处理方式属性没落到期望的元素上根节点不是目标元素默认透传到根节点inheritAttrs: falsev-bind$attrs手动指定控制台警告 Extraneous non-props模板有多个根节点给其中一个根节点加v-bind$attrs事件监听器不生效事件被声明成了 emits导致监听器不再进入 $attrs要么去掉 emits 声明要么在组件内部重新 emit深层透传时部分属性被吞掉中间层组件使用 props 接收了部分属性没有继续转发确认中间层是否把$attrs继续向下传$attrs拿不到某个属性该属性已经被声明为 prop检查definePropsprop 不会进$attrs排查透传问题我个人的习惯是先在子组件里写一条临时的日志把useAttrs()打印出来看看对象里到底有什么。这一步能过滤掉 80% 的玄学问题。剩下 20% 通常是我以为传了但没传或者事件名大小写不一致打印一下父组件那边的v-bind参数就能发现。3. 自定义指令本质是面向 DOM 生命周期的钩子聊完透传再说自定义指令。如果你用过 Vue 内置的v-model、v-show、v-if其实已经接触过指令了。自定义指令就是让你把这些绑定在 DOM 上的逻辑抽出来复用。3.1 指令到底解决了什么问题指令解决的痛点是有一些逻辑既不属于组件的数据状态也不适合放在事件处理里它纯粹是针对 DOM 元素本身的操作——比如进入页面时让输入框自动聚焦、表格列头做拖拽排序、给外部链接自动加target_blank、检测用户复制时给文本追加版权信息。这些逻辑如果用组件去封装你会发现为了一个div级别的行为去建一个组件组件层级会变得很重如果用mounted生命周期去写每个用到的页面又都得重复一遍。指令把这类逻辑以具体元素为单位进行挂载和解绑函数签名一致、复用成本极低。和 mixin 相比指令更轻、语义更清晰不会污染组件的数据命名空间。3.2 指令钩子与组件生命周期的对应关系自定义指令的核心是一组钩子函数它们分别在元素生命的各个阶段被调用。每个钩子拿到的参数是(el, binding, vnode, prevVnode)但我平时真正高频使用的只有前两个而且binding里最有用的几个字段是value指令绑定的值比如v-copycontent里的contentarg指令参数比如v-copy:withPrefix里的withPrefixmodifiers修饰符对象比如v-copy.once里的{ once: true }instance当前组件实例做跨端判断会用到钩子触发时机和组件生命周期的对应关系大致是这样指令钩子触发时机对应组件生命周期created元素初始化属性还没绑定beforeMount 之前mounted元素插入 DOM 后mountedupdated元素所在组件 VNode 更新时updatedbeforeUnmount元素即将卸载beforeUnmountunmounted元素已卸载unmounted要注意的是指令钩子里的 DOM 操作必须考虑时机。比如想在mounted里去el.focus()这是没问题的因为元素已经在文档流里了。但如果你用的钩子是created此时元素还没挂载操作el的属性没问题但调用el.focus()会没效果。3.3 用指令实现水印从需求到完整代码拿一个特别贴近实际需求的例子来完整看一遍页面水印指令。这个需求在很多后台系统里都有——给内容区域加一个带用户 ID 的半透明水印文本防止敏感信息被截图外传。指令的实现思路是在元素上叠加一个绝对定位的水印层根据传入的参数控制水印内容、字号、间距、倾斜角度并且在组件卸载时自动移除。用指令来做的好处是业务组件里只需要写一行v-watermark{ text: 张三-2024-05-12 }不需要了解水印的 DOM 结构怎么搭。完整代码// watermark.js const defaultOptions { text: 内部资料, fontSize: 16, color: rgba(0, 0, 0, 0.08), rotate: -25, gap: 20, zIndex: 9999 } let watermarkMap new WeakMap() function createWatermarkLayer(el, options) { const merged { ...defaultOptions, ...options } // 用 canvas 量出文字尺寸动态铺满整个容器 const canvas document.createElement(canvas) const ctx canvas.getContext(2d) ctx.font ${merged.fontSize}px sans-serif const metrics ctx.measureText(merged.text) const textWidth metrics.width const cellWidth textWidth merged.gap * 2 const cellHeight merged.fontSize * 2 merged.gap * 2 canvas.width cellWidth canvas.height cellHeight const bgCtx canvas.getContext(2d) bgCtx.clearRect(0, 0, canvas.width, canvas.height) bgCtx.translate(cellWidth / 2, cellHeight / 2) bgCtx.rotate((merged.rotate * Math.PI) / 180) bgCtx.font ${merged.fontSize}px sans-serif bgCtx.fillStyle merged.color bgCtx.textAlign center bgCtx.textBaseline middle bgCtx.fillText(merged.text, 0, 0) const bgUrl canvas.toDataURL(image/png) // 创建水印层用 background-image 平铺 const layer document.createElement(div) layer.style.position absolute layer.style.inset 0 layer.style.pointerEvents none layer.style.backgroundImage url(${bgUrl}) layer.style.backgroundRepeat repeat layer.style.zIndex merged.zIndex layer.setAttribute(aria-hidden, true) el.style.position el.style.position static ? relative : el.style.position el.appendChild(layer) return layer } function removeWatermarkLayer(el) { const layer watermarkMap.get(el) if (layer layer.parentNode el) { el.removeChild(layer) } watermarkMap.delete(el) } export default { mounted(el, binding) { const layer createWatermarkLayer(el, binding.value || {}) watermarkMap.set(el, layer) }, updated(el, binding) { // 水印内容变了要重新生成 removeWatermarkLayer(el) const layer createWatermarkLayer(el, binding.value || {}) watermarkMap.set(el, layer) }, unmounted(el) { removeWatermarkLayer(el) } }这段代码里我特意用了WeakMap来保存元素到水印层的映射好处是如果元素被垃圾回收映射关系也会被自动清理不会内存泄漏。全局注册import { createApp } from vue import App from ./App.vue import watermark from ./directives/watermark const app createApp(App) app.directive(watermark, watermark) app.mount(#app)模板里直接使用template div v-watermark{ text: ${user.name}-${new Date().toLocaleDateString()} } classcontent 这里是需要加保护的业务内容 /div /template指令的updated钩子里做了重新渲染逻辑意味着如果用户 ID 变了或者日期变了水印会自动刷新。这个场景实战下来很稳唯一要注意的是水印层设置的是position: absolute如果容器自身没有定位我在代码里帮你兜底改成了 relative。但如果容器有transform或者filter属性absolute定位会以最近的 transformed 祖先为基准水印可能偏离。这种情况建议直接改用position: fixed或者干脆在body上挂一个全屏水印。4. 指令参数、修饰符与动态指令进阶用法水印算是指令的典型单点应用但要把指令用出彩参数、修饰符、动态指令值和批量注册这套机制得熟悉。4.1 参数和修饰符的取值逻辑我用一个v-copy指令来演示参数和修饰符的配合。需求是点击按钮复制指定文本到剪贴板复制成功后 toast 提示且某些场景需要复制带前缀文本的拼接结果。// copy.js import { ElMessage } from element-plus async function handleCopy(el, binding) { const { value, arg, modifiers } binding let textToCopy value // 参数 v-copy:prefix 拼接前缀修饰符 .trim 则去空格 if (arg prefix) { textToCopy 【来源】${value} } if (modifiers.trim) { textToCopy String(textToCopy).trim() } try { await navigator.clipboard.writeText(textToCopy) ElMessage.success(复制成功) } catch (err) { // 兼容旧浏览器降级到 document.execCommand const textarea document.createElement(textarea) textarea.value textToCopy textarea.style.position fixed textarea.style.opacity 0 document.body.appendChild(textarea) textarea.select() document.execCommand(copy) document.body.removeChild(textarea) ElMessage.success(复制成功降级方案) } } export default { mounted(el, binding) { el.__copyHandler__ () handleCopy(el, binding) el.addEventListener(click, el.__copyHandler__) }, updated(el, binding) { // 重新挂载事件时移除旧处理函数防止事件重复绑定 el.removeEventListener(click, el.__copyHandler__) el.__copyHandler__ () handleCopy(el, binding) el.addEventListener(click, el.__copyHandler__) }, unmounted(el) { el.removeEventListener(click, el.__copyHandler__) } }使用方式button v-copy.trim:prefixorderNo复制订单号/buttonbinding.arg拿到的就是prefixmodifiers是{ trim: true }。有一个容易忽略的点updated钩子里如果binding.value变了而你没有重新绑定事件指令内部闭包捕获的 value 还是旧值。所以凡是事件型指令一定记得在updated里解绑并重新绑定否则你的指令大概率会在列表渲染场景中复制到旧数据。4.2 动态指令名与批量注册Vue 还支持动态指令参数比如v-copy:[arg]value这个[arg]可以是响应式数据。这个能力用得好能写出非常灵活的指令比如一个v-permission:[action]的权限指令action从组件数据里动态取指令内部根据参数判断当前用户是否有该权限没有就直接移除元素button v-permission:editorder_edit编辑订单/button button v-permission:deleteorder_delete删除订单/button另外建议把项目里所有自定义指令统一放一个目录集中管理再通过一个directives/index.js注册// directives/index.js import watermark from ./watermark import copy from ./copy import debounce from ./debounce import permission from ./permission const directives { watermark, copy, debounce, permission } export default { install(app) { Object.keys(directives).forEach((name) { app.directive(name, directives[name]) }) } }主入口import directives from ./directives app.use(directives)这样做到后期指令数量上来了维护成本也不会失控。我见过有人把指令定义直接塞在主入口文件里写三五个还行写到十几个时那段代码已经没法看了。4.3 指令的边界什么时候不该用指令指令虽好但不能滥用。我自己踩过一个反面案例有一版需求是想让某个按钮在短时间内防止重复点击我直接写了一个v-once-click指令结果后来产品改需求要求不同按钮防重复点击的间隔不一样甚至有的按钮要允许滑动验证通过后再放开。指令里加这些业务判断越来越复杂最后不得不整块重构。教训就是指令适合承载可复用的 DOM 行为不适合承载和业务状态强耦合的规则。判断标准很简单如果这个行为在被多个页面以完全相同的方式复用且不需要感知具体的业务状态那就适合做成指令如果它需要根据不同的业务场景走完全不同的分支逻辑那应该写到组件内部或者用 composable 封装而不是硬塞进指令。比如防抖指令就非常合适它纯粹是延迟执行的机制问题不关心函数内部是什么业务// debounce.js export default { mounted(el, binding) { const { value, arg } binding const delay arg ? Number(arg) : 300 const fn value let timer null el.__debounceHandler__ function (event) { if (timer) clearTimeout(timer) timer setTimeout(() { fn.call(this, event) }, delay) } el.addEventListener(click, el.__debounceHandler__) }, unmounted(el) { el.removeEventListener(click, el.__debounceHandler__) } }这种就没有任何业务侵入放哪个项目都能用。5. 透传与指令联合作战一个表单场景完整拆解单独聊完透传和自定义指令最后用一个真实场景把它们串起来。这个场景就是我上一份工作里做的增强版表单输入框需要支持原生 input 的所有属性、自动聚焦、带字符长度统计而且焦点状态下要触发外部埋点。5.1 需求拆解表单里要渲染一个二次封装的输入框组件SmartInput它需要透传所有原生 input 属性让使用方不需要感知组件内部结构。页面加载后自动聚焦到第一个SmartInput上。输入内容时实时显示剩余可输入字符数。每次聚焦时上报埋点事件。如果用常规思路第 2 条会在组件里写一个autofocusprop第 4 条会再写一个focus事件的 emit然后每个用到的页面都手动绑定。这样的问题在于职责全堆在组件内部组件会越来越胖。5.2 用透传接管属性用指令接管行为最终的实现方案属性透传负责长得像原生 input自定义指令负责聚焦和埋点这些横切行为。SmartInput组件关键部分template div classsmart-input input classsmart-input__field v-bind$attrs :valuemodelValue inputhandleInput refinputRef / span classsmart-input__counter v-ifmaxlength {{ remainCount }} / {{ maxlength }} /span /div /template script setup import { computed, ref, useAttrs } from vue const attrs useAttrs() const props defineProps({ modelValue: { type: [String, Number], default: }, maxlength: { type: Number, default: undefined } }) const emit defineEmits([update:modelValue]) const inputRef ref(null) const remainCount computed(() { if (!props.maxlength) return 0 return props.maxlength - String(props.modelValue).length }) // 这里故意不吞掉 input 事件声明 emit 后input 就不再出现在 $attrs 里了 function handleInput(event) { emit(update:modelValue, event.target.value) } /script注意我用了useAttrs()拿属性但模板里用的是v-bind$attrs这两个可以并存useAttrs()通常用来在 JavaScript 里对某些属性做二次处理。然后在组件外层申请两个指令v-focus和v-track。// focus.js自动聚焦支持 .delay 修饰符延迟聚焦 export default { mounted(el, binding) { const input el.querySelector(input) || el if (binding.modifiers.delay) { setTimeout(() input.focus(), 800) } else { input.focus() } } }// track.js上报自定义事件 export default { mounted(el, binding) { el.__trackFocusHandler__ () { const { value } binding // value 可以是函数或事件名这里简单处理成函数 if (typeof value function) { value() } } el.addEventListener(focusin, el.__trackFocusHandler__) }, unmounted(el) { el.removeEventListener(focusin, el.__trackFocusHandler__) } }页面里的使用方式template SmartInput v-modelform.name v-focus.delay v-tracktrackReport placeholder请输入姓名 maxlength20 / /template script setup import { SmartInput } from /components import { vFocus, vTrack } from /directives const trackReport () { console.log(埋点聚焦了姓名输入框) } const form reactive({ name: }) /script5.3 这个方案好在哪里坑在哪里这个组合的好处是SmartInput内部不需要知道自动聚焦和埋点的存在这两个能力是通过指令注入的。未来如果产品说只有首页需要自动聚焦其他页面不要直接删掉那一行v-focus就行组件零改动。但这里也踩到过一个隐蔽的坑v-track侦听的是focusin而不是focus。原因很简单我需要在事件回调里通过el.querySelector找到内部的 input而focusin在 Vue 里是原生事件且可以冒泡只要SmartInput外壳 div 收到冒泡就能捕获到。如果用focus它本身不冒泡绑定在 div 上根本不会触发。这也是为什么组件里的聚焦埋点事件往往用focusin而blur对应地用focusout。另外一个经验是当指令和透传碰撞时事件处理顺序要留意。v-track绑定的是外层 div而SmartInput内部可能还有自己的focus处理两者都会触发但各自职责不同一个做业务上报一个做组件内部逻辑。如果你发现某个焦点事件被触发了两次多半是你既在$attrs里接收了外部绑定的 focus 监听器又在指令里绑定了focusin两边都响应了。处理方式是在指令里加一个判断看元素上是否已有同名监听器或者干脆统一约定埋点全部走指令事件透传只留给真正的业务响应。5.4 实测下来的几条心得第一个心得透传属性和指令结合时绑定目标元素的优先级要明确。我的习惯是组件最外层 DOM 负责承载class/style这类布局属性内部真正参与交互的元素比如 input负责承载placeholder、disabled、maxlength这类行为属性。这样视觉上的样式控制由外层承接语义上的行为控制由内层承接两者不打架。第二个心得指令里的 DOM 查询不要只写一层。el.querySelector(input)在大多数场景够用但如果模板嵌套再深一层input 外包了一个 span 再包一个 div建议给目标元素加一个固定 class 比如.smart-input__field指令里用el.querySelector(.smart-input__field)查询而不是直接el.querySelector(input)。别问我为什么知道问就是被第三方 UI 库的 DOM 结构调整坑过。第三个心得如果指令需要传递的参数较多——对象、函数、修饰符、动态参数都要兼顾——不要全塞在binding.value里靠魔法数解决直接约定一个对象字段名写清楚。比如v-watermark{ text, fontSize, rotate }这种比v-watermarktext|16|-25这种字符串拼接方案要可维护得多。我后来看老项目的代码那种靠字符串拼接传参数的指令读起来真的费劲。6. 最后再分享一个调试透传和指令的小技巧写到最后分享一个能显著提升排查效率的习惯在封装通用组件时给透传属性留一个观察后门。具体做法是在开发模式下如果useAttrs()返回的$attrs里有你意料之外的属性直接console.warn打印出来而不是默默接受。很多透传问题的根源是使用方传了拼写错误的属性名比如把maxlength写成了maxLength把placeholder写成了placeholer这类问题如果不显式提示排查起来非常痛苦。加一行开发期警告能省下大量沟通时间script setup import { useAttrs } from vue import { devtools } from /utils/devtools const attrs useAttrs() if (import.meta.env.DEV) { // 这里定义一下允许透传的已知属性白名单 const allowedKeys [class, style, placeholder, maxlength, disabled, id] const extraKeys Object.keys(attrs).filter((key) !allowedKeys.includes(key)) if (extraKeys.length 0) { console.warn([SmartInput] 检测到未预期的透传属性: ${extraKeys.join(, )}) } } /script这个思路同样适用于自定义指令指令的mounted钩子里可以校验binding.value的类型传错了直接报错而不是在运行时悄悄崩溃。自定义指令本来就是约定大于配置的东西把约束做在前面后面不管过多久都还有人记得这些约定。属性透传和自定义指令单独看都是 Vue 里偏基础的知识点但结合起来能在组件封装层面解决一大批组件越来越重的问题。我的经验是能用指令解决的横切关注点不要写进业务组件能用透传解决的属性分发不要定义成 props。把握好这两条原则组件库的代码会清爽很多。 Vue 3属性透传与自定义指令：组件封装的进阶实践
1. 先搞明白属性透传到底透传了什么做 Vue 开发的朋友应该都遇到过这样一个场景你封装了一个BaseInput组件里面只是一层简单的包装结果别人用的时候根本不管你定义了哪些 props直接往组件上塞class、style、placeholder、maxlength这些属性然后你发现它们居然都生效了。初次接触时会觉得这不科学啊我没声明的 props 怎么会自动跑到 DOM 上这个机制就是属性透传Attribute Inheritance官方叫法叫做 fallthrough attributes。1.1 透传是默认行为不是 BugVue 组件的实例本身有两个边界需要分清一个是组件对外声明的接口也就是 props另一个是组件根节点最终要渲染的 DOM。当你在父组件里给子组件传了一个子组件没有声明为 props 的属性Vue 不会报错也不会丢掉它而是把这个多出来的属性自动合并到子组件的根元素上去。这个行为是刻意设计的。它解决的实际问题是当我们封装包装型组件比如给原生 input 加一层 label 和错误提示时不需要把所有原生属性都声明成 props使用者仍然可以像用原生元素一样传属性。比如这段代码!-- BaseInput.vue -- template div classform-field label{{ label }}/label input / /div /template script setup defineProps([label]) /script父组件这样使用BaseInput label用户名 placeholder请输入用户名 maxlength10 /这里placeholder和maxlength在BaseInput里根本没有声明但最终渲染出来的 DOM 是这样div classform-field label用户名/label input placeholder请输入用户名 maxlength10 / /div也就是说placeholder和maxlength这两个属性自动落到了根节点div上而不是input上。注意这里有个隐蔽点根节点是个 div你期望的属性跑到 div 上去了很可能不是你要的效果。1.2 用 inheritAttrs 关掉它会发生什么当你设置inheritAttrs: false在 script setup 中是defineOptions({ inheritAttrs: false })之后组件根节点就不再自动继承这些多余属性了。但这些属性并没有消失它们全部被收编进了一个叫$attrs的对象里。$attrs里装的东西比你想的要多所有没被声明为 props 的属性class、style、id、dataset、ARIA 属性等都在这。而且注意一点事件监听器也会进$attrs。比如父组件给子组件绑定了click、focus如果子组件没有通过defineEmits声明click和focus那这两个监听器也在$attrs里。这就引出了官方文档里一句话的重点透传的属性在 JavaScript 中可以通过$attrs完全拿到在模板里可以借助v-bind$attrs手动绑定到指定元素。template div classform-field label{{ label }}/label input v-bind$attrs / /div /template script setup defineOptions({ inheritAttrs: false }) defineProps([label]) /script这样placeholder就会精确地绑定到input上而不是外围的div。这个做法在封装表单控件时几乎是标配。1.3 $attrs 里到底装了什么我直接用一段代码验证一下因为很多人对$attrs的边界理解是模糊的!-- TestAttrs.vue -- template div classwrapper pre{{ attrsInfo }}/pre /div /template script setup import { useAttrs } from vue const attrs useAttrs() const props defineProps([title]) const attrsInfo JSON.stringify(Object.keys(attrs), null, 2) /script父组件传入一堆东西TestAttrs title我是一个 prop idmain-box classouter-cls >template li第一项/li li第二项/li /template此时 Vue 根本无法猜测该把透传属性放到哪个根节点上所以它会直接抛一个警告Extraneous non-props attributes were passed to component but could not be automatically inherited。所有透传属性都堆在$attrs里需要你自己决定绑给谁template li v-bind$attrs第一项/li li第二项/li /template这里我踩过一次坑写一个 dropdown option 组件模板是 icon 加文本两个 span 作为根节点想着反正.active类名加上去哪个节点都行结果渲染出来 class 没生效控制台还飘着黄色警告。原因就是多根节点必须手动指定不能靠默认透传。老老实实加个v-bind$attrs就好了。2.2 层层传递时 attrs 的合并与覆盖场景升级一下你封装了BaseInput然后你同事又基于BaseInput封装了PhoneInputPhoneInput内部把$attrs重新绑到了BaseInput上。此时透传会有一层合并的行为。给你一个具体例子。BaseInput里这样写input classbase-input v-bind$attrs /外面这层PhoneInput这样写BaseInput classphone-input v-bind$attrs /父组件最终传一个classouter-input。结果不用惊讶最终渲染到 DOM 上的 class 是这三个的合并base-input phone-input outer-input。Vue 对class和style做的是合并而不是覆盖这是刻意的因为这两个属性的语义本来就是可叠加的。但对于普通属性比如id、title、disabled透传时遵循的是就近原则——最里层组件上的显式值覆盖外层透传值。这背后的规则值得记一下透传属性在每一层如果被v-bind$attrs展开都会和当前组件根节点上已有的同名属性做合并class/style合并普通属性取组件内显式绑定的值。如果你想让某个属性彻底不可被外部覆盖用defineProps把它声明成 prop 再内部控制而不是依赖透传规则。2.3 透传失败的常见排查路径我把自己遇到过的属性透传失效的场景汇总了一下按出现频率排序现象原因处理方式属性没落到期望的元素上根节点不是目标元素默认透传到根节点inheritAttrs: falsev-bind$attrs手动指定控制台警告 Extraneous non-props模板有多个根节点给其中一个根节点加v-bind$attrs事件监听器不生效事件被声明成了 emits导致监听器不再进入 $attrs要么去掉 emits 声明要么在组件内部重新 emit深层透传时部分属性被吞掉中间层组件使用 props 接收了部分属性没有继续转发确认中间层是否把$attrs继续向下传$attrs拿不到某个属性该属性已经被声明为 prop检查definePropsprop 不会进$attrs排查透传问题我个人的习惯是先在子组件里写一条临时的日志把useAttrs()打印出来看看对象里到底有什么。这一步能过滤掉 80% 的玄学问题。剩下 20% 通常是我以为传了但没传或者事件名大小写不一致打印一下父组件那边的v-bind参数就能发现。3. 自定义指令本质是面向 DOM 生命周期的钩子聊完透传再说自定义指令。如果你用过 Vue 内置的v-model、v-show、v-if其实已经接触过指令了。自定义指令就是让你把这些绑定在 DOM 上的逻辑抽出来复用。3.1 指令到底解决了什么问题指令解决的痛点是有一些逻辑既不属于组件的数据状态也不适合放在事件处理里它纯粹是针对 DOM 元素本身的操作——比如进入页面时让输入框自动聚焦、表格列头做拖拽排序、给外部链接自动加target_blank、检测用户复制时给文本追加版权信息。这些逻辑如果用组件去封装你会发现为了一个div级别的行为去建一个组件组件层级会变得很重如果用mounted生命周期去写每个用到的页面又都得重复一遍。指令把这类逻辑以具体元素为单位进行挂载和解绑函数签名一致、复用成本极低。和 mixin 相比指令更轻、语义更清晰不会污染组件的数据命名空间。3.2 指令钩子与组件生命周期的对应关系自定义指令的核心是一组钩子函数它们分别在元素生命的各个阶段被调用。每个钩子拿到的参数是(el, binding, vnode, prevVnode)但我平时真正高频使用的只有前两个而且binding里最有用的几个字段是value指令绑定的值比如v-copycontent里的contentarg指令参数比如v-copy:withPrefix里的withPrefixmodifiers修饰符对象比如v-copy.once里的{ once: true }instance当前组件实例做跨端判断会用到钩子触发时机和组件生命周期的对应关系大致是这样指令钩子触发时机对应组件生命周期created元素初始化属性还没绑定beforeMount 之前mounted元素插入 DOM 后mountedupdated元素所在组件 VNode 更新时updatedbeforeUnmount元素即将卸载beforeUnmountunmounted元素已卸载unmounted要注意的是指令钩子里的 DOM 操作必须考虑时机。比如想在mounted里去el.focus()这是没问题的因为元素已经在文档流里了。但如果你用的钩子是created此时元素还没挂载操作el的属性没问题但调用el.focus()会没效果。3.3 用指令实现水印从需求到完整代码拿一个特别贴近实际需求的例子来完整看一遍页面水印指令。这个需求在很多后台系统里都有——给内容区域加一个带用户 ID 的半透明水印文本防止敏感信息被截图外传。指令的实现思路是在元素上叠加一个绝对定位的水印层根据传入的参数控制水印内容、字号、间距、倾斜角度并且在组件卸载时自动移除。用指令来做的好处是业务组件里只需要写一行v-watermark{ text: 张三-2024-05-12 }不需要了解水印的 DOM 结构怎么搭。完整代码// watermark.js const defaultOptions { text: 内部资料, fontSize: 16, color: rgba(0, 0, 0, 0.08), rotate: -25, gap: 20, zIndex: 9999 } let watermarkMap new WeakMap() function createWatermarkLayer(el, options) { const merged { ...defaultOptions, ...options } // 用 canvas 量出文字尺寸动态铺满整个容器 const canvas document.createElement(canvas) const ctx canvas.getContext(2d) ctx.font ${merged.fontSize}px sans-serif const metrics ctx.measureText(merged.text) const textWidth metrics.width const cellWidth textWidth merged.gap * 2 const cellHeight merged.fontSize * 2 merged.gap * 2 canvas.width cellWidth canvas.height cellHeight const bgCtx canvas.getContext(2d) bgCtx.clearRect(0, 0, canvas.width, canvas.height) bgCtx.translate(cellWidth / 2, cellHeight / 2) bgCtx.rotate((merged.rotate * Math.PI) / 180) bgCtx.font ${merged.fontSize}px sans-serif bgCtx.fillStyle merged.color bgCtx.textAlign center bgCtx.textBaseline middle bgCtx.fillText(merged.text, 0, 0) const bgUrl canvas.toDataURL(image/png) // 创建水印层用 background-image 平铺 const layer document.createElement(div) layer.style.position absolute layer.style.inset 0 layer.style.pointerEvents none layer.style.backgroundImage url(${bgUrl}) layer.style.backgroundRepeat repeat layer.style.zIndex merged.zIndex layer.setAttribute(aria-hidden, true) el.style.position el.style.position static ? relative : el.style.position el.appendChild(layer) return layer } function removeWatermarkLayer(el) { const layer watermarkMap.get(el) if (layer layer.parentNode el) { el.removeChild(layer) } watermarkMap.delete(el) } export default { mounted(el, binding) { const layer createWatermarkLayer(el, binding.value || {}) watermarkMap.set(el, layer) }, updated(el, binding) { // 水印内容变了要重新生成 removeWatermarkLayer(el) const layer createWatermarkLayer(el, binding.value || {}) watermarkMap.set(el, layer) }, unmounted(el) { removeWatermarkLayer(el) } }这段代码里我特意用了WeakMap来保存元素到水印层的映射好处是如果元素被垃圾回收映射关系也会被自动清理不会内存泄漏。全局注册import { createApp } from vue import App from ./App.vue import watermark from ./directives/watermark const app createApp(App) app.directive(watermark, watermark) app.mount(#app)模板里直接使用template div v-watermark{ text: ${user.name}-${new Date().toLocaleDateString()} } classcontent 这里是需要加保护的业务内容 /div /template指令的updated钩子里做了重新渲染逻辑意味着如果用户 ID 变了或者日期变了水印会自动刷新。这个场景实战下来很稳唯一要注意的是水印层设置的是position: absolute如果容器自身没有定位我在代码里帮你兜底改成了 relative。但如果容器有transform或者filter属性absolute定位会以最近的 transformed 祖先为基准水印可能偏离。这种情况建议直接改用position: fixed或者干脆在body上挂一个全屏水印。4. 指令参数、修饰符与动态指令进阶用法水印算是指令的典型单点应用但要把指令用出彩参数、修饰符、动态指令值和批量注册这套机制得熟悉。4.1 参数和修饰符的取值逻辑我用一个v-copy指令来演示参数和修饰符的配合。需求是点击按钮复制指定文本到剪贴板复制成功后 toast 提示且某些场景需要复制带前缀文本的拼接结果。// copy.js import { ElMessage } from element-plus async function handleCopy(el, binding) { const { value, arg, modifiers } binding let textToCopy value // 参数 v-copy:prefix 拼接前缀修饰符 .trim 则去空格 if (arg prefix) { textToCopy 【来源】${value} } if (modifiers.trim) { textToCopy String(textToCopy).trim() } try { await navigator.clipboard.writeText(textToCopy) ElMessage.success(复制成功) } catch (err) { // 兼容旧浏览器降级到 document.execCommand const textarea document.createElement(textarea) textarea.value textToCopy textarea.style.position fixed textarea.style.opacity 0 document.body.appendChild(textarea) textarea.select() document.execCommand(copy) document.body.removeChild(textarea) ElMessage.success(复制成功降级方案) } } export default { mounted(el, binding) { el.__copyHandler__ () handleCopy(el, binding) el.addEventListener(click, el.__copyHandler__) }, updated(el, binding) { // 重新挂载事件时移除旧处理函数防止事件重复绑定 el.removeEventListener(click, el.__copyHandler__) el.__copyHandler__ () handleCopy(el, binding) el.addEventListener(click, el.__copyHandler__) }, unmounted(el) { el.removeEventListener(click, el.__copyHandler__) } }使用方式button v-copy.trim:prefixorderNo复制订单号/buttonbinding.arg拿到的就是prefixmodifiers是{ trim: true }。有一个容易忽略的点updated钩子里如果binding.value变了而你没有重新绑定事件指令内部闭包捕获的 value 还是旧值。所以凡是事件型指令一定记得在updated里解绑并重新绑定否则你的指令大概率会在列表渲染场景中复制到旧数据。4.2 动态指令名与批量注册Vue 还支持动态指令参数比如v-copy:[arg]value这个[arg]可以是响应式数据。这个能力用得好能写出非常灵活的指令比如一个v-permission:[action]的权限指令action从组件数据里动态取指令内部根据参数判断当前用户是否有该权限没有就直接移除元素button v-permission:editorder_edit编辑订单/button button v-permission:deleteorder_delete删除订单/button另外建议把项目里所有自定义指令统一放一个目录集中管理再通过一个directives/index.js注册// directives/index.js import watermark from ./watermark import copy from ./copy import debounce from ./debounce import permission from ./permission const directives { watermark, copy, debounce, permission } export default { install(app) { Object.keys(directives).forEach((name) { app.directive(name, directives[name]) }) } }主入口import directives from ./directives app.use(directives)这样做到后期指令数量上来了维护成本也不会失控。我见过有人把指令定义直接塞在主入口文件里写三五个还行写到十几个时那段代码已经没法看了。4.3 指令的边界什么时候不该用指令指令虽好但不能滥用。我自己踩过一个反面案例有一版需求是想让某个按钮在短时间内防止重复点击我直接写了一个v-once-click指令结果后来产品改需求要求不同按钮防重复点击的间隔不一样甚至有的按钮要允许滑动验证通过后再放开。指令里加这些业务判断越来越复杂最后不得不整块重构。教训就是指令适合承载可复用的 DOM 行为不适合承载和业务状态强耦合的规则。判断标准很简单如果这个行为在被多个页面以完全相同的方式复用且不需要感知具体的业务状态那就适合做成指令如果它需要根据不同的业务场景走完全不同的分支逻辑那应该写到组件内部或者用 composable 封装而不是硬塞进指令。比如防抖指令就非常合适它纯粹是延迟执行的机制问题不关心函数内部是什么业务// debounce.js export default { mounted(el, binding) { const { value, arg } binding const delay arg ? Number(arg) : 300 const fn value let timer null el.__debounceHandler__ function (event) { if (timer) clearTimeout(timer) timer setTimeout(() { fn.call(this, event) }, delay) } el.addEventListener(click, el.__debounceHandler__) }, unmounted(el) { el.removeEventListener(click, el.__debounceHandler__) } }这种就没有任何业务侵入放哪个项目都能用。5. 透传与指令联合作战一个表单场景完整拆解单独聊完透传和自定义指令最后用一个真实场景把它们串起来。这个场景就是我上一份工作里做的增强版表单输入框需要支持原生 input 的所有属性、自动聚焦、带字符长度统计而且焦点状态下要触发外部埋点。5.1 需求拆解表单里要渲染一个二次封装的输入框组件SmartInput它需要透传所有原生 input 属性让使用方不需要感知组件内部结构。页面加载后自动聚焦到第一个SmartInput上。输入内容时实时显示剩余可输入字符数。每次聚焦时上报埋点事件。如果用常规思路第 2 条会在组件里写一个autofocusprop第 4 条会再写一个focus事件的 emit然后每个用到的页面都手动绑定。这样的问题在于职责全堆在组件内部组件会越来越胖。5.2 用透传接管属性用指令接管行为最终的实现方案属性透传负责长得像原生 input自定义指令负责聚焦和埋点这些横切行为。SmartInput组件关键部分template div classsmart-input input classsmart-input__field v-bind$attrs :valuemodelValue inputhandleInput refinputRef / span classsmart-input__counter v-ifmaxlength {{ remainCount }} / {{ maxlength }} /span /div /template script setup import { computed, ref, useAttrs } from vue const attrs useAttrs() const props defineProps({ modelValue: { type: [String, Number], default: }, maxlength: { type: Number, default: undefined } }) const emit defineEmits([update:modelValue]) const inputRef ref(null) const remainCount computed(() { if (!props.maxlength) return 0 return props.maxlength - String(props.modelValue).length }) // 这里故意不吞掉 input 事件声明 emit 后input 就不再出现在 $attrs 里了 function handleInput(event) { emit(update:modelValue, event.target.value) } /script注意我用了useAttrs()拿属性但模板里用的是v-bind$attrs这两个可以并存useAttrs()通常用来在 JavaScript 里对某些属性做二次处理。然后在组件外层申请两个指令v-focus和v-track。// focus.js自动聚焦支持 .delay 修饰符延迟聚焦 export default { mounted(el, binding) { const input el.querySelector(input) || el if (binding.modifiers.delay) { setTimeout(() input.focus(), 800) } else { input.focus() } } }// track.js上报自定义事件 export default { mounted(el, binding) { el.__trackFocusHandler__ () { const { value } binding // value 可以是函数或事件名这里简单处理成函数 if (typeof value function) { value() } } el.addEventListener(focusin, el.__trackFocusHandler__) }, unmounted(el) { el.removeEventListener(focusin, el.__trackFocusHandler__) } }页面里的使用方式template SmartInput v-modelform.name v-focus.delay v-tracktrackReport placeholder请输入姓名 maxlength20 / /template script setup import { SmartInput } from /components import { vFocus, vTrack } from /directives const trackReport () { console.log(埋点聚焦了姓名输入框) } const form reactive({ name: }) /script5.3 这个方案好在哪里坑在哪里这个组合的好处是SmartInput内部不需要知道自动聚焦和埋点的存在这两个能力是通过指令注入的。未来如果产品说只有首页需要自动聚焦其他页面不要直接删掉那一行v-focus就行组件零改动。但这里也踩到过一个隐蔽的坑v-track侦听的是focusin而不是focus。原因很简单我需要在事件回调里通过el.querySelector找到内部的 input而focusin在 Vue 里是原生事件且可以冒泡只要SmartInput外壳 div 收到冒泡就能捕获到。如果用focus它本身不冒泡绑定在 div 上根本不会触发。这也是为什么组件里的聚焦埋点事件往往用focusin而blur对应地用focusout。另外一个经验是当指令和透传碰撞时事件处理顺序要留意。v-track绑定的是外层 div而SmartInput内部可能还有自己的focus处理两者都会触发但各自职责不同一个做业务上报一个做组件内部逻辑。如果你发现某个焦点事件被触发了两次多半是你既在$attrs里接收了外部绑定的 focus 监听器又在指令里绑定了focusin两边都响应了。处理方式是在指令里加一个判断看元素上是否已有同名监听器或者干脆统一约定埋点全部走指令事件透传只留给真正的业务响应。5.4 实测下来的几条心得第一个心得透传属性和指令结合时绑定目标元素的优先级要明确。我的习惯是组件最外层 DOM 负责承载class/style这类布局属性内部真正参与交互的元素比如 input负责承载placeholder、disabled、maxlength这类行为属性。这样视觉上的样式控制由外层承接语义上的行为控制由内层承接两者不打架。第二个心得指令里的 DOM 查询不要只写一层。el.querySelector(input)在大多数场景够用但如果模板嵌套再深一层input 外包了一个 span 再包一个 div建议给目标元素加一个固定 class 比如.smart-input__field指令里用el.querySelector(.smart-input__field)查询而不是直接el.querySelector(input)。别问我为什么知道问就是被第三方 UI 库的 DOM 结构调整坑过。第三个心得如果指令需要传递的参数较多——对象、函数、修饰符、动态参数都要兼顾——不要全塞在binding.value里靠魔法数解决直接约定一个对象字段名写清楚。比如v-watermark{ text, fontSize, rotate }这种比v-watermarktext|16|-25这种字符串拼接方案要可维护得多。我后来看老项目的代码那种靠字符串拼接传参数的指令读起来真的费劲。6. 最后再分享一个调试透传和指令的小技巧写到最后分享一个能显著提升排查效率的习惯在封装通用组件时给透传属性留一个观察后门。具体做法是在开发模式下如果useAttrs()返回的$attrs里有你意料之外的属性直接console.warn打印出来而不是默默接受。很多透传问题的根源是使用方传了拼写错误的属性名比如把maxlength写成了maxLength把placeholder写成了placeholer这类问题如果不显式提示排查起来非常痛苦。加一行开发期警告能省下大量沟通时间script setup import { useAttrs } from vue import { devtools } from /utils/devtools const attrs useAttrs() if (import.meta.env.DEV) { // 这里定义一下允许透传的已知属性白名单 const allowedKeys [class, style, placeholder, maxlength, disabled, id] const extraKeys Object.keys(attrs).filter((key) !allowedKeys.includes(key)) if (extraKeys.length 0) { console.warn([SmartInput] 检测到未预期的透传属性: ${extraKeys.join(, )}) } } /script这个思路同样适用于自定义指令指令的mounted钩子里可以校验binding.value的类型传错了直接报错而不是在运行时悄悄崩溃。自定义指令本来就是约定大于配置的东西把约束做在前面后面不管过多久都还有人记得这些约定。属性透传和自定义指令单独看都是 Vue 里偏基础的知识点但结合起来能在组件封装层面解决一大批组件越来越重的问题。我的经验是能用指令解决的横切关注点不要写进业务组件能用透传解决的属性分发不要定义成 props。把握好这两条原则组件库的代码会清爽很多。