属性透传
约 856 字大约 3 分钟
2026-02-10
核心概念
属性透传（Fallthrough Attributes）指 没有被组件声明为 props 或 emits 的属性/事件，仍会自动传递到子组件的根元素
笔记
属性透传让封装组件在不暴露全部 API 的情况下，依旧能够 "像原生元素一样" 接收 class、style、id、data-*、aria-* 等属性
| 类别 | 是否透传 | 说明 |
|---|---|---|
已声明为 props | 否 | 作为组件 props 使用，不再透传 |
已声明为 emits | 否 | 作为组件事件处理，不会落到 DOM |
| 未声明的属性 | 是 | 自动合并到根元素 |
class / style | 是 | 与根元素自身的 class / style 合并 |
| 未声明的事件 | 是 | 作为原生事件监听传递给根元素 |
属性透传规则
最佳实践
- 优先声明
props/emits，让 API 清晰、类型安全 - 需要筛选或移动属性时，使用
inheritAttrs: false+v-bind="$attrs" - 需要透传的属性较多时，直接
v-bind="$attrs"，避免手动枚举 - 需要响应式属性时，把它定义成
props，不要指望useAttrs()响应 - 透传事件时，优先在子组件内部 处理后再转发，确保封装逻辑生效
$attrs 与 useAttrs()
$attrs 中包含所有 未声明为 props / emits 的属性，并且包含 class、style 与未声明的事件监听器。可通过 useAttrs() 在 <script setup> 中访问
访问规则
- 普通属性：
attrs.id、attrs.title data-*/aria-*：使用括号访问，如attrs['data-id']、attrs['aria-label']- 事件监听：以
onXxx形式存在，如@click->attrs.onClick
重要
useAttrs() 返回的对象不是响应式的，不能用 watch 监听变化。需要变化时，优先将其声明为 props，或在 onUpdated 中读取
多根节点与手动透传
当组件渲染 多个根节点 时，Vue 不会自动把属性透传到任意一个节点。此时必须显式通过 v-bind 绑定 $attrs
<script setup lang="ts">
import { useAttrs } from 'vue'
defineOptions({
inheritAttrs: false,
})
const attrs = useAttrs()
</script>
<template>
<header class="title" v-bind="attrs">标题</header>
<main class="content">
<slot />
</main>
</template>inheritAttrs
通过在 defineOptions 中使用 inheritAttrs 用来控制 未声明的属性是否自动合并到根元素
| 设置 | 行为 | 典型用途 |
|---|---|---|
true（默认） | 自动合并到根元素 | 轻量包装组件、希望像原生元素一样使用 |
false | 不自动合并，需要 v-bind="$attrs" | 需要精准指定透传位置、多根节点组件 |
inheritAttrs 的影响
inheritAttrs.vue
<script setup lang="ts">
defineOptions({
inheritAttrs: false,
})
</script>
<template>
<!-- 让外部属性落到真正的输入框上 -->
<input class="field" v-bind="$attrs" />
</template>最小可行案例
代码逻辑
- 父组件向
BaseButton传入id、class、data-testid与两个事件 - 子组件通过
inheritAttrs: false关闭自动透传，再把$attrs显式绑定到<button>上，同时派发自定义的press事件并在内部继续转发原生click - 点击按钮后，页面会更新两行文本，分别对应 自定义事件 与 原生事件透传，便于直观看到它们的区别
<script setup lang="ts">
import BaseButton from './BaseButton.vue';
import { ref } from 'vue'
const press = ref('--')
const native = ref('--')
function handlePress() {
press.value = 'press: 子组件自定义事件'
}
function handleNativeClick() {
native.value = 'click: 原生事件透传'
}
</script>
<template>
<BaseButton
id="save-btn"
class="primary"
data-testid="save"
@press="handlePress"
@click="handleNativeClick"
>
保存
</BaseButton>
<div style="display: flex; flex-direction: column; gap: 8px; margin-top: 8px;">
<span>{{ press }}</span>
<span>{{ native }}</span>
</div>
</template>BaseButton.vue
<script setup lang="ts">
import { useAttrs } from 'vue'
defineOptions({
inheritAttrs: false,
})
const emit = defineEmits<{
(event: 'press', payload: MouseEvent): void
}>()
const attrs = useAttrs()
function handleClick(event: MouseEvent) {
// 组件自定义事件
emit('press', event)
// 透传父组件的原生点击监听
const onClick = attrs.onClick as ((e: MouseEvent) => void) | undefined
if (onClick) onClick(event)
}
</script>
<template>
<button class="btn" v-bind="attrs" type="button" @click="handleClick">
<slot />
</button>
</template>