angular-developer

Angular 開發者指南

1. 在提供指引前，務必先分析專案的 Angular 版本，因為不同版本間的最佳實務與可用功能差異很大。如果使用 Angular CLI 建立新專案，除非使用者指定，否則不要指定版本。

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

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

建立新專案

如果使用者沒有提供指引，以下是建立新 Angular 專案時應遵循的預設規則：

1. 除非使用者指定，否則使用最新的穩定版 Angular。
2. 在新專案中使用 Signals Forms 進行表單管理（Angular v21 及更新版本可用）了解更多。

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：回退至最新版。

• 如果沒有指定版本，且 ng version 指令失敗（表示沒有 Angular 安裝），則必須使用 npx 取得最新版本。
• 指令： npx @angular/cli@latest new <project-name>

元件

處理 Angular 元件時，請根據任務查閱以下參考資料：

• 基礎知識：結構、元資料、核心概念與範本控制流程（@if、@for、@switch）。閱讀 components.md
• 輸入：基於 Signal 的輸入、轉換與 model inputs。閱讀 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

表單

在大多數新應用程式中，偏好使用 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

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 路由指南。

樣式與動畫

實作 Angular 樣式與動畫時，請查閱以下參考資料：

• 在 Angular 中使用 Tailwind CSS：將 Tailwind CSS 整合至 Angular 專案。閱讀 tailwind-css.md
• Angular 動畫：使用原生 CSS（建議）或傳統 DSL 實現動態效果。閱讀 angular-animations.md
• 元件樣式：元件樣式與封裝的最佳實務。閱讀 component-styling.md

測試

撰寫或更新測試時，請根據任務查閱以下參考資料：

• 基礎知識：單元測試（Vitest）的最佳實務、非同步模式與 TestBed。閱讀 testing-fundamentals.md
• 元件 Harnesses：穩健元件互動的標準模式。閱讀 component-harnesses.md
• 路由器測試：使用 RouterTestingHarness 進行可靠的導航測試。閱讀 router-testing.md
• 端對端（E2E）測試：使用 Cypress 進行 E2E 測試的最佳實務。閱讀 e2e-testing.md

工具

使用 Angular 工具時，請查閱以下參考資料：

• Angular CLI：建立應用程式、產生程式碼（元件、路由、服務）、提供服務與建置。閱讀 cli.md
• 程式碼現代化：使用遷移自動重構至現代標準。閱讀 migrations.md
• Angular MCP 伺服器：可用工具、設定與實驗性功能。閱讀 mcp.md
• 環境設定：建置時與執行時期設定的策略。閱讀 environment-configuration.md