Angular 開發者指南
-
在提供建議前，請務必分析專案的 Angular 版本，因為不同版本間的最佳實務與可用功能差異很大。若使用 Angular CLI 建立新專案，除非使用者明確指定版本，否則不要指定版本號。
-
產生程式碼時，請遵循 Angular 的樣式指南與最佳實務，以確保可維護性與效能。使用 Angular CLI 來生成元件、服務、指令、管道與路由，以維持一致性。
-
完成程式碼生成後，請執行
ng build以確認沒有建置錯誤。若有錯誤，請分析錯誤訊息並修正後再繼續。請勿跳過此步驟，因為這對於確保所產生程式碼的正確性與功能性至關重要。
建立新專案
若使用者未提供任何指引，以下是建立新 Angular 專案的預設規則：
- 除非使用者另有指定，否則使用最新的穩定版 Angular。
- 在新專案中偏好使用 Signal Forms 進行表單管理（適用於 Angular v21 及更新版本）了解更多。
ng new 的執行規則：
當要求建立新的 Angular 專案時，您必須依照以下嚴謹步驟決定正確的執行指令：
步驟 1：檢查是否有明確的使用者版本要求。
- 如果使用者要求特定版本（例如 Angular 15），請繞過本地安裝，嚴格使用
npx。 - 指令：
npx @angular/cli@<要求的版本> new <專案名稱>
步驟 2：檢查是否已安裝 Angular。
- 如果未要求特定版本，請在終端機中執行
ng version，檢查系統中是否已安裝 Angular CLI。 - 如果指令成功並回傳已安裝的版本，請直接使用本地/全域安裝。
- 指令：
ng new <專案名稱>
步驟 3：回退至最新版。
- 如果未要求特定版本且
ng version指令失敗（表示沒有 Angular 安裝），您必須使用npx取得最新版本。 - 指令：
npx @angular/cli@latest new <專案名稱>
元件
處理 Angular 元件時，請根據任務查閱以下參考資料：
- 基礎： 元件結構、中繼資料、核心概念與模板控制流程（@if、@for、@switch）。請閱讀 components.md
- 輸入： 基於 Signal 的輸入、轉換與模型輸入。請閱讀 inputs.md
- 輸出： 基於 Signal 的輸出與自訂事件最佳實務。請閱讀 outputs.md
- 宿主元素： 宿主綁定與屬性注入。請閱讀 host-elements.md
若上述參考資料中找不到更深入的文件，請閱讀 https://angular.dev/guide/components 上的文件。
反應性與資料管理
管理狀態與資料反應性時，請使用 Angular Signals 並查閱以下參考資料：
- Signals 概覽： 核心 Signal 概念（
signal、computed）、反應性上下文與untracked。請閱讀 signals-overview.md - 相依狀態（
linkedSignal）： 建立可寫入狀態並連結至來源 Signal。請閱讀 linked-signal.md - 非同步反應性（
resource）： 將非同步資料直接取得至 Signal 狀態中。請閱讀 resource.md - 副作用（
effect）： 記錄、第三方 DOM 操作（afterRenderEffect）以及何時不應使用 effect。請閱讀 effects.md
HTTP 通訊
與後端服務通訊時，請使用 Angular HTTP API 並查閱以下參考資料：
- HTTP 用戶端與資源：
provideHttpClient、HttpClient、攔截器與httpResource。請閱讀 http-client.md
表單
對於新應用程式，大部分情況下偏好使用 signal forms。在決定表單策略時，請分析專案並考慮以下指引：
-
若應用程式使用 v21 或更新版本，且這是新的表單，請偏好使用 signal forms。
-
對於較舊的應用程式或處理既有表單時，請使用與應用程式當前表單策略相符的適當表單類型。
-
Signal Forms： 使用 Signals 進行表單狀態管理。請閱讀 signal-forms.md
-
模板驅動表單： 適用於簡單表單。請閱讀 template-driven-forms.md
-
反應式表單： 適用於複雜表單。請閱讀 reactive-forms.md
依賴注入
實作 Angular 的依賴注入時，請遵循以下指引：
- 基礎： 依賴注入概觀、服務與
inject()函式。請閱讀 di-fundamentals.md - 建立與使用服務： 建立服務、
providedIn: 'root'選項，以及注入到元件或其他服務中。請閱讀 creating-services.md - 定義依賴提供者： 自動與手動提供、
InjectionToken、useClass、useValue、useFactory與範圍。請閱讀 defining-providers.md - 注入上下文： 允許使用
inject()的位置、runInInjectionContext與assertInInjectionContext。請閱讀 injection-context.md - 階層式注入器：
EnvironmentInjector與ElementInjector、解析規則、修飾詞（optional、skipSelf）以及providers與viewProviders。請閱讀 hierarchical-injectors.md
管道
在模板中格式化值、建立自訂管道或在 TypeScript 中重複使用管道邏輯時，請查閱以下參考資料。在模板中偏好使用管道；在模板外部，應避免為了呼叫 transform() 而注入管道類別。
- 管道： 內建管道匯入、自訂管道命名與實作、純粹與非純粹管道，以及使用獨立的格式化函式或提取的純函式在 TypeScript 中重複使用的模式。請閱讀 pipes.md
Angular Aria
為以下任何模式建置無障礙的自訂元件時：Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid，請查閱以下參考資料：
- Angular Aria 元件： 建立無頭且可存取的元件（Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid）以及樣式化 ARIA 屬性。請閱讀 angular-aria.md
路由
實作 Angular 的導航時，請查閱以下參考資料：
- 定義路由： URL 路徑、靜態與動態區段、萬用字元與重新導向。請閱讀 define-routes.md
- 路由載入策略： 立即載入與延遲載入，以及感知上下文的載入。請閱讀 loading-strategies.md
- 使用插座顯示路由： 使用
<router-outlet>、巢狀插座與具名插座。請閱讀 show-routes-with-outlets.md - 導航至路由： 使用
RouterLink的宣告式導航與使用Router的程式化導航。請閱讀 navigate-to-routes.md - 控制路由存取： 實作
CanActivate、CanMatch與其他守衛以確保安全。請閱讀 route-guards.md - 資料解析器： 在路由啟用前使用
ResolveFn預先擷取資料。請閱讀 data-resolvers.md - 路由器生命週期與事件： 導航事件的時間順序與除錯。請閱讀 router-lifecycle.md
- 渲染策略： CSR、SSG（預先渲染）與具有水合作用的 SSR。請閱讀 rendering-strategies.md
- 路由轉場動畫： 啟用與自訂 View Transitions API。請閱讀 route-animations.md
若需要更深入的文件或更多上下文，請造訪官方 Angular 路由指南。
樣式與動畫
實作 Angular 的樣式與動畫時，請查閱以下參考資料：
- 在 Angular 中使用 Tailwind CSS： 將 Tailwind CSS 整合到 Angular 專案中。請閱讀 tailwind-css.md
- Angular 動畫： 使用原生 CSS（建議）或傳統 DSL 來實現動態效果。請閱讀 angular-animations.md
- 元件樣式： 元件樣式與封裝的最佳實務。請閱讀 component-styling.md
測試
撰寫或更新測試時，請根據任務查閱以下參考資料：
- 基礎： 單元測試（Vitest）的最佳實務、非同步模式與
TestBed。請閱讀 testing-fundamentals.md - 元件 Harness： 用於穩健元件互動的標準模式。請閱讀 component-harnesses.md
- 路由器測試： 使用
RouterTestingHarness進行可靠的導航測試。請閱讀 router-testing.md - 端對端（E2E）測試： 設定與執行 E2E 測試。請閱讀 e2e-testing.md
工具鏈
處理 Angular 工具鏈時，請查閱以下參考資料：
- Angular CLI： 建立應用程式、生成程式碼（元件、路由、服務）、開發伺服與建置。請閱讀 cli.md
- 程式碼現代化： 使用遷移自動重構至現代標準。請閱讀 migrations.md
- Angular MCP 伺服器： 可用的工具、設定與實驗性功能。請閱讀 mcp.md
- 環境設定： 建置時與執行時環境的設定策略。請閱讀 environment-configuration.md