angular-developer

Angular 开发者指南

何时激活

• 在任何 Angular 项目或代码库中工作
• 创建或搭建新的 Angular 项目、应用程序或库
• 生成组件、服务、指令、管道、守卫或解析器
• 使用 Angular Signals、linkedSignal 或 resource 实施反应性
• 使用 Angular 表单（signal forms、reactive forms 或 template-driven）
• 设置依赖注入、路由、懒加载或路由守卫
• 添加无障碍功能 (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 Forms。了解更多。

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
• 输入：基于信号的输入、转换和模型输入。阅读 inputs.md
• 输出：基于信号的输出和自定义事件最佳实践。阅读 outputs.md
• 宿主元素：宿主绑定和属性注入。阅读 host-elements.md

如果您需要上述参考中未找到的更深入文档，请阅读 https://angular.dev/guide/components 处的文档。

反应性和数据管理

管理状态和数据反应性时，使用 Angular Signals 并查阅以下参考：

• Signals 概述：核心信号概念（signal、computed）、反应性上下文和 untracked。阅读 signals-overview.md
• 依赖状态 (linkedSignal)：创建链接到源信号的可写状态。阅读 linked-signal.md
• 异步反应性 (resource)：直接将异步数据获取到信号状态中。阅读 resource.md
• 副作用 (effect)：日志记录、第三方 DOM 操作（afterRenderEffect）以及何时不使用效果。阅读 effects.md

表单

在大多数情况下，对于新应用，首选 signal forms。做出表单决策时，分析项目并考虑以下指南：

• 如果应用版本支持 Signal Forms 且这是新表单，首选 signal forms。

• 对于旧应用或现有表单，匹配应用当前的表单策略。

• Signal Forms：使用信号进行表单状态管理。阅读 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
• 使用出口显示路由：使用 <router-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
• 组件 Harness：稳健组件交互的标准模式。阅读 component-harnesses.md
• 路由测试：使用 RouterTestingHarness 进行可靠的导航测试。阅读 router-testing.md
• 端到端 (E2E) 测试：使用 Cypress 或 Playwright 的 E2E 测试最佳实践。阅读 e2e-testing.md

工具

使用 Angular 工具时，查阅以下参考：

• Angular CLI：创建应用程序、生成代码（组件、路由、服务）、服务和构建。阅读 cli.md
• Angular MCP 服务器：可用工具、配置和实验性功能。阅读 mcp.md

反模式

• 使用 null 或 undefined 作为初始 signal form 字段值 — 改为使用 ''、0 或 []
• 不先调用字段即访问表单字段状态标志：form.field.valid() — 使用 form.field().valid()
• 当目标 Angular 版本支持 Signal Forms 时，使用旧表单 API 开始新表单
• 在 [formField] 输入上设置 min、max、value、disabled 或 readonly HTML 属性 — 将这些定义为架构规则
• 在注入上下文之外调用 inject() — 需要时使用 runInInjectionContext
• 对应该使用 computed() 的派生状态使用 effect()
• 在嵌套的 @for 循环中引用 $parent.$index — Angular 不支持 $parent；改用 let outerIdx = $index

相关技能

• tdd-workflow — 适用于 Angular 组件和服务的测试驱动开发工作流
• security-review — Web 应用程序的安全检查清单，包括特定于 Angular 的关注点
• frontend-patterns — React/Next.js 方法的通用前端模式上下文