angular-developer

Angular 開發者指南

何時啟用

• 在任何 Angular 專案或程式碼庫中工作時
• 建立或建置新的 Angular 專案、應用程式或函式庫時
• 產生組件（components）、服務（services）、指令（directives）、管道（pipes）、防衛（guards）或解析器（resolvers）時
• 使用 Angular Signals、linkedSignal 或 resource 實作響應式機制時
• 處理 Angular 表單時（Signal 表單、響應式表單 reactive forms，或範本驅動表單 template-driven）
• 設定依賴注入、路由、延遲載入（lazy loading）或路由防衛（route guards）時
• 加入無障礙功能（ARIA）、動畫或組件樣式時
• 撰寫或除錯 Angular 專用測試時（單元測試、組件 harness、E2E 測試）
• 設定 Angular CLI 工具鏈或 Angular MCP 伺服器時

1. 在提供指導之前，請務必先分析專案的 Angular 版本，因為不同版本之間的最佳實踐和可用功能可能存在顯著差異。如果使用 Angular CLI 建立新專案，除非使用者主動要求，否則請勿指定版本。

2. 產生程式碼時，請遵循 Angular 的風格指南與最佳實踐，以維持可維護性與效能。使用 Angular CLI 建立組件、服務、指令、管道和路由，以確保一致性。

3. 程式碼產生完成後，請執行 ng build 以確保沒有建置錯誤。如果出現錯誤，請先分析錯誤訊息並進行修復後再繼續。切勿跳過此步驟，因為這對於確保產生的程式碼正確且可正常運作至關重要。

建立新專案

若使用者未提供相關規範，在建立新 Angular 專案時請使用以下預設設定：

1. 除非使用者另有指定，否則請使用 Angular 最新穩定版本。
2. 僅在目標 Angular 版本支援時，才在新專案中優先採用 Signal 表單。詳情請參閱 references/signal-forms.md。

ng new 執行規則：
當收到建立新 Angular 專案的指令時，必須嚴格按照以下步驟確定正確的執行命令：

步驟 1：檢查使用者是否指定特定版本。

• 如果使用者要求特定版本（例如 Angular 15），請跳過本機安裝，嚴格使用 npx。
• 命令： npx @angular/cli@<requested_version> new <project-name>

步驟 2：檢查是否存在現有的 Angular 安裝。

• 如果未要求特定版本，請在終端機中執行 ng version 檢查系統是否已安裝 Angular CLI。
• 如果命令執行成功並回傳已安裝的版本，請直接使用本機／全域安裝。
• 命令： ng new <project-name>

步驟 3：回退至最新版本（Fallback to Latest）。

• 如果未要求特定版本且 ng version 命令執行失敗（代表未安裝 Angular），則必須使用 npx 取得最新版本。
• 命令： npx @angular/cli@latest new <project-name>

組件（Components）

處理 Angular 組件時，請根據任務需求參考以下文件：

• 基礎概念：結構剖析、詮釋資料（Metadata）、核心概念，以及範本控制流（@if, @for, @switch）。請參閱 components.md
• Inputs：基於 Signal 的 Input、Transforms 以及 Model Input。請參閱 inputs.md
• Outputs：基於 Signal 的 Output 以及自訂事件最佳實踐。請參閱 outputs.md
• Host 元素：Host 綁定（Host bindings）與屬性注入（Attribute injection）。請參閱 host-elements.md

若需要上述參考資料未包含的深度文件，請閱讀官方文件：https://angular.dev/guide/components。

響應式機制與資料管理

管理狀態與資料響應式機制時，請使用 Angular Signals 並參考以下文件：

• Signals 總覽：Core signal 概念（signal、computed）、響應式上下文（Reactive contexts）以及 untracked。請參閱 signals-overview.md
• 關聯狀態（linkedSignal）：建立與來源 signal 連結的可寫狀態。請參閱 linked-signal.md
• 非同步響應式（resource）：將非同步資料直接擷取至 signal 狀態中。請參閱 resource.md
• 副作用（effect）：日誌記錄（Logging）、第三方 DOM 操作（afterRenderEffect），以及何時不應使用 effect。請參閱 effects.md

表單

在多數新應用程式的場景中，優先使用 Signal 表單。在做出一項表單決策時，請分析專案並考量以下原則：

• 若應用程式版本支援 Signal 表單且這是一個新表單，請優先採用 Signal 表單。

• 對於較舊的應用程式或既有表單，請沿用該應用程式目前的表單策略。

• Signal 表單：使用 Signals 進行表單狀態管理。請參閱 signal-forms.md

• 範本驅動表單（Template-driven forms）：適用於簡單表單。請參閱 template-driven-forms.md

• 響應式表單（Reactive forms）：適用於複雜表單。請參閱 reactive-forms.md

依賴注入（Dependency Injection）

在 Angular 中實作依賴注入時，請遵循以下規範：

• 基礎概念：依賴注入總覽、服務（Services）以及 inject() 函數。請參閱 di-fundamentals.md
• 建立與使用服務：建立服務、providedIn: 'root' 選項，以及注入至組件或其他服務中。請參閱 creating-services.md
• 定義依賴提供者（Dependency Providers）：自動與手動提供、InjectionToken、useClass、useValue、useFactory 及作用域（Scopes）。請參閱 defining-providers.md
• 注入上下文（Injection Context）：允許使用 inject() 的位置、runInInjectionContext 與 assertInInjectionContext。請參閱 injection-context.md
• 層級化注入器（Hierarchical Injectors）：EnvironmentInjector 與 ElementInjector 的比較、解析規則、修飾符（optional、skipSelf），以及 providers 與 viewProviders 的差異。請參閱 hierarchical-injectors.md

Angular Aria

當為以下任一模式建置無障礙自訂組件時：Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid，請參考以下文件：

• Angular Aria 組件：建置 Headless、具備無障礙功能的組件（Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid）並設定 ARIA 屬性樣式。請參閱 angular-aria.md

路由（Routing）

在 Angular 中實作導覽功能時，請參考以下文件：

• 定義路由：URL 路徑、靜態與動態區段、萬用字元（Wildcards）及重新導向。請參閱 define-routes.md
• 路由載入策略：急迫載入（Eager loading）與延遲載入（Lazy loading），以及上下文感知載入。請參閱 loading-strategies.md
• 使用 Outlets 顯示路由：使用 <router-outlet>、巢狀 outlets 以及具名 outlets。請參閱 show-routes-with-outlets.md
• 導覽至路由：使用 RouterLink 進行宣告式導覽，以及使用 Router 進行程式化導覽。請參閱 navigate-to-routes.md
• 使用防衛（Guards）控制路由存取：實作 CanActivate、CanMatch 及其他防衛機制以維護安全性。請參閱 route-guards.md
• 資料解析器（Data Resolvers）：在路由啟用前使用 ResolveFn 預先擷取資料。請參閱 data-resolvers.md
• Router 生命週期與事件：導覽事件的時間順序與除錯。請參閱 router-lifecycle.md
• 渲染策略：CSR、SSG（預先渲染 Prerendering），以及帶水合作用（Hydration）的 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

測試

撰寫或更新測試時，請根據任務需求參考以下文件：

• 基礎概念：單元測試最佳實踐、非同步模式與 TestBed。請參閱 testing-fundamentals.md
• 組件 Harnesses：穩健組件互動的標準模式。請參閱 component-harnesses.md
• Router 測試：使用 RouterTestingHarness 進行可靠的導覽測試。請參閱 router-testing.md
• 端到端（E2E）測試：使用 Cypress 或 Playwright 進行 E2E 測試的最佳實踐。請參閱 e2e-testing.md

工具鏈（Tooling）

使用 Angular 工具鏈時，請參考以下文件：

• Angular CLI：建立應用程式、產生程式碼（組件、路由、服務）、開發伺服器啟動（serving）與建置（building）。請參閱 cli.md
• Angular MCP 伺服器：可用工具、設定與實驗性功能。請參閱 mcp.md

反模式（Anti-Patterns）

• 使用 null 或 undefined 作為 Signal 表單欄位的初始值 — 請改用 ''、0 或 []
• 未先呼叫欄位就直接存取表單欄位狀態標記：form.field.valid() — 請改用 form.field().valid()
• 在目標 Angular 版本支援 Signal 表單時，仍使用較舊的表單 API 建立新表單
• 在 [formField] 輸入元素上設定 min、max、value、disabled 或 readonly 等 HTML 屬性 — 請改在 schema 規則中定義這些約束
• 在注入上下文之外呼叫 inject() — 需要時請使用 runInInjectionContext
• 將 effect() 用於應使用 computed() 的衍生狀態（derived state）
• 在巢狀 @for 迴圈中引用 $parent.$index — Angular 不支援 $parent；請改用 let outerIdx = $index

相關 Skill

• tdd-workflow — 適用於 Angular 組件與服務的測試驅動開發（TDD）工作流程
• security-review — Web 應用程式安全性檢查清單，包含 Angular 特有的安全性考量
• frontend-patterns — 通用前端模式，提供 React/Next.js 方法的背景參考