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.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 表單。在決定表單類型時，請分析專案並考慮以下指引：

• 若應用程式使用 v21 或更新版本，且這是新表單，偏好使用 signal 表單。

• 對於較舊的應用程式或處理現有表單時，請使用與應用程式當前表單策略相符的適當表單類型。

• Signal 表單：使用 signal 進行表單狀態管理。閱讀 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
• 使用 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
• 元件 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