angular-developer

Angular 开发指南

1. 提供指导前，始终分析项目的 Angular 版本，因为不同版本的最佳实践和可用功能可能差异很大。使用 Angular CLI 创建新项目时，除非用户要求，否则不要指定版本。

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

3. 生成代码后，运行 ng build，确保没有构建错误。如果出现错误，请分析错误消息并在继续之前修复。切勿跳过此步骤，因为这对确保生成的代码正确且可正常运行至关重要。

创建新项目

如果用户未提供指南，创建新的 Angular 项目时请遵循以下默认规则：

1. 使用最新的稳定版 Angular，除非用户另有指定。
2. 在新项目中使用 Signal Forms 管理表单（在 Angular v22 及更高版本中已稳定）了解更多。

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 的输入、转换和模型输入。阅读 inputs.md
• 输出：基于 Signal 的输出和自定义事件最佳实践。阅读 outputs.md
• 宿主元素：宿主绑定和属性注入。阅读 host-elements.md
• 命名约定：现代 Angular v20+ 命名风格（“意图优先于角色”），适用于文件、组件、服务、指令、管道和模型。阅读 naming-conventions.md
• 查询与内容投影：基于 Signal 的视图查询和内容查询（viewChild、viewChildren、contentChild、contentChildren），以及使用 <ng-content> 插槽和后备内容进行内容投影。阅读 queries-and-projection.md
• 可延迟视图：使用 @defer 实现延迟加载、代码拆分、触发条件、预获取、加载状态、SSR 和布局稳定性。阅读 deferrable-views.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

HTTP 通信

与后端服务通信时，请使用 Angular HTTP API，并参考以下文档：

• HTTP 客户端与资源：provideHttpClient、HttpClient、拦截器和 httpResource。请阅读 http-client.md

表单

对于大多数新应用，优先使用信号表单。决定表单方案时，请分析项目并考虑以下指南：

• 如果应用使用 v22 或更高版本，且这是一个新表单，优先使用 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

管道

格式化模板中的值、创建自定义管道，或在 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
• 使用出口显示路由：使用 <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
• 服务端与混合渲染：在配置了 SSR 的应用中实现服务端路由、预渲染、水合、兼容服务端的代码和请求数据。请阅读 server-side-rendering.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
• 组件测试工具：稳健组件交互的标准模式。请阅读 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