文档库

Appearance

透传Attributes ​

Attributes 继承 ​

“透传 attribute”指的是传递给组件，但组件本身并未声明为 props 或 emits 的属性或事件监听器。最常见的例子包括 class、style、id 等，它们会自动透传到组件的根元素上。

当一个组件以单个元素为根作渲染时，透传的 attribute 会自动被添加到根元素上。举例来说，假如我们有一个 <MyButton> 组件，它的模板长这样：

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

一个父组件使用了这个组件，并且传入了 class：

ts
<MyButton class="large" />

最后渲染出的 DOM 结果是：

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

<MyButton> 并没有将 class 声明为一个它所接受的 prop，所以 class 被视作透传 attribute，自动透传到了 <MyButton> 的根元素上。

对 class 和 style 的合并 ​

如果一个子组件的根元素已经有了 class 或 style attribute，它会和从父组件上继承的值合并。如果我们将之前的 <MyButton> 组件的模板改成这样：

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

则最后渲染出的 DOM 结果会变成：

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

v-on 监听器继承 ​

同样的规则也适用于 v-on 事件监听器：

vue
<MyButton @click="onClick" />

click 监听器会被添加到 <MyButton> 的根元素，即那个原生的 <button> 元素之上。当原生的 <button> 被点击，会触发父组件的 onClick 方法。

同样的，如果原生 button 元素自身也通过 v-on 绑定了一个事件监听器，则这个监听器和从父组件继承的监听器都会被触发。

ts
<button class="btn" @click="innerClick">提交</button>

因为父组件的监听器也被加到了这个元素上，所以点击行为发生时：

  1. 子组件内部的 innerClick
  2. 父组件传入的 onClick

都会被触发（按冒泡顺序执行）。事件不会被覆盖，它们是并存的。

如果你不想让父组件的监听器自动绑定到根元素，可以在子组件里显式声明 emits。此时 Vue 会认为：

  • click 是组件事件，而不是透传给 DOM 的原生事件
  • 父组件监听 @click 要靠子组件主动 $emit('click')

这就可以避免原生按钮的 click 和父级的 click 混在一起。

深层组件继承 ​

有些情况下一个组件会在根节点上渲染另一个组件。例如，我们重构一下 <MyButton>，让它在根节点上渲染 <BaseButton>：

vue
<!-- <MyButton/> 的模板，只是渲染另一个组件 -->
<BaseButton />

此时 <MyButton> 接收的透传 attribute 会直接继续传给 <BaseButton>。

透传的 attribute 不会包含 <MyButton> 上声明过的 props 或是针对 emits 声明事件的 v-on 侦听函数，换句话说，声明过的 props 和侦听函数被 <MyButton>“消费”了。

禁用 Attributes 继承 ​

如果你不想要一个组件自动地继承 attribute，你可以在组件选项中设置 inheritAttrs: false。

vue
<script setup>
defineOptions({
  inheritAttrs: false
})
// ...setup 逻辑
</script>

最常见的需要禁用 attribute 继承的场景就是 attribute 需要应用在根节点以外的其他元素上。通过设置 inheritAttrs 选项为 false，你可以完全控制透传进来的 attribute 被如何使用。

这些透传进来的 attribute 可以在模板的表达式中直接用 $attrs 访问到。

vue
<span>Fallthrough attribute: {{ $attrs }}</span>

这个 $attrs 对象包含了除组件所声明的 props 和 emits 之外的所有其他 attribute，例如 class，style，v-on 监听器等等。

  • 和 props 有所不同，透传 attributes 在 JavaScript 中保留了它们原始的大小写，所以像 foo-bar 这样的一个 attribute 需要通过 $attrs['foo-bar'] 来访问。
  • 像 @click 这样的一个 v-on 事件监听器将在此对象下被暴露为一个函数 $attrs.onClick。

有时候我们可能为了样式，需要在 <button> 元素外包装一层 <div>：

vue
<div class="btn-wrapper">
  <button class="btn">Click Me</button>
</div>

我们想要所有像 class 和 v-on 监听器这样的透传 attribute 都应用在内部的 <button> 上而不是外层的 <div> 上。我们可以通过设定 inheritAttrs: false 和使用 v-bind="$attrs" 来实现：

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

没有参数的 v-bind 会将一个对象的所有属性都作为 attribute 应用到目标元素上。

多根节点的 Attributes 继承 ​

多个根节点的组件没有自动 attribute 透传行为。如果 $attrs 没有被显式绑定，将会抛出一个运行时警告。

Layout.vue
vue
<header>...</header>
<main>...</main>
<footer>...</footer>

如果 $attrs 被显式绑定，则不会有警告：

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