vue-best-practices

Vue 最佳實務工作流程

將此技能視為一組指令集。除非使用者明確要求不同順序，否則請依序遵循工作流程。

核心原則

• 保持狀態可預測： 單一事實來源，其餘皆由此推導。
• 讓資料流明確： 大部分情況使用 Props 向下、Events 向上。
• 偏好小型、專注的元件： 更容易測試、重用和維護。
• 避免不必要的重新渲染： 明智地使用 computed 屬性和 watcher。
• 可讀性至上： 撰寫清晰、自我說明的程式碼。

1) 編碼前確認架構（必要）

• 預設技術棧：Vue 3 + Composition API + <script setup lang="ts">。
• 如果專案明確使用 Options API，則載入 vue-options-api-best-practices 技能（若可用）。
• 如果專案明確使用 JSX，則載入 vue-jsx-best-practices 技能（若可用）。

1.1 必讀核心參考（必要）

• 在實作任何 Vue 任務之前，請務必閱讀並套用以下核心參考：
  • references/reactivity.md
  • references/sfc.md
  • references/component-data-flow.md
  • references/composables.md
• 在整個任務期間，將這些參考保留在活躍的工作上下文中，而不僅在特定問題出現時才參考。

1.2 編碼前規劃元件邊界（必要）

對於任何非平凡的 feature，在實作前建立簡短的元件對應圖。

• 用一句話定義每個元件的單一職責。
• 預設將 entry/root 和路由層級的檢視元件作為組合表面。
• 將 feature UI 和 feature 邏輯移出 entry/root/view 元件，除非任務刻意是小型單一檔案示範。
• 在對應圖中定義每個子元件的 props/emits 合約。
• 當新增超過一個元件時，偏好使用 feature 資料夾佈局（components/<feature>/...、composables/use<Feature>.ts）。

2) 套用必要的 Vue 基礎（必要）

這些是必要且必須了解的基礎。使用已在第 1.1 節載入的核心參考，在每個 Vue 任務中套用所有這些基礎。

響應性

• 來自 1.1 的必讀參考：reactivity
• 保持來源狀態最小化（ref/reactive），盡可能使用 computed 推導其餘部分。
• 必要時使用 watcher 處理副作用。
• 避免在模板中重新計算昂貴的邏輯。

SFC 結構與模板安全

• 來自 1.1 的必讀參考：sfc
• 保持 SFC 區段順序為：<script> → <template> → <style>。
• 保持 SFC 職責專注；拆分大型元件。
• 保持模板宣告式；將分支/推導移至 script。
• 套用 Vue 模板安全規則（v-html、列表渲染、條件渲染選擇）。

保持元件專注

當元件具有超過一個明確職責時（例如資料編排 + UI，或多個獨立 UI 區段），則拆分元件。

• 偏好較小的元件 + composable，而非單一「巨型元件」
• 將 UI 區段移至子元件（props 傳入、events 傳出）。
• 將狀態/副作用移至 composable（useXxx()）。

套用客觀的拆分觸發條件。如果任何條件成立，則拆分元件：

• 它同時擁有編排/狀態和多個區段的大量呈現標記。
• 它有 3 個以上不同的 UI 區段（例如：表單、篩選器、列表、頁尾/狀態）。
• 模板區塊重複或可能變得可重用（項目行、卡片、列表條目）。

Entry/root 和路由檢視規則：

• 保持 entry/root 和路由檢視元件精簡：應用程式外殼/佈局、provider 接線和 feature 組合。
• 當 feature 包含獨立部分時，不要將完整的 feature 實作放在 entry/root/view 元件中。
• 對於 CRUD/列表 feature（待辦事項、表格、目錄、收件匣），至少拆分為：
  • feature 容器元件
  • 輸入/表單元件
  • 列表（和/或項目）元件
  • 頁尾/動作或篩選器/狀態元件
• 僅對非常小的拋棄式示範允許單一檔案實作；如果選擇此方式，請明確說明為何不需要拆分。

元件資料流

• 來自 1.1 的必讀參考：component-data-flow
• 使用 props 向下、events 向上作為主要模型。
• 僅對真正的雙向元件合約使用 v-model。
• 僅對深層樹狀依賴或共享上下文使用 provide/inject。
• 保持合約明確並使用 defineProps、defineEmits 和 InjectionKey 進行型別化（視需要）。

Composables

• 來自 1.1 的必讀參考：composables
• 當邏輯被重用、有狀態或副作用較重時，將其提取到 composable 中。
• 保持 composable API 小型、型別化且可預測。
• 將 feature 邏輯與呈現元件分離。

3) 僅在需求要求時考慮選擇性功能

3.1 標準選擇性功能

預設不要加入這些功能。僅在需求存在時載入對應的參考。

• Slots：父元件需要控制子元件內容/佈局 -> component-slots
• Fallthrough attributes：包裝器/基礎元件必須安全地轉發 attrs/events -> component-fallthrough-attrs
• 內建元件 <KeepAlive> 用於有狀態的檢視快取 -> component-keep-alive
• 內建元件 <Teleport> 用於覆蓋層/入口 -> component-teleport
• 內建元件 <Suspense> 用於非同步子樹的 fallback 邊界 -> component-suspense
• 動畫相關功能：選擇最簡單且符合所需動作行為的方法。
  • 內建元件 <Transition> 用於進場/離場效果 -> transition
  • 內建元件 <TransitionGroup> 用於動畫列表變更 -> transition-group
  • 基於 class 的動畫用於非進場/離場效果 -> animation-class-based-technique
  • 狀態驅動動畫用於使用者輸入驅動的動畫 -> animation-state-driven-technique

3.2 較不常見的選擇性功能

僅在有明確的產品或技術需求時使用這些功能。

• Directives：行為是 DOM 特定的，且不適合 composable/component -> directives
• 非同步元件：重量級/不常使用的 UI 應延遲載入 -> component-async
• 僅在模板無法表達需求時使用 Render functions -> render-functions
• 當行為必須在應用程式範圍內安裝時使用 Plugins -> plugins
• 狀態管理模式：應用程式範圍的共享狀態跨越 feature 邊界 -> state-management

4) 在行為正確後執行效能最佳化

效能工作是功能完成後的步驟。在核心行為實作並驗證之前，不要進行最佳化。

• 大型列表渲染瓶頸 -> perf-virtualize-large-lists
• 靜態子樹不必要地重新渲染 -> perf-v-once-v-memo-directives
• 熱門列表路徑中的過度抽象 -> perf-avoid-component-abstraction-in-lists
• 昂貴的更新觸發過於頻繁 -> updated-hook-performance

5) 完成前的最終自我檢查

• 核心行為正常運作且符合需求。
• 所有必讀參考都已閱讀並套用。
• 響應性模型最小化且可預測。
• 遵循 SFC 結構和模板規則。
• 元件專注且重構良好，必要時進行拆分。
• Entry/root 和路由檢視元件保持為組合表面，除非有明確的小型示範例外。
• 元件拆分決策明確且可辯護（職責邊界清晰）。
• 資料流合約明確且型別化。
• 在重用/複雜性合理的情況下使用 Composables。
• 如果適用，將狀態/副作用移至 composable。
• 僅在需求要求時使用選擇性功能。
• 僅在功能完成後才套用效能變更。