Vue3 事件名稱大小寫轉換機制

子元件這樣送出事件：

this.$emit('changeSource')

父元件卻這樣接：

<MyComponent @change-source="onChangeSource" />

然後，竟然可以正常運作。

這篇文章會完整拆解 Vue 3 的事件名稱大小寫轉換機制，並對照 Vue 2 的差異，最後給出團隊可落地的命名與 lint 建議。

先講結論

  1. 在 Vue 3，emit('changeSource') 與 @change-source 可以互相對應，這是官方支援行為。[1]
  2. 在 Vue 2，官方文件明確說明自訂事件名稱不會自動做大小寫轉換；若命名不一致會監聽不到。[2]
  3. 即使在 Vue 3，官方仍建議在 template 裡使用 kebab-case 事件名稱，以維持一致性與可讀性。[1]

Vue 2 與 Vue 3 差在哪裡？

Vue 2：名稱必須精準匹配

Vue 2 文件指出，自訂事件名稱不會像 component / prop 一樣做自動大小寫轉換；如果你 emit myEvent，監聽 my-event 通常不會生效。[2]

此外，Vue 2 文件也提到：在 DOM template 情境下，HTML attribute 名稱不分大小寫，可能導致大小寫事件名更容易踩雷，因此建議使用 kebab-case。[2]

Vue 3：camelCase 與 kebab-case 可對應

Vue 3 官方文件在 Component Events 明確示範：子元件 emit camelCase 事件時，父元件可用 kebab-case 監聽，且官方建議 template 使用 kebab-case 保持一致。[1]

這個設計把事件命名行為往 props 的使用體驗靠攏，減少因大小寫不一致造成的溝通與維護成本。

實作範例（Vue 3）

子元件

<script setup>
const emit = defineEmits(['changeSource'])

function updateSource() {
  emit('changeSource', { from: 'A', to: 'B' })
}
</script>

<template>
  <button @click="updateSource">Change</button>
</template>

父元件

<template>
  <ChildComponent @change-source="handleChangeSource" />
</template>

<script setup>
function handleChangeSource(payload) {
  console.log(payload)
}
</script>

以上在 Vue 3 是可行且常見的寫法。[1]

什麼時候還是會出問題？

  1. 專案混用 Vue 2 與 Vue 3 語法認知，導致錯誤套用規則。
  2. 事件名稱拼字不同（不是大小寫問題，而是字串不同），例如 change-source vs source-change。
  3. 沒有宣告 emits（或 defineEmits）時，團隊很難從型別與 lint 提前發現錯字。

團隊最佳實踐

  1. Template 一律用 kebab-case：@change-source。

  2. 事件宣告集中管理：使用 emits 或 defineEmits，降低拼字錯誤。

  3. 加上 lint 約束：

  • vue/v-on-event-hyphenation：規範 template 事件監聽名稱格式。[4]

  • vue/custom-event-name-casing：規範自訂事件名稱風格。[5]

  1. 文件化命名策略：在專案 README 或 Contributing Guide 寫清楚「JS 端 emit 與 template 端 listener 的命名約定」。

延伸：emits 在 Vue 3 的價值

Vue 3 migration guide 指出，Vue 3 引入 emits 選項，讓元件能明確宣告可以送出的事件。[3]

這不只是語法糖，而是可維護性升級：

  1. 元件對外事件介面更清楚。
  2. 搭配型別與工具鏈更容易發現不合法事件。
  3. 在大型團隊合作時，可降低「事件名稱靠默契」造成的錯誤。

一份可直接採用的命名規範

  1. 事件語意使用動詞或動詞片語：submitted、change-source、dialog-opened。
  2. JS 內部若使用 camelCase emit（例如 emit('changeSource')），template 仍統一監聽 kebab-case（@change-source）。[1]
  3. 不使用縮寫與模糊詞（如 chgSrc），避免跨人員理解成本。

總結

你看到 this.$emit('changeSource') 能被 @change-source 接住，在 Vue 3 是預期行為，不是框架 bug。核心差異在於：

  1. Vue 2 對事件名稱大小寫更嚴格，需精準匹配。[2]
  2. Vue 3 支援 camelCase / kebab-case 對應，提升開發體驗。[1]
  3. 實務上仍建議 template 使用 kebab-case，並搭配 lint + emits 做一致化治理。[3][4][5]

參考資料

  1. Vue.js Official Docs, Component Events
    https://vuejs.org/guide/components/events
    存取日期：2026-04-12

  2. Vue 2 Official Docs, Custom Events (Event Names)
    https://v2.vuejs.org/v2/guide/components-custom-events.html
    存取日期：2026-04-12

  3. Vue 3 Migration Guide, emits Option
    https://v3-migration.vuejs.org/breaking-changes/emits-option.html
    存取日期：2026-04-12

  4. eslint-plugin-vue, vue/v-on-event-hyphenation
    https://eslint.vuejs.org/rules/v-on-event-hyphenation
    存取日期：2026-04-12

  5. eslint-plugin-vue, vue/custom-event-name-casing
    https://eslint.vuejs.org/rules/custom-event-name-casing.html
    存取日期：2026-04-12

  6. GitHub Issue, camelCase events can be listened to in the kebab-case (#656)
    https://github.com/vuejs/docs/issues/656
    存取日期：2026-04-12

留言

張貼留言

這個網誌中的熱門文章

《我們為什麼要讀書？為什麼要工作？》讀後感

「一生至少要讀一次！」這句書腰宣傳詞確實刷新了讀者對金錢的觀念。社會文化與風氣深植於每個人心中，而本書體現的觀點極具前瞻性：它將個人置於社會整體中，具體化了「每個人都是社會螺絲釘」的精神，從社會運作的維度闡述工作的本質與金錢的意義。儘管我不確定日本現實文化是否完全如書中所言，但第一章帶來的文化衝擊已足夠顯著；若以此書的理想框架審視台灣社會，兩者間的巨大落差反映出本土勞動環境中存在的結構性失衡。 書中主張工作即是「為他人提供服務」，而薪水則是「因服務他人而獲得的感謝」。每個人透過消費與勞動參與世界運作：消費時接受服務，工作時則轉為服務者，並以此換取消費的籌碼。這種「互為服務、互表感謝」的循環，構成了社會運作的底層邏輯。 關於日本文化的「委婉」，書中第三章提供了另一種詮釋視角。這源於對特質「一體兩面」的觀察，例如「雞婆」的反面即是「體貼」。這種能同時觀看優缺點兩極的文化視角，也延伸到了職業選擇：熱愛足球不一定要成為選手，亦能透過運動記者、經紀人或物理治療師等關聯職業參與其中；即便工作與愛好完全無關，亦不損其價值。 本書以漫畫形式呈現，即便國小學生也能輕鬆閱讀。雖然其論述的觀念帶有理想色彩，且部分邏輯在當前台灣社會實踐上仍面臨阻礙，但對於正處於社會化過渡期的大學生而言，它重新定義了工作的觀念，並為理解世界運作提供了更趨於理想的全新觀點。
閱讀完整內容

違停應以排除干擾為目的——檢討拍照檢舉制度之正當性

違規停車是台灣交通治理的長期挑戰。近年民眾檢舉制度普及，雖補足了警力缺口，卻也引發執法本質的辯論：檢舉制度應是改善交通的工具，還是淪為純粹的追罰機制？我們必須從比例原則審視其正當性。 一、 執法的核心價值：排除侵害而非單純懲罰   交通執法的首要目的在於維護公共空間的流暢與安全。處理違停應以「有效排除干擾」為先，而非將「違法必罰」視為唯一教條。警察在實務中常對駕駛人在場的違規行為優先採取驅離而非開罰，這並非怠惰，而是體現了行政法上的「最小侵害原則」。當勸導已能達成排除妨礙的目的時，處罰便不再具備必要性。 二、 警察職權的法理基礎與界限   雖然《警察職權行使法》與《道路交通管理處罰條例》賦予警察維持秩序的權力，但其行使必須符合目的正當性。參考德國警察法（Polizeirecht）的精神，行政機關介入的正當基礎在於消除對公共秩序的持續性干擾。若干擾可透過非強制手段即時解除，則行政機關應選擇對人民權利損害最小的手段。台灣執法實務中對輕微違規的勸導機制，正是承襲此種「優先恢復秩序」的法治邏輯。 三、 檢舉制度與即時性原則的落差   民眾檢舉制度存在顯著的時間滯後。從拍照到裁罰通知，往往間隔數日，此時違停車輛早已駛離，交通干擾不復存在。這種「事後追罰」已無法實現「即時排除危害」的功能，僅餘下對既往行為的報復性制裁。當執法手段無法達成預防或排除妨害的目的，其手段與目的間的連結便趨於薄弱，甚至偏離了行政法上的比例原則。 四、 效率與法治信賴的權衡   有人認為人在車上仍應受罰以示公平，但從資源配置角度，警察要求違規者立即駛離是成本最低、效率最高的秩序恢復方式。相較之下，過度依賴事後檢舉，不僅無法在第一時間疏解交通，更可能在社會中營造彼此監控的猜忌氛圍，損害人民對政府行政手段的信賴。 五、 結語：回歸秩序本位，重塑檢舉邊界   我們必須反思：執法是為了公共利益，還是為了累積罰單數量？拍照檢舉制度應定位為輔助即時執法的手段，而非脫離秩序排除本質的制裁工具。政府應審慎檢討檢舉案件的裁量標準，確保制度運作不違背法治國精神，將資源重新聚焦於「即時排除干擾」，方能建立真正健康且透明的交通秩序。
閱讀完整內容

《去你的博士學位》讀後感

  我是一名致力於學術研究的大學生，因為實驗室變革與研究所推甄失利，心中的研究之火已漸漸消去，甚至在心中燒出層層裂痕。我是不是不應該做研究？我做這麼多努力結果一場空，是不是我人生失敗了？ 我還在找尋人生的答案。 讀完柯曦答的《去你的博士學位》觸動很深，直得一讀再讀，女王的形象歷歷在目，身為僅在學術象牙塔打滾四餘年的小菜鳥，卻能體會那無法被理解的痛苦。 我曾經以為學術的世界是社會的清淨之地，只要我能在研究中做出一番成就，便能拋下社會的成見，成為人們口中的「成功人士」。但是，大家看到的出色的研究人員是倖存者偏差。在這個象牙塔內打滾數十年仍然無法出頭的人到處都是，半途而廢頂多是轉換跑道，更多的是想要往上爬卻無法成功的人。 我認為作者很幸運找到自己，找到離開象牙塔的出口。由衷感謝柯曦答願意撰寫這本書，將痛苦的回憶透過溫暖的文字與版畫凝結成一本能夠療癒同在煉獄的讀者。輯一到輯四讓我重新審視我過去的努力與現在得到的結果，〈學做人〉輯溫暖的收尾，並鼓勵自己成為一個更好的人。表面上是作者自述，實則讓我感到溫暖，我彷彿獲得作者大大的擁抱，是我心靈的慰藉。 其實，我不太常看心靈勵志書籍，因為大多都過於濫情與高大上。但是這本書卻深深直擊我心。一閱讀完便撰寫此文，將心中的悸動用文字留下，讓柯曦答的這份溫暖替代。 「真的走不下去，衝撞體制，撞得頭破血流變當機立斷吧。」是我書中感觸最深的一句話，就像是為我而寫的一樣，是小精靈在我腦中的建議。 高中、大學時期，我都頗受精神疾病所苦，讓我身心狀況極差，卻無法做出太多行動，因為我沒有勇氣放棄我得來不易的結果。看完這本書，我彷彿有了一絲勇氣。
閱讀完整內容