Vue 3 透传 Attributes 第一章：基本概念与工作原理完全解析
扫描 关注或者微信搜一搜：编程智域 前端至全栈交流与成长
一、什么是 Attributes 透传
在 Vue 3 组件开发中，Attributes 透传
想象一下这个场景：你有一个按钮组件，父组件在使用时传递了 class、id、data-* 等属性，但这些属性并没有在子组件中通过 props 声明。Vue 会自动将这些属性"透传"到子组件的根元素上，这就是 Attributes 透传。
<!-- 父组件 -->
<template>
<MyButton class="btn-primary" id="submit-btn" data-action="submit" />
</template>
<!-- 子组件 MyButton.vue -->
<template>
<button>点击我</button>
<!-- 最终渲染为：<button class="btn-primary" id="submit-btn" data-action="submit">点击我</button> -->
</template>二、Vue 3 中 Attributes 透传的机制
2.1 透传的 Attributes 包含哪些内容
在 Vue 3 中，以下类型的 attributes 会被透传：
HTML 标准属性：如
class、style、id、title等自定义属性：如
data-*、aria-*等事件监听器：如
@click、@focus等（以on开头的 attributes）
不会被透传的 attributes：
已在
props或emits选项中声明的属性class和style有特殊处理规则（会合并而非覆盖）
2.2 透传机制的工作流程
2.3 代码示例：基础透传
<!-- ParentComponent.vue -->
<template>
<div>
<ChildComponent
title="子组件标题"
class="custom-class"
data-info="test"
@click="handleClick"
/>
</div>
</template>
<script setup>
const handleClick = () => {
console.log("子组件被点击");
};
</script><!-- ChildComponent.vue -->
<template>
<div class="child-root">
<p></p>
</div>
</template>
<script setup>
defineProps({
title: String,
});
</script>最终渲染结果：
<div class="child-root custom-class" data-info="test">
<p>子组件标题</p>
</div>注意：title 作为 props 被消费，不会出现在 DOM 上；而 class、data-info 和 @click 事件监听器被透传到了根元素。
三、单根组件与多根组件的透传差异
3.1 单根组件的自动透传
单根组件是指模板中只有一个根元素的组件。在 Vue 3 中，单根组件的 Attributes 透传是自动的。
<!-- SingleRoot.vue -->
<template>
<div class="wrapper">
<slot />
</div>
</template>
<script setup>
// 无需任何额外代码，attributes 自动透传
</script>当父组件使用：
<SingleRoot class="outer" id="my-wrapper" data-role="container">
内容
</SingleRoot>渲染结果：
<div class="wrapper outer" id="my-wrapper" data-role="container">内容</div>3.2 多根组件的手动透传
多根组件（Fragment）是指模板中有多个根元素的组件。Vue 3 支持多根节点，但这也带来了歧义：attributes 应该透传到哪个根元素上？
因此，多根组件不会自动透传 attributes，需要开发者手动指定。
<!-- MultiRoot.vue -->
<template>
<header class="header">头部</header>
<main class="content">
<slot />
</main>
<footer class="footer">底部</footer>
</template>
<script setup>
// 多根组件，attributes 不会自动透传
</script>3.3 使用 $attrs 手动绑定
对于多根组件，我们可以使用 $attrs 对象来手动绑定 attributes 到指定的根元素：
<!-- MultiRootWithAttrs.vue -->
<template>
<header class="header">头部</header>
<main class="content" v-bind="$attrs">
<slot />
</main>
<footer class="footer">底部</footer>
</template>
<script setup>
// $attrs 包含所有未声明的 attributes
</script>现在父组件传递的 attributes 会绑定到 <main> 元素上：
<MultiRootWithAttrs class="main-content" data-section="home">
主内容区域
</MultiRootWithAttrs>渲染结果：
<header class="header">头部</header>
<main class="content main-content" data-section="home">主内容区域</main>
<footer class="footer">底部</footer>四、$attrs 对象详解
4.1 $attrs 的结构
$attrs 是一个包含所有未通过 props 或 emits 声明的 attributes 的对象。
<template>
<div>
<p>attrs: {{ $attrs }}</p>
</div>
</template>
<script setup>
import { onMounted } from "vue";
onMounted(() => {
console.log("attrs:", useAttrs());
});
</script>4.2 在 script setup 中访问 $attrs
<script setup>
import { useAttrs } from "vue";
const attrs = useAttrs();
console.log(attrs.class);
console.log(attrs["data-info"]);
</script>4.3 在 Options API 中访问 $attrs
<script>
export default {
created() {
console.log(this.$attrs);
},
};
</script>五、class 和 style 的特殊合并规则
class 和 style 是特殊的 attributes，它们不会覆盖子组件根元素上已有的值，而是合并。
<!-- 父组件 -->
<ChildComponent class="parent-class" :style="{ color: 'red' }" />
<!-- 子组件 -->
<template>
<div class="child-class" :style="{ background: 'blue' }">内容</div>
</template>最终渲染：
<div class="child-class parent-class" style="color: red; background: blue;">
内容
</div>六、实际应用场景
6.1 封装基础 UI 组件
<!-- BaseInput.vue -->
<template>
<input class="base-input" v-bind="$attrs" />
</template>
<script setup>
// 自动继承所有 attributes: placeholder、disabled、maxlength 等
</script>
<style scoped>
.base-input {
padding: 8px 12px;
border: 1px solid #ddd;
border-radius: 4px;
}
</style>使用：
<BaseInput
v-model="username"
placeholder="请输入用户名"
maxlength="20"
disabled
/>6.2 高阶组件封装
<!-- WithTooltip.vue -->
<template>
<div class="tooltip-wrapper">
<component v-bind="$attrs" :is="tag" />
<div v-if="tooltip" class="tooltip">{{ tooltip }}</div>
</div>
</template>
<script setup>
defineProps({
tag: {
type: String,
default: "button",
},
tooltip: String,
});
</script>课后 Quiz
问题 1：以下代码中，哪些 attributes 会被透传到子组件的根元素？
<!-- 父组件 -->
<ChildComponent title="标题" class="outer" data-id="123" @click="handle" />
<!-- 子组件 -->
<script setup>
defineProps({
title: String,
});
</script>答案：class、data-id 和 @click 会被透传。title 已在 props 中声明，不会被透传。
问题 2：多根组件为什么不能自动透传 attributes？
答案：因为存在歧义。多根组件有多个根元素，Vue 无法确定应该将 attributes 透传到哪个元素上，需要开发者使用 $attrs 手动指定。
问题 3：class 和 style 在透传时有什么特殊处理？
答案：class 和 style 不会覆盖子组件根元素上已有的值，而是进行合并。父组件的 class 会追加到子组件的 class 后面，style 同理。
常见报错解决方案
报错 1：多根组件 attributes 不生效
现象：父组件传递的 attributes 在多根组件上没有效果。
原因：多根组件不会自动透传 attributes。
解决方案：
<!-- 错误示例 -->
<template>
<div>根 1</div>
<div>根 2</div>
</template>
<!-- 正确示例 -->
<template>
<div>根 1</div>
<div v-bind="$attrs">根 2</div>
</template>报错 2：$attrs 在 script setup 中无法访问
现象：在 script setup 中直接使用 $attrs 报错。
原因：script setup 中需要通过 useAttrs() 导入。
解决方案：
<script setup>
import { useAttrs } from "vue";
const attrs = useAttrs();
</script>报错 3：props 和 attrs 重复导致警告
现象：控制台警告 "Extraneous non-props attributes"。
原因：同一个 attribute 既在 props 中声明，又试图透传。
解决方案：确保 attribute 只在 props 中声明或在 attrs 中透传，不要重复。
参考链接
余下文章内容请点击跳转至 个人博客页面 或者 扫描 关注或者微信搜一搜：编程智域 前端至全栈交流与成长，阅读完整的文章：
往期文章归档
</details>
免费好用的热门在线工具
评论
发表评论