``` Tanto los enlaces `class` como `style` usan una sintaxis más directa que se alinea estrechamente con los atributos HTML estándar. Esto hace tus plantillas más fáciles de leer y entender, especialmente para desarrolladores familiarizados con HTML básico. Adicionalmente, las directivas `NgClass` y `NgStyle` incurren en un costo de rendimiento adicional comparado con la sintaxis integrada de enlace `class` y `style`. Para más detalles, consulta la [guía de enlaces](/guide/templates/binding#css-class-and-style-property-bindings) ### Nombra manejadores de eventos por lo que _hacen_, no por el evento disparador Prefiere nombrar manejadores de eventos por la acción que realizan en lugar de por el evento disparador: ```html ``` Usar nombres significativos como este hace más fácil saber qué hace un evento al leer la plantilla. Para eventos de teclado, puedes usar los modificadores de eventos de tecla de Angular con nombres de manejadores específicos: ```html

```

A veces, la lógica de manejo de eventos es especialmente larga o compleja, haciendo impráctico declarar un solo manejador bien nombrado. En estos casos, está bien volver a un nombre como 'handleKeydown' y luego delegar a comportamientos más específicos basados en los detalles del evento:

```ts
@Component({/* ... */})
class RichText {
  handleKeydown(event: KeyboardEvent) {
    if (event.ctrlKey) {
      if (event.key === 'B') {
        this.activateBold();
      } else if (event.key === 'I') {
        this.activateItalic();
      }
// ...
    }
  }
}
```

### Mantén métodos de ciclo de vida simples

Evita poner lógica larga o compleja dentro de hooks de ciclo de vida como `ngOnInit`. En su lugar, prefiere crear métodos bien nombrados para contener esa lógica y luego _llamar esos métodos_ en tus hooks de ciclo de vida. Los nombres de hooks de ciclo de vida describen _cuándo_ se ejecutan, lo que significa que el código dentro no tiene un nombre significativo que describa qué está haciendo el código dentro.

```typescript
// PREFERIR
ngOnInit() {
  this.startLogging();
  this.runBackgroundTask();
}

// EVITAR
ngOnInit() {
  this.logger.setMode('info');
  this.logger.monitorErrors();
  // ...y todo el resto del código que se desplegaría de estos métodos.
}
```

### Usa interfaces de hooks de ciclo de vida

Angular proporciona una interfaz TypeScript para cada método de ciclo de vida. Al agregar un hook de ciclo de vida a tu clase, importa e `implementa` estas interfaces para asegurar que los métodos estén nombrados correctamente.

```ts
import {Component, OnInit} from '@angular/core';

@Component({/* ... */})
export class UserProfile implements OnInit {

// La interfaz `OnInit` asegura que este método esté nombrado correctamente.
  ngOnInit() { /* ... */ }
}
```
Los componentes son los bloques principales de construcción de las aplicaciones Angular. Cada componente representa una parte de una página web más grande. Organizar una aplicación en componentes ayuda a proporcionar estructura a tu proyecto, separando claramente el código en partes específicas que son fáciles de mantener y crecer con el tiempo.

## Definir un Componente

Cada componente tiene algunas partes principales:

1. Un [decorador](https://www.typescriptlang.org/docs/handbook/decorators.html) `@Component` que contiene alguna configuración utilizada por Angular.
2. Una plantilla HTML que controla lo que se renderiza en el DOM.
3. Un [selector CSS ](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors) que define cómo se usa el componente en HTML.
4. Una clase TypeScript con comportamientos, como manejar la entrada del usuario o hacer solicitudes a un servidor..

Aquí hay un ejemplo simplificado de un componente `UserProfile`.

```typescript
// user-profile.ts
@Component({
  selector: 'user-profile',
  template: `
    <h1>Perfil de usuario</h1>
    <p>Esta es la página del perfil de usuario</p>
  `,
})
export class UserProfile { /* Tu código del componente va aquí */ }
```

El decorador `@Component` también acepta opcionalmente una propiedad `styles` para cualquier CSS que quieras aplicar a tu plantilla:

```typescript
// user-profile.ts
@Component({
  selector: 'user-profile',
  template: `
    <h1>Perfil de usuario</h1>
    <p>Esta es la página del perfil de usuario</p>
  `,
  styles: `h1 { font-size: 3em; } `,
})
export class UserProfile { /* Tu código del componente va aquí */ }
```

### Separar HTML y CSS en archivos

Puedes definir el HTML y CSS de un componente en archivos separados usando `templateUrl` y `styleUrl`:

```typescript
// user-profile.ts
@Component({
  selector: 'user-profile',
  templateUrl: 'user-profile.html',
  styleUrl: 'user-profile.css',
})
export class UserProfile {
  // El comportamiento del componente se define aquí
}
```

```html

<h1>Perfil del usuario</h1>
<p>Esta es la página del perfil de usuario</p>
```

```css
/* user-profile.css */
li {
  color: red;
  font-weight: 300;
}
```

## Usar un Component

Construyes una aplicación componiendo múltiples componentes juntos. Por ejemplo, si estás creando una página de perfil de usuario, podrías dividir la página en varios componentes como este:

```mermaid
flowchart TD
    A[UserProfile]-->B
    A-->C
    B[UserBiography]-->D
    C[ProfilePhoto]
    D[UserAddress]
```
Aquí, el componente `UserProfile` utiliza varios otros componentes para generar la página final.

Para importar y usar un componente, debes:
1. En el archivo TypeScript de tu componente, agregar una declaración `import` para el componente que deseas usar.
2. En el decorador `@Component`, agregar el componente que deseas usar al arreglo `imports`.
3. En la plantilla de tu componente, agregar un elemento que coincida con el selector del componente que deseas usar.

Aquí tienes un ejemplo del componente `UserProfile` que importa y utiliza el componente `ProfilePhoto`:

```typescript
// user-profile.ts
import {ProfilePhoto} from 'profile-photo.ts';

@Component({
  selector: 'user-profile',
  imports: [ProfilePhoto],
  template: `
    <h1>Perfil del usuario</h1>
    <profile-photo />
    <p>Esta es la página del perfil de usuario</p>
  `,
})
export class UserProfile {
  // El comportamiento del componente se define aquí
}
```

SUGERENCIA: ¿Quieres saber más sobre los componentes en Angular? [Consulta la guía detallada de componentes](guide/components) para todos todos los detalles.

## Siguiente Paso

Ahora que sabe cómo funcionan los componentes en Angular, es hora de aprender cómo agregamos y gestionamos los datos dinámicos en nuestra aplicación.
# Selectores de Componentes

CONSEJO: Esta guía asume que ya has leído la [Guía de Fundamentos](essentials). Léela primero si eres nuevo en Angular.

Cada componente define
un [selector CSS](https://developer.mozilla.org/es/docs/Web/CSS/CSS_selectors) que determina cómo
se usa el componente:

```typescript
@Component({
  selector: 'profile-photo',
  ...
})
export class ProfilePhoto { }
```
Para usar un componente, creas un elemento HTML que coincida con su selector en las plantillas de _otros_ componentes:

```typescript
@Component({
  template: `
    <profile-photo />
    <button>Subir una nueva foto de perfil</button>`,
  ...,
})
export class UserProfile { }
```
**Angular hace coincidir los selectores estáticamente en tiempo de compilación**. Cambiar el DOM en tiempo de ejecución, ya sea mediante
enlaces de Angular o con APIs del DOM, no afecta los componentes renderizados.

**Un elemento puede coincidir exactamente con un selector de componente.** Si múltiples selectores de componente coinciden con un
solo elemento, Angular genera un error.

**Los selectores de componente distinguen entre mayúsculas y minúsculas.**

## Tipos de selectores

Angular soporta un subconjunto limitado
de [tipos de selectores CSS básicos](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) en
selectores de componente:

| **Tipo de selector**  | **Descripción**                                                                                                 | **Ejemplos**                  |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Tipo de selector      | Coincide con elementos basándose en su nombre de etiqueta HTML, o nombre de nodo.                                                    | `profile-photo`               |
| Selector de atributo | Coincide con elementos basándose en la presencia de un atributo HTML y, opcionalmente, un valor exacto para ese atributo. | `[dropzone]` `[type="reset"]` |
| Selector de clase    | Coincide con elementos basándose en la presencia de una clase CSS.                                                          | `.menu-item`                  |

Para valores de atributos, Angular soporta la coincidencia con un valor de atributo exacto usando el operador
igual (`=`). Angular no soporta otros operadores de valores de atributos.

Los selectores de componente de Angular no soportan combinadores, incluyendo
el [combinador descendiente](https://developer.mozilla.org/es/docs/Web/CSS/Descendant_combinator)
o [combinador hijo](https://developer.mozilla.org/es/docs/Web/CSS/Child_combinator).

Los selectores de componente de Angular no soportan
especificar [espacios de nombres](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course).

### La pseudo-clase `:not`

Angular soporta [la pseudo-clase `:not`](https://developer.mozilla.org/es/docs/Web/CSS/:not).
Puedes agregar esta pseudo-clase a cualquier otro selector para reducir qué elementos coincide
el selector de un componente. Por ejemplo, podrías definir un selector de atributo `[dropzone]` y prevenir
que coincida con elementos `textarea`:

```typescript
@Component({
  selector: '[dropzone]:not(textarea)',
  ...
})
export class DropZone { }
```
Angular no soporta ninguna otra pseudo-clase o pseudo-elemento en selectores de componente.

### Combinando selectores

Puedes combinar múltiples selectores concatenándolos. Por ejemplo, puedes hacer coincidir elementos `<button>`
que especifiquen `type="reset"`:

```typescript
@Component({
  selector: 'button[type="reset"]',
  ...
})
export class ResetButton { }
```
También puedes definir múltiples selectores con una lista separada por comas:

```typescript
@Component({
  selector: 'drop-zone, [dropzone]',
  ...
})
export class DropZone { }
```
Angular crea un componente para cada elemento que coincide con _cualquiera_ de los selectores en la lista.

## Eligiendo un selector

La gran mayoría de componentes deberían usar un nombre de elemento personalizado como su selector. Todos los nombres de
elementos personalizados deberían incluir un guión como se describe
en [la especificación HTML](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name).
Por defecto, Angular genera un error si encuentra un nombre de etiqueta personalizada que no coincide con ningún
componente disponible, previniendo errores debido a nombres de componente mal escritos.

Ver [Configuración avanzada de componentes](guide/components/advanced-configuration) para detalles sobre
usar [elementos personalizados nativos](https://developer.mozilla.org/es/docs/Web/API/Web_components) en
plantillas de Angular.

### Prefijos de selectores

El equipo de Angular recomienda usar un prefijo corto y consistente para todos los componentes personalizados
definidos dentro de tu proyecto. Por ejemplo, si fueras a construir YouTube con Angular, podrías
prefijar tus componentes con `yt-`, con componentes como `yt-menu`, `yt-player`, etc. Hacer espacio de nombres
a tus selectores de esta manera hace inmediatamente claro de dónde viene un componente particular. Por
defecto, el Angular CLI usa `app-`.

IMPORTANTE: Angular usa el prefijo de selector `ng` para sus propias APIs del framework. Nunca uses `ng` como prefijo de selector para tus propios componentes personalizados.

### Cuándo usar un selector de atributo

Deberías considerar un selector de atributo cuando quieras crear un componente en un elemento nativo estándar.
Por ejemplo, si quieres crear un componente de botón personalizado, puedes aprovechar el
elemento `<button>` estándar usando un selector de atributo:

```typescript
@Component({
  selector: 'button[yt-upload]',
   ...
})
export class YouTubeUploadButton { }
```
Este enfoque permite a los consumidores del componente usar directamente todas las APIs estándar del elemento
sin trabajo adicional. Esto es especialmente valioso para atributos ARIA como `aria-label`.

Angular no genera errores cuando encuentra atributos personalizados que no coinciden con un componente
disponible. Al usar componentes con selectores de atributo, los consumidores pueden olvidar importar el
componente o su NgModule, resultando en que el componente no se renderice.
Ver [Importando y usando componentes](guide/components/importing) para más información.

Los componentes que definen selectores de atributo deberían usar atributos en minúsculas y con guiones (dash-case).
Puedes seguir la misma recomendación de prefijos descrita arriba.
# Estilos en componentes

TIP: Esta guía asume que ya has leído la [Guía de Fundamentos](essentials). Léela primero si eres nuevo en Angular.

Los componentes pueden incluir opcionalmente estilos CSS que se aplican al DOM de ese componente:

```typescript
@Component({
  selector: 'profile-photo',
  template: `<img src="profile-photo.jpg" alt="Tu foto de perfil">`,
  styles: ` img { border-radius: 50%; } `,
})
export class ProfilePhoto { }
```
También puedes elegir escribir tus estilos en archivos separados:

```typescript
@Component({
  selector: 'profile-photo',
  templateUrl: 'profile-photo.html',
  styleUrl: 'profile-photo.css',
})
export class ProfilePhoto { }
```
Cuando Angular compila tu componente, estos estilos se emiten junto con la salida JavaScript de tu componente. 
Esto significa que los estilos del componente participan en el sistema de módulos de JavaScript. 
Cuando renderizas un componente Angular, el framework incluye automáticamente sus estilos asociados, 
incluso cuando se carga un componente de forma diferida.

Angular funciona con cualquier herramienta que genere CSS,
incluyendo [Sass](https://sass-lang.com), [less](https://lesscss.org),
y [stylus](https://stylus-lang.com).

## Alcance de estilos

Cada componente tiene una configuración de **encapsulación de vista** que determina cómo el framework delimita el alcance
de los estilos de un componente. Hay tres modos de encapsulación de vista: `Emulated`, `ShadowDom`, y `None`.
Puedes especificar el modo en el decorador `@Component`:

```typescript
@Component({
  ...,
  encapsulation: ViewEncapsulation.None,
})
export class ProfilePhoto { }
```
### ViewEncapsulation.Emulated

Por defecto, Angular usa encapsulación emulada para que los estilos de un componente solo se apliquen a elementos 
definidos en la plantilla de ese componente. En este modo, el framework genera un atributo HTML único 
para cada instancia del componente, añade ese atributo a los elementos en la plantilla del componente, 
e inserta ese atributo en los selectores CSS definidos en los estilos de tu componente.

Este modo asegura que los estilos de un componente no se filtren y afecten otros componentes. Sin embargo, 
los estilos globales definidos fuera de un componente aún puede afectar elementos dentro de un componente 
con encapsulación emulada.

En modo emulado, Angular admite
las pseudo-clases [`:host`](https://developer.mozilla.org/es/docs/Web/CSS/:host)
y [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context) 
sin usar [Shadow DOM](https://developer.mozilla.org/es/docs/Web/API/Web_components/Using_shadow_DOM).
Durante la compilación, el framework transforma estas pseudo-clases en atributos para que no
cumpla con las reglas de estas pseudo-clases nativas en tiempo de ejecución
(ej. compatibilidad del navegador, especificidad). 
El modo de encapsulación emulada de Angular no admite ninguna otra pseudo-clase relacionada con Shadow DOM,
como `::shadow` o `::part`.

#### `::ng-deep`

El modo de encapsulación emulada de Angular admite una pseudo-clase personalizada, `::ng-deep`. Aplicar esta pseudo-clase a
una regla CSS deshabilita la encapsulación para esa regla, convirtiéndola efectivamente en un estilo global. 
**El equipo de Angular desaconseja fuertemente el uso nuevo de `::ng-deep`**. Estas APIs permanecen exclusivamente para 
compatibilidad hacia atrás.

### ViewEncapsulation.ShadowDom

Este modo delimita el alcance de los estilos dentro de un componente
usando [la API estándar web de Shadow DOM](https://developer.mozilla.org/es/docs/Web/API/Web_components/Using_shadow_DOM).
Al habilitar este modo, Angular adjunta un shadow root (raíz de sombra) al elemento host del componente 
y renderiza la plantilla y los estilos del componente en el árbol de sombra (shadow tree) correspondiente.

Este modo garantiza estrictamente que _solo_ los estilos de ese componente se apliquen a elementos en la
plantilla del componente. Los estilos globales no pueden afectar a elementos en un árbol de sombra y los estilos dentro del
árbol de sombra no pueden afectar a elementos fuera de ese árbol de sombra.

Habilitar la encapsulación `ShadowDom`, sin embargo, impacta más que el alcance de estilos. Renderizar el
componente en un árbol de sombra afecta la propagación de eventos, la interacción
con [la API `<slot>`](https://developer.mozilla.org/es/docs/Web/API/Web_components/Using_templates_and_slots),
y cómo las herramientas de desarrollador del navegador muestran elementos. Siempre entiende las implicaciones completas de usar
Shadow DOM en tu aplicación antes de habilitar esta opción.

### ViewEncapsulation.None

Este modo deshabilita toda la encapsulación de estilos para el componente. Cualquier estilo asociado con el
componente se comporta como estilos globales.

NOTA: En los modos `Emulated` y `ShadowDom`, Angular no garantiza al 100% que los estilos de tu componente siempre sobrescriban los estilos que vienen de fuera.
Se asume que estos estilos tienen la misma especificidad que los estilos de tu componente en caso de colisión.

## Definir estilos en plantillas

Puedes usar el elemento `<style>` en la plantilla de un componente para definir estilos adicionales. El
modo de encapsulación de vista del componente se aplica a los estilos definidos de esta manera.

Angular no admite enlaces dentro de elementos de estilo.

## Referenciar archivos de estilo externos

Las plantillas de componentes pueden
usar [el elemento `<link>`](https://developer.mozilla.org/es/docs/Web/HTML/Reference/Elements/link) para
referenciar archivos CSS. Además, tu CSS puede
usar [la regla at `@import`](https://developer.mozilla.org/es/docs/Web/CSS/@import) para referenciar
archivos CSS. Angular trata estas referencias como estilos _externos_. Los estilos externos no se ven afectados por
la encapsulación de vista emulada.
# Accepting data with input properties

TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

TIP: If you're familiar with other web frameworks, input properties are similar to _props_.

When you use a component, you commonly want to pass some data to it. A component specifies the data that it accepts by declaring
**inputs**:

```ts
import {Component, input} from '@angular/core';

@Component({/*...*/})
export class CustomSlider {
  // Declare an input named 'value' with a default value of zero.
  value = input(0);
}
```
This lets you bind to the property in a template:

```html
<custom-slider [value]="50" />
```

If an input has a default value, TypeScript infers the type from the default value:

```typescript
@Component({/*...*/})
export class CustomSlider {
  // TypeScript infers that this input is a number, returning InputSignal<number>.
  value = input(0);
}
```

You can explicitly declare a type for the input by specifying a generic parameter to the function.

If an input without a default value is not set, its value is `undefined`:

```typescript
@Component({/*...*/})
export class CustomSlider {
  // Produces an InputSignal<number | undefined> because `value` may not be set.
  value = input<number>();
}
```

**Angular records inputs statically at compile-time**. Inputs cannot be added or removed at run-time.

The `input` function has special meaning to the Angular compiler. **You can exclusively call `input` in component and directive property initializers.**

When extending a component class, **inputs are inherited by the child class.**

**Input names are case-sensitive.**

## Reading inputs

The `input` function returns an `InputSignal`. You can read the value by calling the signal:

```ts
import {Component, input} from '@angular/core';

@Component({/*...*/})
export class CustomSlider {
  // Declare an input named 'value' with a default value of zero. 
  value = input(0);

// Create a computed expression that reads the value input
  label = computed(() => `The slider's value is ${this.value()}`); 
}
```
Signals created by the `input` function are read-only.

## Required inputs

You can declare that an input is `required` by calling `input.required` instead of `input`:

```ts
@Component({/*...*/})
export class CustomSlider {
  // Declare a required input named value. Returns an `InputSignal<number>`.
  value = input.required<number>();
}
```
Angular enforces that required inputs _must_ be set when the component is used in a template. If you try to use a component without specifying all of its required inputs, Angular reports an error at build-time.

Required inputs do not automatically include `undefined` in the generic parameter of the returned `InputSignal`.

## Configuring inputs

The `input` function accepts a config object as a second parameter that lets you change the way that input works.

### Input transforms

You can specify a `transform` function to change the value of an input when it's set by Angular.

```ts
@Component({
  selector: 'custom-slider',
  /*...*/
})
export class CustomSlider {
  label = input('', {transform: trimString});
}

function trimString(value: string | undefined): string {
  return value?.trim() ?? '';
}
```
```html
<custom-slider [label]="systemVolume" />
```

In the example above, whenever the value of `systemVolume` changes, Angular runs `trimString` and sets `label` to the result.

The most common use-case for input transforms is to accept a wider range of value types in templates, often including `null` and `undefined`.

**Input transform function must be statically analyzable at build-time.** You cannot set transform functions conditionally or as the result of an expression evaluation.

**Input transform functions should always be [pure functions](https://en.wikipedia.org/wiki/Pure_function).** Relying on state outside the transform function can lead to unpredictable behavior.

#### Type checking

When you specify an input transform, the type of the transform function's parameter determines the types of values that can be set to the input in a template.

```ts
@Component({/*...*/})
export class CustomSlider {
  widthPx = input('', {transform: appendPx});
}

function appendPx(value: number): string {
  return `${value}px`;
}
```
In the example above, the `widthPx` input accepts a `number` while the `InputSignal` property returns a `string`.

#### Built-in transformations

Angular includes two built-in transform functions for the two most common scenarios: coercing values to boolean and numbers.

```ts
import {Component, input, booleanAttribute, numberAttribute} from '@angular/core';

@Component({/*...*/})
export class CustomSlider {
  disabled = input(false, {transform: booleanAttribute}); 
  value = input(0, {transform: numberAttribute}); 
}
```
`booleanAttribute` imitates the behavior of standard HTML [boolean attributes](https://developer.mozilla.org/docs/Glossary/Boolean/HTML), where the
_presence_ of the attribute indicates a "true" value. However, Angular's `booleanAttribute` treats the literal string `"false"` as the boolean `false`.

`numberAttribute` attempts to parse the given value to a number, producing `NaN` if parsing fails.

### Input aliases

You can specify the `alias` option to change the name of an input in templates.

```ts
@Component({/*...*/})
export class CustomSlider {
  value = input(0, {alias: 'sliderValue'});
}
```
```html
<custom-slider [sliderValue]="50" />
```

This alias does not affect usage of the property in TypeScript code.

While you should generally avoid aliasing inputs for components, this feature can be useful for renaming properties while preserving an alias for the original name or for avoiding collisions with the name of native DOM element properties.

## Model inputs

**Model inputs** are a special type of input that enable a component to propagate new values back to its parent component.

When creating a component, you can define a model input similarly to how you create a standard input.

Both types of input allow someone to bind a value into the property. However, **model inputs allow the component author to write values into the property**. If the property is bound with a two-way binding, the new value propagates to that binding.

```typescript
@Component({ /* ... */})
export class CustomSlider {
  // Define a model input named "value".
  value = model(0);

increment() {
    // Update the model input with a new value, propagating the value to any bindings. 
    this.value.update(oldValue => oldValue + 10);
  }
}

@Component({
  /* ... */
  // Using the two-way binding syntax means that any changes to the slider's
  // value automatically propagate back to the `volume` signal.
  // Note that this binding uses the signal *instance*, not the signal value.
  template: `<custom-slider [(value)]="volume" />`,
})
export class MediaControls {
  // Create a writable signal for the `volume` local state. 
  volume = signal(0);
}
```

In the above example, the `CustomSlider` can write values into its `value` model input, which then propagates those values back to the `volume` signal in `MediaControls`. This binding keeps the values of `value` and `volume` in sync. Notice that the binding passes the `volume` signal instance, not the _value_ of the signal.

In other respects, model inputs work similarly to standard inputs. You can read the value by calling the signal function, including in reactive contexts like `computed` and `effect`.

See [Two-way binding](guide/templates/two-way-binding) for more details on two-way binding in templates.

### Two-way binding with plain properties

You can bind a plain JavaScript property to a model input.

```typescript
@Component({
  /* ... */
  // `value` is a model input.
  // The parenthesis-inside-square-brackets syntax (aka "banana-in-a-box") creates a two-way binding
  template: '<custom-slider [(value)]="volume" />',
})
export class MediaControls {
  protected volume = 0;
}
```

In the example above, the `CustomSlider` can write values into its `value` model input, which then propagates those values back to the `volume` property in `MediaControls`. This binding keeps the values of `value` and `volume` in sync.

### Implicit `change` events

When you declare a model input in a component or directive, Angular automatically creates a corresponding [output](guide/components/outputs) for that model. The output's name is the model input's name suffixed with "Change".

```typescript
@Directive({ /* ... */ })
export class CustomCheckbox {
  // This automatically creates an output named "checkedChange".
  // Can be subscribed to using `(checkedChange)="handler()"` in the template.
  checked = model(false);
}
```

Angular emits this change event whenever you write a new value into the model input by calling its `set` or `update` methods.

See [Custom events with outputs](guide/components/outputs) for more details on outputs.

### Customizing model inputs

You can mark a model input as required or provide an alias in the same way as a [standard input](guide/signals/inputs).

Model inputs do not support input transforms.

### When to use model inputs

Use model inputs when you want a component to support two-way binding. This is typically appropriate when a component exists to modify a value based on user interaction. Most commonly, custom form controls, such as a date picker or combobox, should use model inputs for their primary value.

## Choosing input names

Avoid choosing input names that collide with properties on DOM elements like HTMLElement. Name collisions introduce confusion about whether the bound property belongs to the component or the DOM element.

Avoid adding prefixes for component inputs like you would with component selectors. Since a given element can only host one component, any custom properties can be assumed to belong to the component.

## Declaring inputs with the `@Input` decorator

TIP: While the Angular team recommends using the signal-based `input` function for new projects, the original decorator-based `@Input` API remains fully supported.

You can alternatively declare component inputs by adding the `@Input` decorator to a property:

```ts
@Component({...})
export class CustomSlider {
  @Input() value = 0;
}
```
Binding to an input is the same in both signal-based and decorator-based inputs:

```html
<custom-slider [value]="50" />
```

### Customizing decorator-based inputs

The `@Input` decorator accepts a config object that lets you change the way that input works.

#### Required inputs

You can specify the `required` option to enforce that a given input must always have a value.

```ts
@Component({...})
export class CustomSlider {
  @Input({required: true}) value = 0;
}
```
If you try to use a component without specifying all of its required inputs, Angular reports an error at build-time.

#### Input transforms

You can specify a `transform` function to change the value of an input when it's set by Angular. This transform function works identically to transform functions for signal-based inputs described above.

```ts
@Component({
  selector: 'custom-slider',
  ...
})
export class CustomSlider {
  @Input({transform: trimString}) label = '';
}

function trimString(value: string | undefined) { return value?.trim() ?? ''; }
```
#### Input aliases

You can specify the `alias` option to change the name of an input in templates.

```ts
@Component({...})
export class CustomSlider {
  @Input({alias: 'sliderValue'}) value = 0;
}
```
```html
<custom-slider [sliderValue]="50" />
```

The `@Input` decorator also accepts the alias as its first parameter in place of the config object.

Input aliases work the same way as for signal-based inputs described above.

### Inputs with getters and setters

When using decorator-based inputs, a property implemented with a getter and setter can be an input:

```ts
export class CustomSlider {
  @Input()
  get value(): number {
    return this.internalValue;
  }

set value(newValue: number) { this.internalValue = newValue; }

private internalValue = 0;
}
```
You can even create a _write-only_ input by only defining a public setter:

```ts
export class CustomSlider {
  @Input()
  set value(newValue: number) {
    this.internalValue = newValue;
  }

private internalValue = 0;
}
```
**Prefer using input transforms instead of getters and setters** if possible.

Avoid complex or costly getters and setters. Angular may invoke an input's setter multiple times, which may negatively impact application performance if the setter performs any costly behaviors, such as DOM manipulation.

## Specify inputs in the `@Component` decorator

In addition to the `@Input` decorator, you can also specify a component's inputs with the `inputs` property in the `@Component` decorator. This can be useful when a component inherits a property from a base class:

```ts
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled'],
})
export class CustomSlider extends BaseSlider { }
```
You can additionally specify an input alias in the `inputs` list by putting the alias after a colon in the string:

```ts
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }
```

# Custom events with outputs

TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

Angular components can define custom events by assigning a property to the `output` function:

```ts
@Component({/*...*/})
export class ExpandablePanel {
  panelClosed = output<void>();
}
```
```html
<expandable-panel (panelClosed)="savePanelState()" />
```

The `output` function returns an `OutputEmitterRef`. You can emit an event by calling the `emit` method on the `OutputEmitterRef`:

```ts
this.panelClosed.emit();
```
Angular refers to properties initialized with the `output` function as **outputs**. You can use outputs to raise custom events, similar to native browser events like `click`.

**Angular custom events do not bubble up the DOM**.

**Output names are case-sensitive.**

When extending a component class, **outputs are inherited by the child class.**

The `output` function has special meaning to the Angular compiler. **You can exclusively call `output` in component and directive property initializers.**

## Emitting event data

You can pass event data when calling `emit`:

```ts
// You can emit primitive values.
this.valueChanged.emit(7);

// You can emit custom event objects
this.thumbDropped.emit({
  pointerX: 123,
  pointerY: 456,
})
```
When defining an event listener in a template, you can access the event data from the `$event` variable:

```html
<custom-slider (valueChanged)="logValue($event)" />
```

Receive the event data in the parent component:

```ts
@Component({
 /*...*/
})
export class App {
  logValue(value: number) {
    ...
  }
}
```
## Customizing output names

The `output` function accepts a parameter that lets you specify a different name for the event in a template:

```ts
@Component({/*...*/})
export class CustomSlider {
  changed = output({alias: 'valueChanged'});
}
```
```html
<custom-slider (valueChanged)="saveVolume()" />
```

This alias does not affect usage of the property in TypeScript code.

While you should generally avoid aliasing outputs for components, this feature can be useful for renaming properties while preserving an alias for the original name or for avoiding collisions with the name of native DOM events.

## Subscribing to outputs programmatically

When creating a component dynamically, you can programmatically subscribe to output events
from the component instance. The `OutputRef` type includes a `subscribe` method:

```ts
const someComponentRef: ComponentRef<SomeComponent> = viewContainerRef.createComponent(/*...*/);

someComponentRef.instance.someEventProperty.subscribe(eventData => {
  console.log(eventData);
});
```

Angular automatically cleans up event subscriptions when it destroys components with subscribers. Alternatively, you can manually unsubscribe from an event. The `subscribe` function returns an `OutputRefSubscription` with an `unsubscribe` method:

```typescript
const eventSubscription = someComponent.someEventProperty.subscribe(eventData => {
  console.log(eventData);
});

// ...

eventSubscription.unsubscribe();
```

## Choosing event names

Avoid choosing output names that collide with events on DOM elements like HTMLElement. Name collisions introduce confusion about whether the bound property belongs to the component or the DOM element.

Avoid adding prefixes for component outputs like you would with component selectors. Since a given element can only host one component, any custom properties can be assumed to belong to the component.

Always use [camelCase](https://en.wikipedia.org/wiki/Camel_case) output names. Avoid prefixing output names with "on".

## Using outputs with RxJS

See [RxJS interop with component and directive outputs](ecosystem/rxjs-interop/output-interop) for details on interoperability between outputs and RxJS.

## Declaring outputs with the `@Output` decorator

TIP: While the Angular team recommends using the `output` function for new projects, the
original decorator-based `@Output` API remains fully supported.

You can alternatively define custom events by assigning a property to a new `EventEmitter` and adding the `@Output` decorator:

```ts
@Component({/*...*/})
export class ExpandablePanel {
  @Output() panelClosed = new EventEmitter<void>();
}
```
You can emit an event by calling the `emit` method on the `EventEmitter`.

### Aliases with the `@Output` decorator

The `@Output` decorator accepts a parameter that lets you specify a different name for the event in a template:

```ts
@Component({/*...*/})
export class CustomSlider {
  @Output('valueChanged') changed = new EventEmitter<number>();
}
```
```html
<custom-slider (valueChanged)="saveVolume()" />
```

This alias does not affect usage of the property in TypeScript code.

## Specify outputs in the `@Component` decorator

In addition to the `@Output` decorator, you can also specify a component's outputs with the `outputs` property in the `@Component` decorator. This can be useful when a component inherits a property from a base class:

```ts
// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged'],
})
export class CustomSlider extends BaseSlider {}
```
You can additionally specify an output alias in the `outputs` list by putting the alias after a colon in the string:

```ts
// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged: volumeChanged'],
})
export class CustomSlider extends BaseSlider {}
```

# Content projection with ng-content

TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

You often need to create components that act as containers for different types of content. For
example, you may want to create a custom card component:

```typescript
@Component({
  selector: 'custom-card',
  template: '<div class="card-shadow">  </div>',
})
export class CustomCard {/* ... */}
```

**You can use the `<ng-content>` element as a placeholder to mark where content should go**:

```typescript
@Component({
  selector: 'custom-card',
  template: '<div class="card-shadow"> <ng-content></ng-content> </div>',
})
export class CustomCard {/* ... */}
```

TIP: `<ng-content>` works similarly
to [the native `<slot>` element](https://developer.mozilla.org/docs/Web/HTML/Element/slot),
but with some Angular-specific functionality.

When you use a component with `<ng-content>`, any children of the component host element are
rendered, or **projected**, at the location of that `<ng-content>`:

```typescript
// Component source
@Component({
  selector: 'custom-card',
  template: `
    <div class="card-shadow">
      <ng-content />
    </div>
  `,
})
export class CustomCard {/* ... */}
```

```html

<custom-card>
  <p>This is the projected content</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <p>This is the projected content</p>
  </div>
</custom-card>
```

Angular refers to any children of a component passed this way as that component's **content**. This
is distinct from the component's **view**, which refers to the elements defined in the component's
template.

**The `<ng-content>` element is neither a component nor DOM element**. Instead, it is a special
placeholder that tells Angular where to render content. Angular's compiler processes
all `<ng-content>` elements at build-time. You cannot insert, remove, or modify `<ng-content>` at
run time. You cannot add directives, styles, or arbitrary attributes to `<ng-content>`.

IMPORTANT: You should not conditionally include `<ng-content>` with `@if`, `@for`, or `@switch`. Angular always
instantiates and creates DOM nodes for content rendered to a `<ng-content>` placeholder, even if
that `<ng-content>` placeholder is hidden. For conditional rendering of component content,
see [Template fragments](api/core/ng-template).

## Multiple content placeholders

Angular supports projecting multiple different elements into different `<ng-content>` placeholders
based on CSS selector. Expanding the card example from above, you could create two placeholders for
a card title and a card body by using the `select` attribute:

```typescript
@Component({
  selector: 'card-title',
  template: `<ng-content>card-title</ng-content>`,
})
export class CardTitle {}

@Component({
  selector: 'card-body',
  template: `<ng-content>card-body</ng-content>`,
})
export class CardBody {}
```

```typescript

Component({
  selector: 'custom-card',
  template: `
  <div class="card-shadow">
    <ng-content select="card-title"></ng-content>
    <div class="card-divider"></div>
    <ng-content select="card-body"></ng-content>
  </div>
  `,
})
export class CustomCard {}
```

```typescript

@Component({
  selector: 'app-root',
  imports: [CustomCard, CardTitle, CardBody],
  template: `
    <custom-card>
      <card-title>Hello</card-title>
      <card-body>Welcome to the example</card-body>
    </custom-card>
`,
})
export class App {}
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>Hello</card-title>
    <div class="card-divider"></div>
    <card-body>Welcome to the example</card-body>
  </div>
</custom-card>
```

The `<ng-content>` placeholder supports the same CSS selectors
as [component selectors](guide/components/selectors).

If you include one or more `<ng-content>` placeholders with a `select` attribute and
one `<ng-content>` placeholder without a `select` attribute, the latter captures all elements that
did not match a `select` attribute:

```html

<div class="card-shadow">
  <ng-content select="card-title"></ng-content>
  <div class="card-divider"></div>
  
  <ng-content></ng-content>
</div>
```

```html

<custom-card>
  <card-title>Hello</card-title>
  <img src="..." />
  <p>Welcome to the example</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>Hello</card-title>
    <div class="card-divider"></div>
    <img src="..." />
    <p>Welcome to the example</p>
  </div>
</custom-card>
```

If a component does not include an `<ng-content>` placeholder without a `select` attribute, any
elements that don't match one of the component's placeholders do not render into the DOM.

## Fallback content

Angular can show *fallback content* for a component's `<ng-content>` placeholder if that component doesn't have any matching child content. You can specify fallback content by adding child content to the `<ng-content>` element itself.

```html

<div class="card-shadow">
  <ng-content select="card-title">Default Title</ng-content>
  <div class="card-divider"></div>
  <ng-content select="card-body">Default Body</ng-content>
</div>
```

```html

<custom-card>
  <card-title>Hello</card-title>
  
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>Hello</card-title>
    <div class="card-divider"></div>
    Default Body
  </div>
</custom-card>
```

## Aliasing content for projection

Angular supports a special attribute, `ngProjectAs`, that allows you to specify a CSS selector on
any element. Whenever an element with `ngProjectAs` is checked against an `<ng-content>`
placeholder, Angular compares against the `ngProjectAs` value instead of the element's identity:

```html

<div class="card-shadow">
  <ng-content select="card-title"></ng-content>
  <div class="card-divider"></div>
  <ng-content></ng-content>
</div>
```

```html

<custom-card>
  <h3 ngProjectAs="card-title">Hello</h3>

<p>Welcome to the example</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <h3>Hello</h3>
    <div class="card-divider"></div>
    <p>Welcome to the example</p>
  </div>
</custom-card>
```

`ngProjectAs` supports only static values and cannot be bound to dynamic expressions.
# Component Lifecycle

TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

A component's **lifecycle** is the sequence of steps that happen between the component's creation
and its destruction. Each step represents a different part of Angular's process for rendering
components and checking them for updates over time.

In your components, you can implement **lifecycle hooks** to run code during these steps.
Lifecycle hooks that relate to a specific component instance are implemented as methods on your
component class. Lifecycle hooks that relate the Angular application as a whole are implemented
as functions that accept a callback.

A component's lifecycle is tightly connected to how Angular checks your components for changes over
time. For the purposes of understanding this lifecycle, you only need to know that Angular walks
your application tree from top to bottom, checking template bindings for changes. The lifecycle
hooks described below run while Angular is doing this traversal. This traversal visits each
component exactly once, so you should always avoid making further state changes in the middle of the
process.

## Summary

<div class="docs-table docs-scroll-track-transparent">
  <table>
    <tr>
      <td><strong>Phase</strong></td>
      <td><strong>Method</strong></td>
      <td><strong>Summary</strong></td>
    </tr>
    <tr>
      <td>Creation</td>
      <td><code>constructor</code></td>
      <td>
        <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes/constructor" target="_blank">
          Standard JavaScript class constructor
        </a>. Runs when Angular instantiates the component.
      </td>
    </tr>
    <tr>
      <td rowspan="7">Change<p>Detection</td>
      <td><code>ngOnInit</code>
      </td>
      <td>Runs once after Angular has initialized all the component's inputs.</td>
    </tr>
    <tr>
      <td><code>ngOnChanges</code></td>
      <td>Runs every time the component's inputs have changed.</td>
    </tr>
    <tr>
      <td><code>ngDoCheck</code></td>
      <td>Runs every time this component is checked for changes.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentInit</code></td>
      <td>Runs once after the component's <em>content</em> has been initialized.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentChecked</code></td>
      <td>Runs every time this component content has been checked for changes.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewInit</code></td>
      <td>Runs once after the component's <em>view</em> has been initialized.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewChecked</code></td>
      <td>Runs every time the component's view has been checked for changes.</td>
    </tr>
    <tr>
      <td rowspan="2">Rendering</td>
      <td><code>afterNextRender</code></td>
      <td>Runs once the next time that <strong>all</strong> components have been rendered to the DOM.</td>
    </tr>
    <tr>
      <td><code>afterEveryRender</code></td>
      <td>Runs every time <strong>all</strong> components have been rendered to the DOM.</td>
    </tr>
    <tr>
      <td>Destruction</td>
      <td><code>ngOnDestroy</code></td>
      <td>Runs once before the component is destroyed.</td>
    </tr>
  </table>
</div>

### ngOnInit

The `ngOnInit` method runs after Angular has initialized all the components inputs with their
initial values. A component's `ngOnInit` runs exactly once.

This step happens _before_ the component's own template is initialized. This means that you can
update the component's state based on its initial input values.

### ngOnChanges

The `ngOnChanges` method runs after any component inputs have changed.

This step happens _before_ the component's own template is checked. This means that you can update
the component's state based on its initial input values.

During initialization, the first `ngOnChanges` runs before `ngOnInit`.

#### Inspecting changes

The `ngOnChanges` method accepts one `SimpleChanges` argument. This object is
a [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)
mapping each component input name to a `SimpleChange` object. Each `SimpleChange` contains the
input's previous value, its current value, and a flag for whether this is the first time the input
has changed.

```ts
@Component({
  /* ... */
})
export class UserProfile {
  name = input('');

ngOnChanges(changes: SimpleChanges) {
    for (const inputName in changes) {
      const inputValues = changes[inputName];
      console.log(`Previous ${inputName} == ${inputValues.previousValue}`);
      console.log(`Current ${inputName} == ${inputValues.currentValue}`);
      console.log(`Is first ${inputName} change == ${inputValues.firstChange}`);
    }
  }
}
```

If you provide an `alias` for any input properties, the `SimpleChanges` Record still uses the
TypeScript property name as a key, rather than the alias.

### ngOnDestroy

The `ngOnDestroy` method runs once just before a component is destroyed. Angular destroys a
component when it is no longer shown on the page, such as being hidden by `@if` or upon navigating
to another page.

#### DestroyRef

As an alternative to the `ngOnDestroy` method, you can inject an instance of `DestroyRef`. You can
register a callback to be invoked upon the component's destruction by calling the `onDestroy` method
of `DestroyRef`.

```ts
@Component({
  /* ... */
})
export class UserProfile {
  constructor() {
    inject(DestroyRef).onDestroy(() => {
      console.log('UserProfile destruction');
    });
  }
}
```

You can pass the `DestroyRef` instance to functions or classes outside your component. Use this
pattern if you have other code that should run some cleanup behavior when the component is
destroyed.

You can also use `DestroyRef` to keep setup code close to cleanup code, rather than putting
all cleanup code in the `ngOnDestroy` method.

### ngDoCheck

The `ngDoCheck` method runs before every time Angular checks a component's template for changes.

You can use this lifecycle hook to manually check for state changes outside of Angular's normal
change detection, manually updating the component's state.

This method runs very frequently and can significantly impact your page's performance. Avoid
defining this hook whenever possible, only using it when you have no alternative.

During initialization, the first `ngDoCheck` runs after `ngOnInit`.

### ngAfterContentInit

The `ngAfterContentInit` method runs once after all the children nested inside the component (its
_content_) have been initialized.

You can use this lifecycle hook to read the results of
[content queries](guide/components/queries#content-queries). While you can access the initialized
state of these queries, attempting to change any state in this method results in an
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)

### ngAfterContentChecked

The `ngAfterContentChecked` method runs every time the children nested inside the component (its
_content_) have been checked for changes.

This method runs very frequently and can significantly impact your page's performance. Avoid
defining this hook whenever possible, only using it when you have no alternative.

While you can access the updated state
of [content queries](guide/components/queries#content-queries) here, attempting to
change any state in this method results in
an [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### ngAfterViewInit

The `ngAfterViewInit` method runs once after all the children in the component's template (its
_view_) have been initialized.

You can use this lifecycle hook to read the results of
[view queries](guide/components/queries#view-queries). While you can access the initialized state of
these queries, attempting to change any state in this method results in an
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)

### ngAfterViewChecked

The `ngAfterViewChecked` method runs every time the children in the component's template (its
_view_) have been checked for changes.

This method runs very frequently and can significantly impact your page's performance. Avoid
defining this hook whenever possible, only using it when you have no alternative.

While you can access the updated state of [view queries](guide/components/queries#view-queries)
here, attempting to
change any state in this method results in
an [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### afterEveryRender and afterNextRender

The `afterEveryRender` and `afterNextRender` functions let you register a **render callback** to be
invoked after Angular has finished rendering _all components_ on the page into the DOM.

These functions are different from the other lifecycle hooks described in this guide. Rather than a
class method, they are standalone functions that accept a callback. The execution of render
callbacks are not tied to any specific component instance, but instead an application-wide hook.

`afterEveryRender` and `afterNextRender` must be called in
an [injection context](guide/di/dependency-injection-context), typically a
component's constructor.

You can use render callbacks to perform manual DOM operations.
See [Using DOM APIs](guide/components/dom-apis) for guidance on working with the DOM in Angular.

Render callbacks do not run during server-side rendering or during build-time pre-rendering.

#### after*Render phases

When using `afterEveryRender` or `afterNextRender`, you can optionally split the work into phases. The
phase gives you control over the sequencing of DOM operations, letting you sequence _write_
operations before _read_ operations in order to minimize
[layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing). In order to
communicate across phases, a phase function may return a result value that can be accessed in the
next phase.

```ts
import {Component, ElementRef, afterNextRender} from '@angular/core';

@Component({...})
export class UserProfile {
  private prevPadding = 0;
  private elementHeight = 0;

constructor() {
    private elementRef = inject(ElementRef);
    const nativeElement = elementRef.nativeElement;

afterNextRender({
      // Use the `Write` phase to write to a geometric property.
      write: () => {
        const padding = computePadding();
        const changed = padding !== this.prevPadding;
        if (changed) {
          nativeElement.style.padding = padding;
        }
        return changed; // Communicate whether anything changed to the read phase.
      },

// Use the `Read` phase to read geometric properties after all writes have occurred.
      read: (didWrite) => {
        if (didWrite) {
          this.elementHeight = nativeElement.getBoundingClientRect().height;
        }
      }
    });
  }
}
```

There are four phases, run in the following order:

| Phase            | Description                                                                                                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`      | Use this phase to read any layout-affecting DOM properties and styles that are strictly necessary for subsequent calculation. Avoid this phase if possible, preferring the `write` and `read` phases. |
| `mixedReadWrite` | Default phase. Use for any operations need to both read and write layout-affecting properties and styles. Avoid this phase if possible, preferring the explicit `write` and `read` phases.            |
| `write`          | Use this phase to write layout-affecting DOM properties and styles.                                                                                                                                   |
| `read`           | Use this phase to read any layout-affecting DOM properties.                                                                                                                                           |

## Lifecycle interfaces

Angular provides a TypeScript interface for each lifecycle method. You can optionally import
and `implement` these interfaces to ensure that your implementation does not have any typos or
misspellings.

Each interface has the same name as the corresponding method without the `ng` prefix. For example,
the interface for `ngOnInit` is `OnInit`.

```ts
@Component({
  /* ... */
})
export class UserProfile implements OnInit {
  ngOnInit() {
    /* ... */
  }
}
```

## Execution order

The following diagrams show the execution order of Angular's lifecycle hooks.

### During initialization

```mermaid
graph TD;
id[constructor]-->CHANGE;
subgraph CHANGE [Change detection]
direction TB
ngOnChanges-->ngOnInit;
ngOnInit-->ngDoCheck;
ngDoCheck-->ngAfterContentInit;
ngDoCheck-->ngAfterViewInit
ngAfterContentInit-->ngAfterContentChecked
ngAfterViewInit-->ngAfterViewChecked
end
CHANGE--Rendering-->afterNextRender-->afterEveryRender
```

### Subsequent updates

```mermaid
graph TD;
subgraph CHANGE [Change detection]
direction TB
ngOnChanges-->ngDoCheck
ngDoCheck-->ngAfterContentChecked;
ngDoCheck-->ngAfterViewChecked
end
CHANGE--Rendering-->afterEveryRender
```

### Ordering with directives

When you put one or more directives on the same element as a component, either in a template or with
the `hostDirectives` property, the framework does not guarantee any ordering of a given lifecycle
hook between the component and the directives on a single element. Never depend on an observed
ordering, as this may change in later versions of Angular.
Las plantillas de componentes no son solo HTML estático pueden usar datos de tu clase de componente y configurar manejadores para la interacción del usuario.

## Mostrar texto dinámico

En Angular, un *binding* crea una conexión dinámica entre la plantilla de un componente y sus datos. Esta conexión asegura que los cambios en los datos del componente actualicen automáticamente la plantilla renderizada.

Puedes crear un binding para mostrar texto dinámico en una plantilla usando llaves dobles:

```typescript
@Component({
  selector: 'user-profile',
  template: `<h1>Perfil {{userName()}}</h1>`,
})
export class TodoListItem {
  userName = signal('pro_programmer_123');
}
```

Cuando Angular renderiza el componente, verás:

```html
<h1>Perfil para pro_programmer_123</h1>
```

Angular mantiene automáticamente el binding actualizado cuando el valor de la signal cambia. Construyendo 
sobre el ejemplo anterior, si actualizamos el valor de la siganl `userName`:

```typescript
this.userName.set('cool_coder_789');
```

La página renderizada se actualiza para reflejar el nuevo valor:

```html
<h1>Perfil para cool_coder_789</h1>
```

## Estableciendo propiedades y atributos dinámicos

Angular soporta binding de valores dinámicos en propiedades del DOM con corchetes:

```typescript
@Component({
  /*...*/
  // Establecer la propiedad `disabled` del botón basada en el valor de `isValidUserId`.
  template: `<button [disabled]="isValidUserId()">Guardar cambios</button>`,
})
export class UserProfile {
  isValidUserId = signal(false);
}
```

También puedes hacer binding a *atributos* HTML prefijando el nombre del atributo con `attr.`:

```html

<ul [attr.role]="listRole()">
```

Angular actualiza automáticamente las propiedades y atributos del DOM cuando el valor vinculado cambia.

## Manejar la interacción del usuario

Angular te permite agregar event listeners a un elemento en tu plantilla con paréntesis:

```typescript
@Component({
  /*...*/
  // Agregar un manejador de evento 'click' que llama al método `cancelSubscription`. 
  template: `<button (click)="cancelSubscription()">Cancelar suscripción</button>`,
})
export class UserProfile {
  /* ... */
  
  cancelSubscription() { /* Tu código de manejo de eventos va aquí. */  }
}
```

Si necesitas pasar el objeto [event](https://developer.mozilla.org/es/docs/Web/API/Event) a tu listener, puedes usar la variable integrada `$event` de Angular dentro de la llamada de función:

```typescript
@Component({
  /*...*/
  // Agregar un manejador de evento 'click' que llama al método `cancelSubscription`. 
  template: `<button (click)="cancelSubscription($event)">Cancelar suscripción</button>`,
})
export class UserProfile {
  /* ... */
  
  cancelSubscription(event: Event) { /* Tu código de manejo de eventos va aquí. */  }
}
```

## Flujo de control con `@if` y `@for`

Puedes ocultar y mostrar condicionalmente partes de una plantilla con el bloque `@if` de Angular:

```html
<h1>Perfil de usuario</h1>

@if (isAdmin()) {
  <h2>Configuración de administrador</h2>
  
}
```

El bloque `@if` también soporta un bloque `@else` opcional:

```html
<h1>Perfil de usuario</h1>

@if (isAdmin()) {
  <h2>Configuración de administrador</h2>
  
} @else {
  <h2>Configuración de usuario</h2>
    
}
```

Puedes repetir parte de una plantilla múltiples veces con el bloque `@for` de Angular:

```html
<h1>Perfil de usuario</h1>

<ul class="user-badge-list">
  @for (badge of badges(); track badge.id) {
    <li class="user-badge">{{badge.name}}</li>
  }
</ul>
```

Angular usa la palabra clave `track`, mostrada en el ejemplo anterior, para asociar datos con los elementos del DOM creados por `@for`. Ve [_¿Por qué es importante track en bloques @for?_](guide/templates/control-flow#why-is-track-in-for-blocks-important) para más información.

¿Quieres saber más sobre plantillas Angular? Consulta la [Guía detallada de Plantillas](guide/templates) para todos los detalles.

## Siguiente paso

Ahora que la aplicación ya cuenta con datos dinámicos y plantillas, es momento de aprender cómo mejorar las plantillas ocultando o mostrando elementos de forma condicional, iterando sobre listas de elementos y más.
# Adding event listeners

Angular supports defining event listeners on an element in your template by specifying the event name inside parentheses along with a statement that runs every time the event occurs.

## Listening to native events

When you want to add event listeners to an HTML element, you wrap the event with parentheses, `()`, which allows you to specify a listener statement.

```typescript
@Component({
  template: `
    <input type="text" (keyup)="updateField()" />
  `,
  ...
})
export class AppComponent{
  updateField(): void {
    console.log('Field is updated!');
  }
}
```

In this example, Angular calls `updateField` every time the `<input>` element emits a `keyup` event.

You can add listeners for any native events, such as: `click`, `keydown`, `mouseover`, etc. To learn more, check out the [all available events on elements on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element#events).

## Accessing the event argument

In every template event listener, Angular provides a variable named `$event` that contains a reference to the event object.

```typescript
@Component({
  template: `
    <input type="text" (keyup)="updateField($event)" />
  `,
  ...
})
export class AppComponent {
  updateField(event: KeyboardEvent): void {
    console.log(`The user pressed: ${event.key}`);
  }
}
```

## Using key modifiers

When you want to capture specific keyboard events for a specific key, you might write some code like the following:

```typescript
@Component({
  template: `
    <input type="text" (keyup)="updateField($event)" />
  `,
  ...
})
export class AppComponent {
  updateField(event: KeyboardEvent): void {
    if (event.key === 'Enter') {
      console.log('The user pressed enter in the text field.');
    }
  }
}
```

However, since this is a common scenario, Angular lets you filter the events by specifying a specific key using the period (`.`) character. By doing so, code can be simplified to:

```typescript
@Component({
  template: `
    <input type="text" (keyup.enter)="updateField($event)" />
  `,
  ...
})
export class AppComponent{
  updateField(event: KeyboardEvent): void {
    console.log('The user pressed enter in the text field.');
  }
}
```

You can also add additional key modifiers:

```html

<input type="text" (keyup.shift.enter)="updateField($event)" />
```

Angular supports the modifiers `alt`, `control`, `meta`, and `shift`.

You can specify the key or code that you would like to bind to keyboard events. The key and code fields are a native part of the browser keyboard event object. By default, event binding assumes you want to use the [Key values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values).

Angular also allows you to specify [Code values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values) by providing a built-in `code` suffix.

```html

<input type="text" (keydown.code.alt.shiftleft)="updateField($event)" />
```

This can be useful for handling keyboard events consistently across different operating systems. For example, when using the Alt key on MacOS devices, the `key` property reports the key based on the character already modified by the Alt key. This means that a combination like Alt + S reports a `key` value of `'ß'`. The `code` property, however, corresponds to the physical or virtual button pressed rather than the character produced.

## Preventing event default behavior

If your event handler should replace the native browser behavior, you can use the event object's [`preventDefault` method](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault):

```typescript
@Component({
  template: `
    <a href="#overlay" (click)="showOverlay($event)">
  `,
  ...
})
export class AppComponent{
  showOverlay(event: PointerEvent): void {
    event.preventDefault();
    console.log('Show overlay without updating the URL!');
  }
}
```

If the event handler statement evaluates to `false`, Angular automatically calls `preventDefault()`, similar to [native event handler attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes). *Always prefer explicitly calling `preventDefault`*, as this approach makes the code's intent obvious.
# Binding dynamic text, properties and attributes

In Angular, a **binding** creates a dynamic connection between a component's template and its data. This connection ensures that changes to the component's data automatically update the rendered template.

## Render dynamic text with text interpolation

You can bind dynamic text in templates with double curly braces, which tells Angular that it is responsible for the expression inside and ensuring it is updated correctly. This is called **text interpolation**.

```typescript
@Component({
  template: `
    <p>Your color preference is {{ theme }}.</p>
  `,
  ...
})
export class AppComponent {
  theme = 'dark';
}
```

In this example, when the snippet is rendered to the page, Angular will replace `{{ theme }}` with `dark`.

```html

<p>Your color preference is dark.</p>
```

Bindings that change over time should read values from [signals](/guide/signals). Angular tracks the signals read in the template, and updates the rendered page when those signal values change.

```typescript
@Component({
  template: `
     
    <p>{{ welcomeMessage }}</p>

<p>Your color preference is {{ theme() }}.</p> 
  `
  ...
})
export class AppComponent {
  welcomeMessage = "Welcome, enjoy this app that we built for you"; 
  theme = signal('dark');
}
```
For more details, see the [Signals guide](/guide/signals).

Continuing the theme example, if a user clicks on a button that updates the `theme` signal to `'light'` after the page loads, the page updates accordingly to:

```html

<p>Your color preference is light.</p>
```

You can use text interpolation anywhere you would normally write text in HTML.

All expression values are converted to a string. Objects and arrays are converted using the value’s `toString` method.

## Binding dynamic properties and attributes

Angular supports binding dynamic values into object properties and HTML attributes with square brackets.

You can bind to properties on an HTML element's DOM instance, a [component](guide/components) instance, or a [directive](guide/directives) instance.

### Native element properties

Every HTML element has a corresponding DOM representation. For example, each `<button>` HTML element corresponds to an instance of `HTMLButtonElement` in the DOM. In Angular, you use property bindings to set values directly to the DOM representation of the element.

```html

<button [disabled]="isFormValid()">Save</button>
```

In this example, every time `isFormValid` changes, Angular automatically sets the `disabled` property of the `HTMLButtonElement` instance.

### Component and directive properties

When an element is an Angular component, you can use property bindings to set component input properties using the same square bracket syntax.

```html

<my-listbox [value]="mySelection()" />
```

In this example, every time `mySelection` changes, Angular automatically sets the `value` property of the `MyListbox` instance.

You can bind to directive properties as well.

```html

<img [ngSrc]="profilePhotoUrl()" alt="The current user's profile photo">
```

### Attributes

When you need to set HTML attributes that do not have corresponding DOM properties, such as ARIA attributes or SVG attributes, you can bind attributes to elements in your template with the `attr.` prefix.

```html

<ul [attr.role]="listRole()">
```

In this example, every time `listRole` changes, Angular automatically sets the `role` attribute of the `<ul>` element by calling `setAttribute`.

If the value of an attribute binding is `null`, Angular removes the attribute by calling `removeAttribute`.

### Text interpolation in properties and attributes

You can also use text interpolation syntax in properties and attributes by using the double curly brace syntax instead of square braces around the property or attribute name. When using this syntax, Angular treats the assignment as a property binding.

```html

<img src="profile-photo.jpg" alt="Profile photo of {{ firstName() }}" >
```

To bind to an attribute with the text interpolation syntax, prefix the attribute name with `attr.`

```html
<button attr.aria-label="Save changes to {{ objectType() }}">
```

## CSS class and style property bindings

Angular supports additional features for binding CSS classes and CSS style properties to elements.

### CSS classes

You can create a CSS class binding to conditionally add or remove a CSS class on an element based on whether the bound value is [truthy or falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).

```html

<ul [class.expanded]="isExpanded()">
```

You can also bind directly to the `class` property. Angular accepts three types of value:

| Description of `class` value                                                                                                                                      | TypeScript type       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| A string containing one or more CSS classes separated by spaces                                                                                                   | `string`              |
| An array of CSS class strings                                                                                                                                     | `string[]`            |
| An object where each property name is a CSS class name and each corresponding value determines whether that class is applied to the element, based on truthiness. | `Record<string, any>` |

```typescript
@Component({
  template: `
    <ul [class]="listClasses"> ... </ul>
    <section [class]="sectionClasses()"> ... </section>
    <button [class]="buttonClasses()"> ... </button>
  `,
  ...
})
export class UserProfile {
  listClasses = 'full-width outlined';
  sectionClasses = signal(['expandable', 'elevated']);
  buttonClasses = signal({
    highlighted: true,
    embiggened: false,
  });
}
```

The above example renders the following DOM:

```html
<ul class="full-width outlined"> ... </ul>
<section class="expandable elevated"> ... </section>
<button class="highlighted"> ... </button>
```

Angular ignores any string values that are not valid CSS class names.

When using static CSS classes, directly binding `class`, and binding specific classes, Angular intelligently combines all of the classes in the rendered result.

```typescript
@Component({
  template: `<ul class="list" [class]="listType()" [class.expanded]="isExpanded()"> ...`,
  ...
})
export class Listbox {
  listType = signal('box');
  isExpanded = signal(true);
}
```

In the example above, Angular renders the `ul` element with all three CSS classes.

```html
<ul class="list box expanded">
```

Angular does not guarantee any specific order of CSS classes on rendered elements.

When binding `class` to an array or an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object or array instance when you modify these values in order for Angular to apply any updates.

If an element has multiple bindings for the same CSS class, Angular resolves collisions by following its style precedence order.

NOTE: Class bindings do not support space-separated class names in a single key. They also don't support mutations on objects as the reference of the binding remains the same. If you need one or the other, use the [ngClass](/api/common/NgClass) directive.

### CSS style properties

You can also bind to CSS style properties directly on an element.

```html

<section [style.display]="isExpanded() ? 'block' : 'none'">
```

You can further specify units for CSS properties that accept units.

```html

<section [style.height.px]="sectionHeightInPixels()">
```

You can also set multiple style values in one binding. Angular accepts the following types of value:

| Description of `style` value                                                                                              | TypeScript type       |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| A string containing zero or more CSS declarations, such as `"display: flex; margin: 8px"`.                                | `string`              |
| An object where each property name is a CSS property name and each corresponding value is the value of that CSS property. | `Record<string, any>` |

```typescript
@Component({
  template: `
    <ul [style]="listStyles()"> ... </ul>
    <section [style]="sectionStyles()"> ... </section>
  `,
  ...
})
export class UserProfile {
  listStyles = signal('display: flex; padding: 8px');
  sectionStyles = signal({
    border: '1px solid black',
    'font-weight': 'bold',
  });
}
```

The above example renders the following DOM.

```html
<ul style="display: flex; padding: 8px"> ... </ul>
<section style="border: 1px solid black; font-weight: bold"> ... </section>
```

When binding `style` to an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object instance when you modify these values in order to Angular to apply any updates.

If an element has multiple bindings for the same style property, Angular resolves collisions by following its style precedence order.
# Control flow

Angular templates support control flow blocks that let you conditionally show, hide, and repeat elements.

## Conditionally display content with `@if`, `@else-if` and `@else`

The `@if` block conditionally displays its content when its condition expression is truthy:

```html
@if (a > b) {
  <p>{{a}} is greater than {{b}}</p>
}
```

If you want to display alternative content, you can do so by providing any number of `@else if` blocks and a singular `@else` block.

```html
@if (a > b) {
  {{a}} is greater than {{b}}
} @else if (b > a) {
  {{a}} is less than {{b}}
} @else {
  {{a}} is equal to {{b}}
}
```

### Referencing the conditional expression's result

The `@if` conditional supports saving the result of the conditional expression into a variable for reuse inside of the block.

```html
@if (user.profile.settings.startDate; as startDate) {
  {{ startDate }}
}
```

This can be useful for referencing longer expressions that would be easier to read and maintain within the template.

## Repeat content with the `@for` block

The `@for` block loops through a collection and repeatedly renders the content of a block. The collection can be any JavaScript [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols), but Angular has additional performance optimizations for `Array` values.

A typical `@for` loop looks like:

```html
@for (item of items; track item.id) {
  {{ item.name }}
}
```

Angular's `@for` block does not support flow-modifying statements like JavaScript's `continue` or `break`.

### Why is `track` in `@for` blocks important?

The `track` expression allows Angular to maintain a relationship between your data and the DOM nodes on the page. This allows Angular to optimize performance by executing the minimum necessary DOM operations when the data changes.

Using track effectively can significantly improve your application's rendering performance when looping over data collections.

Select a property that uniquely identifies each item in the `track` expression. If your data model includes a uniquely identifying property, commonly `id` or `uuid`, use this value. If your data does not include a field like this, strongly consider adding one.

For static collections that never change, you can use `$index` to tell Angular to track each item by its index in the collection.

If no other option is available, you can specify `identity`. This tells Angular to track the item by its reference identity using the triple-equals operator (`===`). Avoid this option whenever possible as it can lead to significantly slower rendering updates, as Angular has no way to map which data item corresponds to which DOM nodes.

### Contextual variables in `@for` blocks

Inside `@for` blocks, several implicit variables are always available:

| Variable | Meaning                                       |
| -------- | --------------------------------------------- |
| `$count` | Number of items in a collection iterated over |
| `$index` | Index of the current row                      |
| `$first` | Whether the current row is the first row      |
| `$last`  | Whether the current row is the last row       |
| `$even`  | Whether the current row index is even         |
| `$odd`   | Whether the current row index is odd          |

These variables are always available with these names, but can be aliased via a `let` segment:

```html
@for (item of items; track item.id; let idx = $index, e = $even) {
  <p>Item #{{ idx }}: {{ item.name }}</p>
}
```

The aliasing is useful when nesting `@for` blocks, letting you read variables from the outer `@for` block from an inner `@for` block.

### Providing a fallback for `@for` blocks with the `@empty` block

You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty` block displays when there are no items:

```html
@for (item of items; track item.name) {
  <li> {{ item.name }}</li>
} @empty {
  <li aria-hidden="true"> There are no items. </li>
}
```

## Conditionally display content with the `@switch` block

While the `@if` block is great for most scenarios, the `@switch` block provides an alternate syntax to conditionally render data. Its syntax closely resembles JavaScript's `switch` statement.

```html
@switch (userPermissions) {
  @case ('admin') {
    <app-admin-dashboard />
  }
  @case ('reviewer') {
    <app-reviewer-dashboard />
  }
  @case ('editor') {
    <app-editor-dashboard />
  }
  @default {
    <app-viewer-dashboard />
  }
}
```

The value of the conditional expression is compared to the case expression using the triple-equals (`===`) operator.

**`@switch` does not have a fallthrough**, so you do not need an equivalent to a `break` or `return` statement in the block.

You can optionally include a `@default` block. The content of the `@default` block displays if none of the preceding case expressions match the switch value.

If no `@case` matches the expression and there is no `@default` block, nothing is shown.
# Variables in templates

Angular has two types of variable declarations in templates: local template variables and template reference variables.

## Local template variables with `@let`

Angular's `@let` syntax allows you to define a local variable and re-use it across a template, similar to the [JavaScript `let` syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let).

### Using `@let`

Use `@let` to declare a variable whose value is based on the result of a template expression. Angular automatically keeps the variable's value up-to-date with the given expression, similar to [bindings](./templates/bindings).

```html
@let name = user.name;
@let greeting = 'Hello, ' + name;
@let data = data$ | async;
@let pi = 3.14159;
@let coordinates = {x: 50, y: 100};
@let longExpression = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit ' +
                      'sed do eiusmod tempor incididunt ut labore et dolore magna ' +
                      'Ut enim ad minim veniam...';
```

Each `@let` block can declare exactly one variable. You cannot declare multiple variables in the same block with a comma.

### Referencing the value of `@let`

Once you've declared a variable with `@let`, you can reuse it in the same template:

```html
@let user = user$ | async;

@if (user) {
  <h1>Hello, {{user.name}}</h1>
  <user-avatar [photo]="user.photo"/>

<ul>
    @for (snack of user.favoriteSnacks; track snack.id) {
      <li>{{snack.name}}</li>
    }
  </ul>

<button (click)="update(user)">Update profile</button>
}
```

### Assignability

A key difference between `@let` and JavaScript's `let` is that `@let` cannot be reassigned after declaration. However, Angular automatically keeps the variable's value up-to-date with the given expression.

```html
@let value = 1;

<button (click)="value = value + 1">Increment the value</button>
```

### Variable scope

`@let` declarations are scoped to the current view and its descendants. Angular creates a new view at component boundaries and wherever a template might contain dynamic content, such as control flow blocks, `@defer` blocks, or structural directives.

Since `@let` declarations are not hoisted, they **cannot** be accessed by parent views or siblings:

```html
@let topLevel = value;

<div>
  @let insideDiv = value;
</div>

{{topLevel}} 
{{insideDiv}}

@if (condition) {
  {{topLevel + insideDiv}}

@let nested = value;

@if (condition) {
    {{topLevel + insideDiv + nested}} 
  }
}

{{nested}} 
```

### Full syntax

The `@let` syntax is formally defined as:

- The `@let` keyword.
- Followed by one or more whitespaces, not including new lines.
- Followed by a valid JavaScript name and zero or more whitespaces.
- Followed by the = symbol and zero or more whitespaces.
- Followed by an Angular expression which can be multi-line.
- Terminated by the `;` symbol.

## Template reference variables

Template reference variables give you a way to declare a variable that references a value from an element in your template.

A template reference variable can refer to the following:

- a DOM element within a template (including [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements))
- an Angular component or directive
- a [TemplateRef](/api/core/TemplateRef) from an [ng-template](/api/core/ng-template)

You can use template reference variables to read information from one part of the template in another part of the same template.

### Declaring a template reference variable

You can declare a variable on an element in a template by adding an attribute that starts with the hash character (`#`) followed by the variable name.

```html

<input #taskInput placeholder="Enter task name">
```

### Assigning values to template reference variables

Angular assigns a value to template variables based on the element on which the variable is declared.

If you declare the variable on a Angular component, the variable refers to the component instance.

```html

<my-datepicker #startDate />
```

If you declare the variable on an `<ng-template>` element, the variable refers to a TemplateRef instance which represents the template. For more information, see [How Angular uses the asterisk, \*, syntax](/guide/directives/structural-directives#structural-directive-shorthand) in [Structural directives](/guide/directives/structural-directives).

```html

<ng-template #myFragment>
  <p>This is a template fragment</p>
</ng-template>
```

If you declare the variable on any other displayed element, the variable refers to the `HTMLElement` instance.

```html

<input #taskInput placeholder="Enter task name">
```

#### Assigning a reference to an Angular directive

Angular directives may have an `exportAs` property that defines a name by which the directive can be referenced in a template:

```typescript
@Directive({
  selector: '[dropZone]',
  exportAs: 'dropZone',
})
export class DropZone { /* ... */ }
```

When you declare a template variable on an element, you can assign that variable a directive instance by specifying this `exportAs` name:

```html

<section dropZone #firstZone="dropZone"> ... </section>
```

You cannot refer to a directive that does not specify an `exportAs` name.

### Using template reference variables with queries

In addition to using template variables to read values from another part of the same template, you can also use this style of variable declaration to "mark" an element for [component and directive queries](/guide/components/queries).

When you want to query for a specific element in a template, you can declare a template variable on that element and then query for the element based on the variable name.

```html
<input #description value="Original description">
```

```typescript
@Component({
  /* ... */,
  template: `<input #description value="Original description">`,
})
export class AppComponent {
  // Query for the input element based on the template variable name.
  @ViewChild('description') input: ElementRef | undefined;
}
```

See [Referencing children with queries](/guide/components/queries) for more information on queries.
# Deferred loading with `@defer`

Deferrable views, also known as `@defer` blocks, reduce the initial bundle size of your application by deferring the loading of code that is not strictly necessary for the initial rendering of a page. This often results in a faster initial load and improvement in Core Web Vitals (CWV), primarily Largest Contentful Paint (LCP) and Time to First Byte (TTFB).

To use this feature, you can declaratively wrap a section of your template in a @defer block:

```html
@defer {
  <large-component />
}
```

The code for any components, directives, and pipes inside the `@defer` block is split into a separate JavaScript file and loaded only when necessary, after the rest of the template has been rendered.

Deferrable views support a variety of triggers, prefetching options, and sub-blocks for placeholder, loading, and error state management.

## Which dependencies are deferred?

Components, directives, pipes, and any component CSS styles can be deferred when loading an application.

In order for the dependencies within a `@defer` block to be deferred, they need to meet two conditions:

1. **They must be standalone.** Non-standalone dependencies cannot be deferred and are still eagerly loaded, even if they are inside of `@defer` blocks.
1. **They cannot be referenced outside of `@defer` blocks within the same file.** If they are referenced outside the `@defer` block or referenced within ViewChild queries, the dependencies will be eagerly loaded.

The _transitive_ dependencies of the components, directives and pipes used in the `@defer` block do not strictly need to be standalone; transitive dependencies can still be declared in an `NgModule` and participate in deferred loading.

Angular's compiler produces a [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) statement for each component, directive, and pipe used in the `@defer` block. The main content of the block renders after all the imports resolve. Angular does not guarantee any particular order for these imports.

## How to manage different stages of deferred loading

`@defer` blocks have several sub blocks to allow you to gracefully handle different stages in the deferred loading process.

### `@defer`

This is the primary block that defines the section of content that is lazily loaded. It is not rendered initially– deferred content loads and renders once the specified [trigger](/guide/templates/defer#triggers) occurs or the `when` condition is met.

By default, a @defer block is triggered when the browser state becomes [idle](/guide/templates/defer#idle).

```html
@defer {
  <large-component />
}
```

### Show placeholder content with `@placeholder`

By default, defer blocks do not render any content before they are triggered.

The `@placeholder` is an optional block that declares what content to show before the `@defer` block is triggered.

```html
@defer {
  <large-component />
} @placeholder {
  <p>Placeholder content</p>
}
```

While optional, certain triggers may require the presence of either a `@placeholder` or a [template reference variable](/guide/templates/variables#template-reference-variables) to function. See the [Triggers](/guide/templates/defer#triggers) section for more details.

Angular replaces placeholder content with the main content once loading is complete. You can use any content in the placeholder section including plain HTML, components, directives, and pipes. Keep in mind the _dependencies of the placeholder block are eagerly loaded_.

The `@placeholder` block accepts an optional parameter to specify the `minimum` amount of time that this placeholder should be shown after the placeholder content initially renders.

```html
@defer {
  <large-component />
} @placeholder (minimum 500ms) {
  <p>Placeholder content</p>
}
```

This `minimum` parameter is specified in time increments of milliseconds (ms) or seconds (s). You can use this parameter to prevent fast flickering of placeholder content in the case that the deferred dependencies are fetched quickly.

### Show loading content with `@loading`

The `@loading` block is an optional block that allows you to declare content that is shown while deferred dependencies are loading. It replaces the `@placeholder` block once loading is triggered.

```html
@defer {
  <large-component />
} @loading {
  <img alt="loading..." src="loading.gif" />
} @placeholder {
  <p>Placeholder content</p>
}
```

Its dependencies are eagerly loaded (similar to `@placeholder`).

The `@loading` block accepts two optional parameters to help prevent fast flickering of content that may occur when deferred dependencies are fetched quickly,:

- `minimum` - the minimum amount of time that this placeholder should be shown
- `after` - the amount of time to wait after loading begins before showing the loading template

```html
@defer {
  <large-component />
} @loading (after 100ms; minimum 1s) {
  <img alt="loading..." src="loading.gif" />
}
```

Both parameters are specified in time increments of milliseconds (ms) or seconds (s). In addition, the timers for both parameters begin immediately after the loading has been triggered.

### Show error state when deferred loading fails with `@error`

The `@error` block is an optional block that displays if deferred loading fails. Similar to `@placeholder` and `@loading`, the dependencies of the @error block are eagerly loaded.

```html
@defer {
  <large-component />
} @error {
  <p>Failed to load large component.</p>
}
```

## Controlling deferred content loading with triggers

You can specify **triggers** that control when Angular loads and displays deferred content.

When a `@defer` block is triggered, it replaces placeholder content with lazily loaded content.

Multiple event triggers can be defined by separating them with a semicolon, `;` and will be evaluated as OR conditions.

There are two types of triggers: `on` and `when`.

### `on`

`on` specifies a condition for when the `@defer` block is triggered.

The available triggers are as follows:

| Trigger                       | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| [`idle`](#idle)               | Triggers when the browser is idle.                                     |
| [`viewport`](#viewport)       | Triggers when specified content enters the viewport                    |
| [`interaction`](#interaction) | Triggers when the user interacts with specified element                |
| [`hover`](#hover)             | Triggers when the mouse hovers over specified area                     |
| [`immediate`](#immediate)     | Triggers immediately after non-deferred content has finished rendering |
| [`timer`](#timer)             | Triggers after a specific duration                                     |

#### `idle`

The `idle` trigger loads the deferred content once the browser has reached an idle state, based on requestIdleCallback. This is the default behavior with a defer block.

```html

@defer {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `viewport`

The `viewport` trigger loads the deferred content when the specified content enters the viewport using the [Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API). Observed content may be `@placeholder` content or an explicit element reference.

By default, the `@defer` watches for the placeholder entering the viewport. Placeholders used this way must have a single root element.

```html
@defer (on viewport) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched to enter the viewport. This variable is passed in as a parameter on the viewport trigger.

```html
<div #greeting>Hello!</div>
@defer (on viewport(greeting)) {
  <greetings-cmp />
}
```

#### `interaction`

The `interaction` trigger loads the deferred content when the user interacts with the specified element through `click` or `keydown` events.

By default, the placeholder acts as the interaction element. Placeholders used this way must have a single root element.

```html
@defer (on interaction) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched for interactions. This variable is passed in as a parameter on the viewport trigger.

```html
<div #greeting>Hello!</div>
@defer (on interaction(greeting)) {
  <greetings-cmp />
}
```

#### `hover`

The `hover` trigger loads the deferred content when the mouse has hovered over the triggered area through the `mouseover` and `focusin` events.

By default, the placeholder acts as the interaction element. Placeholders used this way must have a single root element.

```html
@defer (on hover) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

```html
<div #greeting>Hello!</div>
@defer (on hover(greeting)) {
  <greetings-cmp />
}
```

#### `immediate`

The `immediate` trigger loads the deferred content immediately. This means that the deferred block loads as soon as all other non-deferred content has finished rendering.

```html
@defer (on immediate) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `timer`

The `timer` trigger loads the deferred content after a specified duration.

```html
@defer (on timer(500ms)) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

The duration parameter must be specified in milliseconds (`ms`) or seconds (`s`).

### `when`

The `when` trigger accepts a custom conditional expression and loads the deferred content when the condition becomes truthy.

```html
@defer (when condition) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

This is a one-time operation– the `@defer` block does not revert back to the placeholder if the condition changes to a falsy value after becoming truthy.

## Prefetching data with `prefetch`

In addition to specifying a condition that determines when deferred content is shown, you can optionally specify a **prefetch trigger**. This trigger lets you load the JavaScript associated with the `@defer` block before the deferred content is shown.

Prefetching enables more advanced behaviors, such as letting you start to prefetch resources before a user has actually seen or interacted with a defer block, but might interact with it soon, making the resources available faster.

You can specify a prefetch trigger similarly to the block's main trigger, but prefixed with the `prefetch` keyword. The block's main trigger and prefetch trigger are separated with a semi-colon character (`;`).

In the example below, the prefetching starts when a browser becomes idle and the contents of the block is rendered only once the user interacts with the placeholder.

```html
@defer (on interaction; prefetch on idle) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

## Testing `@defer` blocks

Angular provides TestBed APIs to simplify the process of testing `@defer` blocks and triggering different states during testing. By default, `@defer` blocks in tests play through like a defer block would behave in a real application. If you want to manually step through states, you can switch the defer block behavior to `Manual` in the TestBed configuration.

```typescript
it('should render a defer block in different states', async () => {
  // configures the defer block behavior to start in "paused" state for manual control.
  TestBed.configureTestingModule({deferBlockBehavior: DeferBlockBehavior.Manual});
  @Component({
    // ...
    template: `
      @defer {
        <large-component />
      } @placeholder {
        Placeholder
      } @loading {
        Loading...
      }
    `
  })
  class ComponentA {}
  // Create component fixture.
  const componentFixture = TestBed.createComponent(ComponentA);
  // Retrieve the list of all defer block fixtures and get the first block.
  const deferBlockFixture = (await componentFixture.getDeferBlocks())[0];
  // Renders placeholder state by default.
  expect(componentFixture.nativeElement.innerHTML).toContain('Placeholder');
  // Render loading state and verify rendered output.
  await deferBlockFixture.render(DeferBlockState.Loading);
  expect(componentFixture.nativeElement.innerHTML).toContain('Loading');
  // Render final state and verify the output.
  await deferBlockFixture.render(DeferBlockState.Complete);
  expect(componentFixture.nativeElement.innerHTML).toContain('large works!');
});
```

## Does `@defer` work with `NgModule`?

`@defer` blocks are compatible with both standalone and NgModule-based components, directives and pipes. However, **only standalone components, directives and pipes can be deferred**. NgModule-based dependencies are not deferred and are included in the eagerly loaded bundle.

## Compatibility between `@defer` blocks and Hot Module Reload (HMR)

When Hot Module Replacement (HMR) is active, all `@defer` block chunks are fetched eagerly, overriding any configured triggers. To restore the standard trigger behavior, you must disable HMR by serving your application with the `--no-hmr` flag.

## How does `@defer` work with server-side rendering (SSR) and static-site generation (SSG)?

By default, when rendering an application on the server (either using SSR or SSG), defer blocks always render their `@placeholder` (or nothing if a placeholder is not specified) and triggers are not invoked. On the client, the content of the `@placeholder` is hydrated and triggers are activated.

To render the main content of `@defer` blocks on the server (both SSR and SSG), you can enable [the Incremental Hydration feature](/guide/incremental-hydration) and configure `hydrate` triggers for the necessary blocks.

## Best practices for deferring views

### Avoid cascading loads with nested `@defer` blocks

When you have nested `@defer` blocks, they should have different triggers in order to avoid loading simultaneously, which causes cascading requests and may negatively impact page load performance.

### Avoid layout shifts

Avoid deferring components that are visible in the user’s viewport on initial load. Doing this may negatively affect Core Web Vitals by causing an increase in cumulative layout shift (CLS).

In the event this is necessary, avoid `immediate`, `timer`, `viewport`, and custom `when` triggers that cause the content to load during the initial page render.
# Expression Syntax

Angular expressions are based on JavaScript, but differ in some key ways. This guide walks through the similarities and differences between Angular expressions and standard JavaScript.

## Value literals

Angular supports a subset of [literal values](https://developer.mozilla.org/en-US/docs/Glossary/Literal) from JavaScript.

### Supported value literals

| Literal type    | Example values                  |
| --------------- | ------------------------------- |
| String          | `'Hello'`, `"World"`            |
| Boolean         | `true`, `false`                 |
| Number          | `123`, `3.14`                   |
| Object          | `{name: 'Alice'}`               |
| Array           | `['Onion', 'Cheese', 'Garlic']` |
| null            | `null`                          |
| Template string | `` `Hello ${name}` ``           |

### Unsupported literals

| Literal type | Example value |
| ------------ | ------------- |
| RegExp       | `/\d+/`       |

### Unsupported value literals

| Literal type | Example values |
|--------------|----------------|
| BigInt       | `1n`           |

## Globals

Angular expressions support the following [globals](https://developer.mozilla.org/en-US/docs/Glossary/Global_object):

- [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)
- [$any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any)

No other JavaScript globals are supported. Common JavaScript globals include `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt`, and more.

## Local variables

Angular automatically makes special local variables available for use in expressions in specific contexts. These special variables always start with the dollar sign character (`$`).

For example, `@for` blocks make several local variables corresponding to information about the loop, such as `$index`.

## What operators are supported?

### Supported operators

Angular supports the following operators from standard JavaScript.

| Operator                      | Example(s)                                     |
| ----------------------------- | ---------------------------------------------- |
| Add / Concatenate             | `1 + 2`                                        |
| Subtract                      | `52 - 3`                                       |
| Multiply                      | `41 * 6`                                       |
| Divide                        | `20 / 4`                                       |
| Remainder (Modulo)            | `17 % 5`                                       |
| Exponentiation                | `10 ** 3`                                      |
| Parenthesis                   | `9 * (8 + 4)`                                  |
| Conditional (Ternary)         | `a > b ? true : false`                         |
| And (Logical)                 | `&&`                                           |
| Or (Logical)                  | `\|\|`                                         |
| Not (Logical)                 | `!`                                            |
| Nullish Coalescing            | `possiblyNullValue ?? 'default'`               |
| Comparison Operators          | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==`, `!=` |
| Unary Negation                | `-x`                                           |
| Unary Plus                    | `+y`                                           |
| Property Accessor             | `person['name']`                               |
| Assignment                    | `a = b`                                        |
| Addition Assignment           | `a += b`                                       |
| Subtraction Assignment        | `a -= b`                                       |
| Multiplication Assignment     | `a *= b`                                       |
| Division Assignment           | `a /= b`                                       |
| Remainder Assignment          | `a %= b`                                       |
| Exponentiation Assignment     | `a **= b`                                      |
| Logical AND Assignment        | `a &&= b`                                      |
| Logical OR Assignment         | `a \|\|= b`                                    |
| Nullish Coalescing Assignment | `a ??= b`                                      |

Angular expressions additionally also support the following non-standard operators:

| Operator                        | Example(s)                     |
| ------------------------------- | ------------------------------ |
| [Pipe](/guide/templates/pipes)  | `{{ total \| currency }}`      |
| Optional chaining\*             | `someObj.someProp?.nestedProp` |
| Non-null assertion (TypeScript) | `someObj!.someProp`            |

NOTE: Optional chaining behaves differently from the standard JavaScript version in that if the left side of Angular’s optional chaining operator is `null` or `undefined`, it returns `null` instead of `undefined`.

### Unsupported operators

| Operator              | Example(s)                        |
| --------------------- | --------------------------------- |
| All bitwise operators | `&`, `&=`, `~`, `\|=`, `^=`, etc. |
| Object destructuring  | `const { name } = person`         |
| Array destructuring   | `const [firstItem] = items`       |
| Comma operator        | `x = (x++, x)`                    |
| instanceof            | `car instanceof Automobile`       |
| new                   | `new Car()`                       |

## Lexical context for expressions

Angular expressions are evaluated within the context of the component class as well as any relevant [template variables](/guide/templates/variables), locals, and globals.

When referring to component class members, `this` is always implied. However, if a template declares a [template variables](guide/templates/variables) with the same name as a member, the variable shadows that member. You can unambiguously reference such a class member by explicitly using `this.`. This can be useful when creating an `@let` declaration that shadows a class member, e.g. for signal narrowing purposes.

## Declarations

Generally speaking, declarations are not supported in Angular expressions. This includes, but is not limited to:

| Declarations    | Example(s)                                  |
| --------------- | ------------------------------------------- |
| Variables       | `let label = 'abc'`, `const item = 'apple'` |
| Functions       | `function myCustomFunction() { }`           |
| Arrow Functions | `() => { }`                                 |
| Classes         | `class Rectangle { }`                       |

# Event listener statements

Event handlers are **statements** rather than expressions. While they support all of the same syntax as Angular expressions, there are two key differences:

1. Statements **do support** assignment operators (but not destructing assignments)
1. Statements **do not support** pipes
# Directivas de atributo

Cambia la apariencia o comportamiento de elementos DOM y componentes Angular con directivas de atributo.

## Construyendo una directiva de atributo

Esta sección te guía a través de la creación de una directiva de resaltado que establece el color de fondo del elemento host en amarillo.

1. Para crear una directiva, usa el comando CLI [`ng generate directive`](tools/cli/schematics).

```shell
ng generate directive highlight
```
    El CLI crea `src/app/highlight.directive.ts`, un archivo de prueba correspondiente `src/app/highlight.directive.spec.ts`.

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.0.ts"/>

La propiedad de configuración del decorador `@Directive()` especifica el selector de atributo CSS de la directiva, `[appHighlight]`.

1. Importa `ElementRef` desde `@angular/core`.
    `ElementRef` otorga acceso directo al elemento DOM host a través de su propiedad `nativeElement`.

1. Añade `ElementRef` en el `constructor()` de la directiva para [inyectar](guide/di) una referencia al elemento DOM host, el elemento al que aplicas `appHighlight`.

1. Añade lógica a la clase `HighlightDirective` que establece el fondo a amarillo.

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.1.ts"/>

ÚTIL: Las directivas *no* soportan espacios de nombres.

<docs-code header="src/app/app.component.avoid.html (no soportado)" path="adev/src/content/examples/attribute-directives/src/app/app.component.avoid.html" visibleRegion="unsupported"/>

## Aplicando una directiva de atributo

1. Para usar `HighlightDirective`, añade un elemento `<p>` a la plantilla HTML con la directiva como atributo.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.1.html" visibleRegion="applied"/>

Angular crea una instancia de la clase `HighlightDirective` e inyecta una referencia al elemento `<p>` en el constructor de la directiva, que establece el estilo de fondo del elemento `<p>` a amarillo.

## Manejando eventos de usuario

Esta sección te muestra cómo detectar cuando un usuario pasa el mouse sobre o fuera del elemento y responder estableciendo o limpiando el color de resaltado.

1. Importa `HostListener` desde '@angular/core'.

<docs-code header="src/app/highlight.directive.ts (importaciones)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts" visibleRegion="imports"/>

1. Añade dos manejadores de eventos que responden cuando el mouse entra o sale, cada uno con el decorador `@HostListener()`.

<docs-code header="src/app/highlight.directive.ts (métodos-mouse)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts" visibleRegion="mouse-methods"/>

Suscríbete a eventos del elemento DOM que aloja una directiva de atributo, el `<p>` en este caso, con el decorador `@HostListener()`.

ÚTIL: Los manejadores delegan a un método auxiliar, `highlight()`, que establece el color en el elemento DOM host, `el`.

La directiva completa es la siguiente:

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts"/>

El color de fondo aparece cuando el puntero se desplaza sobre el elemento de párrafo y desaparece cuando el puntero se mueve fuera.

## Pasando valores a una directiva de atributo

Esta sección te guía a través de establecer el color de resaltado mientras aplicas `HighlightDirective`.

1. En `highlight.directive.ts`, importa `Input` desde `@angular/core`.

<docs-code header="src/app/highlight.directive.ts (importaciones)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="imports"/>

1. Añade una propiedad `input` `appHighlight`.

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="input"/>

La función `input()` añade metadatos a la clase que hace que la propiedad `appHighlight` de la directiva esté disponible para enlace.

2. En `app.component.ts`, añade una propiedad `color` al `AppComponent`.

<docs-code header="src/app/app.component.ts (clase)" path="adev/src/content/examples/attribute-directives/src/app/app.component.1.ts" visibleRegion="class"/>

3. Para aplicar simultáneamente la directiva y el color, usa enlace de propiedad con el selector de directiva `appHighlight`, estableciéndolo igual a `color`.

<docs-code header="src/app/app.component.html (color)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="color"/>

El enlace de atributo `[appHighlight]` realiza dos tareas:

* Aplica la directiva de resaltado al elemento `<p>`
    * Establece el color de resaltado de la directiva con un enlace de propiedad

### Estableciendo el valor con entrada de usuario

Esta sección te guía a través de añadir botones de radio para vincular tu elección de color a la directiva `appHighlight`.

1. Añade marcado a `app.component.html` para elegir un color de la siguiente manera:

<docs-code header="src/app/app.component.html (v2)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="v2"/>

1. Revisa `AppComponent.color` para que no tenga valor inicial.

<docs-code header="src/app/app.component.ts (clase)" path="adev/src/content/examples/attribute-directives/src/app/app.component.ts" visibleRegion="class"/>

1. En `highlight.directive.ts`, revisa el método `onMouseEnter` para que primero trate de resaltar con `appHighlight` y recurra a `red` si `appHighlight` es `undefined`.

<docs-code header="src/app/highlight.directive.ts (mouse-enter)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="mouse-enter"/>

1. Ejecuta tu aplicación para verificar que el usuario puede elegir el color con los botones de radio.

## Enlazando a una segunda propiedad

Esta sección te guía a través de configurar tu aplicación para que el desarrollador pueda establecer el color por defecto.

1. Añade una segunda propiedad `Input()` a `HighlightDirective` llamada `defaultColor`.

<docs-code header="src/app/highlight.directive.ts (defaultColor)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.ts" visibleRegion="defaultColor"/>

1. Revisa el `onMouseEnter` de la directiva para que primero trate de resaltar con `appHighlight`, luego con `defaultColor`, y finalmente con `red` si ambas propiedades son `undefined`.

<docs-code header="src/app/highlight.directive.ts (mouse-enter)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.ts" visibleRegion="mouse-enter"/>

1. Para enlazar a `AppComponent.color` y usar "violet" como el color por defecto, añade el siguiente HTML.
    En este caso, el enlace `defaultColor` no usa corchetes, `[]`, porque es estático.

<docs-code header="src/app/app.component.html (defaultColor)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="defaultColor"/>

Como con los componentes, puedes agreg múltiples enlaces de propiedad de directiva a un elemento host.

El color por defecto es rojo si no hay enlace de color por defecto.
Cuando el usuario elige un color, el color seleccionado se convierte en el color de resaltado activo.

## Desactivando el procesamiento de Angular con `NgNonBindable`

Para prevenir la evaluación de expresiones en el navegador, añade `ngNonBindable` al elemento host.
`ngNonBindable` desactiva la interpolación, directivas y enlace en plantillas.

En el siguiente ejemplo, la expresión `{{ 1 + 1 }}` se renderiza tal como está en tu editor de código, y no muestra `2`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="ngNonBindable"/>

Aplicar `ngNonBindable` a un elemento detiene el enlace para los elementos hijos de ese elemento.
Sin embargo, `ngNonBindable` aún permite que las directivas funcionen en el elemento donde aplicas `ngNonBindable`.
En el siguiente ejemplo, la directiva `appHighlight` sigue activa pero Angular no evalúa la expresión `{{ 1 + 1 }}`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="ngNonBindable-with-directive"/>

Si aplicas `ngNonBindable` a un elemento padre, Angular desactiva la interpolación y el enlace de cualquier tipo, como enlace de propiedad o enlace de evento, para los hijos del elemento.
# Directivas estructurales

Las directivas estructurales son directivas aplicadas a un elemento `<ng-template>` que renderizan condicionalmente o repetidamente el contenido de ese `<ng-template>`.

## Caso de uso de ejemplo

En esta guía construirás una directiva estructural que obtiene datos de una fuente de datos dada y renderiza su plantilla cuando esos datos están disponibles. Esta directiva se llama `SelectDirective`, después de la palabra clave SQL `SELECT`, y coincide con un selector de atributo `[select]`.

`SelectDirective` tendrá una entrada que nombra la fuente de datos a usar, que llamarás `selectFrom`. El prefijo `select` para esta entrada es importante para la [sintaxis abreviada](#sintaxis-abreviada-de-directivas-estructurales). La directiva instanciará su `<ng-template>` con un contexto de plantilla que proporciona los datos seleccionados.

El siguiente es un ejemplo de cómo se vería usar esta directiva directamente en un `<ng-template>`:

```html
<ng-template select let-data [selectFrom]="source">
  <p>Los datos son: {{ data }}</p>
</ng-template>
```

La directiva estructural puede esperar a que los datos estén disponibles y luego renderizar su `<ng-template>`.

ÚTIL: Ten en cuenta que el elemento `<ng-template>` de Angular define una plantilla que no renderiza nada por defecto, si simplemente envuelves elementos en un `<ng-template>` sin aplicar una directiva estructural, esos elementos no se renderizarán.

Para más información, consulta la documentación de la [API ng-template](api/core/ng-template).

## Sintaxis abreviada de directivas estructurales

Angular soporta una sintaxis abreviada para directivas estructurales que evita la necesidad de escribir explícitamente un elemento `<ng-template>`.

Las directivas estructurales pueden aplicarse directamente en un elemento anteponiendo un asterisco (`*`) al selector de la directiva, por ejemplo: `*select`. Angular transforma el asterisco delante de una directiva estructural en un `<ng-template>` que aloja la directiva y envuelve el elemento y sus descendientes.

Puedes usar esto con `SelectDirective` de la siguiente manera:

```html
<p *select="let data from source">Los datos son: {{data}}</p>
```

Este ejemplo muestra la flexibilidad de la sintaxis abreviada de directivas estructurales, que a veces se llama _microsintaxis_.

Cuando se usa de esta manera, solo la directiva estructural y sus enlaces se aplican al `<ng-template>`. Cualquier otro atributo o enlace en la etiqueta `<p>` se deja intacto. Por ejemplo, estas dos formas son equivalentes:

```html

<p class="data-view" *select="let data from source">Los datos son: {{data}}</p>

<ng-template select let-data [selectFrom]="source">
  <p class="data-view">Los datos son: {{data}}</p>
</ng-template>
```

La sintaxis abreviada se expande a través de un conjunto de convenciones. Una [gramática](#referencia-de-sintaxis-de-directivas-estructurales) más completa se define a continuación, pero en el ejemplo anterior, esta transformación puede explicarse de la siguiente manera:

La primera parte de la expresión `*select` es `let data`, que declara una variable de plantilla `data`. Como no sigue ninguna asignación, la variable de plantilla se vincula a la propiedad del contexto de plantilla `$implicit`.

La segunda pieza de sintaxis es un par clave-expresión, `from source`. `from` es una clave de enlace y `source` es una expresión de plantilla regular. Las claves de enlace se mapean a propiedades transformándolas a PascalCase y anteponiendo el selector de la directiva estructural. La clave `from` se mapea a `selectFrom`, que luego se vincula a la expresión `source`. Por eso muchas directivas estructurales tendrán entradas que están todas prefijadas con el selector de la directiva estructural.

## Una directiva estructural por elemento

Solo puedes aplicar una directiva estructural por elemento cuando usas la sintaxis abreviada. Esto es porque solo hay un elemento `<ng-template>` en el que se desenvuelve esa directiva. Múltiples directivas requerirían múltiples `<ng-template>` anidados, y no está claro cuál directiva debería ser la primera. `<ng-container>` puede usarse para crear capas de envoltorio cuando múltiples directivas estructurales necesitan aplicarse alrededor del mismo elemento DOM físico o componente, lo que permite al usuario definir la estructura anidada.

## Creando una directiva estructural

Esta sección te guía a través de la creación de `SelectDirective`.

<docs-workflow>
<docs-step title="Generar la directiva">
Usando Angular CLI, ejecuta el siguiente comando, donde `select` es el nombre de la directiva:

```shell
ng generate directive select
```

Angular crea la clase de directiva y especifica el selector CSS, `[select]`, que identifica la directiva en una plantilla.
</docs-step>
<docs-step title="Convertir la directiva estructural">
Importa `TemplateRef` y `ViewContainerRef`. Inyecta `TemplateRef` y `ViewContainerRef` en la directiva como propiedades privadas.

```ts
import {Directive, TemplateRef, ViewContainerRef} from '@angular/core';

@Directive({
  selector: '[select]',
})
export class SelectDirective {
  private templateRef = inject(TemplateRef);
  private viewContainerRef = inject(ViewContainerRef);
}

```

</docs-step>
<docs-step title="Añadir la entrada 'selectFrom'">
Añade una propiedad `selectFrom` `input()`.

```ts
export class SelectDirective {
  // ...

selectFrom = input.required<DataSource>();
}
```

</docs-step>
<docs-step title="Añadir la lógica de negocio">
Con `SelectDirective` ahora estructurada como una directiva estructural con su entrada, ahora puedes añadir la lógica para obtener los datos y renderizar la plantilla con ellos:

```ts
export class SelectDirective {
  // ...

async ngOnInit() {
    const data = await this.selectFrom.load();
    this.viewContainerRef.createEmbeddedView(this.templateRef, {
      // Crear la vista embebida con un objeto de contexto que contiene
      // los datos a través de la clave `$implicit`.
      $implicit: data,
    });
  }
}
```

</docs-step>
</docs-workflow>

¡Y listo! `SelectDirective` está funcionando. Un paso de seguimiento podría ser [añadir soporte de verificación de tipos de plantilla](#tipando-el-contexto-de-la-directiva).

## Referencia de sintaxis de directivas estructurales

Cuando escribas tus propias directivas estructurales, usa la siguiente sintaxis:

```
*:prefix="( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )*"
```
Los siguientes patrones describen cada parte de la gramática de directivas estructurales:

```ts
as = :export "as" :local ";"?
keyExp = :key ":"? :expression ("as" :local)? ";"?
let = "let" :local "=" :export ";"?
```

### Cómo Angular traduce la sintaxis abreviada

Angular translates structural directive shorthand into the normal binding syntax as follows:

## Ejemplos de sintaxis abreviada

La siguiente tabla proporciona ejemplos de sintaxis abreviada:

| Sintaxis abreviada | Cómo Angular interpreta la sintaxis |
|:--- |:--- |
| `*myDir="let item of [1,2,3]"` | `<ng-template myDir let-item [myDirOf]="[1, 2, 3]">` |
| `*myDir="let item of [1,2,3] as items; trackBy: myTrack; index as i"` | `<ng-template myDir let-item [myDirOf]="[1,2,3]" let-items="myDirOf" [myDirTrackBy]="myTrack" let-i="index">` |
| `*ngComponentOutlet="componentClass";` | `<ng-template [ngComponentOutlet]="componentClass">` |
| `*ngComponentOutlet="componentClass; inputs: myInputs";` | `<ng-template [ngComponentOutlet]="componentClass" [ngComponentOutletInputs]="myInputs">` |
| `*myDir="exp as value"` | `<ng-template [myDir]="exp" let-value="myDir">` |

## Mejorando la verificación de tipos de plantilla para directivas personalizadas

Puedes mejorar la verificación de tipos de plantilla para directivas personalizadas añadiendo guardias de plantilla a tu definición de directiva.
Estos guardias ayudan al verificador de tipos de plantilla de Angular a encontrar errores en la plantilla en tiempo de compilación, lo que puede evitar errores en tiempo de ejecución.
Dos tipos diferentes de guardias son posibles:

* `ngTemplateGuard_(input)` te permite controlar cómo una expresión de entrada debe estrecharse basándose en el tipo de una entrada específica.
* `ngTemplateContextGuard` se usa para determinar el tipo del objeto de contexto para la plantilla, basándose en el tipo de la directiva misma.

Esta sección proporciona ejemplos de ambos tipos de guardias.
Para más información, consulta [Verificación de tipos de plantilla](tools/cli/template-typecheck "Guía de verificación de tipos de plantilla").

### Estrechamiento de tipos con guardias de plantilla

Una directiva estructural en una plantilla controla si esa plantilla se renderiza en tiempo de ejecución. Algunas directivas estructurales quieren realizar estrechamiento de tipos basándose en el tipo de expresión de entrada.

Hay dos estrechamientos que son posibles con guardias de entrada:

* Estrechar la expresión de entrada basándose en una función de aserción de tipo TypeScript.
* Estrechar la expresión de entrada basándose en su veracidad.

Para estrechar la expresión de entrada definiendo una función de aserción de tipo:

```ts
// Esta directiva solo renderiza su plantilla si el actor es un usuario.
// Quieres aseverar que dentro de la plantilla, el tipo de la expresión `actor`
// se estrecha a `User`.
@Directive(...)
class ActorIsUser {
  actor = input<User | Robot>();

static ngTemplateGuard_actor(dir: ActorIsUser, expr: User | Robot): expr is User {
    // La declaración de retorno es innecesaria en la práctica, pero incluida para
    // prevenir errores de TypeScript.
    return true;
  }
}
```

La verificación de tipos se comportará dentro de la plantilla como si `ngTemplateGuard_actor` hubiera sido aseverada en la expresión vinculada a la entrada.

Algunas directivas solo renderizan sus plantillas cuando una entrada es veraz. No es posible capturar la semántica completa de veracidad en una función de aserción de tipo, por lo que en su lugar se puede usar un tipo literal de `'binding'` para señalar al verificador de tipos de plantilla que la expresión de enlace misma debería usarse como guardián:

```ts
@Directive(...)
class CustomIf {
  condition = input.required<boolean>();

static ngTemplateGuard_condition: 'binding';
}
```

El verificador de tipos de plantilla se comportará como si la expresión vinculada a `condition` fuera aseverada como veraz dentro de la plantilla.

### Tipando el contexto de la directiva

Si tu directiva estructural proporciona un contexto a la plantilla instanciada, puedes tiparlo correctamente dentro de la plantilla proporcionando una función de aserción de tipo estática `ngTemplateContextGuard`. Esta función puede usar el tipo de la directiva para derivar el tipo del contexto, lo que es útil cuando el tipo de la directiva es genérico.

Para `SelectDirective` descrita anteriormente, puedes implementar un `ngTemplateContextGuard` para especificar correctamente el tipo de datos, incluso si la fuente de datos es genérica.

```ts
// Declarar una interfaz para el contexto de la plantilla:
export interface SelectTemplateContext<T> {
  $implicit: T;
}

@Directive(...)
export class SelectDirective<T> {
  // El tipo genérico `T` de la directiva se inferirá del tipo `DataSource`
  // pasado a la entrada.
  selectFrom = input.required<DataSource<T>>();

// Estrechar el tipo del contexto usando el tipo genérico de la directiva.
  static ngTemplateContextGuard<T>(dir: SelectDirective<T>, ctx: any): ctx is SelectTemplateContext<T> {
    // Como antes, el cuerpo del guardia no se usa en tiempo de ejecución, e incluido solo para evitar
    // errores de TypeScript.
    return true;
  }
}
```
# API de composición de directivas

Las directivas de Angular ofrecen una excelente manera de encapsular comportamientos reutilizables: las directivas pueden aplicar atributos, 
clases CSS y escuchadores de eventos a un elemento.

La *API de composición de directivas* te permite aplicar directivas al elemento host de un componente desde 
*dentro* de la clase TypeScript del componente.

## Añadiendo directivas a un componente

Se aplican directivas a un componente añadiendo una propiedad `hostDirectives` al decorador de un componente. 
Llamamos a tales directivas *directivas host*.

En este ejemplo, aplicamos la directiva `MenuBehavior` 
al elemento host de `AdminMenu`. Esto funciona de manera similar a aplicar `MenuBehavior` al elemento `<admin-menu>` en una plantilla.

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [MenuBehavior],
})
export class AdminMenu { }
```

Cuando el framework renderiza un componente, Angular también crea una instancia de cada directiva host. 
Los enlaces host de las directivas se aplican al elemento host del componente. 
Por defecto, las entradas y salidas de las directivas host no se exponen como parte de la API pública del componente. 
Consulta [Incluyendo entradas y salidas](#incluyendo-entradas-y-salidas) a continuación para más información.

**Angular aplica las directivas host estáticamente en tiempo de compilación.** 
No puedes añadir dinámicamente directivas en tiempo de ejecución.

**Las directivas usadas en `hostDirectives` no pueden especificar `standalone: false`.**

**Angular ignora el `selector` de las directivas aplicadas en la propiedad `hostDirectives`.**

## Incluyendo entradas y salidas

Cuando aplicas `hostDirectives` a tu componente, los inputs y outputs de las directivas host
no se incluyen en la API de tu componente de manera predeterminada.
Puedes incluir explícitamente esos inputs y outputs expandiendo la entrada en `hostDirectives`:

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [{
    directive: MenuBehavior,
    inputs: ['menuId'],
    outputs: ['menuClosed'],
  }],
})
export class AdminMenu { }
```

Al especificar explícitamente los inputs y outputs, los consumidores del componente con
`hostDirective` pueden enlazarlos en una plantilla:

```html
<admin-menu menuId="top-menu" (menuClosed)="logMenuClosed()">
```

Además, puedes asignar alias a los inputs y outputs de `hostDirective` para personalizar la API
de tu componente:

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [{
    directive: MenuBehavior,
    inputs: ['menuId: id'],
    outputs: ['menuClosed: closed'],
  }],
})
export class AdminMenu { }
```

```html
<admin-menu id="top-menu" (closed)="logMenuClosed()">
```

## Añadiendo directivass a otra directiva

También puedes agregar `hostDirectives` a otras directivas, además de a componentes.
Esto habilita la agregación transitiva de múltiples comportamientos.

En el siguiente ejemplo, definimos dos directivas, `Menu` y `Tooltip`.
Luego componemos el comportamiento de estas dos directivas en `MenuWithTooltip`.
Finalmente, aplicamos `MenuWithTooltip` a `SpecializedMenuWithTooltip`.

Cuando `SpecializedMenuWithTooltip` se usa en una plantilla, crea instancias de `Menu`, `Tooltip`
y `MenuWithTooltip`. Los host bindings de cada una de estas directivas se aplican al elemento host
de `SpecializedMenuWithTooltip`.

```typescript
@Directive({...})
export class Menu { }

@Directive({...})
export class Tooltip { }

// MenuWithTooltip puede componer comportamientos de múltiples directivas
@Directive({
  hostDirectives: [Tooltip, Menu],
})
export class MenuWithTooltip { }

// CustomWidget puede aplicar los comportamientos ya compuestos de MenuWithTooltip
@Directive({
  hostDirectives: [MenuWithTooltip],
})
export class SpecializedMenuWithTooltip { }
```

## Semántica de las directivas host

### Orden de ejecución de las directivas

Las directivas host siguen el mismo ciclo de vida que los componentes y directivas usadas
directamente en una plantilla.
Sin embargo, las directivas host siempre ejecutan su constructor, hooks de ciclo de vida y
bindings _antes_ que el componente o directiva sobre el cual se aplican.

El siguiente ejemplo muestra el uso mínimo de una directiva host:

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [MenuBehavior],
})
export class AdminMenu { }
```

El orden de ejecución aquí es:

1. Se instancia `MenuBehavior`
2. Se instancia `AdminMenu`
3. `MenuBehavior` recibe entradas (`ngOnInit`)
4. `AdminMenu` recibe entradas (`ngOnInit`)
5. `MenuBehavior` aplica host bindings
6. `AdminMenu` aplica host bindings

Este orden de operaciones significa que los componentes con `hostDirectives` pueden sobrescribir
cualquier host binding especificado por una directiva host.

Este orden también se aplica a cadenas anidadas de directivas host, como se muestra en el siguiente ejemplo:

```typescript
@Directive({...})
export class Tooltip { }

@Directive({
  hostDirectives: [Tooltip],
})
export class CustomTooltip { }

@Directive({
  hostDirectives: [CustomTooltip],
})
export class EvenMoreCustomTooltip { }
```
En el ejemplo anterior, el orden de ejecución es:

1. Se instancia `Tooltip`
2. Se instancia `CustomTooltip`
3. Se instancia `EvenMoreCustomTooltip`
4. `Tooltip` recibe entradas (`ngOnInit`)
5. `CustomTooltip` recibe entradas (`ngOnInit`)
6. `EvenMoreCustomTooltip` recibe entradas (`ngOnInit`)
7. `Tooltip` aplica host bindings
8. `CustomTooltip` aplica host bindings
9. `EvenMoreCustomTooltip` aplica host bindings

### Dependency injection

Un componente o directiva que especifica `hostDirectives` puede inyectar las instancias de esas
directivas host y viceversa.

Cuando aplicas directivas host a un componente, tanto el componente como las directivas host
pueden definir providers.

Si un componente o directiva con `hostDirectives` y esas directivas host proveen el mismo token de
inyección, los providers definidos en la clase con `hostDirectives` tienen precedencia sobre
los providers definidos en las directivas host.
# Getting started with NgOptimizedImage

The `NgOptimizedImage` directive makes it easy to adopt performance best practices for loading images.

The directive ensures that the loading of the [Largest Contentful Paint (LCP)](http://web.dev/lcp) image is prioritized by:

* Automatically setting the `fetchpriority` attribute on the `<img>` tag
* Lazy loading other images by default
* Automatically generating a preconnect link tag in the document head
* Automatically generating a `srcset` attribute
* Generating a [preload hint](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) if app is using SSR

In addition to optimizing the loading of the LCP image, `NgOptimizedImage` enforces a number of image best practices, such as:

* Using [image CDN URLs to apply image optimizations](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)
* Preventing layout shift by requiring `width` and `height`
* Warning if `width` or `height` have been set incorrectly
* Warning if the image will be visually distorted when rendered

If you're using a background image in CSS, [start here](#how-to-migrate-your-background-image).

**NOTE: Although the `NgOptimizedImage` directive was made a stable feature in Angular version 15, it has been backported and is available as a stable feature in versions 13.4.0 and 14.3.0 as well.**

## Getting Started

<docs-workflow>
<docs-step title="Import `NgOptimizedImage` directive">
Import `NgOptimizedImage` directive from `@angular/common`:

```typescript
import { NgOptimizedImage } from '@angular/common'
```
and include it into the `imports` array of a standalone component or an NgModule:

```typescript
imports: [
  NgOptimizedImage,
  // ...
],
```

</docs-step>
<docs-step title="(Optional) Set up a Loader">
An image loader is not **required** in order to use NgOptimizedImage, but using one with an image CDN enables powerful performance features, including automatic `srcset`s for your images.

A brief guide for setting up a loader can be found in the [Configuring an Image Loader](#configuring-an-image-loader-for-ngoptimizedimage) section at the end of this page.
</docs-step>
<docs-step title="Enable the directive">
To activate the `NgOptimizedImage` directive, replace your image's `src` attribute with `ngSrc`.

```html
<img ngSrc="cat.jpg">
```
If you're using a [built-in third-party loader](#built-in-loaders), make sure to omit the base URL path from `src`, as that will be prepended automatically by the loader.
</docs-step>
<docs-step title="Mark images as `priority`">
Always mark the [LCP image](https://web.dev/lcp/#what-elements-are-considered) on your page as `priority` to prioritize its loading.

```html
<img ngSrc="cat.jpg" width="400" height="200" priority>
```
Marking an image as `priority` applies the following optimizations:

* Sets `fetchpriority=high` (read more about priority hints [here](https://web.dev/priority-hints))
* Sets `loading=eager` (read more about native lazy loading [here](https://web.dev/browser-level-image-lazy-loading))
* Automatically generates a [preload link element](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) if [rendering on the server](guide/ssr).

Angular displays a warning during development if the LCP element is an image that does not have the `priority` attribute. A page’s LCP element can vary based on a number of factors - such as the dimensions of a user's screen, so a page may have multiple images that should be marked `priority`. See [CSS for Web Vitals](https://web.dev/css-web-vitals/#images-and-largest-contentful-paint-lcp) for more details.
</docs-step>
<docs-step title="Include Width and Height">
In order to prevent [image-related layout shifts](https://web.dev/css-web-vitals/#images-and-layout-shifts), NgOptimizedImage requires that you specify a height and width for your image, as follows:

```html
<img ngSrc="cat.jpg" width="400" height="200">
```
For **responsive images** (images which you've styled to grow and shrink relative to the viewport), the `width` and `height` attributes should be the intrinsic size of the image file. For responsive images it's also important to [set a value for `sizes`.](#responsive-images)

For **fixed size images**, the `width` and `height` attributes should reflect the desired rendered size of the image. The aspect ratio of these attributes should always match the intrinsic aspect ratio of the image.

NOTE: If you don't know the size of your images, consider using "fill mode" to inherit the size of the parent container, as described below.
</docs-step>
</docs-workflow>

## Using `fill` mode

In cases where you want to have an image fill a containing element, you can use the `fill` attribute. This is often useful when you want to achieve a "background image" behavior. It can also be helpful when you don't know the exact width and height of your image, but you do have a parent container with a known size that you'd like to fit your image into (see "object-fit" below).

When you add the `fill` attribute to your image, you do not need and should not include a `width` and `height`, as in this example:

```html
<img ngSrc="cat.jpg" fill>
```
You can use the [object-fit](https://developer.mozilla.org/docs/Web/CSS/object-fit) CSS property to change how the image will fill its container. If you style your image with `object-fit: "contain"`, the image will maintain its aspect ratio and be "letterboxed" to fit the element. If you set `object-fit: "cover"`, the element will retain its aspect ratio, fully fill the element, and some content may be "cropped" off.

See visual examples of the above at the [MDN object-fit documentation.](https://developer.mozilla.org/docs/Web/CSS/object-fit)

You can also style your image with the [object-position property](https://developer.mozilla.org/docs/Web/CSS/object-position) to adjust its position within its containing element.

IMPORTANT: For the "fill" image to render properly, its parent element **must** be styled with `position: "relative"`, `position: "fixed"`, or `position: "absolute"`.

## How to migrate your background image

Here's a simple step-by-step process for migrating from `background-image` to `NgOptimizedImage`. For these steps, we'll refer to the element that has an image background as the "containing element":

1) Remove the `background-image` style from the containing element.
2) Ensure that the containing element has `position: "relative"`, `position: "fixed"`, or `position: "absolute"`.
3) Create a new image element as a child of the containing element, using `ngSrc` to enable the `NgOptimizedImage` directive.
4) Give that element the `fill` attribute. Do not include a `height` and `width`.
5) If you believe this image might be your [LCP element](https://web.dev/lcp/), add the `priority` attribute to the image element.

You can adjust how the background image fills the container as described in the [Using fill mode](#using-fill-mode) section.
## Using placeholders

### Automatic placeholders

NgOptimizedImage can display an automatic low-resolution placeholder for your image if you're using a CDN or image host that provides automatic image resizing. Take advantage of this feature by adding the `placeholder` attribute to your image:

```
<img ngSrc="cat.jpg" width="400" height="200" placeholder>
```
Adding this attribute automatically requests a second, smaller version of the image using your specified image loader. This small image will be applied as a `background-image` style with a CSS blur while your image loads. If no image loader is provided, no placeholder image can be generated and an error will be thrown.

The default size for generated placeholders is 30px wide. You can change this size by specifying a pixel value in the `IMAGE_CONFIG` provider, as seen below:

```
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```
If you want sharp edges around your blurred placeholder, you can wrap your image in a containing `<div>` with the `overflow: hidden` style. As long as the `<div>` is the same size as the image (such as by using the `width: fit-content` style), the "fuzzy edges" of the placeholder will be hidden.

### Data URL placeholders

You can also specify a placeholder using a base64 [data URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) without an image loader. The data url format is `data:image/[imagetype];[data]`, where `[imagetype]` is the image format, just as `png`, and `[data]` is a base64 encoding of the image. That encoding can be done using the command line or in JavaScript. For specific commands, see [the MDN documentation](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs#encoding_data_into_base64_format). An example of a data URL placeholder with truncated data is shown below:

```html
<img
  ngSrc="cat.jpg"
  width="400"
  height="200"
  placeholder="data:image/png;base64,iVBORw0K..."
/>
```
However, large data URLs  increase the size of your Angular bundles and slow down page load. If you cannot use an image loader, the Angular team recommends keeping base64 placeholder images smaller than 4KB and using them exclusively on critical images. In addition to decreasing placeholder dimensions, consider changing image formats or parameters used when saving images. At very low resolutions, these parameters can have a large effect on file size.

### Non-blurred placeholders

By default, NgOptimizedImage applies a CSS blur effect to image placeholders. To render a placeholder without blur, provide a `placeholderConfig` argument with an object that includes the `blur` property, set to false. For example:

```html
<img
  ngSrc="cat.jpg"
  width="400"
  height="200"
  placeholder
  [placeholderConfig]="{blur: false}"
/>
```
## Adjusting image styling

Depending on the image's styling, adding `width` and `height` attributes may cause the image to render differently. `NgOptimizedImage` warns you if your image styling renders the image at a distorted aspect ratio.

You can typically fix this by adding `height: auto` or `width: auto` to your image styles. For more information, see the [web.dev article on the `<img>` tag](https://web.dev/patterns/web-vitals-patterns/images/img-tag).

If the `width` and `height` attribute on the image are preventing you from sizing the image the way you want with CSS, consider using `fill` mode instead, and styling the image's parent element.

## Performance Features

NgOptimizedImage includes a number of features designed to improve loading performance in your app. These features are described in this section.

### Add resource hints

A [`preconnect` resource hint](https://web.dev/preconnect-and-dns-prefetch) for your image origin ensures that the LCP image loads as quickly as possible.

Preconnect links are automatically generated for domains provided as an argument to a [loader](#optional-set-up-a-loader). If an image origin cannot be automatically identified, and no preconnect link is detected for the LCP image, `NgOptimizedImage` will warn during development. In that case, you should manually add a resource hint to `index.html`. Within the `<head>` of the document, add a `link` tag with `rel="preconnect"`, as shown below:

```html
<link rel="preconnect" href="https://my.cdn.origin" />
```
To disable preconnect warnings, inject the `PRECONNECT_CHECK_BLOCKLIST` token:

```typescript
providers: [
  {provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],
```
See more information on automatic preconnect generation [here](#why-is-a-preconnect-element-not-being-generated-for-my-image-domain).
### Request images at the correct size with automatic `srcset`

Defining a [`srcset` attribute](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset) ensures that the browser requests an image at the right size for your user's viewport, so it doesn't waste time downloading an image that's too large. `NgOptimizedImage` generates an appropriate `srcset` for the image, based on the presence and value of the [`sizes` attribute](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) on the image tag.

#### Fixed-size images

If your image should be "fixed" in size  (i.e. the same size across devices, except for [pixel density](https://web.dev/codelab-density-descriptors/)), there is no need to set a `sizes` attribute. A `srcset` can be generated automatically from the image's width and height attributes with no further input required.

Example srcset generated:
```html
<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x">
```

#### Responsive images

If your image should be responsive (i.e. grow and shrink according to viewport size), then you will need to define a [`sizes` attribute](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) to generate the `srcset`.

If you haven't used `sizes` before, a good place to start is to set it based on viewport width. For example, if your CSS causes the image to fill 100% of viewport width, set `sizes` to `100vw` and the browser will select the image in the `srcset` that is closest to the viewport width (after accounting for pixel density). If your image is only likely to take up half the screen (ex: in a sidebar), set `sizes` to `50vw` to ensure the browser selects a smaller image. And so on.

If you find that the above does not cover your desired image behavior, see the documentation on [advanced sizes values](#advanced-sizes-values).

Note that `NgOptimizedImage` automatically prepends `"auto"` to the provided `sizes` value. This is an optimization that increases the accuracy of srcset selection on browsers which support `sizes="auto"`, and is ignored by browsers which do not.

By default, the responsive breakpoints are:

`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`

If you would like to customize these breakpoints, you can do so using the `IMAGE_CONFIG` provider:

```typescript
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],
```
If you would like to manually define a `srcset` attribute, you can provide your own using the `ngSrcset` attribute:

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w">
```
If the `ngSrcset` attribute is present, `NgOptimizedImage` generates and sets the `srcset` based on the sizes included. Do not include image file names in `ngSrcset` - the directive infers this information from `ngSrc`. The directive supports both width descriptors (e.g. `100w`) and density descriptors (e.g. `1x`).

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw">
```
### Disabling automatic srcset generation

To disable srcset generation for a single image, you can add the `disableOptimizedSrcset` attribute on the image:

```html
<img ngSrc="about.jpg" disableOptimizedSrcset>
```
### Disabling image lazy loading

By default, `NgOptimizedImage` sets `loading=lazy` for all images that are not marked `priority`. You can disable this behavior for non-priority images by setting the `loading` attribute. This attribute accepts values: `eager`, `auto`, and `lazy`. [See the documentation for the standard image `loading` attribute for details](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/loading#value).

```html
<img ngSrc="cat.jpg" width="400" height="200" loading="eager">
```
### Advanced 'sizes' values

You may want to have images displayed at varying widths on differently-sized screens. A common example of this pattern is a grid- or column-based layout that renders a single column on mobile devices, and two columns on larger devices. You can capture this behavior in the `sizes` attribute, using a "media query" syntax, such as the following:

```html
<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw">
```
The `sizes` attribute in the above example says "I expect this image to be 100 percent of the screen width on devices under 768px wide. Otherwise, I expect it to be 50 percent of the screen width.

For additional information about the `sizes` attribute, see [web.dev](https://web.dev/learn/design/responsive-images/#sizes) or [mdn](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes).

## Configuring an image loader for `NgOptimizedImage`

A "loader" is a function that generates an [image transformation URL](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options) for a given image file. When appropriate, `NgOptimizedImage` sets the size, format, and image quality transformations for an image.

`NgOptimizedImage` provides both a generic loader that applies no transformations, as well as loaders for various third-party image services. It also supports writing your own custom loader.

| Loader type| Behavior |
|:--- |:--- |
| Generic loader | The URL returned by the generic loader will always match the value of `src`. In other words, this loader applies no transformations. Sites that use Angular to serve images are the primary intended use case for this loader.|
| Loaders for third-party image services | The URL returned by the loaders for third-party image services will follow API conventions used by that particular image service. |
| Custom loaders | A custom loader's behavior is defined by its developer. You should use a custom loader if your image service isn't supported by the loaders that come preconfigured with `NgOptimizedImage`.|

Based on the image services commonly used with Angular applications, `NgOptimizedImage` provides loaders preconfigured to work with the following image services:

To use the **generic loader** no additional code changes are necessary. This is the default behavior.

### Built-in Loaders

To use an existing loader for a **third-party image service**, add the provider factory for your chosen service to the `providers` array. In the example below, the Imgix loader is used:

```typescript
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```
The base URL for your image assets should be passed to the provider factory as an argument. For most sites, this base URL should match one of the following patterns:

* <https://yoursite.yourcdn.com>
* <https://subdomain.yoursite.com>
* <https://subdomain.yourcdn.com/yoursite>

You can learn more about the base URL structure in the docs of a corresponding CDN provider.

### Custom Loaders

To use a **custom loader**, provide your loader function as a value for the `IMAGE_LOADER` DI token. In the example below, the custom loader function returns a URL starting with `https://example.com` that includes `src` and `width` as URL parameters.

```typescript
providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}`;
    },
  },
],
```
A loader function for the `NgOptimizedImage` directive takes an object with the `ImageLoaderConfig` type (from `@angular/common`) as its argument and returns the absolute URL of the image asset. The `ImageLoaderConfig` object contains the `src` property, and optional `width` and `loaderParams` properties.

NOTE: even though the `width` property may not always be present, a custom loader must use it to support requesting images at various widths in order for `ngSrcset` to work properly.

### The `loaderParams` Property

There is an additional attribute supported by the `NgOptimizedImage` directive, called `loaderParams`, which is specifically designed to support the use of custom loaders. The `loaderParams` attribute takes an object with any properties as a value, and does not do anything on its own. The data in `loaderParams` is added to the `ImageLoaderConfig` object passed to your custom loader, and can be used to control the behavior of the loader.

A common use for `loaderParams` is controlling advanced image CDN features.

### Example custom loader

The following shows an example of a custom loader function. This example function concatenates `src` and `width`, and uses `loaderParams` to control a custom CDN feature for rounded corners:

```typescript
const myCustomLoader = (config: ImageLoaderConfig) => {
  let url = `https://example.com/images/${config.src}?`;
  let queryParams = [];
  if (config.width) {
    queryParams.push(`w=${config.width}`);
  }
  if (config.loaderParams?.roundedCorners) {
    queryParams.push('mask=corners&corner-radius=5');
  }
  return url + queryParams.join('&');
};
```
Note that in the above example, we've invented the 'roundedCorners' property name to control a feature of our custom loader. We could then use this feature when creating an image, as follows:

```html
<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}">
```
## Frequently Asked Questions

### Does NgOptimizedImage support the `background-image` css property?

The NgOptimizedImage does not directly support the `background-image` css property, but it is designed to easily accommodate the use case of having an image as the background of another element.

For a step-by-step process for migration from `background-image` to `NgOptimizedImage`, see the [How to migrate your background image](#how-to-migrate-your-background-image) section above.

### Why can't I use `src` with `NgOptimizedImage`?

The `ngSrc` attribute was chosen as the trigger for NgOptimizedImage due to technical considerations around how images are loaded by the browser. NgOptimizedImage makes programmatic changes to the `loading` attribute -- if the browser sees the `src` attribute before those changes are made, it will begin eagerly downloading the image file, and the loading changes will be ignored.

### Why is a preconnect element not being generated for my image domain?
Preconnect generation is performed based on static analysis of your application. That means that the image domain must be directly included in the loader parameter, as in the following example:

```typescript
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```
If you use a variable to pass the domain string to the loader, or you're not using a loader, the static analysis will not be able to identify the domain, and no preconnect link will be generated. In this case you should manually add a preconnect link to the document head, as [described above](#add-resource-hints).
### Can I use two different image domains in the same page?

The [image loaders](#configuring-an-image-loader-for-ngoptimizedimage) provider pattern is designed to be as simple as possible for the common use case of having only a single image CDN used within a component. However, it's still very possible to manage multiple image CDNs using a single provider.

To do this, we recommend writing a [custom image loader](#custom-loaders) which uses the [`loaderParams` property](#the-loaderparams-property) to pass a flag that specifies which image CDN should be used, and then invokes the appropriate loader based on that flag.

### Can you add a new built-in loader for my preferred CDN?

For maintenance reasons, we don't currently plan to support additional built-in loaders in the Angular repository. Instead, we encourage developers to publish any additional image loaders as third-party packages.

### Can I use this with the `<picture>` tag

No, but this is on our roadmap, so stay tuned.

If you're waiting on this feature, please upvote the Github issue [here](https://github.com/angular/angular/issues/56594).

### How do I find my LCP image with Chrome DevTools?

1. Using the performance tab of the Chrome DevTools, click on the "start profiling and reload page" button on the top left. It looks like a page refresh icon.

2. This will trigger a profiling snapshot of your Angular application.

3. Once the profiling result is available, select "LCP" in the timings section.

4. A summary entry should appear in the panel at the bottom. You can find the LCP element in the row for "related node".  Clicking on it will reveal the element in the Elements panel.

NOTE: This only identifies the LCP element within the viewport of the page you are testing. It is also recommended to use mobile emulation to identify the LCP element for smaller screens.
In Angular, you use *signals* to create and manage state. A signal is a lightweight wrapper around a value.

Usa la función `signal` para crear una signal que mantenga el estado local:

```typescript
import {signal} from '@angular/core';

// Crear una signal con la función `signal`.
const firstName = signal('Morgan');

// Leer el valor de una signal llamandola - las signals son funciones.
console.log(firstName());

// Cambia el valor de esta signal llamando su método `set` con un nuevo valor.
firstName.set('Jaime');

// También puedes usar el método `update` para cambiar el valor
// basado en el valor anterior.
firstName.update(name => name.toUpperCase()); 
```

Angular rastrea dónde se leen las signals y cuándo se actualizan. El framework usa esta información para hacer trabajo adicional, como actualizar el DOM con nuevo estado. Esta capacidad de responder a valores de signals cambiantes a lo largo del tiempo se conoce como *reactividad*.

## Expresiones computadas

Un `computed` es una signal que produce su valor basado en otras signals.

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());

console.log(firstNameCapitalized()); // MORGAN
```

Una signal `computed` es de solo lectura; no tiene un método `set` o `update`. En su lugar, el valor de la signal `computed` cambia automáticamente cuando cualquiera de las signals que lee cambia:

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());
console.log(firstNameCapitalized()); // MORGAN

firstName.set('Jaime');
console.log(firstNameCapitalized()); // JAIME
```

## Usando signals en componentes

Usa `signal` y `computed` dentro de tus componentes para crear y manejar el estado:

```typescript
@Component({/* ... */})
export class UserProfile {
  isTrial = signal(false);
  isTrialExpired = signal(false);
  showTrialDuration = computed(() => this.isTrial() && !this.isTrialExpired());

activateTrial() {
    this.isTrial.set(true);
  }
}
```

TIP: ¿Quieres saber más sobre Angular Signals? Consulta la [Guía detallada de Signals](guide/signals) para obtener toda la información.

## Siguiente paso

Ahora que has aprendido cómo declarar y manejar datos dinámicos, es momento de aprender cómo usar esos datos dentro de las plantillas.
# Estado dependiente con `linkedSignal`

Puedes usar la función `signal` para gestionar el estado en tu código de Angular. A veces, este estado depende de algún _otro_ estado. Por ejemplo, imagina un componente que permite al usuario seleccionar un método de envío para una orden:

```typescript
@Component({/* ... */})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// Por defecto, selecciona la primera opción de envío.
  selectedOption = signal(this.shippingOptions()[0]);

changeShipping(newOptionIndex: number) {
    this.selectedOption.set(this.shippingOptions()[newOptionIndex]);
  }
}
```

En este ejemplo, `selectedOption` se establece por defecto en la primera opción, pero cambia si el usuario selecciona otra opción. Pero `shippingOptions` es una signal: ¡su valor puede cambiar! Si `shippingOptions` cambia, `selectedOption` puede contener un valor que ya no es una opción válida.

**La función `linkedSignal` te permite crear una signal para gestionar un estado que está intrínsecamente _vinculado_ a otro estado.** Retomando el ejemplo anterior, `linkedSignal` puede reemplazar a `signal`:

```typescript
@Component({/* ... */})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// Inicializar selectedOption a la primera opción de envío.
  selectedOption = linkedSignal(() => this.shippingOptions()[0]);

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }
}
```

`linkedSignal` funciona de manera similar a `signal` con una diferencia clave: en lugar de pasar un valor por defecto, pasas una _función de cómputo_, igual que `computed`. Cuando el valor del cómputo cambia, el valor del `linkedSignal` cambia al resultado del cómputo. Esto ayuda a asegurar que el `linkedSignal` siempre tenga un valor válido.

El siguiente ejemplo muestra cómo el valor de un `linkedSignal` puede cambiar basado en su estado vinculado:

```typescript
const shippingOptions = signal(['Ground', 'Air', 'Sea']);
const selectedOption = linkedSignal(() => shippingOptions()[0]);
console.log(selectedOption()); // 'Ground'

selectedOption.set(shippingOptions()[2]);
console.log(selectedOption()); // 'Sea'

shippingOptions.set(['Email', 'Will Call', 'Postal service']);
console.log(selectedOption()); // 'Email'
```

## Considerando el estado anterior

En algunos casos, el cómputo para un `linkedSignal` necesita considerar el valor anterior del `linkedSignal`.

En el ejemplo anterior, `selectedOption` siempre se actualiza de vuelta a la primera opción cuando `shippingOptions` cambia. Puedes, sin embargo, querer preservar la selección del usuario si su opción seleccionada todavía está en algún lugar de la lista. Para lograr esto, puedes crear un `linkedSignal` con una _fuente_ y _cómputo_ separados:

```typescript
interface ShippingMethod {
  id: number;
  name: string;
}

@Component({/* ... */})
export class ShippingMethodPicker {
  constructor() {
    this.changeShipping(2);
    this.changeShippingOptions();
    console.log(this.selectedOption()); // {"id":2,"name":"Postal Service"}
  }

shippingOptions = signal<ShippingMethod[]>([
    { id: 0, name: 'Ground' },
    { id: 1, name: 'Air' },
    { id: 2, name: 'Sea' },
  ]);

selectedOption = linkedSignal<ShippingMethod[], ShippingMethod>({
    // `selectedOption` se establece al resultado del `cómputo` siempre que esta `source` cambie.
    source: this.shippingOptions,
    computation: (newOptions, previous) => {
      // Si newOptions contiene la opción previamente seleccionada, preservar esa selección.
      // De lo contrario, usar por defecto la primera opción.
      return (
        newOptions.find((opt) => opt.id === previous?.value.id) ?? newOptions[0]
      );
    },
  });

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }

changeShippingOptions() {
    this.shippingOptions.set([
      { id: 0, name: 'Email' },
      { id: 1, name: 'Sea' },
      { id: 2, name: 'Postal Service' },
    ]);
  }
}
```

Cuando creas un `linkedSignal`, puedes pasar un objeto con propiedades separadas `source` y `computation` en lugar de proporcionar solo un cómputo.

La `source` puede ser cualquier signal, como un `computed` o `input` de componente. Cuando el valor de `source` cambia, `linkedSignal` actualiza su valor al resultado del `cómputo` proporcionado.

El `computation` es una función que recibe el nuevo valor de `source` y un objeto `previous`. El objeto `previous` tiene dos propiedades, `previous.source` es el valor anterior de `source`, y `previous.value` es el valor de anterior de `linkedSignal`. Puedes usar estos valores anteriores para decidir el nuevo resultado del cómputo.

ÚTIL: Cuando uses el parámetro `previous`, es necesario proporcionar explícitamente los argumentos de tipo genérico de `linkedSignal`. El primer tipo genérico corresponde con el tipo de `source` y el segundo tipo genérico determina el tipo de salida del `cómputo`.

## Comparación de igualdad personalizada

`linkedSignal`, como cualquier otro signal, puede ser configurado con una función de igualdad personalizada. Esta función es usada por las dependencias aguas abajo para determinar si ese valor del `linkedSignal` (resultado de un cómputo) cambió:

```typescript
const activeUser = signal({id: 123, name: 'Morgan', isAdmin: true});

const activeUserEditCopy = linkedSignal(() => activeUser(), {
  // Considerar al usuario como el mismo si es el mismo `id`.
  equal: (a, b) => a.id === b.id,
});

// O, si separando `source` y `computation`
const activeUserEditCopy = linkedSignal({
  source: activeUser,
  computation: user => user,
  equal: (a, b) => a.id === b.id,
});
```
# Reactividad asíncrona con resources

IMPORTANTE: `resource` es [experimental](reference/releases#experimental). Está listo para que lo pruebes, pero podría cambiar antes de que sea estable.

La mayoría de las APIs de signals son síncronas: `signal`, `computed`, `input`, etc. Sin embargo, las aplicaciones a menudo necesitan manejar datos que están disponibles de forma asíncrona. Un `Resource` te da una forma de incorporar datos asíncronos en el código basado en signals de tu aplicación.

Puedes usar un `Resource` para realizar cualquier tipo de operación asíncrona, pero el caso de uso más común para `Resource` es obtener datos de un servidor. El siguiente ejemplo crea un resource para obtener algunos datos de usuario.

La forma más fácil de crear un `Resource` es la función `resource`.

```typescript
import {resource, Signal} from '@angular/core';

const userId: Signal<string> = getUserId();

const userResource = resource({
  // Define un cómputo reactivo.
  // El valor params se recalcula siempre que cualquier signal leído cambie.
  params: () => ({id: userId()}),

// Define un loader asíncrono que obtiene datos.
  // El resource llama a esta función cada vez que el valor de `params` cambia.
  loader: ({params}) => fetchUser(params),
});

// Crea un signal computed basado en el resultado de la función loader del resource.
const firstName = computed(() => {
  if (userResource.hasValue()) {
    // `hasValue` sirve 2 propósitos:
    // - Actúa como type guard para remover `undefined` del tipo
    // - Protege contra leer un `value` que lanza cuando el resource está en estado de error
    return userResource.value().firstName;
  }

// fallback en caso de que el valor del resource sea `undefined` o si el resource está en estado de error
  return undefined;
});
```

La función `resource` acepta un objeto `ResourceOptions` con dos propiedades principales: `params` y `loader`.

La propiedad `params` define un cómputo reactivo que produce un valor de parámetro. Siempre que las signals leídas en este cómputo cambien, el resource produce un nuevo valor de parámetro, similar a `computed`.

La propiedad `loader` define un `ResourceLoader` — una función asíncrona que obtiene algún estado. El resource llama al loader cada vez que el cómputo `params` produce un nuevo valor, pasando ese valor al loader. Consulta la sección [Resource loaders](#resource-loaders) a continuación para más detalles.

`Resource` tiene un signal `value` que contiene los resultados del loader.

## Resource loaders

Cuando creas un resource, especificas un `ResourceLoader`. Este loader es una función asíncrona que acepta un solo parámetro: un objeto `ResourceLoaderParams`: y devuelve un valor.

El objeto `ResourceLoaderParams` contiene tres propiedades: `params`, `previous`, y `abortSignal`.

| Propiedad    | Descripción                                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`     | El valor del cómputo `params` del resource.                                                                                                      |
| `previous`   | Un objeto con una propiedad `status`, que contiene el `ResourceStatus` anterior.                                                                 |
| `abortSignal`| Un [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). Constalta [Abortando peticiones](#abortando-peticiones) para más detalles. |

Si el cómputo `params` devuelve `undefined`, la función loader no se ejecuta y el estado del resource se convierte en `'idle'`.

### Abortando peticiones

Un resource aborta una operación de carga pendiente si el cómputo `params` cambia mientras el resource está cargando.

Puedes usar el `abortSignal` en `ResourceLoaderParams` para responder a peticiones abortados. Por ejemplo, la función nativa `fetch` acepta un `AbortSignal`:

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params, abortSignal}): Promise<User> => {
    // fetch cancela cualquier pretición HTTP pendiente cuando el `AbortSignal` dado
    // indica que la petición ha sido abortada.
    return fetch(`users/${params.id}`, {signal: abortSignal});
  },
});
```

Consulta [`AbortSignal` en MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) para más detalles sobre cancelación de peticiones con `AbortSignal`.

### Recargando

Puedes activar programáticamente el `loader` de un resource llamando al método `reload`.

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();
```

## Estado del resource

El objeto resource tiene varias propiedades de signal para leer el estado del loader asíncrono.

| Propiedad   | Descripción                                                                                                     |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| `value`     | El valor más reciente del resource, o `undefined` si no se ha recibido ningún valor.                            |
| `hasValue`  | Si el resource tiene un valor.                                                                                  |
| `error`     | El error más reciente encontrado mientras se ejecutaba el loader del resource, o `undefined` si no ha ocurrido ningún error. |
| `isLoading` | Si el loader del resource está ejecutándose actualmente.                                                        |
| `status`    | El `ResourceStatus` específico del resource, como se describe abajo.                                            |

El `status` de una signal proporciona un `ResourceStatus` específico que describe el estado del resource usando una constante de string.

| Estado        | `value()`         | Descripción                                                                  |
| ------------- | :---------------- | ---------------------------------------------------------------------------- |
| `'idle'`      | `undefined`       | El resource no tiene una peticion válida y el loader no se ha ejecutado.       |
| `'error'`     | `undefined`       | El loader ha encontrado un error.                                            |
| `'loading'`   | `undefined`       | El loader se está ejecutando como resultado de que el valor de `params` haya cambiando. |
| `'reloading'` | Valor anterior    | El loader se está ejecutando como resultado de llamar al método `reload` del resource. |
| `'resolved'`  | Valor resuelto    | El loader ha completado.                                                     |
| `'local'`     | Valor establecido localmente | El valor del resource ha sido establecido localmente vía `.set()` o `.update()` |

Puedes usar esta información de estado para mostrar condicionalmente elementos de interfaz de usuario, como indicadores de carga y mensajes de error.

## Obtención de datos reactiva con `httpResource`

[`httpResource`](/guide/http/http-resource) es un wrapper alrededor de `HttpClient` que te da el estado de la petición y la respuesta como signals. Realiza peticiones HTTP a través del stack HTTP de Angular, incluyendo interceptores.
# Entendiendo la inyección de dependencias

La inyección de dependencias, o DI, es uno de los conceptos fundamentales en Angular. DI está integrado en el framework de Angular y permite que las clases con decoradores de Angular, como Componentes, Directivas, Pipes e Injectables, configuren las dependencias que necesitan.

Existen dos roles principales en el sistema DI: consumidor de dependencias y proveedor de dependencias.

Angular facilita la interacción entre consumidores de dependencias y proveedores de dependencias usando una abstracción llamada `Injector`. Cuando se solicita una dependencia, el inyector verifica su registro para ver si ya hay una instancia disponible allí. Si no, se crea una nueva instancia y se almacena en el registro. Angular crea un inyector de toda la aplicación (también conocido como inyector "raíz") durante el proceso de bootstrap de la aplicación. En la mayoría de los casos no necesitas crear inyectores manualmente, pero debes saber que hay una capa que conecta proveedores y consumidores.

Este tema cubre escenarios básicos de cómo una clase puede actuar como una dependencia. Angular también te permite usar funciones, objetos, tipos primitivos como string o Boolean, o cualquier otro tipo como dependencias. Para más información, consulta [Proveedores de dependencias](guide/di/dependency-injection-providers).

## Proporcionando una dependencia

Considera una clase llamada `HeroService` que necesita actuar como una dependencia en un componente.

El primer paso es agregar el decorador `@Injectable` para mostrar que la clase puede ser inyectada.

```typescript
@Injectable()
class HeroService {}
```
El siguiente paso es hacerla disponible en el sistema de ID, proveyéndola. 
Una dependencia se puede proveer en varios lugares:

- [**Preferido**: A nivel raíz de la aplicación usando `providedIn`](#preferido-a-nivel-raíz-de-la-aplicación-usando-providedin)
- [A nivel de Componente](#a-nivel-de-componente)
- [A nivel raíz de la aplicación usando `ApplicationConfig`](#a-nivel-raíz-de-la-aplicación-usando-applicationconfig)
- [Aplicaciones basadas en `NgModule`](#aplicaciones-basadas-en-ngmodule)

### **Preferido**: A nivel raíz de la aplicación usando `providedIn`

Proveer un servicio a nivel raíz de la aplicación usando `providedIn` permite inyectar el servicio en todas las demás clases.
Usar `providedIn` permite que Angular y los optimizadores de código JavaScript eliminen efectivamente los servicios que no se usan (conocido como tree-shaking).

Puedes proveer un servicio usando `providedIn: 'root'` en el decorador `@Injectable`:

```typescript
@Injectable({
  providedIn: 'root'
})
class HeroService {}
```
Cuando provees el servicio a nivel raíz, Angular crea una instancia única y compartida del `HeroService` y la inyecta en cualquier clase que la solicite.

### A nivel de Componente

Puedes proveer servicios a nivel `@Component` usando el campo `providers` del decorador `@Component`.
En este caso el `HeroService` se vuelve disponible para todas las instancias de este componente y otros componentes y directivas usadas en la plantilla.

Por ejemplo:

```typescript
@Component({
  selector: 'hero-list',
  template: '...',
  providers: [HeroService]
})
class HeroListComponent {}
```
Cuando registras un proveedor a nivel de componente, obtienes una nueva instancia del servicio con cada nueva instancia de ese componente.

NOTA: Declarar un servicio de esta manera hace que `HeroService` siempre se incluya en tu aplicación, incluso si el servicio no se usa.

### A nivel raíz de la aplicación usando `ApplicationConfig`

Puedes usar el campo `providers` de `ApplicationConfig` (pasado a la función `bootstrapApplication`) para proveer un servicio u otro `Injectable` a nivel de aplicación.

En el siguiente ejemplo, el `HeroService` está disponible para todos los componentes, directivas y pipes:

```typescript
export const appConfig: ApplicationConfig = {
    providers: [
      { provide: HeroService },
    ]
};
```
Luego, en `main.ts`:

```typescript
bootstrapApplication(AppComponent, appConfig)
```
NOTA: Declarar un servicio de esta manera hace que `HeroService` siempre se incluya en tu aplicación, incluso si el servicio no se usa.

### Aplicaciones basadas en `NgModule`

Las aplicaciones basadas en `@NgModule` usan el campo `providers` del decorador `@NgModule` para proveer un servicio u otro `Injectable` disponible a nivel de aplicación.

Un servicio proveído en un módulo está disponible para todas las declaraciones del módulo, o para cualquier otro módulo que comparta el mismo `ModuleInjector`.
Para entender todos los casos límite, consulta [Inyectores jerárquicos](guide/di/hierarchical-dependency-injection).

NOTA: Declarar un servicio usando `providers` hace que el servicio se incluya en tu aplicación, incluso si el servicio no se usa.

## Inyectando/consumiendo una dependencia

Usa la función `inject` de Angular para recuperar dependencias.

```ts
import {inject, Component} from 'angular/core';

@Component({/* ... */})
export class UserProfile {
  // Puedes usar la función `inject` en inicializadores de propiedades.
  private userClient = inject(UserClient);

constructor() {
    // También puedes usar la función `inject` en un constructor.
    const logger = inject(Logger);
  }
}
```

Puedes usar la función `inject` en cualquier [contexto de inyección](guide/di/dependency-injection-context). La mayoría de las veces, esto es en un inicializador de propiedad de clase o un constructor de clase para componentes, directivas, servicios y pipes.

Cuando Angular descubre que un componente depende de un servicio, primero verifica si el inyector tiene alguna instancia existente de ese servicio. Si una instancia de servicio solicitada aún no existe, el inyector crea una usando el proveedor registrado, y la agrega al inyector antes de devolver el servicio a Angular.

Cuando todos los servicios solicitados han sido resueltos y devueltos, Angular puede llamar al constructor del componente con esos servicios como argumentos.

```mermaid
graph TD;
subgraph Injector
serviceA[Service A]
heroService[HeroService]
serviceC[Service C]
serviceD[Service D]
end
direction TB
componentProperty["Component <br> heroService = inject(HeroService)"]
heroService-->componentProperty
style componentProperty text-align: left
```

## Próximos pasos
# Creando un servicio inyectable

Un servicio es una categoría amplia que abarca cualquier valor, función o característica que una aplicación necesita.
Un servicio es típicamente una clase con un propósito específico y bien definido.
Un componente es un tipo de clase que puede usar DI.

Angular distingue los componentes de los servicios para aumentar la modularidad y reutilización.
Al separar las características relacionadas con la vista de un componente de otros tipos de procesamiento, puedes hacer que tus clases de componente sean eficientes y ligeras.

Idealmente, el trabajo de un componente es habilitar la experiencia del usuario y nada más.
Un componente debe presentar propiedades y métodos para el enlace de datos, para mediar entre la vista (renderizada por la plantilla) y la lógica de la aplicación (que a menudo incluye alguna noción de un modelo).

Un componente puede delegar ciertas tareas a los servicios, como obtener datos del servidor, validar la entrada del usuario o registrar directamente en la consola.
Al definir tales tareas de procesamiento en una clase de servicio inyectable, haces que esas tareas estén disponibles para cualquier componente.
También puedes hacer que tu aplicación sea más adaptable configurando diferentes proveedores del mismo tipo de servicio, según sea apropiado en diferentes circunstancias.

Angular no hace cumplir estos principios.
Angular te ayuda a seguir estos principios haciendo que sea fácil factorizar la lógica de tu aplicación en servicios y hacer que esos servicios estén disponibles para los componentes a través de DI.

## Ejemplos de servicios

Aquí tienes un ejemplo de una clase de servicio que registra en la consola del navegador:

```
export class Logger {
  log(msg: unknown) { console.log(msg); }
  error(msg: unknown) { console.error(msg); }
  warn(msg: unknown) { console.warn(msg); }
}
```
Los servicios pueden depender de otros servicios.
Por ejemplo, aquí tienes un `HeroService` que depende del servicio `Logger`, y también usa `BackendService` para obtener héroes.
Ese servicio a su vez podría depender del servicio `HttpClient` para obtener héroes de forma asíncrona desde un servidor:

```
import { inject } from "@angular/core";

export class HeroService {
  private heroes: Hero[] = [];

private backend = inject(BackendService);
  private logger = inject(Logger);

async getHeroes() {
    // Fetch
    this.heroes = await this.backend.getAll(Hero);
    // Log
    this.logger.log(`Obtenidos ${this.heroes.length} héroes.`);
    return this.heroes;
  }
}
```
## Creando un servicio inyectable con el CLI

El Angular CLI proporciona un comando para crear un nuevo servicio. En el siguiente ejemplo, agregas un nuevo servicio a una aplicación existente.

Para generar una nueva clase `HeroService` en la carpeta `src/app/heroes`, sigue estos pasos:

1. Ejecuta este comando [Angular CLI](/tools/cli):

```sh
ng generate service heroes/hero
```
Este comando crea el siguiente `HeroService` por defecto:

```
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root',
})
export class HeroService {}
```
El decorador `@Injectable()` especifica que Angular puede usar esta clase en el sistema DI.
Los metadatos, `providedIn: 'root'`, significan que el `HeroService` se provee en toda la aplicación.

Agrega un método `getHeroes()` que devuelva los héroes de `mock.heroes.ts` para obtener los datos simulados de héroes:

```
import { Injectable } from '@angular/core';
import { HEROES } from './mock-heroes';

@Injectable({
  // declara que este servicio debe ser creado
  // por el inyector de la aplicación raíz.
  providedIn: 'root',
})
export class HeroService {
  getHeroes() {
    return HEROES;
  }
}
```
Para claridad y mantenibilidad, se recomienda que definas componentes y servicios en archivos separados.

## Inyectando servicios

Para inyectar un servicio como dependencia en un componente, puedes declarar un campo de clase que represente la dependencia y usar la función `inject` de Angular para inicializarlo.

El siguiente ejemplo especifica el `HeroService` en el `HeroListComponent`.
El tipo de `heroService` es `HeroService`.

```
import { inject } from "@angular/core";

export class HeroListComponent {
  private heroService = inject(HeroService);
}
```
También es posible inyectar un servicio en un componente usando el constructor del componente:

```
constructor(private heroService: HeroService)
```
El método `inject` puede ser usado tanto en clases como en funciones, mientras que el método constructor naturalmente solo puede ser usado en un constructor de clase. Sin embargo, en cualquier caso una dependencia solo puede ser inyectada en un [contexto de inyección](guide/di/dependency-injection-context) válido, usualmente en la construcción o inicialización de un componente.

## Inyectando servicios en otros servicios

Cuando un servicio depende de otro servicio, sigue el mismo patrón que inyectar en un componente.
En el siguiente ejemplo, `HeroService` depende de un servicio `Logger` para reportar sus actividades:

```
import { inject, Injectable } from '@angular/core';
import { HEROES } from './mock-heroes';
import { Logger } from '../logger.service';

@Injectable({
  providedIn: 'root',
})
export class HeroService {
  private logger = inject(Logger);

getHeroes() {
    this.logger.log('Getting heroes.');
    return HEROES;
  }
}
```
En este ejemplo, el método `getHeroes()` usa el servicio `Logger` registrando un mensaje cuando obtiene héroes.

## Próximos pasos
# Configurando proveedores de dependencias

Las secciones anteriores describieron cómo usar instancias de clase como dependencias.
Además de las clases, también puedes usar valores como `boolean`, `string`, `Date` y objetos como dependencias.
Angular proporciona las APIs necesarias para hacer flexible la configuración de dependencias, para que puedas hacer que esos valores estén disponibles en DI.

## Especificando un token de proveedor

Si especificas la clase de servicio como el token de proveedor, el comportamiento por defecto es que el inyector instancie esa clase usando el operador `new`.

En el siguiente ejemplo, el componente de la aplicación provee una instancia de `Logger`:

```
providers: [Logger],
```
Sin embargo, puedes configurar DI para asociar el token de proveedor `Logger` con una clase diferente o cualquier otro valor.
Así que cuando se inyecte `Logger`, se usará el valor configurado en su lugar.

De hecho, la sintaxis del proveedor de clase es una expresión abreviada que se expande en una configuración de proveedor, definida por la interfaz `Provider`.
Angular expande el valor `providers` en este caso en un objeto de proveedor completo de la siguiente manera:

```
[{ provide: Logger, useClass: Logger }]
```
La configuración de proveedor expandida es un objeto literal con dos propiedades:

- La propiedad `provide` contiene el token que sirve como clave para consumir el valor de la dependencia.
- La segunda propiedad es un objeto de definición de proveedor, que le dice al inyector **cómo** crear el valor de la dependencia. La definición de proveedor puede ser una de las siguientes:
  - `useClass` - esta opción le dice a Angular DI que instancie una clase proveída cuando se inyecte una dependencia
  - `useExisting` - te permite crear un alias de un token y referenciar cualquier existente.
  - `useFactory` - te permite definir una función que construye una dependencia.
  - `useValue` - provee un valor estático que debe ser usado como dependencia.

Las siguientes secciones describen cómo usar las diferentes definiciones de proveedor.

### Proveedores de clase: useClass

La clave de proveedor `useClass` te permite crear y devolver una nueva instancia de la clase especificada.

Puedes usar este tipo de proveedor para sustituir una implementación alternativa para una clase común o por defecto.
La implementación alternativa puede, por ejemplo, implementar una estrategia diferente, extender la clase por defecto, o emular el comportamiento de la clase real en un caso de prueba.

En el siguiente ejemplo, `BetterLogger` sería instanciado cuando se solicite la dependencia `Logger` en un componente o cualquier otra clase:

```
[{ provide: Logger, useClass: BetterLogger }]
```
Si los proveedores de clase alternativa tienen sus propias dependencias, especifica ambos proveedores en la propiedad de metadatos providers del módulo o componente padre:

```
[
  UserService, // dependencia necesaria en `EvenBetterLogger`.
  { provide: Logger, useClass: EvenBetterLogger },
]
```
En este ejemplo, `EvenBetterLogger` muestra el nombre del usuario en el mensaje de log. Este logger obtiene el usuario de una instancia inyectada de `UserService`:

```
@Injectable()
export class EvenBetterLogger extends Logger {
  private userService = inject(UserService);

override log(message: string) {
    const name = this.userService.user.name;
    super.log(`Mensaje para ${name}: ${message}`);
  }
}
```
Angular DI sabe cómo construir la dependencia `UserService`, ya que ha sido configurada arriba y está disponible en el inyector.

### Proveedores de alias: useExisting

La clave de proveedor `useExisting` te permite mapear un token a otro.
En efecto, el primer token es un alias para el servicio asociado con el segundo token, creando dos formas de acceder al mismo objeto de servicio.

En el siguiente ejemplo, el inyector inyecta la instancia singleton de `NewLogger` cuando el componente solicita el logger nuevo o el viejo:
De esta manera, `OldLogger` es un alias para `NewLogger`.

```
[
  NewLogger,
  // Alias OldLogger con referencia a NewLogger
  { provide: OldLogger, useExisting: NewLogger},
]
```
NOTA: Asegúrate de no crear un alias de `OldLogger` a `NewLogger` con `useClass`, ya que esto crea dos instancias diferentes de `NewLogger`.

### Proveedores de fábrica: useFactory

La clave de proveedor `useFactory` te permite crear un objeto de dependencia llamando a una función de fábrica.
Con este enfoque, puedes crear un valor dinámico basado en información disponible en DI y en otros lugares de la aplicación.

En el siguiente ejemplo, solo los usuarios autorizados deberían ver héroes secretos en el `HeroService`.
La autorización puede cambiar durante el curso de una sola sesión de aplicación, como cuando un usuario diferente inicia sesión.

Para mantener la información sensible de seguridad en `UserService` y fuera de `HeroService`, dale al constructor de `HeroService` una bandera booleana para controlar la visualización de héroes secretos:

```
class HeroService {
  constructor(
    private logger: Logger,
    private isAuthorized: boolean) { }

getHeroes() {
    const auth = this.isAuthorized ? 'autorizado' : 'no autorizado';
    this.logger.log(`Obteniendo héroes para usuario ${auth}.`);
    return HEROES.filter(hero => this.isAuthorized || !hero.isSecret);
  }
}
```
Para implementar la bandera `isAuthorized`, usa un proveedor de fábrica para crear una nueva instancia de logger para `HeroService`.
Esto es necesario ya que necesitamos pasar manualmente `Logger` al construir el servicio de héroes:

```
const heroServiceFactory = (logger: Logger, userService: UserService) =>
  new HeroService(logger, userService.user.isAuthorized);
```
La función de fábrica tiene acceso a `UserService`.
Inyectas tanto `Logger` como `UserService` en el proveedor de fábrica para que el inyector pueda pasarlos a la función de fábrica:

```
export const heroServiceProvider = {
  provide: HeroService,
  useFactory: heroServiceFactory,
  deps: [Logger, UserService]
};
```
- El campo `useFactory` especifica que el proveedor es una función de fábrica cuya implementación es `heroServiceFactory`.
- La propiedad `deps` es un array de tokens de proveedor.
Las clases `Logger` y `UserService` sirven como tokens para sus propios proveedores de clase.
El inyector resuelve estos tokens e inyecta los servicios correspondientes en los parámetros de la función de fábrica `heroServiceFactory` coincidentes, basándose en el orden especificado.

Capturar el proveedor de fábrica en la variable exportada, `heroServiceProvider`, hace que el proveedor de fábrica sea reutilizable.

### Proveedores de valor: useValue

La clave `useValue` te permite asociar un valor estático con un token DI.

Usa esta técnica para proveer constantes de configuración en tiempo de ejecución como direcciones base de sitios web y banderas de características.
También puedes usar un proveedor de valor en una prueba unitaria para proveer datos simulados en lugar de un servicio de datos de producción.

La siguiente sección proporciona más información sobre la clave `useValue`.

## Usando un objeto `InjectionToken`

Usa un objeto `InjectionToken` como token de proveedor para dependencias que no son clases.
El siguiente ejemplo define un token, `APP_CONFIG`. del tipo `InjectionToken`:

```
import { InjectionToken } from '@angular/core';

export interface AppConfig {
  title: string;
}

export const APP_CONFIG = new InjectionToken<AppConfig>('app.config description');
```
El parámetro de tipo opcional, `<AppConfig>`, y la descripción del token, `descripción de app.config`, especifican el propósito del token.

A continuación, registra el proveedor de dependencia en el componente usando el objeto `InjectionToken` de `APP_CONFIG`:

```
const MY_APP_CONFIG_VARIABLE: AppConfig = {
  title: 'Hola',
};

providers: [{ provide: APP_CONFIG, useValue: MY_APP_CONFIG_VARIABLE }]
```
Ahora, inyecta el objeto de configuración en el cuerpo del constructor con la función `inject`:

```
export class AppComponent {
  constructor() {
    const config = inject(APP_CONFIG);
    this.title = config.title;
  }
}
```
### Interfaces y DI

Aunque la interfaz `AppConfig` de TypeScript soporta tipado dentro de la clase, la interfaz `AppConfig` no juega ningún papel en DI.
En TypeScript, una interfaz es un artefacto de tiempo de diseño, y no tiene una representación en tiempo de ejecución, o token, que el framework DI pueda usar.

Cuando TypeScript se transpila a JavaScript, la interfaz desaparece porque JavaScript no tiene interfaces.
Como no hay interfaz para que Angular encuentre en tiempo de ejecución, la interfaz no puede ser un token, ni puedes inyectarla:

```
// No se puede usar interfaz como token de proveedor
[{ provide: AppConfig, useValue: MY_APP_CONFIG_VARIABLE })]
```
```
export class AppComponent {
  // No se puede inyectar usando la interfaz como el tipo de parámetro
  private config = inject(AppConfig);
}
```

# Contexto de inyección

El sistema de inyección de dependencias (DI) se basa internamente en un contexto de tiempo de ejecución donde el inyector actual está disponible.
Esto significa que los inyectores solo pueden funcionar cuando el código se ejecuta en dicho contexto.

El contexto de inyección está disponible en estas situaciones:

* Durante la construcción (vía el `constructor`) de una clase siendo instanciada por el sistema DI, como un `@Injectable` o `@Component`.
* En el inicializador para campos de dichas clases.
* En la función de fábrica especificada para `useFactory` de un `Provider` o un `@Injectable`.
* En la función `factory` especificada para un `InjectionToken`.
* Dentro de un Stack frame que se ejecuta en un contexto de inyección.

Saber cuándo estás en un contexto de inyección te permitirá usar la función [`inject`](api/core/inject) para inyectar instancias.

## Constructores de clase

Cada vez que el sistema DI instancia una clase, lo hace en un contexto de inyección. Esto es manejado por el framework mismo. El constructor de la clase se ejecuta en ese contexto de tiempo de ejecución, lo que también permite la inyección de un token usando la función [`inject`](api/core/inject).

```typescript
class MyComponent  {
  private service1: Service1;
  private service2: Service2 = inject(Service2); // In context

constructor() {
    this.service1 = inject(Service1) // In context
  }
}
```
## Stack frame en contexto

Algunas APIs están diseñadas para ejecutarse en un contexto de inyección. Este es el caso, por ejemplo, con los guards del router. Esto permite el uso de [`inject`](api/core/inject) dentro de la función guard para acceder a un servicio.

Aquí tienes un ejemplo para `CanActivateFn`

```typescript
const canActivateTeam: CanActivateFn =
    (route: ActivatedRouteSnapshot, state: RouterStateSnapshot) => {
      return inject(PermissionsService).canActivate(inject(UserToken), route.params.id);
    };
```
## Ejecutar dentro de un contexto de inyección

Cuando quieres ejecutar una función dada en un contexto de inyección sin estar ya en uno, puedes hacerlo con `runInInjectionContext`.
Esto requiere acceso a un inyector dado, como el `EnvironmentInjector`, por ejemplo:

```
@Injectable({
  providedIn: 'root',
})
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // Haz lo que necesites con el servicio inyectado
    });
  }
}
```
Ten en cuenta que `inject` devolverá una instancia solo si el inyector puede resolver el token requerido.

## Afirma el contexto

Angular proporciona la función auxiliar `assertInInjectionContext` para afirmar que el contexto actual es un contexto de inyección.

## Usando DI fuera de un contexto

Llamar a [`inject`](api/core/inject) o llamar a `assertInInjectionContext` fuera de un contexto de inyección lanzará [error NG0203](/errors/NG0203).
# Inyectores jerárquicos

Los inyectores en Angular tienen reglas que puedes aprovechar para lograr la visibilidad deseada de inyectables en tus aplicaciones.
Al entender estas reglas, puedes determinar si declarar un proveedor a nivel de aplicación, en un Componente, o en una Directiva.

Las aplicaciones que construyes con Angular pueden volverse bastante grandes, y una forma de manejar esta complejidad es dividir la aplicación en un árbol bien definido de componentes.

Puede haber secciones de tu página que funcionen de una manera completamente independiente al resto de la aplicación, con sus propias copias locales de los servicios y otras dependencias que necesita.
Algunos de los servicios que estas secciones de la aplicación usan podrían ser compartidos con otras partes de la aplicación, o con componentes padre que están más arriba en el árbol de componentes, mientras que otras dependencias están destinadas a ser privadas.

Con la inyección de dependencias jerárquica, puedes aislar secciones de la aplicación y darles sus propias dependencias privadas no compartidas con el resto de la aplicación, o hacer que los componentes padre compartan ciertas dependencias con sus componentes hijo únicamente pero no con el resto del árbol de componentes, y así sucesivamente. La inyección de dependencias jerárquica te permite compartir dependencias entre diferentes partes de la aplicación solo cuando y si las necesitas.

## Tipos de jerarquías de inyectores

Angular tiene dos jerarquías de inyectores:

| Jerarquías de inyectores        | Detalles |
|:---                         |:---     |
| Jerarquía `EnvironmentInjector` | Configura un `EnvironmentInjector` en esta jerarquía usando `@Injectable()` o array `providers` en `ApplicationConfig`. |
| Jerarquía `ElementInjector` | Creada implícitamente en cada elemento DOM. Un `ElementInjector` está vacío por defecto a menos que lo configures en la propiedad `providers` en `@Directive()` o `@Component()`. |
Para aplicaciones basadas en `NgModule`, puedes proveer dependencias con la jerarquía `ModuleInjector` usando una anotación `@NgModule()` o `@Injectable()`.
### `EnvironmentInjector`

El `EnvironmentInjector` puede ser configurado de una de dos maneras usando:

* La propiedad `providedIn` de `@Injectable()` para referirse a `root` o `platform`
* El array `providers` de `ApplicationConfig`
Usar la propiedad `providedIn` de `@Injectable()` es preferible a usar el array `providers` de `ApplicationConfig`. Con `providedIn` de `@Injectable()`, las herramientas de optimización pueden realizar tree-shaking, que elimina servicios que tu aplicación no está usando. Esto resulta en tamaños de paquete más pequeños.

El tree-shaking es especialmente útil para una biblioteca porque la aplicación que usa la biblioteca puede no tener necesidad de inyectarla.
`EnvironmentInjector` está configurado por `ApplicationConfig.providers`.

Provee servicios usando `providedIn` de `@Injectable()` de la siguiente manera:

```typescript
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root'  // <--provee este servicio en el EnvironmentInjector raíz
})
export class ItemService {
  name = 'telephone';
}
```
El decorador `@Injectable()` identifica una clase de servicio.
La propiedad `providedIn` configura un `EnvironmentInjector` específico, en este caso `root`, que hace que el servicio esté disponible en el `EnvironmentInjector` `root`.

### ModuleInjector

En el caso de aplicaciones basadas en `NgModule`, el ModuleInjector puede ser configurado de una de dos maneras usando:

* La propiedad `providedIn` de `@Injectable()` para referirse a `root` o `platform`
* El array `providers` de `@NgModule()`

`ModuleInjector` está configurado por la propiedad `@NgModule.providers` y `NgModule.imports`. `ModuleInjector` es un aplanamiento de todos los arrays de proveedores que pueden ser alcanzados siguiendo `NgModule.imports` recursivamente.

Las jerarquías hijas de `ModuleInjector` se crean cuando se cargan perezosamente otros `@NgModules`.

### Inyector de plataforma

Hay dos inyectores más arriba de `root`, un `EnvironmentInjector` adicional y `NullInjector()`.

Considera cómo Angular inicializa la aplicación con lo siguiente en `main.ts`:

```javascript
bootstrapApplication(AppComponent, appConfig);
```
El método `bootstrapApplication()` crea un inyector hijo del inyector de plataforma que se configura mediante la la instancia `ApplicationConfig`.
Este es el `EnvironmentInjector` `root`.

El método `platformBrowserDynamic()` crea un inyector configurado por un `PlatformModule`, que contiene dependencias específicas de la plataforma.
Esto permite que múltiples aplicaciones compartan una configuración de plataforma.
Por ejemplo, un navegador tiene solo una barra de URL, sin importar cuántas aplicaciones tengas ejecutándose.
Puedes configurar proveedores adicionales específicos de la plataforma a nivel de plataforma suministrando `extraProviders` usando la función `platformBrowser()`.

El siguiente inyector padre en la jerarquía es el `NullInjector()`, que está en la parte superior del árbol.
Si has ido tan arriba en el árbol que estás buscando un servicio en el `NullInjector()`, obtendrás un error a menos que hayas usado `@Optional()` porque en última instancia, todo termina en el `NullInjector()` y devuelve un error o, en el caso de `@Optional()`, `null`.
Para más información sobre `@Optional()`, consulta la [sección `@Optional()`](#optional) de esta guía.

El siguiente diagrama representa la relación entre el `ModuleInjector` `root` y sus inyectores padre como describen los párrafos anteriores.

```mermaid
stateDiagram-v2
    elementInjector: EnvironmentInjector<br>(configurado por Angular)<br>tiene cosas especiales como DomSanitizer => providedIn 'platform'
    rootInjector: root EnvironmentInjector<br>(configurado por AppConfig)<br>tiene cosas para tu app => bootstrapApplication(..., AppConfig)
    nullInjector: NullInjector<br>siempre lanza un error a menos que<br>uses @Optional()

direction BT
    rootInjector --> elementInjector
    elementInjector --> nullInjector
```

Mientras que el nombre `root` es un alias especial, otras jerarquías de `EnvironmentInjector` no tienen alias.
Tienes la opción de crear jerarquías de `EnvironmentInjector` cada vez que se crea un componente cargado dinámicamente, como con el Router, que creará jerarquías hijas de `EnvironmentInjector`.

Todas las solicitudes se reenvían al inyector raíz, ya sea que lo hayas configurado con la instancia `ApplicationConfig` pasada al método `bootstrapApplication()`, o registrado todos los proveedores con `root` en sus propios servicios.
Si configuras un proveedor de toda la aplicación en el `ApplicationConfig` de `bootstrapApplication`, sobrescribe uno configurado para `root` en los metadatos `@Injectable()`.
Puedes hacer esto para configurar un proveedor no por defecto de un servicio que se comparte con múltiples aplicaciones.

Aquí tienes un ejemplo del caso donde la configuración del router de componentes incluye una [estrategia de ubicación](guide/routing#location-strategy) no por defecto listando su proveedor en la lista `providers` del `ApplicationConfig`.

```ts
providers: [
  { provide: LocationStrategy, useClass: HashLocationStrategy }
]
```

Para aplicaciones basadas en `NgModule`, configura proveedores de toda la aplicación en los `providers` de `AppModule`.
### `ElementInjector`

Angular crea jerarquías de `ElementInjector` implícitamente para cada elemento DOM.

Proveer un servicio en el decorador `@Component()` usando su propiedad `providers` o `viewProviders` configura un `ElementInjector`.
Por ejemplo, el siguiente `TestComponent` configura el `ElementInjector` proveyendo el servicio de la siguiente manera:

```typescript
@Component({
  …
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```
ÚTIL: Consulta la sección [reglas de resolución](#resolution-rules) para entender la relación entre el árbol `EnvironmentInjector`, el `ModuleInjector` y el árbol `ElementInjector`.

Cuando provees servicios en un componente, ese servicio está disponible por medio del `ElementInjector` en esa instancia de componente.
También puede ser visible en componentes/directivas hijo basándose en las reglas de visibilidad descritas en la sección [reglas de resolución](#resolution-rules).

Cuando la instancia del componente se destruye, también se destruye esa instancia del servicio.

#### `@Directive()` y `@Component()`

Un componente es un tipo especial de directiva, lo que significa que así como `@Directive()` tiene una propiedad `providers`, `@Component()` también la tiene.
Esto significa que las directivas así como los componentes pueden configurar proveedores, usando la propiedad `providers`.
Cuando configuras un proveedor para un componente o directiva usando la propiedad `providers`, ese proveedor pertenece al `ElementInjector` de ese componente o directiva.
Los componentes y directivas en el mismo elemento comparten un inyector.

## Reglas de resolución

Al resolver un token para un componente/directiva, Angular lo resuelve en dos fases:

1. Contra sus padres en la jerarquía `ElementInjector`.
2. Contra sus padres en la jerarquía `EnvironmentInjector`.

Cuando un componente declara una dependencia, Angular trata de satisfacer esa dependencia con su propio `ElementInjector`.
Si el inyector del componente carece del proveedor, pasa la solicitud al `ElementInjector` del componente padre.

Las solicitudes siguen reenviándose hacia arriba hasta que Angular encuentra un inyector que puede manejar la solicitud o se queda sin jerarquías de `ElementInjector` ancestros.

Si Angular no encuentra el proveedor en ninguna jerarquía `ElementInjector`, regresa al elemento donde se originó la solicitud y busca en la jerarquía `EnvironmentInjector`.
Si Angular aún no encuentra el proveedor, lanza un error.

Si has registrado un proveedor para el mismo token DI en diferentes niveles, el primero que Angular encuentra es el que usa para resolver la dependencia.
Si, por ejemplo, un proveedor está registrado localmente en el componente que necesita un servicio,
Angular no busca otro proveedor del mismo servicio.

ÚTIL: Para aplicaciones basadas en `NgModule`, Angular buscará en la jerarquía `ModuleInjector` si no puede encontrar un proveedor en las jerarquías `ElementInjector`.

## Modificadores de resolución

El comportamiento de resolución de Angular puede ser modificado con `optional`, `self`, `skipSelf` y `host`.
Importa cada uno de ellos desde `@angular/core` y usa cada uno en la configuración `inject` cuando inyectes tu servicio.

### Tipos de modificadores

Los modificadores de resolución caen en tres categorías:

* Qué hacer si Angular no encuentra lo que estás buscando, eso es `optional`
* Dónde empezar a buscar, eso es `skipSelf`
* Dónde parar de buscar, `host` y `self`

Por defecto, Angular siempre comienza en el `Injector` actual y sigue buscando todo el camino hacia arriba.
Los modificadores te permiten cambiar la ubicación de inicio, o _self_, y la ubicación de finalización.

Además, puedes combinar todos los modificadores excepto:

* `host` y `self`
* `skipSelf` y `self`.

### `optional`

`optional` permite que Angular considere un servicio que inyectas como opcional.
De esta manera, si no puede ser resuelto en tiempo de ejecución, Angular resuelve el servicio como `null`, en lugar de lanzar un error.
En el siguiente ejemplo, el servicio, `OptionalService`, no está proveído en el servicio, `ApplicationConfig`, `@NgModule()`, o clase de componente, por lo que no está disponible en ningún lugar de la aplicación.

```
export class OptionalComponent {
  public optional? = inject(OptionalService, {optional: true});
}
```
### `self`

Usa `self` para que Angular solo mire el `ElementInjector` para el componente o directiva actual.

Un buen caso de uso para `self` es inyectar un servicio pero solo si está disponible en el elemento host actual.
Para evitar errores en esta situación, combina `self` con `optional`.

Por ejemplo, en el siguiente `SelfNoDataComponent`, nota el `LeafService` inyectado como una propiedad.

```
@Component({
  selector: 'app-self-no-data',
  templateUrl: './self-no-data.component.html',
  styleUrls: ['./self-no-data.component.css']
})
export class SelfNoDataComponent {
  public leaf = inject(LeafService, {optional: true, self: true});
}
```
In this example, there is a parent provider and injecting the service will return the value, however, injecting the service with `self` and `optional` will return `null` because `self` tells the injector to stop searching in the current host element.

Otro ejemplo muestra la clase de componente con un proveedor para `FlowerService`.
En este caso, el inyector no busca más allá del `ElementInjector` actual porque encuentra el `FlowerService` y devuelve el tulipán <code>🌷</code>.

```
### `skipSelf`

`skipSelf` es lo opuesto a `self`.
Con `skipSelf`, Angular comienza su búsqueda de un servicio en el `ElementInjector` padre, en lugar del actual.
Así que si el `ElementInjector` padre estuviera usando el valor de helecho <code>🌿</code> para `emoji`, pero tuvieras hoja de arce <code>🍁</code> en el array `providers` del componente, Angular ignoraría la hoja de arce <code>🍁</code> y usaría el helecho <code>🌿</code>.

Para ver esto en código, asume que el siguiente valor para `emoji` es lo que el componente padre estaría usando, como en este servicio:

<docs-code header="src/app/leaf.service.ts" language="typescript">
export class LeafService {
  emoji = '🌿';
}
```
Imagina que en el componente hijo, tenías un valor diferente, hoja de arce <code>🍁</code> pero querías usar el valor del padre en su lugar.
Esto es cuando usarías `skipSelf`:

```
@Component({
  selector: 'app-skipself',
  templateUrl: './skipself.component.html',
  styleUrls: ['./skipself.component.css'],
  // Angular ignoraría esta instancia de LeafService
  providers: [{ provide: LeafService, useValue: { emoji: '🍁' } }]
})
export class SkipselfComponent {
  // Usa skipSelf como opción de inyección
  public leaf = inject(LeafService, {skipSelf: true});
}
```
En este caso, el valor que obtendrías para `emoji` sería helecho <code>🌿</code>, no hoja de arce <code>🍁</code>.

#### Opción `skipSelf` con `optional`

Usa la opción `skipSelf` con `optional` para prevenir un error si el valor es `null`.

En el siguiente ejemplo, el servicio `Person` se inyecta durante la inicialización de la propiedad.
`skipSelf` le dice a Angular que omita el inyector actual y `optional` prevendrá un error si el servicio `Person` es `null`.

```typescript
class Person {
  parent = inject(Person, {optional: true, skipSelf: true})
}
```
### `host`

`host` te permite designar un componente como la última parada en el árbol de inyectores cuando buscas proveedores.

Incluso si hay una instancia de servicio más arriba en el árbol, Angular no continuará buscando.
Usa `host` de la siguiente manera:

```
@Component({
  selector: 'app-host',
  templateUrl: './host.component.html',
  styleUrls: ['./host.component.css'],
  //  provee el servicio
  providers: [{ provide: FlowerService, useValue: { emoji: '🌷' } }]
})
export class HostComponent {
  // usa host cuando inyectes el servicio
  flower = inject(FlowerService, {host: true, optional: true});
}
```
Dado que `HostComponent` tiene la opción `host`, sin importar lo que el padre de `HostComponent` pueda tener como valor `flower.emoji`, el `HostComponent` usará tulipán <code>🌷</code>.

### Modificadores con inyección de constructor

De manera similar a como se presentó antes, el comportamiento de la inyección de constructor puede ser modificado con `@Optional()`, `@Self()`, `@SkipSelf()` y `@Host()`.

Importa cada uno de ellos desde `@angular/core` y usa cada uno en el constructor de la clase de componente cuando inyectes tu servicio.

```
export class SelfNoDataComponent {
  constructor(@Self() @Optional() public leaf?: LeafService) { }
}
```
## Estructura lógica de la plantilla

Cuando provees servicios en la clase de componente, los servicios son visibles dentro del árbol `ElementInjector` relativo a dónde y cómo provees esos servicios.

Entender la estructura lógica subyacente de la plantilla de Angular te dará una base para configurar servicios y a su vez controlar su visibilidad.

Los componentes se usan en tus plantillas, como en el siguiente ejemplo:

```html
<app-root>
  <app-child></app-child>;
</app-root>
```
ÚTIL: Usualmente, declaras los componentes y sus plantillas en archivos separados.
Para los propósitos de entender cómo funciona el sistema de inyección, es útil mirarlos desde el punto de vista de un árbol lógico combinado.
El término _lógico_ lo distingue del árbol de renderizado, que es el árbol DOM de tu aplicación.
Para marcar las ubicaciones de dónde están ubicadas las plantillas de componentes, esta guía usa el pseudo-elemento `<#VIEW>`, que en realidad no existe en el árbol de renderizado y está presente solo para propósitos de modelo mental.

El siguiente es un ejemplo de cómo los árboles de vista `<app-root>` y `<app-child>` se combinan en un solo árbol lógico:

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …el contenido va aquí…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
Entender la idea de la demarcación `<#VIEW>` es especialmente significativo cuando configuras servicios en la clase de componente.

## Ejemplo: Proveyendo servicios en `@Component()`

Cómo provees servicios usando un decorador `@Component()` (o `@Directive()`) determina su visibilidad.
Las siguientes secciones demuestran `providers` y `viewProviders` junto con formas de modificar la visibilidad del servicio con `skipSelf` y `host`.

Una clase de componente puede proveer servicios de dos maneras:

| Arrays                       | Detalles |
|:---                          |:---     |
| Con un array `providers`     | `@Component({ providers: [SomeService] })`     |
| Con un array `viewProviders` | `@Component({ viewProviders: [SomeService] })` |

En los ejemplos de abajo, verás el árbol lógico de una aplicación Angular.
Para ilustrar cómo funciona el inyector en el contexto de plantillas, el árbol lógico representará la estructura HTML de la aplicación.
Por ejemplo, el árbol lógico mostrará que `<child-component>` es un hijo directo de `<parent-component>`.

En el árbol lógico, verás atributos especiales: `@Provide`, `@Inject`, y `@ApplicationConfig`.
Estos no son atributos reales pero están aquí para demostrar lo que está pasando internamente.

### Estructura de aplicación de ejemplo

La aplicación de ejemplo tiene un `FlowerService` proveído en `root` con un valor `emoji` de hibisco rojo <code>🌺</code>.

```
@Injectable({
  providedIn: 'root'
})
export class FlowerService {
  emoji = '🌺';
}
```
Considera una aplicación con solo un `AppComponent` y un `ChildComponent`.
La vista renderizada más básica se vería como elementos HTML anidados como los siguientes:

```html
<app-root> 
  <app-child> 
  </app-child>
</app-root>
```
Sin embargo, detrás de escena, Angular utiliza una representación de vista lógica de la siguiente manera al resolver las solicitudes de inyección:

```html
<app-root> 
  <#VIEW>
    <app-child> 
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
El `<#VIEW>` aquí representa una instancia de una plantilla.
Nota que cada componente tiene su propio `<#VIEW>`.

El conocimiento de esta estructura puede informar cómo provees e inyectas tus servicios, y darte control completo de la visibilidad del servicio.

Ahora, considera que `<app-root>` inyecta el `FlowerService`:

```
export class AppComponent  {
  flower = inject(FlowerService);
}
```
Agrega un enlace a la plantilla `<app-root>` para visualizar el resultado:

```
<p>Emoji de FlowerService: {{flower.emoji}}</p>
```
La salida en la vista sería:

```shell
Emoji from FlowerService: 🌺
```
En el árbol lógico, esto se representaría como sigue:

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji de FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child>
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
Cuando `<app-root>` solicita el `FlowerService`, es trabajo del inyector resolver el token `FlowerService`.
La resolución del token sucede en dos fases:

1. El inyector determina la ubicación de inicio en el árbol lógico y una ubicación de finalización de la búsqueda.
    El inyector comienza con la ubicación de inicio y busca el token en cada nivel de vista en el árbol lógico.
    Si el token se encuentra, se devuelve.

1. Si el token no se encuentra, el inyector busca el `EnvironmentInjector` padre más cercano para delegar la solicitud.

En el caso del ejemplo, las restricciones son:

1. Comienza con `<#VIEW>` perteneciente a `<app-root>` y termina con `<app-root>`.

* Normalmente el punto de partida para la búsqueda es en el punto de inyección.
        Sin embargo, en este caso `<app-root>` es un componente. Los `@Component`s son especiales en que también incluyen sus propios `viewProviders`, por lo que la búsqueda comienza en `<#VIEW>` perteneciente a `<app-root>`.
        Este no sería el caso para una directiva coincidente en la misma ubicación.
    * La ubicación de finalización resulta ser la misma que el componente mismo, porque es el componente superior en esta aplicación.

1. El `EnvironmentInjector` proveído por el `ApplicationConfig` actúa como el inyector de respaldo cuando el token de inyección no puede ser encontrado en las jerarquías `ElementInjector`.

### Usando el array `providers`

Ahora, en la clase `ChildComponent`, agrega un proveedor para `FlowerService` para demostrar reglas de resolución más complejas en las próximas secciones:

```
@Component({
  selector: 'app-child',
  templateUrl: './child.component.html',
  styleUrls: ['./child.component.css'],
  // usa el array providers para proveer un servicio
  providers: [{ provide: FlowerService, useValue: { emoji: '🌻' } }]
})
export class ChildComponent {
  // inyecta el servicio
  flower = inject(FlowerService);
}
```
Ahora que el `FlowerService` está proveído en el decorador `@Component()`, cuando `<app-child>` solicita el servicio, el inyector solo tiene que mirar tan lejos como el `ElementInjector` en `<app-child>`.
No tendrá que continuar la búsqueda más allá a través del árbol de inyectores.

El siguiente paso es agregar un enlace a la plantilla `ChildComponent`.

```
<p>Emoji de FlowerService: {{flower.emoji}}</p>
```
Para renderizar los nuevos valores, agrega `<app-child>` al final de la plantilla `AppComponent` para que la vista también muestre el girasol:

```shell
Child Component
Emoji de FlowerService: 🌻
```
En el árbol lógico, esto se representa de la siguiente manera:

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji de FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child @Provide(FlowerService="🌻")
               @Inject(FlowerService)=>"🌻"> 
      <#VIEW> 
        <h2>Child Component</h2>
        <p>Emoji de FlowerService: {{flower.emoji}} (🌻)</p>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
Cuando `<app-child>` solicita el `FlowerService`, el inyector comienza su búsqueda en el `<#VIEW>` perteneciente a `<app-child>` $`<#VIEW>` está incluido porque se inyecta desde `@Component()`$ y termina con `<app-child>`.
En este caso, el `FlowerService` se resuelve en el array `providers` con girasol <code>🌻</code> del `<app-child>`.
El inyector no tiene que buscar más en el árbol de inyectores.
Se detiene tan pronto como encuentra el `FlowerService` y nunca ve el hibisco rojo <code>🌺</code>.

### Usando el array `viewProviders`

Usa el array `viewProviders` como otra forma de proveer servicios en el decorador `@Component()`.
Usar `viewProviders` hace que los servicios sean visibles en el `<#VIEW>`.

ÚTIL: Los pasos son los mismos que usar el array `providers`, con la excepción de usar el array `viewProviders` en su lugar.

Para instrucciones paso a paso, continúa con esta sección.
Si puedes configurarlo por tu cuenta, salta adelante a [Modificando la disponibilidad del servicio](#visibility-of-provided-tokens).

Para demostración, estamos construyendo un `AnimalService` para demostrar `viewProviders`.
Primero, crea un `AnimalService` con una propiedad `emoji` de ballena <code>🐳</code>:

```
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root'
})
export class AnimalService {
  emoji = '🐳';
}
```
Siguiendo el mismo patrón que con el `FlowerService`, inyecta el `AnimalService` en la clase `AppComponent`:

```
export class AppComponent {
    public flower = inject(FlowerService);
    public animal = inject(AnimalService);
}
```
ÚTIL: Puedes dejar todo el código relacionado con `FlowerService` en su lugar, ya que permitirá una comparación con el `AnimalService`.

Agrega un array `viewProviders` e inyecta el `AnimalService` en la clase `<app-child>` también, pero dale a `emoji` un valor diferente.
Aquí, tiene un valor de perro <code>🐶</code>.

```
@Component({
  selector: 'app-child',
  templateUrl: './child.component.html',
  styleUrls: ['./child.component.css'],
  // provee servicios
  providers: [{ provide: FlowerService, useValue: { emoji: '��' } }],
  viewProviders: [{ provide: AnimalService, useValue: { emoji: '🐶' } }]
})
export class ChildComponent {
  // inyecta servicios
  flower = inject(FlowerService); 
  animal = inject(AnimalService)
...
}
```
Agrega enlaces a la plantilla `ChildComponent` y la plantilla `AppComponent`.
En la plantilla `ChildComponent`, agrega el siguiente enlace:

```
<p>Emoji de AnimalService: {{animal.emoji}}</p>
```
Además, agrega lo mismo a la plantilla `AppComponent`:

```
<p>Emoji de AnimalService: {{animal.emoji}}</p>s
```
Ahora deberías ver ambos valores en el navegador:

```
AppComponent
Emoji de AnimalService: 🐳

Child Component
Emoji de AnimalService: 🐶
```
El árbol lógico para este ejemplo de `viewProviders` es como sigue:

```html
<app-root @ApplicationConfig
         @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
    <app-child>
      <#VIEW @Provide(AnimalService="🐶")
            @Inject(AnimalService=>"🐶")>
       
       <p>Emoji de AnimalService: {{animal.emoji}} (🐶)</p>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
Así como con el ejemplo de `FlowerService`, el `AnimalService` está proveído en el decorador `@Component()` de `<app-child>`.
Esto significa que como el inyector primero busca en el `ElementInjector` del componente, encuentra el valor `AnimalService` de perro <code>🐶</code>.
No necesita continuar buscando en el árbol `ElementInjector`, ni necesita buscar en el `ModuleInjector`.

### `providers` vs. `viewProviders`

El campo `viewProviders` es conceptualmente similar a `providers`, pero hay una diferencia notable.
Los proveedores configurados en `viewProviders` no son visibles al contenido proyectado que termina como hijos lógicos del componente.

Para ver la diferencia entre usar `providers` y `viewProviders`, agrega otro componente al ejemplo y llámalo `InspectorComponent`.
`InspectorComponent` será un hijo del `ChildComponent`.
En `inspector.component.ts`, inyecta el `FlowerService` y `AnimalService` durante la inicialización de la propiedad:

```
export class InspectorComponent {
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```
No necesitas un array `providers` o `viewProviders`.
A continuación, en `inspector.component.html`, agrega la misma plantilla de componentes anteriores:

```
<p>Emoji de FlowerService: {{flower.emoji}}</p>
<p>Emoji de AnimalService: {{animal.emoji}}</p>
```
Recuerda agregar el `InspectorComponent` al array `imports` de `ChildComponent`.

```
@Component({
  ...
  imports: [InspectorComponent]
})
```
A continuación, agrega lo siguiente a `child.component.html`:

```
...

<div class="container">
  <h3>Proyección de contenido</h3>
  <ng-content></ng-content>
</div>
<h3>Dentro de la vista</h3>

<app-inspector></app-inspector>
```
`<ng-content>` te permite proyectar contenido, y `<app-inspector>` dentro de la plantilla `ChildComponent` hace que el `InspectorComponent` sea un componente hijo de `ChildComponent`.

A continuación, agrega lo siguiente a `app.component.html` para aprovechar la proyección de contenido.

```
<app-child>
  <app-inspector></app-inspector>
</app-child>
```
El navegador ahora renderiza lo siguiente, omitiendo los ejemplos anteriores por brevedad:

```
...
Proyección de contenido

Emoji de FlowerService: 🌻
Emoji de AnimalService: 🐳

Emoji de FlowerService: 🌻
Emoji de AnimalService: 🐶
```
Estos cuatro enlaces demuestran la diferencia entre `providers` y `viewProviders`.
Recuerda que el emoji de perro <code>🐶</code> está declarado dentro del `<#VIEW>` de `ChildComponent` y no es visible al contenido proyectado.
En su lugar, el contenido proyectado ve la ballena <code>🐳</code>.

Sin embargo, en la siguiente sección de salida, aunque el `InspectorComponent` es un componente hijo real de `ChildComponent`, `InspectorComponent` está dentro del `<#VIEW>`, así que cuando pide el `AnimalService`, ve el perro <code>🐶</code>.

El `AnimalService` en el árbol lógico se vería así:

<div class="container">
          <h3>Proyección de contenido</h3>
          <app-inspector @Inject(AnimalService) animal=>"🐳">
            <p>Emoji de AnimalService: {{animal.emoji}} (🐳)</p>
          </app-inspector>
        </div>

<app-inspector>
          <#VIEW @Inject(AnimalService) animal=>"🐶">
            <p>Emoji de AnimalService: {{animal.emoji}} (🐶)</p>
          </#VIEW>
        </app-inspector>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
El contenido proyectado de `<app-inspector>` ve la ballena <code>🐳</code>, no el perro <code>🐶</code>, porque el perro <code>🐶</code> está dentro del `<#VIEW>` de `<app-child>`.
El `<app-inspector>` solo puede ver el perro <code>🐶</code> si también está dentro del `<#VIEW>`.

### Visibilidad de tokens proveídos

Los decoradores de visibilidad influyen en dónde comienza y termina la búsqueda del token de inyección en el árbol lógico.
Para hacer esto, coloca la configuración de visibilidad en el punto de inyección, es decir, cuando invocas `inject()`, en lugar de en un punto de declaración.

Para alterar dónde el inyector comienza a buscar `FlowerService`, agrega `skipSelf` a la invocación `inject()` de `<app-child>` donde se inyecta `FlowerService`.
Esta invocación es un inicializador de propiedad del `<app-child>` como se muestra en `child.component.ts`:

```typescript
flower = inject(FlowerService, { skipSelf: true })
```
Con `skipSelf`, el inyector de `<app-child>` no busca en sí mismo el `FlowerService`.
En su lugar, el inyector comienza a buscar el `FlowerService` en el `ElementInjector` del `<app-root>`, donde no encuentra nada.
Luego, regresa al `ModuleInjector` de `<app-child>` y encuentra el valor de hibisco rojo <code>🌺</code>, que está disponible porque `<app-child>` y `<app-root>` comparten el mismo `ModuleInjector`.
La UI renderiza lo siguiente:

```
Emoji de FlowerService: 🌺
```
En un árbol lógico, esta misma idea podría verse así:

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <app-child @Provide(FlowerService="🌻")>
      <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺">
        
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
Aunque `<app-child>` provee el girasol <code>🌻</code>, la aplicación renderiza el hibisco rojo <code>🌺</code> porque `skipSelf` hace que el inyector actual (`app-child`) se omita a sí mismo y busque en su padre.

Si ahora agregas `host` (además del `skipSelf`), el resultado será `null`.
Esto es porque `host` limita el límite superior de la búsqueda al `<#VIEW>` de `app-child`.
Aquí está la idea en el árbol lógico:

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW> 
    <app-child @Provide(FlowerService="🌻")> 
      <#VIEW inject(FlowerService, {skipSelf: true, host: true, optional:true})=>null>
      </#VIEW>
      </app-parent>
  </#VIEW>
</app-root>
```
Aquí, los servicios y sus valores son los mismos, pero `host` detiene al inyector de buscar más allá del `<#VIEW>` para `FlowerService`, así que no lo encuentra y devuelve `null`.

### `skipSelf` y `viewProviders`

Recuerda, `<app-child>` provee el `AnimalService` en el array `viewProviders` con el valor de perro <code>🐶</code>.
Como el inyector solo tiene que mirar el `ElementInjector` de `<app-child>` para el `AnimalService`, nunca ve la ballena <code>🐳</code>.

Como en el ejemplo de `FlowerService`, si agregas `skipSelf` al `inject()` de `AnimalService`, el inyector no buscará en el `ElementInjector` del `<app-child>` actual para el `AnimalService`.
En su lugar, el inyector comenzará en el `ElementInjector` de `<app-root>`.

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```
El árbol lógico con `skipSelf` en `<app-child>` se ve así:

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
    <app-child>
      <#VIEW @Provide(AnimalService="🐶")
             @Inject(AnimalService, SkipSelf=>"🐳")>
        
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
Con `skipSelf` en `<app-child>`, el inyector comienza su búsqueda del `AnimalService` en el `ElementInjector` de `<app-root> `y encuentra la ballena <code>🐳</code>.

### `host` y `viewProviders`

Si solo usas `host` para la inyección de `AnimalService`, el resultado es perro <code>🐶</code> porque el inyector encuentra el `AnimalService` en el `<#VIEW>` de `<app-child>` mismo.
El `ChildComponent` configura los `viewProviders` para que el emoji de perro se provea como valor de `AnimalService`.
También puedes ver `host` en el `inject()`:

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ]
})
export class ChildComponent {
  animal = inject(AnimalService, { host: true })
}
```
`host: true` hace que el inyector busque hasta que encuentre el borde del `<#VIEW>`.

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳">
  <#VIEW>
    <app-child>
      <#VIEW @Provide(AnimalService="🐶")
             inject(AnimalService, {host: true}=>"🐶")> 
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```
Agrega un array `viewProviders` con un tercer animal, erizo <code>🦔</code>, a los metadatos `@Component()` de `app.component.ts`:

```typescript
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: [ './app.component.css' ],
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🦔' } },
  ],
})
```
A continuación, agrega `skipSelf` junto con `host` al `inject()` para la inyección de `AnimalService` en `child.component.ts`.
Aquí están `host` y `skipSelf` en la inicialización de la propiedad `animal`:

```typescript
export class ChildComponent {
  animal = inject(AnimalService, { host: true, skipSelf: true });
}
```

Cuando `host` y `skipSelf` se aplicaron al `FlowerService`, que está en el array `providers`, el resultado fue `null` porque `skipSelf` comienza su búsqueda en el inyector de `<app-child>`, pero `host` detiene la búsqueda en `<#VIEW>` —donde no hay `FlowerService`
En el árbol lógico, puedes ver que el `FlowerService` es visible en `<app-child>`, no en su `<#VIEW>`.

Sin embargo, el `AnimalService`, que se provee en el array `viewProviders` de `AppComponent`, es visible.

La representación del árbol lógico muestra por qué esto es así:

```html
<app-root @ApplicationConfig
        @Inject(AnimalService=>"🐳">
  <#VIEW @Provide(AnimalService="🦔")
         @Inject(AnimalService, @Optional)=>"🦔">
    
    <app-child>
      <#VIEW @Provide(AnimalService="🐶")
             inject(AnimalService, {skipSelf:true, host: true, optional: true})=>"🦔">
               
      </#VIEW>
      </app-child>
  </#VIEW>
</app-root>
```
`skipSelf`, hace que el inyector comience su búsqueda del `AnimalService` en `<app-root>`, no en `<app-child>`, donde se origina la solicitud, y `host` detiene la búsqueda en el `<#VIEW>` de `<app-root>`.
Como `AnimalService` se provee por medio del array `viewProviders`, el inyector encuentra el erizo <code>🦔</code> en el `<#VIEW>`.

## Ejemplo: Casos de uso de `ElementInjector`

La capacidad de configurar uno o más proveedores en diferentes niveles abre posibilidades útiles.

### Escenario: aislamiento de servicios

Las razones arquitectónicas pueden llevarte a restringir el acceso a un servicio al dominio de aplicación donde pertenece.
Por ejemplo, considera que construimos un `VillainsListComponent` que muestra una lista de villanos.
Obtiene esos villanos de un `VillainsService`.

Si provees `VillainsService` en el `AppModule` raíz, hará que `VillainsService` sea visible en todas partes de la aplicación.
Si más tarde modificas el `VillainsService`, podrías romper algo en otros componentes que comenzaron a depender de este servicio por accidente.

En su lugar, deberías proveer el `VillainsService` en los metadatos `providers` del `VillainsListComponent` así:

```
@Component({
  selector: 'app-villains-list',
  templateUrl: './villains-list.component.html',
  providers: [VillainsService]
})
export class VillainsListComponent {}
```
Al proveer `VillainsService` en los metadatos de `VillainsListComponent` y en ningún otro lugar, el servicio se vuelve disponible solo en el `VillainsListComponent` y su árbol de subcomponentes.

`VillainService` es un singleton con respecto a `VillainsListComponent` porque ahí es donde se declara.
Mientras `VillainsListComponent` no se destruya, será la misma instancia de `VillainService`, pero si hay múltiples instancias de `VillainsListComponent`, entonces cada instancia de `VillainsListComponent` tendrá su propia instancia de `VillainService`.

### Escenario: múltiples sesiones de edición

Muchas aplicaciones permiten a los usuarios trabajar en varias tareas abiertas al mismo tiempo.
Por ejemplo, en una aplicación de preparación de impuestos, el preparador podría estar trabajando en varias declaraciones de impuestos, cambiando de una a otra durante el día.

Para demostrar ese escenario, imagina un `HeroListComponent` que muestra una lista de superhéroes.

Para abrir la declaración de impuestos de un héroe, el preparador hace clic en el nombre de un héroe, lo que abre un componente para editar esa declaración.
Cada declaración de impuestos de héroe seleccionada se abre en su propio componente y múltiples declaraciones pueden estar abiertas al mismo tiempo.

Cada componente de declaración de impuestos tiene las siguientes características:

* Es su propia sesión de edición de declaración de impuestos
* Puede cambiar una declaración de impuestos sin afectar una declaración en otro componente
* Tiene la capacidad de guardar los cambios en su declaración de impuestos o cancelarlos

Supongamos que el `HeroTaxReturnComponent` tenía lógica para manejar y restaurar cambios.
Eso sería una tarea sencilla para una declaración de impuestos de héroe.
En el mundo real, con un modelo de datos de declaración de impuestos rico, el manejo de cambios sería complicado.
Podrías delegar ese manejo a un servicio auxiliar, como hace este ejemplo.

El `HeroTaxReturnService` almacena en caché una sola `HeroTaxReturn`, rastrea los cambios en esa declaración, y puede guardarla o restaurarla.
También delega al singleton de toda la aplicación `HeroService`, que obtiene por inyección.

```
import { Injectable } from '@angular/core';
import { HeroTaxReturn } from './hero';
import { HeroesService } from './heroes.service';

@Injectable()
export class HeroTaxReturnService {
  private currentTaxReturn!: HeroTaxReturn;
  private originalTaxReturn!: HeroTaxReturn;

private heroService = inject(HeroesService);

set taxReturn(htr: HeroTaxReturn) {
    this.originalTaxReturn = htr;
    this.currentTaxReturn  = htr.clone();
  }

get taxReturn(): HeroTaxReturn {
    return this.currentTaxReturn;
  }

restoreTaxReturn() {
    this.taxReturn = this.originalTaxReturn;
  }

saveTaxReturn() {
    this.taxReturn = this.currentTaxReturn;
    this.heroService.saveTaxReturn(this.currentTaxReturn).subscribe();
  }
}
```
Aquí está el `HeroTaxReturnComponent` que hace uso de `HeroTaxReturnService`.

```
import { Component, EventEmitter, input, output } from '@angular/core';
import { HeroTaxReturn } from './hero';
import { HeroTaxReturnService } from './hero-tax-return.service';

@Component({
  selector: 'app-hero-tax-return',
  templateUrl: './hero-tax-return.component.html',
  styleUrls: [ './hero-tax-return.component.css' ],
  providers: [ HeroTaxReturnService ]
})
export class HeroTaxReturnComponent {
  message = '';

close = output<void>();

get taxReturn(): HeroTaxReturn {
    return this.heroTaxReturnService.taxReturn;
  }

taxReturn = input.required<HeroTaxReturn>();

constructor() {
    effect(() => {
      this.heroTaxReturnService.taxReturn = this.taxReturn();
    })
  }

private heroTaxReturnService = inject(HeroTaxReturnService);

onCanceled()  {
    this.flashMessage('Canceled');
    this.heroTaxReturnService.restoreTaxReturn();
  }

onClose() { this.close.emit(); }

onSaved() {
    this.flashMessage('Saved');
    this.heroTaxReturnService.saveTaxReturn();
  }

flashMessage(msg: string) {
    this.message = msg;
    setTimeout(() => this.message = '', 500);
  }
}
```
La _tax-return-to-edit_ llega por medio de la propiedad `input`, que se implementa con getters y setters.
El setter inicializa la propia instancia del componente del `HeroTaxReturnService` con la declaración entrante.
El getter siempre devuelve lo que ese servicio dice que es el estado actual del héroe.
El componente también le pide al servicio que guarde y restaure esta declaración de impuestos.

Esto no funcionará si el servicio es un singleton de toda la aplicación.
Cada componente compartiría la misma instancia del servicio, y cada componente sobrescribiría la declaración de impuestos que pertenecía a otro héroe.

Para prevenir esto, configura el inyector a nivel de componente de `HeroTaxReturnComponent` para proveer el servicio, usando la propiedad `providers` en los metadatos del componente.

```
providers: [HeroTaxReturnService]
```
El `HeroTaxReturnComponent` tiene su propio proveedor del `HeroTaxReturnService`.
Recuerda que cada _instancia_ de componente tiene su propio inyector.
Proveer el servicio a nivel de componente asegura que _cada_ instancia del componente obtenga una instancia privada del servicio. Esto asegura que ninguna declaración de impuestos se sobrescriba.

ÚTIL: El resto del código del escenario depende de otras características y técnicas de Angular que puedes aprender en otras partes de la documentación.

### Escenario: proveedores especializados

Otra razón para proveer un servicio nuevamente en otro nivel es sustituir una implementación _más especializada_ de ese servicio, más profundo en el árbol de componentes.

Por ejemplo, considera un componente `Car` que incluye información de servicio de neumáticos y depende de otros servicios para proporcionar más detalles sobre el automóvil.

El inyector raíz, marcado como (A), usa proveedores _genéricos_ para detalles sobre `CarService` y `EngineService`.

1. Componente `Car` (A). El componente (A) muestra datos de servicio de neumáticos sobre un automóvil y especifica servicios genéricos para proporcionar más información sobre el automóvil.

2. Componente hijo (B). El componente (B) define sus propios proveedores _especializados_ para `CarService` y `EngineService` que tienen capacidades especiales adecuadas para lo que está pasando en el componente (B).

3. Componente hijo (C) como hijo del componente (B). El componente (C) define su propio proveedor aún _más especializado_ para `CarService`.

```mermaid
graph TD;
subgraph COMPONENT_A[Componente A]
subgraph COMPONENT_B[Componente B]
COMPONENT_C[Componente C]
end
end

style COMPONENT_A fill:#BDD7EE
style COMPONENT_B fill:#FFE699
style COMPONENT_C fill:#A9D18E,color:#000
classDef noShadow filter:none
class COMPONENT_A,COMPONENT_B,COMPONENT_C noShadow
```

Detrás de escena, cada componente configura su propio inyector con cero, uno o más proveedores definidos para ese componente mismo.

Cuando resuelves una instancia de `Car` en el componente más profundo (C), su inyector produce:

* Una instancia de `Car` resuelta por el inyector (C)
* Un `Engine` resuelto por el inyector (B)
* Sus `Tires` resueltos por el inyector raíz (A).

```mermaid
graph BT;

subgraph A[" "]
direction LR
RootInjector["(A) RootInjector"]
ServicesA["CarService, EngineService, TiresService"]
end

subgraph B[" "]
direction LR
ParentInjector["(B) ParentInjector"]
ServicesB["CarService2, EngineService2"]
end

subgraph C[" "]
direction LR
ChildInjector["(C) ChildInjector"]
ServicesC["CarService3"]
end

direction LR
car["(C) Car"]
engine["(B) Engine"]
tires["(A) Tires"]

direction BT
car-->ChildInjector
ChildInjector-->ParentInjector-->RootInjector

class car,engine,tires,RootInjector,ParentInjector,ChildInjector,ServicesA,ServicesB,ServicesC,A,B,C noShadow
style car fill:#A9D18E,color:#000
style ChildInjector fill:#A9D18E,color:#000
style engine fill:#FFE699,color:#000
style ParentInjector fill:#FFE699,color:#000
style tires fill:#BDD7EE,color:#000
style RootInjector fill:#BDD7EE,color:#000
```

## Más sobre inyección de dependencias
# Optimizando el tamaño de la aplicación con tokens de inyección ligeros

Esta página proporciona una visión conceptual de una técnica de inyección de dependencias que se recomienda para desarrolladores de librerías.
Diseñar tu librería con *tokens de inyección ligeros* ayuda a optimizar el tamaño del paquete de las aplicaciones cliente que usan tu librería.

Puedes gestionar la estructura de dependencias entre tus componentes y servicios inyectables para optimizar el tamaño del paquete usando proveedores tree-shakable.
Esto normalmente asegura que si un componente o servicio provisto nunca se usa realmente por la aplicación, el compilador puede eliminar su código del paquete.

Debido a la forma en que Angular almacena los tokens de inyección, es posible que tal componente o servicio no utilizado termine en el paquete de todas formas.
Esta página describe un patrón de diseño de inyección de dependencias que soporta tree-shaking adecuado usando tokens de inyección ligeros.

El patrón de diseño de tokens de inyección ligeros es especialmente importante para desarrolladores de librerías.
Asegura que cuando una aplicación usa solo algunas de las capacidades de tu librería, el código no utilizado puede ser eliminado del paquete de la aplicación cliente.

Cuando una aplicación usa tu librería, puede haber algunos servicios que tu librería suministra que la aplicación cliente no usa.
En este caso, el desarrollador de la aplicación debería esperar que ese servicio sea tree-shaken, y no contribuya al tamaño de la aplicación compilada.
Como el desarrollador de la aplicación no puede conocer o remediar un problema de tree-shaking en la librería, es responsabilidad del desarrollador de la librería hacerlo.
Para prevenir la retención de componentes no utilizados, tu librería debería usar el patrón de diseño de tokens de inyección ligeros.

## Cuándo se retienen los tokens

Para explicar mejor la condición bajo la cual ocurre la retención de tokens, considera una librería que proporciona un componente library-card.
Este componente contiene un cuerpo y puede contener un encabezado opcional:

```html
<lib-card>;
  <lib-header>…</lib-header>;
</lib-card>;
```
En una implementación probable, el componente `<lib-card>` usa `@ContentChild()` o `@ContentChildren()` para obtener `<lib-header>` y `<lib-body>`, como en el siguiente ejemplo:

```typescript
@Component({
  selector: 'lib-header',
  …,
})
class LibHeaderComponent {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCardComponent {
  @ContentChild(LibHeaderComponent) header: LibHeaderComponent|null = null;
}
```
Dado que `<lib-header>` es opcional, el elemento puede aparecer en la plantilla en su forma mínima, `<lib-card></lib-card>`.
En este caso, `<lib-header>` no se usa y esperarías que sea tree-shaken, pero eso no es lo que sucede.
Esto es porque `LibCardComponent` en realidad contiene dos referencias al `LibHeaderComponent`:

```typescript
@ContentChild(LibHeaderComponent) header: LibHeaderComponent;
```
* Una de estas referencias está en la *posición de tipo*: es decir, especifica `LibHeaderComponent` como un tipo: `header: LibHeaderComponent;`.
* La otra referencia está en la *posición de valor*: es decir, LibHeaderComponent es el valor del decorador de parámetro `@ContentChild()`: `@ContentChild(LibHeaderComponent)`.

El compilador maneja las referencias de tokens en estas posiciones de manera diferente:

* El compilador borra las referencias de *posición de tipo* después de la conversión desde TypeScript, por lo que no tienen impacto en tree-shaking.
* El compilador debe mantener las referencias de *posición de valor* en tiempo de ejecución, lo que **previene** que el componente sea tree-shaken.

En el ejemplo, el compilador retiene el token `LibHeaderComponent` que ocurre en la posición de valor.
Esto previene que el componente referenciado sea tree-shaken, incluso si la aplicación no usa realmente `<lib-header>` en ningún lugar.
Si el código, plantilla y estilos de `LibHeaderComponent` se combinan para volverse demasiado grandes, incluirlo innecesariamente puede aumentar significativamente el tamaño de la aplicación cliente.

## Cuándo usar el patrón de token de inyección ligero

El problema de tree-shaking surge cuando un componente se usa como un token de inyección.
Hay dos casos cuando eso puede suceder:

* El token se usa en la posición de valor de una [consulta de contenido](guide/components/queries#content-queries).
* El token se usa como un especificador de tipo para inyección de constructor.

En el siguiente ejemplo, ambos usos del token `OtherComponent` causan retención de `OtherComponent`, previniendo que sea tree-shaken cuando no se usa:

```typescript
class MyComponent {
  constructor(@Optional() other: OtherComponent) {}

@ContentChild(OtherComponent) other: OtherComponent|null;
}
```
Aunque los tokens usados solo como especificadores de tipo se eliminan cuando se convierten a JavaScript, todos los tokens usados para inyección de dependencias se necesitan en tiempo de ejecución.
Estos efectivamente cambian `constructor(@Optional() other: OtherComponent)` a `constructor(@Optional() @Inject(OtherComponent) other)`.
El token ahora está en una posición de valor, lo que causa que el tree-shaker mantenga la referencia.

ÚTIL: Las librerías deberían usar [proveedores tree-shakable](guide/di/dependency-injection#providing-dependency) para todos los servicios, proporcionando dependencias a nivel raíz en lugar de en componentes o módulos.

## Usando tokens de inyección ligeros

El patrón de diseño de token de inyección ligero consiste en usar una pequeña clase abstracta como un token de inyección, y proporcionar la implementación real en una etapa posterior.
La clase abstracta se retiene, no es tree-shaken, pero es pequeña y no tiene un impacto material en el tamaño de la aplicación.

El siguiente ejemplo muestra cómo esto funciona para el `LibHeaderComponent`:

```typescript
abstract class LibHeaderToken {}

@Component({
  selector: 'lib-header',
  providers: [
    {provide: LibHeaderToken, useExisting: LibHeaderComponent}
  ]
  …,
})
class LibHeaderComponent extends LibHeaderToken {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCardComponent {
  @ContentChild(LibHeaderToken) header: LibHeaderToken|null = null;
}
```
En este ejemplo, la implementación de `LibCardComponent` ya no se refiere a `LibHeaderComponent` ni en la posición de tipo ni en la posición de valor.
Esto permite que ocurra tree-shaking completo de `LibHeaderComponent`.
El `LibHeaderToken` se retiene, pero es solo una declaración de clase, sin implementación concreta.
Es pequeño y no impacta materialmente el tamaño de la aplicación cuando se retiene después de la compilación.

En su lugar, `LibHeaderComponent` mismo implementa la clase abstracta `LibHeaderToken`.
Puedes usar de forma segura ese token como el proveedor en la definición del componente, permitiendo que Angular inyecte correctamente el tipo concreto.

Para resumir, el patrón de token de inyección ligero consiste en lo siguiente:

1. Un token de inyección ligero que se representa como una clase abstracta.
1. Una definición de componente que implementa la clase abstracta.
1. Inyección del patrón ligero, usando `@ContentChild()` o `@ContentChildren()`.
1. Un proveedor en la implementación del token de inyección ligero que asocia el token de inyección ligero con la implementación.

### Usar el token de inyección ligero para definición de API

Un componente que inyecta un token de inyección ligero podría necesitar invocar un método en la clase inyectada.
El token ahora es una clase abstracta. Como el componente inyectable implementa esa clase, también debes declarar un método abstracto en la clase abstracta del token de inyección ligero.
La implementación del método, con toda su sobrecarga de código, reside en el componente inyectable que puede ser tree-shaken.
Esto permite que el padre se comunique con el hijo, si está presente, de una manera type-safe.

Por ejemplo, el `LibCardComponent` ahora consulta `LibHeaderToken` en lugar de `LibHeaderComponent`.
El siguiente ejemplo muestra cómo el patrón permite que `LibCardComponent` se comunique con el `LibHeaderComponent` sin referirse realmente a `LibHeaderComponent`:

```typescript
abstract class LibHeaderToken {
  abstract doSomething(): void;
}

@Component({
  selector: 'lib-header',
  providers: [
    {provide: LibHeaderToken, useExisting: LibHeaderComponent}
  ]
  …,
})
class LibHeaderComponent extends LibHeaderToken {
  doSomething(): void {
    // Implementación concreta de `doSomething`
  }
}

@Component({
  selector: 'lib-card',
  …,
})
class LibCardComponent implement AfterContentInit {
  @ContentChild(LibHeaderToken) header: LibHeaderToken|null = null;

ngAfterContentInit(): void {
    if (this.header !== null) {
      this.header?.doSomething();
    }
  }
}
```
En este ejemplo, el padre consulta el token para obtener el componente hijo, y almacena la referencia del componente resultante si está presente.
Antes de llamar un método en el hijo, el componente padre verifica si el componente hijo está presente.
Si el componente hijo ha sido tree-shaken, no hay referencia en tiempo de ejecución a él, y no hay llamada a su método.

### Nombrar tu token de inyección ligero

Los tokens de inyección ligeros solo son útiles con componentes.
La guía de estilo de Angular sugiere que nombres los componentes usando el sufijo "Component".
El ejemplo "LibHeaderComponent" sigue esta convención.

Deberías mantener la relación entre el componente y su token mientras aún los distingues.
El estilo recomendado es usar el nombre base del componente con el sufijo "`Token`" para nombrar tus tokens de inyección ligeros: "`LibHeaderToken`."
# RxJS interop with Angular signals

The `@angular/core/rxjs-interop` package offers APIs that help you integrate RxJS and Angular signals.

## Create a signal from an RxJs Observable with `toSignal`

Use the `toSignal` function to create a signal which tracks the value of an Observable. It behaves similarly to the `async` pipe in templates, but is more flexible and can be used anywhere in an application.

```ts
import { Component } from '@angular/core';
import { AsyncPipe } from '@angular/common';
import { interval } from 'rxjs';
import { toSignal } from '@angular/core/rxjs-interop';

@Component({
  template: `{{ counter() }}`,
})
export class Ticker {
  counterObservable = interval(1000);

// Get a `Signal` representing the `counterObservable`'s value.
  counter = toSignal(this.counterObservable, {initialValue: 0});
}
```

Like the `async` pipe, `toSignal` subscribes to the Observable immediately, which may trigger side effects. The subscription created by `toSignal` automatically unsubscribes from the given Observable when the component or service which calls `toSignal` is destroyed.

IMPORTANT: `toSignal` creates a subscription. You should avoid calling it repeatedly for the same Observable, and instead reuse the signal it returns.

### Injection context

`toSignal` by default needs to run in an [injection context](guide/di/dependency-injection-context), such as during construction of a component or service. If an injection context is not available, you can manually specify the `Injector` to use instead.

### Initial values

Observables may not produce a value synchronously on subscription, but signals always require a current value. There are several ways to deal with this "initial" value of `toSignal` signals.

#### The `initialValue` option

As in the example above, you can specify an `initialValue` option with the value the signal should return before the Observable emits for the first time.

#### `undefined` initial values

If you don't provide an `initialValue`, the resulting signal will return `undefined` until the Observable emits. This is similar to the `async` pipe's behavior of returning `null`.

#### The `requireSync` option

Some Observables are guaranteed to emit synchronously, such as `BehaviorSubject`. In those cases, you can specify the `requireSync: true` option.

When `requiredSync` is `true`, `toSignal` enforces that the Observable emits synchronously on subscription. This guarantees that the signal always has a value, and no `undefined` type or initial value is required.

### `manualCleanup`

By default, `toSignal` automatically unsubscribes from the Observable when the component or service that creates it is destroyed.

To override this behavior, you can pass the `manualCleanup` option. You can use this setting for Observables that complete themselves naturally.

### Error and Completion

If an Observable used in `toSignal` produces an error, that error is thrown when the signal is read.

If an Observable used in `toSignal` completes, the signal continues to return the most recently emitted value before completion.

## Create an RxJS Observable from a signal with `toObservable`

Use the `toObservable` utility to create an `Observable` which tracks the value of a signal. The signal's value is monitored with an `effect` which emits the value to the Observable when it changes.

```ts
import { Component, signal } from '@angular/core';
import { toObservable } from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class SearchResults {
  query: Signal<string> = inject(QueryService).query;
  query$ = toObservable(this.query);

results$ = this.query$.pipe(
    switchMap(query => this.http.get('/search?q=' + query ))
  );
}
```

As the `query` signal changes, the `query$` Observable emits the latest query and triggers a new HTTP request.

### Injection context

`toObservable` by default needs to run in an [injection context](guide/di/dependency-injection-context), such as during construction of a component or service. If an injection context is not available, you can manually specify the `Injector` to use instead.

### Timing of `toObservable`

`toObservable` uses an effect to track the value of the signal in a `ReplaySubject`. On subscription, the first value (if available) may be emitted synchronously, and all subsequent values will be asynchronous.

Unlike Observables, signals never provide a synchronous notification of changes. Even if you update a signal's value multiple times, `toObservable` will only emit the value after the signal stabilizes.

```ts
const obs$ = toObservable(mySignal);
obs$.subscribe(value => console.log(value));

mySignal.set(1);
mySignal.set(2);
mySignal.set(3);
```

Here, only the last value (3) will be logged.

## Using `rxResource` for async data

IMPORTANT: `rxResource` is [experimental](reference/releases#experimental). It's ready for you to try, but it might change before it is stable.

Angular's [`resource` function](/guide/signals/resource) gives you a way to incorporate async data into your application's signal-based code. Building on top of this pattern, `rxResource` lets you define a resource where the source of your data is defined in terms of an RxJS `Observable`. Instead of accepting a `loader` function, `rxResource` accepts a `stream` function that accepts an RxJS `Observable`.

```typescript
import {Component, inject} from '@angular/core';
import {rxResource} from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class UserProfile {
  // This component relies on a service that exposes data through an RxJS Observable.
  private userData = inject(MyUserDataClient);

protected userId = input<string>();

private userResource = rxResource({
    params: () => this.userId(),

// The `stream` property expects a factory function that returns
    // a data stream as an RxJS Observable.
    stream: ({params}) => this.userData.load(params.userId),
  });
}
```

The `stream` property accepts a factory function for an RxJS `Observable`. This factory function is passed the resource's `params` value and returns an `Observable`. The resource calls this factory function every time the `params` computation produces a new value. See [Resource loaders](/guide/signals/resource#resource-loaders) for more details on the parameters passed to the factory function.

In all other ways, `rxResource` behaves like and provides the same APIs as `resource` for specifying parameters, reading values, checking loading state, and examining errors.
# RxJS interop with component and directive outputs

TIP: This guide assumes you're familiar with [component and directive outputs](guide/components/outputs).

The `@angular/rxjs-interop` package offers two APIs related to component and directive outputs.

## Creating an output based on an RxJs Observable

The `outputFromObservable` lets you create a component or directive output that emits based on an RxJS observable:

```ts
import {Directive} from '@angular/core';
import {outputFromObservable} from '@angular/core/rxjs-interop';

@Directive({/*...*/})
class Draggable {
  pointerMoves$: Observable<PointerMovements> = listenToPointerMoves();
  
  // Whenever `pointerMoves$` emits, the `pointerMove` event fires.
  pointerMove = outputFromObservable(this.pointerMoves$);
}
```
The `outputFromObservable` function has special meaning to the Angular compiler. **You may only call `outputFromObservable` in component and directive property initializers.**

When you `subscribe` to the output, Angular automatically forwards the subscription to the underlying observable. Angular stops forwarding values when the component or directive is destroyed.

HELPFUL: Consider using `output()` directly if you can emit values imperatively.

## Creating an RxJS Observable from a component or directive output

The `outputToObservable` function lets you create an RxJS observable from a component output.

```ts
import {outputToObservable} from '@angular/core/rxjs-interop';

@Component(/*...*/)
class CustomSlider {
  valueChange = output<number>();
}

// Instance reference to `CustomSlider`.
const slider: CustomSlider = createSlider();

outputToObservable(slider.valueChange) // Observable<number>
  .pipe(...)
  .subscribe(...);
```
HELPFUL: Consider using the `subscribe` method on `OutputRef` directly if it meets your needs.
# Configurando `HttpClient`

Antes de poder usar `HttpClient` en tu aplicación, debes configurarlo usando [inyección de dependencias](guide/di).

## Proporcionando `HttpClient` a través de inyección de dependencias

`HttpClient` se proporciona usando la función auxiliar `provideHttpClient`, que la mayoría de aplicaciones incluyen en los `providers` de la aplicación en `app.config.ts`.

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
  ]
};
```
Si tu aplicación usa el método de inicialización basado en NgModule, puedes incluir `provideHttpClient` en los providers del NgModule de tu aplicación:

```ts
@NgModule({
  providers: [
    provideHttpClient(),
  ],
  // ... otra configuración de la aplicación
})
export class AppModule {}
```
Luego puedes inyectar el servicio `HttpClient` como una dependencia de tus componentes, servicios u otras clases:

```ts
@Injectable({providedIn: 'root'})
export class ConfigService {
  private http = inject(HttpClient);
  // Este servicio ahora puede hacer solicitudes HTTP a través de `this.http`.
}
```
## Configurando características `HttpClient`

`provideHttpClient` acepta una lista de configuraciones de características opcionales, para habilitar o configurar el comportamiento de diferentes aspectos del cliente. Esta sección detalla las características opcionales y sus usos.

### `withFetch`

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withFetch(),
    ),
  ]
};
```
Por defecto, `HttpClient` usa la API [`XMLHttpRequest`](https://developer.mozilla.org/es/docs/Web/API/XMLHttpRequest) para hacer solicitudes. La característica `withFetch` cambia el cliente para usar la API [`fetch`](https://developer.mozilla.org/es/docs/Web/API/Fetch_API) en su lugar.

`fetch` es una API más moderna y está disponible en algunos entornos donde `XMLHttpRequest` no es compatible. Tiene algunas limitaciones, como no producir eventos de progreso de carga.

### `withInterceptors(...)`

`withInterceptors` configura el conjunto de funciones interceptor que procesarán las solicitudes realizadas a través de `HttpClient`. Consulta la [guía de interceptores](guide/http/interceptors) para más información.

### `withInterceptorsFromDi()`

`withInterceptorsFromDi` incluye el estilo más antiguo de interceptores basados en clases en la configuración de `HttpClient`. Consulta la [guía de interceptores](guide/http/interceptors) para más información.

ÚTIL: Los interceptores funcionales (a través de `withInterceptors`) tienen un orden más predecible y los recomendamos sobre los interceptores basados en DI.

### `withRequestsMadeViaParent()`

Por defecto, cuando configuras `HttpClient` usando `provideHttpClient` dentro de un inyector dado, esta configuración sobrescribe cualquier configuración para `HttpClient` que pueda estar presente en el inyector padre.

Al agregar `withRequestsMadeViaParent()`, `HttpClient` se configura para pasar las solicitudes al `HttpClient` del inyector padre, una vez que han pasado por cualquier interceptor configurado en este nivel. Esto es útil si deseas _añadir_ interceptores en un inyector hijo, pero enviando la solicitud también a través de los interceptores del inyector padre.

CRÍTICO: Debes configurar una instancia de `HttpClient` en un inyector superior al actual, de lo contrario esta opción no será válida y obtendrás un error en tiempo de ejecución.

### `withJsonpSupport()`

Incluir `withJsonpSupport` habilita el método `.jsonp()` en `HttpClient`, que realiza una solicitud GET a través de la [convención JSONP](https://es.wikipedia.org/wiki/JSONP) para la carga de datos entre dominios.

ÚTIL: Simpre que sea posible, prefiere usar [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) para hacer solicitudes entre dominios en lugar de JSONP.

### `withXsrfConfiguration(...)`

Incluir esta opción permite la personalización de la funcionalidad de seguridad XSRF integrada de `HttpClient`. Consulta la [guía de seguridad](best-practices/security) para más información.

### `withNoXsrfProtection()`

Incluir esta opción deshabilita la funcionalidad de seguridad XSRF integrada de `HttpClient`. Consulta la [guía de seguridad](best-practices/security) para más información.

## Configuración basada en `HttpClientModule`

Algunas aplicaciones pueden configurar `HttpClient` usando la API más antigua basada en NgModules.

Esta tabla muestra los NgModules disponibles en `@angular/common/http` y cómo se relacionan con las funciones de configuración de proveedores anteriores.

| **NgModule**                            | `provideHttpClient()` Equivalente              |
| --------------------------------------- | --------------------------------------------- |
| `HttpClientModule`                      | `provideHttpClient(withInterceptorsFromDi())` |
| `HttpClientJsonpModule`                 | `withJsonpSupport()`                          |
| `HttpClientXsrfModule.withOptions(...)` | `withXsrfConfiguration(...)`                  |
| `HttpClientXsrfModule.disable()`        | `withNoXsrfProtection()`                      |
Cuando `HttpClientModule` está presente en múltiples inyectores, el comportamiento de los interceptores está mal definido y depende de las opciones exactas y el orden de providers/imports.

Se recomienda usar `provideHttpClient` para configuraciones con múltiples inyectores, ya que ofrece un comportamiento más estable. Consulta la característica anterior `withRequestsMadeViaParent`.

# Realizando solicitudes HTTP

`HttpClient` tiene métodos correspondientes a los diferentes verbos HTTP utilizados para hacer solicitudes, tanto para cargar datos como para aplicar mutaciones en el servidor. Cada método devuelve un [RxJS `Observable`](https://rxjs.dev/guide/observable) que, al sucribirse se suscribe, envía la solicitud y luego emite los resultados cuando el servidor responde.

NOTA: Los `Observable`s creados por `HttpClient` pueden suscribirse cualquier número de veces y harán una nueva solicitud al backend por cada suscripción.

A través de un objeto de opciones pasado al método de solicitud, se pueden ajustar varias propiedades de la solicitud y del tipo de respuesta devuelta.

## Obteniendo datos JSON

Obtener datos de un backend con frecuencia requiere hacer una solicitud GET usando el método [`HttpClient.get()`](api/common/http/HttpClient#get). Este método toma dos argumentos: la URL del endpoint como string desde donde obtener los datos, y un objeto de *opciones opcionales* para configurar la solicitud.

Por ejemplo, para obtener datos de configuración de una API hipotética usando el método `HttpClient.get()`:

```ts
http.get<Config>('/api/config').subscribe(config => {
  // procesar la configuración.
});
```
Observa el argumento de tipo genérico que especifica que los datos devueltos por el servidor serán de tipo `Config`. Este argumento es opcional, y si lo omites, los datos devueltos tendrán tipo `Object`.

CONSEJO: Cuando trabajes con datos de estructura incierta y valores potencialmente `undefined` o `null`, considera usar el tipo `unknown` en lugar de `Object` como tipo de respuesta.

CRÍTICO: El tipo genérico de los métodos de solicitud es una **afirmación** de tipo sobre los datos devueltos por el servidor. `HttpClient` no verifica que los datos de retorno reales coincidan con este tipo.

## Obteniendo otros tipos de datos

Por defecto, `HttpClient` asume que los servidores devolverán datos JSON. Cuando interactúes con una API que no sea JSON, puedes decirle a `HttpClient` qué tipo de respuesta esperar y devolver al hacer la solicitud. Esto se hace con la opción `responseType`.

Por ejemplo, puedes pedirle al `HttpClient` que descargue los bytes sin procesar de una imagen `.jpeg` en un `ArrayBuffer`:

```ts
http.get('/images/dog.jpg', {responseType: 'arraybuffer'}).subscribe(buffer => {
  console.log('La imagen tiene ' + buffer.byteLength + ' bytes de tamaño');
});
```
Debido a que el valor de `responseType` afecta el tipo devuelto por `HttpClient`, debe tener un tipo literal y no un tipo `string`.

Esto sucede automáticamente si el objeto de opciones pasado al método de solicitud es un objeto literal, pero si estás extrayendo las opciones de solicitud a una variable o método auxiliar, podrías necesitar especificarlo explícitamente como literal, por ejemplo: `responseType: 'text' as const`.
## Modificando el estado del servidor

Las APIs del servidor que realizan mutaciones con frecuencia requieren hacer solicitudes POST con un cuerpo de solicitud que especifique el nuevo estado o el cambio a realizar.

El método [`HttpClient.post()`](api/common/http/HttpClient#post) se comporta de manera similar a `get()`, y acepta un argumento `body` adicional antes de sus opciones:

```ts
http.post<Config>('/api/config', newConfig).subscribe(config => {
  console.log('Configuración actualizada:', config);
});
```
Se pueden proporcionar muchos tipos diferentes de valores como `body` de la solicitud, y `HttpClient` los serializará en consecuencia:

IMPORTANTE: Recuerda hacer `.subscribe()` a los `Observable`s de solicitudes de mutación para realmente ejecutar la solicitud.

## Configurando parámetros de URL parameters

Especifica los parámetros de solicitud que deben incluirse en la URL de la solicitud usando la opción `params`.

Pasar un objeto literal es la forma más simple de configurar parámetros de URL:

```ts
http.get('/api/config', {
  params: {filter: 'all'},
}).subscribe(config => {
  // ...
});
```
Alternativamente, puedes pasar una instancia de `HttpParams` si necesitas más control sobre la construcción o serialización de los parámetros.

IMPORTANTE: Las instancias de `HttpParams` son _inmutables_ y no se pueden cambiar directamente. En su lugar, los métodos de mutación como `append()` devuelven una nueva instancia de `HttpParams` con la mutación aplicada.

```ts
const baseParams = new HttpParams().set('filter', 'all');

http.get('/api/config', {
  params: baseParams.set('details', 'enabled'),
}).subscribe(config => {
  // ...
});
```
Puedes instanciar `HttpParams` con un `HttpParameterCodec` personalizado que determine cómo `HttpClient` codificará los parámetros en la URL.

### Codificación personalizada de parámetros

Por defecto, `HttpParams` utiliza el [`HttpUrlEncodingCodec`](api/common/http/HttpUrlEncodingCodec) incorporado para codificar y decodificar las claves y valores de los parámetros.

Puedes proporcionar tu propia implementación de [`HttpParameterCodec`](api/common/http/HttpParameterCodec) para personalizar cómo se aplica la codificación y decodificación.

```ts
import { HttpClient, HttpParams, HttpParameterCodec } from '@angular/common/http';
import { inject } from '@angular/core';

export class CustomHttpParamEncoder  implements HttpParameterCodec {
  encodeKey(key: string): string   {
     return encodeURIComponent(key); 
  }

encodeValue(value: string): string {
    return encodeURIComponent(value);
  }

decodeKey(key: string): string {
    return decodeURIComponent(key);
  }

decodeValue(value: string): string {
    return decodeURIComponent(value);
  }
}

export class ApiService {
  private http = inject(HttpClient);

search() {
    const params = new HttpParams({
      encoder: new CustomHttpParamEncoder(),
    })
    .set('email', 'dev+alerts@example.com')
    .set('q', 'a & b? c/d = e');

return this.http.get('/api/items', { params });
  }
}
```

## Configurando encabezados de solicitud

Especifica los encabezados de solicitud que deben incluirse en la solicitud usando la opción `headers`.

Pasar un objeto literal es la forma más simple de configurar encabezados de solicitud:

```ts
http.get('/api/config', {
  headers: {
    'X-Debug-Level': 'verbose',
  }
}).subscribe(config => {
  // ...
});
```
Alternativamente, pasa una instancia de `HttpHeaders` si necesitas más control sobre la construcción de encabezados

IMPORTANTE: Las instancias de `HttpHeaders` son _inmutables_ y no se pueden cambiar directamente. En su lugar, los métodos de mutación como `append()` devuelven una nueva instancia de `HttpHeaders` con la mutación aplicada.

```ts
const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http.get<Config>('/api/config', {
  headers: baseHeaders.set('X-Debug-Level', 'verbose'),
}).subscribe(config => {
  // ...
});
```
## Interactuando con los eventos de respuesta del servidor

Por conveniencia, `HttpClient` devuelve por defecto un `Observable` con los datos de la respuesta (el body). A veces es útil examinar la respuesta completa, por ejemplo, para obtener cabeceras específicas.

Para acceder a toda la respuesta, establece la opción `observe` en `'response'`:

```ts
http.get<Config>('/api/config', {observe: 'response'}).subscribe(res => {
  console.log('Estado de respuesta:', res.status);
  console.log('Cuerpo:', res.body);
});
```
Debido a que el valor de `observe` afecta el tipo devuelto por `HttpClient`, debe tener un tipo literal y no un tipo `string`.

Esto sucede automáticamente si el objeto de opciones pasado al método de solicitud es un objeto literal, pero si estás extrayendo las opciones de solicitud a una variable o método auxiliar, podrías necesitar especificarlo explícitamente como literal, por ejemplo: `observe: 'response' as const`.
## Recibiendo eventos de progreso sin procesar

Además del cuerpo de la respuesta o el objeto de respuesta, `HttpClient` también puede devolver una secuencia de _eventos_ sin procesar que corresponden a momentos específicos en el ciclo de vida de la solicitud. Estos eventos incluyen cuando se envía la solicitud, cuando se devuelve el encabezado de respuesta, y cuando el cuerpo está completo. Estos eventos también pueden incluir _eventos de progreso_ que reportan el estado de carga y descarga para cuerpos de solicitud o respuesta grandes.

Los eventos de progreso están deshabilitados por defecto (ya que tienen un costo de rendimiento) pero se pueden habilitar con la opción `reportProgress`.

NOTA: La implementación opcional `fetch` de `HttpClient` no reporta eventos de progreso de _carga_.

Para observar la secuencia de eventos, establece la opción `observe` en `'events'`:

```ts
http.post('/api/upload', myData, {
  reportProgress: true,
  observe: 'events',
}).subscribe(event => {
  switch (event.type) {
    case HttpEventType.UploadProgress:
      console.log('Cargados ' + event.loaded + ' de ' + event.total + ' bytes');
      break;
    case HttpEventType.Response:
      console.log('¡Carga finalizada!');
      break;
  }
});
```
Debido a que el valor de `observe` afecta el tipo devuelto por `HttpClient`, debe tener un tipo literal y no un tipo `string`.

Esto sucede automáticamente si el objeto de opciones pasado al método de solicitud es un objeto literal, pero si estás extrayendo las opciones de solicitud a una variable o método auxiliar, podrías necesitar especificarlo explícitamente como literal, como `observe: 'events' as const`.
Cada `HttpEvent` reportado en la secuencia de eventos tiene un `type` que distingue lo que representa el evento:

## Manejando fallos de solicitud

Hay tres formas en que una solicitud HTTP puede fallar:

* Un error de red o conexión puede impedir que la solicitud llegue al servidor backend.
* Una solicitud no respondió a tiempo cuando se configuró la opción de tiempo de espera (timeout).
* El backend puede recibir la solicitud pero fallar al procesarla, y devolver una respuesta de error.

`HttpClient` captura todos tipos de errores mencionados anteriormente en un `HttpErrorResponse` que devuelve a través del canal de error del `Observable`. Los errores de red tienen un código de `status` de `0` y un `error` que es una instancia de [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent). Los errores del backend tienen el código de `status` fallido devuelto por el backend, y la respuesta de error como `error`. Inspecciona la respuesta para identificar la causa del error y la acción apropiada para manejar el error.

La [librería RxJS](https://rxjs.dev/) ofrece varios operadores que pueden ser útiles para el manejo de errores.

Puedes usar el operador `catchError` para transformar una respuesta de error en un valor para la UI. Este valor puede decirle a la UI que muestre una página o valor de error, y capturar la causa del error si es necesario.

A veces, errores transitorios como interrupciones de red pueden hacer que una solicitud falle inesperadamente, y simplemente reintentar la solicitud permitirá que tenga éxito. RxJS proporciona varios operadores de *reintento* que automáticamente se re-suscriben a un `Observable` fallido bajo ciertas condiciones. Por ejemplo, el operador `retry()` automáticamente intentará re-suscribirse un número especificado de veces.

### Tiempos de esperar (Timeouts)

Para establecer un tiempo de espera para una solicitud, puedes configurar la opción `timeout` con un número de milisegundos junto con otras opciones de la solicitud. Si la solicitud al backend no se completa dentro del tiempo especificado, la solicitud se abortará y se emitirá un error.

NOTA: El timeout solo se aplica a la solicitud HTTP al backend en sí. No es un tiempo de espera para toda la cadena de manejo de la solicitud. Por lo tanto, esta opción no se ve afectada por ningún retraso introducido por los interceptores.

```ts
http.get('/api/config', {
  timeout: 3000,
}).subscribe({
  next: config => {
    console.log('Configuración obtenida con éxito:', config);
  },
  error: err => {
    // Si la solicitud supera el tiempo de espera, se habrá emitido un error.
  }
});
```
## Opciones avanzadas de Fetch

Al usar el proveedor `withFetch()`, el `HttpClient` de Angular proporciona acceso a opciones avanzadas de la API Fetch que pueden mejorar el rendimiento y la experiencia del usuario. Estas opciones solo están disponibles cuando se utiliza el backend Fetch.

### Opciones de Fetch

Las siguientes opciones permiten un control detallado sobre el comportamiento de la solicitud al usar el backend Fetch.

#### Conexiones Keep-alive

La opción `keepalive` permite que una solicitud continúe incluso si la página que la inició se cierra. Esto es útil para solicitudes de analíticas o registro que deben completarse aunque el usuario navegue fuera de la página.

```ts
http.post('/api/analytics', analyticsData, {
  keepalive: true
}).subscribe();
```
#### Control de caché HTTP

La opción `cache` controla cómo interactúa la solicitud con la caché HTTP del navegador, lo que puede mejorar significativamente el rendimiento en solicitudes repetidas.

```ts
// Usar respuesta en caché sin importar su antigüedad
http.get('/api/config', {
  cache: 'force-cache'
}).subscribe(config => {
  // ...
});

// Siempre obtener del network, ignorando la caché
http.get('/api/live-data', {
  cache: 'no-cache'
}).subscribe(data => {
  // ...
});

// Usar solo la respuesta en caché, falla si no está en caché
http.get('/api/static-data', {
  cache: 'only-if-cached'
}).subscribe(data => {
  // ...
});
```
#### Prioridad de solicitud para Core Web Vitals

La opción `priority` permite indicar la importancia relativa de una solicitud, ayudando a los navegadores a optimizar la carga de recursos para mejorar los Core Web Vitals.

```ts
// Alta prioridad para recursos críticos
http.get('/api/user-profile', {
  priority: 'high'
}).subscribe(profile => {
  // ...
});

// Baja prioridad para recursos no críticos
http.get('/api/recommendations', {
  priority: 'low'
}).subscribe(recommendations => {
  // ...
});

// Prioridad automática (por defecto), el navegador decide
http.get('/api/settings', {
  priority: 'auto'
}).subscribe(settings => {
  // ...
});
```
Valores disponibles para `priority`:
- `'high'`: Prioridad alta, se carga pronto (por ejemplo, datos críticos del usuario, contenido que se ve sin hacer scroll)
- `'low'`: Prioridad baja, se carga cuando los recursos están disponibles (por ejemplo, análisis, datos de precarga)
- `'auto'`: El navegador determina la prioridad basándose en el contexto de la solicitud (valor por defecto)

TIP: Usa `priority: 'high'` para solicitudes que afectan Largest Contentful Paint (LCP) y `priority: 'low'` para solicitudes que no impactan la experiencia inicial del usuario.

#### Modo de solicitud

La opción `mode` controla cómo se manejan las solicitudes cross-origin y determina el tipo de respuesta.

```ts
// Solo solicitudes same-origin
http.get('/api/local-data', {
  mode: 'same-origin'
}).subscribe(data => {
  // ...
});

// Solicitudes CORS habilitadas cross-origin
http.get('https://api.external.com/data', {
  mode: 'cors'
}).subscribe(data => {
  // ...
});

// Modo no-CORS para solicitudes simples cross-origin
http.get('https://external-api.com/public-data', {
  mode: 'no-cors'
}).subscribe(data => {
  // ...
});
```
Valores disponibles para `mode`:
- `'same-origin'`: Solo permite solicitudes same-origin, falla si es cross-origin
- `'cors'`: Permite solicitudes cross-origin con CORS (por defecto)
- `'no-cors'`: Permite solicitudes simples cross-origin sin CORS, la respuesta es opaca

TIP: Usa `mode: 'same-origin'` para solicitudes sensibles que nunca deberían ser cross-origin.

#### Manejo de redirecciones

La opción `redirect` especifica cómo manejar respuestas de redirección del servidor.

```ts
// Seguir redirecciones automáticamente (comportamiento por defecto)
http.get('/api/resource', {
  redirect: 'follow'
}).subscribe(data => {
  // ...
});

// Prevenir redirecciones automáticas
http.get('/api/resource', {
  redirect: 'manual'
}).subscribe(response => {
  // Manejar la redirección manualmente
});

// Tratar redirecciones como errores
http.get('/api/resource', {
  redirect: 'error'
}).subscribe({
  next: data => {
    // Respuesta exitosa
  },
  error: err => {
    // Las redirecciones activarán este manejador de errores
  }
});
```
Valores disponibles para `redirect`:
- `'follow'`: Seguir redirecciones automáticamente (por defecto)
- `'error'`: Tratar redirecciones como errores
- `'manual'`: No seguir redirecciones automáticamente, devolver la respuesta de redirección

TIP: Usa `redirect: 'manual'` cuando necesites manejar redirecciones con lógica personalizada.

#### Manejo de credenciales

La opción `credentials` controla si se envían cookies, encabezados de autorización y otras credenciales en solicitudes cross-origin. Esto es importante para escenarios de autenticación.

```ts
// Incluir credenciales en solicitudes cross-origin
http.get('https://api.example.com/protected-data', {
  credentials: 'include'
}).subscribe(data => {
  // ...
});

// Nunca enviar credenciales (por defecto en cross-origin)
http.get('https://api.example.com/public-data', {
  credentials: 'omit'
}).subscribe(data => {
  // ...
});

// Enviar credenciales solo para solicitudes same-origin
http.get('/api/user-data', {
  credentials: 'same-origin'
}).subscribe(data => {
  // ...
});

// withCredentials sobrescribe la opción credentials
http.get('https://api.example.com/data', {
  credentials: 'omit',        // Será ignorado
  withCredentials: true       // Fuerza credentials: 'include'
}).subscribe(data => {
  // La solicitud incluirá credenciales aunque credentials sea 'omit'
});

// Enfoque legado (todavía soportado)
http.get('https://api.example.com/data', {
  withCredentials: true
}).subscribe(data => {
  // Equivalente a credentials: 'include'
});
```
IMPORTANTE: La opción `withCredentials` tiene prioridad sobre `credentials`. Si se especifican ambas, `withCredentials: tru`e` siempre resultará en `credentials: 'include'`, sin importar el valor explícito de `credentials`.

Valores disponivles para `credentials`:
- `'omit'`: Nunca enviar credenciales
- `'same-origin'`: Enviar credenciales solo para solicitudes same-origin (por defecto)
- `'include'`: Siempre enviar credenciales, incluso en solicitudes cross-origin

TIP: Usa `credentials: 'include'` cuando necesites enviar cookies o encabezados de autenticación a un dominio diferente que soporte CORS. Evita mezclar `credentials` y `withCredentials` para no generar confusión.

#### Referente (Referrer)

La opción `referrer` permite controlar qué información de referencia se envía con la solicitud, importante por motivos de privacidad y seguridad.

```ts
// Enviar una URL específica como referrer
http.get('/api/data', {
  referrer: 'https://example.com/page'
}).subscribe(data => {
  // ...
});

// Usar la página actual como referrer (por defecto)
http.get('/api/analytics', {
  referrer: 'about:client'
}).subscribe(data => {
  // ...
});
```
La opción `referrer` acepta:
- Una cadena de URL válida: establece la URL de referrer a enviar
- Una cadena vacía `''`: No envía información de referrer
- `'about:client'`: Utiliza el referente referrer (la URL de la página actual).

TIP: Usa `referrer: ''` para solicitudes sensibles donde no quieres filtrar la URL de la página que refirió la solicitud.

#### Integridad (Integrity)

La opción `integrity` permite verificar que la respuesta no ha sido alterada, proporcionando un hash criptográfico del contenido esperado. Esto es útil al cargar scripts u otros recursos desde CDNs.

```ts
// Verificar integridad de la respuesta con hash SHA-256
http.get('/api/script.js', {
  integrity: 'sha256-ABC123...',
  responseType: 'text'
}).subscribe(script => {
  // El contenido del script se verifica contra el hash
});
```
IMPORTANTE: La opción `integrity` requiere una coincidencia exacta entre el contenido de la respuesta y el hash proporcionado. Si el contenido no coincide, la solicitud fallará con un error de red.

TIP: Usa integridad de subrecursos (subresource integrity) al cargar recursos críticos de fuentes externas para asegurar que no han sido modificados. Genera los hashes usando herramientas como `openssl`

## `Observable`s Http

Cada método de solicitud en `HttpClient` construye y devuelve un `Observable` del tipo de respuesta solicitado. Entender cómo funcionan estos `Observable`s es importante al usar `HttpClient`.

`HttpClient` produce lo que RxJS llama `Observable`s "fríos", lo que significa que no ocurre ninguna solicitud real hasta que se suscribe al `Observable`. Solo entonces se envía realmente la solicitud al servidor. Suscribirse al mismo `Observable` múltiples veces activará múltiples solicitudes al backend. Cada suscripción es independiente.

CONSEJO: Puedes pensar en los `Observable`s de `HttpClient` como _planos_ para solicitudes reales del servidor.

Una vez suscrito, cancelar la suscripción abortará la solicitud en progreso. Esto es muy útil si el `Observable` se suscribe a través del pipe `async`, ya que automáticamente cancelará la solicitud si el usuario navega fuera de la página actual. Además, si usas el `Observable` con un combinador RxJS como `switchMap`, esta cancelación limpiará cualquier solicitud obsoleta.

Una vez que la respuesta regresa, los `Observable`s de `HttpClient` usualmente se completan (aunque los interceptores pueden influir en esto).

Debido a la finalización automática, generalmente no hay riesgo de fugas de memoria si las suscripciones de `HttpClient` no se limpian. Sin embargo, como con cualquier operación asíncrona, recomendamos encarecidamente que limpies las suscripciones cuando el componente que las usa se destruya, ya que el callback de suscripción podría ejecutarse y encontrar errores cuando intente interactuar con el componente destruido.

CONSEJO: Usar el pipe `async` o la operación `toSignal` para suscribirse a `Observable`s asegura que las suscripciones se eliminen correctamente.

## Mejores prácticas

Aunque `HttpClient` puede ser inyectado y usado directamente desde los componentes, generalmente se recomienda que crees servicios reutilizables e inyectables que aíslen y encapsulen la lógica de acceso a datos. Por ejemplo, este `UserService` encapsula la lógica para solicitar datos de un usuario por su id:

```ts
@Injectable({providedIn: 'root'})
export class UserService {
  private http = inject(HttpClient);

getUser(id: string): Observable<User> {
    return this.http.get<User>(`/api/user/${id}`);
  }
}
```
Dentro de un componente, puedes combinar `@if` con el `async` pipe para renderizar la interfaz de usuario para los datos solo después de que hayan terminado de cargarse:

```ts
import { AsyncPipe } from '@angular/common';
@Component({
  imports: [AsyncPipe],
  template: `
    @if (user$ | async; as user) {
      <p>Nombre: {{ user.name }}</p>
      <p>Biografía: {{ user.biography }}</p>
    }
  `,
})
export class UserProfileComponent {
  userId = input.required<string>();
  user$!: Observable<User>;

private userService = inject(UserService);

constructor(): void {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```

# Interceptores

`HttpClient` soporta una forma de middleware conocida como _interceptores_.

RESUMEN: Los interceptores son middleware que permiten abstraer patrones comunes como reintentos, caché, registro de actividad y autenticación, evitando que cada solicitud individual tenga que manejar estos casos por separado.

`HttpClient` soporta dos tipos de interceptores: funcionales y basados en DI. Nuestra recomendación es usar interceptores funcionales porque tienen un comportamiento más predecible, especialmente en configuraciones complejas. Nuestros ejemplos en esta guía usan interceptores funcionales, y cubrimos los [interceptores basados en DI](#interceptores-basados-en-di) en su propia sección al final.

## Interceptores

Los interceptores son generalmente funciones que puedes ejecutar para cada solicitud, y tienen amplias capacidades para afectar el contenido y el flujo general de las solicitudes y respuestas. Puedes instalar múltiples interceptores, que forman una cadena de interceptores donde cada interceptor procesa la solicitud o respuesta antes de reenviarla al siguiente interceptor en la cadena.

Puedes usar interceptores para implementar una variedad de patrones comunes, como:

* Agregar encabezados de autenticación a las solicitudes salientes a una API particular.
* Reintentar solicitudes fallidas con retroceso exponencial.
* Almacenar en caché las respuestas por un período de tiempo, o hasta que sean invalidadas por mutaciones.
* Personalizar el análisis de las respuestas.
* Medir los tiempos de respuesta del servidor y registrarlos.
* Controlar elementos de la UI como un indicador de carga mientras las operaciones de red están en progreso.
* Recopilar y agrupar solicitudes realizadas dentro de un marco de tiempo determinado.
* Fallar automáticamente las solicitudes después de una fecha límite o tiempo de espera configurable.
* Consultar periódicamente el servidor y actualizar los resultados.

## Definiendo un interceptor

La forma básica de un interceptor es una función que recibe la `HttpRequest` saliente y una función `next` que representa el siguiente paso de procesamiento en la cadena de interceptores.

Por ejemplo, este `loggingInterceptor` registrará la URL de la solicitud saliente en `console.log` antes de reenviar la solicitud:

```ts
export function loggingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  console.log(req.url);
  return next(req);
}
```
Para que este interceptor realmente intercepte las solicitudes, debes configurar `HttpClient` para usarlo.

## Configurando interceptores

Declaras el conjunto de interceptores a usar al configurar `HttpClient` a través de inyección de dependencias, usando la característica `withInterceptors`:

```ts
bootstrapApplication(AppComponent, {providers: [
  provideHttpClient(
    withInterceptors([loggingInterceptor, cachingInterceptor]),
  )
]});
```
Los interceptores que configuras se encadenan juntos en el orden que los has listado en los providers. En el ejemplo anterior, el `loggingInterceptor` procesaría la solicitud y luego la reenviaría al `cachingInterceptor`.

### Interceptando evento de respuesta

Un interceptor puede transformar la secuencia `Observable` de `HttpEvent`s devuelta por `next` para acceder o manipular la respuesta. Debido a que esta secuencia incluye todos los eventos de respuesta, inspeccionar el `.type` de cada evento puede ser necesario para identificar el objeto de respuesta final.

```ts
export function loggingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  return next(req).pipe(tap(event => {
    if (event.type === HttpEventType.Response) {
      console.log(req.url, 'devolvió una respuesta con estado', event.status);
    }
  }));
}
```
CONSEJO: Los interceptores naturalmente asocian las respuestas con sus solicitudes salientes, porque transforman el flujo de respuesta en una función de cierre (closure) que captura el objeto de solicitud.

## Modificando requests

La mayoría de los aspectos de las instancias `HttpRequest` y `HttpResponse` son _inmutables_, y los interceptores no pueden modificarlos directamente. En su lugar, los interceptores aplican mutaciones clonando estos objetos usando la operación `.clone()`, y especificando qué propiedades deben mutarse en la nueva instancia. Esto puede involucrar realizar actualizaciones inmutables en el valor mismo (como `HttpHeaders` o `HttpParams`).

Por ejemplo, para agregar un encabezado a una solicitud:

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```
Esta inmutabilidad permite que la mayoría de los interceptores sean idempotentes si la misma `HttpRequest` se envía a la cadena de interceptores múltiples veces. Esto puede suceder por algunas razones, incluyendo cuando una solicitud se reintenta después de fallar.

CRÍTICO: El cuerpo de una solicitud o respuesta **no** está protegido de mutaciones profundas. Si un interceptor debe mutar el cuerpo, ten cuidado de manejar la ejecución múltiples veces en la misma solicitud.

## Inyección de dependencias en interceptores

Los interceptores se ejecutan en el _contexto de inyección_ del inyector que los registró, y pueden usar la API `inject` de Angular para recuperar dependencias.

Por ejemplo, supongamos que una aplicación tiene un servicio llamado `AuthService`, que crea tokens de autenticación para las solicitudes salientes. Un interceptor puede inyectar y usar este servicio:

```ts
export function authInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn) {
  // Inject the current `AuthService` and use it to get an authentication token:
  const authToken = inject(AuthService).getAuthToken();

// Clone the request to add the authentication header.
  const newReq = req.clone({
    headers: req.headers.append('X-Authentication-Token', authToken),
  });
  return next(newReq);
}
```
## Metada de solicitudes y respuestas

Con frecuencia es útil incluir información en una solicitud que no se envía al backend, pero está específicamente destinada para los interceptores. Las `HttpRequest`s tienen un objeto `.context` que almacena este tipo de metadatos como una instancia de `HttpContext`. Este objeto funciona como un mapa tipado, con claves de tipo `HttpContextToken`.

Para ilustrar cómo funciona este sistema, usemos metadatos para controlar si un interceptor de caché está habilitado para una solicitud determinada.

### Definiendo tokens de contexto

Para almacenar si el interceptor de caché debe almacenar en caché una solicitud particular en el mapa `.context` de esa solicitud, define un nuevo `HttpContextToken` para actuar como clave:

```ts
export const CACHING_ENABLED = new HttpContextToken<boolean>(() => true);
```
La función proporcionada crea el valor por defecto para el token para las solicitudes que no han establecido explícitamente un valor para él. Usar una función asegura que si el valor del token es un objeto o array, cada solicitud obtiene su propia instancia.

### Leyendo el token en un interceptor

Un interceptor puede entonces leer el token y elegir aplicar lógica de caché o no basándose en su valor:

```ts
export function cachingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  if (req.context.get(CACHING_ENABLED)) {
    // aplicar lógica de caché
    return ...;
  } else {
    // el caché ha sido deshabilitado para esta solicitud
    return next(req);
  }
}
```
### Configurando tokens de contexto al hacer una solicitud

Al hacer una solicitud a través de la API `HttpClient`, puedes proporcionar valores para `HttpContextToken`s:

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```
Los interceptores pueden leer estos valores del `HttpContext` de la solicitud.

### El contexto de la solicitud es mutable

A diferencia de otras propiedades de `HttpRequest`s, el `HttpContext` asociado es _mutable_. Si un interceptor cambia el contexto de una solicitud que luego se reintenta, el mismo interceptor observará la mutación del contexto cuando se ejecute nuevamente. Esto es útil para pasar estado a través de múltiples reintentos si es necesario.

## Respuestas sintéticas

La mayoría de los interceptores simplemente invocarán el manejador `next` mientras transforman la solicitud o la respuesta, pero esto no es estrictamente un requisito. Esta sección discute varias de las formas en que un interceptor puede incorporar comportamiento más avanzado.

Los interceptores no están obligados a invocar `next`. Pueden elegir construir respuestas a través de algún otro mecanismo, como desde un caché o enviando la solicitud a través de un mecanismo alternativo.

Construir una respuesta es posible usando el constructor `HttpResponse`:

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```
## Trabajando con información de redirección

Cuando se usa `HttpClient` con el proveedor `withFetch`, las respuestas incluyen una propiedad `redirected` que indica si la respuesta fue resultado de una redirección. Esta propiedad está alineada con la especificación nativa de la API Fetch y puede ser útil en interceptores para manejar escenarios de redirección.

Un interceptor puede acceder y actuar en base a la información de redirección:

```ts
export function redirectTrackingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  return next(req).pipe(tap(event => {
    if (event.type === HttpEventType.Response && event.redirected) {
      console.log('La solicitud a', req.url, 'fue redirigida a', event.url);
      // Manejar la lógica de redirección - por ejemplo actualizar analíticas, verificaciones de seguridad, etc.
    }
  }));
}
```
También puedes usar la información de redirección para implementar lógica condicional en tus interceptores:

```ts
export function authRedirectInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  return next(req).pipe(tap(event => {
    if (event.type === HttpEventType.Response && event.redirected) {
      // Verificar si fuimos redirigidos a una página de inicio de sesión
      if (event.url?.includes('/login')) {
        // Manejar la redirección de autenticación
        handleAuthRedirect();
      }
    }
  }));
}
```
## Interceptores basados en DI (Inyección de Dependencias)

`HttpClient` también soporta interceptores que se definen como clases inyectables y se configuran a través del sistema DI. Las capacidades de los interceptores basados en DI son idénticas a las de los interceptores funcionales, pero el mecanismo de configuración es diferente.

Un interceptor basado en DI es una clase inyectable que implementa la interfaz `HttpInterceptor`:

```ts
@Injectable()
export class LoggingInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, handler: HttpHandler): Observable<HttpEvent<any>> {
    console.log('URL de la petición: ' + req.url);
    return handler.handle(req);
  }
}
```
Los interceptores basados en DI se configuran a través de un multi-provider de inyección de dependencias:

```ts
bootstrapApplication(AppComponent, {providers: [
  provideHttpClient(
    // Los interceptores basados en DI deben habilitarse explícitamente.
    withInterceptorsFromDi(),
  ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
]});
```
Los interceptores basados en DI se ejecutan en el orden en que se registran sus providers. En una aplicación con una configuración DI extensa y jerárquica, este orden puede ser muy difícil de predecir.
# Probar solicitudes

Como con cualquier dependencia externa, debes simular (mock) el backend HTTP para que tus pruebas puedan emular la interacción con un servidor remoto. La librería `@angular/common/http/testing` proporciona herramientas para capturar las solicitudes realizadas por la aplicación, hacer afirmaciones sobre ellas y simular respuestas que emulen el comportamiento de tu backend.

La librería de pruebas está diseñada para un patrón en el que la aplicación primero ejecuta el código y realiza las peticiones. Luego, la prueba espera que ciertas peticiones se hayan o no se hayan hecho, realiza afirmaciones contra esas peticiones y finalmente proporciona respuestas "vacilando" (flushing) cada petición esperada.

Al final, las pruebas pueden verificar que la aplicación no hizo solicitudes inesperadas.

## Configuración para pruebas

Para comenzar a probar el uso de `HttpClient`, configura `TestBed` e incluye `provideHttpClient()` y `provideHttpClientTesting()` en la configuración de tu prueba. Esto configura `HttpClient` para usar un backend de prueba en lugar de la red real. También proporciona `HttpTestingController`, que usarás para interactuar con el backend de prueba, establecer expectativas sobre qué solicitudes se han realizado, y limpiar respuestas a esas solicitudes. `HttpTestingController` se puede inyectar desde `TestBed` una vez configurado.

Ten en cuenta que debes proporcionar `provideHttpClient()` **antes** que `provideHttpClientTesting()`, ya que `provideHttpClientTesting()` sobrescribirá partes de `provideHttpClient()`. Hacerlo al revés puede romper potencialmente tus pruebas.

```ts
TestBed.configureTestingModule({
  providers: [
    // ... otros providers de prueba
    provideHttpClient(),
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```
Ahora cuando tus pruebas hagan solicitudes, llegarán al backend de prueba en lugar del normal. Puedes usar `httpTesting` para hacer afirmaciones sobre esas solicitudes.

## Esperando y respondiendo solicitudes

Por ejemplo, puedes escribir una prueba que espera que ocurra una solicitud GET y proporciona una respuesta simulada:

```ts
TestBed.configureTestingModule({
  providers: [
    ConfigService,
    provideHttpClient(),
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);

// Cargar `ConfigService` y solicitar la configuración actual.
const service = TestBed.inject(ConfigService);
const config$ = service.getConfig<Config>();

// `firstValueFrom` se suscribe al `Observable`, lo que hace la solicitud HTTP,
// y crea una `Promise` de la respuesta.
const configPromise = firstValueFrom(config$);

// En este punto, la solicitud está pendiente, y podemos afirmar que se realizó
// a través del `HttpTestingController`:
const req = httpTesting.expectOne('/api/config', 'Solicitud para cargar la configuración');

// Si se desea, podemos hacer varias afirmaciones sobre las propiedades de la petición.
expect(req.request.method).toBe('GET');

// Limpiar la solicitud hace que se complete, entregando el resultado.
req.flush(DEFAULT_CONFIG);

// Podemos entonces afirmar que la respuesta fue entregada exitosamente por el `ConfigService`:
expect(await configPromise).toEqual(DEFAULT_CONFIG);

// Finalmente, podemos afirmar que no se hicieron otras solicitudes.
httpTesting.verify();
```
NOTA: `expectOne` fallará si la prueba ha hecho más de una solicitud que coincida con los criterios dados.

Como alternativa a aseverar en `req.method`, podrías usar una forma expandida de `expectOne` para también coincidir con el método de solicitud:

```ts
const req = httpTesting.expectOne({
  method: 'GET',
  url: '/api/config',
}, 'Solicitud para cargar la configuración');
```
ÚTIL: Las APIs de expectativa coinciden contra la URL completa de las solicitudes, incluyendo cualquier parámetro de consulta.

El último paso, verificar que no queden solicitudes pendientes, es lo suficientemente común para que lo muevas a un paso `afterEach()`:

```ts
afterEach(() => {
  // Verificar que ninguna de las pruebas haga solicitudes HTTP adicionales.
  TestBed.inject(HttpTestingController).verify();
});
```
## Manejando más de una solicitud a la vez

Si necesitas responder a solicitudes duplicadas en tu prueba, usa la API `match()` en lugar de `expectOne()`. Toma los mismos argumentos pero devuelve un array de solicitudes coincidentes. Una vez devueltas, estas solicitudes se eliminan de futuras coincidencias y eres responsable de limpiarlas y verificarlas.

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // Manejar la respuesta a cada petición.
}
```
## Coincidencia avanzada

Todas las funciones de coincidencia aceptan una función predicado para lógica de coincidencia personalizada:

```ts
// Busca una petición que tenga un cuerpo de petición.
const requestsWithBody = httpTesting.expectOne(req => req.body !== null);
```
La función `expectNone` afirma que ninguna petición coincide con los criterios dados.

```ts
// Afirma que no se han emitido peticiones de mutación.
httpTesting.expectNone(req => req.method !== 'GET');
```
## Probando el manejo de errores

Debes probar las respuestas de tu aplicación cuando las solicitudes HTTP fallan.

### Errores del backend

Para probar el manejo de errores del backend (cuando el servidor devuelve un código de estado no exitoso), limpia las solicitudes con una respuesta de error que emule lo que tu backend devolvería cuando una solicitud falla.

```ts
const req = httpTesting.expectOne('/api/config');
req.flush('¡Falló!', {status: 500, statusText: 'Error interno del servidor'});

// Afirma que la aplicación manejó con éxito el error del backend.
```
### Errores de red

Las solicitudes también pueden fallar debido a errores de red, que se manifiestan como errores `ProgressEvent`. Estos se pueden entregar con el método `error()`:

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// Afirma que la aplicación manejó con éxito el error de red.
```
## Probando un Interceptor

Debes probar que tus interceptores funcionen bajo las circunstancias deseadas.

Por ejemplo, una aplicación puede requerir agregar un token de autenticación generado por un servicio a cada solicitud saliente.
Este comportamiento se puede hacer cumplir con el uso de un interceptor:

```ts
export function authInterceptor(request: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  const authService = inject(AuthService);

const clonedRequest = request.clone({
    headers: request.headers.append('X-Authentication-Token', authService.getAuthToken()),
  });
  return next(clonedRequest);
}
```
La configuración de `TestBed` para este interceptor debe depender de la característica `withInterceptors`.

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // Se recomienda probar un interceptor a la vez.
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```
El `HttpTestingController` puede recuperar la instancia de la solicitud que luego se puede inspeccionar para asegurar que la solicitud fue modificada.

```ts
const service = TestBed.inject(AuthService);
const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```
Un interceptor similar podría implementarse con interceptores basados en clases:

```ts
@Injectable()
export class AuthInterceptor implements HttpInterceptor {
  private authService = inject(AuthService);

intercept(request: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>> {
    const clonedRequest = request.clone({
      headers: request.headers.append('X-Authentication-Token', this.authService.getAuthToken()),
    });
    return next.handle(clonedRequest);
  }
}
```
Para probarlo, la configuración de `TestBed` debería ser en su lugar:

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    provideHttpClient(withInterceptorsFromDi()),
    provideHttpClientTesting(),
    // Dependemos del token HTTP_INTERCEPTORS para registrar el AuthInterceptor como un HttpInterceptor
    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
  ],
});
```

# Formularios reactivos

Los formularios reactivos proporcionan un enfoque basado en un modelo para manejar las entradas de un formulario cuyos valores cambian con el tiempo. 
Esta guía te muestra cómo crear y actualizar un control de formulario básico, usar múltiples controles en un grupo, validar los valores de un formulario y crear formularios dinámicos en los que puedes agregar o eliminar controles en tiempo de ejecución.

## Visión general de los formularios reactivos

Los formularios reactivos usan un enfoque explícito e inmutable para gestionar el estado de un formulario en cualquier momento.
Cada cambio en el estado del formulario devuelve un nuevo estado, lo que mantiene la integridad del modelo entre cambios.
Los formularios reactivos se construyen alrededor de flujos observables, donde las entradas y los valores del formulario se proporcionan como flujos de valores de entrada, a los que se puede acceder de forma síncrona.

Los formularios reactivos también proporcionan un camino directo hacia las pruebas porque tienes la seguridad de que tus datos son consistentes y predecibles cuando se solicitan.
Cualquier consumidor de los flujos tiene puede manipular esos datos de forma segura.

Los formularios reactivos difieren de los [formularios basados en plantillas](guide/forms/template-driven-forms) de maneras distintas.
Los formularios reactivos proporcionan acceso síncrono al modelo de datos, inmutabilidad con operadores observables y seguimiento de cambios a través de flujos observables.

Los formularios basados en plantillas permiten acceso directo para modificar datos en tu plantilla, pero son menos explícitos que los formularios reactivos porque dependen de directivas incrustadas en la plantilla, junto con datos mutables para rastrear cambios de forma asíncrona.
Consulta la [Visión general de Formularios](guide/forms) para comparaciones detalladas entre los dos paradigmas.

## Añadiendo un control de formulario básico

Para usar controles de formulario, hay tres pasos.

1. Generar un nuevo componente y registrar el módulo de formularios reactivos. Este módulo declara las directivas de formularios reactivos que necesitas para usar formularios reactivos.
1. Instanciar un `FormControl`.
1. Registrar el `FormControl` en la plantilla.

Luego puedes mostrar el formulario agregando el componente a la plantilla.

Los siguientes ejemplos muestran cómo agregar un único control de formulario.
En el ejemplo, el usuario ingresa su nombre en un campo de entrada, captura ese valor de entrada y muestra el valor actual del control del formulario.

<docs-workflow>

<docs-step title="Generar un nuevo componente e importar ReactiveFormsModule">
Usa el comando CLI `ng generate component` para generar un componente en tu proyecto e importa `ReactiveFormsModule` del paquete `@angular/forms` y agrégalo al array de `imports` de tu Componente.

```
</docs-step>

<docs-step title="Declarar una instancia de FormControl">
Usa el constructor de `FormControl` para establecer su valor inicial, que en este caso es una cadena vacía. Al crear estos controles en tu clase de componente, obtienes acceso inmediato para escuchar, actualizar y validar el estado de la entrada del formulario.

<docs-code header="src/app/name-editor/name-editor.component.ts" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" visibleRegion="create-control"/>
</docs-step>

<docs-step title="Registrar el control en la plantilla">
Después de crear el control en la clase del componente, debes asociarlo con un control de formulario en la plantilla. Actualiza la plantilla con el control de formulario usando el enlace `formControl` proporcionado por `FormControlDirective`, que también está incluido en `ReactiveFormsModule`.

<docs-code header="src/app/name-editor/name-editor.component.html" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="control-binding" />

Usando la sintaxis de enlace de plantilla, el control de formulario ahora está registrado en el elemento de entrada `name` de la plantilla. El control de formulario y el elemento DOM se comunican entre sí: la vista refleja cambios en el modelo, y el modelo refleja los cambios en la vista.
</docs-step>

<docs-step title="Mostrar el componente">
El `FormControl` asignado a la propiedad `name` se muestra cuando el componente `<app-name-editor>` se agrega a una plantilla.

<docs-code header="src/app/app.component.html (editor de nombre)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" visibleRegion="app-name-editor"/>
</docs-step>
</docs-workflow>

### Mostrando un valor de control de formulario

Puedes mostrar el valor de las siguientes maneras:

- A través del observable `valueChanges`, donde puedes escuchar cambios en el valor del formulario en la plantilla usando `AsyncPipe` o en la clase del componente usando el método `subscribe()`
- Con la propiedad `value`, que te da proporciona el valor actual en ese momento.

El siguiente ejemplo te muestra cómo mostrar el valor actual usando interpolación en la plantilla.

<docs-code header="src/app/name-editor/name-editor.component.html (control value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="display-value"/>

El valor mostrado cambia a medida que actualizas el control del formulario.

Los formularios reactivos proporcionan acceso a información sobre un control dado a través de propiedades y métodos proporcionados con cada instancia.
Estas propiedades y métodos de la clase subyacente [AbstractControl](api/forms/AbstractControl 'Referencia de API') se usan para controlar el estado del formulario y determinar cuándo mostrar mensajes al manejar [validación de entrada](#validating-form-input 'Aprende más sobre validación de la entrada de formulario').

Lee sobre otras propiedades y métodos de `FormControl` en la [Referencia de API](api/forms/FormControl 'Referencia de sintaxis detallada').

### Reemplazando un valor de control de formulario

Los formularios reactivos tienen métodos para cambiar el valor de un control de forma programática, lo que te da la flexibilidad de actualizar el valor sin necesidad de la interacción del usuario.
Una instancia de `FormControl` proporciona un método `setValue()` que actualiza el valor del control de formulario y valida la estructura del valor proporcionado contra la estructura del control.
Por ejemplo, cuando recuperas datos del formulario desde una API o servicio backend, usa el método `setValue()` para actualizar el control a su nuevo valor, reemplazando completamente el valor anterior.

El siguiente ejemplo agrega un método a la clase del componente para actualizar el valor del control a _Nancy_ usando el método `setValue()`.

<docs-code header="src/app/name-editor/name-editor.component.ts (update value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" visibleRegion="update-value"/>

Actualiza la plantilla con un botón para simular una actualización de nombre.
Cuando haces clic en el botón **Actualizar Nombre**, el valor ingresado en el control del formulario se refleja como su valor actual.

<docs-code header="src/app/name-editor/name-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="update-value"/>

El modelo del formulario es la fuente de la verdad para el control. Por lo tanto, cuando haces clic en el botón, el valor de la entrada cambia dentro de la clase del componente, sobrescribiendo su valor actual.

ÚTIL: En este ejemplo, estás usando un control único.
Cuando uses el método `setValue()` con una instancia de [grupo de formulario](#grouping-form-controls) o [array de formulario](#creating-dynamic-forms), el valor necesita coincidir con la estructura del grupo o array.

## Agrupando controles de formulario

Los formularios típicamente contienen varios controles relacionados.
Los formularios reactivos proporcionan dos formas de agrupar múltiples controles relacionados en un formulario de entrada único.

| Grupos de formulario | Detalle                                                                                                                                                                                                                                                |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Form group  | Define un formulario con un conjunto fijo de controles que puedes gestionar juntos. Los conceptos básicos del grupo de formulario se discuten en esta sección. También puedes [anidar grupos de formulario](#creating-nested-form-groups 'Ver más sobre anidar grupos') para crear formularios más complejos. |
| Form array  | Define un formulario dinámico, en los que puedes agregar y eliminar controles en tiempo de ejecución. También puedes anidar arrays de formulario para crear formularios más complejos. Para más sobre esta opción, consulta [Crear formularios dinámicos](#creating-dynamic-forms).                              |

Al igual que una instancia de `FormControl` (control de formulario) te da control sobre un solo campo de entrada, una instancia de `FormGroup` (grupo de formulario) rastrea el estado del formulario de un grupo de instancias de `FormControl` (por ejemplo, un formulario). 
Cada control en una instancia de `FormGroup` se rastrea por nombre al crear el grupo. 
El siguiente ejemplo muestra cómo gestionar múltiples instancias de `FormControl` en un solo grupo.

Genera un componente `ProfileEditor` e importa las clases `FormGroup` y `FormControl` del paquete `@angular/forms`.

<docs-code language="shell">
ng generate component ProfileEditor
```
<docs-code header="src/app/profile-editor/profile-editor.component.ts (imports)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="imports"/>

Para agregar un grupo de formulario a este componente, sigue los siguientes pasos.

1. Crear una instancia de `FormGroup`.
1. Asociar el modelo y vista de `FormGroup`.
1. Guardar los datos del formulario.

<docs-workflow>

<docs-step title="Crear una instancia de FormGroup">
Crea una propiedad en la clase del componente llamada `profileForm` y establece la propiedad a una nueva instancia de `FormGroup`. Para inicializar el `FormGroup`, proporciona al constructor un objeto de claves nombradas mapeadas a su control.

Para el formulario de perfil, agrega dos instancias de `FormControl` con los nombres `firstName` y `lastName`

<docs-code header="src/app/profile-editor/profile-editor.component.ts (grupo de formulario)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="formgroup"/>

Los controles de formulario individuales ahora están recopilados dentro de un grupo. Una instancia de `FormGroup` proporciona su valor de modelo como un objeto reducido de los valores de cada control en el grupo. Una instancia de `FormGroup` tiene las mismas propiedades $como `value` y `untouched`$ y métodos $como `setValue()`$ que una instancia de control de formulario.
</docs-step>

<docs-step title="Asociar el modelo y vista de FormGroup">
Un grupo de formulario rastrea el estado y los cambios para cada uno de sus controles, por lo que si uno de los controles cambia, el control padre también emite un nuevo estado o cambio de valor. El modelo para el grupo se mantiene a partir de sus miembros. Después de definir el modelo, debes actualizar la plantilla para reflejar el modelo en la vista.

<docs-code header="src/app/profile-editor/profile-editor.component.html (template form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="formgroup"/>

Así como un grupo de formulario contiene un grupo de controles, el `FormGroup` _profileForm_ está vinculado al elemento `form` con la directiva `FormGroup`, creando una capa de comunicación entre el modelo y el formulario que contiene las entradas. La entrada `formControlName` proporcionada por la directiva `FormControlName` vincula cada entrada individual al control de formulario definido en `FormGroup`. Los controles de formulario se comunican con sus respectivos elementos. También comunican cambios a la instancia de `FormGroup`, que proporciona la fuente de verdad para el valor del modelo.
</docs-step>

<docs-step title="Guardar datos del formulario">
El componente `ProfileEditor` acepta entrada del usuario, pero en un escenario real quieres capturar el valor del formulario y hacerlo disponible para procesamiento adicional fuera del componente. La directiva `FormGroup` escucha el evento `submit` emitido por el elemento `form` y emite un evento `ngSubmit` que puedes vincular a una función de callback. Agrega un listener de evento `ngSubmit` a la etiqueta `form` con el método de callback `onSubmit()`.

<docs-code header="src/app/profile-editor/profile-editor.component.html (submit event)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="ng-submit"/>

El método `onSubmit()` en el componente `ProfileEditor` captura el valor actual de `profileForm`. Usa `EventEmitter` para mantener el formulario encapsulado y proporcionar el valor del formulario fuera del componente. El siguiente ejemplo usa `console.warn` para registrar un mensaje en la consola del navegador.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (submit method)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="on-submit"/>

El evento `submit` es emitido por la etiqueta `form` usando el evento DOM integrado. Activas el evento haciendo clic en un botón con tipo `submit`. Esto permite que el usuario presionar la tecla **Enter** para enviar el formulario completado.

Usa un elemento `button` para agregar un botón al final del formulario para activar el envío del formulario.

<docs-code header="src/app/profile-editor/profile-editor.component.html (submit button)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="submit-button"/>

El botón en el fragmento anterior también tiene un enlace `disabled` adjunto para deshabilitar el botón cuando `profileForm` es inválido. Aún no estás realizando ninguna validación, así que el botón siempre está habilitado. La validación básica de formularios se cubre en la sección [Validar entrada de formulario](#validating-form-input).
</docs-step>

<docs-step title="Mostrar el componente">
Para mostrar el componente `ProfileEditor` que contiene el formulario, agrégalo a una plantilla de componente.

<docs-code header="src/app/app.component.html (profile editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" visibleRegion="app-profile-editor"/>

`ProfileEditor` te permite gestionar las instancias de `FormControl` para los controles `firstName` y `lastName` dentro de la instancia de `FormGroup`.

### Creando grupos de formulario anidados

Los `FormGroup` pueden aceptar tanto instancias de `FormControl` individuales como otras instancias de `FormGroup` como hijos. 
Esto hace que la composición de modelos de formulario complejos sea más fácil de mantener y agruparlos lógicamente.

Al construir formularios complejos, gestionar las diferentes áreas de información es más fácil en secciones más pequeñas. 
Usar una instancia de `FormGroup` anidado te permite dividir grandes grupos de formularios en otros más pequeños y manejables.

Para hacer formularios más complejos, sigue estos pasos.

1. Crear un grupo anidado.
1. Agrupar el formulario anidado en la plantilla.

Algunos tipos de información naturalmente caen en el mismo grupo.
Un nombre y dirección son ejemplos típicos de tales grupos anidados, y se usan en los siguientes ejemplos.

<docs-workflow>
<docs-step title="Crear un grupo anidadop">
Para crear un grupo anidado en `profileForm`, agrega un elemento anidado `address` a la instancia de `FormGroup`.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="nested-formgroup"/>

En este ejemplo, `address group` combina los controles actuales `firstName` y `lastName` con los nuevos controles `street`, `city`, `state`, y `zip`. Aunque el elemento `address` en el grupo de formulario es un hijo del elemento general `profileForm` en el grupo de formulario, las mismas reglas se aplican con cambios de valor y estado. Los cambios en estado y valor del grupo de formulario anidado se propagan al grupo de formulario padre, manteniendo consistencia con el modelo general.
</docs-step>

<docs-step title="Agrupar el formulario anidado en la plantilla">
Después de actualizar el modelo en la clase del componente, actualiza la plantilla para conectar la instancia de `FormGroup` y sus elementos de entrada. Agrega el grupo de formulario `address` que contiene los campos `street`, `city`, `state`, y `zip` a la plantilla `ProfileEditor`.

<docs-code header="src/app/profile-editor/profile-editor.component.html (template nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="formgroupname"/>

El formulario `ProfileEditor` se muestra como un grupo, pero el modelo se descompone más para representar las áreas de agrupación lógica.

Muestra el valor para la instancia de `FormGroup` en la plantilla del componente usando la propiedad `value` y `JsonPipe`.
</docs-step>
</docs-workflow>

### Actualizando partes del modelo de datos

Cuando actualizas el valor de una instancia de `FormGroup` que contiene múltiples controles, es posible que solo desees actualizar partes del modelo. 
Esta sección cubre cómo actualizar partes específicas del modelo de datos de un control de formulario.

Hay dos formas de actualizar el valor del modelo:

| Métodos        | Detalles                                                                                                                                                               |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setValue()`   | Establece un nuevo valor para un control individual. El método `setValue()` se adhiere estrictamente a la estructura del grupo de formulario y reemplaza el valor completo del control. |
| `patchValue()` | Reemplaza cualquier propiedad definida en el objeto que haya cambiado en el modelo del formulario.                                                                                     |

Las verificaciones estrictas del método `setValue()` ayudan a detectar errores de anidación en formularios complejos, mientras que `patchValue()` no muestra un error en estos casos.

En `ProfileEditorComponent`, usa el método `updateProfile` con el siguiente ejemplo para actualizar el nombre y la dirección de la calle para el usuario.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (patch value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="patch-value"/>

Simula una actualización agregando un botón a la plantilla para actualizar el perfil del usuario bajo demanda.

<docs-code header="src/app/profile-editor/profile-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="patch-value"/>

Cuando un usuario hace clic en el botón, el modelo `profileForm` se actualiza con nuevos valores para `firstName` y `street`. Observa que `street` se proporciona en un objeto dentro de la propiedad `address`.
Esto es necesario porque el método `patchValue()` aplica la actualización contra la estructura del modelo.
`PatchValue()` solo actualiza propiedades que el modelo del formulario define.

## Empleando el servicio FormBuilder para generar controles

Crear instancias de `FormControl` manualmente puede volverse repetitivo cuando se trabaja con múltiples formularios.
El servicio `FormBuilder` proporciona métodos convenientes para generar controles.

Usa los siguientes pasos para aprovechar este servicio.

1. Importar la clase `FormBuilder`.
1. Inyectar el servicio `FormBuilder`.
1. Generar el contenido del formulario.

Los siguientes ejemplos muestran cómo refactorizar el componente `ProfileEditor` para usar el servicio form builder para crear instancias de `FormControl` y `FormGroup`.

<docs-workflow>
<docs-step title="Importar la clase FormBuilder">
Importa la clase `FormBuilder` del paquete `@angular/forms`.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-builder-imports"/>

</docs-step>

<docs-step title="Inyectar el servicio FormBuilder">
El servicio `FormBuilder` es un proveedor inyectable del módulo de formularios reactivos. Usa la función `inject()` para inyectar esta dependencia en tu componente.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (property init)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="inject-form-builder"/>

</docs-step>
<docs-step title="Generar controles de formulario">
El servicio `FormBuilder` tiene tres métodos: `control()`, `group()` y `array()`. Estos son métodos de fábrica para generar instancias en tus clases de componente incluyendo controles de formulario, grupos de formulario y arrays de formulario. Usa el método `group` para crear los controles de `profileForm`.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (form builder)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-builder"/>

En el ejemplo anterior, usas el método `group()` con el mismo objeto para definir las propiedades en el modelo. El valor para cada nombre de control es un array que contiene el valor inicial como el primer elemento en el array.

SUGERENCIA:  Puedes definir el control con solo el valor inicial, pero si tus controles necesitan validación síncrona o asíncrona, agrega validadores síncronos y asíncronos como el segundo y tercer elemento en el array. Compara usar el form builder con crear las instancias manualmente.
</docs-step>

</docs-workflow>

## Validando la entrada de formulario

_La validación de formularios_ se usa para asegurar que la entrada del usuario sea completa y correcta.
Esta sección cubre agregar un validador único a un control de formulario y cómo mostrar el estado general del formulario.
La validación de formularios se cubre más extensivamente en la guía [Validación de Formularios](guide/forms/form-validation).

Usa los siguientes pasos para agregar validación de formulario.

1. Importar una función validadora en tu componente de formulario.
1. Agregar el validador al campo en el formulario.
1. Agregar lógica para manejar el estado de validación.

La validación más común es hacer un campo requerido.
El siguiente ejemplo muestra cómo agregar una validación requerida al control `firstName` y mostrar el resultado de la validación.

<docs-workflow>
<docs-step title="Importar una función validadora">
Los formularios reactivos incluyen un conjunto de funciones validadoras para casos de uso comunes. Estas funciones reciben un control, lo validan y devuelven un objeto de error o un valor nulo según el resultado de la verificación.

Importa la clase `Validators` del paquete `@angular/forms`.

<docs-step title="Hacer un campo requerido">
En el componente `ProfileEditor`, agrega el método estático `Validators.required` como el segundo elemento en el array para el control `firstName`.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (required validator)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="required-validator"/>
</docs-step>

<docs-step title="Mostrar estado del formulario">
Cuando agregas un campo requerido a un control del formulario, su estado inicial es inválido. Este estado inválido se propaga al elemento del grupo de formulario padre, haciendo su estado inválido. Accede al estado actual de la instancia de `FormGroup` a través de su propiedad `status`.

Muestra el estado actual de `profileForm` usando interpolación.

<docs-code header="src/app/profile-editor/profile-editor.component.html (display status)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="display-status"/>

El botón **Submit** está deshabilitado porque `profileForm` es inválido debido al control de formulario `firstName` requerido. Después de completar la entrada `firstName`, el formulario se vuelve válido y el botón **Submit** se habilita.

Para más información sobre la validación de formularios, visita la guía [Validación de Formularios](guide/forms/form-validation).
</docs-step>
</docs-workflow>

## Creando formularios dinámicos

`FormArray` es una alternativa a `FormGroup` para gestionar cualquier número de controles sin nombre.
Al igual que con las instancias de `FormGroup`, puedes insertar y eliminar controles dinámicamente de las instancias de `FormArray`, y el valor de la instancia de `FormArray` y el estado de validación se calcula desde sus controles hijos.
Sin embargo, no necesitas definir una clave para cada control por nombre, así que esta es una gran opción si no conoces el número de valores hijos de antemano.

Para definir un formulario dinámico, sigue estos pasos.

1. Importar la clase `FormArray`.
1. Definir un control `FormArray`.
1. Acceder al control `FormArray` con un método getter.
1. Mostrar el array de formulario en una plantilla.

El siguiente ejemplo te muestra cómo gestionar un array de _alias_ en `ProfileEditor`.

<docs-workflow>
<docs-step title="Importar la clase `FormArray`">
Importa la clase `FormArray` de `@angular/forms` para usar para información de tipo. El servicio `FormBuilder` está listo para crear una instancia de `FormArray`.

<docs-step title="Definir un control `FormArray`">
Puedes inicializar un array de formulario con cualquier número de controles, desde cero hasta muchos, definiéndolos en un array. Agrega una propiedad `aliases` a la instancia de `FormGroup` para `profileForm` para definir el array de formulario.

Usa el método `FormBuilder.array()` para definir el array, y el método `FormBuilder.control()` para poblar el array con un control inicial.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (aliases form array)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="aliases"/>

El control de alias dentro de la instancia de `FormGroup` ahora está poblado con un control único hasta que se agreguen más controles dinámicamente.
</docs-step>

<docs-step title="Acceder al control `FormArray`">
Un _getter_ proporciona acceso a los alias en la instancia de `FormArray` comparado con repetir el método `profileForm.get()` para obtener cada instancia. La instancia de `FormArray` representa un número indefinido de controles en un array. Es conveniente acceder a un control a través de un getter, y este enfoque es directo de repetir para controles adicionales. <br />

Usa la sintaxis getter para crear una propiedad de clase `aliases` para recuperar el control del `FormArray` de alias del grupo de formulario padre.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (aliases getter)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="aliases-getter"/>

Debido a que el control devuelto es del tipo `AbstractControl`, necesitas proporcionar un tipo explícito para acceder a la sintaxis del método para la instancia de `FormArray`. Define un método para insertar dinámicamente un control de alias en el array de formulario de alias. El método `FormArray.push()` inserta el control como un nuevo elemento en el array.

<docs-code header="src/app/profile-editor/profile-editor.component.ts (add alias)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="add-alias"/>

En la plantilla, cada control se muestra como un campo de entrada separado.

</docs-step>

<docs-step title="Mostrar el array de formulario en la plantilla">

Para adjuntar los alias de tu modelo de formulario, debes agregarlo a la plantilla. Similar a la entrada `formGroupName` proporcionada por `FormGroupNameDirective`, `formArrayName` vincula la comunicación desde la instancia de `FormArray` a la plantilla con `FormArrayNameDirective`.

Agrega el siguiente HTML de plantilla después del `<div>` que cierra el elemento `formGroupName`.

<docs-code header="src/app/profile-editor/profile-editor.component.html (aliases form array template)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="formarrayname"/>

El bloque `@for` itera sobre cada instancia de `FormControl` proporcionada por la instancia de `FormArray` de alias. Debido a que los elementos del `FormArray` no tienen nombre, asignas el índice a la variable `i` y lo pasas a cada control para vincularlo a la entrada `formControlName`.

Cada vez que se agrega una nueva instancia de alias, la nueva instancia de `FormArray` se proporciona su control basado en el índice. Esto te permite rastrear cada control individual al calcular el estado y valor del control raíz.

</docs-step>

<docs-step title="Agregar un alias">

Inicialmente, el formulario contiene un campo `Alias`. Para agregar otro campo, haz clic en el botón **Add Alias**. También puedes validar el array de alias reportado por el modelo del formulario mostrado por `Form Value` en la parte inferior de la plantilla. En lugar de una instancia de `FormControl` para cada alias, puedes componer otra instancia de `FormGroup` con campos adicionales. El proceso de definir un control para cada elemento es el mismo.
</docs-step>

</docs-workflow>

## Resumen de API de formularios reactivos

La siguiente tabla lista las clases base y servicios usados para crear y gestionar controles de formulario reactivo.
Para detalles completos de sintaxis, consulta la documentación de referencia de API para el [paquete Forms](api#forms 'Referencia de API').

### Clases

| Clase             | Detailles                                                                                                                                                                                 |
| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AbstractControl` | La clase base abstracta para las clases concretas de control de formulario `FormControl`, `FormGroup`, y `FormArray`. Proporciona sus comportamientos y propiedades comunes.                           |
| `FormControl`     | Gestiona el valor y estado de validez de un control de formulario individual. Corresponde a un control de formulario HTML como `<input>` o `<select>`.                                            |
| `FormGroup`       | Gestiona el valor y estado de validez de un grupo de instancias de `AbstractControl`. Las propiedades del grupo incluyen sus controles hijos. El formulario de nivel superior en tu componente es `FormGroup`. |
| `FormArray`       | Gestiona el valor y estado de validez de un array indexado numéricamente de instancias de `AbstractControl`.                                                                                      |
| `FormBuilder`     | Un servicio inyectable que proporciona métodos de fábrica para crear instancias de control.                                                                                                     |
| `FormRecord`      | Rastrea el valor y estado de validez de una colección de instancias de `FormControl`, cada una de las cuales tiene el mismo tipo de valor.                                                                  |

### Directivas

| Directiva              | Detalles                                                                                    |
| :--------------------- | :----------------------------------------------------------------------------------------- |
| `FormControlDirective` | Sincroniza una instancia `FormControl` independiente a un elemento de control de formulario.                       |
| `FormControlName`      | Sincroniza `FormControl` en una instancia existente de `FormGroup` a un elemento de control de formulario por nombre. |
| `FormGroupDirective`   | Sincroniza una instancia existente de `FormGroup` a un elemento DOM.                                   |
| `FormGroupName`        | Sincroniza una instancia anidada de `FormGroup` a un elemento DOM.                                      |
| `FormArrayName`        | Sincroniza una instancia anidada de `FormArray` a un elemento DOM.                                      |
# Formularios tipados

A partir de Angular 14, los formularios son estrictamente tipados por defecto.

Como antecedente para esta guía, te recomendamos familiarizarte con los [Formularios Reactivos de Angular](guide/forms/reactive-forms).

## Visión general de formularios tipados

<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" alt="Formularios Tipados en Angular" />

Con los formularios reactivos de Angular, especificas explícitamente un *modelo de formulario*. Como ejemplo simple, considera este formulario básico de inicio de sesión:

```ts
const login = new FormGroup({
  email: new FormControl(''),
  password: new FormControl(''),
});
```

Angular proporciona muchas APIs para interactuar con este `FormGroup`. Por ejemplo, puedes llamar `login.value`, `login.controls`, `login.patchValue`, etc. (Para una referencia completa de la API, consulta la [documentación de la API](api/forms/FormGroup).)

En versiones anteriores de Angular, la mayoría de estas APIs incluían `any` en su tipado, e interactuar con la estructura de los controles, o los valores mismos, no era seguro en cuanto a tipos. Por ejemplo: podías escribir el siguiente código inválido:

```ts
const emailDomain = login.value.email.domain;
```

Con formularios reactivos estrictamente tipados, el código anterior no compila, porque `email` no tiene la propiedad `domain`.

Además de la seguridad, el tipado ofrece otras mejoras, como un mejor autocompletado en los IDE y una forma explícita de especificar la estructura del formulario

Estas mejoras actualmente se aplican solo a formularios *reactivos* (no a formularios [*basados en plantillas*](guide/forms/template-driven-forms)).

## Formularios no tipados

Los formularios no tipados siguen siendo compatibles y continuarán funcionando como antes. Para usarlos, debes importar los símbolos `Untyped` de `@angular/forms`:

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

Cada símbolo `Untyped` tiene exactamente la misma semántica que en versiones anteriores de Angular. Puedes habilitar el tipado de forma incremental al eliminar los prefijos `Untyped`.

## `FormControl`: Primeros pasos

El formulario más simple consiste en un solo control:

```ts
const email = new FormControl('angularrox@gmail.com');
```

Este control será automáticamente inferido para tener el tipo `FormControl<string|null>`. TypeScript aplicará automáticamente este tipo en toda la [API de `FormControl`](api/forms/FormControl), como `email.value`, `email.valueChanges`, `email.setValue(...)`, etc.

### Nulabilidad

Podrías preguntarte: ¿por qué el tipo de este control incluye `null`? Esto es porque el control puede volverse `null` en cualquier momento, llamando a reset:

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

TypeScript te obligará a manejar la posibilidad de que el control se vuelva `null`. Si quieres hacer este control no nullable, puedes usar la opción `nonNullable`. Esto hará que el control se resetee a su valor inicial, en lugar de `null`:

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

Cabe reiterar, esta opción afecta el comportamiento del formulario en tiempo de ejecución cuando se llama a `.reset()`, y debe cambiarse con cuidado.

### Especificar un tipo explícito

Es posible especificar el tipo, en lugar de depender de la inferencia. Considera un control inicializado a `null`. Debido a que el valor inicial es `null`, TypeScript inferirá `FormControl<null>`,  lo cual es más restrictivo de lo que queremos.

```ts
const email = new FormControl(null);
email.setValue('angularrox@gmail.com'); // Error!
```

Para prevenir esto, especificamos explícitamente el tipo como `string|null`:

```ts
const email = new FormControl<string|null>(null);
email.setValue('angularrox@gmail.com');
```

## `FormArray`: Colecciones dinámicas y homogéneas

Un `FormArray` contiene una lista abierta de controles. El parámetro de tipo corresponde al tipo de cada control interno:

```ts
const names = new FormArray([new FormControl('Alex')]);
names.push(new FormControl('Jess'));
```

Este `FormArray` tendrá el tipo de controles internos `FormControl<string|null>`.

Si necesitas tener múltiples tipos de elementos dentro del array, debes usar `UntypedFormArray`, ya que TypeScript no puede inferir el tipo de elemento en cada posición

## `FormGroup` y `FormRecord`

Angular proporciona el tipo `FormGroup` para formularios con un conjunto enumerado de claves, y un tipo llamado `FormRecord`, para grupos abiertos o dinámicos.

### Valores parciales

Considera de nuevo un formulario de inicio de sesión:

```ts
const login = new FormGroup({
    email: new FormControl('', {nonNullable: true}),
    password: new FormControl('', {nonNullable: true}),
});
```

En cualquier `FormGroup`, es [posible deshabilitar controles](api/forms/FormGroup). Cualquier control deshabilitado no aparecerá en el valor del grupo.

Como consecuencia, el tipo de `login.value` es `Partial<{email: string, password: string}>`. El `Partial` en este tipo significa que cada miembro podría ser `undefined`.

Más específicamente, el tipo de `login.value.email` es `string|undefined`, y TypeScript aplicará que manejes el valor posiblemente `undefined` (si tienes `strictNullChecks` habilitado).

Si quieres acceder al valor *incluyendo* controles deshabilitados, y así evitar campos posiblemente `undefined`, puedes usar `login.getRawValue()`.

### Controles opcionales y grupos dinámicos

Algunos formularios tienen controles que pueden o no estar presentes, y que pueden ser agregados o eliminados en tiempo de ejecución. Puedes representar estos controles usando *campos opcionales*:

```ts
interface LoginForm {
  email: FormControl<string>;
  password?: FormControl<string>;
}

const login = new FormGroup<LoginForm>({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});

En este formulario especificamos explícitamente el tipo, lo que nos permite hacer que el control `password` sea opcional. TypeScript se encargará de aplicar que solo los controles opcionales puedan añadirse o eliminarse.

### `FormRecord`

Algunos usos de `FormGroup` no se ajustan al patrón anterior porque las claves no se conocen de antemano. La clase `FormRecord` está diseñada para ese caso:

```ts
const addresses = new FormRecord<FormControl<string|null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

A este `FormRecord` se le puede agregar cualquier control de tipo `string|null`.

Si necesitas un `FormGroup` que sea dinámico (abierto) y heterogéneo (los controles son de diferentes tipos), no es posible mejorar la seguridad de tipos, y deberías usar `UntypedFormGroup`.

Un `FormRecord` también puede construirse con el `FormBuilder`:

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```

## `FormBuilder` and `NonNullableFormBuilder`

La clase `FormBuilder` ha sido actualizada para soportar los nuevos tipos también, de la misma manera que los ejemplos anteriores.

Además, hay un constructor adicional disponible: `NonNullableFormBuilder`. Este tipo es una abreviatura para especificar `{nonNullable: true}` en cada control, y puede eliminar código repetitivo significativo de formularios grandes sin valores nulos. Puedes acceder a él usando la propiedad `nonNullable` en un `FormBuilder`:

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

En el ejemplo anterior, ambos controles internos no permitirán valores nulos (es decir, el valor `nonNullable` estará establecido como `true`)

También puedes inyectarlo usando el nombre `NonNullableFormBuilder`.
# Construyendo un formulario basado en plantillas

Este tutorial te muestra cómo crear un formulario basado en plantillas. Los elementos de control en el formulario están vinculados a propiedades de datos que tienen validación de entrada. La validación de entrada ayuda a mantener la integridad de los datos y el estilo, lo que mejora la experiencia del usuario.

Los formularios basados en plantillas usan [enlace de datos bidireccional](guide/templates/two-way-binding) para actualizar el modelo de datos en el componente a medida que se realizan cambios en la plantilla y viceversa.
Angular soporta dos enfoques de diseño para formularios interactivos. Los formularios basados en plantillas te permiten usar directivas específicas de formulario en tu plantilla de Angular. Los formularios reactivos proporcionan un enfoque basado en modelos para construir formularios.

Los formularios basados en plantillas son una excelente opción para formularios pequeños o simples, mientras que los formularios reactivos son más escalables y adecuados para formularios complejos. Para una comparación de los dos enfoques, consulta [Elegir un enfoque](guide/forms#choosing-an-approach)
Puedes construir casi cualquier tipo de formulario con una plantilla de Angular formularios de inicio de sesión, formularios de contacto, y prácticamente cualquier formulario de negocio.
Puedes diseñar los controles de forma creativa y vincularlos a los datos en tu modelo de objeto.
Puedes especificar reglas de validación, mostrar errores de validación, permitir condicionalmente entrada en controles específicos, activar retroalimentación visual integrada, y mucho más.

## Objetivos

Este tutorial te enseña cómo hacer lo siguiente:

- Construir un formulario de Angular con un componente y plantilla
- Usar `ngModel` para crear enlaces de datos bidireccionales para leer y escribir valores de control de entrada
- Proporcionar retroalimentación visual usando clases CSS especiales que rastrean el estado de los controles
- Mostrar errores de validación a los usuarios y permitir la entrada de datos en los controles del formulario de forma condicional, basándose en el estado del mismo.
- Compartir información entre elementos HTML usando [variables de referencia de plantilla](guide/templates/variables#template-reference-variables)

## Construir un formulario basado en plantillas

Los formularios basados en plantillas se basan en directivas definidas en el `FormsModule`.

| Directives     | Details                                                                                                                                                                                                                                                                         |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NgModel`      | Reconcilia los cambios de valor en el elemento de formulario adjunto con los cambios en el modelo de datos, lo que te permite responder a la entrada del usuario con validación y manejo de errores.                                                                                                           |
| `NgForm`       | Crea una instancia de `FormGroup` de nivel superior y la vincula a un elemento `<form>` para rastrear el valor agregado del formulario y el estado de validación. Tan pronto como importas `FormsModule`, esta directiva se vuelve activa por defecto en todas las etiquetas `<form>`. No necesitas agregar un selector especial. |
| `NgModelGroup` | Crea y vincula una instancia de `FormGroup` a un elemento DOM.                                                                                                                                                                                                                      |

### Resumen de los pasos

En el curso de este tutorial, vinculas un formulario de muestra a datos y manejas la entrada del usuario usando los siguientes pasos.

1. Construir el formulario básico.
   - Definir un modelo de datos de muestra
   - Incluir infraestructura requerida como el `FormsModule`
1. Vincular controles de formulario a propiedades de datos usando la directiva `ngModel` y la sintaxis de enlace de datos bidireccional.
   - Examinar cómo `ngModel` reporta estados de control usando clases CSS
   - Nombrar controles para hacerlos accesibles a `ngModel`
1. Rastrear validez de entrada y estado de control usando `ngModel`.
   - Agregar CSS personalizado para proporcionar retroalimentación visual sobre el estado
   - Mostrar y ocultar mensajes de error de validación
1. Responder a un evento de clic de botón HTML nativo agregando al modelo de datos.
1. Manejar el envío del formulario usando la propiedad de salida [`ngSubmit`](api/forms/NgForm#properties) del formulario.
   - Deshabilitar el botón **Submit** hasta que el formulario sea válido
   - Después del envío, intercambiar el formulario terminado por contenido diferente en la página

## Construir el formulario

1. La aplicación de ejemplo proporcionada crea la clase `Actor` que define el modelo de datos reflejado en el formulario.

<docs-code header="src/app/actor.ts" language="typescript" path="adev/src/content/examples/forms/src/app/actor.ts"/>

1. El diseño y detalles del formulario están definidos en la clase `ActorFormComponent`.

<docs-code header="src/app/actor-form/actor-form.component.ts (v1)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="v1"/>

El valor `selector` del componente de "app-actor-form" significa que puedes colocar este formulario en una plantilla padre usando la etiqueta `<app-actor-form>`.

1. El siguiente código crea una nueva instancia de actor, para que el formulario inicial pueda mostrar un actor de ejemplo.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" visibleRegion="Marilyn"/>

Esta demo usa datos ficticios para `model` y `skills`.
   En una aplicación real, inyectarías un servicio de datos para obtener y guardar datos reales, o exponerías estas propiedades como entradas y salidas.

1. El siguiente código crea una nueva instancia de actor, para que el formulario inicial pueda mostrar un actor de ejemplo.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" visibleRegion="imports"/>

1. El formulario se muestra en el diseño de la aplicación definido por la plantilla del componente raíz.

<docs-code header="src/app/app.component.html" language="html" path="adev/src/content/examples/forms/src/app/app.component.html"/>

La plantilla inicial define el diseño para un formulario con dos grupos de formulario y un botón de envío.
   Los grupos de formulario corresponden a dos propiedades del modelo de datos Actor, nombre y estudio.
   Cada grupo tiene una etiqueta y una caja para entrada de datos del usuario.

- El elemento de control **Name** `<input>` tiene el atributo HTML5 `required`
   - El elemento de control **Studio** `<input>` no lo tiene porque `studio` es opcional

El botón **Submit** tiene algunas clases para estilos.
   En este punto, el diseño del formulario es todo HTML5 plano, sin enlaces o directivas.

1. El formulario de muestra usa algunas clases de estilo de [Twitter Bootstrap](https://getbootstrap.com/css): `container`, `form-group`, `form-control`, y `btn`.
   Para usar estos estilos, la hoja de estilo de la aplicación importa la biblioteca.

<docs-code header="src/styles.css" path="adev/src/content/examples/forms/src/styles.1.css"/>

1. El formulario requiere que la habilidad de un actor se elija de una lista predefinida de `skills` mantenida internamente en `ActorFormComponent`.
   El bucle Angular `@for` itera sobre los valores de datos para llenar el elemento `<select>`.

<docs-code header="src/app/actor-form/actor-form.component.html (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="skills"/>

Si ejecutas la aplicación, verás la lista de habilidades en el control de selección. 
Los elementos de entrada aún no están enlazados a valores de datos o eventos, por lo que todavía están en blanco y no tienen comportamiento.

## Vincular controles de entrada a propiedades de datos

El siguiente paso es vincular los controles de entrada a las propiedades `Actor` correspondientes con el enlace de datos bidireccional, para que respondan a la entrada del usuario actualizando el modelo de datos, y también respondan a los cambios programáticos en los datos actualizando la visualización.

La directiva `ngModel` declarada en `FormsModule` te permite vincular controles en tu formulario basado en plantillas a propiedades en tu modelo de datos.
Cuando incluyes la directiva usando la sintaxis para enlace de datos bidireccional, `[(ngModel)]`, Angular puede rastrear el valor y la interacción del usuario del control y mantener la vista sincronizada con el modelo.

1. Edita el archivo de plantilla `actor-form.component.html`.
1. Encuentra la etiqueta `<input>` junto a la etiqueta **Name**.
1. Agrega la directiva `ngModel`, usando la sintaxis de enlace de datos bidireccional `[(ngModel)]="..."`.

<docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngModelName-1"/>

ÚTIL: Este ejemplo tiene una interpolación de diagnóstico temporal después de cada etiqueta de entrada, `{{model.name}}`, para mostrar el valor de datos actual de la propiedad correspondiente. El comentario te recuerda eliminar las líneas de diagnóstico cuando hayas terminado de observar el enlace de datos bidireccional en funcionamiento.

### Acceder al estado general del formulario

Cuando importaste `FormsModule` en tu componente, Angular automáticamente creó y adjuntó una directiva [NgForm](api/forms/NgForm) a la etiqueta `<form>` en la plantilla (porque `NgForm` tiene el selector `form` que coincide con elementos `<form>`).

Para obtener acceso a `NgForm` y el estado general del formulario, declara una [variable de referencia de plantilla](guide/templates/variables#template-reference-variables).

1. Edita el archivo de plantilla `actor-form.component.html`.
1. Actualiza la etiqueta `<form>` con una variable de referencia de plantilla, `#actorForm`, y establece su valor como sigue.

<docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="template-variable"/>

La variable de plantilla `actorForm` ahora es una referencia a la instancia de directiva `NgForm` que gobierna el formulario como un todo.

1. Ejecuta la aplicación.
1. Comienza a escribir en la caja de entrada **Name**.

A medida que agregas y eliminas caracteres, puedes verlos aparecer y desaparecer del modelo de datos.

La línea de diagnóstico que muestra valores interpolados demuestra que los valores fluyen de la caja de entrada al modelo y viceversa.

### Nombrando elementos de control

Cuando usas `[(ngModel)]` en un elemento, debes definir un atributo `name` para ese elemento.
Angular usa el nombre asignado para registrar el elemento con la directiva `NgForm` adjunta al elemento `<form>` padre.

El ejemplo agregó un atributo `name` al elemento `<input>` y lo estableció como "name", lo cual tiene sentido para el nombre del actor.
Cualquier valor único funcionará, pero es útil usar un nombre descriptivo.

1. Agrega enlaces `[(ngModel)]` similares y atributos `name` a **Studio** y **Skill**.
1. Ahora puedes eliminar los mensajes de diagnóstico que muestran valores interpolados.
1. Para confirmar que el enlace de datos bidireccional funciona para todo el modelo de actor, agrega un nuevo enlace de texto con el pipe [`json`](api/common/JsonPipe) en la parte superior de la plantilla del componente, que serializa los datos a una cadena.

Después de estas revisiones, la plantilla del formulario debería verse como así:

<docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngModel-2"/>

Notarás que:

- Cada elemento `<input>` tiene una propiedad `id`.
  Esto es utilizado por el atributo `for` del elemento `<label>` para hacer coincidir la etiqueta con su control de entrada.
  Esta es una [característica estándar de HTML](https://developer.mozilla.org/es/docs/Web/HTML/Reference/Elements/label).

- Cada elemento `<input>` también tiene la propiedad `name` requerida que Angular usa para registrar el control con el formulario..

Una vez que hayas observado los efectos, puedes eliminar el enlace de texto `{{ model | json }}`.

## Rastrear los estados del formulario

Angular aplica la clase `ng-submitted` a elementos `form` después de que el formulario ha sido enviado. 
Estas clases pueden usarse para cambiar el estilo del formulario después de que ha sido enviado

## Rastrear los estados de control

Agregar la directiva `NgModel` a un control agrega nombres de clase al control que describen su estado.

Estas clases pueden usarse para cambiar el estilo de un control basado en su estado.

Angular también aplica la clase `ng-submitted` a los elementos `form` al enviar, 
pero no a los controles dentro del elemento `form`.

Puedes usar estas clases CSS para definir los estilos de tu control en función de su estado.

### Observar los estados del control

Para ver cómo las clases son agregadas y eliminadas por el framework, abre las herramientas de desarrollador del navegador e inspecciona el elemento `<input>` que representa el nombre del actor.

Usando las herramientas de desarrollador de tu navegador, encuentra el elemento `<input>` que corresponde a la caja de entrada **Name**.
   You can see that the element has multiple CSS classes in addition to "form-control".

1. Cuando lo abres por primera vez, las clases indican que tiene un valor válido, que el valor no ha sido cambiado desde la inicialización o reset, y que el control no ha sido visitado desde la inicialización o reset.

<docs-code language="html">

<input class="form-control ng-untouched ng-pristine ng-valid">;
```
1. Realiza las siguientes acciones en la caja de entrada `<input>` **Name**, y observa qué clases aparecen.

- Observa sin tocar.
     Las clases indican que está sin tocar, pristino y válido.

- Haz clic dentro de la caja de nombre, luego haz clic fuera de ella.
     El control ahora ha sido visitado, y el elemento tiene la clase `ng-touched` en lugar de la clase `ng-untouched`.

- Agrega barras al final del nombre.
     Ahora está en estado `touched` y `dirty`.

- Borra el nombre.
     Esto hace que el valor sea inválido, por lo que la clase `ng-invalid` reemplaza la clase `ng-valid`.

### Crea retroalimentación visual para los estados

El par `ng-valid`/`ng-invalid` es particularmente interesante, porque quieres enviar una
señal visual fuerte cuando los valores son inválidos.
También quieres marcar campos requeridos.

Puedes marcar campos requeridos y datos inválidos al mismo tiempo con una barra coloreada
a la izquierda de la caja de entrada.

Para cambiar la apariencia de esta manera, sigue estos pasos.

1. Agrega definiciones para las clases CSS `ng-*`.
1. Agrega estas definiciones de clase a un nuevo archivo `forms.css`.
1. Agrega el nuevo archivo al proyecto como hermano de `index.html`:

<docs-code header="src/assets/forms.css" language="css" path="adev/src/content/examples/forms/src/assets/forms.css"/>

1. In the `index.html` file, update the `<head>` tag to include the new style sheet.

<docs-code header="src/index.html (styles)" path="adev/src/content/examples/forms/src/index.html" visibleRegion="styles"/>

### Mostrar y ocultar mensajes de error de validación

La caja de entrada **Name** es requerida y limpiarla convierte la barra en roja.
Eso indica que algo está mal, pero el usuario no sabe qué está mal o qué hacer al respecto.
Puedes proporcionar un mensaje útil verificando y respondiendo al estado del control.

El control de de selección **Skill** también es requerida, pero no necesita este tipo de manejo de errores porque ya restringe la selección a valores válidos.

Para definir y mostrar un mensaje de error cuando sea apropiado, sigue estos pasos.

<docs-workflow>
<docs-step title="Agregar una referencia local a la entrada">
Extiende la etiqueta `input` con una variable de referencia de plantilla que puedes usar para acceder al control Angular de la caja de entrada desde dentro de la plantilla. En el ejemplo, la variable es `#name="ngModel"`.

La variable de referencia de plantilla (`#name`) se establece como `"ngModel"` porque ese es el valor de la propiedad [`NgModel.exportAs`](api/core/Directive#exportAs). Esta propiedad le dice a Angular cómo vincular una variable de referencia a una directiva.
</docs-step>

<docs-step title="Agregar el mensaje de error">
Agrega un `<div>` que contenga un mensaje de error apropiado.
</docs-step>

<docs-step title="Hacer el mensaje de error condicional">
Muestra u oculta el mensaje de error vinculando propiedades del control `name` a la propiedad `hidden` del elemento `<div>` del mensaje.
</docs-step>

<docs-code header="src/app/actor-form/actor-form.component.html (hidden-error-msg)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="hidden-error-msg"/>

<docs-step title="Agregar un mensaje de error condicional al nombre">
Agrega un mensaje de error condicional a la caja de entrada `name`, como en el siguiente ejemplo.

<docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="name-with-error-msg"/>
</docs-step>
</docs-workflow>
En este ejemplo, ocultas el mensaje cuando el control es válido o _pristine_.
Pristine significa que el usuario no ha cambiado el valor desde que se mostró en este formulario.
Si ignoras el estado `pristine`, ocultarías el mensaje solo cuando el valor es válido.
Si llegas a este componente con un actor nuevo y en blanco o un actor inválido, verás el mensaje de error inmediatamente, antes de haber hecho algo.

Podrías querer que el mensaje se muestre solo cuando el usuario hace un cambio inválido.
Ocultar el mensaje mientras el control está en el estado `pristine` logra ese objetivo.
Verás la importancia de esta elección cuando agregues un nuevo actor al formulario en el siguiente paso.
## Agrega un nuevo actor

Este ejercicio muestra cómo puedes responder a un evento de clic de botón HTML nativo agregando al modelo de datos.
Para permitir que los usuarios del formulario agreguen un nuevo actor, agregarás un botón **New Actor** que responde a un evento de clic.

1. En la plantilla, coloca un elemento `<button>` "New Actor" en la parte inferior del formulario.
1. En el archivo del componente, agrega el método de creación de actor al modelo de datos de actor.

<docs-code header="src/app/actor-form/actor-form.component.ts (New Actor method)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="new-actor"/>

1. Vincula el evento de clic del botón a un método de creación de actor, `newActor()`.

<docs-code header="src/app/actor-form/actor-form.component.html (New Actor button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="new-actor-button-no-reset"/>

1. Ejecuta la aplicación nuevamente y haz clic en el botón **New Actor**.

El formulario se limpia, y las barras _required_ a la izquierda de la caja de entrada se vuelven rojas, indicando propiedades `name` y `skill` inválidas.
   Observa que los mensajes de error están ocultos.
   Esto es porque el formulario es pristino; no has cambiado nada aún.

1. Ingresa un nombre y haz clic en **New Actor** nuevamente.

Ahora la aplicación muestra un mensaje de error `Name is required`, porque la caja de entrada ya no está en estado `pristine`.
   El formulario recuerda que ingresaste un nombre antes de hacer clic en **New Actor**.

1. Para restaurar el estado pristino de los controles del formulario, limpia todas las banderas imperativamente llamando al método `reset()` del formulario después de llamar al método `newActor()`.

<docs-code header="src/app/actor-form/actor-form.component.html (Reset the form)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="new-actor-button-form-reset"/>

Ahora hacer clic en **New Actor** resetea tanto el formulario como sus banderas de control.

## Enviar el formulario con `ngSubmit`

El usuario debería poder enviar este formulario después de llenarlo.
El botón **Submit** en la parte inferior del formulario no hace nada por sí solo, pero activa un evento de envío de formulario debido a su tipo (`type="submit"`).

Para responder a este evento, sigue los siguientes pasos.

<docs-workflow>

<docs-step title="Escuchar ngOnSubmit">
Vincula la propiedad de evento [`ngSubmit`](api/forms/NgForm#properties) del formulario al método `onSubmit()` del componente actor-form.

<docs-code header="src/app/actor-form/actor-form.component.html (ngSubmit)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngSubmit"/>
</docs-step>

<docs-step title="Vincular la propiedad disabled">
Usa la variable de referencia de plantilla, `#actorForm` para acceder al formulario que contiene el botón **Submit** y crear un enlace de evento.

Vincularás la propiedad del formulario que indica su validez general a la propiedad `disabled` del botón **Submit**.

<docs-code header="src/app/actor-form/actor-form.component.html (submit-button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="submit-button"/>
</docs-step>

<docs-step title="Ejecutar la aplicación">
Observa que el botón está habilitado —aunque aún no hace nada útil.
</docs-step>

<docs-step title="Eliminar el valor Name">
Esto viola la regla "required", así que muestra el mensaje de error —y observa que también deshabilita el botón **Submit**.

No tuviste que conectar explícitamente el estado habilitado del botón a la validez del formulario.
`FormsModule` hizo esto automáticamente cuando definiste una variable de referencia de plantilla en el elemento de formulario mejorado, luego referiste a esa variable en el control del botón.
</docs-step>
</docs-workflow>

### Responder al envío del formulario

Para mostrar una respuesta al envío del formulario, puedes ocultar el área de entrada de datos y mostrar algo más en su lugar.

<docs-workflow>
<docs-step title="Envolver el formulario">
Envuelve todo el formulario en un `<div>` y vincula su propiedad `hidden` a la propiedad `ActorFormComponent.submitted`.

<docs-code header="src/app/actor-form/actor-form.component.html (extracto)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="edit-div"/>

El formulario principal es visible desde el inicio porque la propiedad `submitted` es falsa hasta que envías el formulario, como muestra este fragmento de `ActorFormComponent`:

<docs-code header="src/app/actor-form/actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="submitted"/>

Cuando haces clic en el botón **Submit**, la bandera `submitted` se vuelve verdadera y el formulario desaparece.
</docs-step>

<docs-step title="Agregar el estado enviado">
Para mostrar algo más mientras el formulario está en el estado enviado, agrega el siguiente HTML debajo del nuevo envoltorio `<div>`.

<docs-code header="src/app/actor-form/actor-form.component.html (extracto)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="submitted"/>

Este `<div>`, que muestra un actor de solo lectura con enlaces de interpolación, aparece solo mientras el componente está en el estado enviado.

La visualización alternativa incluye un botón _Edit_ cuyo evento de clic está vinculado a una expresión que limpia la bandera `submitted`.
</docs-step>

<docs-step title="Probar el botón Edit">
Haz clic en el botón *Edit* para cambiar la visualización de vuelta al formulario editable.
</docs-step>
</docs-workflow>

## Resumen

El formulario de Angular discutido en esta página aprovecha las siguientes
características del framework para proporcionar soporte para modificación de datos, validación y más.

- Una plantilla de formulario HTML de Angular
- Una clase de componente de formulario que utiliza un decorador  `@Component`
- Manejo del envío del formulario vinculando a la propiedad de evento `NgForm.ngSubmit`
- Variables de referencia de plantilla como `#actorForm` y `#name`
- Sintaxis `[(ngModel)]` para enlace de datos bidireccional
- El uso de atributos `name` para la validación y el seguimiento de lo scambios en los elementos del formulario
- La propiedad `valid` de la variable de referencia en controles de entrada indica si un control es válido o debería mostrar mensajes de error
- Controlar el estado habilitado del botón **Submit** vinculando a la validez de `NgForm`
- Clases CSS personalizadas que proporcionan retroalimentación visual a los usuarios sobre controles que no son válidos

Aquí está el código para la versión final de la aplicación:
# Validando la entrada de formularios

Puedes mejorar la calidad general de los datos al validar la entrada del usuario en cuanto a precisión y completitud. 
Esta página muestra cómo validar la entrada del usuario desde la interfaz de usuario y mostrar mensajes de validación útiles, tanto en formularios reactivos como en los basados en plantillas.

## Validando la entrada en formularios basados en plantillas

Para agregar validación a un formulario basado en plantillas, agregas los mismos atributos de validación que usarías con [validación nativa de formularios HTML](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5/Constraint_validation).
Angular usa directivas para hacer coincidir estos atributos con funciones validadoras en el framework.

Cada vez que cambia el valor de un control de formulario, Angular ejecuta la validación y genera una lista de errores de validación que resulta en un estado `INVALID`, o null, que resulta en un estado VALID.

Luego puedes inspeccionar el estado del control exportando `ngModel` a una variable de plantilla local.
El siguiente ejemplo exporta `NgModel` a una variable llamada `name`:

```
Observa las siguientes características ilustradas en el ejemplo.

* El elemento `<input>` lleva los atributos de validación HTML: `required` y `minlength`.
    También lleva una directiva validadora personalizada, `forbiddenName`.
    Para más información, consulta la sección [Validadores personalizados](#defining-custom-validators).

* `#name="ngModel"` exporta `NgModel` a una variable local llamada `name`.
    `NgModel` refleja muchas de las propiedades de su instancia `FormControl` subyacente, por lo que puedes usar esto en la plantilla para verificar estados de control como `valid` y `dirty`.
    Para una lista completa de propiedades de control, consulta la referencia de la API [AbstractControl](api/forms/AbstractControl).

* El `@if` más externo revela un conjunto de mensajes anidados pero solo si `name` es inválido y el control está `dirty` o `touched`.

* Cada `@if` anidado puede presentar un mensaje personalizado para uno de los posibles errores de validación.
        Hay mensajes para `required`, `minlength`, y `forbiddenName`.

CONSEJO: Para evitar que el validador muestre errores antes de que el usuario tenga la oportunidad de editar el formulario, debes verificar los estados `dirty` o `touched` en un control.

* Cuando el usuario cambia el valor en el campo observado, el control se marca como "dirty"
* Cuando el usuario quita el foco del elemento de control del formulario, el control se marca como "touched"

## Validando la entrada en formularios reactivos

En un formulario reactivo, la fuente de la verdad es la clase del componente. 
En lugar de agregar validadores a través de atributos en la plantilla, agregas funciones de validador directamente al modelo de control del formulario en la clase del componente. 
Angular luego llama a estas funciones cada vez que el valor del control cambia.

### Funciones de validación

Las funciones de validador pueden ser síncronas o asíncronas.

| Tipo de validador   | Detalles |
|:---              |:---     |
| Validadores síncronos  | Funciones síncronas que toman una instancia de control e inmediatamente devuelven un conjunto de errores de validación o `null`. Pásalos como el segundo argumento cuando instancies un `FormControl`.                       |
| Validadores asíncronos | Funciones asíncronas que toman una instancia de control y devuelven una Promesa u Observable que luego emite un conjunto de errores de validación o `null`. Pásalos como el tercer argumento cuando instancies un `FormControl`. |

Por razones de rendimiento, Angular solo ejecuta validadores asíncronos si todos los validadores síncronos pasan. 
Cada uno debe completarse antes de que se establezcan los errores.

### Funciones de validación integradas

Puedes optar por [escribir tus propias funciones de validador](#defining-custom-validators), o puedes usar algunos de los validadores incorporados de Angular.

Los mismos validadores integrados que están disponibles como atributos en formularios basados en plantillas, como `required` y `minlength`, están todos disponibles para usar como funciones de la clase `Validators`.
Para una lista completa de validadores integrados, consulta la referencia de la API [Validators](api/forms/Validators).

Para actualizar el formulario de actor para que sea un formulario reactivo, usa algunos de los mismos
validadores integrados esta vez, en forma de función, como en el siguiente ejemplo.

<docs-code header="reactive/actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" visibleRegion="form-group"/>

En este ejemplo, el control `name` configura dos validadores integrados, `Validators.required` y `Validators.minLength(4)`, y un validador personalizado, `forbiddenNameValidator`.

Todos estos validadores son síncronos, por lo que se pasan como segundo argumento.
Observa que puedes soportar múltiples validadores pasando las funciones como un array.

Este ejemplo también agrega algunos métodos getter.
En un formulario reactivo, siempre puedes acceder a cualquier control de formulario a través del método `get` en su grupo padre, pero a veces es útil definir getters como abreviación para la plantilla.

Si miras la plantilla para la entrada `name` nuevamente, es bastante similar al ejemplo basado en plantillas.

<docs-code header="reactive/actor-form-reactive.component.html (name with error msg)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" visibleRegion="name-with-error-msg"/>

Este formulario difiere de la versión basada en plantillas en que ya no exporta ninguna directiva. En su lugar, utiliza el getter `name` definido en la clase del componente.

Observa que el atributo `required` todavía está presente en la plantilla. Aunque no es necesario para la validación, debe conservarse por razones de accesibilidad.

## Definiendo validadores personalizados

Los validadores integrados no siempre coinciden con el caso de uso exacto de tu aplicación, por lo que a veces necesitas crear un validador personalizado.

Considera la función `forbiddenNameValidator` del ejemplo anterior.
Así es como se ve la definición de esa función.

<docs-code header="shared/forbidden-name.directive.ts (forbiddenNameValidator)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="custom-validator"/>

La función es una fábrica que toma una expresión regular para detectar un nombre prohibido *específico* y devuelve una función validadora.

En esta muestra, el nombre prohibido es "bob", por lo que el validador rechaza cualquier nombre de actor que contenga "bob".
En otro lugar podría rechazar "alice" o cualquier nombre que coincida con la expresión regular configurada.

La fábrica `forbiddenNameValidator` devuelve la función validadora configurada.
Esa función toma un objeto de control de Angular y devuelve *ya sea* null si el valor del control es válido *o* un objeto de error de validación.
El objeto de error de validación típicamente tiene una propiedad cuyo nombre es la clave de validación, `'forbiddenName'`, y cuyo valor es un diccionario arbitrario de valores que podrías insertar en un mensaje de error, `{name}`.

Los validadores asíncronos personalizados son similares a los validadores síncronos, pero deben devolver una Promise u observable que más tarde emita null o un objeto de error de validación.
En el caso de un observable, el observable debe completarse, momento en el cual el formulario usa el último valor emitido para la validación.

### Añadiendo validadores personalizados a formularios reactivos

En formularios reactivos, agrega un validador personalizado pasando la función directamente al `FormControl`.

### Añadiendo validadores personalizados a formularios basados en plantillas

En formularios basados en plantillas, agrega una directiva a la plantilla, donde la directiva envuelve la función validadora.
Por ejemplo, la directiva `ForbiddenValidatorDirective` correspondiente sirve como un envoltorio alrededor del `forbiddenNameValidator`.

Angular reconoce el papel de la directiva en el proceso de validación porque la directiva se registra con el proveedor `NG_VALIDATORS`, como se muestra en el siguiente ejemplo.
`NG_VALIDATORS` es un proveedor predefinido con una colección extensible de validadores.

<docs-code header="shared/forbidden-name.directive.ts (providers)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="directive-providers"/>

La clase de directiva luego implementa la interfaz `Validator`, para que pueda integrarse fácilmente con formularios de Angular.
Aquí está el resto de la directiva para ayudarte a entender cómo todo se une.

<docs-code header="shared/forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="directive"/>

Una vez que `ForbiddenValidatorDirective` esté lista, puedes agregar su selector, `appForbiddenName`, a cualquier elemento de entrada para activarlo.
Por ejemplo:

<docs-code header="template/actor-form-template.component.html (forbidden-name-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="name-input"/>

CONSEJO: Observa que la directiva de validación personalizada se instancia con `useExisting` en lugar de `useClass`.
El validador registrado debe ser *esta instancia* de `ForbiddenValidatorDirective` —la instancia en el formulario con su propiedad `forbiddenName` vinculada a "bob".

Si reemplazaras `useExisting` con `useClass`, entonces estarías registrando una nueva instancia de clase, una que no tiene `forbiddenName`.

## Clases CSS de estado de control

Angular automáticamente refleja muchas propiedades de control en el elemento de control del formulario como clases CSS.
Usa estas clases para estilizar elementos de control de formulario según el estado del formulario.
Las siguientes clases están actualmente soportadas.

* `.ng-valid`
* `.ng-invalid`
* `.ng-pending`
* `.ng-pristine`
* `.ng-dirty`
* `.ng-untouched`
* `.ng-touched`
* `.ng-submitted` $solo elemento de formulario contenedor$

En el siguiente ejemplo, el formulario de actor usa las clases `.ng-valid` y `.ng-invalid` para
establecer el color del borde de cada control de formulario.

<docs-code header="forms.css (status classes)" path="adev/src/content/examples/form-validation/src/assets/forms.css"/>

## Validación entre campos

Un validador entre campos es un [validador personalizado](#defining-custom-validators "Leer sobre validadores personalizados") que compara los valores de diferentes campos en un formulario y los acepta o rechaza en combinación.
Por ejemplo, podrías tener un formulario que ofrece opciones mutuamente incompatibles, de modo que si el usuario puede elegir A o B, pero no ambos.
Algunos valores de campo también podrían depender de otros; un usuario podría estar permitido elegir B solo si A también está elegido.

Los siguientes ejemplos de validación cruzada muestran cómo hacer lo siguiente:

* Validar entrada de formulario reactivo o basado en plantillas según los valores de dos controles hermanos,
* Mostrar un mensaje de error descriptivo después de que el usuario interactuó con el formulario y la validación falló.

Los ejemplos usan validación cruzada para asegurar que los actores no reutilicen el mismo nombre en su rol llenando el Formulario de Actor.
Los validadores hacen esto verificando que los nombres de actor y roles no coincidan.

### Agregar validación cruzada a formularios reactivos

El formulario tiene la siguiente estructura:

<docs-code language="javascript">

const actorForm = new FormGroup({
  'name': new FormControl(),
  'role': new FormControl(),
  'skill': new FormControl()
});
```
Observa que `name` y `role` son controles hermanos.
Para evaluar ambos controles en un solo validador personalizado, debes realizar la validación en un control ancestro común: el `FormGroup`.
Consultas el `FormGroup` para sus controles hijos para que puedas comparar sus valores.

Para agregar un validador al `FormGroup`, pasa el nuevo validador como segundo argumento en la creación.

```javascript
const actorForm = new FormGroup({
  'name': new FormControl(),
  'role': new FormControl(),
  'skill': new FormControl()
}, { validators: unambiguousRoleValidator });
```
El código del validador es el siguiente.

```
El validador `unambiguousRoleValidator` implementa la interfaz `ValidatorFn`.
Toma un objeto de control de Angular como argumento y devuelve null si el formulario es válido, o `ValidationErrors` en caso contrario.

El validador recupera los controles hijos llamando al método [get](api/forms/AbstractControl#get) del `FormGroup`, luego compara los valores de los controles `name` y `role`.

Si los valores no coinciden, el rol es inequívoco, ambos son válidos, y el validador devuelve null.
Si coinciden, el rol del actor es ambiguo y el validador debe marcar el formulario como inválido devolviendo un objeto de error.

Para proporcionar una mejor experiencia de usuario, la plantilla muestra un mensaje de error apropiado cuando el formulario es inválido.

<docs-code header="reactive/actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" visibleRegion="cross-validation-error-message"/>

Este `@if` muestra el error si el `FormGroup` tiene el error de validación cruzada devuelto por el validador `unambiguousRoleValidator`, pero solo si el usuario terminó de [interactuar con el formulario](#control-status-css-classes).

### Agregar validación cruzada a formularios basados en plantillas

Para un formulario basado en plantillas, debes crear una directiva para envolver la función validadora.
Proporcionas esa directiva como el validador usando el [token `NG_VALIDATORS`](/api/forms/NG_VALIDATORS), como se muestra en el siguiente ejemplo.

<docs-code header="shared/unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" visibleRegion="cross-validation-directive"/>

Debes agregar la nueva directiva a la plantilla HTML.
Debido a que el validador debe registrarse en el nivel más alto del formulario, la siguiente plantilla coloca la directiva en la etiqueta `form`.

<docs-code header="template/actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="cross-validation-register-validator"/>

Para proporcionar una mejor experiencia de usuario, aparece un mensaje de error apropiado cuando el formulario es inválido.

Esto es igual tanto en formularios basados en plantillas como reactivos.

## Crear validadores asíncronos

Los validadores asíncronos implementan las interfaces `AsyncValidatorFn` y `AsyncValidator`.
Estos son muy similares a sus contrapartes síncronas, con las siguientes diferencias.

* Las funciones `validate()` deben devolver una Promise u observable,
* El observable devuelto debe ser finito, lo que significa que debe completarse en algún momento.
    Para convertir un observable infinito en uno finito, canaliza el observable a través de un operador de filtrado como `first`, `last`, `take`, o `takeUntil`.

La validación asíncrona ocurre después de la validación síncrona, y se realiza solo si la validación síncrona es exitosa.
Esta verificación permite que los formularios eviten procesos de validación asíncrona potencialmente costosos $como una solicitud HTTP$ si los métodos de validación más básicos ya han encontrado entrada inválida.

Después de que comienza la validación asíncrona, el control del formulario entra en un estado `pending`.
Inspecciona la propiedad `pending` del control y úsala para dar retroalimentación visual sobre la operación de validación en curso.

Un patrón de UI común es mostrar un spinner mientras se realiza la validación asíncrona.
El siguiente ejemplo muestra cómo lograr esto en un formulario basado en plantillas.

<docs-code language="html">

<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator>
@if(model.pending) {
  <app-spinner />
}
```
### Implementar un validador asíncrono personalizado

En el siguiente ejemplo, un validador asíncrono garantiza que los actores sean seleccionados para un rol que aún no está ocupado. 
Los nuevos actores están constantemente audicionando y los actores antiguos se están retirando, por lo que la lista de roles disponibles no se puede recuperar de antemano. 
Para validar la posible entrada de rol, el validador debe iniciar una operación asíncrona para consultar una base de datos central de todos los actores actualmente seleccionados.

El siguiente código crea la clase de validador, `UniqueRoleValidato`r`, que implementa la interfaz `AsyncValidator`.

```
La propiedad `actorsService` se inicializa con una instancia del token `ActorsService`, que define la siguiente interfaz.

<docs-code language="typescript">
interface ActorsService {
  isRoleTaken: (role: string) => Observable<boolean>;
}
```
En una aplicación del mundo real, `ActorsService` sería responsable de hacer una solicitud HTTP a la base de datos de actores para verificar si el rol está disponible.
Desde el punto de vista del validador, la implementación real del servicio no es importante, por lo que el ejemplo puede codificar contra la interfaz `ActorsService`.

A medida que comienza la validación, `UnambiguousRoleValidator` delega al método `isRoleTaken()` de `ActorsService` con el valor actual del control.
En este punto el control se marca como `pending` y permanece en este estado hasta que la cadena observable devuelta del método `validate()` se complete.

El método `isRoleTaken()` despacha una solicitud HTTP que verifica si el rol está disponible, y devuelve `Observable<boolean>` como resultado.
El método `validate()` canaliza la respuesta a través del operador `map` y la transforma en un resultado de validación.

El método luego, como cualquier validador, devuelve `null` si el formulario es válido, y `ValidationErrors` si no lo es.
Este validador maneja cualquier error potencial con el operador `catchError`.
En este caso, el validador trata el error de `isRoleTaken()` como una validación exitosa, porque la falla al hacer una solicitud de validación no necesariamente significa que el rol sea inválido.
Podrías manejar el error de manera diferente y devolver el objeto `ValidationError` en su lugar.

Después de que pasa algo de tiempo, la cadena observable se completa y la validación asíncrona está hecha.
La bandera `pending` se establece en `false`, y la validez del formulario se actualiza.

### Agregar validadores asíncronos a formularios reactivos

Para usar un validador asíncrono en formularios reactivos, comienza inyectando el validador en una propiedad de la clase del componente.

```
Luego, pasa la función validadora directamente al `FormControl` para aplicarla.

En el siguiente ejemplo, la función `validate` de `UnambiguousRoleValidator` se aplica a `roleControl` pasándola a la opción `asyncValidators` del control y vinculándola a la instancia de `UnambiguousRoleValidator` que fue inyectada en `ActorFormReactiveComponent`.
El valor de `asyncValidators` puede ser una sola función validadora asíncrona, o un array de funciones.
Para aprender más sobre las opciones de `FormControl`, consulta la referencia de la API [AbstractControlOptions](api/forms/AbstractControlOptions).

<docs-code path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" visibleRegion="async-validator-usage"/>

### Agregar validadores asíncronos a formularios basados en plantillas

Para usar un validador asíncrono en formularios basados en plantillas, crea una nueva directiva y registra el proveedor `NG_ASYNC_VALIDATORS` en ella.

En el ejemplo de abajo, la directiva inyecta la clase `UniqueRoleValidator` que contiene la lógica de validación real y la invoca en la función `validate`, activada por Angular cuando debe ocurrir la validación.

<docs-code path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" visibleRegion="async-validator-directive"/>

Luego, como con los validadores síncronos, agrega el selector de la directiva a una entrada para activarla.

<docs-code header="template/actor-form-template.component.html (unique-unambiguous-role-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="role-input"/>

### Optimizar el rendimiento de validadores asíncronos

Por defecto, todos los validadores se ejecutan después de cada cambio de valor del formulario.
Con validadores síncronos, esto normalmente no tiene un impacto notable en el rendimiento de la aplicación.
Los validadores asíncronos, sin embargo, comúnmente realizan algún tipo de solicitud HTTP para validar el control.
Despachar una solicitud HTTP después de cada pulsación de tecla podría poner tensión en la API del backend, y debe evitarse si es posible.

Puedes retrasar la actualización de la validez del formulario cambiando la propiedad `updateOn` de `change` (predeterminado) a `submit` o `blur`.

Con formularios basados en plantillas, establece la propiedad en la plantilla.

<docs-code language="html">
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}">
```
Con formularios reactivos, establece la propiedad en la instancia `FormControl`.

```typescript
new FormControl('', {updateOn: 'blur'});
```
## Interacción con validación nativa de formularios HTML

Por defecto, Angular deshabilita la [validación nativa de formularios HTML](https://developer.mozilla.org/docs/Web/Guide/HTML/Constraint_validation) agregando el atributo `novalidate` en el `<form>` contenedor y usa directivas para hacer coincidir estos atributos con funciones validadoras en el framework.
Si quieres usar validación nativa **en combinación** con validación basada en Angular, puedes volver a habilitarla con la directiva `ngNativeValidate`.
Consulta la [documentación de la API](api/forms/NgForm#native-dom-validation-ui) para más detalles.
# Construir formularios dinámicos

Muchos formularios, como los cuestionarios, pueden ser muy similares entre sí en formato y propósito. 
Para hacer que sea más rápido y fácil generar diferentes versiones de dicho formulario, puedes crear una _plantilla de formulario dinámico_ basada en metadatos que describen el modelo de objeto de negocio. 
Luego, utiliza la plantilla para generar nuevos formularios automáticamente, de acuerdo con los cambios en el modelo de datos.

La técnica es particularmente útil cuando tienes un tipo de formulario cuyo contenido debe cambiar frecuentemente para cumplir con requisitos de negocio y regulatorios que cambian rápidamente.
Un caso de uso típico es un cuestionario.
Podrías necesitar obtener entrada de usuarios en diferentes contextos.
El formato y estilo de los formularios que ve un usuario deben permanecer constantes, mientras que las preguntas reales que necesitas hacer varían con el contexto.

En este tutorial construirás un formulario dinámico que presenta un cuestionario básico.
Construyes una aplicación en línea para héroes que buscan empleo.
La agencia está constantemente ajustando el proceso de aplicación, pero usando el formulario dinámico
puedes crear los nuevos formularios sobre la marcha sin cambiar el código de la aplicación.

El tutorial te guía a través de los siguientes pasos.

1. Habilitar formularios reactivos para un proyecto.
1. Establecer un modelo de datos para representar controles de formulario.
1. Poblar el modelo con datos de muestra.
1. Desarrollar un componente para crear controles de formulario dinámicamente.

El formulario que creas utiliza validación de entrada y estilos para mejorar la experiencia del usuario. 
Tiene un botón de envío que solo se habilita cuando toda la entrada del usuario es válida, y marca la entrada no válida con codificación de colores y mensajes de error.

La versión básica puede evolucionar para admitir una variedad más amplia de preguntas, un renderizado más elegante y una mejor experiencia de usuario.

## Habilitar formularios reactivos para tu proyecto

Los formularios dinámicos se basan en formularios reactivos.

Para que la aplicación tenga acceso a las directivas de formularios reactivos, importa `ReactiveFormsModule` de la biblioteca `@angular/forms` en los componentes necesarios.
## Crea un modelo de objeto de formulario

Un formulario dinámico requiere un modelo de objeto que pueda describir todos los escenarios necesarios para la funcionalidad del formulario.
El formulario de solicitud de héroe de ejemplo es un conjunto de preguntas, es decir, cada control en el formulario debe hacer una pregunta y aceptar una respuesta.

El modelo de datos para este tipo de formulario debe representar una pregunta.
El ejemplo incluye el `DynamicFormQuestionComponent`, que define una pregunta como el objeto base del modelo.

El siguiente `QuestionBase` es una clase base para un conjunto de controles que pueden representar la pregunta y su respuesta en el formulario.

<docs-code header="src/app/question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>

### Define clases de control

Desde esta base, el ejemplo deriva dos nuevas clases, `TextboxQuestion` y `DropdownQuestion`, que representan diferentes tipos de control.
Cuando creas la plantilla del formulario en el siguiente paso, instancias estos tipos específicos de pregunta para renderizar los controles apropiados dinámicamente.

El tipo de control `TextboxQuestion` se representa en una plantilla de formulario usando un elemento `<input>`. Presenta una pregunta y permite a los usuarios introducir datos. El atributo `type` del elemento se define basado en el campo `type` especificado en el argumento `options` (por ejemplo `text`, `email`, `url`).

<docs-code header="question-textbox.ts" path="adev/src/content/examples/dynamic-form/src/app/question-textbox.ts"/>

El tipo de control `DropdownQuestion` presenta una lista de opciones en una caja de selección.

<docs-code header="question-dropdown.ts" path="adev/src/content/examples/dynamic-form/src/app/question-dropdown.ts"/>

### Compón grupos de formulario

Un formulario dinámico usa un servicio para crear conjuntos agrupados de controles de entrada, basado en el modelo del formulario.
El siguiente `QuestionControlService` recopila un conjunto de instancias de `FormGroup` que consumen los metadatos del modelo de preguntas.
Puedes especificar valores por defecto y reglas de validación.

<docs-code header="src/app/question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>

## Compón el contenido del formulario dinámico

El formulario dinámico se representa mediante un componente contenedor, que se agrega en un paso posterior.
Cada pregunta está representada en la plantilla del componente del formulario por una etiqueta `<app-question>`, que coincide con una instancia de `DynamicFormQuestionComponent`.

El `DynamicFormQuestionComponent` es responsable de renderizar los detalles de una pregunta individual basado en valores en el objeto de pregunta vinculado a datos.
El formulario se basa en una directiva [`[formGroup]`](api/forms/FormGroupDirective "Referencia de API") para conectar el HTML de la plantilla a los objetos de control subyacentes.
El `DynamicFormQuestionComponent` crea grupos de formulario y los puebla con controles definidos en el modelo de pregunta, especificando reglas de visualización y validación.
El objetivo del `DynamicFormQuestionComponent` es presentar tipos de pregunta definidos en tu modelo.
Solo tienes dos tipos de preguntas en este punto pero puedes imaginar muchas más.
El bloque `@switch` en la plantilla determina qué tipo de pregunta se debe mostrar.
El switch usa directivas con los selectores [`formControlName`](api/forms/FormControlName "Referencia de API de la directiva FormControlName") y [`formGroup`](api/forms/FormGroupDirective "Referencia de API de FormGroupDirective").
Ambas directivas están definidas en `ReactiveFormsModule`.

### Proporcionar datos

Se requiere otro servicio para proporcionar un conjunto específico de preguntas a partir del cual se construirá un formulario individual.
Para este ejercicio creas el `QuestionService` para proporcionar este array de preguntas desde los datos de muestra codificados.
En una aplicación del mundo real, el servicio podría obtener datos de un sistema backend.
El punto clave, sin embargo, es que controlas las preguntas de aplicación de trabajo de héroe completamente a través de los objetos devueltos de `QuestionService`.
Para mantener el cuestionario a medida que cambian los requisitos, solo necesitas agregar, actualizar y eliminar objetos del array `questions`.

El `QuestionService` proporciona un conjunto de preguntas en forma de un array vinculado a `input()` questions.

<docs-code header="src/app/question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/>

## Crea una plantilla de formulario dinámico

El componente `DynamicFormComponent` es el punto de entrada y el contenedor principal para el formulario, que se representa usando `<app-dynamic-form>` en una plantilla.

El componente `DynamicFormComponent` presenta una lista de preguntas vinculando cada una a un elemento `<app-question>` que coincide con el `DynamicFormQuestionComponent`.
### Muestra el formulario

Para mostrar una instancia del formulario dinámico, la plantilla shell `AppComponent` pasa el array `questions` devuelto por el `QuestionService` al componente contenedor del formulario, `<app-dynamic-form>`.

<docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/>

Esta separación de modelo y datos te permite reutilizar los componentes para cualquier tipo de encuesta, siempre que sea compatible con el modelo de objeto _question_.

### Asegurando datos válidos

La plantilla del formulario usa vinculación dinámica de datos de metadatos para renderizar el formulario sin hacer suposiciones codificadas sobre preguntas específicas.
Agrega tanto metadatos de control como criterios de validación dinámicamente.

Para garantizar que la entrada sea válida, el botón _Save_ está deshabilitado hasta que el formulario está en un estado válido.
Cuando el formulario es válido, haz clic en _Save_ y la aplicación renderiza los valores actuales del formulario como JSON.

La siguiente figura muestra el formulario final.

## Próximos pasos
Angular Router (`@angular/router`) es la librería oficial para gestionar la navegación en aplicaciones de Angular y una parte fundamental del framework. Se incluye de forma predeterminada en todos los proyectos creados por Angular CLI.

## ¿Por qué es necesario el enrutamiento en una SPA?

Cuando navegas a una URL en tu navegador web, el navegador normalmente hace una petición de red a un servidor web y muestra la página HTML devuelta. Cuando navegas a una URL diferente, como hacer clic en un enlace, el navegador hace otra petición de red y reemplaza toda la página con una nueva.

Una aplicación de página única (SPA) difiere en que el navegador solo hace una petición a un servidor web para la primera página, el `index.html`. Después de eso, un router del lado del cliente toma el control, controlando qué contenido se muestra según la URL. Cuando un usuario navega a una URL diferente, el router actualiza el contenido de la página en el lugar sin disparar una recarga completa de la página.

## Cómo Angular gestiona el enrutamiento

El enrutamiento en Angular se compone de tres partes principales:

1. **Routes** definen qué componente se muestra cuando un usuario visita una URL específica.
2. **Outlets** son marcadores de posición en tus plantillas que cargan y renderizan dinámicamente componentes según la ruta activa.
3. **Links** proporcionan una forma para que los usuarios naveguen entre diferentes rutas en tu aplicación sin disparar una recarga completa de la página.

Además, la librería de enrutamiento en Angular ofrece funcionalidad adicional como:

- Rutas anidadas
- Navegación programática
- Parámetros de ruta, consultas y comodines
- Información de ruta activada con `ActivatedRoute`
- Efectos de transición de vista
- Navigation guards

## Próximos pasos

Aprende sobre cómo puedes [definir rutas usando Angular router](/guide/routing/define-routes).
# Definir rutas

Las rutas sirven como los bloques de construcción fundamentales para la navegación dentro de una aplicación Angular.

## ¿Qué son las rutas?

En Angular, una **ruta** es un objeto que define qué componente debe renderizar para una ruta URL específica o patrón, así como opciones de configuración adicionales sobre qué sucede cuando un usuario navega a esa URL.

Aquí hay un ejemplo básico de una ruta:

```typescript
import { AdminPage } from './app-admin/app-admin.component';

const adminPage = {
  path: 'admin',
  component: AdminPage
}
```

Para esta ruta, cuando un usuario visita la ruta `/admin`, la aplicación mostrará el componente `AdminPage`.

### Gestionando rutas en tu aplicación

La mayoría de los proyectos definen rutas en un archivo separado que contiene `routes` en el nombre del archivo.

Una colección de rutas se ve así:

```typescript
import { Routes } from '@angular/router';
import { HomePage } from './home-page/home-page.component';
import { AdminPage } from './about-page/admin-page.component';

export const routes: Routes = [
  {
    path: '',
    component: HomePage,
  },
  {
    path: 'admin',
    component: AdminPage,
  },
];
```

Consejo: Si generaste un proyecto con Angular CLI, tus rutas están definidas en `src/app/app.routes.ts`.

### Agregando el router a tu aplicación

Al hacer bootstrap de una aplicación Angular sin Angular CLI, puedes pasar un objeto de configuración que incluye un array `providers`.

Dentro del array `providers`, puedes agregar el router de Angular a tu aplicación agregando una llamada a la función `provideRouter` con tus rutas.

```typescript
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';

import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    // ...
  ]
};
```

## Rutas URL

### Rutas URL estáticas

Las rutas URL estáticas se refieren a rutas con rutas predefinidas que no cambian según parámetros dinámicos. Estas son rutas que coinciden exactamente con un string `path` y tienen un resultado fijo.

Ejemplos de esto incluyen:

- "/admin"
- "/blog"
- "/settings/account"

### Definir rutas URL con parámetros de ruta

Las URLs parametrizadas te permiten definir rutas dinámicas que permiten múltiples URLs al mismo componente mientras muestran datos dinámicamente según los parámetros en la URL.

Puedes definir este tipo de patrón agregando parámetros al string `path` de tu ruta y prefijando cada parámetro con el carácter dos puntos (`:`).

IMPORTANTE: Los parámetros son distintos de la información en el [query string](https://en.wikipedia.org/wiki/Query_string) de la URL.
Aprende más sobre [parámetros de consulta en Angular en esta guía](/guide/routing/read-route-state#query-parameters).

El siguiente ejemplo muestra un componente de perfil de usuario basado en el id de usuario pasado a través de la URL.

```typescript
import { Routes } from '@angular/router';
import { UserProfile } from './user-profile/user-profile;

const routes: Routes = [
  { path: 'user/:id', component: UserProfile }
];
```

En este ejemplo, URLs como `/user/leeroy` y `/user/jenkins` renderizan el componente `UserProfile`. Este componente puede entonces leer el parámetro `id` y usarlo para realizar trabajo adicional, como obtener datos. Consulta la [guía de lectura de estado de ruta](/guide/routing/read-route-state) para detalles sobre la lectura de parámetros de ruta.

Los nombres de parámetros de ruta válidos deben comenzar con una letra (a-z, A-Z) y solo pueden contener:

- Letras (a-z, A-Z)
- Números (0-9)
- Guión bajo (\_)
- Guión (-)

También puedes definir rutas con múltiples parámetros:

```typescript
import { Routes } from '@angular/router';
import { UserProfile } from './user-profile/user-profile.component';
import { SocialMediaFeed } from './user-profile/social–media-feed.component';

const routes: Routes = [
  { path: 'user/:id/:social-media', component: SocialMediaFeed },
  { path: 'user/:id/', component: UserProfile },
];
```

Con esta nueva ruta, los usuarios pueden visitar `/user/leeroy/youtube` y `/user/leeroy/bluesky` y ver feeds de redes sociales respectivos basados en el parámetro para el usuario leeroy.

Consulta [Leer estado de ruta](/guide/routing/read-route-state) para detalles sobre la lectura de parámetros de ruta.

### Comodines

Cuando necesitas capturar todas las rutas para una ruta específica, la solución es una ruta comodín que se define con el doble asterisco (`**`).

Un ejemplo común es definir un componente de Página No Encontrada.

```typescript
import { Home } from './home/home.component';
import { UserProfile } from './user-profile/user-profile.component';
import { NotFound } from './not-found/not-found.component';

const routes: Routes = [
  { path: 'home', component: Home },
  { path: 'user/:id', component: UserProfile },
  { path: '**', component: NotFound }
];
```

En este array de rutas, la aplicación muestra el componente `NotFound` cuando el usuario visita cualquier ruta fuera de `home` y `user/:id`.

Consejo: Las rutas comodín típicamente se colocan al final de un array de rutas.

## Cómo Angular hace coincidir URLs

Cuando defines rutas, el orden es importante porque Angular usa una estrategia de primera coincidencia gana. Esto significa que una vez que Angular hace coincidir una URL con un `path` de ruta, deja de verificar más rutas. Como resultado, siempre coloca rutas más específicas antes que rutas menos específicas.

El siguiente ejemplo muestra rutas definidas de más específica a menos específica:

```typescript
const routes: Routes = [
  { path: '', component: HomeComponent },              // Ruta vacía
  { path: 'users/new', component: NewUserComponent },  // Estática, más específica
  { path: 'users/:id', component: UserDetailComponent }, // Dinámica
  { path: 'users', component: UsersComponent },        // Estática, menos específica
  { path: '**', component: NotFoundComponent }         // Comodín - siempre último
];
```

Si un usuario visita `/users/new`, el router de Angular pasaría por los siguientes pasos:

1. Verifica `''` - no coincide
1. Verifica `users/new` - ¡coincide! Se detiene aquí
1. Nunca alcanza `users/:id` aunque podría coincidir
1. Nunca alcanza `users`
1. Nunca alcanza `**`

## Estrategias de carga de componentes de ruta

Entender cómo y cuándo se cargan los componentes en el enrutamiento en Angular es crucial para construir aplicaciones web responsivas. Angular ofrece dos estrategias principales para controlar el comportamiento de carga de componentes:

1. **Carga eager (inmediata)**: Componentes que se cargan inmediatamente
2. **Carga lazy (diferida)**: Componentes cargados solo cuando son necesarios

Cada enfoque ofrece ventajas distintas para diferentes escenarios.

### Componentes cargados de forma eager

Cuando defines una ruta con la propiedad `component`, el componente referenciado se carga de forma eager como parte del mismo bundle de JavaScript que la configuración de ruta.

```typescript
import { Routes } from "@angular/router";
import { HomePage } from "./components/home/home-page"
import { LoginPage } from "./components/auth/login-page"

export const routes: Routes = [
  // HomePage y LoginPage están ambos referenciados directamente en esta configuración,
  // por lo que su código se incluye de forma eager en el mismo bundle de JavaScript que este archivo.
  {
    path: "",
    component: HomePage
  },
  {
    path: "login",
    component: LoginPage
  }
]
```

Cargar componentes de ruta de forma eager de esta manera significa que el navegador tiene que descargar y parsear todo el JavaScript para estos componentes como parte de la carga inicial de tu página, pero los componentes están disponibles para Angular inmediatamente.

Aunque incluir más JavaScript en la carga inicial de tu página conduce a tiempos de carga inicial más lentos, esto puede conducir a transiciones más fluidas a medida que el usuario navega por una aplicación.

### Componentes cargados de forma lazy

Puedes usar la propiedad `loadComponent` para cargar de forma lazy el JavaScript para una ruta solo en el punto en que esa ruta se vuelva activa.

```typescript
import { Routes } from "@angular/router";

export const routes: Routes = [
  // Los componentes HomePage y LoginPage se cargan de forma lazy en el punto en que
  // sus rutas correspondientes se vuelven activas.
  {
    path: 'login',
    loadComponent: () => import('./components/auth/login-page').then(m => m.LoginPage)
  },
  {
    path: '',
    loadComponent: () => import('./components/home/home-page').then(m => m.HomePage)
  }
]
```

La propiedad `loadComponent` acepta una función loader que retorna una Promise que se resuelve a un componente de Angular. En la mayoría de los casos, esta función usa la [API de importación dinámica estándar de JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import). Sin embargo, puedes usar cualquier función loader asíncrona arbitraria.

Cargar rutas de forma lazy puede mejorar significativamente la velocidad de carga de tu aplicación Angular al eliminar grandes porciones de JavaScript del bundle inicial. Estas porciones de tu código se compilan en "chunks" de JavaScript separados que el router solicita solo cuando el usuario visita la ruta correspondiente.

### ¿Debo usar una ruta eager o lazy?

Hay muchos factores a considerar al decidir si una ruta debe ser eager o lazy.

En general, se recomienda la carga eager para la(s) página(s) de destino principal(es) mientras que otras páginas se cargarían de forma lazy.

Nota: Si bien las rutas lazy tienen el beneficio de rendimiento inicial de reducir la cantidad de datos iniciales solicitados por el usuario, agrega futuras peticiones de datos que podrían ser indeseables. Esto es particularmente cierto cuando se trata de carga lazy anidada en múltiples niveles, lo que puede impactar significativamente el rendimiento.

## Redirecciones

Puedes definir una ruta que redirige a otra ruta en lugar de renderizar un componente:

```typescript
import { BlogComponent } from './home/blog.component';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: BlogComponent
  },
];
```

Si modificas o eliminas una ruta, algunos usuarios aún pueden hacer clic en enlaces desactualizados o marcadores a esa ruta. Puedes agregar una redirección para dirigir a esos usuarios a una ruta alternativa apropiada en lugar de una página "no encontrada".

## Títulos de página

Puedes asociar un **título** con cada ruta. Angular actualiza automáticamente el [título de página](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) cuando una ruta se activa. Siempre define títulos de página apropiados para tu aplicación, ya que estos títulos son necesarios para crear una experiencia accesible.

```ts
import { Routes } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { AboutComponent } from './about/about.component';
import { ProductsComponent } from './products/products.component';

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    title: 'Home Page'
  },
  {
    path: 'about',
    component: AboutComponent,
    title: 'About Us'
  },
];
```

La propiedad `title` de la página puede establecerse dinámicamente a una función resolver usando [`ResolveFn`](/api/router/ResolveFn).

```ts
const titleResolver: ResolveFn<string> = (route) => route.queryParams['id'];
const routes: Routes = [
   ...
  {
    path: 'products',
    component: ProductsComponent,
    title: titleResolver,
  }
];

```

Los títulos de ruta también se pueden establecer a través de un servicio que extiende la clase abstracta [`TitleStrategy`](/api/router/TitleStrategy). Por defecto, Angular usa el [`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy).

## Proveedores a nivel de ruta para inyección de dependencias

Cada ruta tiene una propiedad `providers` que te permite proporcionar dependencias al contenido de esa ruta a través de [inyección de dependencias](/guide/di).

Escenarios comunes donde esto puede ser útil incluyen aplicaciones que tienen diferentes servicios según si el usuario es admin o no.

```typescript
export const ROUTES: Route[] = [
  {
    path: 'admin',
    providers: [
      AdminService,
      {provide: ADMIN_API_KEY, useValue: '12345'},
    ],
    children: [
      {path: 'users', component: AdminUsersComponent},
      {path: 'teams', component: AdminTeamsComponent},
    ],
  },
  // ... otras rutas de aplicación que no
  //     tienen acceso a ADMIN_API_KEY o AdminService.
];
```

En este ejemplo de código, la ruta `admin` contiene una propiedad de datos protegida de `ADMIN_API_KEY` que solo está disponible para los hijos dentro de su sección. Como resultado, ninguna otra ruta podrá acceder a los datos proporcionados a través de `ADMIN_API_KEY`.

Consulta la [guía de Inyección de dependencias](/guide/di) para más información sobre proveedores e inyección en Angular.

## Asociando datos con rutas

Los datos de ruta te permiten adjuntar información adicional a las rutas. Puedes configurar cómo se comportan los componentes según estos datos.

Hay dos formas de trabajar con datos de ruta: datos estáticos que permanecen constantes, y datos dinámicos que pueden cambiar según condiciones de tiempo de ejecución.

### Datos estáticos

Puedes asociar datos estáticos arbitrarios con una ruta a través de la propiedad `data` para centralizar cosas como metadatos específicos de ruta (por ejemplo, seguimiento de analytics, permisos, etc.):

```typescript
import { Routes } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { AboutComponent } from './about/about.component';
import { ProductsComponent } from './products/products.component';

const routes: Routes = [
  {
    path: 'about',
    component: AboutComponent,
    data: { analyticsId: '456' }
  },
  {
    path: '',
    component: HomeComponent,
    data: { analyticsId: '123' }
  }
];
```

En este ejemplo de código, la página de inicio y la página about están configuradas con un `analyticsId` específico que luego se usaría en sus respectivos componentes para el seguimiento de analytics de página.

Puedes leer estos datos estáticos inyectando el `ActivatedRoute`. Consulta [Leer estado de ruta](/guide/routing/read-route-state) para más detalles.

### Datos dinámicos con data resolvers

Cuando necesitas proporcionar datos dinámicos a una ruta, consulta la [guía sobre resolvers de datos de ruta](/guide/routing/data-resolvers).

## Rutas anidadas

Las rutas anidadas, también conocidas como rutas hijas, son una técnica común para gestionar rutas de navegación más complejas donde un componente tiene una sub-vista que cambia según la URL.

Puedes agregar rutas hijas a cualquier definición de ruta con la propiedad `children`:

```typescript
const routes: Routes = [
  {
    path: 'product/:id',
    component: ProductComponent,
    children: [
      {
        path: 'info',
        component: ProductInfoComponent
      },
      {
        path: 'reviews',
        component: ProductReviewsComponent
      }
    ]
  }
]
```

El ejemplo anterior define una ruta para una página de producto que permite a un usuario cambiar si se muestra la información del producto o las reseñas según la url.

La propiedad `children` acepta un array de objetos `Route`.

Para mostrar rutas hijas, el componente padre (`ProductComponent` en el ejemplo anterior) incluye su propio `<router-outlet>`.

```html

<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

Después de agregar rutas hijas a la configuración y agregar un `<router-outlet>` al componente, la navegación entre URLs que coinciden con las rutas hijas actualiza solo el outlet anidado.

## Próximos pasos

Aprende cómo [mostrar el contenido de tus rutas con Outlets](/guide/routing/show-routes-with-outlets).
# Mostrar rutas con outlets

La directiva `RouterOutlet` es un marcador de posición que marca la ubicación donde el router debe renderizar el componente para la URL actual.

```html
<app-header />
<router-outlet />  
<app-footer />
```

```typescript
import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css'
})
export class AppComponent {}
```

En este ejemplo, si una aplicación tiene las siguientes rutas definidas:

```typescript
import { Routes } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { ProductsComponent } from './products/products.component';

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    title: 'Home Page'
  },
  {
    path: 'products',
    component: ProductsComponent,
    title: 'Our Products'
  }
];
```

Cuando un usuario visita `/products`, Angular renderiza lo siguiente:

```html
<app-header />
<app-products />
<app-footer />
```

Si el usuario regresa a la página de inicio, entonces Angular renderiza:

```html
<app-header />
<app-home />
<app-footer />
```

Al mostrar una ruta, el elemento `<router-outlet>` permanece presente en el DOM como un punto de referencia para futuras navegaciones. Angular inserta el contenido enrutado justo después del elemento outlet como un hermano.

```html

<app-header />
<router-outlet />
<app-footer />
```

```html

<app-header>...</app-header>
<router-outlet></router-outlet>
<app-admin-page>...</app-admin-page>
<app-footer>...</app-footer>
```

## Anidando rutas con rutas hijas

A medida que tu aplicación crece en complejidad, es posible que desees crear rutas que sean relativas a un componente distinto de tu componente raíz. Esto te permite crear experiencias donde solo parte de la aplicación cambia cuando la URL cambia, en lugar de que los usuarios sientan que toda la página se actualiza.

Estos tipos de rutas anidadas se llaman rutas hijas. Esto significa que estás agregando un segundo `<router-outlet>` a tu aplicación, porque es además del `<router-outlet>` en AppComponent.

En este ejemplo, el componente `Settings` mostrará el panel deseado según lo que el usuario seleccione. Una de las cosas únicas que notarás sobre las rutas hijas es que el componente a menudo tiene su propio `<nav>` y `<router-outlet>`.

```html
<h1>Settings</h1>
<nav>
  <ul>
    <li><a routerLink="profile">Profile</a></li>
    <li><a routerLink="security">Security</a></li>
  </ul>
</nav>
<router-outlet />
```

Una ruta hija es como cualquier otra ruta, en que necesita tanto un `path` como un `component`. La única diferencia es que colocas las rutas hijas en un array children dentro de la ruta padre.

```typescript
const routes: Routes = [
  {
    path: 'settings-component',
    component: SettingsComponent, // este es el componente con el <router-outlet> en la plantilla
    children: [
      {
        path: 'profile', // ruta de la ruta hija
        component: ProfileComponent, // componente de ruta hija que el router renderiza
      },
      {
        path: 'security',
        component: SecurityComponent, // otro componente de ruta hija que el router renderiza
      },
    ],
  },
];
```

Una vez que tanto las `routes` como el `<router-outlet>` estén configurados correctamente, ¡tu aplicación ahora está usando rutas anidadas!

## Rutas secundarias con outlets nombrados

Las páginas pueden tener múltiples outlets— puedes asignar un nombre a cada outlet para especificar qué contenido pertenece a qué outlet.

```html
<app-header />
<router-outlet />
<router-outlet name='read-more' />
<router-outlet name='additional-actions' />
<app-footer />
```

Cada outlet debe tener un nombre único. El nombre no se puede establecer ni cambiar dinámicamente. Por defecto, el nombre es `'primary'`.

Angular hace coincidir el nombre del outlet con la propiedad `outlet` definida en cada ruta:

```typescript
{
  path: 'user/:id',
  component: UserDetails,
  outlet: 'additional-actions'
}
```

## Eventos del ciclo de vida del outlet

Hay cuatro eventos del ciclo de vida que un router outlet puede emitir:

| Evento       | Descripción                                                                       |
| ------------ | --------------------------------------------------------------------------------- |
| `activate`   | Cuando se instancia un nuevo componente                                           |
| `deactivate` | Cuando se destruye un componente                                                  |
| `attach`     | Cuando el `RouteReuseStrategy` instruye al outlet a adjuntar el subárbol          |
| `detach`     | Cuando el `RouteReuseStrategy` instruye al outlet a desconectar el subárbol       |

Puedes agregar escuchadores de eventos con la sintaxis estándar de vinculación de eventos:

```html
<router-outlet
  (activate)='onActivate($event)'
  (deactivate)='onDeactivate($event)'
  (attach)='onAttach($event)'
  (detach)='onDetach($event)'
/>
```

Consulta la [documentación de la API para RouterOutlet](/api/router/RouterOutlet?tab=api) si deseas aprender más.

## Próximos pasos

Aprende cómo [navegar a rutas](/guide/routing/navigate-to-routes) con Angular Router.
# Navegar a rutas

La directiva RouterLink es el enfoque declarativo de Angular para la navegación. Te permite usar elementos anchor estándar (`<a>`) que se integran sin problemas con el sistema de enrutamiento en Angular.

## Cómo usar RouterLink

En lugar de usar elementos anchor regulares `<a>` con un atributo `href`, agregas una directiva RouterLink con la ruta apropiada para aprovechar el enrutamiento en Angular.
```typescript
import {RouterLink} from '@angular/router';
@Component({
  template: `
    <nav>
      <a routerLink="/user-profile">User profile</a>
      <a routerLink="/settings">Settings</a>
    </nav>
  `
  imports: [RouterLink],
  ...
})
export class App {}
```

### Usando enlaces absolutos o relativos

Las **URLs relativas** en el enrutamiento en Angular te permiten definir rutas de navegación relativas a la ubicación de la ruta actual. Esto contrasta con las **URLs absolutas** que contienen la ruta completa con el protocolo (por ejemplo, `http://`) y el **dominio raíz** (por ejemplo, `google.com`).

```html

<a href="https://www.angular.dev/essentials">Angular Essentials Guide</a>

<a href="/essentials">Angular Essentials Guide</a>
```

En este ejemplo, el primer ejemplo contiene la ruta completa con el protocolo (es decir, `https://`) y el dominio raíz (es decir, `angular.dev`) explícitamente definidos para la página de essentials. En contraste, el segundo ejemplo asume que el usuario ya está en el dominio raíz correcto para `/essentials`.

En términos generales, se prefieren las URLs relativas porque son más mantenibles en todas las aplicaciones porque no necesitan conocer su posición absoluta dentro de la jerarquía de enrutamiento.

### Cómo funcionan las URLs relativas

El enrutamiento en Angular tiene dos sintaxis para definir URLs relativas: strings y arrays.

```html

<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

ÚTIL: Pasar un string es la forma más común de definir URLs relativas.

Cuando necesitas definir parámetros dinámicos en una URL relativa, usa la sintaxis de array:

```html
<a [routerLink]="['user', currentUserId]">Current User</a>
```

Además, el enrutamiento en Angular te permite especificar si quieres que la ruta sea relativa a la URL actual o al dominio raíz según si la ruta relativa tiene o no el prefijo de barra diagonal (`/`).

Por ejemplo, si el usuario está en `example.com/settings`, aquí está cómo se pueden definir diferentes rutas relativas para varios escenarios:

```html

<a routerLink="notifications">Notifications</a>
<a routerLink="/settings/notifications">Notifications</a>

<a routerLink="/team/123/user/456">User 456</a>
<a [routerLink]="['/team', teamId, 'user', userId]">Current User</a>"
```

## Navegación programática a rutas

Mientras que `RouterLink` maneja la navegación declarativa en templates, Angular proporciona navegación programática para escenarios donde necesitas navegar basándote en lógica, acciones del usuario o estado de la aplicación. Al inyectar `Router`, puedes navegar dinámicamente a rutas, pasar parámetros y controlar el comportamiento de navegación en tu código TypeScript.

### `router.navigate()`

Puedes usar el método `router.navigate()` para navegar programáticamente entre rutas especificando un array de ruta URL.

```typescript
import { Router } from '@angular/router';

@Component({
  selector: 'app-dashboard',
  template: `
    <button (click)="navigateToProfile()">View Profile</button>
  `
})
export class AppDashboard {
  private router = inject(Router);

navigateToProfile() {
    // Navegación estándar
    this.router.navigate(['/profile']);

// Con parámetros de ruta
    this.router.navigate(['/users', userId]);

// Con parámetros de consulta
    this.router.navigate(['/search'], {
      queryParams: { category: 'books', sort: 'price' }
    });
  }
}
```

`router.navigate()` soporta escenarios de enrutamiento simples y complejos, permitiéndote pasar parámetros de ruta, [parámetros de consulta](/guide/routing/read-route-state#query-parameters), y controlar el comportamiento de navegación.

También puedes construir rutas de navegación dinámicas relativas a la ubicación de tu componente en el árbol de enrutamiento usando la opción `relativeTo`.

```typescript
import { Router, ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-user-detail',
  template: `
    <button (click)="navigateToEdit()">Edit User</button>
    <button (click)="navigateToParent()">Back to List</button>
  `
})
export class UserDetailComponent {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {}

// Navegar a una ruta hermana
  navigateToEdit() {
    // Desde: /users/123
    // A:     /users/123/edit
    this.router.navigate(['edit'], { relativeTo: this.route });
  }

// Navegar al padre
  navigateToParent() {
    // Desde: /users/123
    // A:     /users
    this.router.navigate(['..'], { relativeTo: this.route });
  }
}
```

### `router.navigateByUrl()`

El método `router.navigateByUrl()` proporciona una forma directa de navegar programáticamente usando strings de ruta URL en lugar de segmentos de array. Este método es ideal cuando tienes una ruta URL completa y necesitas realizar navegación absoluta, especialmente cuando trabajas con URLs proporcionadas externamente o escenarios de deep linking.

```typescript
// Navegación de ruta estándar
router.navigateByUrl('/products);

// Navegar a ruta anidada
router.navigateByUrl('/products/featured');

// URL completa con parámetros y fragmento
router.navigateByUrl('/products/123?view=details#reviews');

// Navegar con parámetros de consulta
router.navigateByUrl('/search?category=books&sortBy=price');
```

En caso de que necesites reemplazar la URL actual en el historial, `navigateByUrl` también acepta un objeto de configuración que tiene una opción `replaceUrl`.

```typescript
// Reemplazar URL actual en el historial
router.navigateByUrl('/checkout', {
  replaceUrl: true
});
```

## Próximos pasos

Aprende cómo [leer estado de ruta](/guide/routing/read-route-state) para crear componentes responsivos y conscientes del contexto.
# Leer estado de ruta

El Router de Angular te permite leer y usar información asociada con una ruta para crear componentes responsivos y conscientes del contexto.

## Obtener información sobre la ruta actual con ActivatedRoute

`ActivatedRoute` es un servicio de `@angular/router` que proporciona toda la información asociada con la ruta actual.

```typescript
import { Component } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-product',
})
export class ProductComponent {
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    console.log(this.activatedRoute);
  }
}
```

El `ActivatedRoute` puede proporcionar diferente información sobre la ruta. Algunas propiedades comunes incluyen:

| Propiedad     | Detalles                                                                                                                                      |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`         | Un `Observable` de las rutas de ruta, representadas como un array de strings para cada parte de la ruta de ruta.                             |
| `data`        | Un `Observable` que contiene el objeto `data` proporcionado para la ruta. También contiene cualquier valor resuelto del guard de resolución. |
| `params`      | Un `Observable` que contiene los parámetros requeridos y opcionales específicos de la ruta.                                                  |
| `queryParams` | Un `Observable` que contiene los parámetros de consulta disponibles para todas las rutas.                                                    |

Consulta los [docs de la API de `ActivatedRoute`](/api/router/ActivatedRoute) para una lista completa de lo que puedes acceder dentro de la ruta.

## Entendiendo snapshots de ruta

Las navegaciones de página son eventos a lo largo del tiempo, y puedes acceder al estado del router en un momento dado recuperando un snapshot de ruta.

Los snapshots de ruta contienen información esencial sobre la ruta, incluyendo sus parámetros, datos y rutas hijas. Además, los snapshots son estáticos y no reflejarán cambios futuros.

Aquí hay un ejemplo de cómo accederías a un snapshot de ruta:

```typescript
import { ActivatedRoute, ActivatedRouteSnapshot } from '@angular/router';

@Component({ ... })
export class UserProfileComponent {
  readonly userId: string;
  private route = inject(ActivatedRoute);

constructor() {
    // URL de ejemplo: https://www.angular.dev/users/123?role=admin&status=active#contact

// Acceder a parámetros de ruta desde snapshot
    this.userId = this.route.snapshot.paramMap.get('id');

// Acceder a múltiples elementos de ruta
    const snapshot = this.route.snapshot;
    console.log({
      url: snapshot.url,           // https://www.angular.dev
      // Objeto de parámetros de ruta: {id: '123'}
      params: snapshot.params,
      // Objeto de parámetros de consulta: {role: 'admin', status: 'active'}
      queryParams: snapshot.queryParams,  // Parámetros de consulta
    });
  }
}
```

Consulta los [docs de la API de `ActivatedRoute`](/api/router/ActivatedRoute) y los [docs de la API de `ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) para una lista completa de todas las propiedades que puedes acceder.

## Leyendo parámetros en una ruta

Hay dos tipos de parámetros que los desarrolladores pueden utilizar desde una ruta: parámetros de ruta y parámetros de consulta.

### Parámetros de ruta

Los parámetros de ruta te permiten pasar datos a un componente a través de la URL. Esto es útil cuando quieres mostrar contenido específico basado en un identificador en la URL, como un ID de usuario o un ID de producto.

Puedes [definir parámetros de ruta](/guide/routing/define-routes#define-url-paths-with-route-parameters) prefijando el nombre del parámetro con dos puntos (`:`).

```typescript
import { Routes } from '@angular/router';
import { ProductComponent } from './product/product.component';

const routes: Routes = [
  { path: 'product/:id', component: ProductComponent }
];
```

Puedes acceder a los parámetros suscribiéndote a `route.params`.

```typescript
import { Component, inject, signal } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-product-detail',
  template: `<h1>Product Details: {{ productId() }}</h1>`,
})
export class ProductDetailComponent {
  productId = signal('');
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    // Acceder a parámetros de ruta
    this.activatedRoute.params.subscribe((params) => {
      this.productId.set(params['id']);
    });
  }
}
```

### Parámetros de consulta

Los [parámetros de consulta](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) proporcionan una forma flexible de pasar datos opcionales a través de URLs sin afectar la estructura de la ruta. A diferencia de los parámetros de ruta, los parámetros de consulta pueden persistir a través de eventos de navegación y son perfectos para manejar filtrado, ordenamiento, paginación y otros elementos UI con estado.

```typescript
// Estructura de parámetro único
// /products?category=electronics
router.navigate(['/products'], {
  queryParams: { category: 'electronics' }
});

// Múltiples parámetros
// /products?category=electronics&sort=price&page=1
router.navigate(['/products'], {
  queryParams: {
    category: 'electronics',
    sort: 'price',
    page: 1
  }
});
```

Puedes acceder a los parámetros de consulta con `route.queryParams`.

Aquí hay un ejemplo de un `ProductListComponent` que actualiza los parámetros de consulta que afectan cómo muestra una lista de productos:

```typescript
import { ActivatedRoute, Router } from '@angular/router';

@Component({
  selector: 'app-product-list',
  template: `
    <div>
      <select (change)="updateSort($event)">
        <option value="price">Price</option>
        <option value="name">Name</option>
      </select>
      
    </div>
  `
})
export class ProductListComponent implements OnInit {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {
    // Acceder a parámetros de consulta de forma reactiva
    this.route.queryParams.subscribe(params => {
      const sort = params['sort'] || 'price';
      const page = Number(params['page']) || 1;
      this.loadProducts(sort, page);
    });
  }

updateSort(event: Event) {
    const sort = (event.target as HTMLSelectElement).value;
    // Actualizar URL con nuevo parámetro de consulta
    this.router.navigate([], {
      queryParams: { sort },
      queryParamsHandling: 'merge' // Preservar otros parámetros de consulta
    });
  }
}
```

En este ejemplo, los usuarios pueden usar un elemento select para ordenar la lista de productos por nombre o precio. El manejador de cambio asociado actualiza los parámetros de consulta de la URL, lo que a su vez desencadena un evento de cambio que puede leer los parámetros de consulta actualizados y actualizar la lista de productos.

Para más información, consulta los [docs oficiales sobre QueryParamsHandling](/api/router/QueryParamsHandling).

## Detectar ruta activa actual con RouterLinkActive

Puedes usar la directiva `RouterLinkActive` para estilizar dinámicamente elementos de navegación basándose en la ruta activa actual. Esto es común en elementos de navegación para informar a los usuarios cuál es la ruta activa.

```html
<nav>
  <a class="button"
     routerLink="/about"
     routerLinkActive="active-button"
     ariaCurrentWhenActive="page">
    About
  </a> |
  <a class="button"
     routerLink="/settings"
     routerLinkActive="active-button"
     ariaCurrentWhenActive="page">
    Settings
  </a>
</nav>
```

En este ejemplo, el Router de Angular aplicará la clase `active-button` al enlace anchor correcto y `ariaCurrentWhenActive` a `page` cuando la URL coincida con el `routerLink` correspondiente.

Si necesitas agregar múltiples clases al elemento, puedes usar un string separado por espacios o un array:

```html

<a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>

<a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
```

Cuando especificas un valor para routerLinkActive, también estás definiendo el mismo valor para `ariaCurrentWhenActive`. Esto asegura que los usuarios con discapacidad visual (que pueden no percibir el estilo diferente que se está aplicando) también puedan identificar el botón activo.

Si quieres definir un valor diferente para aria, necesitarás establecer explícitamente el valor usando la directiva `ariaCurrentWhenActive`.

### Estrategia de coincidencia de ruta

Por defecto, `RouterLinkActive` considera cualquier ancestro en la ruta como una coincidencia.

```html
<a [routerLink]="['/user/jane']" routerLinkActive="active-link">
  User
</a>
<a [routerLink]="['/user/jane/role/admin']" routerLinkActive="active-link">
  Role
</a>
```

Cuando el usuario visita `/user/jane/role/admin`, ambos enlaces tendrían la clase `active-link`.

### Solo aplicar RouterLinkActive en coincidencias exactas de ruta

Si solo quieres aplicar la clase en una coincidencia exacta, necesitas proporcionar la directiva `routerLinkActiveOptions` con un objeto de configuración que contenga el valor `exact: true`.

```html
<a [routerLink]="['/user/jane']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  User
</a>
<a [routerLink]="['/user/jane/role/admin']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  Role
</a>
```

Si quieres ser más preciso en cómo se hace coincidir una ruta, vale la pena notar que `exact: true` es en realidad azúcar sintáctica para el conjunto completo de opciones de coincidencia:

```typescript
// `exact: true` es equivalente a
{
  paths: 'exact',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'exact',
}

// `exact: false` es equivalente
{
  paths: 'subset',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'subset',
}
```

Para más información, consulta los docs oficiales para [isActiveMatchOptions](/api/router/IsActiveMatchOptions).

### Aplicar RouterLinkActive a un ancestro

La directiva RouterLinkActive también se puede aplicar a un elemento ancestro para permitir a los desarrolladores estilizar los elementos como deseen.

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

Para más información, consulta los [docs de la API para RouterLinkActive](/api/router/RouterLinkActive).
# Otras tareas comunes de enrutamiento

Esta guía cubre algunas otras tareas comunes asociadas con el uso de Angular router en tu aplicación.

## Obtener información de la ruta

A menudo, cuando un usuario navega por tu aplicación, quieres pasar información de un componente a otro.
Por ejemplo, considera una aplicación que muestra una lista de compras de artículos de comestibles.
Cada elemento en la lista tiene un `id` único.
Para editar un elemento, los usuarios hacen clic en un botón Editar, que abre un componente `EditGroceryItem`.
Quieres que ese componente recupere el `id` del artículo de comestible para que pueda mostrar la información correcta al usuario.

Usa una ruta para pasar este tipo de información a los componentes de tu aplicación.
Para hacerlo, usas la funcionalidad [`withComponentInputBinding`](api/router/withComponentInputBinding) con `provideRouter` o la opción `bindToComponentInputs` de `RouterModule.forRoot`.

Para obtener información de una ruta:

<docs-workflow>

<docs-step title="Agregar `withComponentInputBinding`">

Agrega la funcionalidad `withComponentInputBinding` al método `provideRouter`.

```ts
providers: [
  provideRouter(appRoutes, withComponentInputBinding()),
]
```

</docs-step>

<docs-step title="Agregar un `input` al componente">

Actualiza el componente para que tenga una propiedad `input()` que coincida con el nombre del parámetro.

```ts
id = input.required<string>()
hero = computed(() => this.service.getHero(id));
```

</docs-step>
<docs-step title="Opcional: Usar un valor predeterminado">
El router asigna valores a todas las entradas según la ruta actual cuando `withComponentInputBinding` está habilitado.
El router asigna `undefined` si no hay datos de ruta que coincidan con la clave de entrada, como cuando falta un parámetro de consulta opcional.
Debes incluir `undefined` en el tipo del `input` cuando existe la posibilidad de que una entrada no coincida con la ruta.

Proporciona un valor predeterminado usando la opción `transform` en el input o gestionando un estado local con un `linkedSignal`.

```ts
id = input.required({
  transform: (maybeUndefined: string | undefined) => maybeUndefined ?? '0',
});
// o
id = input<string|undefined>();
internalId = linkedSignal(() => this.id() ?? getDefaultId());
```

</docs-step>
</docs-workflow>

NOTA: Puedes vincular todos los datos de ruta con pares clave-valor a las entradas del componente: datos de ruta estáticos o resueltos, parámetros de ruta, parámetros de matriz y parámetros de consulta.
Si deseas usar la información de ruta del componente padre, necesitarás configurar la opción `paramsInheritanceStrategy` del router:
`withRouterConfig({paramsInheritanceStrategy: 'always'})`

## Mostrar una página 404

Para mostrar una página 404, configura una [ruta comodín](guide/routing/common-router-tasks#setting-up-wildcard-routes) con la propiedad `component` establecida en el componente que deseas usar para tu página 404 de la siguiente manera:

```ts
const routes: Routes = [
  { path: 'first-component', component: FirstComponent },
  { path: 'second-component', component: SecondComponent },
  { path: '**', component: PageNotFoundComponent },  // Ruta comodín para una página 404
];
```

La última ruta con el `path` de `**` es una ruta comodín.
El router selecciona esta ruta si la URL solicitada no coincide con ninguna de las rutas anteriores en la lista y envía al usuario al `PageNotFoundComponent`.

## Array de parámetros de enlace

Un array de parámetros de enlace contiene los siguientes ingredientes para la navegación del router:

- La ruta del camino al componente de destino
- Parámetros de ruta requeridos y opcionales que van en la URL de la ruta

Vincula la directiva `RouterLink` a tal array de esta manera:

```html
<a [routerLink]="['/heroes']">Heroes</a>
```

Lo siguiente es un array de dos elementos al especificar un parámetro de ruta:

```html
<a [routerLink]="['/hero', hero.id]">
  <span class="badge">{{ hero.id }}</span>{{ hero.name }}
</a>
```

Proporciona parámetros de ruta opcionales en un objeto, como en `{ foo: 'foo' }`:

```html
<a [routerLink]="['/crisis-center', { foo: 'foo' }]">Crisis Center</a>
```

Estos tres ejemplos cubren las necesidades de una aplicación con un nivel de enrutamiento.
Sin embargo, con un router hijo, como en el centro de crisis, creas nuevas posibilidades de array de enlaces.

El siguiente ejemplo mínimo de `RouterLink` se basa en una ruta hija predeterminada especificada para el centro de crisis.

```html
<a [routerLink]="['/crisis-center']">Crisis Center</a>
```

Revisa lo siguiente:

- El primer elemento en el array identifica la ruta padre $`/crisis-center`$
- No hay parámetros para esta ruta padre
- No hay un valor predeterminado para la ruta hija, por lo que necesitas elegir uno
- Estás navegando al `CrisisListComponent`, cuya ruta es `/`, pero no necesitas agregar explícitamente la barra diagonal

Considera el siguiente enlace de router que navega desde la raíz de la aplicación hasta el Dragon Crisis:

```html
<a [routerLink]="['/crisis-center', 1]">Dragon Crisis</a>
```

- El primer elemento en el array identifica la ruta padre $`/crisis-center`$
- No hay parámetros para esta ruta padre
- El segundo elemento identifica los detalles de la ruta hija sobre una crisis en particular $`/:id`$
- La ruta hija de detalles requiere un parámetro de ruta `id`
- Agregaste el `id` del Dragon Crisis como el segundo elemento en el array $`1`$
- La ruta resultante es `/crisis-center/1`

También podrías redefinir la plantilla de `AppComponent` con rutas del Crisis Center exclusivamente:

```typescript
@Component({
  template: `
    <h1 class="title">Angular Router</h1>
    <nav>
      <a [routerLink]="['/crisis-center']">Crisis Center</a>
      <a [routerLink]="['/crisis-center/1', { foo: 'foo' }]">Dragon Crisis</a>
      <a [routerLink]="['/crisis-center/2']">Shark Crisis</a>
    </nav>
    <router-outlet />
  `
})
export class AppComponent {}
```

En resumen, puedes escribir aplicaciones con uno, dos o más niveles de enrutamiento.
El array de parámetros de enlace ofrece la flexibilidad para representar cualquier profundidad de enrutamiento y cualquier secuencia legal de rutas, parámetros de router $requeridos$ y objetos de parámetros de ruta $opcionales$.

## `LocationStrategy` y estilos de URL del navegador

Cuando el router navega a una nueva vista de componente, actualiza la ubicación y el historial del navegador con una URL para esa vista.

Los navegadores modernos HTML5 soportan [history.pushState](https://developer.mozilla.org/docs/Web/API/History_API/Working_with_the_History_API#adding_and_modifying_history_entries 'HTML5 browser history push-state'), una técnica que cambia la ubicación y el historial de un navegador sin disparar una petición de página al servidor.
El router puede componer una URL "natural" que es indistinguible de una que de otro modo requeriría una carga de página.

Aquí está la URL del Crisis Center en este estilo "HTML5 pushState":

```text
localhost:3002/crisis-center
```

Los navegadores más antiguos envían peticiones de página al servidor cuando la URL de ubicación cambia, a menos que el cambio ocurra después de un "#" $llamado "hash"$.
Los routers pueden aprovechar esta excepción componiendo URLs de ruta dentro de la aplicación con hashes.
Aquí hay una "URL hash" que enruta al Crisis Center.

```text
localhost:3002/src/#/crisis-center
```

El router soporta ambos estilos con dos proveedores `LocationStrategy`:

La función `RouterModule.forRoot()` establece el `LocationStrategy` al `PathLocationStrategy`, lo que lo convierte en la estrategia predeterminada.
También tienes la opción de cambiar al `HashLocationStrategy` con una sobrescritura durante el proceso de bootstrapping.

ÚTIL: Para más información sobre proveedores y el proceso de bootstrap, consulta [Inyección de Dependencias](guide/di/dependency-injection-providers).
# Usar rutas de Angular en una aplicación de página única (SPA)

Este tutorial describe cómo construir una aplicación de página única, SPA que usa múltiples rutas de Angular.

En una Single Page Application $SPA$, todas las funciones de tu aplicación existen en una sola página HTML.
A medida que los usuarios acceden a las características de tu aplicación, el navegador solo necesita renderizar las partes que importan al usuario, en lugar de cargar una nueva página.
Este patrón puede mejorar significativamente la experiencia del usuario de tu aplicación.

Para definir cómo los usuarios navegan a través de tu aplicación, usas rutas.
Agrega rutas para definir cómo los usuarios navegan de una parte de tu aplicación a otra.
También puedes configurar rutas para protegerse contra comportamientos inesperados o no autorizados.

## Objetivos

* Organizar las características de una aplicación de ejemplo en módulos.
* Definir cómo navegar a un componente.
* Pasar información a un componente usando un parámetro.
* Estructurar rutas anidando varias rutas.
* Verificar si los usuarios pueden acceder a una ruta.
* Controlar si la aplicación puede descartar cambios no guardados.
* Mejorar el rendimiento precargando datos de ruta y cargando módulos de características con lazy loading.
* Requerir criterios específicos para cargar componentes.

## Crear una aplicación de ejemplo

Usando Angular CLI, crea una nueva aplicación, *angular-router-sample*.
Esta aplicación tendrá dos componentes: *crisis-list* y *heroes-list*.

1. Crea un nuevo proyecto Angular, *angular-router-sample*.

```shell
ng new angular-router-sample
```
    Cuando se te pregunte `Would you like to add Angular routing?`, selecciona `N`.

Cuando se te pregunte `Which stylesheet format would you like to use?`, selecciona `CSS`.

Después de unos momentos, un nuevo proyecto, `angular-router-sample`, estará listo.

1. Desde tu terminal, navega al directorio `angular-router-sample`.
1. Crea un componente, *crisis-list*.

```shell
ng generate component crisis-list
```
1. En tu editor de código, localiza el archivo `crisis-list.component.html` y reemplaza el contenido placeholder con el siguiente HTML.

```
1. Crea un segundo componente, *heroes-list*.

<docs-code language="shell">
    ng generate component heroes-list
```
1. En tu editor de código, localiza el archivo `heroes-list.component.html` y reemplaza el contenido placeholder con el siguiente HTML.

```
1. En tu editor de código, abre el archivo `app.component.html` y reemplaza su contenido con el siguiente HTML.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="setup"/>

1. Verifica que tu nueva aplicación se ejecuta como se espera ejecutando el comando `ng serve`.

<docs-code language="shell">
    ng serve
```
1. Abre un navegador en `http://localhost:4200`.

Deberías ver una sola página web, consistiendo en un título y el HTML de tus dos componentes.

## Definir tus rutas

En esta sección, definirás dos rutas:

* La ruta `/crisis-center` abre el componente `crisis-center`.
* La ruta `/heroes-list` abre el componente `heroes-list`.

Una definición de ruta es un objeto JavaScript.
Cada ruta típicamente tiene dos propiedades.
La primera propiedad, `path`, es un string que especifica la ruta de URL para la ruta.
La segunda propiedad, `component`, es un string que especifica qué componente debe mostrar tu aplicación para esa ruta.

1. Desde tu editor de código, crea y abre el archivo `app.routes.ts`.
1. Crea y exporta una lista de rutas para tu aplicación:

```ts
import {Routes} from '@angular/router';

export const routes = [];
    ```

1. Agrega dos rutas para tus primeros dos componentes:

```ts
{path: 'crisis-list', component: CrisisListComponent},
    {path: 'heroes-list', component: HeroesListComponent},
    ```

Esta lista de rutas es un array de objetos JavaScript, con cada objeto definiendo las propiedades de una ruta.

## Importar `provideRouter` desde `@angular/router`

El enrutamiento te permite mostrar vistas específicas de tu aplicación dependiendo de la ruta de URL.
Para agregar esta funcionalidad a tu aplicación de ejemplo, necesitas actualizar el archivo `app.config.ts` para usar la función de proveedores del router, `provideRouter`.
Importas esta función de proveedor desde `@angular/router`.

1. Desde tu editor de código, abre el archivo `app.config.ts`.
1. Agrega las siguientes declaraciones de importación:

```ts
import { provideRouter } from '@angular/router';
    import { routes } from './app.routes';
    ```

1. Actualiza los providers en el `appConfig`:

```ts
providers: [provideRouter(routes)]
    ```

Para aplicaciones basadas en `NgModule`, coloca el `provideRouter` en la lista de `providers` del `AppModule`, o cualquier módulo que se pase a `bootstrapModule` en la aplicación.

## Actualizar tu componente con `router-outlet`

En este punto, has definido dos rutas para tu aplicación.
Sin embargo, tu aplicación aún tiene ambos componentes `crisis-list` y `heroes-list` codificados directamente en tu plantilla `app.component.html`.
Para que tus rutas funcionen, necesitas actualizar tu plantilla para cargar dinámicamente un componente basado en la ruta de URL.

Para implementar esta funcionalidad, agregas la directiva `router-outlet` a tu archivo de plantilla.

1. Desde tu editor de código, abre el archivo `app.component.html`.
1. Elimina las siguientes líneas.

```
1. Agrega la directiva `router-outlet`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="router-outlet"/>

1. Agrega `RouterOutlet` a los imports del `AppComponent` en `app.component.ts`

```ts
imports: [RouterOutlet],
    ```

Visualiza tu aplicación actualizada en tu navegador.
Solo deberías ver el título de la aplicación.
Para ver el componente `crisis-list`, agrega `crisis-list` al final de la ruta en la barra de direcciones de tu navegador.
Por ejemplo:

<docs-code language="http">
http://localhost:4200/crisis-list
```
Nota que el componente `crisis-list` se muestra.
Angular está usando la ruta que definiste para cargar dinámicamente el componente.
Puedes cargar el componente `heroes-list` de la misma manera:

```http
http://localhost:4200/heroes-list
```
## Controlar la navegación con elementos UI

Actualmente, tu aplicación soporta dos rutas.
Sin embargo, la única forma de usar esas rutas es que el usuario escriba manualmente la ruta en la barra de direcciones del navegador.
En esta sección, agregarás dos enlaces en los que los usuarios pueden hacer clic para navegar entre los componentes `heroes-list` y `crisis-list`.
También agregarás algunos estilos CSS.
Aunque estos estilos no son requeridos, facilitan identificar el enlace del componente actualmente mostrado.
Agregarás esa funcionalidad en la siguiente sección.

1. Abre el archivo `app.component.html` y agrega el siguiente HTML debajo del título.

```
Este HTML usa una directiva de Angular, `routerLink`.
    Esta directiva conecta las rutas que definiste a tus archivos de plantilla.

1. Agrega la directiva `RouterLink` a la lista de imports de `AppComponent` en `app.component.ts`.

1. Abre el archivo `app.component.css` y agrega los siguientes estilos.

<docs-code header="src/app/app.component.css" path="adev/src/content/examples/router-tutorial/src/app/app.component.css"/>

Si visualizas tu aplicación en el navegador, deberías ver estos dos enlaces.
Cuando haces clic en un enlace, aparece el componente correspondiente.

## Identificar la ruta activa

Aunque los usuarios pueden navegar tu aplicación usando los enlaces que agregaste en la sección anterior, no tienen una forma directa de identificar cuál es la ruta activa.
Agrega esta funcionalidad usando la directiva `routerLinkActive` de Angular.

1. Desde tu editor de código, abre el archivo `app.component.html`.
1. Actualiza las etiquetas anchor para incluir la directiva `routerLinkActive`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="routeractivelink"/>
1. Agrega la directiva `RouterLinkActive` a la lista de `imports` de `AppComponent` en `app.component.ts`.

Visualiza tu aplicación nuevamente.
Al hacer clic en uno de los botones, el estilo para ese botón se actualiza automáticamente, identificando el componente activo para el usuario.
Al agregar la directiva `routerLinkActive`, informas a tu aplicación que aplique una clase CSS específica a la ruta activa.
En este tutorial, esa clase CSS es `activebutton`, pero podrías usar cualquier clase que desees.

Nota que también estamos especificando un valor para el `ariaCurrentWhenActive` de `routerLinkActive`. Esto asegura que los usuarios con discapacidades visuales (que pueden no percibir el estilo diferente que se está aplicando) también puedan identificar el botón activo. Para más información consulta las Mejores Prácticas de Accesibilidad [sección de identificación de enlaces activos](/best-practices/a11y#active-links-identification).

## Agregar una redirección

En este paso del tutorial, agregas una ruta que redirige al usuario para mostrar el componente `/heroes-list`.

1. Desde tu editor de código, abre el archivo `app.routes.ts`.
1. Actualiza la sección `routes` como sigue.

```ts
{path: '', redirectTo: '/heroes-list', pathMatch: 'full'},
    ```

Nota que esta nueva ruta usa un string vacío como su ruta.
    Además, reemplaza la propiedad `component` con dos nuevas:

| Propiedades   | Detalles |
    |:---        |:---    |
    | `redirectTo` | Esta propiedad instruye a Angular a redirigir desde una ruta vacía a la ruta `heroes-list`.                                                                                                                                                       |
    | `pathMatch`  | Esta propiedad instruye a Angular sobre cuánto de la URL debe coincidir. Para este tutorial, deberías establecer esta propiedad en `full`. Esta estrategia se recomienda cuando tienes un string vacío para una ruta. Para más información sobre esta propiedad, consulta la [documentación de la API Route](api/router/Route). |

Ahora cuando abres tu aplicación, muestra el componente `heroes-list` por defecto.

## Agregar una página 404

Es posible que un usuario intente acceder a una ruta que no has definido.
Para dar cuenta de este comportamiento, la mejor práctica es mostrar una página 404.
En esta sección, crearás una página 404 y actualizarás tu configuración de rutas para mostrar esa página para cualquier ruta no especificada.

1. Desde la terminal, crea un nuevo componente, `PageNotFound`.

<docs-code language="shell">
    ng generate component page-not-found
```
1. Desde tu editor de código, abre el archivo `page-not-found.component.html` y reemplaza su contenido con el siguiente HTML.

<docs-code header="src/app/page-not-found/page-not-found.component.html" path="adev/src/content/examples/router-tutorial/src/app/page-not-found/page-not-found.component.html"/>

1. Abre el archivo `app.routes.ts` y agrega la siguiente ruta a la lista de rutas:

```ts
{path: '**', component: PageNotFoundComponent}
    ```

La nueva ruta usa una ruta, `**`.
    Esta ruta es cómo Angular identifica una ruta comodín.
    Cualquier ruta que no coincida con una ruta existente en tu configuración usará esta ruta.

IMPORTANTE: Nota que la ruta comodín se coloca al final del array.
El orden de tus rutas es importante, ya que Angular aplica rutas en orden y usa la primera coincidencia que encuentra.

Intenta navegar a una ruta no existente en tu aplicación, como `http://localhost:4200/powers`.
Esta ruta no coincide con nada definido en tu archivo `app.routes.ts`.
Sin embargo, como definiste una ruta comodín, la aplicación automáticamente muestra tu componente `PageNotFound`.

## Próximos pasos

En este punto, tienes una aplicación básica que usa la característica de enrutamiento en Angular para cambiar qué componentes puede ver el usuario basándose en la dirección URL.
Has extendido estas características para incluir una redirección, así como una ruta comodín para mostrar una página 404 personalizada.

Para más información sobre enrutamiento, consulta los siguientes temas:
# Crear coincidencias de ruta personalizadas

Angular Router soporta una estrategia de coincidencia poderosa que puedes usar para ayudar a los usuarios a navegar tu aplicación.
Esta estrategia de coincidencia soporta rutas estáticas, rutas variables con parámetros, rutas comodín, y más.
Además, puedes construir tu propia coincidencia de patrón personalizada para situaciones en las que las URLs son más complicadas.

En este tutorial, construirás un matcher de ruta personalizado usando `UrlMatcher` de Angular.
Este matcher busca un handle de Twitter en la URL.

## Objetivos

Implementar `UrlMatcher` de Angular para crear un matcher de ruta personalizado.

## Crear una aplicación de ejemplo

Usando Angular CLI, crea una nueva aplicación, *angular-custom-route-match*.
Además del framework de aplicación Angular predeterminado, también crearás un componente *profile*.

1. Crea un nuevo proyecto Angular, *angular-custom-route-match*.

```shell
ng new angular-custom-route-match
    ```

Cuando se te pregunte `Would you like to add Angular routing?`, selecciona `Y`.

Cuando se te pregunte `Which stylesheet format would you like to use?`, selecciona `CSS`.

Después de unos momentos, un nuevo proyecto, `angular-custom-route-match`, estará listo.

1. Desde tu terminal, navega al directorio `angular-custom-route-match`.
1. Crea un componente, *profile*.

```shell
ng generate component profile
    ```

1. En tu editor de código, localiza el archivo `profile.component.html` y reemplaza el contenido placeholder con el siguiente HTML.

```
1. En tu editor de código, localiza el archivo `app.component.html` y reemplaza el contenido placeholder con el siguiente HTML.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.component.html"/>

## Configurar las rutas para tu aplicación

Con el framework de tu aplicación en su lugar, a continuación necesitas agregar capacidades de enrutamiento al archivo `app.config.ts`.
Como parte de este proceso, crearás un matcher de URL personalizado que busca un handle de Twitter en la URL.
Este handle se identifica por un símbolo `@` precedente.

1. En tu editor de código, abre tu archivo `app.config.ts`.
1. Agrega una declaración `import` para `provideRouter` y `withComponentInputBinding` de Angular, así como las rutas de la aplicación.

```ts
import {provideRouter, withComponentInputBinding} from '@angular/router';

import {routes} from './app.routes';
    ```

1. En el array de providers, agrega una declaración `provideRouter(routes, withComponentInputBinding())`.

1. Define el matcher de ruta personalizado agregando el siguiente código a las rutas de la aplicación.

<docs-code header="src/app/app.routes.ts" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.routes.ts" visibleRegion="matcher"/>

Este matcher personalizado es una función que realiza las siguientes tareas:

* El matcher verifica que el array contiene solo un segmento
* El matcher emplea una expresión regular para asegurar que el formato del nombre de usuario coincida
* Si hay una coincidencia, la función retorna la URL completa, definiendo un parámetro de ruta `username` como una subcadena de la ruta
* Si no hay coincidencia, la función retorna null y el router continúa buscando otras rutas que coincidan con la URL

ÚTIL: Un matcher de URL personalizado se comporta como cualquier otra definición de ruta. Define rutas hijo o rutas con lazy loading como lo harías con cualquier otra ruta.

## Leer los parámetros de ruta

Con el matcher personalizado en su lugar, ahora puedes vincular el parámetro de ruta en el componente `profile`.

En tu editor de código, abre tu archivo `profile.component.ts` y crea un `Input` que coincida con el parámetro `username`.
Agregamos la característica `withComponentInputBinding` anteriormente
en `provideRouter`. Esto permite que el `Router` vincule información directamente a los componentes de ruta.

```ts
@Input() username!: string;
```

## Probar tu matcher de URL personalizado

Con tu código en su lugar, ahora puedes probar tu matcher de URL personalizado.

1. Desde una ventana de terminal, ejecuta el comando `ng serve`.

<docs-code language="shell">
    ng serve
```
1. Abre un navegador en `http://localhost:4200`.

Deberías ver una sola página web, consistiendo en una oración que dice `Navigate to my profile`.

1. Haz clic en el hipervínculo **my profile**.

Una nueva oración, que dice `Hello, Angular!` aparece en la página.

## Próximos pasos

La coincidencia de patrones con Angular Router te proporciona mucha flexibilidad cuando tienes URLs dinámicas en tu aplicación.
Para aprender más sobre Angular Router, consulta los siguientes temas:
ÚTIL: Este contenido está basado en [Custom Route Matching with the Angular Router](https://medium.com/@brandontroberts/custom-route-matching-with-the-angular-router-fbdd48665483), de [Brandon Roberts](https://twitter.com/brandontroberts).
# Server and hybrid rendering

Angular ships all applications as client-side rendered (CSR) by default. While this approach delivers a initial payload that's lightweight, it introduces trade-offs including slower load times, degraded performance metrics, and higher resource demands since the user's device performs most of the computations. As a result, many applications achieve significant performance improvements by integrating server-side rendering (SSR) into a hybrid rendering strategy.

## What is hybrid rendering?

Hybrid rendering allows developers to leverage the benefits of server-side rendering (SSR), pre-rendering (also known as "static site generation" or SSG) and client-side rendering (CSR) to optimize your Angular application. It gives you fine-grained control over how the different parts of your app are rendered to give your users the best experience possible.

## Setting up hybrid rendering

You can create a **new** project with hybrid rendering by using the server-side rendering flag (i.e., `--ssr`) with the Angular CLI `ng new` command:

```shell
ng new --ssr
```

You can also enable hybrid rendering by adding server-side rendering to an existing project with the `ng add` command:

```shell
ng add @angular/ssr
```

NOTE: By default, Angular prerenders your entire application and generates a server file. To disable this and create a fully static app, set `outputMode` to `static`. To enable SSR, update the server routes to use `RenderMode.Server`. For more details, see [`Server routing`](#server-routing) and [`Generate a fully static application`](#generate-a-fully-static-application).

## Server routing

### Configuring server routes

You can create a server route config by declaring an array of [`ServerRoute`](api/ssr/ServerRoute 'API reference') objects. This configuration typically lives in a file named `app.routes.server.ts`.

```typescript
// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '', // This renders the "/" route on the client (CSR)
    renderMode: RenderMode.Client,
  },
  {
    path: 'about', // This page is static, so we prerender it (SSG)
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'profile', // This page requires user-specific data, so we use SSR
    renderMode: RenderMode.Server,
  },
  {
    path: '**', // All other routes will be rendered on the server (SSR)
    renderMode: RenderMode.Server,
  },
];
```

You can add this config to your application with [`provideServerRendering`](api/ssr/provideServerRendering 'API reference') using the [`withRoutes`](api/ssr/withRoutes 'API reference') function:

```typescript
import { provideServerRendering, withRoutes } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

// app.config.server.ts
const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
    // ... other providers ...
  ]
};
```

When using the [App shell pattern](ecosystem/service-workers/app-shell), you must specify the component to be used as the app shell for client-side rendered routes. To do this, use the [`withAppShell`](api/ssr/withAppShell 'API reference') feature:

```typescript
import { provideServerRendering, withRoutes, withAppShell } from '@angular/ssr';
import { AppShellComponent } from './app-shell/app-shell.component';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      withRoutes(serverRoutes),
      withAppShell(AppShellComponent),
    ),
    // ... other providers ...
  ]
};
```

### Rendering modes

The server routing configuration lets you specify how each route in your application should render by setting a [`RenderMode`](api/ssr/RenderMode 'API reference'):

| Rendering mode      | Description                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Server (SSR)**    | Renders the application on the server for each request, sending a fully populated HTML page to the browser. |
| **Client (CSR)**    | Renders the application in the browser. This is the default Angular behavior.                               |
| **Prerender (SSG)** | Prerenders the application at build time, generating static HTML files for each route.                      |

#### Choosing a rendering mode

Each rendering mode has different benefits and drawbacks. You can choose rendering modes based on the specific needs of your application.

##### Client-side rendering (CSR)

Client-side rendering has the simplest development model, as you can write code that assumes it always runs in a web browser. This lets you use a wide range of client-side libraries that also assume they run in a browser.

Client-side rendering generally has worse performance than other rendering modes, as it must download, parse, and execute your page's JavaScript before the user can see any rendered content. If your page fetches more data from the server as it renders, users also have to wait for those additional requests before they can view the complete content.

If your page is indexed by search crawlers, client-side rendering may negatively affect search engine optimization (SEO), as search crawlers have limits to how much JavaScript they execute when indexing a page.

When client-side rendering, the server does not need to do any work to render a page beyond serving static JavaScript assets. You may consider this factor if server cost is a concern.

Applications that support installable, offline experiences with [service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can rely on client-side rendering without needing to communicate with a server.

##### Server-side rendering (SSR)

Server-side rendering offers faster page loads than client-side rendering. Instead of waiting for JavaScript to download and run, the server directly renders an HTML document upon receiving a request from the browser. The user experiences only the latency necessary for the server to fetch data and render the requested page. This mode also eliminates the need for additional network requests from the browser, as your code can fetch data during rendering on the server.

Server-side rendering generally has excellent search engine optimization (SEO), as search crawlers receive a fully rendered HTML document.

Server-side rendering requires you to author code that does not strictly depend on browser APIs and limits your selection of JavaScript libraries that assume they run in a browser.

When server-side rendering, your server runs Angular to produce an HTML response for every request which may increase server hosting costs.

##### Build-time prerendering

Prerendering offers faster page loads than both client-side rendering and server-side rendering. Because prerendering creates HTML documents at _build-time_, the server can directly respond to requests with the static HTML document without any additional work.

Prerendering requires that all information necessary to render a page is available at _build-time_. This means that prerendered pages cannot include any data to the specific user loading the page. Prerendering is primarily useful for pages that are the same for all users of your application.

Because prerendering occurs at build-time, it may add significant time to your production builds. Using [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') to produce a large number of HTML documents may affect the total file size of your deployments, and thus lead to slower deployments.

Prerendering generally has excellent search engine optimization (SEO), as search crawlers receive a fully rendered HTML document.

Prerendering requires you to author code that does not strictly depend on browser APIs and limits your selection of JavaScript libraries that assume they run in a browser.

Prerendering incurs extremely little overhead per server request, as your server responds with static HTML documents. Static files are also easily cached by Content Delivery Networks (CDNs), browsers, and intermediate caching layers for even faster subsequent page loads. Fully static sites can also be deployed solely through a CDN or static file server, eliminating the need to maintain a custom server runtime for your application. This enhances scalability by offloading work from an application web server, making it particularly beneficial for high-traffic applications.

NOTE: When using Angular service worker, the first request is server-rendered, but all subsequent requests are handled by the service worker and rendered client-side.

### Setting headers and status codes

You can set custom headers and status codes for individual server routes using the `headers` and `status` properties in the `ServerRoute` configuration.

```typescript
// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'profile',
    renderMode: RenderMode.Server,
    headers: {
      'X-My-Custom-Header': 'some-value',
    },
    status: 201,
  },
  // ... other routes
];
```

### Redirects

Angular handles redirects specified by the [`redirectTo`](api/router/Route#redirectTo 'API reference') property in route configurations, differently on the server-side.

**Server-Side Rendering (SSR)**
Redirects are performed using standard HTTP redirects (e.g., 301, 302) within the server-side rendering process.

**Prerendering (SSG)**
Redirects are implemented as "soft redirects" using [`<meta http-equiv="refresh">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#refresh) tags in the prerendered HTML.

### Customizing build-time prerendering (SSG)

When using [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), you can specify several configuration options to customize the prerendering and serving process.

#### Parameterized routes

For each route with [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), you can specify a [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') function. This function lets you control which specific parameters produce separate prerendered documents.

The [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') function returns a `Promise` that resolves to an array of objects. Each object is a key-value map of route parameter name to value. For example, if you define a route like `post/:id`, `getPrerenderParams ` could return the array `[{id: 123}, {id: 456}]`, and thus render separate documents for `post/123` and `post/456`.

The body of [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') can use Angular's [`inject`](api/core/inject 'API reference') function to inject dependencies and perform any work to determine which routes to prerender. This typically includes making requests to fetch data to construct the array of parameter values.

You can also use this function with catch-all routes (e.g., `/**`), where the parameter name will be `"**"` and the return value will be the segments of the path, such as `foo/bar`. These can be combined with other parameters (e.g., `/post/:id/**`) to handle more complex route configuration.

```ts
// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const dataService = inject(PostService);
      const ids = await dataService.getIds(); // Assuming this returns ['1', '2', '3']

return ids.map(id => ({ id })); // Generates paths like: /post/1, /post/2, /post/3
    },
  },
  {
    path: 'post/:id/**',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      return [
        { id: '1', '**': 'foo/3' },
        { id: '2', '**': 'bar/4' },
      ]; // Generates paths like: /post/1/foo/3, /post/2/bar/4
    },
  },
];
```

Because [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') exclusively applies to [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), this function always runs at _build-time_. `getPrerenderParams` must not rely on any browser-specific or server-specific APIs for data.

IMPORTANT: When using [`inject`](api/core/inject 'API reference') inside `getPrerenderParams`, please remember that `inject` must be used synchronously. It cannot be invoked within asynchronous callbacks or following any `await` statements. For more information, refer to [`runInInjectionContext`](api/core/runInInjectionContext).

#### Fallback strategies

When using [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') mode, you can specify a fallback strategy to handle requests for paths that haven't been prerendered.

The available fallback strategies are:

- **Server:** Falls back to server-side rendering. This is the **default** behavior if no `fallback` property is specified.
- **Client:** Falls back to client-side rendering.
- **None:** No fallback. Angular will not handle requests for paths that are not prerendered.

```typescript
// app.routes.server.ts
import { RenderMode, PrerenderFallback, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    fallback: PrerenderFallback.Client, // Fallback to CSR if not prerendered
    async getPrerenderParams() {
      // This function returns an array of objects representing prerendered posts at the paths:
      // `/post/1`, `/post/2`, and `/post/3`.
      // The path `/post/4` will utilize the fallback behavior if it's requested.
      return [{ id: 1 }, { id: 2 }, { id: 3 }];
    },
  },
];
```

## Authoring server-compatible components

Some common browser APIs and capabilities might not be available on the server. Applications cannot make use of browser-specific global objects like `window`, `document`, `navigator`, or `location` as well as certain properties of `HTMLElement`.

In general, code which relies on browser-specific symbols should only be executed in the browser, not on the server. This can be enforced through the [`afterEveryRender`](api/core/afterEveryRender) and [`afterNextRender`](api/core/afterNextRender) lifecycle hooks. These are only executed on the browser and skipped on the server.

```typescript
import { Component, ViewChild, afterNextRender } from '@angular/core';

@Component({
  selector: 'my-cmp',
  template: `<span #content>{{ ... }}</span>`,
})
export class MyComponent {
  @ViewChild('content') contentRef: ElementRef;

constructor() {
    afterNextRender(() => {
      // Safe to check `scrollHeight` because this will only run in the browser, not the server.
      console.log('content height: ' + this.contentRef.nativeElement.scrollHeight);
    });
  }
}
```

## Accessing Request and Response via DI

The `@angular/core` package provides several tokens for interacting with the server-side rendering environment. These tokens give you access to crucial information and objects within your Angular application during SSR.

- **[`REQUEST`](api/core/REQUEST 'API reference'):** Provides access to the current request object, which is of type [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) from the Web API. This allows you to access headers, cookies, and other request information.
- **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API reference'):** Provides access to the response initialization options, which is of type [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters) from the Web API. This allows you to set headers and the status code for the response dynamically. Use this token to set headers or status codes that need to be determined at runtime.
- **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API reference'):** Provides access to additional context related to the current request. This context can be passed as the second parameter of the [`handle`](api/ssr/AngularAppEngine#handle 'API reference') function. Typically, this is used to provide additional request-related information that is not part of the standard Web API.

```typescript
import { inject, REQUEST } from '@angular/core';

@Component({
  selector: 'app-my-component',
  template: `<h1>My Component</h1>`,
})
export class MyComponent {
  constructor() {
    const request = inject(REQUEST);
    console.log(request?.url);
  }
}
```

IMPORTANT: The above tokens will be `null` in the following scenarios:

- During the build processes.
- When the application is rendered in the browser (CSR).
- When performing static site generation (SSG).
- During route extraction in development (at the time of the request).

## Generate a fully static application

By default, Angular prerenders your entire application and generates a server file for handling requests. This allows your app to serve pre-rendered content to users. However, if you prefer a fully static site without a server, you can opt out of this behavior by setting the `outputMode` to `static` in your `angular.json` configuration file.

When `outputMode` is set to `static`, Angular generates pre-rendered HTML files for each route at build time, but it does not generate a server file or require a Node.js server to serve the app. This is useful for deploying to static hosting providers where a backend server is not needed.

To configure this, update your `angular.json` file as follows:

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```

## Caching data when using HttpClient

[`HttpClient`](api/common/http/HttpClient) cached outgoing network requests when running on the server. This information is serialized and transferred to the browser as part of the initial HTML sent from the server. In the browser, `HttpClient` checks whether it has data in the cache and if so, reuses it instead of making a new HTTP request during initial application rendering. `HttpClient` stops using the cache once an application becomes [stable](api/core/ApplicationRef#isStable) while running in a browser.

By default, `HttpClient` caches all `HEAD` and `GET` requests which don't contain `Authorization` or `Proxy-Authorization` headers. You can override those settings by using [`withHttpTransferCacheOptions`](api/platform-browser/withHttpTransferCacheOptions) when providing hydration.

```typescript
bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(withHttpTransferCacheOptions({
      includePostRequests: true
    }))
  ]
});
```

## Configuring a server

### Node.js

The `@angular/ssr/node` extends `@angular/ssr` specifically for Node.js environments. It provides APIs that make it easier to implement server-side rendering within your Node.js application. For a complete list of functions and usage examples, refer to the [`@angular/ssr/node` API reference](api/ssr/node/AngularNodeAppEngine) API reference.

```typescript
// server.ts
import { AngularNodeAppEngine, createNodeRequestHandler, writeResponseToNodeResponse } from '@angular/ssr/node';
import express from 'express';

const app = express();
const angularApp = new AngularNodeAppEngine();

app.use('*', (req, res, next) => {
  angularApp
    .handle(req)
    .then(response => {
      if (response) {
        writeResponseToNodeResponse(response, res);
      } else {
        next(); // Pass control to the next middleware
      }
    })
    .catch(next);
});

/**
 * The request handler used by the Angular CLI (dev-server and during build).
 */
export const reqHandler = createNodeRequestHandler(app);
```

### Non-Node.js

The `@angular/ssr` provides essential APIs for server-side rendering your Angular application on platforms other than Node.js. It leverages the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects from the Web API, enabling you to integrate Angular SSR into various server environments. For detailed information and examples, refer to the [`@angular/ssr` API reference](api/ssr/AngularAppEngine).

```typescript
// server.ts
import { AngularAppEngine, createRequestHandler } from '@angular/ssr';

const angularApp = new AngularAppEngine();

/**
 * This is a request handler used by the Angular CLI (dev-server and during build).
 */
export const reqHandler = createRequestHandler(async (req: Request) => {
  const res: Response|null = await angularApp.render(req);

// ...
});
```
# Hydration

## What is hydration

Hydration is the process that restores the server-side rendered application on the client. This includes things like reusing the server rendered DOM structures, persisting the application state, transferring application data that was retrieved already by the server, and other processes.

## Why is hydration important?

Hydration improves application performance by avoiding extra work to re-create DOM nodes. Instead, Angular tries to match existing DOM elements to the applications structure at runtime and reuses DOM nodes when possible. This results in a performance improvement that can be measured using [Core Web Vitals (CWV)](https://web.dev/learn-core-web-vitals/) statistics, such as reducing the First Input Delay ([FID](https://web.dev/fid/)) and Largest Contentful Paint ([LCP](https://web.dev/lcp/)), as well as Cumulative Layout Shift ([CLS](https://web.dev/cls/)). Improving these numbers also affects things like SEO performance.

Without hydration enabled, server-side rendered Angular applications will destroy and re-render the application's DOM, which may result in a visible UI flicker. This re-rendering can negatively impact [Core Web Vitals](https://web.dev/learn-core-web-vitals/) like [LCP](https://web.dev/lcp/) and cause a layout shift. Enabling hydration allows the existing DOM to be re-used and prevents a flicker.

## How do you enable hydration in Angular

Hydration can be enabled for server-side rendered (SSR) applications only. Follow the [Angular SSR Guide](guide/ssr) to enable server-side rendering first.

### Using Angular CLI

If you've used Angular CLI to enable SSR (either by enabling it during application creation or later via `ng add @angular/ssr`), the code that enables hydration should already be included into your application.

### Manual setup

If you have a custom setup and didn't use Angular CLI to enable SSR, you can enable hydration manually by visiting your main application component or module and importing `provideClientHydration` from `@angular/platform-browser`. You'll then add that provider to your app's bootstrapping providers list.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration()]
});
```

Alternatively if you are using NgModules, you would add `provideClientHydration` to your root app module's provider list.

```typescript
import {provideClientHydration} from '@angular/platform-browser';
import {NgModule} from '@angular/core';

@NgModule({
  declarations: [AppComponent],
  exports: [AppComponent],
  bootstrap: [AppComponent],
  providers: [provideClientHydration()],
})
export class AppModule {}
```

IMPORTANT: Make sure that the `provideClientHydration()` call is also included into a set of providers that is used to bootstrap an application on the **server**. In applications with the default project structure (generated by the `ng new` command), adding a call to the root `AppModule` should be sufficient, since this module is imported by the server module. If you use a custom setup, add the `provideClientHydration()` call to the providers list in the server bootstrap configuration.

### Verify that hydration is enabled

After you've configured hydration and have started up your server, load your application in the browser.

HELPFUL: You will likely need to fix instances of Direct DOM Manipulation before hydration will fully work either by switching to Angular constructs or by using `ngSkipHydration`. See [Constraints](#constraints), [Direct DOM Manipulation](#direct-dom-manipulation), and [How to skip hydration for particular components](#how-to-skip-hydration-for-particular-components) for more details.

While running an application in dev mode, you can confirm hydration is enabled by opening the Developer Tools in your browser and viewing the console. You should see a message that includes hydration-related stats, such as the number of components and nodes hydrated. Angular calculates the stats based on all components rendered on a page, including those that come from third-party libraries.

You can also use [Angular DevTools browser extension](tools/devtools) to see hydration status of components on a page. Angular DevTools also allows to enable an overlay to indicate which parts of the page were hydrated. If there is a hydration mismatch error - DevTools would also highlight a component that caused the error.

## Capturing and replaying events

When an application is rendered on the server, it is visible in a browser as soon as produced HTML loads. Users may assume that they can interact with the page, but event listeners are not attached until hydration completes. Starting from v18, you can enable the Event Replay feature that allows to capture all events that happen before hydration and replay those events once hydration has completed. You can enable it using the `withEventReplay()` function, for example:

```typescript
import {provideClientHydration, withEventReplay} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(withEventReplay())
  ]
});
```

### How event replay works
Event Replay is a feature that improves user experience by capturing user events that were triggered before the hydration process is complete. Then those events are replayed, ensuring none of that interaction was lost.

The Event Replay is divided into three main phases:

- **Capturing user interactions**<br>
Prior to **Hydration**, Event Replay captures and stores all interactions that the user may perform, such as clicks and other browser native events.

- **Storing events**<br>
The **Event Contract** keeps in memory all the interactions recorded in the previous step, ensuring that they are not lost for later replay.

- **Relaunch of events**<br>
Once **Hydration** is complete, Angular re-invokes the captured events.

Event replay supports _native browser events_, for example `click`, `mouseover`, and `focusin`. If you'd like to learn more about JSAction, the library that powers event replay, you can read more [on the readme](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme).

---

This feature ensures a consistent user experience, preventing user actions performed before Hydration from being ignored. NOTE: if you have [incremental hydration](guide/incremental-hydration) enabled, event replay is automatically enabled under the hood.

## Constraints

Hydration imposes a few constraints on your application that are not present without hydration enabled. Your application must have the same generated DOM structure on both the server and the client. The process of hydration expects the DOM tree to have the same structure in both places. This also includes whitespaces and comment nodes that Angular produces during the rendering on the server. Those whitespaces and nodes must be present in the HTML generated by the server-side rendering process.

IMPORTANT: The HTML produced by the server side rendering operation **must not** be altered between the server and the client.

If there is a mismatch between server and client DOM tree structures, the hydration process will encounter problems attempting to match up what was expected to what is actually present in the DOM. Components that do direct DOM manipulation using native DOM APIs are the most common culprit.

### Direct DOM Manipulation

If you have components that manipulate the DOM using native DOM APIs or use `innerHTML` or `outerHTML`, the hydration process will encounter errors. Specific cases where DOM manipulation is a problem are situations like accessing the `document`, querying for specific elements, and injecting additional nodes using `appendChild`. Detaching DOM nodes and moving them to other locations will also result in errors.

This is because Angular is unaware of these DOM changes and cannot resolve them during the hydration process. Angular will expect a certain structure, but it will encounter a different structure when attempting to hydrate. This mismatch will result in hydration failure and throw a DOM mismatch error ([see below](#errors)).

It is best to refactor your component to avoid this sort of DOM manipulation. Try to use Angular APIs to do this work, if you can. If you cannot refactor this behavior, use the `ngSkipHydration` attribute ([described below](#how-to-skip-hydration-for-particular-components)) until you can refactor into a hydration friendly solution.

### Valid HTML structure

There are a few cases where if you have a component template that does not have valid HTML structure, this could result in a DOM mismatch error during hydration.

As an example, here are some of the most common cases of this issue.

- `<table>` without a `<tbody>`
- `<div>` inside a `<p>`
- `<a>` inside another `<a>`

If you are uncertain about whether your HTML is valid, you can use a [syntax validator](https://validator.w3.org/) to check it.

NOTE: While the HTML standard does not require the `<tbody>` element inside tables, modern browsers automatically create a `<tbody>` element in tables that do not declare one. Because of this inconsistency, always explicitly declare a `<tbody>` element in tables to avoid hydration errors.

### Preserve Whitespaces Configuration

When using the hydration feature, we recommend using the default setting of `false` for `preserveWhitespaces`. If this setting is not in your tsconfig, the value will be `false` and no changes are required. If you choose to enable preserving whitespaces by adding `preserveWhitespaces: true` to your tsconfig, it is possible you may encounter issues with hydration. This is not yet a fully supported configuration.

HELPFUL: Make sure that this setting is set **consistently** in `tsconfig.server.json` for your server and `tsconfig.app.json` for your browser builds. A mismatched value will cause hydration to break.

If you choose to set this setting in your tsconfig, we recommend to set it only in `tsconfig.app.json` which by default the `tsconfig.server.json` will inherit it from.

### Custom or Noop Zone.js are not yet supported

Hydration relies on a signal from Zone.js when it becomes stable inside an application, so that Angular can start the serialization process on the server or post-hydration cleanup on the client to remove DOM nodes that remained unclaimed.

Providing a custom or a "noop" Zone.js implementation may lead to a different timing of the "stable" event, thus triggering the serialization or the cleanup too early or too late. This is not yet a fully supported configuration and you may need to adjust the timing of the `onStable` event in the custom Zone.js implementation.

## Errors

There are several hydration related errors you may encounter ranging from node mismatches to cases when the `ngSkipHydration` was used on an invalid host node. The most common error case that may occur is due to direct DOM manipulation using native APIs that results in hydration being unable to find or match the expected DOM tree structure on the client that was rendered by the server. The other case you may encounter this type of error was mentioned in the [Valid HTML structure](#valid-html-structure) section earlier. So, make sure the HTML in your templates are using valid structure, and you'll avoid that error case.

For a full reference on hydration related errors, visit the [Errors Reference Guide](/errors).

## How to skip hydration for particular components

Some components may not work properly with hydration enabled due to some of the aforementioned issues, like [Direct DOM Manipulation](#direct-dom-manipulation). As a workaround, you can add the `ngSkipHydration` attribute to a component's tag in order to skip hydrating the entire component.

```html
<app-example ngSkipHydration />
```

Alternatively you can set `ngSkipHydration` as a host binding.

```typescript
@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}
```

The `ngSkipHydration` attribute will force Angular to skip hydrating the entire component and its children. Using this attribute means that the component will behave as if hydration is not enabled, meaning it will destroy and re-render itself.

HELPFUL: This will fix rendering issues, but it means that for this component (and its children), you don't get the benefits of hydration. You will need to adjust your component's implementation to avoid hydration-breaking patterns (i.e. Direct DOM Manipulation) to be able to remove the skip hydration annotation.

The `ngSkipHydration` attribute can only be used on component host nodes. Angular throws an error if this attribute is added to other nodes.

Keep in mind that adding the `ngSkipHydration` attribute to your root application component would effectively disable hydration for your entire application. Be careful and thoughtful about using this attribute. It is intended as a last resort workaround. Components that break hydration should be considered bugs that need to be fixed.

## Hydration Timing and Application Stability

Application stability is an important part of the hydration process. Hydration and any post-hydration processes only occur once the application has reported stability. There are a number of ways that stability can be delayed. Examples include setting timeouts and intervals, unresolved promises, and pending microtasks. In those cases, you may encounter the [Application remains unstable](errors/NG0506) error, which indicates that your app has not yet reached the stable state after 10 seconds. If you're finding that your application is not hydrating right away, take a look at what is impacting application stability and refactor to avoid causing these delays.

## I18N

HELPFUL: By default, Angular will skip hydration for components that use i18n blocks, effectively re-rendering those components from scratch.

To enable hydration for i18n blocks, you can add [`withI18nSupport`](/api/platform-browser/withI18nSupport) to your `provideClientHydration` call.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration(withI18nSupport())]
});
```

## Consistent rendering across server-side and client-side
Avoid introducing `@if` blocks and other conditionals that display different content when server-side rendering than client-side rendering, such as using an `@if` block with Angular's `isPlatformBrowser` function. These rendering differences cause layout shifts, negatively impacting end-user experience and core web vitals.

## Third Party Libraries with DOM Manipulation

There are a number of third party libraries that depend on DOM manipulation to be able to render. D3 charts is a prime example. These libraries worked without hydration, but they may cause DOM mismatch errors when hydration is enabled. For now, if you encounter DOM mismatch errors using one of these libraries, you can add the `ngSkipHydration` attribute to the component that renders using that library.

## Third Party Scripts with DOM Manipulation

Many third party scripts, such as ad trackers and analytics, modify the DOM before hydration can occur. These scripts may cause hydration errors because the page no longer matches the structure expected by Angular. Prefer deferring this type of script until after hydration whenever possible. Consider using [`AfterNextRender`](api/core/afterNextRender) to delay the script until post-hydration processes have occurred.

## Incremental Hydration

Incremental hydration is an advanced form of hydration that allows for more granular control over when hydration happens. See the [incremental hydration guide](guide/incremental-hydration) for more information.
# Incremental Hydration

**Incremental hydration** is an advanced type of [hydration](guide/hydration) that can leave sections of your application dehydrated and _incrementally_ trigger hydration of those sections as they are needed.

## Why use incremental hydration?

Incremental hydration is a performance improvement that builds on top of full application hydration. It can produce smaller initial bundles while still providing an end-user experience that is comparable to a full application hydration experience. Smaller bundles improve initial load times, reducing [First Input Delay (FID)](https://web.dev/fid) and [Cumulative Layout Shift (CLS)](https://web.dev/cls).

Incremental hydration also lets you use deferrable views (`@defer`) for content that may not have been deferrable before. Specifically, you can now use deferrable views for content that is above the fold. Prior to incremental hydration, putting a `@defer` block above the fold would result in placeholder content rendering and then being replaced by the `@defer` block's main template content. This would result in a layout shift. Incremental hydration means the main template of the `@defer` block will render with no layout shift on hydration.

## How do you enable incremental hydration in Angular?

You can enable incremental hydration for applications that already use server-side rendering (SSR) with hydration. Follow the [Angular SSR Guide](guide/ssr) to enable server-side rendering and the [Angular Hydration Guide](guide/hydration) to enable hydration first.

Enable incremental hydration by adding the `withIncrementalHydration()` function to the `provideClientHydration` provider.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withIncrementalHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration(withIncrementalHydration())]
});
```

Incremental Hydration depends on and enables [event replay](guide/hydration#capturing-and-replaying-events) automatically. If you already have `withEventReplay()` in your list, you can safely remove it after enabling incremental hydration.

## How does incremental hydration work?

Incremental hydration builds on top of full-application [hydration](guide/hydration), [deferrable views](guide/defer), and [event replay](guide/hydration#capturing-and-replaying-events). With incremental hydration, you can add additional triggers to `@defer` blocks that define incremental hydration boundaries. Adding a `hydrate` trigger to a defer block tells Angular that it should load that defer block's dependencies during server-side rendering and render the main template rather than the `@placeholder`. When client-side rendering, the dependencies are still deferred, and the defer block content stays dehydrated until its `hydrate` trigger fires. That trigger tells the defer block to fetch its dependencies and hydrate the content. Any browser events, specifically those that match listeners registered in your component, that are triggered by the user prior to hydration are queued up and replayed once the hydration process is complete.

## Controlling hydration of content with triggers

You can specify **hydrate triggers** that control when Angular loads and hydrates deferred content. These are additional triggers that can be used alongside regular `@defer` triggers.

Each `@defer` block may have multiple hydrate event triggers, separated with a semicolon (`;`). Angular triggers hydration when _any_ of the triggers fire.

There are three types of hydrate triggers: `hydrate on`, `hydrate when`, and `hydrate never`.

### `hydrate on`

`hydrate on` specifies a condition for when hydration is triggered for the `@defer` block.

The available triggers are as follows:

| Trigger                                             | Description                                                            |
| --------------------------------------------------- | ---------------------------------------------------------------------- |
| [`hydrate on idle`](#hydrate-on-idle)               | Triggers when the browser is idle.                                     |
| [`hydrate on viewport`](#hydrate-on-viewport)       | Triggers when specified content enters the viewport                    |
| [`hydrate on interaction`](#hydrate-on-interaction) | Triggers when the user interacts with specified element                |
| [`hydrate on hover`](#hydrate-on-hover)             | Triggers when the mouse hovers over specified area                     |
| [`hydrate on immediate`](#hydrate-on-immediate)     | Triggers immediately after non-deferred content has finished rendering |
| [`hydrate on timer`](#hydrate-on-timer)             | Triggers after a specific duration                                     |

#### `hydrate on idle`

The `hydrate on idle` trigger loads the deferrable view's dependencies and hydrates the content once the browser has reached an idle state, based on `requestIdleCallback`.

```html
@defer (hydrate on idle) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on viewport`

The `hydrate on viewport` trigger loads the deferrable view's dependencies and hydrates the corresponding page of the app when the specified content enters the viewport using the
[Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API).

```html
@defer (hydrate on viewport) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on interaction`

The `hydrate on interaction` trigger loads the deferrable view's dependencies and hydrates the content when the user interacts with the specified element through
`click` or `keydown` events.

```html
@defer (hydrate on interaction) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on hover`

The `hydrate on hover` trigger loads the deferrable view's dependencies and hydrates the content when the mouse has hovered over the triggered area through the
`mouseover` and `focusin` events.

```html
@defer (hydrate on hover) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on immediate`

The `hydrate on immediate` trigger loads the deferrable view's dependencies and hydrates the content immediately. This means that the deferred block loads as soon
as all other non-deferred content has finished rendering.

```html
@defer (hydrate on immediate) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on timer`

The `hydrate on timer` trigger loads the deferrable view's dependencies and hydrates the content after a specified duration.

```html
@defer (hydrate on timer(500ms)) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

The duration parameter must be specified in milliseconds (`ms`) or seconds (`s`).

### `hydrate when`

The `hydrate when` trigger accepts a custom conditional expression and loads the deferrable view's dependencies and hydrates the content when the
condition becomes truthy.

```html
@defer (hydrate when condition) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

NOTE: `hydrate when` conditions only trigger when they are the top-most dehydrated `@defer` block. The condition provided for the trigger is
specified in the parent component, which needs to exist before it can be triggered. If the parent block is dehydrated, that expression will not yet
be resolvable by Angular.

### `hydrate never`

The `hydrate never` allows users to specify that the content in the defer block should remain dehydrated indefinitely, effectively becoming static
content. Note that this applies to the initial render only. During a subsequent client-side render, a `@defer` block with `hydrate never` would
still fetch dependencies, as hydration only applies to initial load of server-side rendered content. In the example below, subsequent client-side
renders would load the `@defer` block dependencies on viewport.

```html
@defer (on viewport; hydrate never) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

NOTE: Using `hydrate never` prevents hydration of the entire nested subtree of a given `@defer` block. No other `hydrate` triggers fire for content nested underneath that block.

## Hydrate triggers alongside regular triggers

Hydrate triggers are additional triggers that are used alongside regular triggers on a `@defer` block. Hydration is an initial load optimization, and that means hydrate triggers only apply to that initial load. Any subsequent client side render will still use the regular trigger.

```html
@defer (on idle; hydrate on interaction) {
  <example-cmp />
} @placeholder{
  <div>Example Placeholder</div>
}
```

In this example, on the initial load, the `hydrate on interaction` applies. Hydration will be triggered on interaction with the `<example-cmp />` component. On any subsequent page load that is client-side rendered, for example when a user clicks a routerLink that loads a page with this component, the `on idle` will apply.

## How does incremental hydration work with nested `@defer` blocks?

Angular's component and dependency system is hierarchical, which means hydrating any component requires all of its parents also be hydrated. So if hydration is triggered for a child `@defer` block of a nested set of dehydrated `@defer` blocks, hydration is triggered from the top-most dehydrated `@defer` block down to the triggered child and fire in that order.

```html
@defer (hydrate on interaction) {
  <parent-block-cmp />
  @defer (hydrate on hover) {
    <child-block-cmp />
  } @placeholder {
    <div>Child placeholder</div>
  }
} @placeholder{
  <div>Parent Placeholder</div>
}
```

In the above example, hovering over the nested `@defer` block triggers hydration. The parent `@defer` block with the `<parent-block-cmp />` hydrates first, then the child `@defer` block with `<child-block-cmp />` hydrates after.

## Constraints

Incremental hydration has the same constraints as full-application hydration, including limits on direct DOM manipulation and requiring valid HTML structure. Visit the [Hydration guide constraints](guide/hydration#constraints) section for more details.

## Do I still need to specify `@placeholder` blocks?

Yes. `@placeholder` block content is not used for incremental hydration, but a `@placeholder` is still necessary for subsequent client-side rendering cases. If your content was not on the route that was part of the initial load, then any navigation to the route that has your `@defer` block content renders like a regular `@defer` block. So the `@placeholder` is rendered in those client-side rendering cases.
# Pruebas

Probar tu aplicación Angular te ayuda a verificar que tu aplicación está funcionando como esperas.

## Configurar pruebas

Angular CLI descarga e instala todo lo que necesitas para probar una aplicación Angular con [Jasmine testing framework](https://jasmine.github.io).

El proyecto que creas con el CLI está inmediatamente listo para probar.
Solo ejecuta el comando CLI [`ng test`](cli/test):

```shell
ng test
```
El comando `ng test` construye la aplicación en modo *watch*,
y lanza el [Karma test runner](https://karma-runner.github.io).

La salida de consola se ve como a continuación:

```shell
02 11 2022 09:08:28.605:INFO [karma-server]: Karma v6.4.1 server started at http://localhost:9876/
02 11 2022 09:08:28.607:INFO [launcher]: Launching browsers Chrome with concurrency unlimited
02 11 2022 09:08:28.620:INFO [launcher]: Starting browser Chrome
02 11 2022 09:08:31.312:INFO [Chrome]: Connected on socket -LaEYvD2R7MdcS0-AAAB with id 31534482
Chrome: Executed 3 of 3 SUCCESS (0.193 secs / 0.172 secs)
TOTAL: 3 SUCCESS
```
La última línea del log muestra que Karma ejecutó tres pruebas que todas pasaron.

La salida de pruebas se muestra en el navegador usando [Karma Jasmine HTML Reporter](https://github.com/dfederm/karma-jasmine-html-reporter).

Haz clic en una fila de prueba para re-ejecutar solo esa prueba o haz clic en una descripción para re-ejecutar las pruebas en el grupo de pruebas seleccionado $"test suite"$.

Mientras tanto, el comando `ng test` está observando cambios.

Para ver esto en acción, haz un pequeño cambio a `app.component.ts` y guarda.
Las pruebas se ejecutan nuevamente, el navegador se actualiza y los nuevos resultados de prueba aparecen.

## Configuración

Angular CLI se encarga de la configuración de Jasmine y Karma por ti. Construye la configuración completa en memoria, basándose en opciones especificadas en el archivo `angular.json`.

Si quieres personalizar Karma, puedes crear un `karma.conf.js` ejecutando el siguiente comando:

```shell
ng generate config karma
```
ÚTIL: Lee más sobre la configuración de Karma en la [guía de configuración de Karma](http://karma-runner.github.io/6.4/config/configuration-file.html).

### Otros frameworks de prueba

También puedes hacer pruebas unitarias de una aplicación Angular con otras librerías de prueba y test runners.
Cada librería y runner tiene sus propios procedimientos de instalación, configuración y sintaxis distintivos.

### Nombre y ubicación del archivo de prueba

Dentro de la carpeta `src/app` el Angular CLI generó un archivo de prueba para el `AppComponent` llamado `app.component.spec.ts`.

IMPORTANTE: La extensión del archivo de prueba **debe ser `.spec.ts`** para que las herramientas puedan identificarlo como un archivo con pruebas $también conocido como un archivo *spec*$.

Los archivos `app.component.ts` y `app.component.spec.ts` son hermanos en la misma carpeta.
Los nombres raíz de los archivos $`app.component`$ son los mismos para ambos archivos.

Adopta estas dos convenciones en tus propios proyectos para *cada tipo* de archivo de prueba.

#### Coloca tu archivo spec junto al archivo que prueba

Es una buena idea colocar los archivos spec de prueba unitaria en la misma carpeta
que los archivos de código fuente de la aplicación que prueban:

* Tales pruebas son fáciles de encontrar
* Ves de un vistazo si una parte de tu aplicación carece de pruebas
* Las pruebas cercanas pueden revelar cómo funciona una parte en contexto
* Cuando mueves el código fuente $inevitable$, recuerdas mover la prueba
* Cuando renombras el archivo fuente $inevitable$, recuerdas renombrar el archivo de prueba

#### Coloca tus archivos spec en una carpeta de prueba

Las specs de integración de aplicación pueden probar las interacciones de múltiples partes
distribuidas en carpetas y módulos.
Realmente no pertenecen a ninguna parte en particular, por lo que no tienen un
hogar natural junto a ningún archivo.

A menudo es mejor crear una carpeta apropiada para ellas en el directorio `tests`.

Por supuesto, las specs que prueban los helpers de prueba pertenecen en la carpeta `test`,
junto a sus archivos helper correspondientes.

## Pruebas en integración continua

Una de las mejores maneras de mantener tu proyecto libre de errores es a través de un conjunto de pruebas, pero podrías olvidar ejecutar las pruebas todo el tiempo.

Los servidores de integración continua $CI$ te permiten configurar el repositorio de tu proyecto para que tus pruebas se ejecuten en cada commit y pull request.

Para probar tu aplicación Angular CLI en integración continua $CI$ ejecuta el siguiente comando:

```shell
ng test --no-watch --no-progress --browsers=ChromeHeadless
```
## Más información sobre pruebas

Después de que hayas configurado tu aplicación para pruebas, podrías encontrar útiles las siguientes guías de pruebas.

|                                                                    | Detalles |
|:---                                                                |:---     |
| [Cobertura de código](guide/testing/code-coverage)                       | Cuánto de tu aplicación cubren tus pruebas y cómo especificar cantidades requeridas. |
| [Probar servicios](guide/testing/services)                         | Cómo probar los servicios que usa tu aplicación.                                   |
| [Fundamentos de probar componentes](guide/testing/components-basics)    | Fundamentos de probar componentes en Angular.                                             |
| [Escenarios de prueba de componentes](guide/testing/components-scenarios)  | Varios tipos de escenarios de prueba de componentes y casos de uso.                       |
| [Probar directivas de atributo](guide/testing/attribute-directives) | Cómo probar tus directivas de atributo.                                            |
| [Probar pipes](guide/testing/pipes)                               | Cómo probar pipes.                                                                |
| [Depurar pruebas](guide/testing/debugging)                            | Bugs comunes de pruebas.                                                              |
| [APIs utilitarias de pruebas](guide/testing/utility-apis)                 | Características de pruebas en Angular.                                                         |

# Descubrir cuánto código estás probando

Angular CLI puede ejecutar pruebas unitarias y crear reportes de cobertura de código.
Los reportes de cobertura de código te muestran cualquier parte de tu código base que podría no estar correctamente probada por tus pruebas unitarias.

Para generar un reporte de cobertura ejecuta el siguiente comando en la raíz de tu proyecto.

```shell
ng test --no-watch --code-coverage
```
Cuando las pruebas estén completas, el comando crea un nuevo directorio `/coverage` en el proyecto.
Abre el archivo `index.html` para ver un reporte con tu código fuente y valores de cobertura de código.

Si quieres crear reportes de cobertura de código cada vez que pruebas, establece la siguiente opción en el archivo de configuración de Angular CLI, `angular.json`:

```json
"test": {
  "options": {
    "codeCoverage": true
  }
}
```
## Aplicación de cobertura de código

Los porcentajes de cobertura de código te permiten estimar cuánto de tu código está probado.
Si tu equipo decide sobre una cantidad mínima establecida para ser probada unitariamente, aplica este mínimo con Angular CLI.

Por ejemplo, supón que quieres que la base de código tenga un mínimo de 80% de cobertura de código.
Para habilitar esto, abre el archivo de configuración de la plataforma de pruebas [Karma](https://karma-runner.github.io), `karma.conf.js`, y agrega la propiedad `check` en la clave `coverageReporter:`.

```javascript
coverageReporter: {
  dir: require('path').join(__dirname, './coverage/<project-name>'),
  subdir: '.',
  reporters: [
    { type: 'html' },
    { type: 'text-summary' }
  ],
  check: {
    global: {
      statements: 80,
      branches: 80,
      functions: 80,
      lines: 80
    }
  }
}
```
ÚTIL: Lee más sobre crear y ajustar la configuración de Karma en la [guía de pruebas](guide/testing#configuration).

La propiedad `check` hace que la herramienta aplique un mínimo de 80% de cobertura de código cuando las pruebas unitarias se ejecutan en el proyecto.

Lee más sobre opciones de configuración de cobertura en la [documentación de karma coverage](https://github.com/karma-runner/karma-coverage/blob/master/docs/configuration.md).
# Probar servicios

Para verificar que tus servicios están funcionando como pretendes, puedes escribir pruebas específicamente para ellos.

Los servicios son a menudo los archivos más sencillos de probar unitariamente.
Aquí hay algunas pruebas unitarias síncronas y asíncronas del `ValueService` escritas sin ayuda de las utilidades de pruebas de Angular.

```
## Servicios con dependencias

Los servicios a menudo dependen de otros servicios que Angular inyecta en el constructor.
En muchos casos, puedes crear e *inyectar* estas dependencias manualmente mientras llamas al constructor del servicio.

El `MasterService` es un ejemplo simple:

<docs-code header="app/demo/demo.ts" path="adev/src/content/examples/testing/src/app/demo/demo.ts" visibleRegion="MasterService"/>

`MasterService` delega su único método, `getValue`, al `ValueService` inyectado.

Aquí hay varias formas de probarlo.

<docs-code header="app/demo/demo.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="MasterService"/>

La primera prueba crea un `ValueService` con `new` y lo pasa al constructor de `MasterService`.

Sin embargo, inyectar el servicio real rara vez funciona bien ya que la mayoría de los servicios dependientes son difíciles de crear y controlar.

En su lugar, simula la dependencia, usa un valor dummy, o crea un [spy](https://jasmine.github.io/tutorials/your_first_suite#section-Spies) en el método pertinente del servicio.

ÚTIL: Prefiere los spies ya que usualmente son la mejor forma de simular servicios.

Estas técnicas estándar de pruebas son geniales para probar servicios de forma aislada unitariamente.

Sin embargo, casi siempre inyectas servicios en clases de aplicación usando inyección de dependencias de Angular y deberías tener pruebas que reflejen ese patrón de uso.
Las utilidades de pruebas de Angular hacen que sea sencillo investigar cómo se comportan los servicios inyectados.

## Probar servicios con el `TestBed`

Tu aplicación depende de la [inyección de dependencias (DI)](guide/di) de Angular para crear servicios.
Cuando un servicio tiene un servicio dependiente, DI encuentra o crea ese servicio dependiente.
Y si ese servicio dependiente tiene sus propias dependencias, DI las encuentra-o-crea también.

Como *consumidor* del servicio, no te preocupas por nada de esto.
No te preocupas por el orden de los argumentos del constructor o cómo se crean.

Como *probador* del servicio, debes al menos pensar sobre el primer nivel de dependencias del servicio pero *puedes* dejar que Angular DI haga la creación del servicio y se ocupe del orden de los argumentos del constructor cuando usas la utilidad de pruebas `TestBed` para proporcionar y crear servicios.

## Angular `TestBed`

El `TestBed` es la más importante de las utilidades de pruebas de Angular.
El `TestBed` crea un módulo *test* de Angular construido dinámicamente que emula un [@NgModule](guide/ngmodules) de Angular.

El método `TestBed.configureTestingModule()` toma un objeto de metadata que puede tener la mayoría de las propiedades de un [@NgModule](guide/ngmodules).

Para probar un servicio, estableces la propiedad de metadata `providers` con un array de los servicios que probarás o simularás.

<docs-code header="app/demo/demo.testbed.spec.ts (provide ValueService in beforeEach)" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-before-each"/>

Luego inyéctalo dentro de una prueba llamando a `TestBed.inject()` con la clase del servicio como argumento.

ÚTIL: `TestBed.get()` fue deprecado a partir de la versión 9 de Angular.
Para ayudar a minimizar cambios disruptivos, Angular introduce una nueva función llamada `TestBed.inject()`, que deberías usar en su lugar.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-inject-it"/>

O dentro del `beforeEach()` si prefieres inyectar el servicio como parte de tu configuración.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-inject-before-each">
```
Cuando pruebes un servicio con una dependencia, proporciona el mock en el array `providers`.

En el siguiente ejemplo, el mock es un objeto spy.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="master-service-before-each"/>

La prueba consume ese spy de la misma manera que lo hizo antes.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="master-service-it"/>

## Probar sin `beforeEach()`

La mayoría de suites de prueba en esta guía llaman a `beforeEach()` para establecer las precondiciones para cada prueba `it()` y dependen del `TestBed` para crear clases e inyectar servicios.

Hay otra escuela de pruebas que nunca llama a `beforeEach()` y prefiere crear clases explícitamente en lugar de usar el `TestBed`.

Aquí está cómo podrías reescribir una de las pruebas de `MasterService` en ese estilo.

Comienza poniendo código preparatorio reutilizable en una función *setup* en lugar de `beforeEach()`.

<docs-code header="app/demo/demo.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-setup"/>

La función `setup()` retorna un objeto literal con las variables, como `masterService`, que una prueba podría referenciar.
No defines variables *semi-globales* $por ejemplo, `let masterService: MasterService`$ en el cuerpo del `describe()`.

Luego cada prueba invoca `setup()` en su primera línea, antes de continuar con pasos que manipulan el sujeto de prueba y afirman expectativas.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-test"/>

Nota cómo la prueba usa [*asignación por desestructuración*](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) para extraer las variables de setup que necesita.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-setup-call"/>

Muchos desarrolladores sienten que este enfoque es más limpio y más explícito que el estilo tradicional de `beforeEach()`.

Aunque esta guía de pruebas sigue el estilo tradicional y los [schematics por defecto del CLI](https://github.com/angular/angular-cli) generan archivos de prueba con `beforeEach()` y `TestBed`, siéntete libre de adoptar *este enfoque alternativo* en tus propios proyectos.

## Probar servicios HTTP

Los servicios de datos que hacen llamadas HTTP a servidores remotos típicamente inyectan y delegan al servicio [`HttpClient`](guide/http/testing) de Angular para llamadas XHR.

Puedes probar un servicio de datos con un spy de `HttpClient` inyectado como probarías cualquier servicio con una dependencia.

<docs-code header="app/model/hero.service.spec.ts (tests with spies)" path="adev/src/content/examples/testing/src/app/model/hero.service.spec.ts" visibleRegion="test-with-spies"/>

IMPORTANTE: Los métodos de `HeroService` retornan `Observables`.
Debes *suscribirte* a un observable para $a$ hacer que se ejecute y $b$ afirmar que el método tiene éxito o falla.

El método `subscribe()` toma un callback de éxito $`next`$ y uno de fallo $`error`$.
Asegúrate de proporcionar *ambos* callbacks para que captures errores.
Descuidar hacerlo produce un error asíncrono no capturado de observable que el test runner probablemente atribuirá a una prueba completamente diferente.

## `HttpClientTestingModule`

Las interacciones extendidas entre un servicio de datos y el `HttpClient` pueden ser complejas y difíciles de simular con spies.

El `HttpClientTestingModule` puede hacer que estos escenarios de pruebas sean más manejables.

Mientras que la *muestra de código* que acompaña esta guía demuestra `HttpClientTestingModule`, esta página difiere a la [guía de Http](guide/http/testing), que cubre pruebas con el `HttpClientTestingModule` en detalle.
# Fundamentos de probar componentes

Un componente, a diferencia de todas las otras partes de una aplicación Angular, combina una plantilla HTML y una clase TypeScript.
El componente verdaderamente es la plantilla y la clase *trabajando juntas*.
Para probar adecuadamente un componente, deberías probar que trabajen juntos como se pretende.

Tales pruebas requieren crear el elemento host del componente en el DOM del navegador, como hace Angular, e investigar la interacción de la clase del componente con el DOM como se describe en su plantilla.

El `TestBed` de Angular facilita este tipo de pruebas como verás en las siguientes secciones.
Pero en muchos casos, *probar la clase del componente sola*, sin involucramiento del DOM, puede validar mucho del comportamiento del componente de una manera más directa y obvia.

## Pruebas del DOM de componentes

Un componente es más que solo su clase.
Un componente interactúa con el DOM y con otros componentes.
Las clases solas no pueden decirte si el componente va a renderizar correctamente, responder a la entrada y gestos del usuario, o integrarse con sus componentes padre e hijo.

* ¿Está `Lightswitch.clicked()` vinculado a algo de modo que el usuario pueda invocarlo?
* ¿Se muestra el `Lightswitch.message`?
* ¿Puede el usuario realmente seleccionar el héroe mostrado por `DashboardHeroComponent`?
* ¿Se muestra el nombre del héroe como se espera $como mayúsculas$?
* ¿Se muestra el mensaje de bienvenida por la plantilla de `WelcomeComponent`?

Estas podrían no ser preguntas problemáticas para los componentes simples precedentes ilustrados.
Pero muchos componentes tienen interacciones complejas con los elementos DOM descritos en sus plantillas, causando que HTML aparezca y desaparezca a medida que el estado del componente cambia.

Para responder estos tipos de preguntas, tienes que crear los elementos DOM asociados con los componentes, debes examinar el DOM para confirmar que el estado del componente se muestra correctamente en los momentos apropiados, y debes simular la interacción del usuario con la pantalla para determinar si esas interacciones hacen que el componente se comporte como se espera.

Para escribir estos tipos de prueba, usarás características adicionales del `TestBed` así como otros helpers de pruebas.

### Pruebas generadas por el CLI

El CLI crea un archivo de prueba inicial para ti por defecto cuando le pides que genere un nuevo componente.

Por ejemplo, el siguiente comando del CLI genera un `BannerComponent` en la carpeta `app/banner` $con plantilla y estilos inline$:

```shell
ng generate component banner --inline-template --inline-style --module app
```
También genera un archivo de prueba inicial para el componente, `banner-external.component.spec.ts`, que se ve así:

<docs-code header="app/banner/banner-external.component.spec.ts (initial)" path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v1"/>

ÚTIL: Porque `compileComponents` es asíncrono, usa la función utilitaria [`waitForAsync`](api/core/testing/waitForAsync) importada de `@angular/core/testing`.

Consulta la sección [waitForAsync](guide/testing/components-scenarios#waitForAsync) para más detalles.

### Reducir la configuración

Solo las últimas tres líneas de este archivo realmente prueban el componente y todo lo que hacen es afirmar que Angular puede crear el componente.

El resto del archivo es código de configuración boilerplate anticipando pruebas más avanzadas que *podrían* volverse necesarias si el componente evoluciona en algo sustancial.

Aprenderás sobre estas características de prueba avanzadas en las siguientes secciones.
Por ahora, puedes reducir radicalmente este archivo de prueba a un tamaño más manejable:

<docs-code header="app/banner/banner-initial.component.spec.ts (minimal)" path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v2"/>

En este ejemplo, el objeto de metadata pasado a `TestBed.configureTestingModule` simplemente declara `BannerComponent`, el componente a probar.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="configureTestingModule"/>

ÚTIL: No hay necesidad de declarar o importar nada más.
El módulo de prueba por defecto está pre-configurado con algo como el `BrowserModule` de `@angular/platform-browser`.

Más tarde llamarás a `TestBed.configureTestingModule()` con imports, providers y más declarations para adaptarse a tus necesidades de pruebas.
Métodos `override` opcionales pueden ajustar aún más aspectos de la configuración.

### `createComponent()`

Después de configurar `TestBed`, llamas a su método `createComponent()`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="createComponent"/>

`TestBed.createComponent()` crea una instancia del `BannerComponent`, agrega un elemento correspondiente al DOM del test-runner, y retorna un [`ComponentFixture`](#componentfixture).

IMPORTANTE: No re-configures `TestBed` después de llamar a `createComponent`.

El método `createComponent` congela la definición actual del `TestBed`, cerrándola a más configuración.

No puedes llamar más métodos de configuración del `TestBed`, ni `configureTestingModule()`, ni `get()`, ni ninguno de los métodos `override...`.
Si lo intentas, `TestBed` lanza un error.

### `ComponentFixture`

El [ComponentFixture](api/core/testing/ComponentFixture) es un harness de prueba para interactuar con el componente creado y su elemento correspondiente.

Accede a la instancia del componente a través del fixture y confirma que existe con una expectativa de Jasmine:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="componentInstance"/>

### `beforeEach()`

Agregarás más pruebas a medida que este componente evolucione.
En lugar de duplicar la configuración del `TestBed` para cada prueba, refactoriza para sacar la configuración en un `beforeEach()` de Jasmine y algunas variables de soporte:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v3"/>

Ahora agrega una prueba que obtiene el elemento del componente de `fixture.nativeElement` y busca el texto esperado.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-2"/>

### `nativeElement`

El valor de `ComponentFixture.nativeElement` tiene el tipo `any`.
Más tarde encontrarás el `DebugElement.nativeElement` y también tiene el tipo `any`.

Angular no puede saber en tiempo de compilación qué tipo de elemento HTML es el `nativeElement` o si siquiera es un elemento HTML.
La aplicación podría estar ejecutándose en una *plataforma no-navegador*, como el servidor o un [Web Worker](https://developer.mozilla.org/docs/Web/API/Web_Workers_API), donde el elemento podría tener una API disminuida o no existir en absoluto.

Las pruebas en esta guía están diseñadas para ejecutarse en un navegador, por lo que un valor `nativeElement` siempre será un `HTMLElement` o una de sus clases derivadas.

Sabiendo que es un `HTMLElement` de algún tipo, usa el `querySelector` HTML estándar para profundizar en el árbol de elementos.

Aquí hay otra prueba que llama a `HTMLElement.querySelector` para obtener el elemento párrafo y buscar el texto del banner:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-3"/>

### `DebugElement`

El *fixture* de Angular proporciona el elemento del componente directamente a través del `fixture.nativeElement`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="nativeElement"/>

Esto es en realidad un método de conveniencia, implementado como `fixture.debugElement.nativeElement`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="debugElement-nativeElement"/>

Hay una buena razón para esta ruta indirecta al elemento.

Las propiedades del `nativeElement` dependen del entorno de ejecución.
Podrías estar ejecutando estas pruebas en una plataforma *no-navegador* que no tiene un DOM o cuya emulación de DOM no soporta la API completa de `HTMLElement`.

Angular depende de la abstracción `DebugElement` para trabajar de forma segura en *todas las plataformas soportadas*.
En lugar de crear un árbol de elementos HTML, Angular crea un árbol `DebugElement` que envuelve los *elementos nativos* para la plataforma de ejecución.
La propiedad `nativeElement` desenvuelve el `DebugElement` y retorna el objeto de elemento específico de la plataforma.

Porque las pruebas de muestra para esta guía están diseñadas para ejecutarse solo en un navegador, un `nativeElement` en estas pruebas es siempre un `HTMLElement` cuyos métodos y propiedades familiares puedes explorar dentro de una prueba.

Aquí está la prueba anterior, re-implementada con `fixture.debugElement.nativeElement`:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-4"/>

El `DebugElement` tiene otros métodos y propiedades que son útiles en pruebas, como verás en otros lugares de esta guía.

Importas el símbolo `DebugElement` de la librería core de Angular.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="import-debug-element"/>

### `By.css()`

Aunque las pruebas en esta guía todas se ejecutan en el navegador, algunas aplicaciones podrían ejecutarse en una plataforma diferente al menos parte del tiempo.

Por ejemplo, el componente podría renderizar primero en el servidor como parte de una estrategia para hacer que la aplicación se inicie más rápido en dispositivos pobremente conectados.
El renderizador del lado del servidor podría no soportar la API completa de elementos HTML.
Si no soporta `querySelector`, la prueba anterior podría fallar.

El `DebugElement` ofrece métodos de consulta que funcionan para todas las plataformas soportadas.
Estos métodos de consulta toman una función *predicate* que retorna `true` cuando un nodo en el árbol `DebugElement` coincide con los criterios de selección.

Creas un *predicate* con la ayuda de una clase `By` importada de una librería para la plataforma de ejecución.
Aquí está el import `By` para la plataforma navegador:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="import-by"/>

El siguiente ejemplo re-implementa la prueba anterior con `DebugElement.query()` y el método `By.css` del navegador.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-5"/>

Algunas observaciones dignas de mención:

* El método estático `By.css()` selecciona nodos `DebugElement` con un [selector CSS estándar](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS selectors').
* La consulta retorna un `DebugElement` para el párrafo.
* Debes desenvolver ese resultado para obtener el elemento párrafo.

Cuando estás filtrando por selector CSS y solo probando propiedades del *elemento nativo* de un navegador, el enfoque `By.css` podría ser excesivo.

A menudo es más directo y claro filtrar con un método `HTMLElement` estándar como `querySelector()` o `querySelectorAll()`.
# Escenarios de prueba de componentes

Esta guía explora casos de uso comunes de prueba de componentes.

## Binding de componentes

En la aplicación de ejemplo, el `BannerComponent` presenta texto de título estático en la plantilla HTML.

Después de algunos cambios, el `BannerComponent` presenta un título dinámico vinculándose a la propiedad `title` del componente como esto.

```
Por mínimo que sea esto, decides agregar una prueba para confirmar que el componente realmente muestra el contenido correcto donde crees que debería.

### Consultar por el `<h1>`

Escribirás una secuencia de pruebas que inspeccionan el valor del elemento `<h1>` que envuelve el binding de interpolación de la propiedad *title*.

Actualizas el `beforeEach` para encontrar ese elemento con un `querySelector` HTML estándar y asignarlo a la variable `h1`.

<docs-code header="app/banner/banner.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="setup"/>

### `createComponent()` no vincula datos

Para tu primera prueba te gustaría ver que la pantalla muestra el `title` predeterminado.
Tu instinto es escribir una prueba que inmediatamente inspecciona el `<h1>` así:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="expect-h1-default-v1"/>

*Esa prueba falla* con el mensaje:

<docs-code language="javascript">

expected '' to contain 'Test Tour of Heroes'.
```
El binding ocurre cuando Angular realiza **detección de cambios**.

En producción, la detección de cambios se activa automáticamente cuando Angular crea un componente o el usuario ingresa una pulsación de tecla, por ejemplo.

El `TestBed.createComponent` no desencadena detección de cambios por defecto; un hecho confirmado en la prueba revisada:

```
### `detectChanges()`

Puedes decirle al `TestBed` que realice binding de datos llamando a `fixture.detectChanges()`.
Solo entonces el `<h1>` tiene el título esperado.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="expect-h1-default"/>

La detección de cambios retrasada es intencional y útil.
Le da al probador una oportunidad de inspeccionar y cambiar el estado del componente *antes de que Angular inicie el binding de datos y llame a [hooks de ciclo de vida](guide/components/lifecycle)*.

Aquí hay otra prueba que cambia la propiedad `title` del componente *antes* de llamar a `fixture.detectChanges()`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="after-change"/>

### Detección automática de cambios

Las pruebas de `BannerComponent` llaman frecuentemente a `detectChanges`.
Muchos probadores prefieren que el entorno de prueba de Angular ejecute la detección de cambios automáticamente como lo hace en producción.

Eso es posible configurando el `TestBed` con el provider `ComponentFixtureAutoDetect`.
Primero impórtalo de la librería utilitaria de testing:

<docs-code header="app/banner/banner.component.detect-changes.spec.ts (import)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="import-ComponentFixtureAutoDetect"/>

Luego agrégalo al array `providers` de la configuración del módulo de testing:

<docs-code header="app/banner/banner.component.detect-changes.spec.ts (AutoDetect)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="auto-detect"/>

ÚTIL: También puedes usar la función `fixture.autoDetectChanges()` en su lugar si solo quieres habilitar la detección automática de cambios después de hacer actualizaciones al estado del componente del fixture. Además, la detección automática de cambios está activada por defecto cuando usas `provideZonelessChangeDetection` y desactivarla no es recomendado.

Aquí hay tres pruebas que ilustran cómo funciona la detección automática de cambios.

<docs-code header="app/banner/banner.component.detect-changes.spec.ts (AutoDetect Tests)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="auto-detect-tests"/>

La primera prueba muestra el beneficio de la detección automática de cambios.

La segunda y tercera prueba revelan una limitación importante.
El entorno de testing de Angular no ejecuta detección de cambios síncronamente cuando las actualizaciones ocurren dentro del caso de prueba que cambió el `title` del componente.
La prueba debe llamar a `await fixture.whenStable` para esperar otra ronda de detección de cambios.

ÚTIL: Angular no sabe sobre actualizaciones directas a valores que no son signals. La forma más fácil de asegurar que la detección de cambios se programe es usar signals para valores leídos en la plantilla.

### Cambiar un valor de input con `dispatchEvent()`

Para simular la entrada del usuario, encuentra el elemento input y establece su propiedad `value`.

Pero hay un paso esencial, intermedio.

Angular no sabe que estableciste la propiedad `value` del elemento input.
No leerá esa propiedad hasta que generes el evento `input` del elemento llamando a `dispatchEvent()`.

El siguiente ejemplo demuestra la secuencia adecuada.

<docs-code header="app/hero/hero-detail.component.spec.ts (pipe test)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="title-case-pipe"/>

## Componente con archivos externos

El `BannerComponent` precedente está definido con una *plantilla inline* y *css inline*, especificados en las propiedades `@Component.template` y `@Component.styles` respectivamente.

Muchos componentes especifican *plantillas externas* y *css externo* con las propiedades `@Component.templateUrl` y `@Component.styleUrls` respectivamente, como lo hace la siguiente variante de `BannerComponent`.

<docs-code header="app/banner/banner-external.component.ts (metadata)" path="adev/src/content/examples/testing/src/app/banner/banner-external.component.ts" visibleRegion="metadata"/>

Esta sintaxis le dice al compilador de Angular que lea los archivos externos durante la compilación del componente.

Eso no es un problema cuando ejecutas el comando CLI `ng test` porque *compila la aplicación antes de ejecutar las pruebas*.

Sin embargo, si ejecutas las pruebas en un **entorno no-CLI**, las pruebas de este componente podrían fallar.
Por ejemplo, si ejecutas las pruebas de `BannerComponent` en un entorno de codificación web como [plunker](https://plnkr.co), verás un mensaje como este:

<docs-code hideCopy language="shell">

Error: This test module uses the component BannerComponent
which is using a "templateUrl" or "styleUrls", but they were never compiled.
Please call "TestBed.compileComponents" before your test.
```
Obtienes este mensaje de fallo de prueba cuando el entorno de runtime compila el código fuente *durante las pruebas mismas*.

Para corregir el problema, llama a `compileComponents()` como se explica en la siguiente sección [Llamando compileComponents](#calling-compilecomponents).

## Componente con una dependencia

Los componentes a menudo tienen dependencias de servicio.

El `WelcomeComponent` muestra un mensaje de bienvenida al usuario autenticado.
Sabe quién es el usuario basado en una propiedad del `UserService` inyectado:

```
El `WelcomeComponent` tiene lógica de decisión que interactúa con el servicio, lógica que hace que este componente valga la pena probar.

### Proporcionar dobles de prueba de servicio

Un *componente-bajo-prueba* no tiene que ser proporcionado con servicios reales.

Inyectar el `UserService` real podría ser difícil.
El servicio real podría pedirle al usuario credenciales de inicio de sesión e intentar llegar a un servidor de autenticación.
Estos comportamientos pueden ser difíciles de interceptar. Ten en cuenta que usar dobles de prueba hace que la prueba se comporte diferente de la producción, así que úsalos con moderación.

### Obtener servicios inyectados

Las pruebas necesitan acceso al `UserService` inyectado en el `WelcomeComponent`.

Angular tiene un sistema de inyección jerárquico.
Puede haber inyectores en múltiples niveles, desde el inyector raíz creado por el `TestBed` hacia abajo a través del árbol de componentes.

La forma más segura de obtener el servicio inyectado, la forma que ***siempre funciona***,
es **obtenerlo del inyector del *componente-bajo-prueba***.
El inyector del componente es una propiedad del `DebugElement` del fixture.

<docs-code header="WelcomeComponent's injector" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="injected-service"/>

ÚTIL: Esto _usualmente_ no es necesario. Los servicios a menudo se proporcionan en la raíz o los overrides del TestBed y pueden recuperarse más fácilmente con `TestBed.inject()` (ver abajo).

### `TestBed.inject()`

Esto es más fácil de recordar y menos verboso que recuperar un servicio usando el `DebugElement` del fixture.

En esta suite de pruebas, el *único* provider de `UserService` es el módulo de testing raíz, por lo que es seguro llamar a `TestBed.inject()` de la siguiente manera:

<docs-code header="TestBed injector" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="inject-from-testbed" />

ÚTIL: Para un caso de uso en el que `TestBed.inject()` no funciona, consulta la sección [*Override component providers*](#override-component-providers) que explica cuándo y por qué debes obtener el servicio del inyector del componente en su lugar.

### Configuración final y pruebas

Aquí está el `beforeEach()` completo, usando `TestBed.inject()`:

<docs-code header="app/welcome/welcome.component.spec.ts" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="setup"/>

Y aquí hay algunas pruebas:

<docs-code header="app/welcome/welcome.component.spec.ts" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="tests"/>

La primera es una prueba de cordura; confirma que el `UserService` es llamado y funciona.

ÚTIL: La función withContext $por ejemplo, `'expected name'`$ es una etiqueta de fallo opcional.
Si la expectativa falla, Jasmine agrega esta etiqueta al mensaje de fallo de expectativa.
En una spec con múltiples expectativas, puede ayudar a aclarar qué salió mal y qué expectativa falló.

Las pruebas restantes confirman la lógica del componente cuando el servicio retorna diferentes valores.
La segunda prueba valida el efecto de cambiar el nombre del usuario.
La tercera prueba verifica que el componente muestra el mensaje apropiado cuando no hay usuario autenticado.

## Componente con servicio async

En esta muestra, la plantilla `AboutComponent` aloja un `TwainComponent`.
El `TwainComponent` muestra citas de Mark Twain.

<docs-code header="app/twain/twain.component.ts (template)" path="adev/src/content/examples/testing/src/app/twain/twain.component.ts" visibleRegion="template" />

ÚTIL: El valor de la propiedad `quote` del componente pasa a través de un `AsyncPipe`.
Eso significa que la propiedad retorna ya sea una `Promise` o un `Observable`.

En este ejemplo, el método `TwainComponent.getQuote()` te dice que la propiedad `quote` retorna un `Observable`.

<docs-code header="app/twain/twain.component.ts (getQuote)" path="adev/src/content/examples/testing/src/app/twain/twain.component.ts" visibleRegion="get-quote"/>

El `TwainComponent` obtiene citas de un `TwainService` inyectado.
El componente inicia el `Observable` retornado con un valor placeholder $`'...'`$, antes de que el servicio pueda retornar su primera cita.

El `catchError` intercepta errores de servicio, prepara un mensaje de error, y retorna el valor placeholder en el canal de éxito.

Estas son todas características que querrás probar.

### Probar con un spy

Cuando se prueba un componente, solo la API pública del servicio debería importar.
En general, las pruebas mismas no deberían hacer llamadas a servidores remotos.
Deberían emular tales llamadas.
La configuración en este `app/twain/twain.component.spec.ts` muestra una forma de hacerlo:

<docs-code header="app/twain/twain.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="setup"/>

Enfócate en el spy.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="spy"/>

El spy está diseñado de tal manera que cualquier llamada a `getQuote` recibe un observable con una cita de prueba.
A diferencia del método `getQuote()` real, este spy evita el servidor y retorna un observable síncrono cuyo valor está disponible inmediatamente.

Puedes escribir muchas pruebas útiles con este spy, aunque su `Observable` sea síncrono.

ÚTIL: Es mejor limitar el uso de spies solo a lo que es necesario para la prueba. Crear mocks o spies para más de lo necesario puede ser frágil. A medida que el componente e injectable evolucionan, las pruebas no relacionadas pueden fallar porque ya no simulan suficientes comportamientos que de otro modo no afectarían la prueba.
### Prueba async con `fakeAsync()`

Para usar la funcionalidad `fakeAsync()`, debes importar `zone.js/testing` en tu archivo de configuración de pruebas.
Si creaste tu proyecto con Angular CLI, `zone-testing` ya está importado en `src/test.ts`.

La siguiente prueba confirma el comportamiento esperado cuando el servicio retorna un `ErrorObservable`.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="error-test"/>

ÚTIL: La función `it()` recibe un argumento de la siguiente forma.

<docs-code language="javascript">

fakeAsync(() => { /*test body*/ })
```
La función `fakeAsync()` habilita un estilo de codificación lineal ejecutando el cuerpo de la prueba en una `fakeAsync test zone` especial.
El cuerpo de la prueba aparece ser síncrono.
No hay sintaxis anidada $como un `Promise.then()`$ para interrumpir el flujo de control.

ÚTIL: Limitación: La función `fakeAsync()` no funcionará si el cuerpo de la prueba hace una llamada `XMLHttpRequest` $XHR$.
Las llamadas XHR dentro de una prueba son raras, pero si necesitas llamar XHR, consulta la sección [`waitForAsync()`](#waitForAsync).

IMPORTANTE: Ten en cuenta que las tareas asíncronas que ocurren dentro de la zona `fakeAsync` necesitan ejecutarse manualmente con `flush` o `tick`. Si intentas esperar a que se completen (es decir, usando `fixture.whenStable`) sin usar los helpers de prueba `fakeAsync` para avanzar el tiempo, tu prueba probablemente fallará. Ver abajo para más información.

### La función `tick()`

Tienes que llamar a [tick()](api/core/testing/tick) para avanzar el reloj virtual.

Llamar a [tick()](api/core/testing/tick) simula el paso del tiempo hasta que todas las actividades asíncronas pendientes terminen.
En este caso, espera al `setTimeout()` del observable.

La función [tick()](api/core/testing/tick) acepta `millis` y `tickOptions` como parámetros. El parámetro `millis` especifica cuánto avanza el reloj virtual y por defecto es `0` si no se proporciona.
Por ejemplo, si tienes un `setTimeout(fn, 100)` en una prueba `fakeAsync()`, necesitas usar `tick(100)` para desencadenar el callback fn.
El parámetro opcional `tickOptions` tiene una propiedad llamada `processNewMacroTasksSynchronously`. La propiedad `processNewMacroTasksSynchronously` representa si invocar nuevas macro tasks generadas al hacer tick y por defecto es `true`.

```
La función [tick()](api/core/testing/tick) es una de las utilidades de testing de Angular que importas con `TestBed`.
Es una compañera de `fakeAsync()` y solo puedes llamarla dentro de un cuerpo `fakeAsync()`.

### tickOptions

En este ejemplo, tienes una nueva macro task, la función `setTimeout` anidada. Por defecto, cuando el `tick` es setTimeout, tanto `outside` como `nested` se desencadenarán.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-tick-new-macro-task-sync"/>

En algunos casos, no quieres desencadenar la nueva macro task al hacer tick. Puedes usar `tick(millis, {processNewMacroTasksSynchronously: false})` para no invocar una nueva macro task.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-tick-new-macro-task-async"/>

### Comparar fechas dentro de fakeAsync()

`fakeAsync()` simula el paso del tiempo, lo que te permite calcular la diferencia entre fechas dentro de `fakeAsync()`.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-date"/>

### jasmine.clock con fakeAsync()

Jasmine también proporciona una característica `clock` para simular fechas.
Angular ejecuta automáticamente pruebas que se ejecutan después de que se llame `jasmine.clock().install()` dentro de un método `fakeAsync()` hasta que se llame `jasmine.clock().uninstall()`.
`fakeAsync()` no es necesario y lanza un error si se anida.

Por defecto, esta característica está deshabilitada.
Para habilitarla, establece una bandera global antes de importar `zone-testing`.

Si usas Angular CLI, configura esta bandera en `src/test.ts`.

<docs-code language="typescript">

[window as any]('__zone_symbol__fakeAsyncPatchLock') = true;
import 'zone.js/testing';
```
```
### Usar el scheduler de RxJS dentro de fakeAsync()

También puedes usar el scheduler de RxJS en `fakeAsync()` igual que usando `setTimeout()` o `setInterval()`, pero necesitas importar `zone.js/plugins/zone-patch-rxjs-fake-async` para parchear el scheduler de RxJS.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-rxjs"/>

### Soportar más macroTasks

Por defecto, `fakeAsync()` soporta las siguientes macro tasks.

* `setTimeout`
* `setInterval`
* `requestAnimationFrame`
* `webkitRequestAnimationFrame`
* `mozRequestAnimationFrame`

Si ejecutas otras macro tasks como `HTMLCanvasElement.toBlob()`, se lanza un error *"Unknown macroTask scheduled in fake async test"*.
Si quieres soportar tal caso, necesitas definir la macro task que quieres soportar en `beforeEach()`.
Por ejemplo:

<docs-code header="src/app/shared/canvas.component.spec.ts (excerpt)" path="adev/src/content/examples/testing/src/app/shared/canvas.component.spec.ts" visibleRegion="enable-toBlob-macrotask"/>

ÚTIL: Para hacer que el elemento `<canvas>` sea Zone.js-aware en tu aplicación, necesitas importar el parche `zone-patch-canvas` $ya sea en `polyfills.ts` o en el archivo específico que usa `<canvas>`$:

<docs-code header="src/polyfills.ts or src/app/shared/canvas.component.ts" path="adev/src/content/examples/testing/src/app/shared/canvas.component.ts" visibleRegion="import-canvas-patch"/>

### Observables async

Podrías estar satisfecho con la cobertura de prueba de estas pruebas.

Sin embargo, podrías estar preocupado por el hecho de que el servicio real no se comporta exactamente de esta manera.
El servicio real envía solicitudes a un servidor remoto.
Un servidor toma tiempo en responder y la respuesta ciertamente no estará disponible inmediatamente como en las dos pruebas anteriores.

Tus pruebas reflejarán el mundo real más fielmente si retornas un observable *asíncrono* del spy `getQuote()` así.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="async-setup"/>

### Helpers de observable async

El observable async fue producido por un helper `asyncData`.
El helper `asyncData` es una función utilitaria que tendrás que escribir tú mismo, o copiar esta de el código de muestra.

<docs-code header="testing/async-observable-helpers.ts" path="adev/src/content/examples/testing/src/testing/async-observable-helpers.ts" visibleRegion="async-data"/>

El observable de este helper emite el valor `data` en el siguiente turno del motor de JavaScript.

El [operador `defer()` de RxJS](http://reactivex.io/documentation/operators/defer.html) retorna un observable.
Toma una función factory que retorna ya sea una promesa o un observable.
Cuando algo se suscribe al observable de *defer*, agrega el suscriptor a un nuevo observable creado con esa factory.

El operador `defer()` transforma el `Promise.resolve()` en un nuevo observable que, como `HttpClient`, emite una vez y se completa.
Los suscriptores se desuscriben después de recibir el valor de datos.

Hay un helper similar para producir un error async.

<docs-code path="adev/src/content/examples/testing/src/testing/async-observable-helpers.ts" visibleRegion="async-error"/>

### Más pruebas async

Ahora que el spy `getQuote()` está retornando observables async, la mayoría de tus pruebas tendrán que ser async también.

Aquí hay una prueba `fakeAsync()` que demuestra el flujo de datos que esperarías en el mundo real.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="fake-async-test"/>

Nota que el elemento quote muestra el valor placeholder $`'...'`$ después de `ngOnInit()`.
La primera cita aún no ha llegado.

Para vaciar la primera cita del observable, llamas a [tick()](api/core/testing/tick).
Luego llamas a `detectChanges()` para decirle a Angular que actualice la pantalla.

Entonces puedes afirmar que el elemento quote muestra el texto esperado.

### Prueba async sin `fakeAsync()`

Aquí está la prueba `fakeAsync()` anterior, reescrita con el `async`.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="async-test"/>

### `whenStable`

La prueba debe esperar a que el observable `getQuote()` emita la siguiente cita.
En lugar de llamar a [tick()](api/core/testing/tick), llama a `fixture.whenStable()`.

El `fixture.whenStable()` retorna una promesa que se resuelve cuando la cola de tareas del motor de JavaScript se vuelve vacía.
En este ejemplo, la cola de tareas se vuelve vacía cuando el observable emite la primera cita.
## Componente con inputs y outputs

Un componente con inputs y outputs típicamente aparece dentro de la plantilla de vista de un componente host.
El host usa un property binding para establecer la propiedad input y un event binding para escuchar eventos generados por la propiedad output.

El objetivo de testing es verificar que tales bindings funcionen como se espera.
Las pruebas deberían establecer valores de input y escuchar eventos de output.

El `DashboardHeroComponent` es un pequeño ejemplo de un componente en este rol.
Muestra un héroe individual proporcionado por el `DashboardComponent`.
Hacer clic en ese héroe le dice al `DashboardComponent` que el usuario ha seleccionado el héroe.

El `DashboardHeroComponent` está incrustado en la plantilla `DashboardComponent` así:

<docs-code header="app/dashboard/dashboard.component.html (excerpt)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.html" visibleRegion="dashboard-hero"/>

El `DashboardHeroComponent` aparece en un bloque `@for`, que establece la propiedad input `hero` de cada componente al valor de bucle y escucha el evento `selected` del componente.

Aquí está la definición completa del componente:

<docs-code header="app/dashboard/dashboard-hero.component.ts (component)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.ts" visibleRegion="component"/>

Aunque probar un componente tan simple tiene poco valor intrínseco, vale la pena saber cómo.
Usa uno de estos enfoques:

* Probarlo como se usa por `DashboardComponent`
* Probarlo como un componente standalone
* Probarlo como se usa por un sustituto para `DashboardComponent`

El objetivo inmediato es probar el `DashboardHeroComponent`, no el `DashboardComponent`, así que, prueba la segunda y tercera opciones.

### Probar `DashboardHeroComponent` standalone

Aquí está la parte principal de la configuración del archivo spec.

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="setup"/>

Nota cómo el código de configuración asigna un héroe de prueba $`expectedHero`$ a la propiedad `hero` del componente, emulando la forma en que el `DashboardComponent` lo establecería usando el property binding en su repeater.

La siguiente prueba verifica que el nombre del héroe se propaga a la plantilla usando un binding.

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="name-test"/>

Porque la [plantilla](#dashboard-hero-component) pasa el nombre del héroe a través del `UpperCasePipe` de Angular, la prueba debe coincidir el valor del elemento con el nombre en mayúsculas.

### Hacer clic

Hacer clic en el héroe debería generar un evento `selected` que el componente host $`DashboardComponent` presumiblemente$ puede escuchar:

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test"/>

La propiedad `selected` del componente retorna un `EventEmitter`, que se ve como un `Observable` síncrono de RxJS para los consumidores.
La prueba se suscribe a él *explícitamente* igual que el componente host lo hace *implícitamente*.

Si el componente se comporta como se espera, hacer clic en el elemento del héroe debería decirle a la propiedad `selected` del componente que emita el objeto `hero`.

La prueba detecta ese evento a través de su suscripción a `selected`.

### `triggerEventHandler`

El `heroDe` en la prueba anterior es un `DebugElement` que representa el `<div>` del héroe.

Tiene propiedades y métodos de Angular que abstraen la interacción con el elemento nativo.
Esta prueba llama al `DebugElement.triggerEventHandler` con el nombre de evento "click".
El binding de evento "click" responde llamando a `DashboardHeroComponent.click()`.

El `DebugElement.triggerEventHandler` de Angular puede generar *cualquier evento vinculado a datos* por su *nombre de evento*.
El segundo parámetro es el objeto de evento pasado al handler.

La prueba desencadenó un evento "click".

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="trigger-event-handler"/>

En este caso, la prueba asume correctamente que el handler de evento de runtime, el método `click()` del componente, no se preocupa por el objeto de evento.

ÚTIL: Otros handlers son menos indulgentes.
Por ejemplo, la directiva `RouterLink` espera un objeto con una propiedad `button` que identifica qué botón del mouse, si alguno, fue presionado durante el clic.
La directiva `RouterLink` lanza un error si el objeto de evento falta.

### Hacer clic en el elemento

La siguiente alternativa de prueba llama al método `click()` propio del elemento nativo, que es perfectamente fino para *este componente*.

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test-2"/>

### Helper `click()`

Hacer clic en un botón, un anchor, o un elemento HTML arbitrario es una tarea de prueba común.

Haz eso consistente y directo encapsulando el proceso *click-triggering* en un helper como la siguiente función `click()`:

<docs-code header="testing/index.ts (click helper)" path="adev/src/content/examples/testing/src/testing/index.ts" visibleRegion="click-event"/>

El primer parámetro es el *elemento-a-hacer-clic*.
Si quieres, pasa un objeto de evento personalizado como segundo parámetro.
El predeterminado es un [objeto de evento de mouse de botón izquierdo](https://developer.mozilla.org/docs/Web/API/MouseEvent/button) parcial aceptado por muchos handlers incluyendo la directiva `RouterLink`.

IMPORTANTE: La función helper `click()` **no** es una de las utilidades de testing de Angular.
Es una función definida en el *código de muestra de esta guía*.
Todas las pruebas de muestra la usan.
Si te gusta, agrégala a tu propia colección de helpers.

Aquí está la prueba anterior, reescrita usando el helper click.

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test with click helper)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test-3"/>

## Componente dentro de un test host

Las pruebas anteriores jugaron el rol del `DashboardComponent` host ellas mismas.
¿Pero funciona correctamente el `DashboardHeroComponent` cuando está correctamente vinculado a datos a un componente host?

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test host)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host"/>

El test host establece la propiedad input `hero` del componente con su héroe de prueba.
Vincula el evento `selected` del componente con su handler `onSelected`, que registra el héroe emitido en su propiedad `selectedHero`.

Más tarde, las pruebas podrán verificar `selectedHero` para verificar que el evento `DashboardHeroComponent.selected` emitió el héroe esperado.

La configuración para las pruebas `test-host` es similar a la configuración para las pruebas standalone:

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test host setup)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host-setup"/>

Esta configuración de módulo de testing muestra dos diferencias importantes:

* *Crea* el `TestHostComponent` en lugar del `DashboardHeroComponent`
* El `TestHostComponent` establece el `DashboardHeroComponent.hero` con un binding

El `createComponent` retorna un `fixture` que contiene una instancia de `TestHostComponent` en lugar de una instancia de `DashboardHeroComponent`.

Crear el `TestHostComponent` tiene el efecto secundario de crear un `DashboardHeroComponent` porque este último aparece dentro de la plantilla del primero.
La consulta para el elemento héroe $`heroEl`$ aún lo encuentra en el DOM de prueba, aunque a mayor profundidad en el árbol de elementos que antes.

Las pruebas mismas son casi idénticas a la versión standalone:

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test-host)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host-tests"/>

Solo la prueba de evento selected difiere.
Confirma que el héroe `DashboardHeroComponent` seleccionado realmente encuentra su camino hacia arriba a través del event binding al componente host.

## Componente de enrutamiento

Un *componente de enrutamiento* es un componente que le dice al `Router` que navegue a otro componente.
El `DashboardComponent` es un *componente de enrutamiento* porque el usuario puede navegar al `HeroDetailComponent` haciendo clic en uno de los *botones de héroe* en el dashboard.

Angular proporciona helpers de prueba para reducir boilerplate y probar más efectivamente código que depende de `HttpClient`. La función `provideRouter` puede usarse directamente en el módulo de prueba también.

<docs-code header="app/dashboard/dashboard.component.spec.ts" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.spec.ts" visibleRegion="router-harness"/>

La siguiente prueba hace clic en el héroe mostrado y confirma que navegamos a la URL esperada.

<docs-code header="app/dashboard/dashboard.component.spec.ts (navigate test)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.spec.ts" visibleRegion="navigate-test"/>

## Componentes enrutados

Un *componente enrutado* es el destino de una navegación `Router`.
Puede ser más difícil de probar, especialmente cuando la ruta al componente *incluye parámetros*.
El `HeroDetailComponent` es un *componente enrutado* que es el destino de tal ruta.

Cuando un usuario hace clic en un héroe de *Dashboard*, el `DashboardComponent` le dice al `Router` que navegue a `heroes/:id`.
El `:id` es un parámetro de ruta cuyo valor es el `id` del héroe a editar.

El `Router` coincide esa URL con una ruta al `HeroDetailComponent`.
Crea un objeto `ActivatedRoute` con la información de enrutamiento y lo inyecta en una nueva instancia del `HeroDetailComponent`.

Aquí están los servicios inyectados en `HeroDetailComponent`:

<docs-code header="app/hero/hero-detail.component.ts (inject)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="inject"/>

El componente `HeroDetail` necesita el parámetro `id` para poder obtener el héroe correspondiente usando el `HeroDetailService`.
El componente tiene que obtener el `id` de la propiedad `ActivatedRoute.paramMap` que es un `Observable`.

No puede simplemente referenciar la propiedad `id` del `ActivatedRoute.paramMap`.
El componente tiene que *suscribirse* al observable `ActivatedRoute.paramMap` y estar preparado para que el `id` cambie durante su vida útil.

<docs-code header="app/hero/hero-detail.component.ts (constructor)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="ctor"/>

Las pruebas pueden explorar cómo el `HeroDetailComponent` responde a diferentes valores de parámetro `id` navegando a diferentes rutas.

## Pruebas de componentes anidados

Las plantillas de componentes a menudo tienen componentes anidados, cuyas plantillas podrían contener más componentes.

El árbol de componentes puede ser muy profundo y a veces los componentes anidados no juegan ningún rol en probar el componente en la parte superior del árbol.

El `AppComponent`, por ejemplo, muestra una barra de navegación con anchors y sus directivas `RouterLink`.

<docs-code header="app/app.component.html" path="adev/src/content/examples/testing/src/app/app.component.html"/>

Para validar los enlaces pero no la navegación, no necesitas el `Router` para navegar y no necesitas el `<router-outlet>` para marcar dónde el `Router` inserta *componentes enrutados*.

El `BannerComponent` y `WelcomeComponent` $indicados por `<app-banner>` y `<app-welcome>`$ también son irrelevantes.

Sin embargo, cualquier prueba que cree el `AppComponent` en el DOM también crea instancias de estos tres componentes y, si dejas que eso suceda, tendrás que configurar el `TestBed` para crearlos.

Si descuidas declararlos, el compilador de Angular no reconocerá las etiquetas `<app-banner>`, `<app-welcome>` y `<router-outlet>` en la plantilla `AppComponent` y lanzará un error.

Si declaras los componentes reales, también tendrás que declarar *sus* componentes anidados y proporcionar *todos* los servicios inyectados en *cualquier* componente en el árbol.

Esta sección describe dos técnicas para minimizar la configuración.
Úsalas, solas o en combinación, para mantener el foco en probar el componente primario.

### Hacer stub de componentes innecesarios

En la primera técnica, creas y declaras versiones stub de los componentes y directiva que juegan poco o ningún rol en las pruebas.

<docs-code header="app/app.component.spec.ts (stub declaration)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="component-stubs"/>

Los selectores stub coinciden con los selectores para los componentes reales correspondientes.
Pero sus plantillas y clases están vacías.

Luego declár alos sobrescribiendo los `imports` de tu componente usando `TestBed.overrideComponent`.

<docs-code header="app/app.component.spec.ts (TestBed stubs)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="testbed-stubs"/>

ÚTIL: La clave `set` en este ejemplo reemplaza todos los imports existentes en tu componente, asegúrate de importar todas las dependencias, no solo los stubs. Alternativamente puedes usar las claves `remove`/`add` para remover y agregar imports selectivamente.

### `NO_ERRORS_SCHEMA`

En el segundo enfoque, agrega `NO_ERRORS_SCHEMA` a los overrides de metadata de tu componente.

<docs-code header="app/app.component.spec.ts (NO_ERRORS_SCHEMA)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="no-errors-schema"/>

El `NO_ERRORS_SCHEMA` le dice al compilador de Angular que ignore elementos y atributos no reconocidos.

El compilador reconoce el elemento `<app-root>` y el atributo `routerLink` porque declaraste un `AppComponent` y `RouterLink` correspondientes en la configuración del `TestBed`.

Pero el compilador no lanzará un error cuando encuentre `<app-banner>`, `<app-welcome>` o `<router-outlet>`.
Simplemente los renderiza como etiquetas vacías y el navegador los ignora.

Ya no necesitas los componentes stub.

### Usar ambas técnicas juntas

Estas son técnicas para *Shallow Component Testing*, llamadas así porque reducen la superficie visual del componente solo a aquellos elementos en la plantilla del componente que importan para las pruebas.

El enfoque `NO_ERRORS_SCHEMA` es el más fácil de los dos pero no lo uses en exceso.

El `NO_ERRORS_SCHEMA` también evita que el compilador te diga sobre los componentes y atributos faltantes que omitiste inadvertidamente o escribiste mal.
Podrías desperdiciar horas persiguiendo bugs fantasma que el compilador habría capturado en un instante.

El enfoque de *componente stub* tiene otra ventaja.
Aunque los stubs en *este* ejemplo están vacíos, podrías darles plantillas y clases reducidas si tus pruebas necesitan interactuar con ellos de alguna manera.

En la práctica combinarás las dos técnicas en la misma configuración, como se ve en este ejemplo.

<docs-code header="app/app.component.spec.ts (mixed setup)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="mixed-setup"/>

El compilador de Angular crea el `BannerStubComponent` para el elemento `<app-banner>` y aplica el `RouterLink` a los anchors con el atributo `routerLink`, pero ignora las etiquetas `<app-welcome>` y `<router-outlet>`.

### `By.directive` y directivas inyectadas

Un poco más de configuración desencadena el binding de datos inicial y obtiene referencias a los enlaces de navegación:

<docs-code header="app/app.component.spec.ts (test setup)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="test-setup"/>

Tres puntos de interés especial:

* Localizar los elementos anchor con una directiva adjunta usando `By.directive`
* La consulta retorna wrappers `DebugElement` alrededor de los elementos coincidentes
* Cada `DebugElement` expone un inyector de dependencias con la instancia específica de la directiva adjunta a ese elemento

Los enlaces del `AppComponent` a validar son los siguientes:

<docs-code header="app/app.component.html (navigation links)" path="adev/src/content/examples/testing/src/app/app.component.html" visibleRegion="links"/>

Aquí hay algunas pruebas que confirman que esos enlaces están conectados a las directivas `routerLink` como se espera:

<docs-code header="app/app.component.spec.ts (selected tests)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="tests"/>

## Usar un objeto `page`

El `HeroDetailComponent` es una vista simple con un título, dos campos de héroe y dos botones.

Pero hay bastante complejidad de plantilla incluso en este formulario simple.

<docs-code
  path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.html" header="app/hero/hero-detail.component.html"/>

Las pruebas que ejercitan el componente necesitan…

* Esperar hasta que un héroe llegue antes de que los elementos aparezcan en el DOM
* Una referencia al texto del título
* Una referencia al cuadro de entrada de nombre para inspeccionarlo y establecerlo
* Referencias a los dos botones para poder hacer clic en ellos

Incluso un formulario pequeño como este puede producir un lío de configuración condicional tortuosa y selección de elementos CSS.

Domestica la complejidad con una clase `Page` que maneja el acceso a las propiedades del componente y encapsula la lógica que las establece.

Aquí hay tal clase `Page` para el `hero-detail.component.spec.ts`

<docs-code header="app/hero/hero-detail.component.spec.ts (Page)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="page"/>

Ahora los hooks importantes para manipulación e inspección de componentes están organizados ordenadamente y son accesibles desde una instancia de `Page`.

Un método `createComponent` crea un objeto `page` y llena los espacios en blanco una vez que el `hero` llega.

<docs-code header="app/hero/hero-detail.component.spec.ts (createComponent)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="create-component"/>

Aquí hay algunas pruebas más de `HeroDetailComponent` para reforzar el punto.

<docs-code header="app/hero/hero-detail.component.spec.ts (selected tests)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="selected-tests"/>

## Override component providers

El `HeroDetailComponent` proporciona su propio `HeroDetailService`.

<docs-code header="app/hero/hero-detail.component.ts (prototype)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="prototype"/>

No es posible hacer stub del `HeroDetailService` del componente en los `providers` del `TestBed.configureTestingModule`.
Esos son providers para el *módulo de testing*, no el componente.
Preparan el inyector de dependencias en el *nivel del fixture*.

Angular crea el componente con su *propio* inyector, que es un *hijo* del inyector del fixture.
Registra los providers del componente $el `HeroDetailService` en este caso$ con el inyector hijo.

Una prueba no puede llegar a servicios del inyector hijo desde el inyector del fixture.
Y `TestBed.configureTestingModule` tampoco puede configurarlos.

¡Angular ha creado nuevas instancias del `HeroDetailService` real todo el tiempo!

ÚTIL: Estas pruebas podrían fallar o agotar el tiempo de espera si el `HeroDetailService` hiciera sus propias llamadas XHR a un servidor remoto.
Podría no haber un servidor remoto al cual llamar.

Afortunadamente, el `HeroDetailService` delega responsabilidad para acceso a datos remotos a un `HeroService` inyectado.

<docs-code header="app/hero/hero-detail.service.ts (prototype)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.service.ts" visibleRegion="prototype"/>

La [configuración de prueba anterior](#import-a-feature-module) reemplaza el `HeroService` real con un `TestHeroService` que intercepta solicitudes de servidor y falsifica sus respuestas.

¿Qué pasa si no tienes tanta suerte?
¿Qué pasa si falsificar el `HeroService` es difícil?
¿Qué pasa si `HeroDetailService` hace sus propias solicitudes de servidor?

El método `TestBed.overrideComponent` puede reemplazar los `providers` del componente con *test doubles* fáciles de manejar como se ve en la siguiente variación de configuración:

<docs-code header="app/hero/hero-detail.component.spec.ts (Override setup)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="setup-override"/>

Nota que `TestBed.configureTestingModule` ya no proporciona un `HeroService` falso porque [no es necesario](#spy-stub).

### El método `overrideComponent`

Enfócate en el método `overrideComponent`.

<docs-code header="app/hero/hero-detail.component.spec.ts (overrideComponent)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="override-component-method"/>

Toma dos argumentos: el tipo de componente a sobrescribir $`HeroDetailComponent`$ y un objeto de metadata de override.
El [objeto de metadata de override](guide/testing/utility-apis#metadata-override-object) es un genérico definido como sigue:

<docs-code language="javascript">

type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```
Un objeto de metadata override puede agregar-y-remover elementos en propiedades de metadata o restablecer completamente esas propiedades.
Este ejemplo restablece los metadata `providers` del componente.

El parámetro de tipo, `T`, es el tipo de metadata que pasarías al decorador `@Component`:

```javascript
selector?: string;
template?: string;
templateUrl?: string;
providers?: any[];
…
```
### Proporcionar un *spy stub* (`HeroDetailServiceSpy`)

Este ejemplo reemplaza completamente el array `providers` del componente con un nuevo array que contiene un `HeroDetailServiceSpy`.

El `HeroDetailServiceSpy` es una versión stubbed del `HeroDetailService` real que falsifica todas las características necesarias de ese servicio.
No inyecta ni delega al `HeroService` de nivel inferior, por lo que no hay necesidad de proporcionar un test double para eso.

Las pruebas relacionadas con `HeroDetailComponent` afirmarán que los métodos del `HeroDetailService` fueron llamados espiando en los métodos del servicio.
En consecuencia, el stub implementa sus métodos como spies:

<docs-code header="app/hero/hero-detail.component.spec.ts (HeroDetailServiceSpy)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="hds-spy"/>

### Las pruebas override

Ahora las pruebas pueden controlar el héroe del componente directamente manipulando el `testHero` del spy-stub y confirmar que los métodos del servicio fueron llamados.

<docs-code header="app/hero/hero-detail.component.spec.ts (override tests)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="override-tests"/>

### Más overrides

El método `TestBed.overrideComponent` puede llamarse múltiples veces para los mismos o diferentes componentes.
El `TestBed` ofrece métodos similares `overrideDirective`, `overrideModule` y `overridePipe` para profundizar y reemplazar partes de estas otras clases.

Explora las opciones y combinaciones por tu cuenta.
# Depurar pruebas

Si tus pruebas no están funcionando como esperas, puedes inspeccionarlas y depurarlas en el navegador.

Depura specs en el navegador de la misma manera que depuras una aplicación.

1. Revela la ventana del navegador de Karma.
    Consulta [Configurar testing](guide/testing#set-up-testing) si necesitas ayuda con este paso.

1. Haz clic en el botón **DEBUG** para abrir una nueva pestaña del navegador y re-ejecutar las pruebas.
1. Abre las **Herramientas de Desarrollador** del navegador. En Windows, presiona `Ctrl-Shift-I`. En macOS, presiona `Command-Option-I`.
1. Selecciona la sección **Sources**.
1. Presiona `Control/Command-P`, y luego comienza a escribir el nombre de tu archivo de prueba para abrirlo.
1. Establece un breakpoint en la prueba.
1. Actualiza el navegador, y nota cómo se detiene en el breakpoint.

<img alt="Depuración de Karma" src="assets/images/guide/testing/karma-1st-spec-debug.png">
# APIs utilitarias de pruebas

Esta página describe las características de pruebas de Angular más útiles.

Las utilidades de pruebas de Angular incluyen el `TestBed`, el `ComponentFixture` y un puñado de funciones que controlan el entorno de prueba.
Las clases [`TestBed`](#testbed-api-summary) y [`ComponentFixture`](#component-fixture-api-summary) se cubren por separado.

Aquí hay un resumen de las funciones independientes, en orden de utilidad probable:

| Función                     | Detalles |
|:---                          |:---     |
| `waitForAsync`               | Ejecuta el cuerpo de una prueba $`it`$ o función de configuración $`beforeEach`$ dentro de una *zona de prueba async* especial. Ver [waitForAsync](guide/testing/components-scenarios#waitForAsync).                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `fakeAsync`                  | Ejecuta el cuerpo de una prueba $`it`$ dentro de una *zona de prueba fakeAsync* especial, habilitando un estilo de codificación de flujo de control lineal. Ver [fakeAsync](guide/testing/components-scenarios#fake-async).                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `tick`                       | Simula el paso del tiempo y la finalización de actividades asíncronas pendientes vaciando tanto las colas de *timer* como de *micro-task* dentro de la *zona de prueba fakeAsync*.  El lector curioso y dedicado podría disfrutar esta larga publicación de blog, ["*Tasks, microtasks, queues and schedules*"](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules).  Acepta un argumento opcional que mueve el reloj virtual hacia adelante por el número especificado de milisegundos, limpiando actividades asíncronas programadas dentro de ese marco de tiempo. Ver [tick](guide/testing/components-scenarios#tick). |
| `inject`                     | Inyecta uno o más servicios del inyector `TestBed` actual en una función de prueba. No puede inyectar un servicio proporcionado por el componente mismo. Ver discusión de [debugElement.injector](guide/testing/components-scenarios#get-injected-services).                                                                                                                                                                                                                                                                                                                                                                          |
| `discardPeriodicTasks`       | Cuando una prueba `fakeAsync()` termina con *tasks* de evento de timer pendientes $callbacks `setTimeOut` y `setInterval` en cola$, la prueba falla con un mensaje de error claro. <br /> En general, una prueba debería terminar sin tareas en cola. Cuando se esperan tareas de timer pendientes, llama a `discardPeriodicTasks` para vaciar la cola de *task* y evitar el error.                                                                                                                                                                                                                                                                                          |
| `flushMicrotasks`            | Cuando una prueba `fakeAsync()` termina con *micro-tasks* pendientes como promesas no resueltas, la prueba falla con un mensaje de error claro. <br /> En general, una prueba debería esperar a que las micro-tasks finalicen. Cuando se esperan microtasks pendientes, llama a `flushMicrotasks` para vaciar la cola de *micro-task* y evitar el error.                                                                                                                                                                                                                                                                                                 |
| `ComponentFixtureAutoDetect` | Un token de provider para un servicio que activa la [detección automática de cambios](guide/testing/components-scenarios#automatic-change-detection).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `getTestBed`                 | Obtiene la instancia actual del `TestBed`. Usualmente innecesario porque los métodos de clase estáticos de la clase `TestBed` son típicamente suficientes. La instancia `TestBed` expone algunos miembros raramente usados que no están disponibles como métodos estáticos.                                                                                                                                                                                                                                                                                                                                                                                  |

## Resumen de la clase `TestBed`

La clase `TestBed` es una de las utilidades principales de pruebas de Angular.
Su API es bastante grande y puede ser abrumadora hasta que la hayas explorado, un poco a la vez.
Lee la parte temprana de esta guía primero para obtener lo básico antes de intentar absorber la API completa.

La definición de módulo pasada a `configureTestingModule` es un subconjunto de las propiedades de metadata `@NgModule`.

```javascript
type TestModuleMetadata = {
  providers?: any[];
  declarations?: any[];
  imports?: any[];
  schemas?: Array<SchemaMetadata | any[]>;
};
```
Cada método override toma un `MetadataOverride<T>` donde `T` es el tipo de metadata apropiado para el método, es decir, el parámetro de un `@NgModule`, `@Component`, `@Directive` o `@Pipe`.

```javascript
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```
La API del `TestBed` consiste en métodos de clase estáticos que actualizan o referencian una instancia *global* del `TestBed`.

Internamente, todos los métodos estáticos cubren métodos de la instancia `TestBed` de runtime actual, que también es retornada por la función `getTestBed()`.

Llama a los métodos `TestBed` *dentro* de un `beforeEach()` para asegurar un comienzo fresco antes de cada prueba individual.

Aquí están los métodos estáticos más importantes, en orden de utilidad probable.

| Métodos                                                        | Detalles |
|:---                                                            |:---     |
| `configureTestingModule`                                       | Los shims de testing $`karma-test-shim`, `browser-test-shim`$ establecen el [entorno de prueba inicial](guide/testing) y un módulo de testing predeterminado. El módulo de testing predeterminado está configurado con declarativas básicas y algunos sustitutos de servicio de Angular que cada probador necesita. <br /> Llama a `configureTestingModule` para refinar la configuración del módulo de testing para un conjunto particular de pruebas agregando y eliminando imports, declarations $de componentes, directivas y pipes$, y providers.                                                                                                                                              |
| `compileComponents`                                            | Compila el módulo de testing de forma asíncrona después de que hayas terminado de configurarlo. **Debes** llamar a este método si *alguno* de los componentes del módulo de testing tiene un `templateUrl` o `styleUrls` porque obtener archivos de plantilla y estilo del componente es necesariamente asíncrono. Ver [compileComponents](guide/testing/components-scenarios#calling-compilecomponents). <br /> Después de llamar a `compileComponents`, la configuración del `TestBed` se congela durante la duración del spec actual.                                                                                                                                                                 |
| `createComponent<T>`                                     | Crea una instancia de un componente de tipo `T` basado en la configuración actual del `TestBed`. Después de llamar a `createComponent`, la configuración del `TestBed` se congela durante la duración del spec actual.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `overrideModule`                                               | Reemplaza metadata para el `NgModule` dado. Recuerda que los módulos pueden importar otros módulos. El método `overrideModule` puede llegar profundamente al módulo de testing actual para modificar uno de estos módulos internos.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `overrideComponent`                                            | Reemplaza metadata para la clase de componente dada, que podría estar anidada profundamente dentro de un módulo interno.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `overrideDirective`                                            | Reemplaza metadata para la clase de directiva dada, que podría estar anidada profundamente dentro de un módulo interno.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `overridePipe`                                                 | Reemplaza metadata para la clase de pipe dada, que podría estar anidada profundamente dentro de un módulo interno.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|
| `inject`                           | Recupera un servicio del inyector `TestBed` actual. La función `inject` es a menudo adecuada para este propósito. Pero `inject` lanza un error si no puede proporcionar el servicio. <br /> ¿Qué pasa si el servicio es opcional? <br /> El método `TestBed.inject()` toma un segundo parámetro opcional, el objeto a retornar si Angular no puede encontrar el provider $`null` en este ejemplo$: <docs-code header="app/demo/demo.testbed.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="testbed-get-w-null"/> Después de llamar a `TestBed.inject`, la configuración del `TestBed` se congela durante la duración del spec actual. |
|
| `initTestEnvironment` | Inicializa el entorno de testing para toda la ejecución de pruebas. <br /> Los shims de testing $`karma-test-shim`, `browser-test-shim`$ lo llaman por ti así que raramente hay una razón para que lo llames tú mismo. <br /> Llama a este método *exactamente una vez*. Para cambiar este predeterminado en medio de una ejecución de pruebas, llama primero a `resetTestEnvironment`. <br /> Especifica la factory del compilador de Angular, un `PlatformRef`, y un módulo de testing de Angular predeterminado. Alternativas para plataformas no-navegador están disponibles en la forma general `@angular/platform-<platform_name>/testing/<platform_name>`.                                                                  |
| `resetTestEnvironment`                                         | Reinicia el entorno de prueba inicial, incluyendo el módulo de testing predeterminado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

Algunos de los métodos de instancia del `TestBed` no están cubiertos por métodos de *clase* `TestBed` estáticos.
Estos rara vez se necesitan.

## El `ComponentFixture`

El `TestBed.createComponent<T>` crea una instancia del componente `T` y retorna un `ComponentFixture` fuertemente tipado para ese componente.

Las propiedades y métodos del `ComponentFixture` proporcionan acceso al componente, su representación DOM y aspectos de su entorno Angular.

### Propiedades de `ComponentFixture`

Aquí están las propiedades más importantes para los probadores, en orden de utilidad probable.

| Propiedades          | Detalles |
|:---                 |:---     |
| `componentInstance` | La instancia de la clase del componente creada por `TestBed.createComponent`.                                                                                                                                                                                                                          |
| `debugElement`      | El `DebugElement` asociado con el elemento raíz del componente. <br /> El `debugElement` proporciona información sobre el componente y su elemento DOM durante la prueba y depuración. Es una propiedad crítica para los probadores. Los miembros más interesantes se cubren [abajo](#debug-element-details). |
| `nativeElement`     | El elemento DOM nativo en la raíz del componente.                                                                                                                                                                                                                                                               |
| `changeDetectorRef` | El `ChangeDetectorRef` para el componente. <br /> El `ChangeDetectorRef` es más valioso cuando se prueba un componente que tiene el método `ChangeDetectionStrategy.OnPush` o la detección de cambios del componente está bajo tu control programático.                                                   |

### Métodos de `ComponentFixture`

Los métodos *fixture* hacen que Angular realice ciertas tareas en el árbol de componentes.
Llama a estos métodos para desencadenar comportamiento de Angular en respuesta a una acción de usuario simulada.

Aquí están los métodos más útiles para los probadores.

| Métodos             | Detalles |
|:---                 |:---     |
| `detectChanges`     | Desencadena un ciclo de detección de cambios para el componente. <br /> Llámalo para inicializar el componente $llama a `ngOnInit`$ y después de que tu código de prueba cambie los valores de propiedad vinculados a datos del componente. Angular no puede ver que has cambiado `personComponent.name` y no actualizará el binding `name` hasta que llames a `detectChanges`. <br /> Ejecuta `checkNoChanges` después para confirmar que no hay actualizaciones circulares a menos que se llame como `detectChanges(false)`;                                                                                    |
| `autoDetectChanges` | Establece esto a `true` cuando quieras que el fixture detecte cambios automáticamente. <br /> Cuando autodetect es `true`, el test fixture llama a `detectChanges` inmediatamente después de crear el componente. Luego escucha eventos de zona pertinentes y llama a `detectChanges` en consecuencia. Cuando tu código de prueba modifica valores de propiedad del componente directamente, probablemente aún tengas que llamar a `fixture.detectChanges` para desencadenar actualizaciones de binding de datos. <br /> El predeterminado es `false`. Los probadores que prefieren control fino sobre el comportamiento de prueba tienden a mantenerlo en `false`. |
| `checkNoChanges`    | Ejecuta una ejecución de detección de cambios para asegurarse de que no hay cambios pendientes. Lanza excepciones si los hay.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `isStable`          | Si el fixture es actualmente *estable*, retorna `true`. Si hay tareas async que no se han completado, retorna `false`.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `whenStable`        | Retorna una promesa que se resuelve cuando el fixture es estable. <br /> Para reanudar las pruebas después de la finalización de actividad asíncrona o detección de cambios asíncrona, engancha esa promesa. Ver [whenStable](guide/testing/components-scenarios#whenstable).                                                                                                                                                                                                                                                                                                  |
| `destroy`           | Desencadena la destrucción del componente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### `DebugElement`

El `DebugElement` proporciona información crucial sobre la representación DOM del componente.

Desde el `DebugElement` del componente raíz de prueba retornado por `fixture.debugElement`, puedes caminar $y consultar$ todo el subárbol de elementos y componentes del fixture.

Aquí están los miembros más útiles de `DebugElement` para los probadores, en orden aproximado de utilidad:

| Miembros               | Detalles |
|:---                   |:---     |
| `nativeElement`       | El elemento DOM correspondiente en el navegador                                                                                                                                                                                                                                                                        |
| `query`               | Llamar a `query(predicate: Predicate<DebugElement>)` retorna el primer `DebugElement` que coincide con el [predicate](#query-predicate) a cualquier profundidad en el subárbol.                                                                                                                                                                                                                                        |
| `queryAll`            | Llamar a `queryAll(predicate: Predicate<DebugElement>)` retorna todos los `DebugElements` que coinciden con el [predicate](#query-predicate) a cualquier profundidad en el subárbol.                                                                                                                                                                                                                              |
| `injector`            | El inyector de dependencias del host. Por ejemplo, el inyector de instancia del componente del elemento raíz.                                                                                                                                                                                                                                                                                                              |
| `componentInstance`   | La propia instancia del componente del elemento, si tiene una.                                                                                                                                                                                                                                                                                                                                                    |
| `context`             | Un objeto que proporciona contexto padre para este elemento. A menudo una instancia de componente ancestro que gobierna este elemento. <br /> Cuando un elemento se repite dentro de un bloque `@for`, el contexto es un `RepeaterContext` cuya propiedad `$implicit` es el valor de la instancia de la fila. Por ejemplo, el `hero` en `@for(hero of heroes; ...)`.                                                                   |
| `children`            | Los hijos `DebugElement` inmediatos. Camina el árbol descendiendo a través de `children`.  `DebugElement` también tiene `childNodes`, una lista de objetos `DebugNode`. `DebugElement` deriva de objetos `DebugNode` y a menudo hay más nodos que elementos. Los probadores usualmente pueden ignorar nodos planos.                                                                  |
| `parent`              | El padre `DebugElement`. Null si este es el elemento raíz.                                                                                                                                                                                                                                                                                                                                            |
| `name`                | El nombre de tag del elemento, si es un elemento.                                                                                                                                                                                                                                                                                                                                                              |
| `triggerEventHandler` | Desencadena el evento por su nombre si hay un listener correspondiente en la colección `listeners` del elemento. El segundo parámetro es el *objeto evento* esperado por el handler. Ver [triggerEventHandler](guide/testing/components-scenarios#trigger-event-handler). <br /> Si el evento carece de un listener o hay algún otro problema, considera llamar a `nativeElement.dispatchEvent(eventObject)`. |
| `listeners`           | Los callbacks adjuntos a las propiedades `@Output` del componente y/o las propiedades de evento del elemento.                                                                                                                                                                                                                                                                                                   |
| `providerTokens`      | Los tokens de lookup del inyector de este componente. Incluye el componente mismo más los tokens que el componente lista en su metadata `providers`.                                                                                                                                                                                                                                                            |
| `source`              | Dónde encontrar este elemento en la plantilla del componente fuente.                                                                                                                                                                                                                                                                                                                                            |
| `references`          | Diccionario de objetos asociados con variables locales de plantilla $por ejemplo, `#foo`$, con clave del nombre de la variable local.                                                                                                                                                                                                                                                                                        |

Los métodos `DebugElement.query(predicate)` y `DebugElement.queryAll(predicate)` toman un predicate que filtra el subárbol del elemento fuente para coincidencias `DebugElement`.

El predicate es cualquier método que toma un `DebugElement` y retorna un valor *truthy*.
El siguiente ejemplo encuentra todos los `DebugElements` con una referencia a una variable local de plantilla llamada "content":

<docs-code header="app/demo/demo.testbed.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="custom-predicate"/>

La clase `By` de Angular tiene tres métodos estáticos para predicates comunes:

<docs-code header="app/hero/hero-list.component.spec.ts" path="adev/src/content/examples/testing/src/app/hero/hero-list.component.spec.ts" visibleRegion="by"/>
# Visión general de component harnesses

Un <strong>component harness</strong> es una clase que permite a las pruebas interactuar con componentes de la manera en que un usuario final lo hace a través de una API soportada. Puedes crear test harnesses para cualquier componente, desde pequeños widgets reutilizables hasta páginas completas.

Los harnesses ofrecen varios beneficios:

- Hacen que las pruebas sean menos frágiles al aislarse contra detalles de implementación de un componente, como su estructura DOM
- Hacen que las pruebas se vuelvan más legibles y más fáciles de mantener
- Pueden usarse en múltiples entornos de pruebas

```typescript
// Ejemplo de prueba con un harness para un componente llamado MyButtonComponent
it('should load button with exact text', async () => {
  const button = await loader.getHarness(MyButtonComponentHarness);
  expect(await button.getText()).toBe('Confirm');
});
```
Los component harnesses son especialmente útiles para widgets de UI compartidos. Los desarrolladores a menudo escriben pruebas que dependen de detalles privados de implementación de widgets, como estructura DOM y clases CSS. Esas dependencias hacen que las pruebas sean frágiles y difíciles de mantener. Los harnesses ofrecen una alternativa— una API soportada que interactúa con el widget de la misma manera que un usuario final lo hace. Los cambios de implementación del widget ahora se vuelven menos propensos a romper las pruebas de usuario. Por ejemplo, [Angular Material](https://material.angular.dev/components/categories) proporciona un test harness para cada componente en la librería.

Los component harnesses soportan múltiples entornos de pruebas. Puedes usar la misma implementación de harness en pruebas tanto unitarias como end-to-end. Los autores de pruebas solo necesitan aprender una API y los autores de componentes no tienen que mantener implementaciones de prueba unitaria y end-to-end separadas.

Muchos desarrolladores pueden categorizarse por una de las siguientes categorías de tipo de desarrollador: autores de pruebas, autores de component harness y autores de entornos de harness. Usa la tabla a continuación para encontrar la sección más relevante en esta guía basada en estas categorías:

| Tipo de Desarrollador              | Descripción                                                                                                                                                                                                                                                                                            | Sección Relevante                                                                                             |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| Autores de pruebas                | Desarrolladores que usan component harnesses escritos por alguien más para probar su aplicación. Por ejemplo, esto podría ser un desarrollador de aplicaciones que usa un componente de menú de terceros y necesita interactuar con el menú en una prueba unitaria.                                                                       | [Usar component harnesses en pruebas](guide/testing/using-component-harnesses)                                |
| Autores de component harness   | Desarrolladores que mantienen algunos componentes Angular reutilizables y quieren crear un test harness para que sus usuarios lo usen en sus pruebas. Por ejemplo, un autor de una librería de componentes Angular de terceros o un desarrollador que mantiene un conjunto de componentes comunes para una aplicación Angular grande.             | [Crear component harnesses para tus componentes](guide/testing/creating-component-harnesses)               |
| Autores de entornos de harness | Desarrolladores que quieren agregar soporte para usar component harnesses en entornos de pruebas adicionales. Para información sobre entornos de pruebas soportados de forma inmediata, consulta los [entornos de test harness y loaders](guide/testing/using-component-harnesses#test-harness-environments-and-loaders). | [Agregar soporte para entornos de pruebas adicionales](guide/testing/component-harnesses-testing-environments) |

Para la referencia completa de la API, consulta la [página de referencia de la API de component harness del CDK de Angular](/api#angular_cdk_testing).
# Usar component harnesses en pruebas

## Antes de comenzar

CONSEJO: Esta guía asume que ya leíste la [guía de visión general de component harnesses](guide/testing/component-harnesses-overview). Lee eso primero si eres nuevo en el uso de component harnesses.

### Instalación del CDK

El [Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) es un conjunto de primitivas de comportamiento para construir componentes. Para usar los component harnesses, primero instala `@angular/cdk` desde npm. Puedes hacer esto desde tu terminal usando Angular CLI:

```shell
ng add @angular/cdk
```
## Entornos de test harness y loaders

Puedes usar component test harnesses en diferentes entornos de prueba. El CDK de Angular soporta dos entornos integrados:

- Pruebas unitarias con el `TestBed` de Angular
- Pruebas end-to-end con [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver)

Cada entorno proporciona un <strong>harness loader</strong>. El loader crea las instancias de harness que usas a lo largo de tus pruebas. Consulta abajo para una guía más específica sobre entornos de testing soportados.

Los entornos de testing adicionales requieren bindings personalizados. Consulta la [guía de agregar soporte de harness para entornos de testing adicionales](guide/testing/component-harnesses-testing-environments) para más información.

### Usar el loader de `TestbedHarnessEnvironment` para pruebas unitarias

Para pruebas unitarias puedes crear un harness loader desde [TestbedHarnessEnvironment](/api/cdk/testing/TestbedHarnessEnvironment). Este entorno usa un [component fixture](api/core/testing/ComponentFixture) creado por el `TestBed` de Angular.

Para crear un harness loader enraizado en el elemento raíz del fixture, usa el método `loader()`:

```typescript
const fixture = TestBed.createComponent(MyComponent);

// Crear un harness loader desde el fixture
const loader = TestbedHarnessEnvironment.loader(fixture);
...

// Usar el loader para obtener instancias de harness
const myComponentHarness = await loader.getHarness(MyComponent);
```
Para crear un harness loader para harnesses para elementos que caen fuera del fixture, usa el método `documentRootLoader()`. Por ejemplo, código que muestra un elemento flotante o pop-up a menudo adjunta elementos DOM directamente al body del documento, como el servicio `Overlay` en el CDK de Angular.

También puedes crear un harness loader directamente con `harnessForFixture()` para un harness en el elemento raíz de ese fixture directamente.

### Usar el loader de `SeleniumWebDriverHarnessEnvironment` para pruebas end-to-end

Para pruebas end-to-end basadas en WebDriver puedes crear un harness loader con `SeleniumWebDriverHarnessEnvironment`.

Usa el método `loader()` para obtener la instancia de harness loader para el documento HTML actual, enraizado en el elemento raíz del documento. Este entorno usa un cliente WebDriver.

```typescript
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```
## Usar un harness loader

Las instancias de harness loader corresponden a un elemento DOM específico y se usan para crear instancias de component harness para elementos bajo ese elemento específico.

Para obtener `ComponentHarness` para la primera instancia del elemento, usa el método `getHarness()`. Para obtener todas las instancias de `ComponentHarness`, usa el método `getAllHarnesses()`.

```typescript
// Obtener harness para la primera instancia del elemento
const myComponentHarness = await loader.getHarness(MyComponent);

// Obtener harnesses para todas las instancias del elemento
const myComponentHarnesses = await loader.getHarnesses(MyComponent);
```
Además de `getHarness` y `getAllHarnesses`, `HarnessLoader` tiene varios otros métodos útiles para consultar harnesses:

- `getHarnessAtIndex(...)`: Obtiene el harness para un componente que coincide con el criterio dado en un índice específico.
- `countHarnesses(...)`: Cuenta el número de instancias de componente que coinciden con el criterio dado.
- `hasHarness(...)`: Verifica si al menos una instancia de componente coincide con el criterio dado.

Como ejemplo, considera un componente dialog-button reutilizable que abre un diálogo al hacer clic. Contiene los siguientes componentes, cada uno con un harness correspondiente:

- `MyDialogButton` (compone el `MyButton` y `MyDialog` con una API conveniente)
- `MyButton` (un componente button estándar)
- `MyDialog` (un diálogo adjuntado a `document.body` por `MyDialogButton` al hacer clic)

La siguiente prueba carga harnesses para cada uno de estos componentes:

```typescript
let fixture: ComponentFixture<MyDialogButton>;
let loader: HarnessLoader;
let rootLoader: HarnessLoader;

beforeEach(() => {
  fixture = TestBed.createComponent(MyDialogButton);
  loader = TestbedHarnessEnvironment.loader(fixture);
  rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
});

it('loads harnesses', async () => {
  // Cargar un harness para el componente bootstrap con `harnessForFixture`
  dialogButtonHarness =
    await TestbedHarnessEnvironment.harnessForFixture(fixture, MyDialogButtonHarness);

// El elemento button está dentro del elemento raíz del fixture, así que usamos `loader`.
  const buttonHarness = await loader.getHarness(MyButtonHarness);

// Hacer clic en el botón para abrir el diálogo
  await buttonHarness.click();

// El diálogo se adjunta a `document.body`, fuera del elemento raíz del fixture,
  // así que usamos `rootLoader` en este caso.
  const dialogHarness = await rootLoader.getHarness(MyDialogHarness);

// ... hacer algunas afirmaciones
});
```
### Comportamiento de harness en diferentes entornos

Los harnesses pueden no comportarse exactamente igual en todos los entornos. Algunas diferencias son inevitables entre la interacción real del usuario versus los eventos simulados generados en pruebas unitarias. El CDK de Angular hace un mejor esfuerzo para normalizar el comportamiento en la medida posible.

### Interactuar con elementos hijos

Para interactuar con elementos debajo del elemento raíz de este harness loader, usa la instancia `HarnessLoader` de un elemento hijo. Para la primera instancia del elemento hijo, usa el método `getChildLoader()`. Para todas las instancias del elemento hijo, usa el método `getAllChildLoaders()`.

```typescript
const myComponentHarness = await loader.getHarness(MyComponent);

// Obtener loader para la primera instancia del elemento hijo con selector '.child'
const childLoader = await myComponentHarness.getLoader('.child');

// Obtener loaders para todas las instancias de elementos hijos con selector '.child'
const allChildLoaders = await myComponentHarness.getAllChildLoaders('.child');
```
### Filtrar harnesses

Cuando una página contiene múltiples instancias de un componente particular, es posible que quieras filtrar basado en alguna propiedad del componente para obtener una instancia de componente particular. Puedes usar un <strong>harness predicate</strong>, una clase usada para asociar una clase `ComponentHarness` con funciones predicates que pueden usarse para filtrar instancias de componentes, para hacerlo.

Cuando le pides a un `HarnessLoader` un harness, en realidad estás proporcionando una HarnessQuery. Una consulta puede ser una de dos cosas:

- Un constructor de harness. Esto solo obtiene ese harness
- Un `HarnessPredicate`, que obtiene harnesses que están filtrados basados en una o más condiciones

`HarnessPredicate` soporta algunos filtros base (selector, ancestor) que funcionan en cualquier cosa que extienda `ComponentHarness`.

```typescript
// Ejemplo de cargar un MyButtonComponentHarness con un harness predicate
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {selector: '[disabled]'});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```
Sin embargo, es común que los harnesses implementen un método estático `with()` que acepta opciones de filtrado específicas del componente y retorna un `HarnessPredicate`.

```typescript
// Ejemplo de cargar un MyButtonComponentHarness con un selector específico
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}))
```
Para más detalles consulta la documentación específica del harness ya que las opciones de filtrado adicionales son específicas de cada implementación de harness.

## Usar APIs de test harness

Aunque cada harness define una API específica para su componente correspondiente, todos comparten una clase base común, [ComponentHarness](/api/cdk/testing/ComponentHarness). Esta clase base define una propiedad estática, `hostSelector`, que coincide la clase harness con instancias del componente en el DOM.

Más allá de eso, la API de cualquier harness dado es específica de su componente correspondiente; consulta la documentación del componente para aprender cómo usar un harness específico.

Como ejemplo, lo siguiente es una prueba para un componente que usa el [harness del componente slider de Angular Material](https://material.angular.dev/components/slider/api#MatSliderHarness):

```typescript
it('should get value of slider thumb', async () => {
  const slider = await loader.getHarness(MatSliderHarness);
  const thumb = await slider.getEndThumb();
  expect(await thumb.getValue()).toBe(50);
});
```
## Interoperabilidad con la detección de cambios de Angular

Por defecto, los test harnesses ejecutan la [detección de cambios](https://angular.dev/best-practices/runtime-performance) de Angular antes de leer el estado de un elemento DOM y después de interactuar con un elemento DOM.

Puede haber momentos en que necesites un control más fino sobre la detección de cambios en tus pruebas, como verificar el estado de un componente mientras una operación async está pendiente. En estos casos usa la función `manualChangeDetection` para deshabilitar el manejo automático de detección de cambios para un bloque de código.

```typescript
it('checks state while async action is in progress', async () => {
  const buttonHarness = loader.getHarness(MyButtonHarness);
  await manualChangeDetection(async () => {
    await buttonHarness.click();
    fixture.detectChanges();
    // Verificar expectativas mientras la operación de clic async está en progreso.
    expect(isProgressSpinnerVisible()).toBe(true);
    await fixture.whenStable();
    // Verificar expectativas después de que la operación de clic async se complete.
    expect(isProgressSpinnerVisible()).toBe(false);
  });
});
```
Casi todos los métodos de harness son asíncronos y retornan una `Promise` para soportar lo siguiente:

- Soporte para pruebas unitarias
- Soporte para pruebas end-to-end
- Aislar pruebas contra cambios en comportamiento asíncrono

El equipo de Angular recomienda usar [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) para mejorar la legibilidad de la prueba. Llamar a `await` bloquea la ejecución de tu prueba hasta que la `Promise` asociada se resuelva.

Ocasionalmente, es posible que quieras realizar múltiples acciones simultáneamente y esperar hasta que todas estén hechas en lugar de realizar cada acción secuencialmente. Por ejemplo, leer múltiples propiedades de un solo componente. En estas situaciones usa la función `parallel` para paralelizar las operaciones. La función parallel funciona de manera similar a `Promise.all`, mientras también optimiza las verificaciones de detección de cambios.

```typescript
it('reads properties in parallel', async () => {
  const checkboxHarness = loader.getHarness(MyCheckboxHarness);
  // Leer las propiedades checked e intermediate simultáneamente.
  const [checked, indeterminate] = await parallel(() => [
    checkboxHarness.isChecked(),
    checkboxHarness.isIndeterminate()
  ]);
  expect(checked).toBe(false);
  expect(indeterminate).toBe(true);
});
```

# Crear harnesses para tus componentes

## Antes de comenzar

### ¿Cuándo tiene sentido crear un test harness?

El equipo de Angular recomienda crear component test harnesses para componentes compartidos que se usan en muchos lugares y tienen algo de interactividad de usuario. Esto comúnmente aplica a librerías de widgets y componentes reutilizables similares. Los harnesses son valiosos para estos casos porque proporcionan a los consumidores de estos componentes compartidos una API bien soportada para interactuar con un componente. Las pruebas que usan harnesses pueden evitar depender de detalles de implementación poco confiables de estos componentes compartidos, como estructura DOM y event listeners específicos.

Para componentes que aparecen en solo un lugar, como una página en una aplicación, los harnesses no proporcionan tanto beneficio. En estas situaciones, las pruebas de un componente pueden razonablemente depender de los detalles de implementación de este componente, ya que las pruebas y componentes se actualizan al mismo tiempo. Sin embargo, los harnesses aún proporcionan algo de valor si usarías el harness en pruebas tanto unitarias como end-to-end.

### Instalación del CDK

```shell
ng add @angular/cdk
```
## Extender `ComponentHarness`

La clase abstracta `ComponentHarness` es la clase base para todos los component harnesses. Para crear un component harness personalizado, extiende `ComponentHarness` e implementa la propiedad estática `hostSelector`.

La propiedad `hostSelector` identifica elementos en el DOM que coinciden con esta subclase harness. En la mayoría de los casos, el `hostSelector` debería ser el mismo que el selector del `Component` o `Directive` correspondiente. Por ejemplo, considera un componente popup simple:

```typescript
@Component({
  selector: 'my-popup',
  template: `
    <button (click)="toggle()">{{triggerText()}}</button>
    @if (isOpen()) {
      <div class="my-popup-content"><ng-content></ng-content></div>
    }
  `
})
class MyPopup {
  triggerText = input('');

isOpen = signal(false);

toggle() {
    this.isOpen.update((value) => !value);
  }
}
```
En este caso, un harness mínimo para el componente se vería como lo siguiente:

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```
Aunque las subclases de `ComponentHarness` requieren solo la propiedad `hostSelector`, la mayoría de los harnesses también deberían implementar un método estático `with` para generar instancias de `HarnessPredicate`. La [sección de filtrar harnesses](guide/testing/using-component-harnesses#filtering-harnesses) cubre esto con más detalle.

## Encontrar elementos en el DOM del componente

Cada instancia de una subclase de `ComponentHarness` representa una instancia particular del componente correspondiente. Puedes acceder al elemento host del componente a través del método `host()` de la clase base `ComponentHarness`.

`ComponentHarness` también ofrece varios métodos para localizar elementos dentro del DOM del componente. Estos métodos son `locatorFor()`, `locatorForOptional()` y `locatorForAll()`. Estos métodos crean funciones que encuentran elementos, no encuentran elementos directamente. Este enfoque protege contra el almacenamiento en caché de referencias a elementos desactualizados. Por ejemplo, cuando un bloque `@if` oculta y luego muestra un elemento, el resultado es un nuevo elemento DOM; usar funciones asegura que las pruebas siempre referencien el estado actual del DOM.

Consulta la [página de referencia de la API de ComponentHarness](/api/cdk/testing/ComponentHarness) para la lista completa de detalles de los diferentes métodos `locatorFor`.

Por ejemplo, el ejemplo `MyPopupHarness` discutido arriba podría proporcionar métodos para obtener los elementos trigger y content como sigue:

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

// Obtiene el elemento trigger
  getTriggerElement = this.locatorFor('button');

// Obtiene el elemento content.
  getContentElement = this.locatorForOptional('.my-popup-content');
}
```
## Trabajar con instancias de `TestElement`

`TestElement` es una abstracción diseñada para trabajar en diferentes entornos de prueba (Pruebas unitarias, WebDriver, etc). Al usar harnesses, deberías realizar toda interacción DOM a través de esta interfaz. Otros medios de acceder a elementos DOM, como `document.querySelector()`, no funcionan en todos los entornos de prueba.

`TestElement` tiene una cantidad de métodos para interactuar con el DOM subyacente, como `blur()`, `click()`, `getAttribute()` y más. Consulta la [página de referencia de la API de TestElement](/api/cdk/testing/TestElement) para la lista completa de métodos.

No expongas instancias de `TestElement` a usuarios de harness a menos que sea un elemento que el consumidor del componente define directamente, como el elemento host del componente. Exponer instancias de `TestElement` para elementos internos lleva a los usuarios a depender de la estructura DOM interna de un componente.

En su lugar, proporciona métodos más enfocados para acciones específicas que el usuario final puede tomar o estado particular que pueden observar. Por ejemplo, `MyPopupHarness` de secciones anteriores podría proporcionar métodos como `toggle` e `isOpen`:

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

protected getTriggerElement = this.locatorFor('button');
  protected getContentElement = this.locatorForOptional('.my-popup-content');

/** Alterna el estado abierto del popup. */
  async toggle() {
    const trigger = await this.getTriggerElement();
    return trigger.click();
  }

/** Verifica si el popup está abierto. */
  async isOpen() {
    const content = await this.getContentElement();
    return !!content;
  }
}
```
## Cargar harnesses para subcomponentes

Los componentes más grandes a menudo componen subcomponentes. Puedes reflejar esta estructura en el harness de un componente también. Cada uno de los métodos `locatorFor` en `ComponentHarness` tiene una firma alternativa que puede usarse para localizar sub-harnesses en lugar de elementos.

Consulta la [página de referencia de la API de ComponentHarness](/api/cdk/testing/ComponentHarness) para la lista completa de los diferentes métodos locatorFor.

Por ejemplo, considera un menú construido usando el popup de arriba:

```typescript
@Directive({
  selector: 'my-menu-item'
})
class MyMenuItem {}

@Component({
  selector: 'my-menu',
  template: `
    <my-popup>
      <ng-content></ng-content>
    </my-popup>
  `
})
class MyMenu {
  triggerText = input('');

@ContentChildren(MyMenuItem) items: QueryList<MyMenuItem>;
}
```
El harness para `MyMenu` puede entonces aprovechar otros harnesses para `MyPopup` y `MyMenuItem`:

```typescript
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/** Obtiene los items de menú actualmente mostrados (lista vacía si el menú está cerrado). */
  getItems = this.locatorForAll(MyMenuItemHarness);

/** Alterna el estado abierto del menú. */
  async toggle() {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.toggle();
  }
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';
}
```
## Filtrar instancias de harness con `HarnessPredicate`

Cuando una página contiene múltiples instancias de un componente particular, es posible que quieras filtrar basado en alguna propiedad del componente para obtener una instancia de componente particular. Por ejemplo, es posible que quieras un botón con algún texto específico, o un menú con un ID específico. La clase `HarnessPredicate` puede capturar criterios como este para una subclase de `ComponentHarness`. Aunque el autor de la prueba puede construir instancias de `HarnessPredicate` manualmente, es más fácil cuando la subclase de `ComponentHarness` proporciona un método helper para construir predicates para filtros comunes.

Deberías crear un método estático `with()` en cada subclase de `ComponentHarness` que retorne un `HarnessPredicate` para esa clase. Esto permite a los autores de pruebas escribir código fácilmente comprensible, p. ej., `loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`. Además de las opciones estándar de selector y ancestor, el método `with` debería agregar cualquier otra opción que tenga sentido para la subclase particular.

Los harnesses que necesitan agregar opciones adicionales deberían extender la interfaz `BaseHarnessFilters` y propiedades opcionales adicionales según sea necesario. `HarnessPredicate` proporciona varios métodos de conveniencia para agregar opciones: `stringMatches()`, `addOption()` y `add()`. Consulta la [página de API de HarnessPredicate](/api/cdk/testing/HarnessPredicate) para la descripción completa.

Por ejemplo, cuando se trabaja con un menú es útil filtrar basado en el texto del trigger y filtrar items de menú basado en su texto:

```typescript
interface MyMenuHarnessFilters extends BaseHarnessFilters {
  /** Filtra basado en el texto del trigger para el menú. */
  triggerText?: string | RegExp;
}

interface MyMenuItemHarnessFilters extends BaseHarnessFilters {
  /** Filtra basado en el texto del item de menú. */
  text?: string | RegExp;
}

class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** Crea un `HarnessPredicate` usado para localizar un `MyMenuHarness` particular. */
  static with(options: MyMenuHarnessFilters): HarnessPredicate<MyMenuHarness> {
    return new HarnessPredicate(MyMenuHarness, options)
      .addOption('trigger text', options.triggerText,
        (harness, text) => HarnessPredicate.stringMatches(harness.getTriggerText(), text));
  }

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/** Obtiene el texto del trigger del menú. */
  async getTriggerText(): Promise<string> {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.getTriggerText();
  }
  ...
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';

/** Crea un `HarnessPredicate` usado para localizar un `MyMenuItemHarness` particular. */
  static with(options: MyMenuItemHarnessFilters): HarnessPredicate<MyMenuItemHarness> {
    return new HarnessPredicate(MyMenuItemHarness, options)
      .addOption('text', options.text,
        (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text));
  }

/** Obtiene el texto del item de menú. */
  async getText(): Promise<string> {
    const host = await this.host();
    return host.text();
  }
}
```
Puedes pasar un `HarnessPredicate` en lugar de una clase `ComponentHarness` a cualquiera de las APIs en `HarnessLoader`, `LocatorFactory` o `ComponentHarness`. Esto permite a los autores de pruebas fácilmente dirigirse a una instancia de componente particular al crear una instancia de harness. También permite al autor del harness aprovechar el mismo `HarnessPredicate` para habilitar APIs más poderosas en su clase harness. Por ejemplo, considera el método `getItems` en el `MyMenuHarness` mostrado arriba. Agregar una API de filtrado permite a los usuarios del harness buscar items de menú particulares:

```typescript
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** Obtiene una lista de items en el menú, opcionalmente filtrados basados en el criterio dado. */
  async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> {
    const getFilteredItems = this.locatorForAll(MyMenuItemHarness.with(filters));
    return getFilteredItems();
  }
  ...
}
```
## Crear `HarnessLoader` para elementos que usan proyección de contenido

Algunos componentes proyectan contenido adicional en la plantilla del componente. Consulta la [guía de proyección de contenido](guide/components/content-projection) para más información.

Agrega una instancia de `HarnessLoader` con alcance al elemento que contiene el `<ng-content>` cuando crees un harness para un componente que usa proyección de contenido. Esto permite al usuario del harness cargar harnesses adicionales para cualquier componente que fue pasado como contenido. `ComponentHarness` tiene varios métodos que pueden usarse para crear instancias de HarnessLoader para casos como este: `harnessLoaderFor()`, `harnessLoaderForOptional()`, `harnessLoaderForAll()`. Consulta la [página de referencia de la API de la interfaz HarnessLoader](/api/cdk/testing/HarnessLoader) para más detalles.

Por ejemplo, el ejemplo `MyPopupHarness` de arriba puede extender `ContentContainerComponentHarness` para agregar soporte para cargar harnesses dentro del `<ng-content>` del componente.

```typescript
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```
## Acceder a elementos fuera del elemento host del componente

Hay momentos cuando un component harness podría necesitar acceder a elementos fuera del elemento host de su componente correspondiente. Por ejemplo, código que muestra un elemento flotante o pop-up a menudo adjunta elementos DOM directamente al body del documento, como el servicio `Overlay` en el CDK de Angular.

En este caso, `ComponentHarness` proporciona un método que puede usarse para obtener un `LocatorFactory` para el elemento raíz del documento. El `LocatorFactory` soporta la mayoría de las mismas APIs que la clase base `ComponentHarness`, y puede luego usarse para consultar relativo al elemento raíz del documento.

Considera si el componente `MyPopup` arriba usara el overlay del CDK para el contenido del popup, en lugar de un elemento en su propia plantilla. En este caso, `MyPopupHarness` tendría que acceder al elemento content a través del método `documentRootLocatorFactory()` que obtiene una factory locator enraizada en la raíz del documento.

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

/** Obtiene un `HarnessLoader` cuyo elemento raíz es el elemento content del popup. */
  async getHarnessLoaderForContent(): Promise<HarnessLoader> {
    const rootLocator = this.documentRootLocatorFactory();
    return rootLocator.harnessLoaderFor('my-popup-content');
  }
}
```
## Esperar tareas asíncronas

Los métodos en `TestElement` automáticamente desencadenan la detección de cambios de Angular y esperan tareas dentro del `NgZone`. En la mayoría de los casos no se requiere esfuerzo especial para que los autores de harness esperen tareas asíncronas. Sin embargo, hay algunos casos extremos donde esto puede no ser suficiente.

Bajo algunas circunstancias, las animaciones de Angular pueden requerir un segundo ciclo de detección de cambios y la subsiguiente estabilización de `NgZone` antes de que los eventos de animación se vacíen completamente. En casos donde esto se necesita, el `ComponentHarness` ofrece un método `forceStabilize()` que puede llamarse para hacer la segunda ronda.

Puedes usar `NgZone.runOutsideAngular()` para programar tareas fuera de NgZone. Llama al método `waitForTasksOutsideAngular()` en el harness correspondiente si necesitas esperar explícitamente tareas fuera de `NgZone` ya que esto no sucede automáticamente.
# Animando tus aplicaciones con `animate.enter` y `animate.leave`

Las animaciones bien diseñadas pueden hacer que tu aplicación sea más divertida y fácil de usar, pero no son solo cosméticas.
Las animaciones pueden mejorar tu aplicación y la experiencia del usuario de varias maneras:

* Sin animaciones, las transiciones de páginas web pueden parecer abruptas y bruscas
* El movimiento mejora enormemente la experiencia del usuario, así que las animaciones dan a los usuarios la oportunidad de detectar la respuesta de la aplicación a sus acciones
* Las buenas animaciones pueden dirigir suavemente la atención del usuario a lo largo de un flujo de trabajo

Angular proporciona `animate.enter` y `animate.leave` para animar los elementos de tu aplicación. Estas dos características aplican clases CSS de entrada y salida en los momentos apropiados o llaman funciones para aplicar animaciones de bibliotecas de terceros. `animate.enter` y `animate.leave` no son directivas. Son APIs especiales soportadas directamente por el compilador de Angular. Pueden ser usadas en elementos directamente y también pueden ser usadas como un enlace host.

## `animate.enter`

Puedes usar `animate.enter` para animar elementos a medida que _entran_ al DOM. Puedes definir animaciones de entrada usando clases CSS con transiciones o animaciones de keyframes.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts">
    <docs-code header="src/app/enter.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts" />
    <docs-code header="src/app/enter.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.html" />
    <docs-code header="src/app/enter.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.css"/>
</docs-code-multifile>

Cuando la animación se completa, Angular elimina la clase o clases que especificaste en `animate.enter` del DOM. Las clases de animación solo están presentes mientras la animación está activa.

NOTA: Cuando se usan múltiples animaciones de keyframes o propiedades de transición en un elemento, Angular elimina todas las clases solo _después_ de que la animación más larga se haya completado.

Puedes usar `animate.enter` con cualquier otra característica de Angular, como control de flujo o expresiones dinámicas. `animate.enter` acepta tanto una cadena de clase única (con múltiples clases separadas por espacios), o un array de cadenas de clases.

Una nota rápida sobre el uso de transiciones CSS: Si eliges usar transiciones en lugar de animaciones de keyframes, las clases agregadas al elemento con `animate.enter` representan el estado al que la transición animará. Tu CSS de elemento base es cómo se verá el elemento cuando no se ejecuten animaciones, lo cual es probablemente similar al estado final de la transición CSS. Así que todavía necesitarías emparejarlo con `@starting-style` para tener un estado _desde_ apropiado para que tu transición funcione.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts">
    <docs-code header="src/app/enter-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts" />
    <docs-code header="src/app/enter-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.html" />
    <docs-code header="src/app/enter-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.css"/>
</docs-code-multifile>

## `animate.leave`

Puedes usar `animate.leave` para animar elementos a medida que _salen_ del DOM. Puedes definir animaciones de salida usando clases CSS con transformaciones o animaciones de keyframes.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts">
    <docs-code header="src/app/leave.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts" />
    <docs-code header="src/app/leave.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.html" />
    <docs-code header="src/app/leave.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.css"/>
</docs-code-multifile>

Cuando la animación se completa, Angular elimina automáticamente el elemento animado del DOM.

NOTA: Cuando se usan múltiples animaciones de keyframes o propiedades de transición en un elemento, Angular espera para eliminar el elemento solo _después_ de que la más larga de esas animaciones se haya completado.

`animate.leave` también puede ser usado con signals y otros enlaces. Puedes usar `animate.leave` con una clase única o múltiples clases. Ya sea especificándolo como una cadena simple con espacios o un array de cadenas.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts">
    <docs-code header="src/app/leave-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts" />
    <docs-code header="src/app/leave-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.html" />
    <docs-code header="src/app/leave-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.css"/>
</docs-code-multifile>

## Enlaces de eventos, funciones y bibliotecas de terceros

Tanto `animate.enter` como `animate.leave` soportan sintaxis de enlace de eventos que permite llamadas a funciones. Puedes usar esta sintaxis para llamar a una función en el código de tu componente o utilizar bibliotecas de animación de terceros, como [GSAP](https://gsap.com/), [anime.js](https://animejs.com/), o cualquier otra biblioteca de animación JavaScript.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts">
    <docs-code header="src/app/leave-event.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts" />
    <docs-code header="src/app/leave-event.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.html" />
    <docs-code header="src/app/leave-event.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.css"/>
</docs-code-multifile>

El objeto `$event` tiene el tipo `AnimationCallbackEvent`. Incluye el elemento como el `target` y proporciona una función `animationComplete()` para notificar al framework cuando la animación termina.

IMPORTANTE: **Debes** llamar a la función `animationComplete()` cuando uses `animate.leave` para que Angular elimine el elemento.

Si no llamas a `animationComplete()` cuando usas `animate.leave`, Angular llama a la función automáticamente después de un retraso de cuatro segundos. Puedes configurar la duración del retraso proporcionando el token `MAX_ANIMATION_TIMEOUT` en milisegundos.

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```

## Pruebas

TestBed proporciona soporte integrado para habilitar o deshabilitar animaciones en tu entorno de prueba. Las animaciones CSS requieren un navegador para ejecutarse, y muchas de las APIs no están disponibles en un entorno de prueba. Por defecto, TestBed deshabilita las animaciones para ti en tus entornos de prueba.

Si quieres probar que las animaciones están animando en una prueba de navegador, por ejemplo una prueba end-to-end, puedes configurar TestBed para habilitar animaciones especificando `animationsEnabled: true` en tu configuración de prueba.

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

Esto configurará las animaciones en tu entorno de prueba para que se comporten normalmente.

NOTA: Algunos entornos de prueba no emiten eventos de animación como `animationstart`, `animationend` y sus equivalentes de eventos de transición.

## Más sobre animaciones de Angular

También puede que te interese lo siguiente:
# Animando tu aplicación con CSS

CSS ofrece un conjunto robusto de herramientas para crear animaciones hermosas y atractivas dentro de tu aplicación.

## Cómo escribir animaciones en CSS nativo

Si nunca has escrito animaciones en CSS nativo, hay varias guías excelentes para comenzar. Aquí hay algunas de ellas:
[Guía de animaciones CSS de MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)
[Guía de animaciones CSS3 de W3Schools](https://www.w3schools.com/css/css3_animations.asp)
[Tutorial completo de animaciones CSS](https://www.lambdatest.com/blog/css-animations-tutorial/)
[Animación CSS para principiantes](https://thoughtbot.com/blog/css-animation-for-beginners)

y un par de videos:
[Aprende animación CSS en 9 minutos](https://www.youtube.com/watch?v=z2LQYsZhsFw)
[Lista de reproducción de tutorial de animación CSS de Net Ninja](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

Consulta algunas de estas diversas guías y tutoriales, y luego regresa a esta guía.

## Creando animaciones reutilizables

Puedes crear animaciones reutilizables que se pueden compartir en toda tu aplicación usando `@keyframes`. Define animaciones de keyframes en un archivo CSS compartido, y podrás reutilizar esas animaciones de keyframes donde quieras dentro de tu aplicación.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-shared"/>

Agregar la clase `animated-class` a un elemento activaría la animación en ese elemento.

## Animando una transición

### Animando estado y estilos

Es posible que desees animar entre dos estados diferentes, por ejemplo cuando un elemento está abierto o cerrado. Puedes lograr esto usando clases CSS ya sea mediante una animación de keyframe o estilo de transición.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-states"/>

Disparar el estado `open` o `closed` se hace alternando clases en el elemento en tu componente. Puedes encontrar ejemplos de cómo hacer esto en nuestra [guía de plantillas](guide/templates/binding#css-class-and-style-property-bindings).

Puedes ver ejemplos similares en la guía de plantillas para [animar estilos directamente](guide/templates/binding#css-style-properties).

### Transiciones, tiempo y easing

Animar a menudo requiere ajustar comportamientos de tiempo, retrasos y easing. Esto se puede hacer usando varias propiedades CSS o propiedades abreviadas.

Especifica `animation-duration`, `animation-delay` y `animation-timing-function` para una animación de keyframe en CSS, o alternativamente usa la propiedad abreviada `animation`.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-timing"/>

De manera similar, puedes usar `transition-duration`, `transition-delay` y `transition-timing-function` y la abreviación `transition` para animaciones que no están usando `@keyframes`.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="transition-timing"/>

### Disparando una animación

Las animaciones se pueden disparar alternando estilos o clases CSS. Una vez que una clase está presente en un elemento, la animación ocurrirá. Eliminar la clase revertirá el elemento a cualquier CSS que esté definido para ese elemento. Aquí hay un ejemplo:

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts">
    <docs-code header="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" />
    <docs-code header="src/app/open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" />
    <docs-code header="src/app/open-close.component.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.css"/>
</docs-code-multifile>

## Transiciones y triggers

### Animando altura automática

Puedes usar css-grid para animar a altura automática.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts">
    <docs-code header="src/app/auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" />
    <docs-code header="src/app/auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" />
    <docs-code header="src/app/auto-height.component.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.css"  />
</docs-code-multifile>

Si no tienes que preocuparte por soportar todos los navegadores, también puedes revisar `calc-size()`, que es la verdadera solución para animar altura automática. Consulta [la documentación de MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) y (este tutorial)[https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/] para más información.

### Animar entrada y salida de una vista

Puedes crear animaciones para cuando un elemento entra en una vista o sale de una vista. Comencemos viendo cómo animar un elemento que entra en una vista. Haremos esto con `animate.enter`, que aplicará clases de animación cuando un elemento entre en la vista.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts">
    <docs-code header="src/app/insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" />
    <docs-code header="src/app/insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" />
    <docs-code header="src/app/insert.component.css" path="adev/src/content/examples/animations/src/app/native-css/insert.component.css"  />
</docs-code-multifile>

Animar un elemento cuando sale de la vista es similar a animar cuando entra en una vista. Usa `animate.leave` para especificar qué clases CSS aplicar cuando el elemento sale de la vista.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts">
    <docs-code header="src/app/remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" />
    <docs-code header="src/app/remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" />
    <docs-code header="src/app/remove.component.css" path="adev/src/content/examples/animations/src/app/native-css/remove.component.css"  />
</docs-code-multifile>

Para más información sobre `animate.enter` y `animate.leave`, consulta la [guía de animaciones de entrada y salida](guide/animations).

### Animando incremento y decremento

Animar en incremento y decremento es un patrón común en aplicaciones. Aquí hay un ejemplo de cómo puedes lograr ese comportamiento.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts">
    <docs-code header="src/app/increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" />
    <docs-code header="src/app/increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" />
    <docs-code header="src/app/increment-decrement.component.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.css" />
</docs-code-multifile>

### Deshabilitando una animación o todas las animaciones

Si deseas deshabilitar las animaciones que has especificado, tienes múltiples opciones.

1. Crea una clase personalizada que fuerce la animación y transición a `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

Aplicar esta clase a un elemento previene que cualquier animación se dispare en ese elemento. Alternativamente podrías aplicar esto a todo tu DOM o sección de tu DOM para forzar este comportamiento. Sin embargo, esto previene que los eventos de animación se disparen. Si estás esperando eventos de animación para la eliminación de elementos, esta solución no funcionará. Una solución alternativa es establecer las duraciones a 1 milisegundo en su lugar.

2. Usa la media query [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) para asegurar que no se reproduzcan animaciones para usuarios que prefieren menos animación.

3. Prevenir la adición de clases de animación programáticamente

### Callbacks de animación

Si tienes acciones que te gustaría ejecutar en ciertos puntos durante las animaciones, hay varios eventos disponibles que puedes escuchar. Aquí hay algunos de ellos.

[`OnAnimationStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationstart_event)
[`OnAnimationEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationend_event)
[`OnAnimationIteration`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationitration_event)
[`OnAnimationCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationcancel_event)

[`OnTransitionStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionstart_event)
[`OnTransitionRun`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionrun_event)
[`OnTransitionEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionend_event)
[`OnTransitionCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitioncancel_event)

La API de Web Animations tiene mucha funcionalidad adicional. [Echa un vistazo a la documentación](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) para ver todas las APIs de animación disponibles.

NOTA: Ten en cuenta los problemas de propagación con estos callbacks. Si estás animando hijos y padres, los eventos se propagan desde los hijos hacia los padres. Considera detener la propagación o examinar más detalles dentro del evento para determinar si estás respondiendo al objetivo de evento deseado en lugar de un evento que se propaga desde un nodo hijo. Puedes examinar la propiedad `animationname` o las propiedades que están siendo transicionadas para verificar que tienes los nodos correctos.

## Secuencias complejas

Las animaciones son a menudo más complicadas que solo un simple fade in o fade out. Puedes tener muchas secuencias complicadas de animaciones que desees ejecutar. Echemos un vistazo a algunos de esos posibles escenarios.

### Escalonando animaciones en una lista

Un efecto común es escalonar las animaciones de cada elemento en una lista para crear un efecto en cascada. Esto se puede lograr utilizando `animation-delay` o `transition-delay`. Aquí hay un ejemplo de cómo podría verse ese CSS.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts">
    <docs-code header="src/app/stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" />
    <docs-code header="src/app/stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" />
    <docs-code header="src/app/stagger.component.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.css" />
</docs-code-multifile>

### Animaciones paralelas

Puedes aplicar múltiples animaciones a un elemento a la vez usando la propiedad abreviada `animation`. Cada una puede tener sus propias duraciones y retrasos. Esto te permite componer animaciones juntas y crear efectos complicados.

```css
.target-element {
  animation: rotate 3s, fade-in 2s;
}
```

En este ejemplo, las animaciones `rotate` y `fade-in` se disparan al mismo tiempo, pero tienen diferentes duraciones.

### Animando los elementos de una lista que se reordena

Los elementos en un bucle `@for` serán eliminados y re-agregados, lo que disparará animaciones usando `@starting-styles` para animaciones de entrada. Alternativamente, puedes usar `animate.enter` para este mismo comportamiento. Usa `animate.leave` para animar elementos a medida que se eliminan, como se ve en el ejemplo a continuación.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts">
    <docs-code header="src/app/reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" />
    <docs-code header="src/app/reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" />
    <docs-code header="src/app/reorder.component.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.css" />
</docs-code-multifile>

## Control programático de animaciones

Puedes obtener animaciones de un elemento directamente usando [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations). Esto devuelve un array de cada [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) en ese elemento. Puedes usar la API de `Animation` para hacer mucho más de lo que podías con lo que ofrecía el `AnimationPlayer` del paquete de animaciones. Desde aquí puedes `cancel()`, `play()`, `pause()`, `reverse()` y mucho más. Esta API nativa debería proporcionar todo lo que necesitas para controlar tus animaciones.

## Más sobre animaciones de Angular

También puede que te interese lo siguiente:
# Animaciones de transición de ruta

Las animaciones de transición de ruta mejoran la experiencia del usuario proporcionando transiciones visuales suaves al navegar entre diferentes vistas en tu aplicación Angular. [Angular Router](/guide/routing/overview) incluye soporte integrado para la API View Transitions del navegador, habilitando animaciones fluidas entre cambios de ruta en navegadores compatibles.

ÚTIL: La integración nativa de View Transitions del Router está actualmente en [developer preview](/reference/releases#developer-preview). Native View Transitions son una característica relativamente nueva del navegador con soporte limitado en todos los navegadores.

## Cómo funcionan View Transitions

View transitions usan la API nativa del navegador [`document.startViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) para crear animaciones suaves entre diferentes estados de tu aplicación. La API funciona mediante:

1. **Capturar el estado actual** - El navegador toma una captura de pantalla de la página actual
2. **Ejecutar la actualización del DOM** - Tu función de callback se ejecuta para actualizar el DOM
3. **Capturar el nuevo estado** - El navegador captura el estado de la página actualizada
4. **Reproducir la transición** - El navegador anima entre los estados antiguo y nuevo

Aquí está la estructura básica de la API `startViewTransition`:

```ts
document.startViewTransition(async () => {
  await updateTheDOMSomehow();
});
```

Para más detalles sobre la API del navegador, consulta el [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions).

## Cómo el Router usa view transitions

Angular Router integra view transitions en el ciclo de vida de navegación para crear cambios de ruta fluidos. Durante la navegación, el Router:

1. **Completa la preparación de navegación** - Se ejecutan coincidencia de ruta, [lazy loading](/guide/routing/define-routes#lazily-loaded-components), [guards](/guide/routing/route-guards) y [resolvers](/guide/routing/data-resolvers)
2. **Inicia la view transition** - El Router llama a `startViewTransition` cuando las rutas están listas para activación
3. **Actualiza el DOM** - El Router activa nuevas rutas y desactiva las antiguas dentro del callback de transición
4. **Finaliza la transición** - La Promise de transición se resuelve cuando Angular completa la renderización

La integración de view transition del Router actúa como una [mejora progresiva](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). Cuando los navegadores no soportan la API View Transitions, el Router realiza actualizaciones DOM normales sin animación, asegurando que tu aplicación funcione en todos los navegadores.

## Habilitar View Transitions en el Router

Habilita view transitions agregando la característica `withViewTransitions` a tu [configuración del router](/guide/routing/define-routes#adding-the-router-to-your-application). Angular soporta tanto enfoques de bootstrap standalone como NgModule:

### Bootstrap standalone

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter, withViewTransitions } from '@angular/router';
import { routes } from './app.routes';

bootstrapApplication(MyApp, {
  providers: [
    provideRouter(routes, withViewTransitions()),
  ]
});
```

### Bootstrap NgModule

```ts
import { NgModule } from '@angular/core';
import { RouterModule } from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})]
})
export class AppRouting {}
```

[Prueba el ejemplo "count" en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

Este ejemplo demuestra cómo la navegación del router puede reemplazar llamadas directas a `startViewTransition` para actualizaciones de contador.

## Personalizar transiciones con CSS

Puedes personalizar view transitions usando CSS para crear efectos de animación únicos. El navegador crea elementos de transición separados que puedes seleccionar con selectores CSS.

Para crear transiciones personalizadas:

1. **Agregar view-transition-name** - Asigna nombres únicos a elementos que quieras animar
2. **Definir animaciones globales** - Crea animaciones CSS en tus estilos globales
3. **Seleccionar pseudo-elementos de transición** - Usa selectores `::view-transition-old()` y `::view-transition-new()`

Aquí hay un ejemplo que agrega un efecto de rotación a un elemento contador:

```css
/* Definir animaciones keyframe */
@keyframes rotate-out {
  to {
    transform: rotate(90deg);
  }
}

@keyframes rotate-in {
  from {
    transform: rotate(-90deg);
  }
}

/* Seleccionar pseudo-elementos de view transition */
::view-transition-old(count),
::view-transition-new(count) {
  animation-duration: 200ms;
  animation-name: -ua-view-transition-fade-in, rotate-in;
}

::view-transition-old(count) {
  animation-name: -ua-view-transition-fade-out, rotate-out;
}
```

IMPORTANTE: Define animaciones de view transition en tu archivo de estilos globales, no en estilos de componentes. La [encapsulación de vista](/guide/components/styling#view-encapsulation) de Angular limita el alcance de los estilos de componentes, lo que les impide seleccionar correctamente los pseudo-elementos de transición.

[Prueba el ejemplo actualizado "count" en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)

## Control avanzado de transición con onViewTransitionCreated

La característica `withViewTransitions` acepta un objeto de opciones con un callback `onViewTransitionCreated` para control avanzado sobre view transitions. Este callback:

- Se ejecuta en un [contexto de inyección](/guide/di/dependency-injection-context#run-within-an-injection-context)
- Recibe un objeto [`ViewTransitionInfo`](/api/router/ViewTransitionInfo) que contiene:
  - La instancia `ViewTransition` de `startViewTransition`
  - El [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) para la ruta desde la que se está navegando
  - El [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) para la ruta a la que se está navegando

Usa este callback para personalizar el comportamiento de transición basado en el contexto de navegación. Por ejemplo, puedes omitir transiciones para tipos específicos de navegación:

```ts
import { inject } from '@angular/core';
import { Router, withViewTransitions } from '@angular/router';

withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    const router = inject(Router);
    const targetUrl = router.getCurrentNavigation()!.finalUrl!;

// Omitir transición si solo cambia el fragment o query params
    const config = {
      paths: 'exact',
      matrixParams: 'exact',
      fragment: 'ignored',
      queryParams: 'ignored',
    };

if (router.isActive(targetUrl, config)) {
      transition.skipTransition();
    }
  },
})
```

Este ejemplo omite la view transition cuando la navegación solo cambia el [fragmento de URL o parámetros de consulta](/guide/routing/read-route-state#query-parameters) (como enlaces anchor dentro de la misma página). El método `skipTransition()` previene la animación mientras aún permite que la navegación se complete.

## Ejemplos del Chrome explainer adaptados a Angular

Los siguientes ejemplos demuestran varias técnicas de view transition adaptadas de la documentación del equipo de Chrome para uso con Angular Router:

### Los elementos en transición no necesitan ser el mismo elemento DOM

Los elementos pueden hacer transición suavemente entre diferentes elementos DOM siempre que compartan el mismo `view-transition-name`.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning_elements_dont_need_to_be_the_same_dom_element)
- [Ejemplo Angular en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-dh8npr?file=src%2Fmain.ts)

### Animaciones personalizadas de entrada y salida

Crea animaciones únicas para elementos que entran y salen del viewport durante transiciones de ruta.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#custom_entry_and_exit_transitions)
- [Ejemplo Angular en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-8kly3o)

### Actualizaciones asíncronas del DOM y espera por contenido

Angular Router prioriza transiciones inmediatas sobre esperar a que se cargue contenido adicional.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

NOTA: Angular Router no proporciona una forma de retrasar view transitions. Esta decisión de diseño previene que las páginas se vuelvan no interactivas mientras esperan contenido adicional. Como nota la documentación de Chrome: "Durante este tiempo, la página está congelada, por lo que los retrasos aquí deben mantenerse al mínimo...en algunos casos es mejor evitar el retraso por completo y usar el contenido que ya tienes."

### Manejar múltiples estilos de view transition con tipos de view transition

Usa tipos de view transition para aplicar diferentes estilos de animación basados en el contexto de navegación.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types)
- [Ejemplo Angular en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-vxzcam)

### Manejar múltiples estilos de view transition con un nombre de clase en la raíz de view transition (deprecado)

Este enfoque usa clases CSS en el elemento raíz de transición para controlar estilos de animación.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [Ejemplo Angular en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)

### Transición sin congelar otras animaciones

Mantén otras animaciones de página durante view transitions para crear experiencias de usuario más dinámicas.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning-without-freezing)
- [Ejemplo Angular en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-76kgww)

### Animar con JavaScript

Controla view transitions programáticamente usando APIs de JavaScript para escenarios de animación complejos.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#animating-with-javascript)
- [Ejemplo Angular en StackBlitz](https://stackblitz.com/edit/stackblitz-starters-cklnkm)
# Migrando del paquete de Animations de Angular

El paquete `@angular/animations` está deprecado a partir de la v20.2, que también introdujo las nuevas características `animate.enter` y `animate.leave` para agregar animaciones a tu aplicación. Usando estas nuevas características, puedes reemplazar todas las animaciones basadas en `@angular/animations` con CSS puro o bibliotecas de animación JS. Eliminar `@angular/animations` de tu aplicación puede reducir significativamente el tamaño de tu bundle de JavaScript. Las animaciones CSS nativas generalmente ofrecen rendimiento superior, ya que pueden beneficiarse de la aceleración por hardware. Esta guía te acompaña a través del proceso de refactorizar tu código de `@angular/animations` a animaciones CSS nativas.

## Cómo escribir animaciones en CSS nativo

Consulta algunas de estas diversas guías y tutoriales, y luego regresa a esta guía.

## Creando animaciones reutilizables

Al igual que con el paquete de animaciones, puedes crear animaciones reutilizables que se pueden compartir en toda tu aplicación. La versión del paquete de animaciones de esto te hacía usar la función `animation()` en un archivo TypeScript compartido. La versión CSS nativa de esto es similar, pero vive en un archivo CSS compartido.

#### Con paquete de Animations
<docs-code header="src/app/animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" visibleRegion="animation-example"/>

#### Con CSS nativo
<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-shared"/>

Agregar la clase `animated-class` a un elemento activaría la animación en ese elemento.

## Animando una transición

### Animando estado y estilos

El paquete de animaciones te permitía definir varios estados usando la función [`state()`](api/animations/state) dentro de un componente. Los ejemplos podrían ser un estado `open` o `closed` que contiene los estilos para cada estado respectivo dentro de la definición. Por ejemplo:

#### Con paquete de Animations
<docs-code header="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/open-close.component.ts" visibleRegion="state1"/>

Este mismo comportamiento se puede lograr nativamente usando clases CSS ya sea mediante una animación de keyframe o estilo de transición.

#### Con CSS nativo
<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-states"/>

Puedes ver ejemplos similares en la guía de plantillas para [animar estilos directamente](guide/templates/binding#css-style-properties).

### Transiciones, tiempo y easing

La función `animate()` del paquete de animaciones permite proporcionar tiempo, como duración, retrasos y easing. Esto se puede hacer nativamente con CSS usando varias propiedades CSS o propiedades abreviadas.

Especifica `animation-duration`, `animation-delay` y `animation-timing-function` para una animación de keyframe en CSS, o alternativamente usa la propiedad abreviada `animation`.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-timing"/>

De manera similar, puedes usar `transition-duration`, `transition-delay` y `transition-timing-function` y la abreviación `transition` para animaciones que no están usando `@keyframes`.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="transition-timing"/>

### Disparando una animación

El paquete de animaciones requería especificar triggers usando la función `trigger()` y anidar todos tus estados dentro de ella. Con CSS nativo, esto es innecesario. Las animaciones se pueden disparar alternando estilos o clases CSS. Una vez que una clase está presente en un elemento, la animación ocurrirá. Eliminar la clase revertirá el elemento a cualquier CSS que esté definido para ese elemento. Esto resulta en significativamente menos código para hacer la misma animación. Aquí hay un ejemplo:

#### Con paquete de Animations
#### Con CSS nativo
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts">
    <docs-code header="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" />
    <docs-code header="src/app/open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" />
    <docs-code header="src/app/open-close.component.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.css"/>
</docs-code-multifile>

## Transiciones y triggers

### Coincidencia de estado predefinido y comodines

El paquete de animaciones ofrece la capacidad de hacer coincidir tus estados definidos con una transición mediante cadenas. Por ejemplo, animar de open a closed sería `open => closed`. Puedes usar comodines para hacer coincidir cualquier estado con un estado objetivo, como `* => closed` y la palabra clave `void` se puede usar para estados de entrada y salida. Por ejemplo: `* => void` para cuando un elemento sale de una vista o `void => *` para cuando el elemento entra en una vista.

Estos patrones de coincidencia de estado no se necesitan en absoluto cuando se anima con CSS directamente. Puedes gestionar qué transiciones y animaciones `@keyframes` se aplican basándote en las clases que establezcas y/o los estilos que establezcas en los elementos. También puedes agregar `@starting-style` para controlar cómo se ve el elemento al entrar inmediatamente al DOM.

### Cálculo automático de propiedades con comodines

El paquete de animaciones ofrece la capacidad de animar cosas que han sido históricamente difíciles de animar, como animar una altura establecida a `height: auto`. Ahora también puedes hacer esto con CSS puro.

#### Con paquete de Animations
Puedes usar css-grid para animar a altura automática.

#### Con CSS nativo
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts">
    <docs-code header="src/app/auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" />
    <docs-code header="src/app/auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" />
    <docs-code header="src/app/auto-height.component.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.css"  />
</docs-code-multifile>

### Animar entrada y salida de una vista

El paquete de animaciones ofrecía el patrón de coincidencia mencionado anteriormente para entrada y salida, pero también incluía los alias abreviados de `:enter` y `:leave`.

#### Con paquete de Animations
Aquí está cómo se puede lograr lo mismo sin el paquete de animaciones usando `animate.enter`.

#### Con CSS nativo
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts">
    <docs-code header="src/app/insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" />
    <docs-code header="src/app/insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" />
    <docs-code header="src/app/insert.component.css" path="adev/src/content/examples/animations/src/app/native-css/insert.component.css"  />
</docs-code-multifile>

Usa `animate.leave` para animar elementos a medida que salen de la vista, lo que aplicará las clases CSS especificadas al elemento a medida que sale de la vista.

#### Con CSS nativo
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts">
    <docs-code header="src/app/remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" />
    <docs-code header="src/app/remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" />
    <docs-code header="src/app/remove.component.css" path="adev/src/content/examples/animations/src/app/native-css/remove.component.css"  />
</docs-code-multifile>

Para más información sobre `animate.enter` y `animate.leave`, consulta la [guía de animaciones de entrada y salida](guide/animations).

### Animando incremento y decremento

Junto con los mencionados `:enter` y `:leave`, también está `:increment` y `:decrement`. También puedes animar estos agregando y eliminando clases. A diferencia de los alias integrados del paquete de animaciones, no hay aplicación automática de clases cuando los valores suben o bajan. Puedes aplicar las clases apropiadas programáticamente. Aquí hay un ejemplo:

#### Con paquete de Animations
#### Con CSS nativo
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts">
    <docs-code header="src/app/increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" />
    <docs-code header="src/app/increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" />
    <docs-code header="src/app/increment-decrement.component.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.css" />
</docs-code-multifile>

### Animaciones padre / hijo

A diferencia del paquete de animaciones, cuando se especifican múltiples animaciones dentro de un componente dado, ninguna animación tiene prioridad sobre otra y nada bloquea que ninguna animación se dispare. Cualquier secuenciación de animaciones tendría que ser manejada por tu definición de tu animación CSS, usando retraso de animation / transition, y/o usando `animationend` o `transitionend` para manejar la adición del siguiente CSS a animar.

### Deshabilitando una animación o todas las animaciones

Con animaciones CSS nativas, si deseas deshabilitar las animaciones que has especificado, tienes múltiples opciones.

1. Crea una clase personalizada que fuerce la animación y transición a `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

3. Prevenir la adición de clases de animación programáticamente

### Callbacks de animación

El paquete de animaciones exponía callbacks para que uses en el caso de que desees hacer algo cuando la animación haya terminado. Las animaciones CSS nativas también tienen estos callbacks.

## Secuencias complejas

El paquete de animaciones tiene funcionalidad integrada para crear secuencias complejas. Estas secuencias son totalmente posibles sin el paquete de animaciones.

### Dirigirse a elementos específicos

En el paquete de animaciones, podías dirigirte a elementos específicos usando la función `query()` para encontrar elementos específicos por un nombre de clase CSS, similar a [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector). Esto es innecesario en un mundo de animación CSS nativa. En su lugar, puedes usar tus selectores CSS para dirigirte a sub-clases y aplicar cualquier `transform` o `animation` deseada.

Para alternar clases para nodos hijos dentro de una plantilla, puedes usar enlaces de clase y estilo para agregar las animaciones en los puntos correctos.

### Stagger()

La función `stagger()` te permitía retrasar la animación de cada elemento en una lista de elementos por un tiempo especificado para crear un efecto en cascada. Puedes replicar este comportamiento en CSS nativo utilizando `animation-delay` o `transition-delay`. Aquí hay un ejemplo de cómo podría verse ese CSS.

#### Con paquete de Animations
#### Con CSS nativo
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts">
    <docs-code header="src/app/stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" />
    <docs-code header="src/app/stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" />
    <docs-code header="src/app/stagger.component.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.css" />
</docs-code-multifile>

### Animaciones paralelas

El paquete de animaciones tiene una función `group()` para reproducir múltiples animaciones al mismo tiempo. En CSS, tienes control total sobre el tiempo de animación. Si tienes múltiples animaciones definidas, puedes aplicarlas todas a la vez.

```css
.target-element {
  animation: rotate 3s, fade-in 2s;
}
```

En este ejemplo, las animaciones `rotate` y `fade-in` se disparan al mismo tiempo.

### Animando los elementos de una lista que se reordena

El reordenamiento de elementos en una lista funciona de forma inmediata usando las técnicas descritas anteriormente. No se requiere ningún trabajo especial adicional. Los elementos en un bucle `@for` serán eliminados y re-agregados correctamente, lo que disparará animaciones usando `@starting-styles` para animaciones de entrada. Alternativamente, puedes usar `animate.enter` para este mismo comportamiento. Usa `animate.leave` para animar elementos a medida que se eliminan, como se ve en el ejemplo anterior.

#### Con paquete de Animations<
#### Con CSS nativo
<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts">
    <docs-code header="src/app/reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" />
    <docs-code header="src/app/reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" />
    <docs-code header="src/app/reorder.component.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.css" />
</docs-code-multifile>
## Migrando usos de AnimationPlayer

La clase `AnimationPlayer` permite acceso a una animación para hacer cosas más avanzadas como pausar, reproducir, reiniciar y finalizar una animación a través de código. Todas estas cosas también se pueden manejar nativamente.

## Transiciones de ruta

Puedes usar transiciones de vista para animar entre rutas. Consulta la [Guía de animaciones de transición de ruta](guide/routing/route-transition-animations) para comenzar.
# Angular without ZoneJS (Zoneless)

## Why use Zoneless?

The main advantages to removing ZoneJS as a dependency are:

- **Improved performance**: ZoneJS uses DOM events and async tasks as indicators of when application state _might_ have updated and subsequently triggers application synchronization to run change detection on the application's views. ZoneJS does not have any insight into whether application state actually changed and so this synchronization is triggered more frequently than necessary.
- **Improved Core Web Vitals**: ZoneJS brings a fair amount of overhead, both in payload size and in startup time cost.
- **Improved debugging experience**: ZoneJS makes debugging code more difficult. Stack traces are harder to understand with ZoneJS. It's also difficult to understand when code breaks as a result of being outside the Angular Zone.
- **Better ecosystem compatibility**: ZoneJS works by patching browser APIs but does not automatically have patches for every new browser API. Some APIs cannot be patched effectively, such as `async`/`await`, and have to be downleveled to work with ZoneJS. Sometimes libraries in the ecosystem are also incompatible with the way ZoneJS patches the native APIs. Removing ZoneJS as a dependency ensures better long-term compatibility by removing a source of complexity, monkey patching, and ongoing maintenance.

## Enabling Zoneless in an application
```typescript
// standalone bootstrap
bootstrapApplication(MyApp, {providers: [
  provideZonelessChangeDetection(),
]});

// NgModule bootstrap
platformBrowser().bootstrapModule(AppModule);
@NgModule({
  providers: [provideZonelessChangeDetection()]
})
export class AppModule {}
```

## Removing ZoneJS

Zoneless applications should remove ZoneJS entirely from the build to reduce bundle size. ZoneJS is typically
loaded via the `polyfills` option in `angular.json`, both in the `build` and `test` targets. Remove `zone.js`
and `zone.js/testing` from both to remove it from the build. Projects which use an explicit `polyfills.ts` file
should remove `import 'zone.js';` and `import 'zone.js/testing';` from the file.

After removing ZoneJS from the build, there is no longer a need for a `zone.js` dependency either and the
package can be removed entirely:

```shell
npm uninstall zone.js
```

## Requirements for Zoneless compatibility

Angular relies on notifications from core APIs in order to determine when to run change detection and on which views.
These notifications include:

- `ChangeDetectorRef.markForCheck` (called automatically by `AsyncPipe`)
- `ComponentRef.setInput`
- Updating a signal that's read in a template
- Bound host or template listeners callbacks
- Attaching a view that was marked dirty by one of the above

### `OnPush`-compatible components

One way to ensure that a component is using the correct notification mechanisms from above is to
use [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush).

The `OnPush` change detection strategy is not required, but it is a recommended step towards zoneless compatibility for application components. It is not always possible for library components to use `ChangeDetectionStrategy.OnPush`.
When a library component is a host for user-components which might use `ChangeDetectionStrategy.Default`, it cannot use `OnPush` because that would prevent the child component from being refreshed if it is not `OnPush` compatible and relies on ZoneJS to trigger change detection. Components can use the `Default` strategy as long as they notify Angular when change detection needs to run (calling `markForCheck`, using signals, `AsyncPipe`, etc.).
Being a host for a user component means using an API such as `ViewContainerRef.createComponent` and not just hosting a portion of a template from a user component (i.e. content projection or a using a template ref input).

### Remove `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable`, or `NgZone.onStable`

Applications and libraries need to remove uses of `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` and `NgZone.onStable`.
These observables will never emit when an Application enables zoneless change detection.
Similarly, `NgZone.isStable` will always be `true` and should not be used as a condition for code execution.

The `NgZone.onMicrotaskEmpty` and `NgZone.onStable` observables are most often used to wait for Angular to
complete change detection before performing a task. Instead, these can be replaced by `afterNextRender`
if they need to wait for a single change detection or `afterEveryRender` if there is some condition that might span
several change detection rounds. In other cases, these observables were used because they happened to be
familiar and have similar timing to what was needed. More straightforward or direct DOM APIs can be used instead,
such as `MutationObserver` when code needs to wait for certain DOM state (rather than waiting for it indirectly
through Angular's render hooks).
`NgZone.run` and `NgZone.runOutsideAngular` do not need to be removed in order for code to be compatible with
Zoneless applications. In fact, removing these calls can lead to performance regressions for libraries that
are used in applications that still rely on ZoneJS.
### `PendingTasks` for Server Side Rendering (SSR)

If you are using SSR with Angular, you may know that it relies on ZoneJS to help determine when the application
is "stable" and can be serialized. If there are asynchronous tasks that should prevent serialization, an application
not using ZoneJS must make Angular aware of these with the [PendingTasks](/api/core/PendingTasks) service. Serialization
will wait for the first moment that all pending tasks have been removed.
The two most straightforward uses of pending tasks are the `run` method:

```typescript
const taskService = inject(PendingTasks);
taskService.run(async () => {
  const someResult = await doSomeWorkThatNeedsToBeRendered();
  this.someState.set(someResult);
});
```

For more complicated use-cases, you can manually add and remove a pending task:

```typescript
const taskService = inject(PendingTasks);
const taskCleanup = taskService.add();
try {
  await doSomeWorkThatNeedsToBeRendered();
} catch {
  // handle error
} finally {
  taskCleanup();
}
```

In addition, the [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent#) helper in `rxjs-interop` ensures
the application remains unstable until the observable emits, completes, errors, or is unsubscribed.

```typescript
readonly myObservableState = someObservable.pipe(pendingUntilEvent());
```

The framework uses this service internally as well to prevent serialization until asynchronous tasks are complete. These include, but are not limited to,
an ongoing Router navigation and an incomplete `HttpClient` request.

## Testing and Debugging

### Using Zoneless in `TestBed`

The zoneless provider function can also be used with `TestBed` to help
ensure the components under test are compatible with a Zoneless
Angular application.

```typescript
TestBed.configureTestingModule({
  providers: [provideZonelessChangeDetection()]
});

const fixture = TestBed.createComponent(MyComponent);
await fixture.whenStable();
```

To ensure tests have the most similar behavior to production code,
avoid using `fixture.detectChanges()` when possible. This forces
change detection to run when Angular might otherwise have not
scheduled change detection. Tests should ensure these notifications
are happening and allow Angular to handle when to synchronize
state rather than manually forcing it to happen in the test.

For existing test suites, using `fixture.detectChanges()` is a common pattern
and it is likely not worth the effort of converting these to
`await fixture.whenStable()`. `TestBed` will still enforce that the
fixture's component is `OnPush` compatible and throws `ExpressionChangedAfterItHasBeenCheckedError`
if it finds that template values were updated without a
change notification (i.e. `fixture.componentInstance.someValue = 'newValue';`).
If the component is used in production, this issue should be addressed by updating
the component to use signals for state or call `ChangeDetectorRef.markForCheck()`.
If the component is only used as a test wrapper and never used in an application,
it is acceptable to use `fixture.changeDetectorRef.markForCheck()`.

### Debug-mode check to ensure updates are detected

Angular also provides an additional tool to help verify that an application is making
updates to state in a zoneless-compatible way. `provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})`
can be used to periodically check to ensure that no bindings have been updated
without a notification. Angular throws `ExpressionChangedAfterItHasBeenCheckedError`
if there is an updated binding that would not have refreshed by the zoneless change
detection.
As an open source project, Angular’s daily commits, PRs and momentum is all trackable on GitHub. To increase transparency into how this daily work connects to the framework’s future, our roadmap brings together the team’s current and future planned vision.

The following projects are not associated with a particular Angular version. We will release them on completion, and they will be part of a specific version based on our release schedule, following semantic versioning. For example, we release features in the next minor after completion or the next major if they include breaking changes.

Currently, Angular has two goals for the framework:

1. Improve the [Angular developer experience](#improving-the-angular-developer-experience) and
2. Improve the [framework’s performance](#fast-by-default).

Continue reading to learn how we plan to deliver these objectives with specific project work.

## Explore modern Angular

Start developing with the latest Angular features from our roadmap. This list represents the current status of new features from our roadmap:

### Available to experiment with

* [Resource API](/guide/signals/resource)
* [httpResource](/api/common/http/httpResource)

### Production ready

* [Zoneless change detection](/guide/zoneless)
* [Linked Signal API](/guide/signals/linked-signal)
* [Incremental hydration](/guide/incremental-hydration)
* [Effect API](/api/core/effect)
* [Event replay with SSR](/api/platform-browser/withEventReplay)
* [Route-level render mode](/guide/ssr)

## Improving the Angular developer experience

### Developer velocity
### Improve Angular Material and the CDK
### Improve tooling
## Future work, explorations, and prototyping

This section represents explorations and prototyping of potential future projects. A reasonable outcome is to decide that our current solutions are the best options. Other projects may result in RFCs, graduating to in-progress projects, or being deprioritized as the web continues to innovate along with our framework.
## Completed projects
# Manteniendo tus proyectos Angular actualizados

Al igual que la Web y todo el ecosistema web, Angular está mejorando continuamente.
Angular equilibra la mejora continua con un fuerte enfoque en la estabilidad y en hacer las actualizaciones directas.
Mantener tu aplicación Angular actualizada te permite aprovechar las nuevas funcionalidades de vanguardia, así como optimizaciones y correcciones de errores.

Este documento contiene información y recursos para ayudarte a mantener tus aplicaciones y bibliotecas Angular actualizadas.

Para información sobre nuestra política y prácticas de versionado —incluyendo prácticas de soporte y deprecación, así como el calendario de lanzamientos— consulta [Versionado y lanzamientos de Angular](reference/releases "Versionado y lanzamientos de Angular").

ÚTIL: Si actualmente estás usando AngularJS, consulta [Actualizando desde AngularJS](https://angular.io/guide/upgrade "Actualizando desde Angular JS").
*AngularJS* es el nombre para todas las versiones v1.x de Angular.

## Recibiendo notificaciones de nuevos lanzamientos

Para recibir notificaciones cuando nuevos lanzamientos estén disponibles, sigue a [@angular](https://x.com/angular "@angular en X") en X (anteriormente Twitter) o suscríbete al [blog de Angular](https://blog.angular.dev "Blog de Angular").

## Aprendiendo sobre nuevas funcionalidades

¿Qué hay de nuevo? ¿Qué ha cambiado? Compartimos las cosas más importantes que necesitas saber en el blog de Angular en [anuncios de lanzamiento]( https://blog.angular.dev/ "Blog de Angular - anuncios de lanzamiento").

Para revisar una lista completa de cambios, organizados por versión, consulta el [registro de cambios de Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md "Registro de cambios de Angular").

## Verificando tu versión de Angular

Para verificar la versión de Angular de tu aplicación usa el comando `ng version` desde dentro del directorio de tu proyecto.

## Encontrando la versión actual de Angular

La versión estable más reciente lanzada de Angular aparece [en npm](https://www.npmjs.com/package/@angular/core "Angular en npm") bajo "Version." Por ejemplo, `16.2.4`.

También puedes encontrar la versión más actual de Angular usando el comando CLI [`ng update`](cli/update).
Por defecto, [`ng update`](cli/update)(sin argumentos adicionales) lista las actualizaciones que están disponibles para ti.

## Actualizando tu entorno y aplicaciones

Para hacer la actualización sencilla, proporcionamos instrucciones completas en la [Guía de Actualización de Angular](update-guide) interactiva.

La Guía de Actualización de Angular proporciona instrucciones de actualización personalizadas, basadas en las versiones actuales y objetivo que especifiques.
Incluye rutas de actualización básicas y avanzadas, para coincidir con la complejidad de tus aplicaciones.
También incluye información de solución de problemas y cualquier cambio manual recomendado para ayudarte a aprovechar al máximo el nuevo lanzamiento.

Para actualizaciones simples, el comando CLI [`ng update`](cli/update) es todo lo que necesitas.
Sin argumentos adicionales, [`ng update`](cli/update) lista las actualizaciones que están disponibles para ti y proporciona pasos recomendados para actualizar tu aplicación a la versión más actual.

[Versionado y Lanzamientos de Angular](reference/releases#versioning "Prácticas de Lanzamiento de Angular, Versionado") describe el nivel de cambio que puedes esperar basado en el número de versión de un lanzamiento.
También describe las rutas de actualización soportadas.

## Resumen de recursos

* Anuncios de lanzamiento:
    [Blog de Angular - anuncios de lanzamiento](https://blog.angular.dev/ "Anuncios del blog de Angular sobre lanzamientos recientes")

* Detalles de lanzamiento:
    [Registro de cambios de Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md "Registro de cambios de Angular")

* Instrucciones de actualización:
    [Guía de Actualización de Angular](update-guide)

* Referencia del comando de actualización:
    [Referencia del comando `ng update` de Angular CLI](cli/update)

* Prácticas de versionado, lanzamiento, soporte y deprecación:
    [Versionado y lanzamientos de Angular](reference/releases "Versionado y lanzamientos de Angular")
# Seguridad en `HttpClient`

`HttpClient` incluye soporte integrado para dos mecanismos de seguridad HTTP comunes: protección XSSI y protección XSRF/CSRF.

CONSEJO: También considera adoptar una [Política de Seguridad de Contenido](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) para tus APIs.

## Protección XSSI

La Inclusión de Scripts Entre Sitios (XSSI) es una forma de ataque de [Scripting Entre Sitios](https://es.wikipedia.org/wiki/Cross-site_scripting) donde un atacante carga datos JSON de tus endpoints de API como `<script>`s en una página que controla. Diferentes técnicas de JavaScript pueden entonces usarse para acceder a estos datos.

Una técnica común para prevenir XSSI es servir respuestas JSON con un "prefijo no ejecutable", comúnmente `)]}',\n`. Este prefijo previene que la respuesta JSON sea interpretada como JavaScript ejecutable válido. Cuando la API se carga como datos, el prefijo puede eliminarse antes del análisis JSON.

`HttpClient` automáticamente elimina este prefijo XSSI (si está presente) al analizar JSON de una respuesta.

## Protección XSRF/CSRF

[Falsificación de Solicitudes Entre Sitios (XSRF o CSRF)](https://es.wikipedia.org/wiki/Cross-site_request_forgery) es una técnica de ataque mediante la cual el atacante puede engañar a un usuario autenticado para que ejecute acciones en tu sitio web sin saberlo.

`HttpClient` soporta un [mecanismo común](https://es.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token) usado para prevenir ataques XSRF. Al realizar solicitudes HTTP, un interceptor lee un token de una cookie, por defecto `XSRF-TOKEN`, y lo establece como un encabezado HTTP, `X-XSRF-TOKEN`. Debido a que solo el código que se ejecuta en tu dominio podría leer la cookie, el backend puede estar seguro de que la solicitud HTTP vino de tu aplicación cliente y no de un atacante.

Por defecto, un interceptor envía este encabezado en todas las solicitudes de mutación (como `POST`) a URLs relativas, pero no en solicitudes GET/HEAD o en solicitudes con una URL absoluta.
La protección CSRF solo es necesaria para solicitudes que pueden cambiar el estado en el backend. Por su naturaleza, los ataques CSRF cruzan límites de dominio, y la [política de mismo origen](https://developer.mozilla.org/es/docs/Web/Security/Same-origin_policy) de la web impedirá que una página atacante recupere los resultados de solicitudes GET autenticadas.
Para aprovechar esto, tu servidor necesita establecer un token en una cookie de sesión legible por JavaScript llamada `XSRF-TOKEN` ya sea en la carga de la página o en la primera solicitud GET. En solicitudes posteriores, el servidor puede verificar que la cookie coincida con el encabezado HTTP `X-XSRF-TOKEN`, y por lo tanto estar seguro de que solo el código que se ejecuta en tu dominio podría haber enviado la solicitud. El token debe ser único para cada usuario y debe ser verificable por el servidor; esto previene que el cliente invente sus propios tokens. Establece el token como un resumen de la cookie de autenticación de tu sitio con una sal para mayor seguridad.

Para prevenir colisiones en entornos donde múltiples aplicaciones Angular comparten el mismo dominio o subdominio, dale a cada aplicación un nombre de cookie único.
  Tu servicio backend debe estar configurado para establecer la cookie para tu página, y para verificar que el encabezado esté presente en todas las solicitudes elegibles. No hacerlo hace que la protección predeterminada de Angular sea inefectiva.
### Configura nombres personalizados de cookie/encabezado

Si tu servicio backend usa nombres diferentes para la cookie o encabezado del token XSRF, usa `withXsrfConfiguration` para sobrescribir los valores predeterminados.

Agrégalo a la llamada de `provideHttpClient` de la siguiente manera:

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'CUSTOM_XSRF_TOKEN',
        headerName: 'X-Custom-Xsrf-Header',
      }),
    ),
  ]
};
```
### Desabilitando la protección XSRF

Si el mecanismo de protección XSRF integrado no funciona para tu aplicación, puedes deshabilitarlo usando la característica `withNoXsrfProtection`:

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withNoXsrfProtection(),
    ),
  ]
};
```

# Internacionalización de Angular (i18n)

La *internacionalización*, a veces referenciada como i18n, es el proceso de diseñar y preparar tu proyecto para su uso en diferentes configuraciones regionales (locales) alrededor del mundo.
La *localización* es el proceso de construir versiones de tu proyecto para diferentes configuraciones regionales.
El proceso de localización incluye las siguientes acciones.

* Extraer texto para traducción a diferentes idiomas
* Formatear datos para una configuración regional específica

Una *configuración regional* (locale) identifica una región en la que las personas hablan un idioma particular o variante del idioma.
Las posibles regiones incluyen países y regiones geográficas.
Una configuración regional determina el formato y análisis de los siguientes detalles.

* Unidades de medida incluyendo fecha y hora, números y monedas
* Nombres traducidos incluyendo zonas horarias, idiomas y países

Para una introducción rápida a la localización e internacionalización mira este video:

<docs-video src="https://www.youtube.com/embed/KNTN-nsbV7M"/>

## Aprende sobre la internacionalización de Angular