文章目錄

• 一、追本溯源：兩個世界的“語言”差異

• 1.1 HTML 世界：大小寫不敏感的“寬容”天性
• 1.2 JavaScript 世界：大小寫敏感的“嚴謹”法則
• 1.3 “鴻溝”與“橋樑”：Vue 的命名轉換機制

• 二、核心規則：`kebab-case` 與 `camelCase` 的自動轉換

• 2.1 官方定義與實踐：黃金法則的具象化
• 2.2 轉換原理的通俗化闡釋
• 2.3 打破規則的後果：常見錯誤與潛在風險

• 錯誤一：在父組件模板中使用 `camelCase`
• 錯誤二：在子組件腳本中使用 `kebab-case`

• 2.4 轉換規則的可視化流程

• 三、命名約定與最佳實踐：寫出專業代碼的秘訣

• 3.1 `camelCase` 在 JavaScript 中的統治地位
• 3.2 `kebab-case` 在 HTML 中的必要性
• 3.3 命名規範速查表
• 3.4 特殊情況深度解析：數字與縮略詞

• 3.4.1 包含數字的 Prop
• 3.4.2 包含首字母縮略詞的 Prop

• 3.5 團隊協作中的規範落地

• 四、Props 驗證與 TypeScript：類型安全下的命名

• 4.1 命名約定與 Prop 驗證的協同工作
• 4.2 TypeScript 的強力加持：編譯時類型檢查

• 4.2.1 使用泛型定義 `defineProps`
• 4.2.2 運行時聲明與類型聲明的結合

• 4.3 類型安全下的命名轉換流程

• 五、高級場景與邊緣案例：探索 Prop 傳遞的邊界

• 5.1 動態 Props：`v-bind` 的威力
• 5.2 透傳 Attributes：`$attrs` 的繼承之旅
• 5.3 非Prop屬性：事件監聽器的命名轉換

• 六、常見陷阱與故障排除：成為 Prop 命名大師

• 6.1 “我的 Prop 是 `undefined`！”——故障排查清單
• 6.2 “我的樣式和類名沒有生效！”——與 `$attrs` 的愛恨情仇

• 陷阱一：多根節點組件的“選擇困難症”
• 陷阱二：`inheritAttrs: false` 的“獨立宣言”

• 6.3 動態 Prop 與響應式更新：數據流的“高速公路”

• 問題一：父組件數據變了，子組件沒反應？

• 七、總結與心智模型：內化 Prop 命名法則

• 7.1 核心思想回顧：一座橋，兩種語言
• 7.2 從“知道”到“做到”：將規範融入肌肉記憶
• 7.3 最終的啓示：約定優於配置

一、追本溯源：兩個世界的“語言”差異

要理解 Vue 中的 Props 大小寫問題，我們首先需要跳出 Vue 本身，去看看構成我們應用的兩大基石：HTML 和 JavaScript。它們在對待“大小寫”這個問題上，有着截然不同的“性格”。正是這種性格差異，催生了 Vue 中的命名約定。

1.1 HTML 世界：大小寫不敏感的“寬容”天性

HTML，作為超文本標記語言，其核心任務是描述網頁的結構。從它誕生之初，為了適應各種各樣的人和機器，它被設計得相當“寬容”。其中最顯著的一個特性就是：HTML 屬性名是大小寫不敏感的。

這意味着，在你的 HTML 文檔中，以下幾種寫法對於瀏覽器來説，是完全等價的：

<!-- 這三種寫法在瀏覽器看來一模一樣 -->
<div ID="myContainer" Class="wrapper">Hello World</div>
<div id="myContainer" class="wrapper">Hello World</div>
<div Id="MyContainer" CLASS="wrapper">Hello World</div>

瀏覽器在解析 HTML 時，會自動將所有的屬性名統一轉換為小寫形式進行處理。所以，無論你在源碼中寫成 ID、id 還是 Id，最終在瀏覽器的 DOM（文檔對象模型）樹中，它都會變成 id。

為什麼會這樣設計？

這主要源於歷史原因和標準規範。HTML 的前身 SGML（標準通用標記語言）本身就對大小寫不敏感。早期的網頁開發環境比較混亂，開發者使用的操作系統和編輯器五花八門，統一大小寫可以降低出錯概率，讓語言更易於上手。此外，HTML 規範明確規定，屬性名不區分大小寫，這保證了所有瀏覽器廠商都能實現統一的行為，確保網頁的跨平台兼容性。

對我們前端開發者意味着什麼？

這意味着，當我們在 Vue 模板中書寫 HTML 時，我們實際上是在一個“大小寫不敏感”的環境裏。我們寫的 my-prop 和 myProp，瀏覽器接收到的都是 myprop（注意，是全部小寫）。這個認知至關重要，它是理解後續一切規則的出發點。

1.2 JavaScript 世界：大小寫敏感的“嚴謹”法則

與 HTML 的“寬容”截然相反，JavaScript 作為一門編程語言，表現得極為“嚴謹”。在 JavaScript 的世界裏，一切標識符（包括變量名、函數名、屬性名等）都是大小寫敏感的。

看下面這個簡單的例子：

// 這三個是完全不同的變量
let myVariable = 'I am lowercase';
let MyVariable = 'I am capitalized (PascalCase)';
let myvariable = 'I am all lowercase';

console.log(myVariable); // 輸出: 'I am lowercase'
console.log(MyVariable); // 輸出: 'I am capitalized (PascalCase)'
console.log(myvariable); // 輸出: 'I am all lowercase'

試圖訪問一個大小寫不匹配的變量，會導致 undefined，甚至在嚴格模式下可能引發錯誤。這種嚴謹性是編程語言的基石，它保證了代碼的精確性和可預測性。

在 Vue 中，我們在哪裏與這個“嚴謹”的世界打交道？

主要在兩個地方：

1. <script setup> 或 setup() 函數：我們在這裏定義組件的邏輯、數據、方法等。所有的變量、函數、props 定義都遵循 JavaScript 的大小寫敏感規則。
2. 模板中的表達式：雖然在模板裏，但 {{ }} 插值、v-bind 的值等，本質上都是 JavaScript 表達式，它們同樣遵循大小寫敏感的規則。

1.3 “鴻溝”與“橋樑”：Vue 的命名轉換機制

現在，問題變得清晰了。我們有兩個世界：

當 Vue 組件運行時，它需要在這兩個世界之間架起一座橋樑。父組件通過 模板 傳遞數據，子組件通過 腳本 接收數據。數據在傳遞過程中，必須經過一次“翻譯”，才能確保從“大小寫不敏感”的世界安全抵達“大小寫敏感”的世界。

Vue 的設計者們為我們提供了一個非常優雅且自動化的解決方案：命名轉換機制。

這個機制的核心規則可以概括為一句話：

在父組件的模板中使用 kebab-case（短橫線命名法），在子組件的腳本中使用 camelCase（駝峯命名法）。

Vue 會自動將模板中的 kebab-case 屬性名，轉換為子組件接收時的 camelCase 變量名。

這個轉換過程就像一個盡職的翻譯官：

• 發送方（父組件模板）：用清晰、符合 HTML 習慣的 kebab-case 寫下地址，例如 user-profile-info。
• 翻譯官（Vue 內部）：看到 user-profile-info，自動將其翻譯成 JavaScript 世界更習慣的 userProfileInfo。
• 接收方（子組件腳本）：直接使用 userProfileInfo 這個變量，完美接收數據。

這個機制解決了兩個世界之間的“鴻溝”，讓我們可以在各自的世界裏使用最自然、最符合語言習慣的命名方式，而無需擔心數據傳遞的錯位。在接下來的章節中，我們將深入剖析這個“翻譯官”的工作細節，並探討在不同場景下如何最佳地利用它。

二、核心規則：kebab-case 與 camelCase 的自動轉換

我們已經瞭解了 Vue 命名轉換機制的背景和核心思想。現在，讓我們聚焦於這條黃金法則本身，通過具體的代碼示例和深入的原理分析，讓你徹底掌握它。

2.1 官方定義與實踐：黃金法則的具象化

Vue 官方文檔明確指出，當使用 DOM 模板時（也就是我們絕大多數情況下使用的 .vue 單文件組件中的模板部分），Prop 的名稱需要從 camelCase 轉換為 kebab-case。

讓我們通過一個最經典的“父傳子”示例來感受一下。

場景： 父組件 ParentComponent.vue 要向子組件 ChildComponent.vue 傳遞一個包含用户問候語的消息。

子組件 ChildComponent.vue (接收方):

<template>
  <div class="child-box">
    <!-- 在模板中，我們直接使用 JavaScript 中的駝峯命名 -->
    <h2>子組件收到的消息是: {{ initialMessage }}</h2>
  </div>
</template>

<script setup>
// 使用 <script setup> 語法糖
// 1. 使用 defineProps 來定義組件的 props
// 2. 在這裏，我們使用 camelCase (駝峯命名法) 來定義 prop 的名字
// 3. 這是一個對象形式的定義，我們可以指定類型和默認值，這是最佳實踐
const props = defineProps({
  // 定義一個名為 'initialMessage' 的 prop
  // 注意：這裏是 'initialMessage' (駝峯)
  initialMessage: {
    type: String,      // 規定它必須是字符串類型
    required: true,    // 規定它是必須傳遞的
    default: '默認值'  // 如果不是 required，可以設置默認值
  }
});

// 在腳本邏輯中，我們通過 props 對象來訪問它
// 訪問時也必須使用 camelCase
console.log('子組件腳本中收到的消息:', props.initialMessage); 
// 如果你在瀏覽器控制枱看，這裏會正確打印出父組件傳遞的值
</script>

<style scoped>
.child-box {
  border: 1px solid #42b983;
  padding: 20px;
  margin-top: 10px;
  border-radius: 8px;
}
</style>

父組件 ParentComponent.vue (發送方):

<template>
  <div class="parent-container">
    <h1>我是父組件</h1>
    <p>我準備向子組件傳遞一條消息...</p>
    
    <!-- 
      關鍵點在這裏！
      1. 我們引入並使用了 ChildComponent 組件
      2. 在傳遞 prop 時，我們必須使用 kebab-case (短橫線命名法)
      3. 將子組件中定義的 'initialMessage' 轉換為 'initial-message'
    -->
    <ChildComponent initial-message="你好，我是來自父組件的消息！" />
    
    <!-- 
      錯誤示範 (雖然某些情況下可能“看起來”能工作，但絕對不要這樣做！)
      <ChildComponent initialMessage="這是一個錯誤的示範" />
      我們會在 2.3 節詳細解釋為什麼這是錯誤的。
    -->
  </div>
</template>

<script setup>
// 導入子組件
import ChildComponent from './ChildComponent.vue';
</script>

<style scoped>
.parent-container {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
</style>

代碼分析與解讀：

1. 子組件定義 (ChildComponent.vue)：在 <script setup> 中，我們使用 defineProps 來聲明組件期望接收的 props。initialMessage 這個名字是標準的 camelCase，符合 JavaScript 的命名習慣，清晰易讀。
2. 父組件傳遞 (ParentComponent.vue)：在父組件的模板中，當我們給 <ChildComponent> 標籤添加屬性時，我們寫成了 initial-message。這是 kebab-case，完全符合 HTML 屬性的書寫風格。
3. Vue 的“魔法”：當 Vue 編譯父組件的模板時，它看到了 initial-message 這個屬性。在創建子組件實例並傳遞 props 的過程中，Vue 內部會執行一個類似 str.replace(/-([a-z])/g, (g) => g[1].toUpperCase()) 的轉換，將 initial-message 變成 initialMessage，然後精準地傳遞給子組件中定義的同名 prop。
4. 無縫銜接：子組件在模板和腳本中，都直接使用 initialMessage，完全感知不到父組件那邊是用 initial-message 傳過來的。這個轉換過程對開發者是透明的，極大地提升了開發體驗。

2.2 轉換原理的通俗化闡釋

我們可以把 Vue 的這個轉換過程想象成一個智能的“包裹分揀系統”。

• 包裹（數據）：你要傳遞的數據，比如字符串 "你好，我是來自父組件的消息！"。
• 發貨單（父組件模板中的屬性）：你在包裹上貼的發貨單，寫的是 initial-message。這個地址格式是給“快遞系統”（HTML 解析器）看的，它不關心大小寫，只認這種標準格式。
• 分揀中心（Vue 編譯器）：分揀中心的機器（Vue）掃描到發貨單上的 initial-message，它內部有一套規則：“凡是看到短橫線，就去掉短橫線，並把後面那個字母變成大寫”。於是，它自動將地址轉換成 initialMessage。
• 收件人（子組件腳本）：收件人（子組件的 defineProps）只認 initialMessage 這個地址。當分揀中心把包裹送到時，地址完全匹配，包裹（數據）就被成功簽收了。

這個比喻告訴我們，這個轉換不是隨意的，而是一套有章可循的、自動化的流程，確保了數據在兩個不同“命名規則”的區域間準確無誤地傳遞。

2.3 打破規則的後果：常見錯誤與潛在風險

瞭解了正確的做法，我們再來看看如果“任性”地打破規則，會發生什麼。這對於加深理解和避免踩坑至關重要。

錯誤一：在父組件模板中使用 camelCase

<!-- ParentComponent.vue 中的錯誤寫法 -->
<ChildComponent initialMessage="這會有問題嗎？" />

會發生什麼？

這取決於你的運行環境，但結果通常不是你想要的。

1. 瀏覽器解析：瀏覽器首先解析這段 HTML。由於 HTML 屬性不區分大小寫，initialMessage 會被瀏覽器統一看作 initialmessage（全小寫）。
2. Vue 接收：Vue 從瀏覽器解析後的 DOM 中讀取屬性，它拿到的是 initialmessage。
3. 轉換匹配：Vue 嘗試將 initialmessage 轉換為 camelCase。但 initialmessage 中沒有短橫線，所以轉換結果仍然是 initialmessage。
4. 尋找 Prop：Vue 去子組件的 defineProps 定義中尋找名為 initialmessage 的 prop。但子組件定義的是 initialMessage。
5. 最終結果：匹配失敗！子組件中的 props.initialMessage 將是 undefined（或者你設置的默認值）。數據傳遞失敗。

有沒有例外？

在某些情況下，比如使用字符串模板（非 DOM 模板）或者某些打包工具的優化下，這種寫法可能“僥倖”成功。但這是極不可靠的，完全依賴於底層實現，一旦環境變化（如升級 Vue 版本、更換構建工具），就會導致不可預知的 bug。因此，永遠不要在模板中使用 camelCase 來傳遞 props。

錯誤二：在子組件腳本中使用 kebab-case

// ChildComponent.vue 中的錯誤寫法
const props = defineProps({
  // 使用 kebab-case 定義 prop
  'initial-message': { 
    type: String,
    required: true
  }
});

// 如何訪問這個 prop？
// 你不能這樣寫：props.initial-message (語法錯誤)
// 你必須這樣寫：
console.log(props['initial-message']);

會發生什麼？

1. 定義成功：從技術上講，JavaScript 允許對象使用字符串作為鍵，所以 defineProps({ 'initial-message': ... }) 這種寫法本身是合法的。
2. 訪問困難：問題在於訪問。在 JavaScript 中，- 是減法操作符，所以 props.initial-message 會被解釋為 props.initial 減去 message，這顯然不是我們想要的。你必須使用方括號表示法 props['initial-message'] 來訪問它。
3. 可讀性與維護性差：這種寫法完全違背了 JavaScript 的命名習慣，代碼變得非常醜陋和不直觀。當其他開發者（或者未來的你）看到這段代碼時，會感到困惑。IDE 的代碼提示和自動補全功能也可能無法很好地工作。
4. 模板中使用：在子組件的模板中，你仍然需要寫 {{ initialMessage }}。Vue 在模板中會把 initialMessage 解析為 props.initialMessage，而 props.initialMessage 是 undefined。如果你想在模板中使用，你還得寫 {{ props['initial-message'] }}，這簡直是災難。

結論： 永遠不要在腳本中使用 kebab-case 來定義 props。這會破壞代碼的優雅性和可維護性。

2.4 轉換規則的可視化流程

為了更直觀地理解這個過程，我們可以用一個 流程圖來描繪數據從父組件到子組件的完整旅程。

子組件

Vue 編譯與運行時

父組件

屬性名轉為小寫

kebab-case -> camelCase

匹配成功

<script setup>

defineProps({ initialMessage: ... })

props.initialMessage = 'Hello'

<template>

{{ initialMessage }}

渲染 'Hello'

HTML 解析器

接收屬性名 'initial-message'

Vue Prop 轉換器

轉換後屬性名 'initialMessage'

定義數據

<script setup>

const msg = 'Hello'

<template>

<ChildComponent :initial-message='msg' />

這個流程圖清晰地展示了：

1. 父組件在模板中寫下 kebab-case 的屬性。
2. Vue 的內部機制將其轉換為 camelCase。
3. 子組件使用 camelCase 的定義來接收和使用這個 prop。

整個過程是單向且自動的，我們只需要遵守兩端的命名約定即可。

三、命名約定與最佳實踐：寫出專業代碼的秘訣

掌握了核心規則之後，我們來探討如何在實際項目中建立一套統一、高效的命名約定。這不僅僅是技術問題，更是團隊協作和項目長期維護的基石。

3.1 camelCase 在 JavaScript 中的統治地位

在 JavaScript 世界裏，camelCase（駝峯命名法）是變量和函數命名的絕對主流。為什麼？

• 可讀性高：getUserProfile 比 getuserprofile 或 get_user_profile（後者是 Python 等語言的風格）在視覺上更容易區分單詞。
• 符合語言習慣：絕大多數 JavaScript 內置 API 和流行的庫都採用 camelCase，如 querySelector、addEventListener、useState（React）等。遵循它能讓你的代碼與生態系統融為一體。
• IDE 友好：現代 IDE 和代碼編輯器對 camelCase 提供了極好的智能提示、自動補全和重構支持。

因此，在 Vue 組件的 <script> 部分，無論是 props、data、computed 還是 methods，都應堅定地使用 camelCase。

// 好的示例
const props = defineProps({
  userProfile: Object,
  isLoggedIn: Boolean,
  itemCount: {
    type: Number,
    default: 0
  }
});

const firstName = ref('');
const lastName = ref('');

const fullName = computed(() => `${firstName.value} ${lastName.value}`);

function submitForm() {
  // ...
}

3.2 kebab-case 在 HTML 中的必要性

同樣，在 HTML 模板中使用 kebab-case 也是不二之選。

• HTML 標準：雖然 HTML 屬性不區分大小寫，但 W3C 等標準化組織推薦使用小寫。kebab-case 是全小寫的，符合這一推薦。
• 避免歧義：myprop 和 myProp 在瀏覽器看來是一樣的，這可能導致混淆。而 my-prop 則是明確且唯一的。
• 可讀性：對於較長的名稱，user-profile-avatar-url 比 userprofileavatarurl 易讀得多。
• 與未來 HTML 屬性區分：萬一未來 HTML 標準引入了一個新的名為 userprofile 的全局屬性，你組件中使用的 userprofile prop 就會產生衝突。而使用 user-profile 則可以有效避免這種潛在的命名衝突。

3.3 命名規範速查表

為了方便你隨時查閲，這裏整理了一張詳細的命名規範速查表。

3.4 特殊情況深度解析：數字與縮略詞

3.4.1 包含數字的 Prop

當 Prop 名包含數字時，轉換規則依然完美工作。Vue 的轉換邏輯是尋找 - 後跟小寫字母的模式，數字不會干擾這個過程。

• 定義 (子組件): const props = defineProps({ chartData2: Array });
• 傳遞 (父組件): <MyChart :chart-data2="data" />
• 使用 (子組件模板): {{ chartData2.length }}

這個轉換過程是 chart-data2 -> chartData2，非常直觀。

3.4.2 包含首字母縮略詞的 Prop

這是一個稍微棘手一點的問題，比如 API、HTML、CPU 等。我們該如何命名？

方案一：將縮略詞視為一個普通單詞，全部小寫（推薦）

• 定義: apiKey -> api-key
• 定義: htmlContent -> html-content

優點：

• 一致性：轉換規則簡單明瞭，kebab-case 部分永遠是全小寫。
• 可讀性：api-key 非常清晰，沒有人會誤解。
• 社區主流：這是目前 Vue 社區和大多數項目中最廣泛採用的做法。

方案二：保留縮略詞的大小寫

• 定義: APIKey -> api-key
• 定義: HTMLContent -> html-content

問題：

• 不對稱性：你在 JS 中寫的是 APIKey，但在 HTML 中卻變成了 api-key。這種不對稱性可能會讓一些開發者感到困惑。
• 潛在的混亂：如果團隊裏有人寫 aPIKey，那在 HTML 中還是 api-key，但 JS 代碼就變得不統一了。

結論： 強烈推薦方案一。始終將縮略詞在 camelCase 中視為以小寫字母開頭的單詞。這能帶來最佳的代碼一致性和可維護性。

3.5 團隊協作中的規範落地

在一個團隊中，確保每個人都遵守命名規範至關重要。

1. 寫入團隊文檔：將命名規範明確寫入團隊的編碼風格指南中，作為新成員入職培訓和代碼審查的依據。
2. 利用自動化工具：這是最有效的方式。配置 ESLint，並使用 eslint-plugin-vue 插件。它內置了規則來強制執行 prop 的命名約定。

// .eslintrc.js
module.exports = {
  extends: [
    'plugin:vue/vue3-essential', // 或者 'plugin:vue/vue3-strongly-recommended'
    // ... 其他配置
  ],
  rules: {
    // 強制在組件定義中使用 camelCase
    'vue/prop-name-casing': ['error', 'camelCase'],
    // 強制在模板中使用 kebab-case (這個規則可能需要自定義或檢查插件是否支持)
    // 通常，這個規則是通過檢查 HTML 屬性來間接實現的
  }
};

配置好之後，任何不符合規範的代碼在保存或提交時都會被自動標記為錯誤，甚至可以配置成自動修復，從源頭上杜絕了不規範的寫法。

四、Props 驗證與 TypeScript：類型安全下的命名

隨着項目複雜度的提升，我們不再滿足於僅僅傳遞數據，我們還需要對數據進行驗證，確保組件接收到的數據是預期的類型和格式。Vue 3 與 TypeScript 的結合，更是將這種類型安全提升到了新的高度。在這一章，我們將探討命名約定如何與 Props 驗證和 TypeScript 完美融合。

4.1 命名約定與 Prop 驗證的協同工作

Prop 驗證是在子組件的 defineProps 中進行的。如前所述，這裏的命名必須使用 camelCase。驗證邏輯本身與命名轉換規則是解耦的，它只關心 camelCase 形式的 prop 名。

讓我們看一個更復雜的驗證示例：

子組件 AdvancedChild.vue:

<template>
  <div>
    <h3>高級子組件</h3>
    <p>用户名: {{ user.name }}</p>
    <p>權限級別: {{ user.role }}</p>
    <p>消息: {{ message }}</p>
    <p>計數值: {{ counter }}</p>
    <button @click="increment">+1</button>
  </div>
</template>

<script setup>
// 定義一個複雜的用户對象類型
const userPropsValidator = (value) => {
  // 自定義驗證函數
  return value && typeof value === 'object' && 'name' in value && 'role' in value;
};

const props = defineProps({
  // 1. 基礎類型檢查
  message: {
    type: String,
    required: true, // 必須傳遞
    validator: (value) => {
      // 自定義驗證器：消息長度必須大於5
      return value.length > 5;
    }
  },

  // 2. 複雜對象類型檢查
  user: {
    type: Object, // 也可以是 Array, Function 等
    // 使用自定義驗證函數進行更精細的控制
    validator: userPropsValidator,
    default: () => ({ name: 'Guest', role: 'visitor' }) // 對象/數組的默認值必須從一個工廠函數獲取
  },

  // 3. 多種可能的類型
  counter: {
    type: [Number, String], // 可以是數字或字符串
    default: 0
  },

  // 4. 自定義構造函數檢查
  // 假設我們有一個 Person 類
  // person: {
  //   type: Person,
  //   required: true
  // }
});

// 方法的定義
function increment() {
  // 注意：不能直接修改 props！
  // props.counter++; // 錯誤！
  // 正確的做法是 emit 一個事件，讓父組件來修改
  emit('update:counter', Number(props.counter) + 1);
}

// 定義組件可以觸發的事件
const emit = defineEmits(['update:counter']);
</script>

父組件 ParentForAdvanced.vue:

<template>
  <div>
    <h2>父組件</h2>
    <AdvancedChild
      :message="msg"
      :user="currentUser"
      :counter="count"
      @update:counter="count = $event"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import AdvancedChild from './AdvancedChild.vue';

const msg = ref('這是一條足夠長的消息');
const currentUser = ref({ name: 'Alice', role: 'admin' });
const count = ref(10);
</script>

代碼分析：

1. 命名與驗證分離：在 defineProps 中，message, user, counter 都是 camelCase。Vue 的驗證系統（type, required, validator）直接作用於這些 camelCase 的 prop 名。
2. 父組件傳遞：父組件模板中嚴格遵守 kebab-case 規則，:message -> :message (單字母無需轉換)，:user -> :user，:counter -> :counter。對於 v-model 或 .sync 的修飾符，如 @update:counter，事件名也遵循 camelCase -> kebab-case 的轉換。
3. 類型安全：即使沒有 TypeScript，通過 type 屬性和自定義 validator，我們也在運行時獲得了一層類型安全保障。如果父組件傳遞了錯誤類型的數據（比如給 message 傳了個數字），Vue 會在開發環境下向控制枱輸出警告。

4.2 TypeScript 的強力加持：編譯時類型檢查

Vue 3 對 TypeScript 提供了一流的支持，尤其是在 <script setup> 語法中。使用 TypeScript，我們可以將 Prop 的類型檢查從“運行時”提前到“編譯時”，在編碼階段就能發現錯誤。

4.2.1 使用泛型定義 defineProps

這是在 <script setup> 中使用 TypeScript 定義 props 的最現代、最簡潔的方式。

子組件 TypedChild.vue:

<template>
  <div>
    <p>標題: {{ title }}</p>
    <p>是否可見: {{ isVisible ? '是' : '否' }}</p>
    <p>元數據: {{ metadata }}</p>
  </div>
</template>

<script setup lang="ts">
// 1. 導入必要的類型
import type { PropType } from 'vue';

// 2. 定義一個接口來描述複雜對象的結構
interface Metadata {
  author: string;
  createdAt: Date;
  tags: string[];
}

// 3. 使用泛型定義 props
// 這裏的類型定義會自動被 Vue 用來進行運行時驗證
const props = defineProps<{
  // 簡單類型
  title: string;
  isVisible?: boolean; // ? 表示可選

  // 複雜類型
  metadata: Metadata;

  // 帶有默認值的 prop
  // 注意：泛型語法中無法直接設置默認值，需要使用 withDefaults
  pageCount: number;
}>();

// 4. 使用 withDefaults 為泛型定義的 props 設置默認值
// withDefaults 的第二個參數是一個對象，用於提供默認值
const propsWithDefaults = withDefaults(defineProps<{
  title: string;
  pageCount?: number; // 在這裏標記為可選
}>(), {
  // 為可選的 pageCount 提供默認值
  pageCount: 10
});

// 現在，在 TypeScript 的世界裏，props.title, props.metadata 等都具有了正確的類型
// IDE 會提供精確的代碼提示和類型檢查
console.log(props.metadata.author.toUpperCase()); // 安全，IDE 知道 author 是 string
// props.pageCount.toFixed(2); // 如果沒有 withDefaults，這裏可能報錯，因為 pageCount 可能是 undefined
propsWithDefaults.pageCount.toFixed(2); // 安全，因為有了默認值
</script>

父組件 ParentForTyped.vue:

<template>
  <div>
    <!-- 
      在父組件中，即使子組件用了 TypeScript，傳遞 props 的方式不變。
      仍然要使用 kebab-case。
    -->
    <TypedChild
      title="TypeScript 入門"
      :is-visible="true"
      :metadata="bookMeta"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import TypedChild from './TypedChild.vue';
import type { Metadata } from './TypedChild.vue'; // 可以導入類型以保持一致

// 這裏的數據也具有類型
const bookMeta = ref<Metadata>({
  author: 'Evan You',
  createdAt: new Date(),
  tags: ['vue', 'typescript', 'frontend']
});
</script>

解讀與優勢：

1. 編譯時檢查：當你在父組件中寫 <TypedChild :title="123" /> 時，TypeScript 編譯器（通過 Volar 插件）會立刻報錯，因為它知道 title 應該是一個 string。你無需運行應用就能發現這個錯誤。
2. 強大的類型推斷：在子組件內部，當你輸入 props. 時，IDE 會精確地提示 title, isVisible, metadata 等屬性，並且它們都帶有正確的類型信息。
3. 命名約定不變：注意，即使我們用 TypeScript 的 camelCase 定義了 title，在父組件模板中，我們仍然要寫 :title。這裏的 title 沒有短橫線，所以無需轉換。如果定義的是 bookTitle，模板中就要寫 :book-title。TypeScript 隻影響 <script> 部分的類型，不改變模板中的 kebab-case 約定。
4. 接口複用：通過 interface 或 type 定義複雜對象結構，可以在父子組件間共享，確保數據結構的一致性。

4.2.2 運行時聲明與類型聲明的結合

對於一些需要複雜運行時驗證（如自定義 validator 函數）的場景，我們可以將傳統的對象聲明與 TypeScript 類型聲明結合起來。

<script setup lang="ts">
import type { PropType } from 'vue';

// 定義類型
interface Post {
  id: number;
  title: string;
}

// 使用傳統的對象形式進行 defineProps
// 並通過泛型為這個 props 對象指定類型
const props = defineProps({
  // 為 postId 指定類型，並添加驗證
  postId: {
    type: Number as PropType<number>, // 使用 PropType 進行類型斷言
    required: true,
    validator: (value) => value > 0 // 自定義驗證：ID 必須是正數
  },
  // 為 post 對象指定類型
  post: {
    type: Object as PropType<Post>,
    required: true
  }
});

// props.post.id 仍然具有類型推斷
</script>

這種方式結合了兩者的優點：既有 TypeScript 的類型提示，又有強大的運行時驗證能力。

4.3 類型安全下的命名轉換流程

在 TypeScript 的加持下，我們的數據流變得更加堅固。下圖展示了這個增強版的流程：

graph TD
    subgraph 父組件
        A[<script setup lang="ts">] --> B{定義類型化數據};
        B --> C["const post: Post = { id: 1, title: '...' }"];
        C --> D[<template>];
        D --> E["<TypedChild :post-id="post.id" :post-title="post.title" />"];
    end

    subgraph Vue 編譯與運行時
        E --> F{HTML 解析器};
        F -- 屬性名轉為小寫 --> G["接收 'post-id', 'post-title'"];
        G --> H{Vue Prop 轉換器};
        H -- "kebab-case -> camelCase" --> I["轉換後 'postId', 'postTitle'"];
        I --> J{TypeScript 類型檢查};
        J -- 檢查父組件傳入值的類型 --> K{通過};
        J -- 類型不匹配 --> L{編譯時錯誤};
    end

    subgraph 子組件
        K --> M[<script setup lang="ts">];
        M --> N["defineProps<{ postId: number, postTitle: string }>()"];
        N -- 匹配成功 --> O["props.postId, props.postTitle 具有類型"];
        O --> P[<template>];
        P --> Q["{{ postTitle }}"];
        Q --> R[渲染];
    end

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style M fill:#ccf,stroke:#333,stroke-width:2px
    style J fill:#f99,stroke:#333,stroke-width:2px

這個流程圖增加了一個關鍵的“TypeScript 類型檢查”環節，它在編譯時就為我們保駕護航，確保了傳遞的數據不僅在命名上正確，在類型上也萬無一失。

五、高級場景與邊緣案例：探索 Prop 傳遞的邊界

掌握了基礎和最佳實踐後，讓我們來挑戰一些更復雜的場景。在這些場景中，Props 的命名轉換規則依然有效，但理解其背後的行為能幫助我們解決更棘手的問題。

5.1 動態 Props：v-bind 的威力

我們經常需要將一個對象中的所有屬性都作為 props 傳遞給子組件。這時，v-bind 的無參數語法（簡寫為 :）就派上了用場。

場景： 一個配置對象需要完整地傳遞給一個設置組件。

子組件 SettingsPanel.vue:

<template>
  <div class="settings">
    <h4>設置面板</h4>
    <p>主題: {{ theme }}</p>
    <p>字體大小: {{ fontSize }}px</p>
    <p>顯示通知: {{ showNotifications ? '開啓' : '關閉' }}</p>
  </div>
</template>

<script setup>
// 仍然使用 camelCase 定義 props
const props = defineProps({
  theme: {
    type: String,
    default: 'light'
  },
  fontSize: {
    type: Number,
    default: 16
  },
  showNotifications: {
    type: Boolean,
    default: false
  }
});
</script>

父組件 App.vue:

<template>
  <div>
    <h1>應用主界面</h1>
    <button @click="toggleTheme">切換主題</button>
    
    <!-- 
      關鍵點：v-bind 的無參數用法
      1. 我們有一個 JavaScript 對象 userSettings
      2. 這個對象的鍵是 camelCase (theme, fontSize, showNotifications)
      3. 我們使用 v-bind="userSettings" 將整個對象傳遞
    -->
    <SettingsPanel v-bind="userSettings" />
    
    <!-- 上面這行代碼等價於下面這行代碼 -->
    <!-- 
    <SettingsPanel 
      :theme="userSettings.theme"
      :font-size="userSettings.fontSize"
      :show-notifications="userSettings.showNotifications"
    />
    -->
  </div>
</template>

<script setup>
import { reactive } from 'vue';
import SettingsPanel from './SettingsPanel.vue';

// 這個對象的鍵是 camelCase，因為它是一個 JS 對象
const userSettings = reactive({
  theme: 'dark',
  fontSize: 18,
  showNotifications: true
});

function toggleTheme() {
  userSettings.theme = userSettings.theme === 'dark' ? 'light' : 'dark';
}
</script>

深度解析：

1. 對象鍵的命名：userSettings 是一個標準的 JavaScript 對象，它的鍵 theme, fontSize, showNotifications 遵循 camelCase 約定，這是最自然的做法。
2. Vue 的“二次翻譯”：當 Vue 遇到 v-bind="userSettings" 時，它並不會直接把這個對象扔給子組件。它會遍歷 userSettings 的每一個鍵值對，對每一個鍵執行一次“camelCase -> kebab-case”的轉換，然後再作為屬性傳遞給子組件。

• theme -> :theme
• fontSize -> :font-size
• showNotifications -> :show-notifications

3. 最終效果：這個過程和我們在模板中手動一個一個寫 :font-size="..." 是完全一樣的。v-bind 的無參數語法只是一個強大的語法糖，它自動完成了繁瑣的轉換工作。

這個特性非常強大，它讓我們可以在 JavaScript 中維護一個結構化的、camelCase 的配置對象，然後一鍵傳遞給子組件，同時還能享受到 Vue 自動轉換帶來的便利和正確性。

5.2 透傳 Attributes：$attrs 的繼承之旅

“透傳 Attributes”指的是，當一個組件以單個元素為根時，父組件傳遞給它的、但未被該組件聲明為 props 或 emits 的 attribute（如 class, style, id, 自定義屬性等）會被“透傳”到其根元素上。

場景： 我們創建一個自定義按鈕組件 MyButton，希望它能像原生 <button> 一樣接收 class, style, type, disabled 等屬性。

子組件 MyButton.vue:

<template>
  <!-- 
    1. 我們只聲明瞭一個 'btnType' prop
    2. 其他所有屬性，如 class, style, disabled, data-id 等，都沒有被聲明
    3. Vue 會自動將這些未聲明的屬性“透傳”到這個根元素 <button> 上
  -->
  <button class="base-btn" :class="btnClass">
    <slot />
  </button>
</template>

<script setup>
const props = defineProps({
  // 只聲明一個自定義的 prop
  btnType: {
    type: String,
    default: 'primary'
  }
});

// 根據 prop 計算一個 class
const btnClass = computed(() => `btn-${props.btnType}`);
</script>

<style>
.base-btn {
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
.btn-primary { background-color: #42b983; color: white; }
.btn-danger { background-color: #f44336; color: white; }
</style>

父組件 App.vue:

<template>
  <div>
    <!-- 
      傳遞給 MyButton 的屬性：
      - btn-type: 這是一個聲明的 prop
      - class: 這是一個未聲明的 attribute
      - style: 這是一個未聲明的 attribute
      - disabled: 這是一個未聲明的 attribute
      - data-testid: 這是一個未聲明的自定義 attribute
    -->
    <MyButton
      btn-type="danger"
      class="large-button"
      style="font-weight: bold;"
      disabled
      data-testid="submit-button"
    >
      點擊我
    </MyButton>
  </div>
</template>

<script setup>
import MyButton from './MyButton.vue';
</script>

渲染結果與命名分析：

最終渲染出的 HTML 會是：

<button class="base-btn btn-danger large-button" style="font-weight: bold;" disabled data-testid="submit-button">
  點擊我
</button>

發生了什麼？

1. btn-type="danger"：這是一個聲明的 prop。Vue 將其轉換為 btnType: 'danger'，傳遞給 MyButton 的腳本。腳本用它計算出 btnClass 為 btn-danger，並應用到 class 上。
2. class, style, disabled, data-testid：這些都不是 MyButton 聲明的 props。Vue 將它們收集到一個特殊的對象 $attrs 中。
3. 透傳：因為 MyButton 的模板只有一個根元素 <button>，Vue 會自動將 $attrs 對象中的所有屬性“展開”並應用到這個 <button> 元素上。
4. 命名轉換：在這個透傳過程中，命名轉換規則依然生效。如果你傳遞了一個 my-custom-attr，它會被添加到 <button> 上。如果你試圖傳遞 myCustomAttr，它會被瀏覽器（和Vue）視為 mycustomattr，這通常不是你想要的。

$attrs 的內部結構：

在 MyButton 的腳本中，你可以通過 useAttrs() 訪問 $attrs。

import { useAttrs } from 'vue';

const attrs = useAttrs();

console.log(attrs);
// 在開發模式下，你可能會看到類似這樣的對象：
// {
//   class: 'large-button',
//   style: { fontWeight: 'bold' },
//   disabled: '',
//   'data-testid': 'submit-button'
// }

注意，data-testid 在 $attrs 對象中是作為 'data-testid'（帶短橫線的字符串鍵）存在的。這再次證明了 Vue 在內部忠實地保留了 kebab-case 的形式，直到需要與 JavaScript 交互時才進行轉換。

5.3 非Prop屬性：事件監聽器的命名轉換

事件監聽器（如 @click）雖然不是 props，但它們的命名也遵循類似的轉換規則。

• 子組件觸發事件 ($emit)：在腳本中，事件名應使用 camelCase。
• 父組件監聽事件 (@)：在模板中，事件名應使用 kebab-case。

子組件 FormInput.vue:

<template>
  <input 
    type="text" 
    :value="modelValue" 
    @input="handleInput"
  />
</template>

<script setup>
const props = defineProps(['modelValue']);
const emit = defineEmits(['update:modelValue', 'clearInput']); // 使用 camelCase 聲明事件

function handleInput(e) {
  // 觸發 'update:modelValue' 事件
  emit('update:modelValue', e.target.value);
}

// 比如有一個清空按鈕的方法
function clear() {
  emit('clearInput'); // 觸發 'clearInput' 事件
}
</script>

父組件 App.vue:

<template>
  <div>
    <!-- 
      監聽事件時，使用 kebab-case
      @update:model-value -> 對應子組件的 'update:modelValue'
      @clear-input -> 對應子組件的 'clearInput'
    -->
    <FormInput 
      v-model="username" 
      @clear-input="username = ''"
    />
    <p>你輸入的是: {{ username }}</p>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import FormInput from './FormInput.vue';

const username = ref('');
</script>

這個規則與 props 的規則完全一致，確保了組件間通信（無論是 props down 還是 events up）的命名風格統一。

六、常見陷阱與故障排除：成為 Prop 命名大師

即便我們完全理解了規則，在實際開發中，由於各種複雜情況，仍然可能遇到問題。本章將作為一個“急救手冊”，幫助你快速定位和解決與 Props 命名相關的常見問題。

6.1 “我的 Prop 是 undefined！”——故障排查清單

這是最常見的問題。當你發現子組件沒有收到父組件傳遞的 prop，顯示為 undefined 時，不要慌張，按照以下清單逐一排查。

第一步：檢查父組件模板中的命名（kebab-case）

這是最可能的出錯點。

• 錯誤：<Child myUserInfo="..." />
• 正確：<Child my-user-info="..." />

仔細檢查你的屬性名，確保它是由小寫字母和短橫線組成的。這是 90% 的問題所在。

第二步：檢查子組件 defineProps 中的命名（camelCase）

如果父組件的命名沒問題，那麼問題可能出在接收方。

• 錯誤：defineProps({ 'my-user-info': String }) 或者 defineProps({ MyUserInfo: String })
• 正確：defineProps({ myUserInfo: String })

確認你在 defineProps 中使用的鍵是 camelCase。即使你用字符串鍵寫成了 'my-user-info'，雖然在 JS 中語法上可行，但在模板中訪問時會變得非常彆扭（props['my-user-info']），並且違背了最佳實踐。

第三步：檢查數據源本身

有時候，命名完全正確，但傳遞的數據本身就是 undefined。

<!-- ParentComponent.vue -->
<script setup>
import { ref } from 'vue';
import ChildComponent from './ChildComponent.vue';

const userData = ref(); // <-- 這裏忘了初始化，或者 API 請求還未完成

// 錯誤地傳遞了一個 undefined 的值
// <ChildComponent :user-info="userData" /> 
</script>

在父組件中，使用 console.log 或者 Vue DevTools 檢查你準備傳遞給子組件的那個變量，確保它確實有值。

第四步：檢查 Prop 驗證函數

自定義驗證函數可能在不經意間“背叛”了你。

// ChildComponent.vue
const props = defineProps({
  age: {
    type: Number,
    validator(value) {
      // 一個有 bug 的驗證器！
      // return value > 18; // 這個邏輯可能不符合預期
      return value > 0 && value < 150; // 更合理的邏輯
    }
  }
});

如果 validator 函數返回了 false，Vue 會在開發模式下拋出警告，並且該 prop 會被視為無效。檢查你的驗證邏輯，確保它在所有預期情況下都能返回 true。

第五步：檢查作用域和拼寫

這是一個低級但時有發生的錯誤。

<!-- ChildComponent.vue -->
<template>
  <!-- 拼寫錯誤！應該是 userInfo -->
  <div>{{ userInfomation }}</div> 
</template>

<script setup>
defineProps({
  userInfo: Object
});
</script>

在模板或腳本中訪問 prop 時，確保變量名拼寫正確，並且是在正確的作用域內（例如，在 <script setup> 中定義的 props 可以在模板和 <script setup> 的其他地方直接訪問）。

第六步：祭出終極大法——Vue DevTools

如果以上所有步驟都無法解決問題，那麼 Vue DevTools 是你最強大的盟友。

1. 在瀏覽器中安裝 Vue DevTools 插件。
2. 打開你的應用，並激活 DevTools。
3. 在左側組件樹中選擇你的子組件。
4. 在右側面板中，你會看到幾個選項卡，點擊 “Props”。

(這是一個示意圖，實際界面可能略有不同)

在這裏，你可以清晰地看到：

• 子組件期望接收的 Props：列表中會顯示所有通過 defineProps 聲明的 prop。
• 實際接收到的值：每個 prop 對應的值。
• 傳遞來源：有時會顯示是從哪個父組件傳遞過來的。

如果某個 prop 顯示為 undefined，但你在父組件模板中確實傳遞了，那麼幾乎可以肯定是命名轉換出了問題。DevTools 能讓你一目瞭然地看到數據流在哪一環斷裂了。

6.2 “我的樣式和類名沒有生效！”——與 $attrs 的愛恨情仇

你給一個自定義組件傳遞了 class 或 style，期望它能像普通 HTML 元素一樣應用這些樣式，但渲染出來卻“毫髮無損”。這通常與“透傳 Attributes”和組件的根節點結構有關。

陷阱一：多根節點組件的“選擇困難症”

在 Vue 3 中，組件可以有多個根節點。這帶來了更大的佈局靈活性，但也給透傳 Attributes 帶來了一個難題：Vue 不知道該把這些未聲明的屬性（如 class, style）傳給哪個根元素。

默認行為： 對於多根節點組件，透傳 Attributes 不會自動應用，你需要手動指定。

示例：

<!-- MultiRootCard.vue -->
<template>
  <!-- 這個組件有兩個根節點 -->
  <div class="card-header">
    <slot name="header"></slot>
  </div>
  <div class="card-body">
    <slot></slot>
  </div>
</template>

<script setup>
// 沒有聲明任何 props
</script>

父組件使用：

<template>
  <!-- 我們期望這個 red-border 類能應用上去 -->
  <MultiRootCard class="red-border">
    <template #header>標題</template>
    <p>這是卡片內容。</p>
  </MultiRootCard>
</template>

<style>
.red-border {
  border: 2px solid red;
}
</style>

結果： 你會發現 red-border 這個類名沒有出現在任何地方。<div class="card-header"> 和 <div class="card-body"> 都沒有這個類。

解決方案：手動指定 v-bind="$attrs"

你需要明確告訴 Vue：“請把所有透傳屬性都放在這個元素上。”

<!-- MultiRootCard.vue (修復版) -->
<template>
  <!-- 
    我們決定將所有透傳屬性（包括 class, style 等）都應用到 card-body 上
    注意：v-bind="$attrs" 是一個特殊用法，它會將一個對象的所有屬性展開到當前元素上
  -->
  <div class="card-header">
    <slot name="header"></slot>
  </div>
  <div class="card-body" v-bind="$attrs">
    <slot></slot>
  </div>
</template>

現在，red-border 類就會被正確地應用到 <div class="card-body"> 上。你也可以選擇只傳遞 class 和 style：:class="$attrs.class" :style="$attrs.style"，但 v-bind="$attrs" 更為簡潔和全面。

陷阱二：inheritAttrs: false 的“獨立宣言”

有時候，我們可能不希望任何透傳屬性被自動應用到根元素上，而是想完全控制它們的應用位置。這時，我們可以在腳本中顯式地禁用默認的繼承行為。

場景： 創建一個自定義輸入框組件，我們希望 class 和 style 應用在外層的 div 包裝器上，而 placeholder, disabled 等屬性應用在內部的 <input> 元素上。

<!-- CustomInput.vue -->
<template>
  <!-- 
    1. 因為我們設置了 inheritAttrs: false，class 和 style 不會自動應用到根 div
    2. 我們手動將 class 和 style 綁定到包裝器 div
    3. 我們使用 v-bind="$attrs" 將其他所有屬性（如 placeholder, disabled）綁定到 input 元素
  -->
  <div class="input-wrapper" :class="$attrs.class" :style="$attrs.style">
    <label v-if="label">{{ label }}</label>
    <input v-bind="$attrs" :value="modelValue" @input="$emit('update:modelValue', $event.target.value)" />
  </div>
</template>

<script setup>
// 定義組件選項，包括 inheritAttrs
defineOptions({
  inheritAttrs: false // 關鍵！禁用屬性自動繼承
});

defineProps({
  label: String,
  modelValue: [String, Number]
});

defineEmits(['update:modelValue']);
</script>

<style scoped>
.input-wrapper {
  margin-bottom: 1em;
}
</style>

父組件使用：

<template>
  <!-- 
    傳遞的屬性：
    - class: large-input
    - style: color: blue;
    - placeholder: "請輸入用户名"
    - disabled
  -->
  <CustomInput
    v-model="username"
    label="用户名"
    class="large-input"
    style="color: blue;"
    placeholder="請輸入用户名"
    disabled
  />
</template>

渲染結果：

<div class="input-wrapper large-input" style="color: blue;">
  <label>用户名</label>
  <input placeholder="請輸入用户名" disabled>
</div>

通過 inheritAttrs: false，我們獲得了對透傳屬性的完全控制權，可以像搭積木一樣，精確地將它們分配給組件內部的任意元素。

6.3 動態 Prop 與響應式更新：數據流的“高速公路”

Props 是單向數據流：數據從父組件流向子組件。當父組件的數據發生變化時，子組件的 prop 應該會自動更新。但如果這個“高速公路”堵車了，該怎麼辦？

問題一：父組件數據變了，子組件沒反應？

這通常不是命名問題，而是響應式系統的問題。

原因 1：父組件傳遞的數據不是響應式的。

// ParentComponent.vue (錯誤示例)
import { ref } from 'vue';
import ChildComponent from './ChildComponent.vue';

let count = 0; // <-- 這是一個普通變量，不是響應式的！

function increment() {
  count++; // 修改普通變量，Vue 無法追蹤
}

即使你把 count 傳遞給子組件，count 的變化也不會觸發子組件的更新。

解決方案：確保數據源是響應式的。

// ParentComponent.vue (正確示例)
import { ref } from 'vue';
import ChildComponent from './ChildComponent.vue';

const count = ref(0); // <-- 使用 ref 包裝，使其成為響應式

function increment() {
  count.value++; // 修改 .value，Vue 可以追蹤到變化
}

使用 ref, reactive, computed 等 API 創建的數據才是響應式的，才能驅動視圖更新。

原因 2：子組件試圖直接修改 prop。

<!-- ChildComponent.vue (錯誤示例) -->
<script setup>
const props = defineProps({
  counter: Number
});

function incrementInChild() {
  props.counter++; // <-- 嚴重錯誤！不能直接修改 prop
}
</script>

Vue 會阻止這種直接修改，並在開發模式下給出警告。這破壞了單向數據流的原則，會讓數據流變得混亂不堪。

解決方案：通過事件通知父組件（“請求-響應”模式）

子組件不應該自己“做決定”，而應該向父組件“發請求”。

<!-- ChildComponent.vue (正確示例) -->
<template>
  <button @click="requestIncrement">+1</button>
  <p>當前值: {{ counter }}</p>
</template>

<script setup>
const props = defineProps(['counter']);
const emit = defineEmits(['update:counter']); // 聲明一個事件

function requestIncrement() {
  // 不直接修改，而是觸發一個事件，並告訴父組件想要的新值
  emit('update:counter', props.counter + 1);
}
</script>

父組件中使用 v-model（最佳實踐）

v-model 是處理這種雙向綁定需求的語法糖，它內部就是 :prop 和 @update:prop 的組合。

<!-- ParentComponent.vue -->
<template>
  <!-- 
    v-model:counter 相當於：
    :counter="count"
    @update:counter="newValue => count = newValue"
  -->
  <ChildComponent v-model:counter="count" />
</template>

通過這種方式，我們既遵守了 Props 的單向數據流原則，又實現了便捷的雙向綁定效果，代碼清晰且可維護。

狀態更新（父組件內部）：父組件在接收到事件後，更新自己的響應式數據，從而觸發新一輪的數據流。

掌握了這些故障排除技巧和響應式數據流的原則，你就能從容應對幾乎所有與 Props 相關的複雜問題，真正成為一名駕馭 Vue 組件通信的大師。

七、總結與心智模型：內化 Prop 命名法則

經過前面六個章節的深度探索，我們已經從語言特性、核心規則、最佳實踐、類型安全、高級場景到故障排除，全方位、多角度地剖析了 Vue 3 中的 Props 大小寫問題。現在，是時候將這些零散的知識點串聯起來，構建一個清晰、穩固的心智模型了。

7.1 核心思想回顧：一座橋，兩種語言

讓我們回到最初的那個比喻：Vue 組件是兩個世界的交匯點。

• 模板世界：使用 HTML 語言，特點是大小寫不敏感。這裏的“官方語言”是 kebab-case。它清晰、標準，與 HTML 生態完美融合。
• 腳本世界：使用 JavaScript 語言，特點是大小寫敏感。這裏的“官方語言”是 camelCase。它自然、高效，與 JS 生態無縫銜接。

Vue 的 Prop 命名轉換機制，就是架在這兩個世界之間的一座全自動、高精度的“翻譯橋”。

你不需要關心橋墩是如何澆築的，也不需要了解橋上的傳感器是如何工作的。你只需要記住並遵守兩邊的“交通規則”：

• 上橋前（父組件模板）：請説 kebab-case。
• 下橋後（子組件腳本）：請用 camelCase。

只要你遵守了規則，Vue 這座橋就能保證你的數據（信使）安全、準確地送達。這個心智模型可以讓你在面對任何 Prop 傳遞場景時，都能迅速做出正確的判斷。

7.2 從“知道”到“做到”：將規範融入肌肉記憶

僅僅“知道”規則是不夠的，真正的專業體現在“做到”，並將其內化為一種本能。

1. 刻意練習：在接下來的一週裏，每次寫組件時，都刻意地在心中默唸一遍規則：“模板 kebab-case，腳本 camelCase”。剛開始可能會覺得有點慢，但很快就會形成習慣。
2. 代碼審查：在參與團隊代碼審查時，將 Prop 命名規範作為一項重要的檢查點。幫助他人糾正錯誤的同時，也能加深自己的理解。
3. 擁抱工具：我們之前提到了 ESLint 和 Vue DevTools。請務必在你的項目中配置好它們。讓機器來強制執行規範，遠比靠人的自覺性要可靠得多。當 ESLint 自動將你寫錯的 myUserInfo 糾正為 my-user-info 時，這個反饋循環會極大地加速你的學習過程。
4. 閲讀優秀源碼：去 GitHub 上找一些知名的、高質量的 Vue 3 開源項目（如 Vite, Nuxt UI, Element Plus 等）。看看它們是如何命名 Props 的。通過閲讀高手的代碼，你可以學到很多約定俗成的細節和技巧。

7.3 最終的啓示：約定優於配置

Vue 的 Prop 命名轉換機制，完美體現了軟件工程中一個重要的設計哲學：約定優於配置。

框架沒有提供一個複雜的配置選項讓你去自定義轉換規則（比如，你可以配置成用 snake_case 嗎？）。相反，它提供了一套簡單、明確、唯一的約定。

這樣做的好處是巨大的：

• 降低心智負擔：你不需要做選擇，只需要遵循。這大大減少了開發中的猶豫和決策成本。
• 提升團隊效率：當團隊中所有人都遵循同一套約定時，代碼的可讀性和一致性會達到一個非常高的水平。任何人接手別人的代碼，都能快速上手。
• 構建強大的生態系統：正是因為有了統一的約定，Vue 的插件、組件庫、工具鏈才能高效地協同工作。

理解了這一點，你就會明白，遵守 Prop 命名規範，不僅僅是為了避免 bug，更是為了成為 Vue 生態系統中一個“合格”的公民，享受這個生態系統帶來的所有便利。

至此，我們對 Vue 3 Props 大小寫問題的探索之旅已接近尾聲。我們從最基礎的語言差異出發，深入到框架的核心機制，再到實際項目中的最佳實踐、高級應用和故障排除，最終上升到了設計哲學的層面。