Angular 開發者指南
啟用時機
- 在任何 Angular 專案或程式碼庫中工作時
- 建立或初始化新的 Angular 專案、應用程式或函式庫時
- 生成元件、服務、指令、管道、守衛或解析器時
- 使用 Angular Signals、
linkedSignal或resource實作響應式設計時 - 處理 Angular 表單（signal forms、反應式表單或樣板驅動表單）時
- 設定依賴注入、路由、延遲載入或路由守衛時
- 新增無障礙（ARIA）、動畫或元件樣式時
- 編寫或偵錯 Angular 特定的測試（單元測試、元件測試工具、E2E）時
- 設定 Angular CLI 工具或 Angular MCP 伺服器時
-
在提供指導前，務必先分析專案的 Angular 版本，因為最佳實踐和可用功能在不同版本之間可能會有顯著差異。如果使用 Angular CLI 建立新專案，除非使用者指定，否則不要指定版本。
-
生成程式碼時，請遵循 Angular 的樣式指南和最佳實踐，以確保可維護性和效能。使用 Angular CLI 來建構元件、服務、指令、管道和路由，以確保一致性。
-
完成程式碼生成後，請執行
ng build以確保沒有建置錯誤。如果出現錯誤，請分析錯誤訊息並在繼續之前修復它們。不要跳過此步驟，因為這對於確保生成的程式碼正確且可運作至關重要。
建立新專案
如果使用者沒有提供指導，在建立新的 Angular 專案時，請使用以下預設值：
- 除非使用者另有指定，否則使用最新的穩定版 Angular。
- 僅當目標 Angular 版本支援 Signal Forms 時，才在新專案中優先使用 Signal Forms。了解更多
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 的輸入、轉換和 model inputs。閱讀 inputs.md
- 輸出：基於 Signal 的輸出和自訂事件最佳實踐。閱讀 outputs.md
- 宿主元素：Host bindings 和屬性注入。閱讀 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
表單
在大多數新應用程式中，優先使用 signal forms。在決定表單策略時，請分析專案並考慮以下指導原則：
-
如果應用程式版本支援 Signal Forms 且這是新表單，則優先使用 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
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
- 使用 Outlet 顯示路由：使用
<router-outlet>、巢狀 outlet 和具名 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 Routing 指南。
樣式與動畫
在 Angular 中實作樣式和動畫時，請查閱以下參考資料：
- 在 Angular 中使用 Tailwind CSS：將 Tailwind CSS 整合到 Angular 專案中。閱讀 tailwind-css.md
- Angular 動畫：使用原生 CSS（建議）或傳統 DSL 來實現動態效果。閱讀 angular-animations.md
- 元件樣式：元件樣式和封裝的最佳實踐。閱讀 component-styling.md
測試
在撰寫或更新測試時，請根據任務查閱以下參考資料：
- 基礎知識：單元測試、非同步模式和
TestBed的最佳實踐。閱讀 testing-fundamentals.md - 元件測試工具：用於穩健元件互動的標準模式。閱讀 component-harnesses.md
- 路由器測試：使用
RouterTestingHarness進行可靠的導航測試。閱讀 router-testing.md - 端到端 (E2E) 測試：使用 Cypress 或 Playwright 進行 E2E 測試的最佳實踐。閱讀 e2e-testing.md
工具
在使用 Angular 工具時，請查閱以下參考資料：
反模式
- 使用
null或undefined作為 signal form 欄位的初始值 — 應改用''、0或[] - 在未先呼叫欄位的情況下存取表單欄位狀態標誌：
form.field.valid()— 應使用form.field().valid() - 在目標 Angular 版本支援 Signal Forms 時，對新表單使用較舊的表單 API
- 在
[formField]輸入上設定min、max、value、disabled或readonlyHTML 屬性 — 應改為將這些定義為 schema 規則 - 在注入上下文之外呼叫
inject()— 必要時請使用runInInjectionContext - 對應使用
computed()的衍生狀態使用effect() - 在巢狀
@for迴圈中引用$parent.$index— Angular 不支援$parent；請改用let outerIdx = $index
相關技能
tdd-workflow— 適用於 Angular 元件和服務的測試驅動開發工作流程security-review— Web 應用程式的安全檢查清單，包含 Angular 特定的注意事項frontend-patterns— 提供有關 React/Next.js 方法上下文的一般前端模式