22. 透传属性

本节目标：理解透传属性的工作机制，学会控制属性的自动传递和手动绑定。

什么是透传属性

“透传属性”（Attribute Inheritance / Fallthrough Attributes）就是父组件传给组件、但组件没有声明为 prop 的属性。比如 class、style、id 这些。

<MyButton class="large" />

<MyButton> 没有声明 class 为 prop。那 class="large" 去哪了？

如果组件只有一个根节点，透传属性会自动加到根元素上：

<!-- MyButton 的模板 -->
<button>Click Me</button>

渲染结果：

<button class="large">Click Me</button>

如果根元素已经有 class，透传过来的会合并：

<!-- MyButton 的模板 -->
<button class="btn">Click Me</button>

<!-- 父组件 -->
<MyButton class="large" />

渲染结果：

<button class="btn large">Click Me</button>

style 同理——组件内的 style 和透传的 style 会合并覆盖。

<MyButton @click="onClick" />

click 监听器会加到根 <button> 元素上。如果根元素本身也有 @click，两个都会触发。

如果组件的根是另一个组件，透传属性会继续往下传：

<!-- MyButton 的模板 -->
<BaseButton />

透传到 MyButton 的属性会自动转发到 BaseButton。

有两个注意点：

如果你不想让属性自动加到根元素上，可以关闭：

<script setup>
defineOptions({
  inheritAttrs: false
})
</script>

关闭后你可以手动决定属性去哪。配合 v-bind="$attrs"：

<div class="btn-wrapper">
  <button class="btn" v-bind="$attrs">Click Me</button>
</div>

这样所有透传属性会到内层 <button>，不是外层 <div>。

v-bind 不跟参数会把对象的所有属性都绑上去——这是”全部传递”的简写。

$attrs 包含所有未声明为 prop/emits 的属性：

<span>透传属性: {{ $attrs }}</span>

几点要注意：

在 <script setup> 里可以用 useAttrs()：

<script setup>
import { useAttrs } from 'vue'

const attrs = useAttrs()
</script>

单根节点会自动继承，多根节点不会。如果不在模板里绑定 $attrs，Vue 会发出警告：

<!-- CustomLayout 的模板 -->
<header>...</header>
<main>...</main>
<footer>...</footer>

Vue 不知道该把属性给谁。解决办法：手动指定：

<header>...</header>
<main v-bind="$attrs">...</main>
<footer>...</footer>

Warning

多根节点必须显式绑定 $attrs，否则会有运行时警告。养成习惯：多根组件一定写 v-bind="$attrs"。

场景	做法
属性自动加到根元素	默认行为即可
属性要加到内部元素	`inheritAttrs: false` + `v-bind="$attrs"`
属性要分给不同子元素	`inheritAttrs: false` + 手动 `$attrs.xxx`
多个根节点	必须关闭继承，手动指定