从零掌握 Vue 3 useAttrs：属性透传的终极解决方案

📖 概述

useAttrs() 是 Vue 3 中的一个组合式 API 函数，用于访问传递给组件但未被 defineProps 或 defineEmits 声明的属性。它返回一个响应式对象，包含所有未声明的属性。

🎯 基本概念

什么是 useAttrs？

useAttrs() 返回一个包含所有传递给组件但未被声明的属性的响应式对象。这些属性包括 HTML 属性、事件监听器、class、style 等。

使用场景

• 🔧 透传属性到内部元素
• 🎨 动态应用样式和类名
• 📡 传递事件监听器
• 🏷️ 处理自定义属性

🔧 函数签名

function useAttrs(): Record<string, any>;

💻 代码示例

🚀 基础用法

<script setup lang="ts">
import { useAttrs } from "vue";

// 获取所有未声明的属性
const attrs = useAttrs();

console.log(attrs); // 包含所有未声明的属性
</script>

<template>
  <div>
    <!-- 透传所有属性到 div 元素 -->
    <div v-bind="attrs">内容</div>
  </div>
</template>

🎨 透传属性到内部元素

<script setup lang="ts">
import { useAttrs } from "vue";

// 定义 props
interface Props {
  title: string;
}

const props = defineProps<Props>();
const attrs = useAttrs();
</script>

<template>
  <div class="card">
    <h3>{{ title }}</h3>
    <!-- 将未声明的属性透传到 button 元素 -->
    <button v-bind="attrs">
      <slot />
    </button>
  </div>
</template>

📡 处理事件监听器

<script setup lang="ts">
import { useAttrs } from "vue";

const attrs = useAttrs();

// 检查是否有点击事件
const hasClickHandler = computed(() => "onClick" in attrs);
</script>

<template>
  <div class="container">
    <!-- 透传事件监听器 -->
    <div v-bind="attrs" class="clickable">
      <slot />
    </div>
  </div>
</template>

🏷️ 选择性透传属性

<script setup lang="ts">
import { useAttrs, computed } from "vue";

const attrs = useAttrs();

// 只透传特定的属性
const buttonAttrs = computed(() => {
  const { class: className, style, ...rest } = attrs;
  return {
    class: `btn ${className || ""}`,
    style,
    ...rest,
  };
});
</script>

<template>
  <button v-bind="buttonAttrs">
    <slot />
  </button>
</template>

⚖️ 与 defineProps 的对比

✅ 使用 defineProps（声明属性）

<script setup lang="ts">
interface Props {
  title: string;
  disabled?: boolean;
}

const props = defineProps<Props>();
</script>

<template>
  <button :disabled="props.disabled">
    {{ props.title }}
  </button>
</template>

🔧 使用 useAttrs（透传属性）

<script setup lang="ts">
import { useAttrs } from "vue";

const attrs = useAttrs();
</script>

<template>
  <button v-bind="attrs">
    <slot />
  </button>
</template>

⚠️ 注意事项

🔢 属性优先级

defineProps 声明的属性优先级高于 useAttrs 中的属性：

<script setup lang="ts">
interface Props {
  class?: string;
}

const props = defineProps<Props>();
const attrs = useAttrs();

// props.class 会覆盖 attrs.class
</script>

📝 响应式更新

useAttrs() 返回的对象是响应式的，会随着父组件传递的属性变化而更新：

<script setup lang="ts">
import { useAttrs, watch } from "vue";

const attrs = useAttrs();

// 监听属性变化
watch(
  attrs,
  (newAttrs) => {
    console.log("属性已更新:", newAttrs);
  },
  { deep: true }
);
</script>

🛡️ 类型安全

useAttrs() 返回的类型是 Record<string, any>，需要手动进行类型检查：

<script setup lang="ts">
import { useAttrs } from "vue";

const attrs = useAttrs();

// 类型安全的属性访问
const isDisabled = computed(() => {
  return attrs.disabled === true || attrs.disabled === "";
});
</script>

🎯 最佳实践

1️⃣ 合理使用透传

只在确实需要透传属性时使用 useAttrs()，避免过度使用：

<script setup lang="ts">
import { useAttrs } from "vue";

const attrs = useAttrs();

// 只透传必要的属性
const buttonAttrs = computed(() => {
  const { class: className, style, disabled, ...rest } = attrs;
  return {
    class: `custom-button ${className || ""}`,
    style,
    disabled,
    ...rest,
  };
});
</script>

2️⃣ 结合 defineProps 使用

将 useAttrs() 与 defineProps() 结合使用，明确组件的 API：

<script setup lang="ts">
interface Props {
  variant?: "primary" | "secondary";
  size?: "small" | "medium" | "large";
}

const props = defineProps<Props>();
const attrs = useAttrs();

// 合并 props 和 attrs
const buttonProps = computed(() => ({
  class: `btn btn-${props.variant || "primary"} btn-${props.size || "medium"}`,
  ...attrs,
}));
</script>

3️⃣ 避免属性冲突

注意避免属性名冲突，特别是在透传时：

<script setup lang="ts">
import { useAttrs, computed } from "vue";

const attrs = useAttrs();

// 避免 class 属性冲突
const mergedClass = computed(() => {
  const baseClass = "base-component";
  const attrsClass = attrs.class || "";
  return `${baseClass} ${attrsClass}`.trim();
});
</script>

❓ 常见问题

Q: useAttrs 和 $attrs 有什么区别？

A: useAttrs() 是组合式 API，$attrs 是选项式 API。在 <script setup> 中推荐使用 useAttrs()。

Q: 如何处理 useAttrs 的类型安全？

A: 可以使用类型断言或创建类型安全的访问函数：

const attrs = useAttrs();

// 类型安全的访问
const getAttr = <T>(key: string, defaultValue: T): T => {
  return (attrs[key] as T) ?? defaultValue;
};

Q: useAttrs 是否包含事件监听器？

A: 是的，useAttrs() 包含所有未声明的事件监听器，如 onClick、onInput 等。

📝 总结

useAttrs() 是 Vue 3 中处理未声明属性的强大工具，特别适用于创建可复用的包装组件。通过合理使用 useAttrs()，可以实现灵活的属性透传，提高组件的可复用性和开发效率。记住要结合 defineProps() 使用，明确组件的 API 边界，并注意属性优先级和类型安全。