angular-dev-v19

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Angular Developer Guidelines — v19

Angular开发者指南 — v19

This skill targets existing Angular v19 projects. All guidance, APIs, and examples are written for v19. Features exclusive to v20+ or v21+ are not included.

**本技能面向现有Angular v19项目。**所有指导、API和示例均针对v19编写，不包含v20+或v21+专属的功能。

Legacy Syntax Policy (STRICT — applies to all code generation)

遗留语法策略（严格执行 — 适用于所有代码生成）

The following legacy Angular APIs are FORBIDDEN in new code. Never generate them. Never suggest them. Always use the modern equivalent.

Legacy (NEVER use)	Modern (ALWAYS use)	Notes
`@Input()` decorator	`input()` / `input.required()`	Signal-based, reactive, type-safe
`@Output()` + `EventEmitter`	`output()`	No `EventEmitter` import needed
`@HostBinding()`	`host: { '[prop]': expr }` in metadata	Declarative, co-located
`@HostListener()`	`host: { '(event)': 'handler($event)' }` in metadata	Declarative, co-located
`@ViewChild()` / `@ViewChildren()`	`viewChild()` / `viewChildren()`	Signal-based queries
`@ContentChild()` / `@ContentChildren()`	`contentChild()` / `contentChildren()`	Signal-based queries
`ngIf` / `ngFor` / `*ngSwitch`	`@if` / `@for` / `@switch`	Built-in control flow
`constructor(private svc: Service)`	`private svc = inject(Service)`	Functional injection
`NgModule` (for new code)	Standalone components	`standalone: true` is default in v19
`ngOnInit` for signal derivation	`computed()` / `effect()`	Reactive by default
`ngOnDestroy` for cleanup	`DestroyRef.onDestroy()` / `takeUntilDestroyed()`	Prefer modern alternatives; `ngOnDestroy` is not forbidden

以下Angular遗留API在新代码中禁止使用。绝不要生成或推荐它们，务必使用现代替代方案。

遗留语法（禁止使用）	现代替代方案（必须使用）	说明
`@Input()` 装饰器	`input()` / `input.required()`	基于Signal、响应式、类型安全
`@Output()` + `EventEmitter`	`output()`	无需导入 `EventEmitter`
`@HostBinding()`	元数据中的 `host: { '[prop]': expr }`	声明式、内联定义
`@HostListener()`	元数据中的 `host: { '(event)': 'handler($event)' }`	声明式、内联定义
`@ViewChild()` / `@ViewChildren()`	`viewChild()` / `viewChildren()`	基于Signal的查询
`@ContentChild()` / `@ContentChildren()`	`contentChild()` / `contentChildren()`	基于Signal的查询
`ngIf` / `ngFor` / `*ngSwitch`	`@if` / `@for` / `@switch`	内置控制流
`constructor(private svc: Service)`	`private svc = inject(Service)`	函数式注入
`NgModule` （新代码中）	独立组件	v19中 `standalone: true` 为默认值
用于Signal派生的 `ngOnInit`	`computed()` / `effect()`	默认响应式
用于清理的 `ngOnDestroy`	`DestroyRef.onDestroy()` / `takeUntilDestroyed()`	优先使用现代替代方案； `ngOnDestroy` 并未被完全禁止

Refactoring Guidance

重构指导

When the agent is editing or working in a file that uses legacy syntax:

Complete the user's requested task first using modern syntax only.
After the task is done, suggest a follow-up refactoring opportunity:
"This file uses legacy
```
@Input()
```
/
```
@Output()
```
decorators. Want me to refactor them to signal-based
```
input()
```
/
```
output()
```
as a separate change?"
Never mix — if you add new inputs/outputs to a file with legacy ones, still use the modern API for the new additions. Do not match the file's legacy style.
Never refactor in the same change unless the user explicitly asks for it.

当Agent在使用遗留语法的文件中编辑或工作时：

首先完成用户请求的任务，且仅使用现代语法。
任务完成后，建议后续的重构机会：
"此文件使用了遗留的
```
@Input()
```
/
```
@Output()
```
装饰器。是否需要我将它们重构为基于Signal的
```
input()
```
/
```
output()
```
，作为单独的变更？"
绝不混用 — 若向使用遗留语法的文件添加新的输入/输出，仍需为新增内容使用现代API，不要匹配文件的遗留风格。
除非用户明确要求，否则不要在同一变更中进行重构。

When Asked to Refactor Legacy Code

当被要求重构遗留代码时

Do not rewrite manually. Angular ships official schematics that perform full-program analysis across TypeScript and templates. Always prefer a schematic over hand-editing.

Protocol:

Read the affected
```
.ts
```
and
```
.html
```
files to identify which legacy patterns are present.
Consult refactoring.md to select the correct schematic.
Run the schematic (scoped with
```
--path
```
when appropriate).
Run
```
ng build
```
to verify no errors were introduced.

Read refactoring.md for all available schematics, exact commands, flags, and known limitations.

不要手动重写。Angular官方提供了schematics，可对TypeScript和模板进行全程序分析。始终优先使用schematics而非手动编辑。

流程：

读取受影响的
```
.ts
```
和
```
.html
```
文件，识别存在的遗留模式。
查阅refactoring.md选择正确的schematic。
运行schematic（必要时使用
```
--path
```
参数限定范围）。
运行
```
ng build
```
验证未引入错误。

查看refactoring.md获取所有可用的schematics、精确命令、参数和已知限制。

General Guidelines

通用指导原则

When generating code, follow Angular's style guide and best practices for maintainability and performance.
Once you finish generating code, run
```
ng build
```
to ensure there are no build errors. If there are errors, analyze the error messages and fix them before proceeding.

生成代码时，遵循Angular风格指南和最佳实践，以保证可维护性和性能。
代码生成完成后，运行
```
ng build
```
确保无构建错误。若存在错误，分析错误信息并修复后再继续。

Components

组件

When working with Angular components, consult the following references based on the task:

Fundamentals: Anatomy, metadata, and core concepts. Read components.md
Inputs: Signal-based inputs, transforms, and model inputs. Read inputs.md
Outputs: Signal-based outputs and custom event best practices. Read outputs.md
Host Elements: Host bindings and attribute injection. Read host-elements.md
Templates: Control flow, @let, class/style bindings, typed form access. Read templates.md
Lifecycle: Signals-first lifecycle, DestroyRef, afterNextRender, takeUntilDestroyed. Read lifecycle.md
Directives: Attribute, host directives, directive composition API, and the same-name alias convention. Read directives.md
Structural Directives: Portal, lazy render, domain-logic conditionals (role/permission), typed template outlet, and microsyntax reference. Read structural-directives.md

Refactoring Legacy Code: All Angular migration schematics (

signal-input-migration

output-migration

signal-queries-migration

inject-migration

control-flow-migration

standalone-migration

, and more). Read refactoring.md

If you require deeper documentation not found in the references above, read the documentation at

https://angular.dev/guide/components

处理Angular组件时，根据任务查阅以下参考文档：

基础: 组件结构、元数据和核心概念。阅读components.md
输入: 基于Signal的输入、转换和模型输入。阅读inputs.md
输出: 基于Signal的输出和自定义事件最佳实践。阅读outputs.md
宿主元素: 宿主绑定和属性注入。阅读host-elements.md
模板: 控制流、@let、类/样式绑定、类型化表单访问。阅读templates.md
生命周期: 优先使用Signal的生命周期、DestroyRef、afterNextRender、takeUntilDestroyed。阅读lifecycle.md
指令: 属性指令、宿主指令、指令组合API和同名别名约定。阅读directives.md
结构型指令: 门户、延迟渲染、领域逻辑条件（角色/权限）、类型化模板出口和微语法参考。阅读structural-directives.md

遗留代码重构: 所有Angular迁移schematics（

signal-input-migration

、

output-migration

、

signal-queries-migration

、

inject-migration

、

control-flow-migration

、

standalone-migration

等）。阅读refactoring.md

若上述参考文档未包含所需的详细内容，请查阅官方文档

https://angular.dev/guide/components

。

Reactivity and Data Management

响应式编程与数据管理

When managing state and data reactivity, use Angular Signals and consult the following references:

Signals Overview: Core signal concepts (
```
signal
```
,
```
computed
```
), reactive contexts, and
```
untracked
```
. Read signals-overview.md
Dependent State (
linkedSignal
): Creating writable state linked to source signals. Read linked-signal.md
Async Reactivity (
resource
): Fetching asynchronous data directly into signal state. Read resource.md
⚠️
```
resource()
```
,
```
httpResource()
```
, and
```
rxResource()
```
are experimental in v19. Use with awareness that the API may change in v20+.
Side Effects (
effect
): Logging, third-party DOM manipulation, and when NOT to use effects. Read effects.md
RxJS Interop: Bridging signals and observables with
```
toSignal()
```
,
```
toObservable()
```
, and
```
takeUntilDestroyed()
```
. Read rxjs-interop.md

管理状态和数据响应式时，使用Angular Signals并查阅以下参考文档：

Signals概述: Signal核心概念（
```
signal
```
、
```
computed
```
）、响应式上下文和
```
untracked
```
。阅读signals-overview.md
依赖状态（
linkedSignal
）: 创建与源Signal关联的可写状态。阅读linked-signal.md
异步响应式（
resource
）: 直接将异步数据获取到Signal状态中。阅读resource.md
⚠️ v19中
```
resource()
```
、
```
httpResource()
```
和
```
rxResource()
```
为实验性API。使用时请注意，该API可能在v20+中发生变更。
副作用（
effect
）: 日志记录、第三方DOM操作以及副作用的禁用场景。阅读effects.md
RxJS互操作: 使用
```
toSignal()
```
、
```
toObservable()
```
和
```
takeUntilDestroyed()
```
实现Signal与Observable的桥接。阅读rxjs-interop.md

Forms

表单

Default for v19: Typed Reactive Forms.

Reactive forms: Use for all forms with typed FormGroup/FormControl. Read reactive-forms.md

Signal Forms (
@angular/forms/signals
) are not available in v19. Do not reference them.

v19默认：类型化响应式表单。

响应式表单: 所有表单均使用类型化FormGroup/FormControl。阅读reactive-forms.md

v19中不支持Signal Forms（
@angular/forms/signals
），请勿引用。

Dependency Injection

依赖注入

When implementing dependency injection in Angular, follow these guidelines:

Fundamentals: Overview of Dependency Injection, services, and the
```
inject()
```
function. Read di-fundamentals.md
Creating and Using Services: Creating services, the
```
providedIn: 'root'
```
option, and injecting into components or other services. Read creating-services.md
Defining Dependency Providers: Automatic vs manual provision,
```
InjectionToken
```
,
```
useClass
```
,
```
useValue
```
,
```
useFactory
```
, and scopes. Read defining-providers.md
Injection Context: Where
```
inject()
```
is allowed,
```
runInInjectionContext
```
, and
```
assertInInjectionContext
```
. Read injection-context.md
Hierarchical Injectors: The
```
EnvironmentInjector
```
vs
```
ElementInjector
```
, resolution rules, modifiers (
```
optional
```
,
```
skipSelf
```
), and
```
providers
```
vs
```
viewProviders
```
. Read hierarchical-injectors.md
Services: Service design patterns, single responsibility, and facade pattern. Read services.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
服务: 服务设计模式、单一职责原则和外观模式。阅读services.md

Routing

路由

When implementing navigation in Angular, consult the following references:

Define Routes: URL paths, static vs dynamic segments, wildcards, and redirects. Read define-routes.md
Show Routes with Outlets: Using
```
<router-outlet>
```
, nested outlets, and named outlets. Read show-routes-with-outlets.md
Navigate to Routes: Declarative navigation with
```
RouterLink
```
and programmatic navigation with
```
Router
```
. Read navigate-to-routes.md
Control Route Access with Guards: Implementing
```
CanActivate
```
,
```
CanMatch
```
, and other guards for security. Read route-guards.md
Data Resolvers: Pre-fetching data before route activation with
```
ResolveFn
```
. Read data-resolvers.md
Router Lifecycle and Events: Chronological order of navigation events and debugging. Read router-lifecycle.md

If you require deeper documentation or more context, visit the official Angular Routing guide.

在Angular中实现导航时，查阅以下参考文档：

定义路由: URL路径、静态与动态分段、通配符和重定向。阅读define-routes.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

若需要更详细的文档或更多上下文，请访问官方Angular路由指南。

HTTP & Data Fetching

HTTP与数据获取

When implementing HTTP and data fetching, consult the following references:

HTTP entry point (choosing the right API,
```
HttpClient
```
mutations, error handling): Read http.md
Resource APIs (
```
httpResource()
```
,
```
resource()
```
,
```
rxResource()
```
, state signals, loading states): Read resource.md

⚠️ All resource APIs are experimental in v19.
Interceptors (functional interceptors, auth, error, registration): Read interceptors.md

实现HTTP和数据获取时，查阅以下参考文档：

HTTP入口（选择合适的API、
```
HttpClient
```
变更、错误处理）：阅读http.md
Resource API（
```
httpResource()
```
、
```
resource()
```
、
```
rxResource()
```
、状态Signal、加载状态）：阅读resource.md

⚠️ v19中所有Resource API均为实验性。
拦截器（函数式拦截器、认证、错误处理、注册）：阅读interceptors.md

Styling and Animations

样式与动画

When implementing styling and animations in Angular, consult the following references:

Using Tailwind CSS with Angular: Integrating Tailwind CSS into Angular projects. Read tailwind-css.md
Angular Animations: Use native CSS animations (recommended) or the
```
@angular/animations
```
DSL for dynamic effects. Read angular-animations.md
```
animate.enter
```
/
```
animate.leave
```
are not available in v19. Use CSS animations or the
```
@angular/animations
```
DSL.
Styling components: Best practices for component styles and encapsulation. Read component-styling.md

在Angular中实现样式与动画时，查阅以下参考文档：

Angular集成Tailwind CSS: 将Tailwind CSS集成到Angular项目中。阅读tailwind-css.md
Angular动画: 推荐使用原生CSS动画，或使用
```
@angular/animations
```
DSL实现动态效果。阅读angular-animations.md
v19中不支持
```
animate.enter
```
/
```
animate.leave
```
。请使用CSS动画或
```
@angular/animations
```
DSL。
组件样式: 组件样式的最佳实践与封装。阅读component-styling.md

Testing

测试

When writing or updating tests, consult the following references based on the task:

Fundamentals: Best practices for unit testing, async patterns, and
```
TestBed
```
. Use Jasmine/Karma or a manual Vitest setup (native Vitest support is v20+ only). Read testing-fundamentals.md
Component Harnesses: Standard patterns for robust component interaction. Read component-harnesses.md
Router Testing: Using
```
RouterTestingHarness
```
for reliable navigation tests. Read router-testing.md

编写或更新测试时，根据任务查阅以下参考文档：

基础: 单元测试最佳实践、异步模式和
```
TestBed
```
。使用Jasmine/Karma或手动配置Vitest（原生Vitest支持仅在v20+中提供）。阅读testing-fundamentals.md
组件测试工具: 用于可靠组件交互的标准模式。阅读component-harnesses.md
路由测试: 使用
```
RouterTestingHarness
```
进行可靠的导航测试。阅读router-testing.md

Tooling

工具链

When working with Angular tooling, consult the following references:

Nx: This project uses Nx. Use
```
nx generate
```
,
```
nx build
```
,
```
nx serve
```
, and
```
nx test
```
instead of the Angular CLI directly. Refer to the Nx docs for available generators and executors.

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

Nx: 本项目使用Nx。请使用
```
nx generate
```
、
```
nx build
```
、
```
nx serve
```
和
```
nx test
```
替代Angular CLI直接执行。参考Nx文档获取可用的生成器和执行器。