vue-best-practices

Vue 最佳實務工作流程

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

核心原則

• 保持狀態可預測： 單一事實來源，其餘皆由此推導。
• 讓資料流明確： 大部分情況使用 Props 向下傳遞，事件向上觸發。
• 偏好小型、專注的元件： 更容易測試、重複使用和維護。
• 避免不必要的重新渲染： 明智地使用 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 編碼前規劃元件邊界（必要）

對於任何非單純的功能，在實作前先建立簡短的元件對應圖。

• 用一句話定義每個元件的單一職責。
• 預設將進入點/根元件和路由層級檢視元件作為組合表面。
• 將功能 UI 和功能邏輯移出進入點/根/檢視元件，除非任務刻意是小型單一檔案示範。
• 在對應圖中為每個子元件定義 props/emits 合約。
• 當新增超過一個元件時，偏好功能資料夾佈局（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 區段）時，將其拆分。

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

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

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

進入點/根和路由檢視規則：

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

元件資料流

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

Composables

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

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

3.1 標準選擇性功能

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

• Slots：父元件需要控制子元件內容/佈局 -> component-slots
• Fallthrough 屬性：包裝器/基礎元件必須安全地轉發 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 較不常見的選擇性功能

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

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

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

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

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

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

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