Angular 开发者指南
何时激活
- 在任何 Angular 项目或代码库中工作时
- 创建或搭建新的 Angular 项目、应用或库时
- 生成组件、服务、指令、管道、守卫或解析器时
- 使用 Angular Signals、
linkedSignal或resource实现响应式时 - 使用 Angular 表单（信号表单、响应式表单或模板驱动表单）时
- 设置依赖注入、路由、懒加载或路由守卫时
- 添加无障碍（ARIA）、动画或组件样式时
- 编写或调试 Angular 特定测试（单元测试、组件测试工具、端到端测试）时
- 配置 Angular CLI 工具或 Angular MCP 服务器时
-
在提供指导之前，始终分析项目的 Angular 版本，因为最佳实践和可用功能在不同版本之间可能有显著差异。如果使用 Angular CLI 创建新项目，除非用户提示，否则不要指定版本。
-
生成代码时，遵循 Angular 的风格指南和最佳实践，以确保可维护性和性能。使用 Angular CLI 搭建组件、服务、指令、管道和路由，以确保一致性。
-
完成代码生成后，运行
ng build以确保没有构建错误。如果存在错误，分析错误消息并修复它们，然后再继续。不要跳过此步骤，因为它对于确保生成的代码正确且功能正常至关重要。
创建新项目
如果用户未提供指导，在创建新 Angular 项目时使用以下默认值：
- 除非用户另有说明，否则使用最新的稳定版 Angular。
- 仅当目标 Angular 版本支持信号表单时，才在新项目中优先使用信号表单。了解更多
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
- 输入： 基于信号的输入、转换和模型输入。阅读 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。阅读 effects.md
表单
对于大多数新应用来说，优先使用信号表单。在做表单决策时，分析项目并考虑以下指导原则：
-
如果应用版本支持信号表单并且这是一个新表单，优先使用信号表单。
-
对于较旧的应用或现有表单，匹配应用当前的表单策略。
-
信号表单： 使用信号进行表单状态管理。阅读 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（预渲染）和带水合（Hydration）的 SSR。阅读 rendering-strategies.md
- 路由过渡动画： 启用和自定义视图过渡 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.md
- 路由测试： 使用
RouterTestingHarness进行可靠的导航测试。阅读 router-testing.md - 端到端（E2E）测试： 使用 Cypress 或 Playwright 进行 E2E 测试的最佳实践。阅读 e2e-testing.md
工具
在使用 Angular 工具时，查阅以下参考文档：
反模式
- 使用
null或undefined作为初始信号表单字段值——改用''、0或[] - 在不先调用字段的情况下访问表单字段状态标志：
form.field.valid()——改用form.field().valid() - 当目标 Angular 版本支持信号表单时，对新手表单使用较旧的表单 API
- 在
[formField]输入上设置min、max、value、disabled或readonlyHTML 属性——改为将其定义为架构规则 - 在注入上下文之外调用
inject()——必要时使用runInInjectionContext - 对应该使用
computed()的派生状态使用effect() - 在嵌套的
@for循环中引用$parent.$index——Angular 不支持$parent；改用let outerIdx = $index
相关技能
tdd-workflow——适用于 Angular 组件和服务的测试驱动开发工作流security-review——针对 Web 应用的安全清单，包括 Angular 特定问题frontend-patterns——关于 React/Next.js 方法上下文的一般前端模式