Angular 開發者指南
何時啟動
- 在任何 Angular 專案或程式碼庫中工作
- 建立或初始化新的 Angular 專案、應用程式或函式庫
- 產生元件、服務、指令、管道、守衛或解析器
- 使用 Angular Signals、
linkedSignal或resource實作反應性 - 處理 Angular 表單 (signal 表單、響應式表單或模板驅動表單)
- 設定依賴注入、路由、延遲載入或路由守衛
- 新增無障礙 (ARIA)、動畫或元件樣式
- 撰寫或除錯 Angular 特定測試 (單元測試、元件測試工具、端對端測試)
- 設定 Angular CLI 工具或 Angular MCP 伺服器
-
在提供指引前，務必先分析專案的 Angular 版本，因為最佳實務與可用功能在不同版本間可能差異很大。如果使用 Angular CLI 建立新專案，除非使用者指定，否則不要指定版本。
-
生成程式碼時，遵循 Angular 的風格指南與最佳實務，以確保可維護性與效能。使用 Angular CLI 來建立元件、服務、指令、管道與路由，以維持一致性。
-
完成生成程式碼後，執行
ng build以確保沒有建置錯誤。如有錯誤，請分析錯誤訊息並修正後再繼續。不可跳過此步驟，因為這對確保生成的程式碼正確且可運作至關重要。
建立新專案
如果使用者未提供任何準則，建立新 Angular 專案時使用以下預設值：
- 除非使用者指定其他版本，否則使用最新的穩定版 Angular。
- 僅在目標 Angular 版本支援 Signal 表單時，才在新專案中偏好使用 Signal 表單。了解更多
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 表單。在決定表單策略時，請分析專案並考慮以下準則：
-
如果應用程式版本支援 Signal 表單且這是新表單，偏好使用 signal 表單。
-
對於較舊的應用程式或現有表單，請匹配應用程式當前的表單策略。
-
Signal 表單：使用 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
測試
在撰寫或更新測試時，請根據任務查閱以下參考資料：
- 基礎知識：單元測試的最佳實務、非同步模式與
TestBed。請閱讀 testing-fundamentals.md - 元件測試工具 (Component Harnesses)：進行穩定元件互動的標準模式。請閱讀 component-harnesses.md
- 路由測試：使用
RouterTestingHarness進行可靠的導航測試。請閱讀 router-testing.md - 端對端 (E2E) 測試：使用 Cypress 或 Playwright 進行 E2E 測試的最佳實務。請閱讀 e2e-testing.md
工具
在使用 Angular 工具時，請查閱以下參考資料：
反模式
- 在初始化 signal 表單欄位值時使用
null或undefined——應改用''、0或[] - 在未先呼叫欄位的情況下存取表單欄位狀態旗標：
form.field.valid()——應使用form.field().valid() - 當目標 Angular 版本支援 Signal 表單時，仍在新表單中使用較舊的表單 API
- 在
[formField]輸入上設定min、max、value、disabled或readonlyHTML 屬性——應改為在 schema 規則中定義 - 在注入上下文外部呼叫
inject()——必要時使用runInInjectionContext - 使用
effect()來處理應使用computed()的派生狀態 - 在巢狀
@for迴圈中引用$parent.$index——Angular 不支援$parent；請改用let outerIdx = $index
相關技能
tdd-workflow——適用於 Angular 元件與服務的測試驅動開發工作流程security-review——網頁應用程式的安全檢查清單，包含 Angular 特定注意事項frontend-patterns——提供 React/Next.js 方法上下文的一般前端模式