本文 AI 產出，尚未審核

Vue3 元件通信：深入了解 $attrs 與 $listeners

簡介

在 Vue3 中，元件之間的溝通是開發大型單頁應用的基礎。除了 props、emit、provide/inject 等常見方式外，$attrs 與 $listeners（Vue2 時代的概念）提供了更彈性的屬性與事件轉發機制。它們讓我們可以在 「包裝（wrapper）元件」、「高階元件」 或 「抽象介面」 中，無需逐一列出每個屬性或事件，就把父層傳遞下來的資訊完整轉交給子元件，極大提升可維護性與重用性。

本篇文章將從概念說明、實作範例、常見陷阱與最佳實踐，帶領你完整掌握 $attrs 與 $listeners 在 Vue3 的使用方式，並提供實務上值得參考的應用情境。

核心概念

1. $attrs 的定位

  • 什麼是 $attrs？
    $attrs 是一個包含 所有父層傳入但未在 props 中聲明 的屬性與原生 HTML attribute（例如 class、style、id）的物件。它同時也會收集 未被 emits 宣告的事件（在 Vue2 中屬於 $listeners 的範疇）。

  • 為什麼需要 $attrs？
    當我們建立 包裝元件（例如自訂的 UI 元件）時，往往不想在每個 wrapper 中重複列出所有可能的屬性與事件。透過 $attrs，可以 自動把「未聲明」的屬性/事件原封不動傳遞 給內部子元件或根元素。

2. $listeners 的演變

在 Vue2 中，$listeners 專門收集 父層傳下來的事件監聽器（v-on:*），而 $attrs 只收集屬性。Vue3 將兩者合併，所有未聲明的屬性與事件都放在 $attrs，因此 $listeners 已不再是獨立的 API，只需要關注 $attrs 即可。

⚠️ 注意：若你仍在升級 Vue2 專案，必須自行將 $listeners 合併到 $attrs，或使用 Vue3 的兼容模式。

3. $attrs 的傳遞方式

方法 說明
inheritAttrs: false 讓元件 不自動 把 $attrs 套用到根元素上，方便自行控制轉發位置（例如只給子元件）。
v-bind="$attrs" 在模板中 一次性 把所有 $attrs 轉發給目標元素或子元件。
Object.entries($attrs) 在 setup 或 render 函式中動態操作 $attrs（例如過濾、重命名）。

程式碼範例

以下示範 4 個常見情境，從最簡單的屬性轉發到進階的事件重命名與過濾。

範例 1：最基礎的 $attrs 轉發（包裝 <button>）

<!-- WrapperButton.vue -->
<template>
  <!-- 直接把所有未宣告的屬性與事件掛在根元素 -->
  <button v-bind="$attrs">{{ label }}</button>
</template>

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

const props = defineProps({
  label: { type: String, default: '送出' }
})

// 此元件不需要額外的 props，所有其他屬性 (e.g. class, disabled, @click) 會自動透過 $attrs 傳遞
</script>

使用方式

<WrapperButton
  class="primary"
  :disabled="isSubmitting"
  @click="handleSubmit"
/>

只要在父層加上 class、disabled、@click，WrapperButton 會自動把它們轉給內部 <button>，不需要在 props 或 emits 中額外聲明。

範例 2：inheritAttrs: false + 手動轉發給子元件

<!-- CardWrapper.vue -->
<template>
  <div class="card" :style="customStyle">
    <!-- 手動把 $attrs 只傳給 CardContent -->
    <CardContent v-bind="$attrs" />
  </div>
</template>

<script>
import { defineComponent } from 'vue'
import CardContent from './CardContent.vue'

export default defineComponent({
  name: 'CardWrapper',
  components: { CardContent },
  inheritAttrs: false, // 防止 $attrs 被自動掛到根 <div>
  props: {
    customStyle: Object
  }
})
</script>

父層使用

<CardWrapper :custom-style="{ padding: '1rem' }" title="卡片標題" @close="onClose" />
  • title 與 @close 會 只傳給 CardContent，不會影響外層的 <div>。
  • 這種方式常用於 「布局容器」，讓外層保持乾淨的 DOM 結構。

範例 3：過濾與重命名事件（模擬 $listeners）

<!-- InputWrapper.vue -->
<template>
  <input
    v-bind="inputAttrs"
    @input="onInput"
    @focus="emit('focus')"
  />
</template>

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

const emit = defineEmits(['update:modelValue', 'focus'])

const attrs = useAttrs()

// 只取出原生屬性，排除事件 (Vue3 會把事件也放在 $attrs)
const inputAttrs = {}
for (const [key, value] of Object.entries(attrs)) {
  if (!key.startsWith('on')) { // 排除 onClick, onFocus 等事件
    inputAttrs[key] = value
  }
}

// 把原生 input 事件重新包裝成我們自定義的 emit
function onInput(event) {
  emit('update:modelValue', event.target.value)
}
</script>

父層使用

<InputWrapper
  v-model="username"
  placeholder="請輸入使用者名稱"
  @focus="handleFocus"
/>
  • 這裡 過濾掉 $attrs 中的事件，只保留純屬性給 <input>，同時把 input 事件 重新包裝 為 update:modelValue，符合 Vue3 的 v-model 機制。
  • 透過 useAttrs()，我們可以在 setup 中靈活操作 $attrs，這在 高階元件 中非常實用。

範例 4：在 render 函式中動態合併 $attrs（進階）

// FancyLink.jsx
import { defineComponent, h, useAttrs } from 'vue'

export default defineComponent({
  name: 'FancyLink',
  inheritAttrs: false,
  props: {
    to: { type: String, required: true }
  },
  setup(props) {
    const attrs = useAttrs()

    return () => {
      // 合併自訂屬性與 $attrs，並加入預設的 class
      const mergedAttrs = {
        href: props.to,
        class: ['fancy-link', attrs.class],
        ...attrs // 其他屬性 (target, rel, @click 等) 都保留
      }
      return h('a', mergedAttrs, attrs.title || '連結')
    }
  }
})

父層使用

<FancyLink
  to="https://vuejs.org"
  target="_blank"
  rel="noopener"
  class="external"
  title="Vue 官方網站"
/>
  • 在 render 函式裡，我們可以 自行決定屬性合併的順序，讓預設 class 先於使用者傳入的 class。
  • 此技巧常見於 UI 套件，需要保證元件的基礎樣式不會被外部覆寫，同時仍允許使用者自行調整。

常見陷阱與最佳實踐

陷阱 說明 解決方式
忘記 inheritAttrs: false 包裝元件會把 $attrs 自動掛在根元素，導致 DOM 結構不符合預期（例如多餘的 class、style） 在需要手動轉發的情況下，明確設定 inheritAttrs: false。
事件被意外吞掉 在 Vue3 中，未在 emits 中聲明的事件會被視為 $attrs，若直接 v-bind="$attrs"，自訂事件 可能被當作原生屬性忽略。 使用 defineEmits 或 emit 明確宣告，或在 setup 內過濾 on* 事件。
屬性衝突 父層傳入的 class、style 可能與子元件內部預設的樣式衝突。 在轉發前 合併或過濾（如範例 4 中的 mergedAttrs），或使用 CSS 優先級（BEM、:deep）避免衝突。
過度依賴 $attrs 把所有屬性都交給子元件，會失去 型別檢查與文件化 的好處。 只在 通用容器、高階元件 中使用；對於 業務邏輯 明確的屬性仍建議使用 props。
在 TypeScript 中缺少類型 $attrs 預設是 Record<string, any>，會失去自動補全。 使用 defineProps + ExtractPropTypes 手動定義類型，或在 setup 中使用 toRefs(useAttrs()) 並自行加上介面。

最佳實踐總結

  1. 明確需求：只有在「不想逐一列出」或「需要把所有屬性/事件原封不動轉發」時才使用 $attrs。
  2. 使用 inheritAttrs: false 讓你掌控 $attrs 的掛載位置。
  3. 事件重命名：若要把原生事件轉成自訂事件，請在 setup 中過濾 on*，或使用 defineEmits 明確聲明。
  4. 合併策略：根據 UI 套件的需求，決定是 先合併後覆寫（範例 4）或 直接傳遞。
  5. 文件化：即使使用 $attrs，仍應在元件說明文件中列出「可能傳入的屬性與事件」以供使用者參考。

實際應用場景

場景 為什麼適合使用 $attrs 範例概念
自訂 UI 套件的基礎元件（如 <BaseButton>、<BaseInput>） 允許使用者自由加入 class、style、id、@click 等，且不需要在每個基礎元件重複聲明。 BaseButton.vue 中 v-bind="$attrs"，配合 inheritAttrs: false 只把事件傳給內部 <button>。
高階表單元件（如 <FormItem> 包裝 <input>、<select>） 需要把 表單驗證屬性（required、maxlength）以及 事件（@blur）全部傳給子元件，同時保留外層的排版樣式。 FormItem.vue 手動過濾 on*，只把屬性交給子表單元件。
動態組件載入（<component :is="type">） 父層可能不知道最終渲染的實體是哪個元件，使用 $attrs 可以保證所有屬性/事件自動傳遞。 DynamicWrapper.vue 中 v-bind="$attrs"，不需要預先知道子元件的 props。
跨平台 UI（Web + Native） 在 web 端使用 <a>，在 native（如 Vue Native）使用 <TouchableOpacity>，兩者屬性不同但都需要接收父層傳入的屬性。 LinkWrapper.vue 根據平台切換渲染，仍使用 $attrs 轉發通用屬性。

總結

  • $attrs 是 Vue3 中統一管理「未聲明的屬性與事件」的核心工具，取代了 Vue2 的 $listeners。
  • 透過 inheritAttrs: false、v-bind="$attrs" 以及 useAttrs()，我們可以在 包裝元件、高階元件、動態組件 中靈活轉發或過濾資訊，減少樣板程式碼、提升可維護性。
  • 在實務開發時，避免過度依賴 $attrs，仍應在關鍵業務屬性上使用 props，並在文件中清楚說明可接受的屬性與事件。
  • 常見的陷阱包括 忘記關閉自動繼承、事件被吞掉、屬性衝突，只要遵循最佳實踐（明確聲明、適當過濾、合理合併），就能順利運用 $attrs 建構彈性且易於擴充的 Vue3 應用。

掌握 $attrs（以及隱含的 $listeners）的使用技巧，將讓你的 Vue3 專案在元件通信上更乾淨、更具可組合性，也更符合現代前端開發的最佳實踐。祝你寫程式開心，元件溝通無礙！ 🚀