阅读此章节时,我们假设你已经读过组件基础,若你对组件还完全不了解,请先阅读它。

Attribute 继承 $attrs

“透传 attribute” 是传递给组件的 attribute 或者 v-on 事件监听器,但并没有显式地声明在所接收组件的 propsemits 上。最常见的例子就是 classstyleid

当一个组件以单个元素为根作渲染时,透传的 attribute 会自动添加到根元素的 attribute 中。举个例子,下面这个 <MyButton> 组件有这样的模板:

  1. <!-- <MyButton> 的模板 -->
  2. <button>click me</button>

一个父组件使用了这个组件:

  1. <MyButton class="large" />

最后渲染出的 DOM 结果是:

  1. <button class="large">click me</button>

classstyle 的合并

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

  1. <!-- <MyButton> 的模板 -->
  2. <button class="btn">click me</button>

最后渲染出的 DOM 结果是:

  1. <button class="btn large">click me</button>

Vue 2 的虚拟 DOM 实现对 class 和 style attribute 有一些特殊处理。因此,与其它所有 attribute 不一样,它们没有被包含在 $attrs 中。 https://v3.cn.vuejs.org/guide/migration/attrs-includes-class-style.html

v-on 监听器继承

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

  1. <MyButton @click="onClick" />

监听器 click 会被添加到 <MyButton> 的根元素,即那个原生的 <button> 元素之上。当原生的 <button> 被点击,会触发父组件的 onClick 方法。如果原生 button 元素已经通过 v-on 绑定了一个事件监听器,则这些监听器都会被触发。

“透传 attribute” 是传递给组件的 attribute 或者 v-on 事件监听器;在 vue2 中这两者是分开的,属性是$attrs,事件是$listeners。在vue3事件监听器是 $attrs 的一部分,$listeners被移除。https://v3.cn.vuejs.org/guide/migration/listeners-removed.html#%E6%A6%82%E8%A7%88

深层组件继承

如果一个组件在根节点上渲染另一个组件,例如,我们重构一下 <MyButton>,让它在根节点上渲染 <BaseButton>

  1. <!-- <MyButton/> 的模板,只是渲染另一个组件 -->
  2. <BaseButton />

此时 <MyButton> 接收的透传 attribute 会直接传向 <BaseButton>

请注意:

  1. 透传的 attribute 不会包含 <MyButton> 上声明过的 props 或是针对 emits 声明事件的 v-on 侦听函数,换句话说,声明过的 props 和侦听函数被 <MyButton>“消费” 了。
  2. 透传的 attribute 若符合声明,也可以作为 props 传入 <BaseButton>

禁用 Attribute 继承

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

如果你使用了 <script setup>,你需要一个额外的 <script> 块来书写这个选项声明:

  1. <script>
  2. // 使用一个简单的 <script> to declare options
  3. export default {
  4. inheritAttrs: false
  5. }
  6. </script>
  7. <script setup>
  8. // ...setup 部分逻辑
  9. </script>

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

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

  1. <span>Fallthrough attribute: {{ $attrs }}</span>

这个 $attrs 对象包含了除组件的 propsemits 属性外的所有其他 attribute,例如 classstylev-on 监听器等等。

有几点需要注意:

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

现在我们要再次使用一下之前小节中的 <MyButton> 组件例子。有时候我们可能为了样式,需要在 <button> 元素外包装一层 <div>

  1. <div class="btn-wrapper">
  2. <button class="btn">click me</button>
  3. </div>

非根节点的 Attribute 继承

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

  1. <div class="btn-wrapper">
  2. <button class="btn" v-bind="$attrs">click me</button>
  3. </div>

请记住没有参数的 [v-bind](/guide/essentials/template-syntax.html#dynamically-binding-multiple-attributes) 会将一个对象的所有属性都作为 attribute 应用到目标元素上。

多根节点的 Attribute 继承

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

  1. <CustomLayout id="custom-layout" @click="changeValue" />

如果 <CustomLayout> 有下面这样的多根节点模板,由于 Vue 不知道要将 attribute 透传到哪里,所以会抛出一个警告。

  1. <header>...</header>
  2. <main>...</main>
  3. <footer>...</footer>

如果 $attrs 被显式绑定,则不会有警告:

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

在 JavaScript 中访问透传 Attribute

如果需要,你可以在 <script setup> 中使用 useAttrs() API 来访问一个组件的所有透传 attribute:

  1. <script setup>
  2. import { useAttrs } from 'vue'
  3. const attrs = useAttrs()
  4. </script>

如果没有使用 <script setup>attrs 会作为 setup() 上下文对象的一个属性暴露:

  1. export default {
  2. setup(props, ctx) {
  3. // 透传 attribute 被暴露为 ctx.attrs
  4. console.log(ctx.attrs)
  5. }
  6. }

需要注意的是,虽然这里的 attrs 对象总是反映为最新的透传 attribute,但它并不是响应式的 (考虑到性能因素)。你不能通过侦听器去监听它的变化。如果你需要响应性,可以使用 prop。或者你也可以使用 onUpdated() 使得在每次更新时结合最新的 attrs 执行副作用。

如果需要,你可以通过 $attrs 这个实例属性来访问组件的所有透传 attribute:

  1. export default {
  2. created() {
  3. console.log(this.$attrs)
  4. }
  5. }