angular-developer

Angular 开发指南

激活时机

• 在任何 Angular 项目或代码库中工作时
• 创建或初始化脚手架（Angular 项目、应用或库）
• 生成组件（components）、服务（services）、指令（directives）、管道（pipes）、守卫（guards）或解析器（resolvers）
• 使用 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：基于 Signal 的 input、transform 及 model input。阅读 inputs.md
• Outputs：基于 Signal 的 output 及自定义事件最佳实践。阅读 outputs.md
• Host 元素：Host 绑定与属性注入。阅读 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 forms。在做表单技术选型时，请分析项目并参考以下建议：

• 如果应用版本支持 Signal Forms 且这是新建表单，优先使用 signal forms。

• 对于旧版应用或存量表单，与项目当前使用的表单方案保持一致。

• Signal Forms：使用 Signals 管理表单状态。阅读 signal-forms.md

• 模板驱动表单（Template-driven forms）：适用于简单表单。阅读 template-driven-forms.md

• 响应式表单（Reactive forms）：适用于复杂表单。阅读 reactive-forms.md

依赖注入

在 Angular 中实现依赖注入时，请遵循以下规范：

• 基础概念：依赖注入概述、服务（services）及 inject() 函数。阅读 di-fundamentals.md
• 创建与使用服务：创建服务、providedIn: 'root' 选项，以及在组件或其他服务中注入服务。阅读 creating-services.md
• 定义依赖 Provider：自动提供 vs 手动提供、InjectionToken、useClass、useValue、useFactory 及作用域。阅读 defining-providers.md
• 注入上下文（Injection Context）：允许调用 inject() 的场景、runInInjectionContext 及 assertInInjectionContext。阅读 injection-context.md
• 层级注入器（Hierarchical Injectors）：EnvironmentInjector vs ElementInjector、解析规则、修饰符（optional、skipSelf）以及 providers vs viewProviders。阅读 hierarchical-injectors.md

Angular Aria

为以下常见设计模式构建支持无障碍特性的自定义组件时（Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid），请参考以下文档：

• Angular Aria 组件：构建 Headless 无障碍组件（Accordion、Listbox、Combobox、Menu、Tabs、Toolbar、Tree、Grid）及 ARIA 属性样式设置。阅读 angular-aria.md

路由

在 Angular 中实现页面导航时，请参考以下文档：

• 定义路由：URL 路径、静态与动态路径段、通配符及重定向。阅读 define-routes.md
• 路由加载策略：预加载（Eager） vs 懒加载（Lazy），以及上下文感知加载。阅读 loading-strategies.md
• 使用 Outlet 展示路由：使用 <router-outlet>、嵌套 Outlet 及具名 Outlet。阅读 show-routes-with-outlets.md
• 页面跳转：使用 RouterLink 进行声明式导航，以及使用 Router 进行编程式导航。阅读 navigate-to-routes.md
• 使用守卫控制路由权限：实现 CanActivate、CanMatch 及其他安全守卫。阅读 route-guards.md
• 数据解析器（Data Resolvers）：在路由激活前使用 ResolveFn 预拉取数据。阅读 data-resolvers.md
• 路由生命周期与事件：导航事件的时间顺序与调试技巧。阅读 router-lifecycle.md
• 渲染策略：CSR、SSG（预渲染/Prerendering）及水合 SSR（Hydration）。阅读 rendering-strategies.md
• 路由过渡动画：启用并自定义 View Transitions API。阅读 route-animations.md

如果需要更深度的文档或更多上下文，请访问 Angular Routing 官方指南。

样式与动画

在 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）：健壮组件交互的标准模式。阅读 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 属性 — 应在 schema 规则中统一定义
• 在注入上下文外调用 inject() — 必要时请使用 runInInjectionContext
• 把本该使用 computed() 的派生状态写成了 effect()
• 在嵌套 @for 循环中引用 $parent.$index — Angular 不支持 $parent；请改用 let outerIdx = $index

相关 Skill

• tdd-workflow — 适用于 Angular 组件和服务的测试驱动开发工作流
• security-review — Web 应用安全检查清单（包含 Angular 专属安全注意事项）
• frontend-patterns — 通用前端设计模式（提供 React/Next.js 实现思路的参考）