跳转至

Angular 开发者指南

激活时

  • 在处理任何 Angular 项目或代码库时
  • 在创建或搭建新的 Angular 项目、应用程序或库时
  • 在生成组件、服务、指令、管道、守卫或解析器时
  • 在使用 Angular 信号、linkedSignal 或 resource 实现响应性时
  • 在处理 Angular 表单（信号表单、响应式表单或模板驱动表单）时
  • 在设置依赖注入、路由、延迟加载或路由守卫时
  • 在添加无障碍（ARIA）、动画或组件样式时
  • 在创建或调试 Angular 特定的测试（单元测试、组件 harness、E2E）时

  • 在创建 Angular CLI 工具或配置 Angular MCP 服务器时

  • 在提供指导之前，请始终分析项目的 Angular 版本。最佳实践和可用功能在不同版本之间可能有很大差异。使用 Angular CLI 创建新项目时，除非用户明确要求，否则不要指定版本。

  • 生成代码时，请遵循 Angular 风格指南和 Angular 最佳实践，以确保可维护性和性能。使用 Angular CLI 搭建组件、服务、指令、管道和路由，以确保一致性。

  • 完成代码生成后，请运行 ng build 检查是否有构建错误。如果有错误，请分析错误消息并修复后再继续。不要跳过此步骤，以确保生成的代码能够正常运行。

创建新项目

如果用户未提供指南，请在创建新的 Angular 项目时使用以下默认设置。

  1. 除非用户另有指定，否则请使用 Angular 的最新稳定版本。
  2. 仅当目标 Angular 版本支持信号表单时，新项目才应优先使用信号表单。请查看详细信息。

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 信号，并参考以下文档。

  • 信号概述： 核心信号概念（signal、computed）、响应式上下文以及 untracked。请阅读 signals-overview.md。
  • 依赖状态（linkedSignal）： 创建链接到源信号的可写状态。请阅读 linked-signal.md。
  • 异步响应性（resource）： 直接将异步数据获取到信号状态中。请阅读 resource.md。
  • 副作用（effect）： 日志记录、第三方 DOM 操作（afterRenderEffect）以及不使用副作用的主题。请阅读 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 路径、静态 vs 动态段、通配符和重定向。阅读 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、SGG（预渲染）以及带水合的 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 工具开发时，请参考以下文档。

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

反模式

  • 不要将 null 或 undefined 用作信号表单字段值 — 请使用 ''、0 或 [] 代替。
  • 不调用字段而访问表单字段状态标志：form.field.valid() — 请使用 form.field().valid() 代替。
  • 在目标 Angular 版本支持信号表单时，使用旧版表单 API 创建新表单。
  • 在 [formField] 输入上设置 min、max、value、disabled 或 readonly HTML 属性 — 请将这些定义为 schema 规则。
  • 在注入上下文之外调用 inject() — 如有必要，请使用 runInInjectionContext。
  • 对派生状态使用 effect() — 请使用 computed() 代替。
  • 在嵌套的 @for 循环中引用 $parent.$index — Angular 不支持 $parent。请使用 let outerIdx = $index 代替。
  • tdd-workflow — 适用于 Angular 组件和服务的测试驱动开发工作流。
  • security-review — 包含 Angular 特定关注点的 Web 应用程序安全清单。
  • frontend-patterns — 用于 React/Next.js 方法上下文的通用前端模式。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC