``` 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 Save Save ``` 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 <!-- user-profile.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 CONSEJO: 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 4 modos de encapsulación de vista: `Emulated`, `ShadowDom`, `ExperimentalIsolatedShadowDom`, 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 la pseudo-clase [`:host`](https://developer.mozilla.org/es/docs/Web/CSS/Reference/Selectors/:host). Aunque la pseudo-clase [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context) está deprecada en navegadores modernos, el compilador de Angular proporciona soporte completo para ella. Ambas pseudo-clases pueden usarse sin depender de [Shadow DOM](https://developer.mozilla.org/es/docs/Web/API/Web_components/Using_shadow_DOM) nativo. 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/docs/Web/Web_Components/Using_shadow_DOM). Al habilitar este modo, Angular adjunta un shadow root al elemento host del componente y renderiza la plantilla y los estilos del componente en el árbol de sombra correspondiente. 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.ExperimentalIsolatedShadowDom Se comporta como se describe arriba, excepto que 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. ### 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. # Aceptando datos con propiedades de input CONSEJO: Esta guía asume que ya has leído la [Guía de Esenciales](essentials). Lee esa primero si eres nuevo en Angular. CONSEJO: Si estás familiarizado con otros frameworks web, las propiedades de input son similares a _props_. Cuando usas un componente, comúnmente quieres pasarle algunos datos. Un componente especifica los datos que acepta declarando **inputs**: ```ts {highlight:[5]} import {Component, input} from '@angular/core'; @Component({/*...*/}) export class CustomSlider { // Declara un input llamado 'value' con un valor predeterminado de cero. value = input(0); } ``` Esto te permite enlazar a la propiedad en una plantilla: ```html <custom-slider [value]="50" /> ``` Si un input tiene un valor predeterminado, TypeScript infiere el tipo del valor predeterminado: ```ts @Component({/*...*/}) export class CustomSlider { // TypeScript infiere que este input es un número, devolviendo InputSignal<number>. value = input(0); } ``` Puedes declarar explícitamente un tipo para el input especificando un parámetro genérico a la función. Si un input sin un valor predeterminado no se establece, su valor es `undefined`: ```ts @Component({/*...*/}) export class CustomSlider { // Produce un InputSignal<number | undefined> porque `value` puede no estar establecido. value = input<number>(); } ``` **Angular registra los inputs estáticamente en tiempo de compilación**. Los inputs no se pueden agregar o eliminar en tiempo de ejecución. La función `input` tiene un significado especial para el compilador de Angular. **Solo puedes llamar a `input` en inicializadores de propiedades de componentes y directivas.** Al extender una clase de componente, **los inputs son heredados por la clase hija.** **Los nombres de input distinguen entre mayúsculas y minúsculas.** ## Leer inputs La función `input` devuelve un `InputSignal`. Puedes leer el valor llamando a la signal: ```ts {highlight:[5]} import {Component, input, computed} from '@angular/core'; @Component({/*...*/}) export class CustomSlider { // Declara un input llamado 'value' con un valor predeterminado de cero. value = input(0); // Crea una expresión computed que lee el input value label = computed(() => `El valor del slider es ${this.value()}`); } ``` Las signals creadas por la función `input` son de solo lectura. ## Inputs requeridos Puedes declarar que un input es `required` llamando a `input.required` en lugar de `input`: ```ts {highlight:[3]} @Component({/*...*/}) export class CustomSlider { // Declara un input requerido llamado value. Devuelve un `InputSignal<number>`. value = input.required<number>(); } ``` Angular exige que los inputs requeridos _deben_ establecerse cuando el componente se usa en una plantilla. Si intentas usar un componente sin especificar todos sus inputs requeridos, Angular reporta un error en tiempo de compilación. Los inputs requeridos no incluyen automáticamente `undefined` en el parámetro genérico del `InputSignal` devuelto. ## Configurar inputs La función `input` acepta un objeto de configuración como segundo parámetro que te permite cambiar la forma en que funciona el input. ### Transformaciones de input Puedes especificar una función `transform` para cambiar el valor de un input cuando es establecido por Angular. ```ts {highlight:[6]} @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" /> ``` En el ejemplo anterior, cada vez que el valor de `systemVolume` cambia, Angular ejecuta `trimString` y establece `label` con el resultado. El caso de uso más común para las transformaciones de input es aceptar un rango más amplio de tipos de valor en las plantillas, frecuentemente incluyendo `null` y `undefined`. **La función de transformación de input debe ser analizable estáticamente en tiempo de compilación.** No puedes establecer funciones de transformación condicionalmente o como resultado de una evaluación de expresión. **Las funciones de transformación de input siempre deben ser [funciones puras](https://en.wikipedia.org/wiki/Pure_function).** Depender de estado fuera de la función de transformación puede llevar a comportamiento impredecible. #### Verificación de tipos Cuando especificas una transformación de input, el tipo del parámetro de la función de transformación determina los tipos de valores que se pueden establecer al input en una plantilla. ```ts @Component({/*...*/}) export class CustomSlider { widthPx = input('', {transform: appendPx}); } function appendPx(value: number): string { return `${value}px`; } ``` En el ejemplo anterior, el input `widthPx` acepta un `number` mientras que la propiedad `InputSignal` devuelve un `string`. #### Transformaciones integradas Angular incluye dos funciones de transformación integradas para los dos escenarios más comunes: convertir valores a booleano y números. ```ts import {Component, input, booleanAttribute, numberAttribute} from '@angular/core'; @Component({/*...*/}) export class CustomSlider { disabled = input(false, {transform: booleanAttribute}); value = input(0, {transform: numberAttribute}); } ``` `booleanAttribute` imita el comportamiento de los [atributos booleanos](https://developer.mozilla.org/docs/Glossary/Boolean/HTML) estándar de HTML, donde la _presencia_ del atributo indica un valor "true". Sin embargo, el `booleanAttribute` de Angular trata la cadena literal `"false"` como el booleano `false`. `numberAttribute` intenta parsear el valor dado a un número, produciendo `NaN` si el parseo falla. ### Alias de input Puedes especificar la opción `alias` para cambiar el nombre de un input en las plantillas. ```ts {highlight:[3]} @Component({/*...*/}) export class CustomSlider { value = input(0, {alias: 'sliderValue'}); } ``` ```html <custom-slider [sliderValue]="50" /> ``` Este alias no afecta el uso de la propiedad en código TypeScript. Aunque generalmente debes evitar usar alias para inputs de componentes, esta característica puede ser útil para renombrar propiedades mientras se preserva un alias para el nombre original o para evitar colisiones con el nombre de propiedades de elementos DOM nativos. ## Model inputs Los **model inputs** son un tipo especial de input que permiten a un componente propagar nuevos valores de vuelta a su componente padre. Al crear un componente, puedes definir un model input de manera similar a como creas un input estándar. Ambos tipos de input permiten a alguien enlazar un valor a la propiedad. Sin embargo, **los model inputs permiten al autor del componente escribir valores en la propiedad**. Si la propiedad está enlazada con un enlace bidireccional, el nuevo valor se propaga a ese enlace. ```ts @Component({ /* ... */}) export class CustomSlider { // Define un model input llamado "value". value = model(0); increment() { // Actualiza el model input con un nuevo valor, propagando el valor a cualquier enlace. this.value.update(oldValue => oldValue + 10); } } @Component({ /* ... */ // Usar la sintaxis de enlace bidireccional significa que cualquier cambio al valor del slider // se propaga automáticamente de vuelta a la signal `volume`. // Nota que este enlace usa la *instancia* de la signal, no el valor de la signal. template: `<custom-slider [(value)]="volume" />`, }) export class MediaControls { // Crea una signal escribible para el estado local `volume`. volume = signal(0); } ``` En el ejemplo anterior, `CustomSlider` puede escribir valores en su model input `value`, que luego propaga esos valores de vuelta a la signal `volume` en `MediaControls`. Este enlace mantiene los valores de `value` y `volume` sincronizados. Nota que el enlace pasa la instancia de la signal `volume`, no el _valor_ de la signal. En otros aspectos, los model inputs funcionan de manera similar a los inputs estándar. Puedes leer el valor llamando a la función de signal, incluyendo en contextos reactivos como `computed` y `effect`. Consulta [Enlace bidireccional](guide/templates/two-way-binding) para más detalles sobre el enlace bidireccional en plantillas. ### Enlace bidireccional con propiedades planas Puedes enlazar una propiedad JavaScript plana a un model input. ```typescript @Component({ /* ... */ // `value` es un model input. // La sintaxis de paréntesis dentro de corchetes (también conocida como "banana-in-a-box") crea un enlace bidireccional template: '<custom-slider [(value)]="volume" />', }) export class MediaControls { protected volume = 0; } ``` En el ejemplo anterior, `CustomSlider` puede escribir valores en su model input `value`, que luego propaga esos valores de vuelta a la propiedad `volume` en `MediaControls`. Este enlace mantiene los valores de `value` y `volume` sincronizados. ### Eventos `change` implícitos Cuando declaras un model input en un componente o directiva, Angular crea automáticamente un [output](guide/components/outputs) correspondiente para ese model. El nombre del output es el nombre del model input con el sufijo "Change". ```ts @Directive({ /* ... */ }) export class CustomCheckbox { // Esto crea automáticamente un output llamado "checkedChange". // Se puede suscribir usando `(checkedChange)="handler()"` en la plantilla. checked = model(false); } ``` Angular emite este evento de cambio cada vez que escribes un nuevo valor en el model input llamando a sus métodos `set` o `update`. Consulta [Eventos personalizados con outputs](guide/components/outputs) para más detalles sobre outputs. ### Personalizar model inputs Puedes marcar un model input como requerido o proporcionar un alias de la misma manera que un [input estándar](guide/signals/inputs). Los model inputs no admiten transformaciones de input. ### Cuándo usar model inputs Usa model inputs cuando quieras que un componente admita enlace bidireccional. Esto es típicamente apropiado cuando un componente existe para modificar un valor basado en la interacción del usuario. Más comúnmente, los controles de formulario personalizados, como un selector de fecha o combobox, deben usar model inputs para su valor principal. ## Elegir nombres de input Evita elegir nombres de input que colisionen con propiedades en elementos DOM como HTMLElement. Las colisiones de nombres introducen confusión sobre si la propiedad enlazada pertenece al componente o al elemento DOM. Evita agregar prefijos para inputs de componentes como lo harías con selectores de componentes. Dado que un elemento dado solo puede alojar un componente, se puede asumir que cualquier propiedad personalizada pertenece al componente. ## Declarar inputs con el decorador `@Input` CONSEJO: Aunque el equipo de Angular recomienda usar la función `input` basada en signals para proyectos nuevos, la API original basada en decoradores `@Input` sigue siendo completamente compatible. Alternativamente puedes declarar inputs de componente agregando el decorador `@Input` a una propiedad: ```ts {highlight:[3]} @Component({...}) export class CustomSlider { @Input() value = 0; } ``` Enlazar a un input es lo mismo tanto en inputs basados en signals como en inputs basados en decoradores: ```html <custom-slider [value]="50" /> ``` ### Personalizar inputs basados en decoradores El decorador `@Input` acepta un objeto de configuración que te permite cambiar la forma en que funciona el input. #### Inputs requeridos Puedes especificar la opción `required` para exigir que un input dado siempre tenga un valor. ```ts {highlight:[3]} @Component({...}) export class CustomSlider { @Input({required: true}) value = 0; } ``` Si intentas usar un componente sin especificar todos sus inputs requeridos, Angular reporta un error en tiempo de compilación. #### Transformaciones de input Puedes especificar una función `transform` para cambiar el valor de un input cuando es establecido por Angular. Esta función de transformación funciona de manera idéntica a las funciones de transformación para inputs basados en signals descritas anteriormente. ```ts {highlight:[6]} @Component({ selector: 'custom-slider', ... }) export class CustomSlider { @Input({transform: trimString}) label = ''; } function trimString(value: string | undefined) { return value?.trim() ?? ''; } ``` #### Alias de input Puedes especificar la opción `alias` para cambiar el nombre de un input en las plantillas. ```ts {highlight:[3]} @Component({...}) export class CustomSlider { @Input({alias: 'sliderValue'}) value = 0; } ``` ```html <custom-slider [sliderValue]="50" /> ``` El decorador `@Input` también acepta el alias como su primer parámetro en lugar del objeto de configuración. Los alias de input funcionan de la misma manera que para inputs basados en signals descritos anteriormente. ### Inputs con getters y setters Cuando usas inputs basados en decoradores, una propiedad implementada con un getter y setter puede ser un input: ```ts export class CustomSlider { @Input() get value(): number { return this.internalValue; } set value(newValue: number) { this.internalValue = newValue; } private internalValue = 0; } ``` Incluso puedes crear un input _de solo escritura_ definiendo solo un setter público: ```ts export class CustomSlider { @Input() set value(newValue: number) { this.internalValue = newValue; } private internalValue = 0; } ``` **Prefiere usar transformaciones de input en lugar de getters y setters** si es posible. Evita getters y setters complejos o costosos. Angular puede invocar el setter de un input múltiples veces, lo que puede impactar negativamente el rendimiento de la aplicación si el setter realiza comportamientos costosos, como manipulación del DOM. ## Especificar inputs en el decorador `@Component` Además del decorador `@Input`, también puedes especificar los inputs de un componente con la propiedad `inputs` en el decorador `@Component`. Esto puede ser útil cuando un componente hereda una propiedad de una clase base: ```ts {highlight:[4]} // `CustomSlider` hereda la propiedad `disabled` de `BaseSlider`. @Component({ ..., inputs: ['disabled'], }) export class CustomSlider extends BaseSlider { } ``` Además puedes especificar un alias de input en la lista `inputs` poniendo el alias después de dos puntos en la cadena: ```ts {highlight:[4]} // `CustomSlider` hereda la propiedad `disabled` de `BaseSlider`. @Component({ ..., inputs: ['disabled: sliderDisabled'], }) export class CustomSlider extends BaseSlider { } ``` # Eventos personalizados con outputs CONSEJO: Esta guía asume que ya has leído la [Guía de Esenciales](essentials). Lee esa primero si eres nuevo en Angular. Los componentes de Angular pueden definir eventos personalizados asignando una propiedad a la función `output`: ```ts {highlight:[3]} @Component({/*...*/}) export class ExpandablePanel { panelClosed = output<void>(); } ``` ```html <expandable-panel (panelClosed)="savePanelState()" /> ``` La función `output` devuelve un `OutputEmitterRef`. Puedes emitir un evento llamando al método `emit` en el `OutputEmitterRef`: ```ts this.panelClosed.emit(); ``` Angular se refiere a las propiedades inicializadas con la función `output` como **outputs**. Puedes usar outputs para generar eventos personalizados, similares a los eventos nativos del navegador como `click`. **Los eventos personalizados de Angular no propagan hacia arriba en el DOM**. **Los nombres de output distinguen entre mayúsculas y minúsculas.** Al extender una clase de componente, **los outputs son heredados por la clase hija.** La función `output` tiene un significado especial para el compilador de Angular. **Solo puedes llamar a `output` en inicializadores de propiedades de componentes y directivas.** ## Emitir datos del evento Puedes pasar datos del evento al llamar a `emit`: ```ts // Puedes emitir valores primitivos. this.valueChanged.emit(7); // Puedes emitir objetos de evento personalizados this.thumbDropped.emit({ pointerX: 123, pointerY: 456, }) ``` Al definir un event listener en una plantilla, puedes acceder a los datos del evento desde la variable `$event`: ```html <custom-slider (valueChanged)="logValue($event)" /> ``` Recibe los datos del evento en el componente padre: ```ts @Component({ /*...*/ }) export class App { logValue(value: number) { ... } } ``` ## Personalizar nombres de output La función `output` acepta un parámetro que te permite especificar un nombre diferente para el evento en una plantilla: ```ts @Component({/*...*/}) export class CustomSlider { changed = output({alias: 'valueChanged'}); } ``` ```html <custom-slider (valueChanged)="saveVolume()" /> ``` Este alias no afecta el uso de la propiedad en código TypeScript. Aunque generalmente debes evitar usar alias para outputs de componentes, esta característica puede ser útil para renombrar propiedades mientras se preserva un alias para el nombre original o para evitar colisiones con el nombre de eventos DOM nativos. ## Suscribirse a outputs programáticamente Al crear un componente dinámicamente, puedes suscribirte programáticamente a eventos de output desde la instancia del componente. El tipo `OutputRef` incluye un método `subscribe`: ```ts const someComponentRef: ComponentRef<SomeComponent> = viewContainerRef.createComponent(/*...*/); someComponentRef.instance.someEventProperty.subscribe(eventData => { console.log(eventData); }); ``` Angular limpia automáticamente las suscripciones de eventos cuando destruye componentes con suscriptores. Alternativamente, puedes cancelar manualmente la suscripción a un evento. La función `subscribe` devuelve un `OutputRefSubscription` con un método `unsubscribe`: ```ts const eventSubscription = someComponent.someEventProperty.subscribe(eventData => { console.log(eventData); }); // ... eventSubscription.unsubscribe(); ``` ## Elegir nombres de eventos Evita elegir nombres de output que colisionen con eventos en elementos DOM como HTMLElement. Las colisiones de nombres introducen confusión sobre si la propiedad enlazada pertenece al componente o al elemento DOM. Evita agregar prefijos para outputs de componentes como lo harías con selectores de componentes. Dado que un elemento dado solo puede alojar un componente, se puede asumir que cualquier propiedad personalizada pertenece al componente. Siempre usa [camelCase](https://en.wikipedia.org/wiki/Camel_case) para nombres de output. Evita prefijar nombres de output con "on". ## Usar outputs con RxJS Consulta [Interoperabilidad de RxJS con outputs de componentes y directivas](ecosystem/rxjs-interop/output-interop) para detalles sobre la interoperabilidad entre outputs y RxJS. ## Declarar outputs con el decorador `@Output` CONSEJO: Aunque el equipo de Angular recomienda usar la función `output` para proyectos nuevos, la API original basada en decoradores `@Output` sigue siendo completamente compatible. Alternativamente puedes definir eventos personalizados asignando una propiedad a un nuevo `EventEmitter` y agregando el decorador `@Output`: ```ts @Component({/*...*/}) export class ExpandablePanel { @Output() panelClosed = new EventEmitter<void>(); } ``` Puedes emitir un evento llamando al método `emit` en el `EventEmitter`. ### Alias con el decorador `@Output` El decorador `@Output` acepta un parámetro que te permite especificar un nombre diferente para el evento en una plantilla: ```ts @Component({/*...*/}) export class CustomSlider { @Output('valueChanged') changed = new EventEmitter<number>(); } ``` ```html <custom-slider (valueChanged)="saveVolume()" /> ``` Este alias no afecta el uso de la propiedad en código TypeScript. ## Especificar outputs en el decorador `@Component` Además del decorador `@Output`, también puedes especificar los outputs de un componente con la propiedad `outputs` en el decorador `@Component`. Esto puede ser útil cuando un componente hereda una propiedad de una clase base: ```ts // `CustomSlider` hereda la propiedad `valueChanged` de `BaseSlider`. @Component({ /*...*/ outputs: ['valueChanged'], }) export class CustomSlider extends BaseSlider {} ``` Además puedes especificar un alias de output en la lista `outputs` poniendo el alias después de dos puntos en la cadena: ```ts // `CustomSlider` hereda la propiedad `valueChanged` de `BaseSlider`. @Component({ /*...*/ outputs: ['valueChanged: volumeChanged'], }) export class CustomSlider extends BaseSlider {} ``` # Proyección de contenido con ng-content CONSEJO: Esta guía asume que ya has leído la [Guía de Esenciales](essentials). Lee esa primero si eres nuevo en Angular. Frecuentemente necesitas crear componentes que actúen como contenedores para diferentes tipos de contenido. Por ejemplo, puedes querer crear un componente de tarjeta personalizado: ```typescript @Component({ selector: 'custom-card', template: '<div class="card-shadow"> <!-- el contenido de la tarjeta va aquí --> </div>', }) export class CustomCard {/* ... */} ``` **Puedes usar el elemento `<ng-content>` como marcador de posición para indicar dónde debe ir el contenido**: ```typescript @Component({ selector: 'custom-card', template: '<div class="card-shadow"> <ng-content/> </div>', }) export class CustomCard {/* ... */} ``` CONSEJO: `<ng-content>` funciona de manera similar al [elemento nativo `<slot>`](https://developer.mozilla.org/es/docs/Web/HTML/Reference/Elements/slot), pero con alguna funcionalidad específica de Angular. Cuando usas un componente con `<ng-content>`, cualquier hijo del elemento host del componente se renderiza, o **proyecta**, en la ubicación de ese `<ng-content>`: ```typescript // Código fuente del componente @Component({ selector: 'custom-card', template: ` <div class="card-shadow"> <ng-content /> </div> `, }) export class CustomCard {/* ... */} ``` ```html <!-- Usando el componente --> <custom-card> <p>Este es el contenido proyectado</p> </custom-card> ``` ```html <!-- El DOM renderizado --> <custom-card> <div class="card-shadow"> <p>Este es el contenido proyectado</p> </div> </custom-card> ``` Angular se refiere a cualquier hijo de un componente pasado de esta manera como el **contenido** de ese componente. Esto es distinto de la **vista** del componente, que se refiere a los elementos definidos en la plantilla del componente. **El elemento `<ng-content>` no es ni un componente ni un elemento DOM**. En su lugar, es un marcador de posición especial que le dice a Angular dónde renderizar el contenido. El compilador de Angular procesa todos los elementos `<ng-content>` en tiempo de compilación. No puedes insertar, eliminar o modificar `<ng-content>` en tiempo de ejecución. No puedes agregar directivas, estilos o atributos arbitrarios a `<ng-content>`. IMPORTANTE: No debes incluir condicionalmente `<ng-content>` con `@if`, `@for` o `@switch`. Angular siempre instancia y crea nodos DOM para el contenido renderizado en un marcador de posición `<ng-content>`, incluso si ese marcador de posición `<ng-content>` está oculto. Para renderizado condicional del contenido del componente, consulta [Fragmentos de plantilla](api/core/ng-template). ## Múltiples marcadores de posición de contenido Angular admite proyectar múltiples elementos diferentes en diferentes marcadores de posición `<ng-content>` basándose en selectores CSS. Expandiendo el ejemplo de la tarjeta de arriba, podrías crear dos marcadores de posición para un título de tarjeta y un cuerpo de tarjeta usando el atributo `select`: ```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 <!-- Plantilla del componente --> 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 <!-- Usando el componente --> @Component({ selector: 'app-root', imports: [CustomCard, CardTitle, CardBody], template: ` <custom-card> <card-title>Hola</card-title> <card-body>Bienvenido al ejemplo</card-body> </custom-card> `, }) export class App {} ``` ```html <!-- DOM renderizado --> <custom-card> <div class="card-shadow"> <card-title>Hola</card-title> <div class="card-divider"></div> <card-body>Bienvenido al ejemplo</card-body> </div> </custom-card> ``` El marcador de posición `<ng-content>` admite los mismos selectores CSS que los [selectores de componentes](guide/components/selectors). Si incluyes uno o más marcadores de posición `<ng-content>` con un atributo `select` y un marcador de posición `<ng-content>` sin un atributo `select`, el último captura todos los elementos que no coincidieron con un atributo `select`: ```html <!-- Plantilla del componente --> <div class="card-shadow"> <ng-content select="card-title"></ng-content> <div class="card-divider"></div> <!-- captura cualquier cosa excepto "card-title" --> <ng-content></ng-content> </div> ``` ```html <!-- Usando el componente --> <custom-card> <card-title>Hola</card-title> <img src="..." /> <p>Bienvenido al ejemplo</p> </custom-card> ``` ```html <!-- DOM renderizado --> <custom-card> <div class="card-shadow"> <card-title>Hola</card-title> <div class="card-divider"></div> <img src="..." /> <p>Bienvenido al ejemplo</p> </div> </custom-card> ``` Si un componente no incluye un marcador de posición `<ng-content>` sin un atributo `select`, cualquier elemento que no coincida con uno de los marcadores de posición del componente no se renderiza en el DOM. ## Contenido de respaldo Angular puede mostrar _contenido de respaldo_ para el marcador de posición `<ng-content>` de un componente si ese componente no tiene ningún contenido hijo coincidente. Puedes especificar contenido de respaldo agregando contenido hijo al propio elemento `<ng-content>`. ```html <!-- Plantilla del componente --> <div class="card-shadow"> <ng-content select="card-title">Título predeterminado</ng-content> <div class="card-divider"></div> <ng-content select="card-body">Cuerpo predeterminado</ng-content> </div> ``` ```html <!-- Usando el componente --> <custom-card> <card-title>Hola</card-title> <!-- No se proporcionó card-body --> </custom-card> ``` ```html <!-- DOM renderizado --> <custom-card> <div class="card-shadow"> <card-title>Hola</card-title> <div class="card-divider"></div> Cuerpo predeterminado </div> </custom-card> ``` ## Alias de contenido para proyección Angular admite un atributo especial, `ngProjectAs`, que te permite especificar un selector CSS en cualquier elemento. Siempre que un elemento con `ngProjectAs` se compara contra un marcador de posición `<ng-content>`, Angular compara contra el valor de `ngProjectAs` en lugar de la identidad del elemento: ```html <!-- Plantilla del componente --> <div class="card-shadow"> <ng-content select="card-title"></ng-content> <div class="card-divider"></div> <ng-content></ng-content> </div> ``` ```html <!-- Usando el componente --> <custom-card> <h3 ngProjectAs="card-title">Hola</h3> <p>Bienvenido al ejemplo</p> </custom-card> ``` ```html <!-- DOM renderizado --> <custom-card> <div class="card-shadow"> <h3>Hola</h3> <div class="card-divider"></div> <p>Bienvenido al ejemplo</p> </div> </custom-card> ``` `ngProjectAs` solo admite valores estáticos y no se puede enlazar a expresiones dinámicas. # Ciclo de vida del componente CONSEJO: Esta guía asume que ya has leído la [Guía de Esenciales](essentials). Lee esa primero si eres nuevo en Angular. El **ciclo de vida** de un componente es la secuencia de pasos que ocurren entre la creación del componente y su destrucción. Cada paso representa una parte diferente del proceso de Angular para renderizar componentes y verificar actualizaciones a lo largo del tiempo. En tus componentes, puedes implementar **hooks de ciclo de vida** para ejecutar código durante estos pasos. Los hooks de ciclo de vida que se relacionan con una instancia específica de componente se implementan como métodos en tu clase de componente. Los hooks de ciclo de vida que se relacionan con la aplicación Angular en su conjunto se implementan como funciones que aceptan un callback. El ciclo de vida de un componente está estrechamente conectado con cómo Angular verifica los cambios en tus componentes a lo largo del tiempo. Para entender este ciclo de vida, solo necesitas saber que Angular recorre tu árbol de aplicación de arriba hacia abajo, verificando los enlaces de plantilla en busca de cambios. Los hooks de ciclo de vida descritos a continuación se ejecutan mientras Angular realiza este recorrido. Este recorrido visita cada componente exactamente una vez, por lo que siempre debes evitar hacer más cambios de estado en medio del proceso. ## Resumen <div class="docs-table docs-scroll-track-transparent"> <table> <tr> <td><strong>Fase</strong></td> <td><strong>Método</strong></td> <td><strong>Resumen</strong></td> </tr> <tr> <td>Creación</td> <td><code>constructor</code></td> <td> <a href="https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Classes/constructor" target="_blank"> Constructor de clase JavaScript estándar </a>. Se ejecuta cuando Angular instancia el componente. </td> </tr> <tr> <td rowspan="7">Detección de<p>cambios</td> <td><code>ngOnInit</code> </td> <td>Se ejecuta una vez después de que Angular ha inicializado todos los inputs del componente.</td> </tr> <tr> <td><code>ngOnChanges</code></td> <td>Se ejecuta cada vez que los inputs del componente han cambiado.</td> </tr> <tr> <td><code>ngDoCheck</code></td> <td>Se ejecuta cada vez que este componente es verificado en busca de cambios.</td> </tr> <tr> <td><code>ngAfterContentInit</code></td> <td>Se ejecuta una vez después de que el <em>contenido</em> del componente ha sido inicializado.</td> </tr> <tr> <td><code>ngAfterContentChecked</code></td> <td>Se ejecuta cada vez que el contenido de este componente ha sido verificado en busca de cambios.</td> </tr> <tr> <td><code>ngAfterViewInit</code></td> <td>Se ejecuta una vez después de que la <em>vista</em> del componente ha sido inicializada.</td> </tr> <tr> <td><code>ngAfterViewChecked</code></td> <td>Se ejecuta cada vez que la vista del componente ha sido verificada en busca de cambios.</td> </tr> <tr> <td rowspan="2">Renderizado</td> <td><code>afterNextRender</code></td> <td>Se ejecuta una vez la próxima vez que <strong>todos</strong> los componentes han sido renderizados en el DOM.</td> </tr> <tr> <td><code>afterEveryRender</code></td> <td>Se ejecuta cada vez que <strong>todos</strong> los componentes han sido renderizados en el DOM.</td> </tr> <tr> <td>Destrucción</td> <td><code>ngOnDestroy</code></td> <td>Se ejecuta una vez antes de que el componente sea destruido.</td> </tr> </table> </div> ### ngOnInit El método `ngOnInit` se ejecuta después de que Angular ha inicializado todos los inputs del componente con sus valores iniciales. El `ngOnInit` de un componente se ejecuta exactamente una vez. Este paso ocurre _antes_ de que la propia plantilla del componente sea inicializada. Esto significa que puedes actualizar el estado del componente basándote en sus valores de input iniciales. ### ngOnChanges El método `ngOnChanges` se ejecuta después de que cualquier input del componente ha cambiado. Este paso ocurre _antes_ de que la propia plantilla del componente sea verificada. Esto significa que puedes actualizar el estado del componente basándote en sus valores de input iniciales. Durante la inicialización, el primer `ngOnChanges` se ejecuta antes de `ngOnInit`. #### Inspeccionar cambios El método `ngOnChanges` acepta un argumento `SimpleChanges`. Este objeto es un [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) que mapea cada nombre de input del componente a un objeto `SimpleChange`. Cada `SimpleChange` contiene el valor anterior del input, su valor actual, y una bandera que indica si esta es la primera vez que el input ha cambiado. Opcionalmente puedes pasar la clase actual o this como el primer argumento genérico para una verificación de tipos más fuerte. ```ts @Component({ /* ... */ }) export class UserProfile { name = input(''); ngOnChanges(changes: SimpleChanges<UserProfile>) { if (changes.name) { console.log(`Anterior: ${changes.name.previousValue}`); console.log(`Actual: ${changes.name.currentValue}`); console.log(`Es el primero: ${changes.name.firstChange}`); } } } ``` Si proporcionas un `alias` para cualquier propiedad de input, el Record `SimpleChanges` todavía usa el nombre de la propiedad TypeScript como clave, en lugar del alias. ### ngOnDestroy El método `ngOnDestroy` se ejecuta una vez justo antes de que un componente sea destruido. Angular destruye un componente cuando ya no se muestra en la página, como cuando es ocultado por `@if` o al navegar a otra página. #### DestroyRef Como alternativa al método `ngOnDestroy`, puedes inyectar una instancia de `DestroyRef`. Puedes registrar un callback para ser invocado en la destrucción del componente llamando al método `onDestroy` de `DestroyRef`. ```ts @Component({ /* ... */ }) export class UserProfile { constructor() { inject(DestroyRef).onDestroy(() => { console.log('Destrucción de UserProfile'); }); } } ``` Puedes pasar la instancia de `DestroyRef` a funciones o clases fuera de tu componente. Usa este patrón si tienes otro código que debe ejecutar algún comportamiento de limpieza cuando el componente es destruido. También puedes usar `DestroyRef` para mantener el código de configuración cerca del código de limpieza, en lugar de poner todo el código de limpieza en el método `ngOnDestroy`. ##### Detectar destrucción de instancia `DestroyRef` proporciona una propiedad `destroyed` que permite verificar si una instancia dada ya ha sido destruida. Esto es útil para evitar operaciones en componentes destruidos, especialmente cuando se trata de lógica retrasada o asíncrona. Al verificar `destroyRef.destroyed`, puedes prevenir la ejecución de código después de que la instancia ha sido limpiada, evitando errores potenciales como `NG0911: View has already been destroyed.`. ### ngDoCheck El método `ngDoCheck` se ejecuta antes de cada vez que Angular verifica la plantilla de un componente en busca de cambios. Puedes usar este hook de ciclo de vida para verificar manualmente cambios de estado fuera de la detección normal de cambios de Angular, actualizando manualmente el estado del componente. Este método se ejecuta muy frecuentemente y puede impactar significativamente el rendimiento de tu página. Evita definir este hook siempre que sea posible, usándolo solo cuando no tengas alternativa. Durante la inicialización, el primer `ngDoCheck` se ejecuta después de `ngOnInit`. ### ngAfterContentInit El método `ngAfterContentInit` se ejecuta una vez después de que todos los hijos anidados dentro del componente (su _contenido_) han sido inicializados. Puedes usar este hook de ciclo de vida para leer los resultados de las [consultas de contenido](guide/components/queries#content-queries). Aunque puedes acceder al estado inicializado de estas consultas, intentar cambiar cualquier estado en este método resulta en un [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100) ### ngAfterContentChecked El método `ngAfterContentChecked` se ejecuta cada vez que los hijos anidados dentro del componente (su _contenido_) han sido verificados en busca de cambios. Este método se ejecuta muy frecuentemente y puede impactar significativamente el rendimiento de tu página. Evita definir este hook siempre que sea posible, usándolo solo cuando no tengas alternativa. Aunque puedes acceder al estado actualizado de las [consultas de contenido](guide/components/queries#content-queries) aquí, intentar cambiar cualquier estado en este método resulta en un [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100). ### ngAfterViewInit El método `ngAfterViewInit` se ejecuta una vez después de que todos los hijos en la plantilla del componente (su _vista_) han sido inicializados. Puedes usar este hook de ciclo de vida para leer los resultados de las [consultas de vista](guide/components/queries#view-queries). Aunque puedes acceder al estado inicializado de estas consultas, intentar cambiar cualquier estado en este método resulta en un [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100) ### ngAfterViewChecked El método `ngAfterViewChecked` se ejecuta cada vez que los hijos en la plantilla del componente (su _vista_) han sido verificados en busca de cambios. Este método se ejecuta muy frecuentemente y puede impactar significativamente el rendimiento de tu página. Evita definir este hook siempre que sea posible, usándolo solo cuando no tengas alternativa. Aunque puedes acceder al estado actualizado de las [consultas de vista](guide/components/queries#view-queries) aquí, intentar cambiar cualquier estado en este método resulta en un [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100). ### afterEveryRender y afterNextRender Las funciones `afterEveryRender` y `afterNextRender` te permiten registrar un **callback de renderizado** para ser invocado después de que Angular ha terminado de renderizar _todos los componentes_ en la página en el DOM. Estas funciones son diferentes de los otros hooks de ciclo de vida descritos en esta guía. En lugar de un método de clase, son funciones standalone que aceptan un callback. La ejecución de los callbacks de renderizado no está vinculada a ninguna instancia específica de componente, sino que es un hook a nivel de aplicación. `afterEveryRender` y `afterNextRender` deben ser llamados en un [contexto de inyección](guide/di/dependency-injection-context), típicamente el constructor de un componente. Puedes usar callbacks de renderizado para realizar operaciones manuales del DOM. Consulta [Usar APIs del DOM](guide/components/dom-apis) para orientación sobre trabajar con el DOM en Angular. Los callbacks de renderizado no se ejecutan durante el renderizado del lado del servidor o durante el pre-renderizado en tiempo de compilación. #### Fases de after\*Render Al usar `afterEveryRender` o `afterNextRender`, opcionalmente puedes dividir el trabajo en fases. La fase te da control sobre la secuenciación de operaciones del DOM, permitiéndote secuenciar operaciones de _escritura_ antes de operaciones de _lectura_ para minimizar el [layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing). Para comunicarse entre fases, una función de fase puede devolver un valor de resultado que puede ser accedido en la siguiente fase. ```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({ // Usa la fase `Write` para escribir a una propiedad geométrica. write: () => { const padding = computePadding(); const changed = padding !== this.prevPadding; if (changed) { nativeElement.style.padding = padding; } return changed; // Comunica si algo cambió a la fase read. }, // Usa la fase `Read` para leer propiedades geométricas después de que todas las escrituras hayan ocurrido. read: (didWrite) => { if (didWrite) { this.elementHeight = nativeElement.getBoundingClientRect().height; } } }); } } ``` Hay cuatro fases, ejecutadas en el siguiente orden: | Fase | Descripción | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `earlyRead` | Usa esta fase para leer cualquier propiedad y estilo del DOM que afecte el layout y que sea estrictamente necesario para cálculos posteriores. Evita esta fase si es posible, prefiriendo las fases `write` y `read`. | | `write` | Usa esta fase para escribir propiedades y estilos del DOM que afecten el layout. | | `mixedReadWrite` | Fase predeterminada. Usa para cualquier operación que necesite tanto leer como escribir propiedades y estilos que afecten el layout. Evita esta fase si es posible, prefiriendo las fases explícitas `write` y `read`. | | `read` | Usa esta fase para leer cualquier propiedad del DOM que afecte el layout. | ## Interfaces de ciclo de vida Angular proporciona una interfaz TypeScript para cada método de ciclo de vida. Opcionalmente puedes importar e `implementar` estas interfaces para asegurar que tu implementación no tenga errores tipográficos o de ortografía. Cada interfaz tiene el mismo nombre que el método correspondiente sin el prefijo `ng`. Por ejemplo, la interfaz para `ngOnInit` es `OnInit`. ```ts @Component({ /* ... */ }) export class UserProfile implements OnInit { ngOnInit() { /* ... */ } } ``` ## Orden de ejecución Los siguientes diagramas muestran el orden de ejecución de los hooks de ciclo de vida de Angular. ### Durante la inicialización ```mermaid graph TD; id[constructor]-->CHANGE; subgraph CHANGE [Detección de cambios] direction TB ngOnChanges-->ngOnInit; ngOnInit-->ngDoCheck; ngDoCheck-->ngAfterContentInit; ngDoCheck-->ngAfterViewInit ngAfterContentInit-->ngAfterContentChecked ngAfterViewInit-->ngAfterViewChecked end CHANGE--Renderizado-->afterNextRender-->afterEveryRender ``` ### Actualizaciones posteriores ```mermaid graph TD; subgraph CHANGE [Detección de cambios] direction TB ngOnChanges-->ngDoCheck ngDoCheck-->ngAfterContentChecked; ngDoCheck-->ngAfterViewChecked end CHANGE--Renderizado-->afterEveryRender ``` ### Orden con directivas Cuando pones una o más directivas en el mismo elemento que un componente, ya sea en una plantilla o con la propiedad `hostDirectives`, el framework no garantiza ningún orden de un hook de ciclo de vida dado entre el componente y las directivas en un solo elemento. Nunca dependas de un orden observado, ya que esto puede cambiar en versiones posteriores de 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 UserProfile { 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 <!-- Hacer binding del atributo `role` en el elemento `<ul>` al valor de `listRole`. --> <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. # Agregar escuchadores de eventos Angular soporta definir escuchadores de eventos en un elemento en tu plantilla especificando el nombre del evento dentro de paréntesis junto con una declaración que se ejecuta cada vez que ocurre el evento. ## Escuchar eventos nativos Cuando quieres agregar escuchadores de eventos a un elemento HTML, envuelves el evento con paréntesis, `()`, lo que te permite especificar una declaración de escuchador. ```typescript @Component({ template: ` <input type="text" (keyup)="updateField()" /> `, ... }) export class AppComponent{ updateField(): void { console.log('¡Campo actualizado!'); } } ``` En este ejemplo, Angular llama a `updateField` cada vez que el elemento `<input>` emite un evento `keyup`. Puedes agregar escuchadores para cualquier evento nativo, como: `click`, `keydown`, `mouseover`, etc. Para aprender más, consulta [todos los eventos disponibles en elementos en MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element#events). ## Acceder al argumento del evento En cada escuchador de evento de plantilla, Angular proporciona una variable llamada `$event` que contiene una referencia al objeto del evento. ```typescript @Component({ template: ` <input type="text" (keyup)="updateField($event)" /> `, ... }) export class AppComponent { updateField(event: KeyboardEvent): void { console.log(`El usuario presionó: ${event.key}`); } } ``` ## Usar modificadores de teclas Cuando quieres capturar eventos de teclado específicos para una tecla específica, podrías escribir código como el siguiente: ```typescript @Component({ template: ` <input type="text" (keyup)="updateField($event)" /> `, ... }) export class AppComponent { updateField(event: KeyboardEvent): void { if (event.key === 'Enter') { console.log('El usuario presionó enter en el campo de texto.'); } } } ``` Sin embargo, dado que este es un escenario común, Angular te permite filtrar los eventos especificando una tecla específica usando el carácter de punto (`.`). Al hacerlo, el código se puede simplificar a: ```typescript @Component({ template: ` <input type="text" (keyup.enter)="updateField($event)" /> `, ... }) export class AppComponent{ updateField(event: KeyboardEvent): void { console.log('El usuario presionó enter en el campo de texto.'); } } ``` También puedes agregar modificadores de teclas adicionales: ```html <!-- Coincide con shift y enter --> <input type="text" (keyup.shift.enter)="updateField($event)" /> ``` Angular soporta los modificadores `alt`, `control`, `meta`, y `shift`. Puedes especificar la key o code que te gustaría enlazar a eventos de teclado. Los campos key y code son parte nativa del objeto de evento de teclado del navegador. Por defecto, el enlace de eventos asume que quieres usar los [valores Key para eventos de teclado](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values). Angular también te permite especificar [valores Code para eventos de teclado](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values) proporcionando un sufijo `code` integrado. ```html <!-- Coincide con alt y shift izquierdo --> <input type="text" (keydown.code.alt.shiftleft)="updateField($event)" /> ``` Esto puede ser útil para manejar eventos de teclado de manera consistente entre diferentes sistemas operativos. Por ejemplo, al usar la tecla Alt en dispositivos MacOS, la propiedad `key` reporta la tecla basada en el carácter ya modificado por la tecla Alt. Esto significa que una combinación como Alt + S reporta un valor de `key` de `'ß'`. La propiedad `code`, sin embargo, corresponde al botón físico o virtual presionado en lugar del carácter producido. ## Prevenir el comportamiento predeterminado del evento Si tu manejador de eventos debe reemplazar el comportamiento nativo del navegador, puedes usar el [método `preventDefault`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) del objeto del evento: ```typescript @Component({ template: ` <a href="#overlay" (click)="showOverlay($event)"> `, ... }) export class AppComponent{ showOverlay(event: PointerEvent): void { event.preventDefault(); console.log('¡Mostrar overlay sin actualizar la URL!'); } } ``` Si la declaración del manejador de eventos se evalúa como `false`, Angular automáticamente llama a `preventDefault()`, similar a los [atributos de manejador de eventos nativos](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes). _Siempre prefiere llamar explícitamente a `preventDefault`_, ya que este enfoque hace que la intención del código sea obvia. ## Extender el manejo de eventos El sistema de eventos de Angular es extensible mediante plugins de eventos personalizados registrados con el token de inyección `EVENT_MANAGER_PLUGINS`. ### Implementar un Event Plugin Para crear un plugin de eventos personalizado, extiende la clase `EventManagerPlugin` e implementa los métodos requeridos. ```ts import { Injectable } from '@angular/core'; import { EventManagerPlugin } from '@angular/platform-browser'; @Injectable() export class DebounceEventPlugin extends EventManagerPlugin { constructor() { super(document); } // Define qué eventos soporta este plugin override supports(eventName: string) { return /debounce/.test(eventName); } // Maneja el registro del evento override addEventListener( element: HTMLElement, eventName: string, handler: Function ) { // Analiza el evento: ej., "click.debounce.500" // event: "click", delay: 500 const [event, method , delay = 300 ] = eventName.split('.'); let timeoutId: number; const listener = (event: Event) => { clearTimeout(timeoutId); timeoutId = setTimeout(() => { handler(event); }, delay); }; element.addEventListener(event, listener); // Retorna función de limpieza return () => { clearTimeout(timeoutId); element.removeEventListener(event, listener); }; } } ``` Registra tu plugin personalizado usando el token `EVENT_MANAGER_PLUGINS` en los proveedores de tu aplicación: ```ts import { bootstrapApplication } from '@angular/platform-browser'; import { EVENT_MANAGER_PLUGINS } from '@angular/platform-browser'; import { AppComponent } from './app/app.component'; import { DebounceEventPlugin } from './debounce-event-plugin'; bootstrapApplication(AppComponent, { providers: [ { provide: EVENT_MANAGER_PLUGINS, useClass: DebounceEventPlugin, multi: true } ] }); ``` Una vez registrado, puedes usar tu sintaxis de evento personalizada en plantillas, así como con la propiedad `host`: ```typescript @Component({ template: ` <input type="text" (input.debounce.500)="onSearch($event.target.value)" placeholder="Search..." /> `, ... }) export class Search { onSearch(query: string): void { console.log('Buscando:', query); } } ``` ```ts @Component({ ..., host: { '(click.debounce.500)': 'handleDebouncedClick()', }, }) export class AwesomeCard { handleDebouncedClick(): void { console.log('¡Clic con debounce!'); } } ``` # Enlazar texto, propiedades y atributos dinámicos En Angular, un **enlace** (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. ## Renderizar texto dinámico con interpolación de texto Puedes enlazar texto dinámico en plantillas con llaves dobles, lo que le indica a Angular que es responsable de la expresión dentro y asegurar que se actualice correctamente. Esto se llama **interpolación de texto**. ```typescript @Component({ template: ` <p>Your color preference is {{ theme }}.</p> `, ... }) export class AppComponent { theme = 'dark'; } ``` En este ejemplo, cuando el fragmento se renderiza en la página, Angular reemplazará `{{ theme }}` con `dark`. ```html <!-- Salida renderizada --> <p>Your color preference is dark.</p> ``` Los enlaces que cambian con el tiempo deben leer valores de [signals](/guide/signals). Angular rastrea los signals leídos en la plantilla, y actualiza la página renderizada cuando esos valores de signals cambian. ```typescript @Component({ template: ` <!-- No necesariamente se actualiza cuando `welcomeMessage` cambia. --> <p>{{ welcomeMessage }}</p> <p>Your color preference is {{ theme() }}.</p> <!-- Siempre se actualiza cuando el valor del signal `name` cambia. --> ` ... }) export class AppComponent { welcomeMessage = "Welcome, enjoy this app that we built for you"; theme = signal('dark'); } ``` Para más detalles, consulta la [guía de Signals](/guide/signals). Continuando con el ejemplo del tema, si un usuario hace clic en un botón que actualiza el signal `theme` a `'light'` después de que se carga la página, la página se actualiza en consecuencia a: ```html <!-- Salida renderizada --> <p>Your color preference is light.</p> ``` Puedes usar interpolación de texto en cualquier lugar donde normalmente escribirías texto en HTML. Todos los valores de expresión se convierten a una cadena. Los objetos y arrays se convierten usando el método `toString` del valor. ## Enlazar propiedades y atributos dinámicos Angular soporta enlazar valores dinámicos a propiedades de objetos y atributos HTML con corchetes. Puedes enlazar a propiedades en la instancia DOM de un elemento HTML, una instancia de [componente](guide/components), o una instancia de [directiva](guide/directives). ### Propiedades de elementos nativos Cada elemento HTML tiene una representación DOM correspondiente. Por ejemplo, cada elemento HTML `<button>` corresponde a una instancia de `HTMLButtonElement` en el DOM. En Angular, usas enlaces de propiedad para establecer valores directamente a la representación DOM del elemento. ```html <!-- Enlaza la propiedad `disabled` en el objeto DOM del elemento button --> <button [disabled]="isFormValid()">Save</button> ``` En este ejemplo, cada vez que `isFormValid` cambia, Angular establece automáticamente la propiedad `disabled` de la instancia `HTMLButtonElement`. ### Propiedades de componentes y directivas Cuando un elemento es un componente de Angular, puedes usar enlaces de propiedad para establecer propiedades de entrada de componentes usando la misma sintaxis de corchetes. ```html <!-- Enlaza la propiedad `value` en la instancia del componente `MyListbox`. --> <my-listbox [value]="mySelection()" /> ``` En este ejemplo, cada vez que `mySelection` cambia, Angular establece automáticamente la propiedad `value` de la instancia `MyListbox`. También puedes enlazar a propiedades de directivas. ```html <!-- Enlaza a la propiedad `ngSrc` de la directiva `NgOptimizedImage` --> <img [ngSrc]="profilePhotoUrl()" alt="The current user's profile photo"> ``` ### Atributos Cuando necesitas establecer atributos HTML que no tienen propiedades DOM correspondientes, como atributos SVG, puedes enlazar atributos a elementos en tu plantilla con el prefijo `attr.`. ```html <!-- Enlaza el atributo `role` en el elemento `<ul>` a la propiedad `listRole` del componente. --> <ul [attr.role]="listRole()"> ``` En este ejemplo, cada vez que `listRole` cambia, Angular establece automáticamente el atributo `role` del elemento `<ul>` llamando a `setAttribute`. Si el valor de un enlace de atributo es `null`, Angular elimina el atributo llamando a `removeAttribute`. ### Interpolación de texto en propiedades y atributos También puedes usar sintaxis de interpolación de texto en propiedades y atributos usando la sintaxis de llaves dobles en lugar de corchetes alrededor del nombre de la propiedad o atributo. Cuando uses esta sintaxis, Angular trata la asignación como un enlace de propiedad. ```html <!-- Enlaza un valor a la propiedad `alt` del objeto DOM del elemento imagen. --> <img src="profile-photo.jpg" alt="Profile photo of {{ firstName() }}" > ``` ## Enlaces de clases CSS y propiedades de estilo Angular soporta funcionalidades adicionales para enlazar clases CSS y propiedades de estilo CSS a elementos. ### Clases CSS Puedes crear un enlace de clase CSS para agregar o quitar condicionalmente una clase CSS en un elemento basándose en si el valor enlazado es [truthy o falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy). ```html <!-- Cuando `isExpanded` es truthy, agrega la clase CSS `expanded`. --> <ul [class.expanded]="isExpanded()"> ``` También puedes enlazar directamente a la propiedad `class`. Angular acepta tres tipos de valor: | Descripción del valor de `class` | Tipo TypeScript | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | Una cadena que contiene una o más clases CSS separadas por espacios | `string` | | Un array de cadenas de clases CSS | `string[]` | | Un objeto donde cada nombre de propiedad es un nombre de clase CSS y cada valor correspondiente determina si esa clase se aplica al elemento, basado en su valor de 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, }); } ``` El ejemplo anterior renderiza el siguiente DOM: ```html <ul class="full-width outlined"> ... </ul> <section class="expandable elevated"> ... </section> <button class="highlighted"> ... </button> ``` Angular ignora cualquier valor de cadena que no sea un nombre de clase CSS válido. Cuando usas clases CSS estáticas, enlazando `class` directamente, y enlazando clases específicas, Angular combina inteligentemente todas las clases en el resultado renderizado. ```typescript @Component({ template: `<ul class="list" [class]="listType()" [class.expanded]="isExpanded()"> ...`, ... }) export class Listbox { listType = signal('box'); isExpanded = signal(true); } ``` En el ejemplo anterior, Angular renderiza el elemento `ul` con las tres clases CSS. ```html <ul class="list box expanded"> ``` Angular no garantiza ningún orden específico de clases CSS en los elementos renderizados. Cuando enlazas `class` a un array o un objeto, Angular compara el valor anterior con el valor actual usando el operador de triple igualdad (`===`). Debes crear una nueva instancia de objeto o array cuando modifiques estos valores para que Angular aplique cualquier actualización. Si un elemento tiene múltiples enlaces para la misma clase CSS, Angular resuelve las colisiones siguiendo su orden de precedencia de estilos. NOTA: Los enlaces de clase no soportan nombres de clase separados por espacios en una sola clave. Tampoco soportan mutaciones en objetos ya que la referencia del enlace permanece igual. Si necesitas una u otra, usa la directiva [ngClass](/api/common/NgClass). ### Propiedades de estilo CSS También puedes enlazar directamente a propiedades de estilo CSS en un elemento. ```html <!-- Establece la propiedad CSS `display` basada en la propiedad `isExpanded`. --> <section [style.display]="isExpanded() ? 'block' : 'none'"> ``` Puedes especificar además unidades para propiedades CSS que aceptan unidades. ```html <!-- Establece la propiedad CSS `height` a un valor en píxeles basado en la propiedad `sectionHeightInPixels`. --> <section [style.height.px]="sectionHeightInPixels()"> ``` También puedes establecer múltiples valores de estilo en un enlace. Angular acepta los siguientes tipos de valor: | Descripción del valor de `style` | Tipo TypeScript | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | Una cadena que contiene cero o más declaraciones CSS, como `"display: flex; margin: 8px"`. | `string` | | Un objeto donde cada nombre de propiedad es un nombre de propiedad CSS y cada valor correspondiente es el valor de esa propiedad CSS. | `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', }); } ``` El ejemplo anterior renderiza el siguiente DOM. ```html <ul style="display: flex; padding: 8px"> ... </ul> <section style="border: 1px solid black; font-weight: bold"> ... </section> ``` Cuando enlazas `style` a un objeto, Angular compara el valor anterior con el valor actual usando el operador de triple igualdad (`===`). Debes crear una nueva instancia de objeto cuando modifiques estos valores para que Angular aplique cualquier actualización. Si un elemento tiene múltiples enlaces para la misma propiedad de estilo, Angular resuelve las colisiones siguiendo su orden de precedencia de estilos. ## Atributos ARIA Angular soporta enlazar valores de cadena a atributos ARIA. ```html <button type="button" [aria-label]="actionLabel()"> {{ actionLabel() }} </button> ``` Angular escribe el valor de cadena al atributo `aria-label` del elemento y lo elimina cuando el valor enlazado es `null`. Algunas funcionalidades ARIA exponen propiedades DOM o entradas de directivas que aceptan valores estructurados (como referencias a elementos). Usa enlaces de propiedad estándar para esos casos. Consulta la [guía de accesibilidad](best-practices/a11y#aria-attributes-and-properties) para ejemplos y orientación adicional. # Flujo de control Las plantillas de Angular soportan bloques de flujo de control que te permiten mostrar, ocultar y repetir elementos condicionalmente. ## Mostrar contenido condicionalmente con `@if`, `@else-if` y `@else` El bloque `@if` muestra condicionalmente su contenido cuando su expresión de condición es truthy: ```html @if (a > b) { <p>{{a}} is greater than {{b}}</p> } ``` Si quieres mostrar contenido alternativo, puedes hacerlo proporcionando cualquier número de bloques `@else if` y un único bloque `@else`. ```html @if (a > b) { {{a}} is greater than {{b}} } @else if (b > a) { {{a}} is less than {{b}} } @else { {{a}} is equal to {{b}} } ``` ### Referenciar el resultado de la expresión condicional El condicional `@if` soporta guardar el resultado de la expresión condicional en una variable para reutilizarla dentro del bloque. ```html @if (user.profile.settings.startDate; as startDate) { {{ startDate }} } ``` Esto puede ser útil para referenciar expresiones más largas que serían más fáciles de leer y mantener dentro de la plantilla. ## Repetir contenido con el bloque `@for` El bloque `@for` recorre una colección y renderiza repetidamente el contenido de un bloque. La colección puede ser cualquier [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols) de JavaScript, pero Angular tiene optimizaciones de rendimiento adicionales para valores de `Array`. Un bucle `@for` típico se ve así: ```html @for (item of items; track item.id) { {{ item.name }} } ``` El bloque `@for` de Angular no soporta declaraciones que modifican el flujo como `continue` o `break` de JavaScript. ### ¿Por qué es importante `track` en los bloques `@for`? La expresión `track` permite a Angular mantener una relación entre tus datos y los nodos DOM en la página. Esto permite a Angular optimizar el rendimiento ejecutando las operaciones DOM mínimas necesarias cuando los datos cambian. Usar track efectivamente puede mejorar significativamente el rendimiento de renderización de tu aplicación al iterar sobre colecciones de datos. Selecciona una propiedad que identifique únicamente cada elemento en la expresión `track`. Si tu modelo de datos incluye una propiedad que identifica únicamente, comúnmente `id` o `uuid`, usa este valor. Si tus datos no incluyen un campo como este, considera seriamente agregar uno. Para colecciones estáticas que nunca cambian, puedes usar `$index` para indicarle a Angular que rastree cada elemento por su índice en la colección. Si no hay otra opción disponible, puedes especificar `identity`. Esto le indica a Angular que rastree el elemento por su identidad de referencia usando el operador de triple igualdad (`===`). Evita esta opción siempre que sea posible, ya que puede llevar a actualizaciones de renderización significativamente más lentas, ya que Angular no tiene forma de mapear qué elemento de datos corresponde a qué nodos DOM. ### Variables contextuales en bloques `@for` Dentro de los bloques `@for`, varias variables implícitas siempre están disponibles: | Variable | Significado | | -------- | -------------------------------------------------------- | | `$count` | Número de elementos en la colección iterada | | `$index` | Índice de la fila actual | | `$first` | Si la fila actual es la primera fila | | `$last` | Si la fila actual es la última fila | | `$even` | Si el índice de la fila actual es par | | `$odd` | Si el índice de la fila actual es impar | Estas variables siempre están disponibles con estos nombres, pero pueden ser renombradas mediante un segmento `let`: ```html @for (item of items; track item.id; let idx = $index, e = $even) { <p>Item #{{ idx }}: {{ item.name }}</p> } ``` El renombrado es útil al anidar bloques `@for`, permitiéndote leer variables del bloque `@for` externo desde un bloque `@for` interno. ### Proporcionar un fallback para bloques `@for` con el bloque `@empty` Opcionalmente puedes incluir una sección `@empty` inmediatamente después del contenido del bloque `@for`. El contenido del bloque `@empty` se muestra cuando no hay elementos: ```html @for (item of items; track item.name) { <li> {{ item.name }}</li> } @empty { <li> There are no items. </li> } ``` ## Mostrar contenido condicionalmente con el bloque `@switch` Aunque el bloque `@if` es excelente para la mayoría de escenarios, el bloque `@switch` proporciona una sintaxis alternativa para renderizar datos condicionalmente. Su sintaxis se asemeja mucho a la declaración `switch` de JavaScript. ```html @switch (userPermissions) { @case ('admin') { <app-admin-dashboard /> } @case ('reviewer') { <app-reviewer-dashboard /> } @case ('editor') { <app-editor-dashboard /> } @default { <app-viewer-dashboard /> } } ``` El valor de la expresión condicional se compara con la expresión case usando el operador de triple igualdad (`===`). **`@switch` no tiene fallthrough**, por lo que no necesitas un equivalente a una declaración `break` o `return` en el bloque. Opcionalmente puedes incluir un bloque `@default`. El contenido del bloque `@default` se muestra si ninguna de las expresiones case precedentes coincide con el valor del switch. Si ningún `@case` coincide con la expresión y no hay un bloque `@default`, no se muestra nada. # Variables en plantillas Angular tiene dos tipos de declaraciones de variables en plantillas: variables locales de plantilla y variables de referencia de plantilla. ## Variables locales de plantilla con `@let` La sintaxis `@let` de Angular te permite definir una variable local y reutilizarla en toda la plantilla, similar a la [sintaxis `let` de JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let). ### Usando `@let` Usa `@let` para declarar una variable cuyo valor se basa en el resultado de una expresión de plantilla. Angular mantiene automáticamente el valor de la variable actualizado con la expresión dada, similar a los [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...'; ``` Cada bloque `@let` puede declarar exactamente una variable. No puedes declarar múltiples variables en el mismo bloque con una coma. ### Referenciando el valor de `@let` Una vez que has declarado una variable con `@let`, puedes reutilizarla en la misma plantilla: ```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> } ``` ### Asignabilidad Una diferencia clave entre `@let` y el `let` de JavaScript es que `@let` no puede ser reasignado después de la declaración. Sin embargo, Angular mantiene automáticamente el valor de la variable actualizado con la expresión dada. ```html @let value = 1; <!-- Inválido - ¡Esto no funciona! --> <button (click)="value = value + 1">Increment the value</button> ``` ### Alcance de variables Las declaraciones `@let` tienen alcance a la vista actual y sus descendientes. Angular crea una nueva vista en los límites de componentes y en cualquier lugar donde una plantilla pueda contener contenido dinámico, como bloques de control de flujo, bloques `@defer`, o directivas estructurales. Dado que las declaraciones `@let` no se elevan (no son hoisted), **no pueden** ser accedidas por vistas padres o hermanas: ```html @let topLevel = value; <div> @let insideDiv = value; </div> {{topLevel}} <!-- Válido --> {{insideDiv}} <!-- Válido --> @if (condition) { {{topLevel + insideDiv}} <!-- Válido --> @let nested = value; @if (condition) { {{topLevel + insideDiv + nested}} <!-- Válido --> } } {{nested}} <!-- Error, no se eleva desde @if --> ``` ### Sintaxis completa La sintaxis `@let` está formalmente definida como: - La palabra clave `@let`. - Seguida de uno o más espacios en blanco, sin incluir nuevas líneas. - Seguida de un nombre JavaScript válido y cero o más espacios en blanco. - Seguida del símbolo = y cero o más espacios en blanco. - Seguida de una expresión Angular que puede ser multilínea. - Terminada por el símbolo `;`. ## Variables de referencia de plantilla Las variables de referencia de plantilla te dan una forma de declarar una variable que referencia un valor de un elemento en tu plantilla. Una variable de referencia de plantilla puede referirse a lo siguiente: - un elemento DOM dentro de una plantilla (incluyendo [elementos personalizados](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)) - un componente o directiva de Angular - un [TemplateRef](/api/core/TemplateRef) de un [ng-template](/api/core/ng-template) Puedes usar variables de referencia de plantilla para leer información de una parte de la plantilla en otra parte de la misma plantilla. ### Declarando una variable de referencia de plantilla Puedes declarar una variable en un elemento de una plantilla agregando un atributo que comienza con el carácter hash (`#`) seguido del nombre de la variable. ```html <!-- Crea una variable de referencia de plantilla llamada "taskInput", que referencia al HTMLInputElement. --> <input #taskInput placeholder="Enter task name"> ``` ### Asignando valores a variables de referencia de plantilla Angular asigna un valor a las variables de plantilla basándose en el elemento en el que se declara la variable. Si declaras la variable en un componente de Angular, la variable se refiere a la instancia del componente. ```html <!-- La variable `startDate` se asigna a la instancia de `MyDatepicker`. --> <my-datepicker #startDate /> ``` Si declaras la variable en un elemento `<ng-template>`, la variable se refiere a una instancia de TemplateRef que representa la plantilla. Para más información, consulta [Cómo Angular usa el asterisco, \*, sintaxis](/guide/directives/structural-directives#structural-directive-shorthand) en [Directivas estructurales](/guide/directives/structural-directives). ```html <!-- La variable `myFragment` se asigna a la instancia de `TemplateRef` correspondiente a este fragmento de plantilla. --> <ng-template #myFragment> <p>This is a template fragment</p> </ng-template> ``` Si declaras la variable en cualquier otro elemento mostrado, la variable se refiere a la instancia de `HTMLElement`. ```html <!-- La variable "taskInput" se refiere a la instancia de HTMLInputElement. --> <input #taskInput placeholder="Enter task name"> ``` #### Asignando una referencia a una directiva de Angular Las directivas de Angular pueden tener una propiedad `exportAs` que define un nombre por el cual la directiva puede ser referenciada en una plantilla: ```typescript @Directive({ selector: '[dropZone]', exportAs: 'dropZone', }) export class DropZone { /* ... */ } ``` Cuando declaras una variable de plantilla en un elemento, puedes asignar a esa variable una instancia de directiva especificando este nombre `exportAs`: ```html <!-- La variable `firstZone` se refiere a la instancia de la directiva `DropZone`. --> <section dropZone #firstZone="dropZone"> ... </section> ``` No puedes referirte a una directiva que no especifica un nombre `exportAs`. ### Usando variables de referencia de plantilla con consultas Además de usar variables de plantilla para leer valores de otra parte de la misma plantilla, también puedes usar este estilo de declaración de variable para "marcar" un elemento para [consultas de componentes y directivas](/guide/components/queries). Cuando quieres consultar por un elemento específico en una plantilla, puedes declarar una variable de plantilla en ese elemento y luego consultar por el elemento basándote en el nombre de la variable. ```html <input #description value="Original description"> ``` ```typescript @Component({ /* ... */, template: `<input #description value="Original description">`, }) export class AppComponent { // Consulta por el elemento input basándose en el nombre de la variable de plantilla. @ViewChild('description') input: ElementRef | undefined; } ``` Consulta [Referenciando hijos con consultas](/guide/components/queries) para más información sobre consultas. # Carga diferida con `@defer` Las vistas diferibles, también conocidas como bloques `@defer`, reducen el tamaño del bundle inicial de tu aplicación al diferir la carga de código que no es estrictamente necesario para la renderización inicial de una página. Esto a menudo resulta en una carga inicial más rápida y una mejora en Core Web Vitals (CWV), principalmente Largest Contentful Paint (LCP) y Time to First Byte (TTFB). Para usar esta característica, puedes envolver declarativamente una sección de tu plantilla en un bloque @defer: ```html @defer { <large-component /> } ``` El código de cualquier componente, directiva y pipe dentro del bloque `@defer` se divide en un archivo JavaScript separado y se carga solo cuando es necesario, después de que el resto de la plantilla haya sido renderizada. Las vistas diferibles soportan una variedad de triggers, opciones de precarga, y sub-bloques para la gestión de estados de placeholder, carga y error. ## ¿Qué dependencias se difieren? Los componentes, directivas, pipes y cualquier estilo CSS de componente pueden ser diferidos al cargar una aplicación. Para que las dependencias dentro de un bloque `@defer` sean diferidas, necesitan cumplir dos condiciones: 1. **Deben ser standalone.** Las dependencias no standalone no pueden ser diferidas y aún se cargan de forma eager, incluso si están dentro de bloques `@defer`. 1. **No pueden ser referenciadas fuera de los bloques `@defer` dentro del mismo archivo.** Si son referenciadas fuera del bloque `@defer` o referenciadas dentro de consultas ViewChild, las dependencias se cargarán de forma eager. Las dependencias _transitivas_ de los componentes, directivas y pipes usados en el bloque `@defer` no necesitan estrictamente ser standalone; las dependencias transitivas aún pueden ser declaradas en un `NgModule` y participar en la carga diferida. El compilador de Angular produce una declaración de [importación dinámica](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) para cada componente, directiva y pipe usado en el bloque `@defer`. El contenido principal del bloque se renderiza después de que todas las importaciones se resuelvan. Angular no garantiza ningún orden particular para estas importaciones. ## Cómo gestionar diferentes etapas de la carga diferida Los bloques `@defer` tienen varios sub-bloques para permitirte manejar elegantemente diferentes etapas en el proceso de carga diferida. ### `@defer` Este es el bloque principal que define la sección de contenido que se carga de forma lazy. No se renderiza inicialmente: el contenido diferido se carga y renderiza una vez que ocurre el [trigger](/guide/templates/defer#triggers) especificado o se cumple la condición `when`. Por defecto, un bloque `@defer` se dispara cuando el estado del navegador se vuelve [idle](/guide/templates/defer#idle). ```html @defer { <large-component /> } ``` ### Mostrar contenido de placeholder con `@placeholder` Por defecto, los bloques defer no renderizan ningún contenido antes de ser disparados. El `@placeholder` es un bloque opcional que declara qué contenido mostrar antes de que se dispare el bloque `@defer`. ```html @defer { <large-component /> } @placeholder { <p>Placeholder content</p> } ``` Aunque es opcional, ciertos triggers pueden requerir la presencia de un `@placeholder` o una [variable de referencia de plantilla](/guide/templates/variables#template-reference-variables) para funcionar. Consulta la sección [Triggers](/guide/templates/defer#triggers) para más detalles. Angular reemplaza el contenido del placeholder con el contenido principal una vez que la carga se completa. Puedes usar cualquier contenido en la sección de placeholder incluyendo HTML simple, componentes, directivas y pipes. Ten en cuenta que _las dependencias del bloque placeholder se cargan de forma eager_. El bloque `@placeholder` acepta un parámetro opcional para especificar la cantidad `minimum` de tiempo que este placeholder debería mostrarse después de que el contenido del placeholder se renderice inicialmente. ```html @defer { <large-component /> } @placeholder (minimum 500ms) { <p>Placeholder content</p> } ``` Este parámetro `minimum` se especifica en incrementos de tiempo de milisegundos (ms) o segundos (s). Puedes usar este parámetro para prevenir parpadeos rápidos del contenido del placeholder en caso de que las dependencias diferidas se obtengan rápidamente. ### Mostrar contenido de carga con `@loading` El bloque `@loading` es un bloque opcional que te permite declarar contenido que se muestra mientras las dependencias diferidas se están cargando. Reemplaza el bloque `@placeholder` una vez que se dispara la carga. ```html @defer { <large-component /> } @loading { <img alt="loading..." src="loading.gif" /> } @placeholder { <p>Placeholder content</p> } ``` Sus dependencias se cargan de forma eager (similar a `@placeholder`). El bloque `@loading` acepta dos parámetros opcionales para ayudar a prevenir parpadeos rápidos de contenido que pueden ocurrir cuando las dependencias diferidas se obtienen rápidamente: - `minimum` - la cantidad mínima de tiempo que este placeholder debería mostrarse - `after` - la cantidad de tiempo a esperar después de que comienza la carga antes de mostrar la plantilla de carga ```html @defer { <large-component /> } @loading (after 100ms; minimum 1s) { <img alt="loading..." src="loading.gif" /> } ``` Ambos parámetros se especifican en incrementos de tiempo de milisegundos (ms) o segundos (s). Además, los temporizadores para ambos parámetros comienzan inmediatamente después de que la carga ha sido disparada. ### Mostrar estado de error cuando falla la carga diferida con `@error` El bloque `@error` es un bloque opcional que se muestra si la carga diferida falla. Similar a `@placeholder` y `@loading`, las dependencias del bloque @error se cargan de forma eager. ```html @defer { <large-component /> } @error { <p>Failed to load large component.</p> } ``` ## Controlar la carga de contenido diferido con triggers Puedes especificar **triggers** que controlan cuándo Angular carga y muestra el contenido diferido. Cuando se dispara un bloque `@defer`, reemplaza el contenido del placeholder con contenido cargado de forma lazy. Se pueden definir múltiples triggers de evento separándolos con punto y coma, `;` y se evaluarán como condiciones OR. Hay dos tipos de triggers: `on` y `when`. ### `on` `on` especifica una condición para cuándo se dispara el bloque `@defer`. Los triggers disponibles son los siguientes: | Trigger | Descripción | | ----------------------------- | --------------------------------------------------------------------------------- | | [`idle`](#idle) | Se dispara cuando el navegador está en estado idle. | | [`viewport`](#viewport) | Se dispara cuando el contenido especificado entra al viewport | | [`interaction`](#interaction) | Se dispara cuando el usuario interactúa con el elemento especificado | | [`hover`](#hover) | Se dispara cuando el mouse pasa sobre el área especificada | | [`immediate`](#immediate) | Se dispara inmediatamente después de que el contenido no diferido haya terminado de renderizarse | | [`timer`](#timer) | Se dispara después de una duración específica | #### `idle` El trigger `idle` carga el contenido diferido una vez que el navegador ha alcanzado un estado idle, basado en requestIdleCallback. Este es el comportamiento predeterminado con un bloque defer. ```html <!-- @defer (on idle) es el comportamiento por defecto --> @defer { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` #### `viewport` El trigger `viewport` carga el contenido diferido cuando el contenido especificado entra al viewport usando la [Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API). El contenido observado puede ser el contenido `@placeholder` o una referencia de elemento explícita. Por defecto, el `@defer` observa que el placeholder entre al viewport. Los placeholders usados de esta manera deben tener un solo elemento raíz. ```html @defer (on viewport) { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` Alternativamente, puedes especificar una [variable de referencia de plantilla](/guide/templates/variables) en la misma plantilla que el bloque `@defer` como el elemento que se observa para entrar al viewport. Esta variable se pasa como un parámetro en el trigger viewport. ```html <div #greeting>Hello!</div> @defer (on viewport(greeting)) { <greetings-cmp /> } ``` Si quieres personalizar las opciones del `IntersectionObserver`, el trigger `viewport` soporta pasar un objeto literal. El literal soporta todas las propiedades del segundo parámetro de `IntersectionObserver`, excepto `root`. Al usar la notación de objeto literal, tienes que pasar tu trigger usando la propiedad `trigger`. ```html <div #greeting>Hello!</div> <!-- Con opciones y un trigger --> @defer (on viewport({trigger: greeting, rootMargin: '100px', threshold: 0.5})) { <greetings-cmp /> } <!-- Con opciones y un trigger implícito --> @defer (on viewport({rootMargin: '100px', threshold: 0.5})) { <greetings-cmp /> } @placeholder { <div>Implied trigger</div> } ``` #### `interaction` El trigger `interaction` carga el contenido diferido cuando el usuario interactúa con el elemento especificado a través de eventos `click` o `keydown`. Por defecto, el placeholder actúa como el elemento de interacción. Los placeholders usados de esta manera deben tener un solo elemento raíz. ```html @defer (on interaction) { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` Alternativamente, puedes especificar una [variable de referencia de plantilla](/guide/templates/variables) en la misma plantilla que el bloque `@defer` como el elemento que se observa para interacciones. Esta variable se pasa como un parámetro en el trigger viewport. ```html <div #greeting>Hello!</div> @defer (on interaction(greeting)) { <greetings-cmp /> } ``` #### `hover` El trigger `hover` carga el contenido diferido cuando el mouse ha pasado sobre el área disparada a través de los eventos `mouseover` y `focusin`. Por defecto, el placeholder actúa como el elemento de interacción. Los placeholders usados de esta manera deben tener un solo elemento raíz. ```html @defer (on hover) { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` Alternativamente, puedes especificar una [variable de referencia de plantilla](/guide/templates/variables) en la misma plantilla que el bloque `@defer` como el elemento que se observa para entrar al viewport. Esta variable se pasa como un parámetro en el trigger viewport. ```html <div #greeting>Hello!</div> @defer (on hover(greeting)) { <greetings-cmp /> } ``` #### `immediate` El trigger `immediate` carga el contenido diferido inmediatamente. Esto significa que el bloque diferido se carga tan pronto como todo el otro contenido no diferido haya terminado de renderizarse. ```html @defer (on immediate) { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` #### `timer` El trigger `timer` carga el contenido diferido después de una duración especificada. ```html @defer (on timer(500ms)) { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` El parámetro de duración debe especificarse en milisegundos (`ms`) o segundos (`s`). ### `when` El trigger `when` acepta una expresión condicional personalizada y carga el contenido diferido cuando la condición se vuelve truthy. ```html @defer (when condition) { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` Esta es una operación de una sola vez: el bloque `@defer` no vuelve al placeholder si la condición cambia a un valor falsy después de volverse truthy. ## Precargar datos con `prefetch` Además de especificar una condición que determina cuándo se muestra el contenido diferido, opcionalmente puedes especificar un **trigger de precarga**. Este trigger te permite cargar el JavaScript asociado con el bloque `@defer` antes de que se muestre el contenido diferido. La precarga habilita comportamientos más avanzados, como permitirte comenzar a precargar recursos antes de que un usuario haya visto o interactuado realmente con un bloque defer, pero podría interactuar con él pronto, haciendo que los recursos estén disponibles más rápido. Puedes especificar un trigger de precarga de manera similar al trigger principal del bloque, pero prefijado con la palabra clave `prefetch`. El trigger principal del bloque y el trigger de precarga están separados con un carácter de punto y coma (`;`). En el ejemplo a continuación, la precarga comienza cuando un navegador se vuelve idle y el contenido del bloque se renderiza solo una vez que el usuario interactúa con el placeholder. ```html @defer (on interaction; prefetch on idle) { <large-cmp /> } @placeholder { <div>Large component placeholder</div> } ``` ## Probar bloques `@defer` Angular proporciona APIs de TestBed para simplificar el proceso de probar bloques `@defer` y disparar diferentes estados durante las pruebas. Por defecto, los bloques `@defer` en las pruebas se ejecutan como un bloque defer se comportaría en una aplicación real. Si quieres avanzar manualmente a través de los estados, puedes cambiar el comportamiento del bloque defer a `Manual` en la configuración de TestBed. ```typescript it('should render a defer block in different states', async () => { // configura el comportamiento del bloque defer para iniciar en estado "pausado" para control manual. TestBed.configureTestingModule({deferBlockBehavior: DeferBlockBehavior.Manual}); @Component({ // ... template: ` @defer { <large-component /> } @placeholder { Placeholder } @loading { Loading... } ` }) class ComponentA {} // Crea el fixture del componente. const componentFixture = TestBed.createComponent(ComponentA); // Obtiene la lista de todos los fixtures de bloques defer y obtiene el primer bloque. const deferBlockFixture = (await componentFixture.getDeferBlocks())[0]; // Renderiza el estado placeholder por defecto. expect(componentFixture.nativeElement.innerHTML).toContain('Placeholder'); // Renderiza el estado loading y verifica la salida renderizada. await deferBlockFixture.render(DeferBlockState.Loading); expect(componentFixture.nativeElement.innerHTML).toContain('Loading'); // Renderiza el estado final y verifica la salida. await deferBlockFixture.render(DeferBlockState.Complete); expect(componentFixture.nativeElement.innerHTML).toContain('large works!'); }); ``` ## ¿Funciona `@defer` con `NgModule`? Los bloques `@defer` son compatibles tanto con componentes, directivas y pipes basados en standalone como en NgModule. Sin embargo, **solo los componentes, directivas y pipes standalone pueden ser diferidos**. Las dependencias basadas en NgModule no se difieren y se incluyen en el bundle cargado de forma eager. ## Compatibilidad entre bloques `@defer` y Hot Module Reload (HMR) Cuando Hot Module Replacement (HMR) está activo, todos los chunks de bloque `@defer` se obtienen de forma eager, anulando cualquier trigger configurado. Para restaurar el comportamiento de trigger estándar, debes deshabilitar HMR sirviendo tu aplicación con la bandera `--no-hmr`. ## ¿Cómo funciona `@defer` con server-side rendering (SSR) y static-site generation (SSG)? Por defecto, al renderizar una aplicación en el servidor (ya sea usando SSR o SSG), los bloques defer siempre renderizan su `@placeholder` (o nada si no se especifica un placeholder) y los triggers no se invocan. En el cliente, el contenido del `@placeholder` se hidrata y los triggers se activan. Para renderizar el contenido principal de los bloques `@defer` en el servidor (tanto SSR como SSG), puedes habilitar [la característica de Incremental Hydration](/guide/incremental-hydration) y configurar triggers `hydrate` para los bloques necesarios. ## Mejores prácticas para diferir vistas ### Evitar cargas en cascada con bloques `@defer` anidados Cuando tienes bloques `@defer` anidados, deberían tener diferentes triggers para evitar cargar simultáneamente, lo que causa peticiones en cascada y puede impactar negativamente el rendimiento de carga de la página. ### Evitar cambios de diseño Evita diferir componentes que son visibles en el viewport del usuario en la carga inicial. Hacer esto puede afectar negativamente Core Web Vitals al causar un aumento en el cumulative layout shift (CLS). En el caso de que esto sea necesario, evita los triggers `immediate`, `timer`, `viewport`, y triggers `when` personalizados que causan que el contenido se cargue durante la renderización inicial de la página. ### Mantener la accesibilidad en mente Al usar bloques `@defer`, considera el impacto en usuarios con tecnologías asistivas como lectores de pantalla. Los lectores de pantalla que se enfocan en una sección diferida leerán inicialmente el contenido del placeholder o de carga, pero pueden no anunciar cambios cuando el contenido diferido se carga. Para asegurar que los cambios de contenido diferido sean anunciados a los lectores de pantalla, puedes envolver tu bloque `@defer` en un elemento con una región live: ```html <div aria-live="polite" aria-atomic="true"> @defer (on timer(2000)) { <user-profile [user]="currentUser" /> } @placeholder { Loading user profile... } @loading { Please wait... } @error { Failed to load profile } </div> ``` Esto asegura que los cambios sean anunciados al usuario cuando ocurren transiciones (placeholder → loading → content/error). # Sintaxis de Expresiones Las expresiones de Angular están basadas en JavaScript, pero difieren en algunos aspectos clave. Esta guía recorre las similitudes y diferencias entre las expresiones de Angular y JavaScript estándar. ## Literales de valor Angular soporta un subconjunto de [valores literales](https://developer.mozilla.org/en-US/docs/Glossary/Literal) de JavaScript. ### Literales de valor soportados | Tipo de literal | Valores de ejemplo | | --------------- | ----------------------------------- | | String | `'Hello'`, `"World"` | | Boolean | `true`, `false` | | Number | `123`, `3.14` | | Object | `{name: 'Alice'}` | | Array | `['Onion', 'Cheese', 'Garlic']` | | null | `null` | | Template string | `` `Hello ${name}` `` | | RegExp | `/\d+/` | ### Literales de valor no soportados | Tipo de literal | Valores de ejemplo | | --------------- | ------------------ | | BigInt | `1n` | ## Globales Las expresiones de Angular soportan los siguientes [globales](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 se soportan otros globales de JavaScript. Los globales comunes de JavaScript incluyen `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt`, y más. ## Variables locales Angular automáticamente hace disponibles variables locales especiales para usar en expresiones en contextos específicos. Estas variables especiales siempre comienzan con el carácter de signo de dólar (`$`). Por ejemplo, los bloques `@for` hacen disponibles varias variables locales correspondientes a información sobre el bucle, como `$index`. ## ¿Qué operadores están soportados? ### Operadores soportados Angular soporta los siguientes operadores de JavaScript estándar. | Operador | Ejemplo(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` | Las expresiones de Angular también soportan adicionalmente los siguientes operadores no estándar: | Operador | Ejemplo(s) | | ----------------------------------------- | ------------------------------ | | [Pipe](/guide/templates/pipes) | `{{ total \| currency }}` | | Optional chaining\* | `someObj.someProp?.nestedProp` | | Non-null assertion (TypeScript) | `someObj!.someProp` | NOTA: El optional chaining se comporta de manera diferente a la versión estándar de JavaScript en que si el lado izquierdo del operador optional chaining de Angular es `null` o `undefined`, retorna `null` en lugar de `undefined`. ### Operadores no soportados | Operador | Ejemplo(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()` | ## Contexto léxico para expresiones Las expresiones de Angular se evalúan dentro del contexto de la clase del componente así como de cualquier [variable de plantilla](/guide/templates/variables), locales y globales relevantes. Al referirse a miembros de la clase del componente, `this` siempre está implícito. Sin embargo, si una plantilla declara una [variable de plantilla](guide/templates/variables) con el mismo nombre que un miembro, la variable oculta ese miembro. Puedes referenciar inequívocamente tal miembro de clase usando explícitamente `this.`. Esto puede ser útil al crear una declaración `@let` que oculta un miembro de clase, por ejemplo, para propósitos de estrechamiento de signals. ## Declaraciones En términos generales, las declaraciones no están soportadas en las expresiones de Angular. Esto incluye, pero no se limita a: | Declaraciones | Ejemplo(s) | | --------------- | ------------------------------------------- | | Variables | `let label = 'abc'`, `const item = 'apple'` | | Functions | `function myCustomFunction() { }` | | Arrow Functions | `() => { }` | | Classes | `class Rectangle { }` | # Declaraciones de event listeners Los manejadores de eventos son **declaraciones** en lugar de expresiones. Aunque soportan toda la misma sintaxis que las expresiones de Angular, hay dos diferencias clave: 1. Las declaraciones **sí soportan** operadores de asignación (pero no asignaciones destructivas) 1. Las declaraciones **no soportan** 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="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="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="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="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. Configura las vinculaciones de eventos del host usando la propiedad `host` en el decorador `@Directive()`. <docs-code header="src/app/highlight.directive.ts (decorador)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts" visibleRegion="decorator"/> 1. Añade dos manejadores de eventos que responden cuando el mouse entra o sale, cada uno con el decorador `@HostListener()`. <docs-code header="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 los eventos del elemento del DOM que hospeda una directiva de atributo (en este caso, el `<p>`) configurando los listeners de eventos en la [propiedad host](guide/components/host-elements#binding-to-the-host-element) de la directiva. Ú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="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. <img alt="Segundo Resaltado" src="assets/images/guide/attribute-directives/highlight-directive-anim.gif"> ## 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="highlight.directive.ts (importaciones)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="imports"/> 2. Añade una propiedad `input` `appHighlight`. <docs-code header="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. 3. En `app.component.ts`, añade una propiedad `color` al `AppComponent`. <docs-code header="app.component.ts (clase)" path="adev/src/content/examples/attribute-directives/src/app/app.component.1.ts" visibleRegion="class"/> 4. 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="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="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="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. <img alt="Gif animado de la directiva de resaltado refactorizada cambiando color según el botón de radio que selecciona el usuario" src="assets/images/guide/attribute-directives/highlight-directive-v2-anim.gif"> ## 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="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="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="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. <img alt="Gif animado de la directiva de resaltado final que muestra color rojo sin enlace y violeta con el color por defecto establecido. Cuando el usuario selecciona color, la selección toma precedencia." src="assets/images/guide/attribute-directives/highlight-directive-final-anim.gif"> ## 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="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="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 <!-- Sintaxis abreviada: --> <p class="data-view" *select="let data from source">Los datos son: {{data}}</p> <!-- Sintaxis de forma larga: --> <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 ";"? ``` | Palabra clave | Detalles | | :------------- | :--------------------------------------------------- | | `prefix` | Clave de atributo HTML | | `key` | Clave de atributo HTML | | `local` | Nombre de variable local usado en la plantilla | | `export` | Valor exportado por la directiva bajo un nombre dado | | `expression` | Expresión estándar de Angular | ### Cómo Angular traduce la sintaxis abreviada Angular translates structural directive shorthand into the normal binding syntax as follows: | Shorthand | Translation | |:------------------------------ |:------------------------------------------------------------- | | `prefix` and naked `expression` | `[prefix]="expression"` | | `keyExp` | `[prefixKey]="expression"` (The `prefix` is added to the `key`) | | `let local` | `let-local="export"` | ## 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`: ```ts import { NgOptimizedImage } from '@angular/common' ``` and include it into the `imports` array of a standalone component or an NgModule: ```ts imports: [ NgOptimizedImage, // ... ], ``` </docs-code> </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: ```html <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: ```ts 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: ```ts 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: ```ts 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"> ``` ### Controlling image decoding By default, `NgOptimizedImage` sets `decoding="auto"` for all images. This allows the browser to decide the optimal time to decode an image after it has been fetched. When an image is marked as `priority`, Angular automatically sets `decoding="sync"` to ensure the image is decoded and painted as early as possible helping improve **Largest Contentful Paint (LCP)** performance. You can still override this behavior by explicitly setting the `decoding` attribute. [See the documentation for the standard image `decoding` attribute for details](https://developer.mozilla.org/docs/Web/HTML/Element/img#decoding). ```html <!-- Default: decoding is 'auto' --> <img ngSrc="gallery/landscape.jpg" width="1200" height="800"> <!-- Decode the image asynchronously to avoid blocking the main thread.--> <img ngSrc="gallery/preview.jpg" width="600" height="400" decoding="async"> <!-- Priority images automatically use decoding="sync" --> <img ngSrc="awesome.jpg" width="500" height="625" priority > <!-- Decode immediately (can block) when you need the pixels right away --> <img ngSrc="hero.jpg" width="1600" height="900" decoding="sync"> ``` **Allowed values** - `auto` (default): lets the browser choose the optimal strategy. - `async`: decodes the image asynchronously, avoiding main‑thread blocking where possible. - `sync`: decodes the image immediately; can block rendering but ensures pixels are ready as soon as the image is available. ### 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: | Image Service | Angular API | Documentation | | :------------------------ | :------------------------ | :-------------------------------------------------------------------------- | | Cloudflare Image Resizing | `provideCloudflareLoader` | [Documentation](https://developers.cloudflare.com/images/image-resizing/) | | Cloudinary | `provideCloudinaryLoader` | [Documentation](https://cloudinary.com/documentation/resizing_and_cropping) | | ImageKit | `provideImageKitLoader` | [Documentation](https://docs.imagekit.io/) | | Imgix | `provideImgixLoader` | [Documentation](https://docs.imgix.com/) | | Netlify | `provideNetlifyLoader` | [Documentation](https://docs.netlify.com/image-cdn/overview/) | 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: ```ts 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. ```ts 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: ```ts 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: ```ts 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. <img alt="LCP in the Chrome DevTools" src="assets/images/guide/image-optimization/devtools-lcp.png"> 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. CONSEJO: 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 `computation`. ## 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). Consulta [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 petició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 mediante `.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. # 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(`Fetched ${this.heroes.length} heroes.`); 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: ```ts {header: 'heroes/hero.service.ts (CLI-generated)'} 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: ```ts {header: 'hero.service.ts'} 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`. ```ts 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: ```ts {header: 'hero-list.component.ts (constructor signature)'} 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: ```ts {header: 'hero.service.ts', highlight: [[3],[9],[12]]} 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 # 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. NOTA: Para ejemplos básicos de usar `inject()` en constructores de clase e inicializadores de campos, consulta la [guía de resumen](/guide/di#where-can-inject-be-used). ## 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` ```ts {highlight: [3]} 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: ```ts {highlight: [9], header: "hero.service.ts"} @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. ## Afirmar el contexto Angular proporciona la función auxiliar `assertInInjectionContext` para afirmar que el contexto actual es un contexto de inyección y lanza un error claro si no lo es. Pasa una referencia a la función que llama para que el mensaje de error apunte al punto de entrada de la API correcto. Esto produce un mensaje más claro y accionable que el error genérico de inyección predeterminado. ```ts import { ElementRef, assertInInjectionContext, inject } from '@angular/core'; export function injectNativeElement<T extends Element>(): T { assertInInjectionContext(injectNativeElement); return inject(ElementRef).nativeElement; } ``` Puedes llamar a esta función auxiliar **desde un contexto de inyección** (constructor, inicializador de campo, fábrica de proveedor, o código ejecutado vía `runInInjectionContext`): ```ts import { Component, inject } from '@angular/core'; import { injectNativeElement } from './dom-helpers'; @Component({ /* … */ }) export class PreviewCard { readonly hostEl = injectNativeElement<HTMLElement>(); // El inicializador de campo se ejecuta en un contexto de inyección. onAction() { const anotherRef = injectNativeElement<HTMLElement>(); // Falla: se ejecuta fuera de 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 Esta guía proporciona una cobertura en profundidad del sistema de inyección de dependencias jerárquico de Angular, incluyendo reglas de resolución, modificadores y patrones avanzados. NOTA: Para conceptos básicos sobre la jerarquía de inyectores y el alcance de proveedores, consulta la [guía de definición de proveedores de dependencias](guide/di/defining-dependency-providers#injector-hierarchy-in-angular). ## 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: ```ts {highlight:[4]} 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`: ```ts 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 `root` `ModuleInjector` 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: ```ts {highlight:[3]} @Component({ /* … */ providers: [{ provide: ItemService, useValue: { name: 'lamp' } }] }) export class TestComponent ``` ÚTIL: Consulta la sección [reglas de resolución](#reglas-de-resolución) 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](#reglas-de-resolución). 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. ```ts {header:"optional/optional.component.ts"} 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. ```ts {header: 'self-no-data.component.ts', highlight: [7]} @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}); } ``` En este ejemplo, hay un proveedor padre e inyectar el servicio devolverá el valor, sin embargo, inyectar el servicio con `self` y `optional` devolverá `null` porque `self` le dice al inyector que deje de buscar en el elemento host actual. 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>. ```ts {header:"self/self.component.ts"} @Component({ selector: 'app-self', templateUrl: './self.component.html', styleUrls: ['./self.component.css'], providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}], }) export class SelfComponent { constructor(@Self() public flower: FlowerService) {} } ``` ### `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: ```ts {header: 'leaf.service.ts'} 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`: ```ts {header:"skipself.component.ts" highlight:[[6],[10]]} @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`. ```ts class Person { parent = inject(Person, {optional: true, skipSelf: true}) } ``` ### `host` <!-- TODO: Remove ambiguity between host and self. --> `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: ```ts {header:"host.component.ts" highlight:[[6],[9]]} @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. ```ts {header:"self-no-data.component.ts" highlight:[2]} 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. | Atributo de servicio Angular | Detalles | |:----------------------------- |:--------------------------------------------------------------------------------------- | | `@Inject(Token)=>Value` | Si `Token` se inyecta en esta ubicación en el árbol lógico, su valor sería `Value`. | | `@Provide(Token=Value)` | Indica que `Token` se provee con `Value` en esta ubicación en el árbol lógico. | | `@ApplicationConfig` | Demuestra que se debe usar un `EnvironmentInjector` de respaldo en esta ubicación. | ### 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>. ```ts {header:"flower.service.ts"} @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> <!-- selector de AppComponent --> <app-child> <!-- selector de ChildComponent --> </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> <!-- selector de AppComponent --> <#VIEW> <app-child> <!-- selector de ChildComponent --> <#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`: ```typescript export class AppComponent { flower = inject(FlowerService); } ``` Agrega un enlace a la plantilla `<app-root>` para visualizar el resultado: ```html <p>Emoji de FlowerService: {{flower.emoji}}</p> ``` La salida en la vista sería: ```shell Emoji de 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: ```ts @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`. ```html <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)=>"🌻"> <!-- la búsqueda termina aquí --> <#VIEW> <!-- la búsqueda inicia aquí --> <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](#visibilidad-de-tokens-proveídos). Para demostración, estamos construyendo un `AnimalService` para demostrar `viewProviders`. Primero, crea un `AnimalService` con una propiedad `emoji` de ballena <code>🐳</code>: ```typescript 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`: ```ts 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>. ```typescript @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: ```html <p>Emoji de AnimalService: {{animal.emoji}}</p> ``` Además, agrega lo mismo a la plantilla `AppComponent`: ```html <p>Emoji de AnimalService: {{animal.emoji}}</p> ``` Ahora deberías ver ambos valores en el navegador: ```shell 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=>"🐶")> <!-- ^^usar viewProviders significa que AnimalService está disponible en <#VIEW>--> <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: ```typescript 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: ```html <p>Emoji de FlowerService: {{flower.emoji}}</p> <p>Emoji de AnimalService: {{animal.emoji}}</p> ``` Recuerda agregar el `InspectorComponent` al array `imports` de `ChildComponent`. ```ts @Component({ ... imports: [InspectorComponent] }) ``` A continuación, agrega lo siguiente a `child.component.html`: ```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. ```html <app-child> <app-inspector></app-inspector> </app-child> ``` El navegador ahora renderiza lo siguiente, omitiendo los ejemplos anteriores por brevedad: ```shell ... 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í: ```html <app-root @ApplicationConfig @Inject(AnimalService) animal=>"🐳"> <#VIEW> <app-child> <#VIEW @Provide(AnimalService="🐶") @Inject(AnimalService=>"🐶")> <!-- ^^usar viewProviders significa que AnimalService está disponible en <#VIEW>--> <p>Emoji de AnimalService: {{animal.emoji}} (🐶)</p> <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: ```shell 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)=>"🌺"> <!-- Con SkipSelf, el inyector busca en el siguiente inyector arriba en el árbol (app-root) --> </#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> <!-- la búsqueda termina aquí con null --> <app-child @Provide(FlowerService="🌻")> <!-- la búsqueda inicia aquí --> <#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><!-- la búsqueda inicia aquí --> <app-child> <#VIEW @Provide(AnimalService="🐶") @Inject(AnimalService, SkipSelf=>"🐳")> <!--Add 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}=>"🐶")> <!-- el host detiene la búsqueda aquí" --> </#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 }); } ``` <!-- TODO: This requires a rework. It seems not well explained what `viewProviders`/`injectors` is here and how `host` works. --> 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)=>"🦔"> <!-- ^^skipSelf inicia aquí, host detiene aquí^^ --> <app-child> <#VIEW @Provide(AnimalService="🐶") inject(AnimalService, {skipSelf:true, host: true, optional: true})=>"🦔"> <!-- Agregar skipSelf --> </#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í: ```typescript @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. ```typescript import {inject, 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`. ```typescript import {Component, 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. ```typescript 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: ```ts {highlight: [14]} import {Component, ContentChild} from '@angular/core'; @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`: ```ts @ContentChild(LibHeaderComponent) header: LibHeaderComponent | null; ``` - 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: ```ts {highlight: [[2],[4]]} 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`: ```ts {highlight: [[1],[5], [15]]} 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`: ```ts {highlight: [[2],[9],[11],[19]]} 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 implements 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`". # Interoperabilidad de RxJS con signals de Angular El paquete `@angular/core/rxjs-interop` ofrece APIs que te ayudan a integrar RxJS y los signals de Angular. ## Crea un signal a partir de un Observable de RxJS con `toSignal` Usa la función `toSignal` para crear un signal que rastrea el valor de un Observable. Se comporta de forma similar al pipe `async` en las plantillas, pero es más flexible y puede utilizarse en cualquier parte de la aplicación. ```typescript 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); // Obtiene un `Signal` que representa el valor de `counterObservable`. counter = toSignal(this.counterObservable, {initialValue: 0}); } ``` Al igual que el pipe `async`, `toSignal` se suscribe al Observable inmediatamente, lo cual puede desencadenar efectos secundarios. La suscripción creada por `toSignal` se da de baja automáticamente del Observable proporcionado cuando se destruye el componente o servicio que llama a `toSignal`. IMPORTANTE: `toSignal` crea una suscripción. Debes evitar llamarlo repetidamente para el mismo Observable y, en su lugar, reutilizar el signal que devuelve. ### Contexto de inyección De manera predeterminada, `toSignal` necesita ejecutarse en un [contexto de inyección](guide/di/dependency-injection-context), como durante la construcción de un componente o servicio. Si no hay un contexto de inyección disponible, puedes especificar manualmente el `Injector` que debe utilizar. ### Valores iniciales Es posible que los Observables no produzcan un valor de forma síncrona al suscribirse, pero los signals siempre requieren un valor actual. Hay varias formas de manejar este valor "inicial" de los signals de `toSignal`. #### La opción `initialValue` Como en el ejemplo anterior, puedes especificar una opción `initialValue` con el valor que el signal debe devolver antes de que el Observable emita por primera vez. #### Valores iniciales `undefined` Si no proporcionas un `initialValue`, el signal resultante devolverá `undefined` hasta que el Observable emita. Esto es similar al comportamiento del pipe `async`, que devuelve `null`. #### La opción `requireSync` Algunos Observables garantizan que emitirán de forma síncrona, por ejemplo, `BehaviorSubject`. En esos casos, puedes especificar la opción `requireSync: true`. Cuando `requireSync` es `true`, `toSignal` exige que el Observable emita de forma síncrona al suscribirse. Esto garantiza que el signal siempre tenga un valor y que no sea necesario un tipo `undefined` ni un valor inicial. ### `manualCleanup` De forma predeterminada, `toSignal` da de baja automáticamente del Observable cuando se destruye el componente o servicio que lo crea. Para reemplazar este comportamiento, puedes pasar la opción `manualCleanup`. Puedes utilizar este ajuste para Observables que se completan de forma natural. #### Comparación de igualdad personalizada Algunos Observables pueden emitir valores que son **iguales** aunque difieran por referencia o en detalles menores. La opción `equal` te permite definir una **función de igualdad personalizada** para determinar cuándo dos valores consecutivos deben considerarse iguales. Cuando dos valores emitidos se consideran iguales, el signal resultante **no se actualiza**. Esto evita cálculos redundantes, actualizaciones del DOM o efectos que se ejecuten innecesariamente. ```ts import { Component } from '@angular/core'; import { toSignal } from '@angular/core/rxjs-interop'; import { interval, map } from 'rxjs'; @Component(/* ... */) export class EqualExample { temperature$ = interval(1000).pipe( map(() => ({ temperature: Math.floor(Math.random() * 3) + 20 }) ) // 20, 21 o 22 aleatoriamente ); // Solo actualiza si la temperatura cambia temperature = toSignal(this.temperature$, { initialValue: { temperature : 20 }, equal: (prev, curr) => prev.temperature === curr.temperature }); } ``` ### Error y finalización Si un Observable usado en `toSignal` produce un error, dicho error se lanza cuando se lee el signal. Si un Observable usado en `toSignal` se completa, el signal continúa devolviendo el valor emitido más recientemente antes de completarse. ## Crea un Observable de RxJS a partir de un signal con `toObservable` Usa la utilidad `toObservable` para crear un `Observable` que rastrea el valor de un signal. El valor del signal se supervisa con un `effect` que emite el valor al Observable cuando cambia. ```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 )) ); } ``` Cuando el signal `query` cambia, el Observable `query$` emite la consulta más reciente y desencadena una nueva solicitud HTTP. ### Contexto de inyección De forma predeterminada, `toObservable` necesita ejecutarse en un [contexto de inyección](guide/di/dependency-injection-context), como durante la construcción de un componente o servicio. Si no hay un contexto de inyección disponible, puedes especificar manualmente el `Injector` que se debe utilizar. ### Sincronización de `toObservable` `toObservable` utiliza un effect para rastrear el valor del signal en un `ReplaySubject`. Al suscribirse, el primer valor (si está disponible) puede emitirse de forma síncrona y todos los valores posteriores serán asíncronos. A diferencia de los Observables, los signals nunca proporcionan una notificación síncrona de los cambios. Incluso si actualizas el valor de un signal varias veces, `toObservable` solo emitirá el valor después de que el signal se estabilice. ```ts const obs$ = toObservable(mySignal); obs$.subscribe(value => console.log(value)); mySignal.set(1); mySignal.set(2); mySignal.set(3); ``` Aquí, solo se registrará el último valor (3). ## Usar `rxResource` para datos asíncronos IMPORTANTE: `rxResource` es [experimental](reference/releases#experimental). Está listo para que lo pruebes, pero podría cambiar antes de ser estable. La [`resource` function](/guide/signals/resource) de Angular te permite incorporar datos asíncronos en el código de tu aplicación basado en signals. Sobre este patrón, `rxResource` te permite definir un recurso en el que la fuente de tus datos está definida en términos de un `Observable` de RxJS. En lugar de aceptar una función `loader`, `rxResource` acepta una función `stream` que recibe un `Observable` de RxJS. ```typescript import {Component, inject} from '@angular/core'; import {rxResource} from '@angular/core/rxjs-interop'; @Component(/* ... */) export class UserProfile { // Este componente depende de un servicio que expone datos a través de un Observable de RxJS. private userData = inject(MyUserDataClient); protected userId = input<string>(); private userResource = rxResource({ params: () => ({ userId: this.userId() }), // La propiedad `stream` espera una función factory que devuelva // un flujo de datos como un Observable de RxJS. stream: ({params}) => this.userData.load(params.userId), }); } ``` La propiedad `stream` acepta una función factory para un `Observable` de RxJS. Esta función factory recibe el valor `params` del recurso y devuelve un `Observable`. El recurso llama a esta función cada vez que el cómputo de `params` produce un valor nuevo. Consulta [Resource loaders](/guide/signals/resource#resource-loaders) para más detalles sobre los parámetros que se pasan a la función factory. En todos los demás aspectos, `rxResource` se comporta como `resource` y proporciona las mismas APIs para especificar parámetros, leer valores, comprobar el estado de carga y examinar errores. # Interoperabilidad de RxJS con outputs de componentes y directivas CONSEJO: Esta guía supone que ya estás familiarizado con los [outputs de componentes y directivas](guide/components/outputs). El paquete `@angular/rxjs-interop` ofrece dos APIs relacionadas con los outputs de componentes y directivas. ## Crear un output basado en un Observable de RxJS `outputFromObservable` te permite crear un output de componente o directiva que emite en función de un Observable de RxJS: ```ts {highlight:[9]} import {Directive} from '@angular/core'; import {outputFromObservable} from '@angular/core/rxjs-interop'; @Directive({/*...*/}) class Draggable { pointerMoves$: Observable<PointerMovements> = listenToPointerMoves(); // Cada vez que `pointerMoves$` emite, se dispara el evento `pointerMove`. pointerMove = outputFromObservable(this.pointerMoves$); } ``` La función `outputFromObservable` tiene un significado especial para el compilador de Angular. **Solo puedes llamar a `outputFromObservable` en inicializadores de propiedades de componentes y directivas.** Cuando te suscribes (`subscribe`) al output, Angular reenvía automáticamente la suscripción al Observable subyacente. Angular deja de reenviar valores cuando el componente o la directiva se destruye. ÚTIL: Considera usar `output()` directamente si puedes emitir valores de forma imperativa. ## Crear un Observable de RxJS a partir de un output de componente o directiva La función `outputToObservable` te permite crear un Observable de RxJS a partir de un output de componente. ```ts {highlight:[11]} import {outputToObservable} from '@angular/core/rxjs-interop'; @Component(/*...*/) class CustomSlider { valueChange = output<number>(); } // Referencia de instancia a `CustomSlider`. const slider: CustomSlider = createSlider(); outputToObservable(slider.valueChange) // Observable<number> .pipe(...) .subscribe(...); ``` ÚTIL: Considera usar directamente el método `subscribe` en `OutputRef` si satisface tus necesidades. # 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: Siempre 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 lista los NgModules disponibles en `@angular/common/http` y cómo se relacionan con las funciones de configuración de proveedores anteriores. | **NgModule** | `provideHttpClient()` equivalent | | --------------------------------------- | --------------------------------------------- | | `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 suscribirse, 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`. | **`Valor de responseType`** | **Tipo de respuesta devuelto** | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'json'` (por defecto) | Datos JSON del tipo genérico dado | | `'text'` | Cadena de texto (string) | | `'arraybuffer'` | [`ArrayBuffer`](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) que contiene los bytes de respuesta sin procesar | | `'blob'` | una instancia [`Blob`](https://developer.mozilla.org/es/docs/Web/API/Blob) | 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: | **Tipo de `body`** | **Serializado as** | | - | - | | string | Texto plano | | number, boolean, array, u objeto plano | JSON | | [`ArrayBuffer`](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) | datos sin procesar del buffer | | [`Blob`](https://developer.mozilla.org/es/docs/Web/API/Blob) | datos sin procesar con el tipo de contenido del `Blob` | | [`FormData`](https://developer.mozilla.org/es/docs/Web/API/FormData) | datos codificados `multipart/form-data` | | [`HttpParams`](api/common/http/HttpParams) o [`URLSearchParams`](https://developer.mozilla.org/es/docs/Web/API/URLSearchParams) | string formateado `application/x-www-form-urlencoded` | IMPORTANTE: Recuerda hacer `.subscribe()` a los `Observable`s de solicitudes de mutación para realmente ejecutar la solicitud. ## Configurando parámetros de URL 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: | **Valor de `type`** | **Significado del evento** | | - | - | | `HttpEventType.Sent` | La solicitud ha sido enviada al servidor | | `HttpEventType.UploadProgress` | Un `HttpUploadProgressEvent` reportando progreso en la carga del cuerpo de la solicitud | | `HttpEventType.ResponseHeader` | Se ha recibido el encabezado de la respuesta, incluyendo estado y encabezados | | `HttpEventType.DownloadProgress` | Un `HttpDownloadProgressEvent` que reporta el progreso de la descarga del cuerpo de la respuesta | | `HttpEventType.Response` | Se ha recibido toda la respuesta, incluyendo el cuerpo de la respuesta | | `HttpEventType.User` | Un evento personalizado de un interceptor Http. ## 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) CONSEJO: 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 CONSEJO: 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 CONSEJO: 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: true` siempre resultará en `credentials: 'include'`, sin importar el valor explícito de `credentials`. Valores disponibles 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 CONSEJO: 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 referrer (la URL de la página actual). CONSEJO: Usa `referrer: ''` para solicitudes sensibles donde no quieres filtrar la URL de la página que refirió la solicitud. #### Política de referrer La opción `referrerPolicy` controla cuánta información de referrer, la URL de la página que realiza la solicitud, se envía junto con una solicitud HTTP. Esta configuración afecta tanto la privacidad como los análisis, permitiéndote equilibrar la visibilidad de datos con consideraciones de seguridad. ```ts // No enviar información de referrer independientemente de la página actual http.get('/api/data', { referrerPolicy: 'no-referrer' }).subscribe(); // Enviar solo el origen (por ejemplo, https://example.com) http.get('/api/analytics', { referrerPolicy: 'origin' }).subscribe(); ``` La opción `referrerPolicy` acepta: - `'no-referrer'`: Nunca envía el encabezado `Referer`. - `'no-referrer-when-downgrade'`: Envía el referrer para solicitudes same-origin y seguras (HTTPS→HTTPS), pero lo omite al navegar desde un origen seguro a uno menos seguro (HTTPS→HTTP). - `'origin'`: Envía solo el origen (esquema, host, puerto) del referrer, omitiendo información de ruta y consulta. - `'origin-when-cross-origin'`: Envía la URL completa para solicitudes same-origin, pero solo el origen para solicitudes cross-origin. - `'same-origin'`: Envía la URL completa para solicitudes same-origin y ningún referrer para solicitudes cross-origin. - `'strict-origin'`: Envía solo el origen, y solo si el nivel de seguridad del protocolo no se degrada (por ejemplo, HTTPS→HTTPS). Omite el referrer en caso de degradación. - `'strict-origin-when-cross-origin'`: Comportamiento predeterminado del navegador. Envía la URL completa para solicitudes same-origin, el origen para solicitudes cross-origin cuando no hay degradación, y omite el referrer en caso de degradación. - `'unsafe-url'`: Siempre envía la URL completa (incluyendo ruta y consulta). Esto puede exponer datos sensibles y debe usarse con precaución. CONSEJO: Prefiere valores conservadores como `'no-referrer'`, `'origin'`, o `'strict-origin-when-cross-origin'` para solicitudes sensibles a la privacidad. #### 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. CONSEJO: 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-inyección-de-dependencias) 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 solicitudes 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. IMPORTANTE: 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) { // Inyecta el `AuthService` actual y úsalo para obtener un token de autenticación: const authToken = inject(AuthService).getAuthToken(); // Clona la solicitud para agregar el encabezado de autenticación. const newReq = req.clone({ headers: req.headers.append('X-Authentication-Token', authToken), }); return next(newReq); } ``` ## Metadatos 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(); } } })); } ``` ## Trabajando con tipos de respuesta Cuando se usa `HttpClient` con el proveedor `withFetch`, las respuestas incluyen una propiedad `type` que indica cómo el navegador manejó la respuesta basándose en las políticas CORS y el modo de solicitud. Esta propiedad está alineada con la especificación nativa de la API Fetch y proporciona información valiosa para depurar problemas CORS y entender la accesibilidad de las respuestas. La propiedad `type` de la respuesta puede tener los siguientes valores: - `'basic'` - Respuesta del mismo origen con todos los encabezados accesibles - `'cors'` - Respuesta de origen cruzado con encabezados CORS configurados correctamente - `'opaque'` - Respuesta de origen cruzado sin CORS, los encabezados y el cuerpo pueden estar limitados - `'opaqueredirect'` - Respuesta de una solicitud redirigida en modo no-cors - `'error'` - Ocurrió un error de red Un interceptor puede usar la información del tipo de respuesta para depurar CORS y manejar errores: ```ts export function responseTypeInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> { return next(req).pipe(map(event => { if (event.type === HttpEventType.Response) { // Manejar diferentes tipos de respuesta apropiadamente switch (event.responseType) { case 'opaque': // Acceso limitado a los datos de respuesta console.warn('Datos de respuesta limitados debido a la política CORS'); break; case 'cors': case 'basic': // Acceso completo a los datos de respuesta break; case 'error': // Manejar errores de red console.error('Error de red en la respuesta'); break; } } })); } ``` ## 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 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="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="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="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="name-editor.component.html (valor de control)" 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](#validando-la-entrada-de-formulario '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="name-editor.component.ts (actualizar valor)" 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="name-editor.component.html (actualizar valor)" 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. CONSEJO: En este ejemplo, estás usando un control único. Cuando uses el método `setValue()` con una instancia de [grupo de formulario](#agrupando-controles-de-formulario) o [array de formulario](#creando-formularios-dinámicos), 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](#creando-grupos-de-formulario-anidados '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](#creando-formularios-dinámicos). | 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="profile-editor.component.ts (importaciones)" 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="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="profile-editor.component.html (grupo de formulario de plantilla)" 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="profile-editor.component.html (evento de envío)" 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="profile-editor.component.ts (método de envío)" 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="profile-editor.component.html (botón de envío)" 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](#validando-la-entrada-de-formulario). </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="app.component.html (editor de perfil)" 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 anidado"> Para crear un grupo anidado en `profileForm`, agrega un elemento anidado `address` a la instancia de `FormGroup`. <docs-code header="profile-editor.component.ts (grupo de formulario anidado)" 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="profile-editor.component.html (grupo de formulario anidado de plantilla)" 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="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="profile-editor.component.html (actualizar valor)" 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="profile-editor.component.ts (importar)" 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="profile-editor.component.ts (inicialización de propiedad)" 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="profile-editor.component.ts (constructor de formulario)" 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. CONSEJO: 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-code header="profile-editor.component.ts (importar)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="validator-imports"/> </docs-step> <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="profile-editor.component.ts (validador requerido)" 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="profile-editor.component.html (mostrar estado)" 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-code header="profile-editor.component.ts (importar)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-array-imports"/> </docs-step> <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="profile-editor.component.ts (array de formulario de alias)" 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="profile-editor.component.ts (getter de alias)" 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, y también puedes pasar un array de controles a `FormArray.push()` para registrar múltiples controles a la vez. <docs-code header="profile-editor.component.ts (agregar 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="profile-editor.component.html (plantilla de array de formulario de alias)" 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> ## Eventos unificados de cambio de estado de control Todos los controles de formulario exponen un único flujo unificado de **eventos de cambio de estado de control** a través del observable `events` en `AbstractControl` (`FormControl`, `FormGroup`, `FormArray`, y `FormRecord`). Este flujo unificado te permite reaccionar a cambios de estado de **valor**, **estado**, **pristine**, **touched** y **reset**, y también para **acciones a nivel de formulario** como **submit**, permitiéndote manejar todas las actualizaciones con una sola suscripción en lugar de conectar múltiples observables. ### Tipos de eventos Cada elemento emitido por `events` es una instancia de una clase de evento específica: - **`ValueChangeEvent`** — cuando el **valor** del control cambia. - **`StatusChangeEvent`** — cuando el **estado de validación** del control se actualiza a uno de los valores de `FormControlStatus` (`VALID`, `INVALID`, `PENDING`, o `DISABLED`). - **`PristineChangeEvent`** — cuando el estado **pristine/dirty** del control cambia. - **`TouchedChangeEvent`** — cuando el estado **touched/untouched** del control cambia. - **`FormResetEvent`** — cuando un control o formulario se restablece, ya sea mediante la API `reset()` o una acción nativa. - **`FormSubmittedEvent`** — cuando se envía el formulario. Todas las clases de eventos extienden `ControlEvent` e incluyen una referencia `source` al `AbstractControl` que originó el cambio, lo cual es útil en formularios grandes. ```ts import { Component } from '@angular/core'; import { FormControl, ValueChangeEvent, StatusChangeEvent, PristineChangeEvent, TouchedChangeEvent, FormResetEvent, FormSubmittedEvent, ReactiveFormsModule, FormGroup, } from '@angular/forms'; @Component({/* ... */ }) export class UnifiedEventsBasicComponent { form = new FormGroup({ username: new FormControl(''), }); constructor() { this.form.events.subscribe((e) => { if (e instanceof ValueChangeEvent) { console.log('Value changed to: ', e.value); } if (e instanceof StatusChangeEvent) { console.log('Status changed to: ', e.status); } if (e instanceof PristineChangeEvent) { console.log('Pristine status changed to: ', e.pristine); } if (e instanceof TouchedChangeEvent) { console.log('Touched status changed to: ', e.touched); } if (e instanceof FormResetEvent) { console.log('Form was reset'); } if (e instanceof FormSubmittedEvent) { console.log('Form was submitted'); } }); } } ``` ### Filtrar eventos específicos Prefiere operadores RxJS cuando solo necesites un subconjunto de tipos de eventos. ```ts import { filter } from 'rxjs/operators'; import { StatusChangeEvent } from '@angular/forms'; control.events .pipe(filter((e) => e instanceof StatusChangeEvent)) .subscribe((e) => console.log('Status:', e.status)); ``` ### Unificar desde múltiples suscripciones **Antes** ```ts import { combineLatest } from 'rxjs/operators'; combineLatest([control.valueChanges, control.statusChanges]) .subscribe(([value, status]) => { /* ... */ }); ``` **Después** ```ts control.events.subscribe((e) => { // Manejar ValueChangeEvent, StatusChangeEvent, etc. }); ``` NOTA: En el cambio de valor, la emisión ocurre justo después de que se actualiza el valor de este control. El valor de un control padre (por ejemplo, si este FormControl es parte de un FormGroup) se actualiza más tarde, por lo que acceder al valor de un control padre (usando la propiedad `value`) desde el callback de este evento podría resultar en obtener un valor que aún no se ha actualizado. Suscríbete a los `events` del control padre en su lugar. ## Funciones de utilidad para restringir tipos de control de formulario Angular proporciona cuatro funciones de utilidad que ayudan a determinar el tipo concreto de un `AbstractControl`. Estas funciones actúan como **type guards** y restringen el tipo de control cuando devuelven `true`, lo que te permite acceder de forma segura a propiedades específicas del subtipo dentro del mismo bloque. | Función de utilidad | Detalles | | :--------------- | :-------------------------------------------------- | | `isFormControl` | Devuelve `true` cuando el control es un `FormControl`. | | `isFormGroup` | Devuelve `true` cuando el control es un `FormGroup` | | `isFormRecord` | Devuelve `true` cuando el control es un `FormRecord` | | `isFormArray` | Devuelve `true` cuando el control es un `FormArray` | Estos ayudantes son particularmente útiles en **validadores personalizados**, donde la firma de la función recibe un `AbstractControl`, pero la lógica está destinada a un tipo de control específico. ```ts import { AbstractControl, isFormArray } from '@angular/forms'; export function positiveValues(control: AbstractControl) { if (!isFormArray(control)) { return null; // No es un FormArray: el validador no es aplicable. } // Seguro para acceder a la API específica de FormArray después de restringir. const hasNegative = control.controls.some(c => c.value < 0); return hasNegative ? { positiveValues: true } : null; } ``` ## 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 | Detalles | | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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')); ``` Puedes pasar un array de controles a `aliases.push()` cuando necesites agregar varias entradas a la vez. ```ts const aliases = new FormArray([new FormControl('ng')]); aliases.push([new FormControl('ngDev'), new FormControl('ngAwesome')]); ``` 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. Un `FormArray` también proporciona un método `clear()` para eliminar todos los controles que contiene: ```ts const aliases = new FormArray([new FormControl('ngDev'), new FormControl('ngAwesome')]); aliases.clear(); console.log(aliases.length); // 0 ``` ## `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}), }); login.removeControl('password'); ``` 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 <!-- TODO: link to preview --> <!-- <docs-code live/> --> 1. La aplicación de ejemplo proporcionada crea la clase `Actor` que define el modelo de datos reflejado en el formulario. <docs-code header="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="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="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="actor-form.component.html (habilidades)" 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="actor-form.component.html (extracto)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngModelName-1"/> CONSEJO: 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="actor-form.component.html (extracto)" 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="actor-form.component.html (extracto)" 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. | Estados | Clase si es verdadero | Clase si es falso | | :------------------------------- | :------------ | :------------- | | El control ha sido visitado. | `ng-touched` | `ng-untouched` | | El valor del control ha cambiado. | `ng-dirty` | `ng-pristine` | | El valor del control es válido. | `ng-valid` | `ng-invalid` | 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. ```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="index.html (estilos)" 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="actor-form.component.html (mensaje de error oculto)" 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="actor-form.component.html (extracto)" 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="actor-form.component.ts (método New Actor)" 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="actor-form.component.html (botón New Actor)" 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="actor-form.component.html (Restablecer el formulario)" 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="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="actor-form.component.html (botón de envío)" 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="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="actor-form.component.ts (enviado)" 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="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`: <docs-code header="actor-form-template.component.html (nombre)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="name-with-error-msg"/> 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](#definiendo-validadores-personalizados). - `#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](#definiendo-validadores-personalizados), 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="actor-form-reactive.component.ts (funciones de validación)" 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="actor-form-reactive.component.html (nombre con mensaje de errror)" 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="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`. <docs-code header="actor-form-reactive.component.ts (funciones de validación)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" visibleRegion="custom-validator"/> ### 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="forbidden-name.directive.ts (proveedores)" 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="forbidden-name.directive.ts (directiva)" 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="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](#definiendo-validadores-personalizados "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: ```ts 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. ```ts const actorForm = new FormGroup( { 'name': new FormControl(), 'role': new FormControl(), 'skill': new FormControl(), }, {validators: unambiguousRoleValidator}, ); ``` El código del validador es el siguiente. <docs-code header="unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" visibleRegion="cross-validation-validator"/> 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="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](#clases-css-de-estado-de-control). ### 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="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="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. <docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="cross-validation-error-message"/> 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. ```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`. <docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" visibleRegion="async-validator"/> La propiedad `actorsService` se inicializa con una instancia del token `ActorsService`, que define la siguiente interfaz. ```ts 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. <docs-code header="actor-form-reactive.component.2.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" visibleRegion="async-validator-inject"/> 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 header="actor-form-reactive.component.2.ts" 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 header="role.directive.ts" 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="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. ```html <input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}"> ``` Con formularios reactivos, establece la propiedad en la instancia `FormControl`. ```ts 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="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="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="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. <img alt="Dynamic-Form" src="assets/images/guide/dynamic-form/dynamic-form.png"> ## 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 `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. <img alt="Diagrama para ilustrar rutas anidadas" src="assets/images/guide/router/nested-routing-diagram.svg"> 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 <!-- ProductComponent --> <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 /> <!-- Angular inserta el contenido de tu ruta aquí --> <app-footer /> ``` ```ts 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: ```ts 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 <!-- Contenido de la plantilla del componente --> <app-header /> <router-outlet /> <app-footer /> ``` ```html <!-- Contenido renderizado en la página cuando el usuario visita /admin --> <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. ```ts 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. ## Pasar datos contextuales a componentes enrutados Pasar datos contextuales a componentes enrutados a menudo requiere estado global o configuraciones de ruta complicadas. Para facilitar esto, cada `RouterOutlet` soporta un input `routerOutletData`. Los componentes enrutados y sus hijos pueden leer estos datos como un signal usando el token de inyección `ROUTER_OUTLET_DATA`, permitiendo configuración específica del outlet sin modificar definiciones de ruta. ```typescript import { Component } from '@angular/core'; import { RouterOutlet } from '@angular/router'; @Component({ selector: 'app-dashboard', imports: [RouterOutlet], template: ` <h2>Dashboard</h2> <router-outlet [routerOutletData]="{ layout: 'sidebar' }" /> `, }) export class DashboardComponent {} ``` El componente enrutado puede inyectar los datos del outlet proporcionados usando `ROUTER_OUTLET_DATA`: ```typescript import { Component, inject } from '@angular/core'; import { ROUTER_OUTLET_DATA } from '@angular/router'; @Component({ selector: 'app-stats', template: `<p>Stats view (layout: {{ outletData().layout }})</p>`, }) export class StatsComponent { outletData = inject(ROUTER_OUTLET_DATA) as Signal<{ layout: string }>; } ``` Cuando Angular activa el `StatsComponent` en ese outlet, recibe `{ layout: 'sidebar' }` como datos inyectados. NOTA: Cuando el input `routerOutletData` no está establecido, el valor inyectado es null por defecto. --- ## 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 <!-- URL absoluta --> <a href="https://www.angular.dev/essentials">Angular Essentials Guide</a> <!-- URL relativa --> <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 <!-- Navega al usuario a /dashboard --> <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 <!-- Navega a /settings/notifications --> <a routerLink="notifications">Notifications</a> <a routerLink="/settings/notifications">Notifications</a> <!-- Navega a /team/:teamId/user/:userId --> <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' } }); // Con parámetros de matriz this.router.navigate(['/products', { featured: true, onSale: true }]); } } ``` `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. ```ts // 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'); // Con parámetros de matriz router.navigateByUrl('/sales-awesome;isOffer=true;showModal=false') ``` 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`. ```ts // 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 tres tipos de parámetros que los desarrolladores pueden utilizar desde una ruta: parámetros de ruta, parámetros de consulta y parámetros de matriz. ### 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> <!-- Lista de productos --> </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). ### Parámetros de matriz Los parámetros de matriz son parámetros opcionales que pertenecen a un segmento de URL específico, en lugar de aplicarse a toda la ruta. A diferencia de los parámetros de consulta que aparecen después de un `?` y se aplican globalmente, los parámetros de matriz usan punto y coma (`;`) y están limitados a segmentos de ruta individuales. Los parámetros de matriz son útiles cuando necesitas pasar datos auxiliares a un segmento de ruta específico sin afectar la definición de ruta o el comportamiento de coincidencia. Al igual que los parámetros de consulta, no necesitan estar definidos en tu configuración de ruta. ```ts // Formato de URL: /path;key=value // Múltiples parámetros: /path;key1=value1;key2=value2 // Navegar con parámetros de matriz this.router.navigate(['/awesome-products', { view: 'grid', filter: 'new' }]); // Resulta en URL: /awesome-products;view=grid;filter=new ``` **Usando ActivatedRoute** ```ts import { Component, inject } from '@angular/core'; import { ActivatedRoute } from '@angular/router'; @Component(/* ... */) export class AwesomeProducts { private route = inject(ActivatedRoute); constructor() { // Acceder a parámetros de matriz vía params this.route.params.subscribe((params) => { const view = params['view']; // p.ej., 'grid' const filter = params['filter']; // p.ej., 'new' }); } } ``` NOTA: Como alternativa a usar `ActivatedRoute`, los parámetros de matriz también se vinculan a inputs de componente cuando se usa `withComponentInputBinding`. ## 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 <!-- Sintaxis de string separado por espacios --> <a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a> <!-- Sintaxis de array --> <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` 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'})`. Consulta [opciones de configuración del router](guide/routing/customizing-route-behavior#opciones-de-configuración-del-router) para obtener detalles sobre otras configuraciones disponibles. ## Mostrar una página 404 Para mostrar una página 404, configura una [ruta comodín](guide/routing/common-router-tasks#mostrar-una-página-404) 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> ``` Esta sintaxis pasa parámetros de matriz, que son parámetros opcionales asociados con un segmento de URL específico. Aprende más sobre [parámetros de matriz](/guide/routing/read-route-state#parámetros-de-matriz). 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`: | Providers | Details | | :--------------------- | :-------------------------------------------- | | `PathLocationStrategy` | El estilo predeterminado "HTML5 pushState". | | `HashLocationStrategy` | El estilo "hash URL". | 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_. ```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. <docs-code header="heroes-list/heroes-list.component.html" path="adev/src/content/examples/router-tutorial/src/app/heroes-list/heroes-list.component.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="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`. ```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. <docs-code header="app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="components"/> 1. Agrega la directiva `router-outlet`. <docs-code header="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. <docs-code header="app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="nav"/> 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="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="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`. ```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. <docs-code header="profile/profile.component.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.component.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="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="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 username = input.required<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`. ```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 an 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`. #### 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. ```ts // 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` and `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 { contentRef = viewChild.required<ElementRef>('content'); 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); }); } } ``` ## Setting providers on the server On the server side, top level provider values are set once when the application code is initially parsed and evaluated. This means that providers configured with `useValue` will keep their value across multiple requests, until the server application is restarted. If you want to generate a new value for each request, use a factory provider with `useFactory`. The factory function will run for every incoming request, ensuring that a new value is created and assigned to the token each time. ## Accessing Document via DI When working with server-side rendering, you should avoid directly referencing browser-specific globals like `document`. Instead, use the [`DOCUMENT`](api/core/DOCUMENT) token to access the document object in a platform-agnostic way. ```ts import { Injectable, inject, DOCUMENT } from '@angular/core'; @Injectable({ providedIn: 'root' }) export class CanonicalLinkService { private readonly document = inject(DOCUMENT); // During server rendering, inject a <link rel="canonical"> tag // so the generated HTML includes the correct canonical URL setCanonical(href: string): void { const link = this.document.createElement('link'); link.rel = 'canonical'; link.href = href; this.document.head.appendChild(link); } } ``` HELPFUL: For managing meta tags, Angular provides the `Meta` service. ## 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` caches 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. ### Configuring the caching options You can customize how Angular caches HTTP responses during server‑side rendering (SSR) and reuses them during hydration by configuring `HttpTransferCacheOptions`. This configuration is provided globally using `withHttpTransferCacheOptions` inside `provideClientHydration()`. 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` to the hydration configuration. ```ts import { bootstrapApplication } from '@angular/platform-browser'; import { provideClientHydration, withHttpTransferCacheOptions } from '@angular/platform-browser'; bootstrapApplication(AppComponent, { providers: [ provideClientHydration( withHttpTransferCacheOptions({ includeHeaders: ['ETag', 'Cache-Control'], filter: (req) => !req.url.includes('/api/profile'), includePostRequests: true, includeRequestsWithAuthHeaders: false, }), ), ], }); ``` --- ### `includeHeaders` Specifies which headers from the server response should be included in cached entries. No headers are included by default. ```ts withHttpTransferCacheOptions({ includeHeaders: ['ETag', 'Cache-Control'], }); ``` IMPORTANT: Avoid including sensitive headers like authentication tokens. These can leak user‑specific data between requests. --- ### `includePostRequests` By default, only `GET` and `HEAD` requests are cached. You can enable caching for `POST` requests when they are used as read operations such as GraphQL queries. ```ts withHttpTransferCacheOptions({ includePostRequests: true, }); ``` Use this only when `POST` requests are **idempotent** and safe to reuse between server and client renders. --- ### `includeRequestsWithAuthHeaders` Determines whether requests containing `Authorization` or `Proxy‑Authorization` headers are eligible for caching. By default, these are excluded to prevent caching user‑specific responses. ```ts withHttpTransferCacheOptions({ includeRequestsWithAuthHeaders: true, }); ``` Enable only when authentication headers do **not** affect the response content (for example, public tokens for analytics APIs). ### Per‑request overrides You can override caching behavior for a specific request using the `transferCache` request option. ```ts // Include specific headers for this request http.get('/api/profile', { transferCache: { includeHeaders: ['CustomHeader'] } }); ``` ### Disabling caching You can disable HTTP caching of requests sent from the server either globally or individually. #### Globally To disable caching for all requests in your application, use the `withNoHttpTransferCache` feature: ```ts import { bootstrapApplication, provideClientHydration, withNoHttpTransferCache } from '@angular/platform-browser'; bootstrapApplication(AppComponent, { providers: [ provideClientHydration(withNoHttpTransferCache()) ] }); ``` #### `filter` You can also selectively disable caching for certain requests using the [`filter`](api/common/http/HttpTransferCacheOptions) option in `withHttpTransferCacheOptions`. For example, you can disable caching for a specific API endpoint: ```ts import { bootstrapApplication, provideClientHydration, withHttpTransferCacheOptions } from '@angular/platform-browser'; bootstrapApplication(AppComponent, { providers: [ provideClientHydration(withHttpTransferCacheOptions({ filter: (req) => !req.url.includes('/api/sensitive-data') })) ] }); ``` Use this option to exclude endpoints with user‑specific or dynamic data (for example `/api/profile`). #### Individually To disable caching for an individual request, you can specify the [`transferCache`](api/common/http/HttpRequest#transferCache) option in an `HttpRequest`. ```ts httpClient.get('/api/sensitive-data', { transferCache: false }); ``` ## 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. ```ts // 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). ```ts // 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 unitarias Probar tu aplicación Angular te ayuda a verificar que está funcionando como esperas. Las pruebas unitarias son cruciales para detectar errores temprano, asegurar la calidad del código y facilitar la refactorización segura. NOTA: Esta guía se enfoca en la configuración de pruebas predeterminada para nuevos proyectos de Angular CLI. Si estás migrando un proyecto existente de Karma a Vitest, consulta la [guía de Migración de Karma a Vitest](guide/testing/migrating-to-vitest). Aunque Vitest es el ejecutor de pruebas predeterminado, Karma todavía está completamente soportado. Para información sobre pruebas con Karma, consulta la [guía de pruebas de Karma](guide/testing/karma). ## Configurar pruebas Angular CLI descarga e instala todo lo que necesitas para probar una aplicación Angular con el [framework de pruebas Vitest](https://vitest.dev). Por defecto, los nuevos proyectos incluyen `vitest` y `jsdom`. Vitest ejecuta tus pruebas unitarias en un entorno de Node.js, usando `jsdom` para emular el DOM. Esto permite una ejecución de pruebas más rápida al evitar la sobrecarga de lanzar un navegador. También puedes usar `happy-dom` como alternativa instalándolo y eliminando `jsdom`. El CLI detectará y usará automáticamente `happy-dom` si está presente. 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 [ejecutor de pruebas Vitest](https://vitest.dev). La salida de consola se ve así: ```shell ✓ src/app/app.spec.ts (3) ✓ AppComponent should create the app ✓ AppComponent should have as title 'my-app' ✓ AppComponent should render title Test Files 1 passed (1) Tests 3 passed (3) Start at 18:18:01 Duration 2.46s (transform 615ms, setup 2ms, collect 2.21s, tests 5ms) ``` El comando `ng test` también observa cambios. Para ver esto en acción, haz un pequeño cambio a `app.ts` y guárdalo. Las pruebas se ejecutan nuevamente y los nuevos resultados aparecen en la consola. ## Configuración Angular CLI maneja la mayor parte de la configuración de Vitest por ti. Para muchos casos de uso comunes, puedes ajustar el comportamiento de las pruebas modificando opciones directamente en tu archivo `angular.json`. ### Opciones de configuración integradas Puedes cambiar las siguientes opciones en el target `test` de tu archivo `angular.json`: - `include`: Patrones glob de archivos para incluir en las pruebas. Por defecto es `['**/*.spec.ts', '**/*.test.ts']`. - `exclude`: Patrones glob de archivos para excluir de las pruebas. - `setupFiles`: Una lista de rutas a archivos de configuración global (por ejemplo, polyfills o mocks globales) que se ejecutan antes de tus pruebas. - `providersFile`: La ruta a un archivo que exporta un array predeterminado de proveedores de Angular para el entorno de pruebas. Esto es útil para configurar proveedores de prueba globales que se inyectan en tus pruebas. - `coverage`: Un booleano para habilitar o deshabilitar reportes de cobertura de código. Por defecto es `false`. - `browsers`: Un array de nombres de navegadores para ejecutar pruebas (por ejemplo, `["chromium"]`). Requiere que se instale un proveedor de navegador. Por ejemplo, podrías crear un archivo `src/test-providers.ts` para proporcionar `provideHttpClientTesting` a todas tus pruebas: ```typescript import { Provider } from '@angular/core'; import { provideHttpClient } from '@angular/common/http'; import { provideHttpClientTesting } from '@angular/common/http/testing'; const testProviders: Provider[] = [ provideHttpClient(), provideHttpClientTesting(), ]; export default testProviders; ``` Luego referenciarías este archivo en tu `angular.json`: ```json { "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "include": ["src/**/*.spec.ts"], "setupFiles": ["src/test-setup.ts"], "providersFile": "src/test-providers.ts", "coverage": true, "browsers": ["chromium"] } } } } } } ``` ### Avanzado: Configuración personalizada de Vitest Para casos de uso avanzados, puedes proporcionar un archivo de configuración personalizado de Vitest. IMPORTANTE: Aunque usar una configuración personalizada habilita opciones avanzadas, el equipo de Angular no proporciona soporte directo para el contenido específico del archivo de configuración o para cualquier plugin de terceros usado dentro de él. El CLI también sobrescribirá ciertas propiedades (`test.projects`, `test.include`) para asegurar el funcionamiento adecuado. Puedes crear un archivo de configuración de Vitest (por ejemplo, `vitest-base.config.ts`) y referenciarlo en tu `angular.json` usando la opción `runnerConfig`. ```json { "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "runnerConfig": "vitest-base.config.ts" } } } } } } ``` También puedes generar un archivo de configuración base usando el CLI: ```shell ng generate config vitest ``` Esto crea un archivo `vitest-base.config.ts` que puedes personalizar. CONSEJO: Lee más sobre la configuración de Vitest en la [guía de configuración de Vitest](https://vitest.dev/config/). ## Cobertura de código Puedes generar reportes de cobertura de código agregando la bandera `--coverage` al comando `ng test`. El reporte se genera en el directorio `coverage/`. Para información más detallada sobre prerrequisitos, aplicar umbrales de cobertura y configuración avanzada, consulta la [guía de Cobertura de código](guide/testing/code-coverage). ## Ejecutar pruebas en un navegador Aunque el entorno predeterminado de Node.js es más rápido para la mayoría de las pruebas unitarias, también puedes ejecutar tus pruebas en un navegador real. Esto es útil para pruebas que dependen de APIs específicas del navegador (como renderizado) o para depuración. Para ejecutar pruebas en un navegador, primero debes instalar un proveedor de navegador. Elige uno de los siguientes proveedores de navegador según tus necesidades: - **Playwright**: `@vitest/browser-playwright` para Chromium, Firefox y WebKit. - **WebdriverIO**: `@vitest/browser-webdriverio` para Chrome, Firefox, Safari y Edge. - **Preview**: `@vitest/browser-preview` para entornos Webcontainer (como StackBlitz). ```shell // npm npm install --save-dev @vitest/browser-playwright playwright ``` ```shell // yarn yarn add --dev @vitest/browser-playwright playwright ``` ```shell // pnpm pnpm add -D @vitest/browser-playwright playwright ``` ```shell // bun bun add --dev @vitest/browser-playwright playwright ``` Una vez que el proveedor esté instalado, puedes ejecutar tus pruebas en el navegador usando la bandera `--browsers`: ```bash # Ejemplo para Playwright ng test --browsers=chromium # Ejemplo para WebdriverIO ng test --browsers=chrome ``` El modo headless se habilita automáticamente si la variable de entorno `CI` está establecida. De lo contrario, las pruebas se ejecutarán en un navegador con interfaz gráfica. ## Otros frameworks de prueba También puedes hacer pruebas unitarias de una aplicación Angular con otras librerías de prueba y ejecutores de pruebas. Cada librería y ejecutor tiene sus propios procedimientos de instalación, configuración y sintaxis distintivos. ## Pruebas en integración continua Un conjunto de pruebas robusto es una parte clave de una canalización de integración continua (CI). Los servidores de 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 en un servidor de integración continua (CI), típicamente puedes ejecutar el comando de prueba estándar: ```shell ng test ``` La mayoría de los servidores de CI establecen una variable de entorno `CI=true`, que `ng test` detecta. Esto ejecuta automáticamente tus pruebas en el modo apropiado no interactivo de ejecución única. Si tu servidor de CI no establece esta variable, o si necesitas forzar el modo de ejecución única manualmente, puedes usar las banderas `--no-watch` y `--no-progress`: ```shell ng test --no-watch --no-progress ``` ## 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 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) | Errores comunes de pruebas. | | [APIs utilitarias de pruebas](guide/testing/utility-apis) | Características de pruebas en Angular. | # 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. ## Prerrequisitos Para generar reportes de cobertura de código con Vitest, debes instalar el paquete `@vitest/coverage-v8`: ```shell // npm npm install --save-dev @vitest/coverage-v8 ``` ```shell // yarn yarn add --dev @vitest/coverage-v8 ``` ```shell // pnpm pnpm add -D @vitest/coverage-v8 ``` ```shell // bun bun add --dev @vitest/coverage-v8 ``` ## Generar un reporte Para generar un reporte de cobertura, agrega la bandera `--coverage` al comando `ng test`: ```shell ng test --coverage ``` Después de que se ejecuten las pruebas, 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, puedes establecer la opción `coverage` en `true` en tu archivo `angular.json`: ```json { "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "coverage": true } } } } } } ``` ## Aplicar umbrales 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 para ser probada unitariamente, puedes aplicar este mínimo en tu configuración. 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, agrega la opción `coverageThresholds` a tu archivo `angular.json`: ```json { "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "coverage": true, "coverageThresholds": { "statements": 80, "branches": 80, "functions": 80, "lines": 80 } } } } } } } ``` Ahora, si tu cobertura cae por debajo del 80% cuando ejecutas tus pruebas, el comando fallará. ## Configuración avanzada Puedes configurar varias otras opciones de cobertura en tu archivo `angular.json`: - `coverageInclude`: Patrones glob de archivos para incluir en el reporte de cobertura. - `coverageReporters`: Un array de reportes para usar (por ejemplo, `html`, `lcov`, `json`). - `coverageWatermarks`: Un objeto que especifica marcas de agua `[low, high]` para el reporte HTML, que puede afectar la codificación de colores del reporte. ```json { "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "coverage": true, "coverageReporters": ["html", "lcov"], "coverageWatermarks": { "statements": [50, 80], "branches": [50, 80], "functions": [50, 80], "lines": [50, 80] } } } } } } } ``` # Probar servicios NOTA: Aunque esta guía se está actualizando para Vitest, algunos ejemplos de código actualmente usan sintaxis y APIs de Karma/Jasmine. Estamos trabajando activamente para proporcionar equivalentes de Vitest donde sea aplicable. 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. ``` ## 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="demo.testbed.spec.ts (proporcionar ValueService en 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. CONSEJO: `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="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="hero.service.spec.ts (pruebas con 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="banner-external.component.spec.ts (inicial)" path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v1"/> CONSEJO: 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="banner-initial.component.spec.ts (mínimo)" 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"/> CONSEJO: 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="banner.component.spec.ts (configuración)" 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="banner.component.detect-changes.spec.ts (importar)" 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="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="banner.component.detect-changes.spec.ts (Pruebas AutoDetect)" 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="hero-detail.component.spec.ts (prueba de pipe)" 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="banner-external.component.ts (metadatos)" 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()`. ## 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="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="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="twain.component.ts (plantilla)" 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="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 `twain.component.spec.ts` muestra una forma de hacerlo: <docs-code header="twain.component.spec.ts (configuración)" 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()`](#prueba-async-sin-fakeasync). 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="canvas.component.spec.ts (extracto)" 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 o 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="dashboard.component.html (extracto)" 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="dashboard-hero.component.ts (componente)" 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="dashboard-hero.component.spec.ts (configuración)" 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](#probar-dashboardherocomponent-standalone) 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="dashboard-hero.component.spec.ts (prueba con helper click)" 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="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="dashboard-hero.component.spec.ts (configuración test host)" 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="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="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="dashboard.component.spec.ts (prueba de navegación)" 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="hero-detail.component.ts (inyectar)" 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="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.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.component.spec.ts (declaración stub)" 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áralos sobrescribiendo los `imports` de tu componente usando `TestBed.overrideComponent`. <docs-code header="app.component.spec.ts (stubs TestBed)" 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.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.component.spec.ts (configuración mixta)" 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.component.spec.ts (configuración de prueba)" 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.component.html (enlaces de navegación)" 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.component.spec.ts (pruebas seleccionadas)" 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="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="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="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="hero-detail.component.spec.ts (pruebas seleccionadas)" 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="hero-detail.component.ts (prototipo)" 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="hero-detail.service.ts (prototipo)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.service.ts" visibleRegion="prototype"/> La configuración de prueba anterior 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="hero-detail.component.spec.ts (configuración Override)" 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](#proporcionar-un-spy-stub-herodetailservicespy). ### El método `overrideComponent` Enfócate en el método `overrideComponent`. <docs-code header="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="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="hero-detail.component.spec.ts (pruebas override)" 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 depurarlas tanto en el entorno predeterminado de Node.js como en un navegador real. ## Depurar en Node.js Depurar en el entorno predeterminado de Node.js suele ser la forma más rápida de diagnosticar problemas que no están relacionados con APIs específicas del navegador o renderizado. 1. Ejecuta el comando `ng test` con la bandera `--debug`: ```shell ng test --debug ``` 2. El ejecutor de pruebas se iniciará en modo debug y esperará a que se adjunte un depurador. 3. Ahora puedes adjuntar tu depurador preferido. Por ejemplo, puedes usar el depurador integrado de Node.js en VS Code o Chrome DevTools para Node.js. ## Depurar en un navegador Depurar en un navegador se recomienda para pruebas que dependen del DOM u otras APIs específicas del navegador. Este enfoque te permite usar las herramientas de desarrollador del propio navegador. 1. Asegúrate de tener un proveedor de navegador instalado. Consulta [Ejecutar pruebas en un navegador](guide/testing/overview#ejecutar-pruebas-en-un-navegador) para instrucciones de configuración. 2. Ejecuta el comando `ng test` con las banderas `--browsers` y `--debug`: ```shell ng test --browsers=chromium --debug ``` 3. Este comando ejecuta las pruebas en un navegador con interfaz gráfica y lo mantiene abierto después de que las pruebas terminen, permitiéndote inspeccionar la salida. 4. Abre las **Herramientas de Desarrollador** del navegador. En Windows, presiona `Ctrl-Shift-I`. En macOS, presiona `Command-Option-I`. 5. Ve a la pestaña **Sources**. 6. Usa `Control/Command-P` para buscar y abrir tu archivo de prueba. 7. Establece un breakpoint en tu prueba. 8. Recarga la interfaz del ejecutor de pruebas en el navegador. La ejecución ahora se detendrá en tu breakpoint. # APIs utilitarias de pruebas NOTA: Aunque esta guía se está actualizando para Vitest, algunas descripciones y ejemplos de APIs utilitarias se presentan actualmente en el contexto de Karma/Jasmine. Estamos trabajando activamente para proporcionar equivalentes de Vitest y orientación actualizada donde sea aplicable. 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`](#resumen-de-la-clase-testbed) y [`ComponentFixture`](#el-componentfixture) se cubren por separado. Aquí hay un resumen de las funciones independientes, en orden de utilidad probable: | Función | Detalles | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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). | | `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. | Para manejar escenarios asíncronos complejos o probar aplicaciones basadas en Zone.js heredadas, consulta la guía de [Utilidades de pruebas de Zone.js](guide/testing/zone-js-testing-utilities). ## 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](#debugelement). | | `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 a cualquier profundidad en el subárbol. | | `queryAll` | Llamar a `queryAll(predicate: Predicate<DebugElement>)` retorna todos los `DebugElements` que coinciden con el 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="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: | Método estático | Detalles | |:------------------------- |:---------------------------------------------------------------------------------- | | `By.all` | Retorna todos los elementos | | `By.css(selector)` | Retorna elementos con selectores CSS coincidentes | | `By.directive(directive)` | Retorna elementos que Angular coincidió con una instancia de la clase de directiva | <docs-code header="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 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. ### ¿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 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 ``` ## 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 algo cosmético. 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 chocantes. - El movimiento mejora enormemente la experiencia del usuario, por lo que las animaciones les dan la oportunidad de detectar la respuesta de la aplicación a sus acciones. - Las buenas animaciones pueden guiar 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="enter.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts" /> <docs-code header="enter.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.html" /> <docs-code header="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="enter-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts" /> <docs-code header="enter-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.html" /> <docs-code header="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="leave.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts" /> <docs-code header="leave.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.html" /> <docs-code header="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="leave-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts" /> <docs-code header="leave-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.html" /> <docs-code header="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="leave-event.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts" /> <docs-code header="leave-event.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.html" /> <docs-code header="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 } ``` ## Compatibilidad con las animaciones heredadas de Angular No puedes usar animaciones heredadas junto con `animate.enter` y `animate.leave` dentro del mismo componente. Hacerlo provocaría que las clases de entrada permanezcan en el elemento o que los nodos que salen no se eliminen. Fuera de eso, está bien usar tanto las animaciones heredadas como las nuevas animaciones `animate.enter` y `animate.leave` dentro de la misma _aplicación_. La única excepción es la proyección de contenido. Si estás proyectando contenido desde un componente con animaciones heredadas hacia otro componente que usa `animate.enter` o `animate.leave`, o viceversa, esto producirá el mismo comportamiento que si se usaran juntas en el mismo componente. Esto no es compatible. ## 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="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="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="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="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="open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" /> <docs-code header="open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" /> <docs-code header="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="auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" /> <docs-code header="auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" /> <docs-code header="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="insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" /> <docs-code header="insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" /> <docs-code header="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="remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" /> <docs-code header="remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" /> <docs-code header="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="increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" /> <docs-code header="increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" /> <docs-code header="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="stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" /> <docs-code header="stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" /> <docs-code header="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="reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" /> <docs-code header="reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" /> <docs-code header="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#componentes-cargados-de-forma-lazy), [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#agregando-el-router-a-tu-aplicación). 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#parámetros-de-consulta) (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 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 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 el paquete de Aninaciones <docs-code header="animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" visibleRegion="animation-example"/> #### Con CSS nativo <docs-code header="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 el paquete de Aninaciones <docs-code header="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="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 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="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="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 el paquete de Aninaciones #### Con CSS nativo <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts"> <docs-code header="open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" /> <docs-code header="open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" /> <docs-code header="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 el paquete de Animaciones 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="auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" /> <docs-code header="auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" /> <docs-code header="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 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 el paquete de Ani 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="insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" /> <docs-code header="insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" /> <docs-code header="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="remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" /> <docs-code header="remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" /> <docs-code header="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 el paquete de Aninaciones #### Con CSS nativo <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts"> <docs-code header="increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" /> <docs-code header="increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" /> <docs-code header="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; } ``` 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 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. [`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 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 el paquete de Aninaciones #### Con CSS nativo <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts"> <docs-code header="stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" /> <docs-code header="stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" /> <docs-code header=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 el paquete de Aninaciones #### Con CSS nativo <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts"> <docs-code header="reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" /> <docs-code header="reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" /> <docs-code header="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. 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. ## 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 sin ZoneJS (Zoneless) ## ¿Por qué usar Zoneless? Las principales ventajas de eliminar ZoneJS como dependencia son: - **Rendimiento mejorado**: ZoneJS usa eventos del DOM y tareas asíncronas como indicadores de cuándo el estado de la aplicación _podría_ haberse actualizado y posteriormente activa la sincronización de la aplicación para ejecutar la detección de cambios en las vistas de la aplicación. ZoneJS no tiene conocimiento de si el estado de la aplicación realmente cambió, por lo que esta sincronización se activa con más frecuencia de la necesaria. - **Mejores Core Web Vitals**: ZoneJS trae una cantidad considerable de sobrecarga, tanto en tamaño de payload como en costo de tiempo de inicio. - **Mejor experiencia de depuración**: ZoneJS hace que depurar código sea más difícil. Los stack traces son más difíciles de entender con ZoneJS. También es difícil entender cuándo el código falla como resultado de estar fuera de la Angular Zone. - **Mejor compatibilidad con el ecosistema**: ZoneJS funciona parcheando APIs del navegador, pero no tiene automáticamente parches para cada nueva API del navegador. Algunas APIs no pueden ser parcheadas efectivamente, como `async`/`await`, y tienen que ser convertidas a versiones anteriores para funcionar con ZoneJS. A veces, las bibliotecas en el ecosistema también son incompatibles con la forma en que ZoneJS parchea las APIs nativas. Eliminar ZoneJS como dependencia asegura mejor compatibilidad a largo plazo al remover una fuente de complejidad, monkey patching y mantenimiento continuo. ## Habilitar Zoneless en una aplicación ```typescript // bootstrap standalone bootstrapApplication(MyApp, {providers: [ provideZonelessChangeDetection(), ]}); // bootstrap con NgModule platformBrowser().bootstrapModule(AppModule); @NgModule({ providers: [provideZonelessChangeDetection()] }) export class AppModule {} ``` ## Eliminar ZoneJS Las aplicaciones Zoneless deberían eliminar ZoneJS completamente de la compilación para reducir el tamaño del bundle. ZoneJS típicamente se carga a través de la opción `polyfills` en `angular.json`, tanto en los targets `build` como `test`. Elimina `zone.js` y `zone.js/testing` de ambos para removerlo de la compilación. Los proyectos que usan un archivo `polyfills.ts` explícito deberían eliminar `import 'zone.js';` e `import 'zone.js/testing';` del archivo. Después de eliminar ZoneJS de la compilación, ya no hay necesidad de tener `zone.js` como dependencia y el paquete puede ser eliminado completamente: ```shell npm uninstall zone.js ``` ## Requisitos para compatibilidad con Zoneless Angular depende de notificaciones de las APIs principales para determinar cuándo ejecutar la detección de cambios y en qué vistas. Estas notificaciones incluyen: - `ChangeDetectorRef.markForCheck` (llamado automáticamente por `AsyncPipe`) - `ComponentRef.setInput` - Actualizar un signal que se lee en una plantilla - Callbacks de listeners de host o plantilla enlazados - Adjuntar una vista que fue marcada como dirty por alguno de los anteriores ### Componentes compatibles con `OnPush` Una forma de asegurar que un componente está usando los mecanismos de notificación correctos mencionados arriba es usar [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush). La estrategia de detección de cambios `OnPush` no es requerida, pero es un paso recomendado hacia la compatibilidad con zoneless para componentes de aplicación. No siempre es posible para componentes de biblioteca usar `ChangeDetectionStrategy.OnPush`. Cuando un componente de biblioteca es host para componentes de usuario que podrían usar `ChangeDetectionStrategy.Default`, no puede usar `OnPush` porque eso evitaría que el componente hijo se actualice si no es compatible con `OnPush` y depende de ZoneJS para activar la detección de cambios. Los componentes pueden usar la estrategia `Default` siempre que notifiquen a Angular cuando la detección de cambios necesita ejecutarse (llamando a `markForCheck`, usando signals, `AsyncPipe`, etc.). Ser host para un componente de usuario significa usar una API como `ViewContainerRef.createComponent` y no solo alojar una porción de una plantilla de un componente de usuario (es decir, proyección de contenido o usar un template ref como entrada). ### Eliminar `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable` o `NgZone.onStable` Las aplicaciones y bibliotecas necesitan eliminar los usos de `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` y `NgZone.onStable`. Estos observables nunca emitirán cuando una aplicación habilita la detección de cambios zoneless. De manera similar, `NgZone.isStable` siempre será `true` y no debería usarse como condición para la ejecución de código. Los observables `NgZone.onMicrotaskEmpty` y `NgZone.onStable` se usan más frecuentemente para esperar a que Angular complete la detección de cambios antes de realizar una tarea. En su lugar, estos pueden ser reemplazados por `afterNextRender` si necesitan esperar una sola detección de cambios o `afterEveryRender` si hay alguna condición que podría abarcar varias rondas de detección de cambios. En otros casos, estos observables se usaban porque resultaban familiares y tenían un timing similar a lo que se necesitaba. Se pueden usar APIs del DOM más directas en su lugar, como `MutationObserver` cuando el código necesita esperar cierto estado del DOM (en lugar de esperarlo indirectamente a través de los hooks de renderizado de Angular). `NgZone.run` y `NgZone.runOutsideAngular` no necesitan ser eliminados para que el código sea compatible con aplicaciones Zoneless. De hecho, eliminar estas llamadas puede llevar a regresiones de rendimiento para bibliotecas que se usan en aplicaciones que aún dependen de ZoneJS. ### `PendingTasks` para Server Side Rendering (SSR) Si estás usando SSR con Angular, puede que sepas que depende de ZoneJS para ayudar a determinar cuándo la aplicación está "estable" y puede ser serializada. Si hay tareas asíncronas que deberían prevenir la serialización, una aplicación que no usa ZoneJS debe hacer que Angular esté al tanto de estas con el servicio [PendingTasks](/api/core/PendingTasks). La serialización esperará hasta el primer momento en que todas las tareas pendientes hayan sido eliminadas. Los dos usos más directos de las tareas pendientes son el método `run`: ```typescript const taskService = inject(PendingTasks); taskService.run(async () => { const someResult = await doSomeWorkThatNeedsToBeRendered(); this.someState.set(someResult); }); ``` Para casos de uso más complicados, puedes agregar y eliminar manualmente una tarea pendiente: ```typescript const taskService = inject(PendingTasks); const taskCleanup = taskService.add(); try { await doSomeWorkThatNeedsToBeRendered(); } catch { // manejar error } finally { taskCleanup(); } ``` Además, el helper [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent#) en `rxjs-interop` asegura que la aplicación permanezca inestable hasta que el observable emita, complete, tenga un error o se cancele la suscripción. ```typescript readonly myObservableState = someObservable.pipe(pendingUntilEvent()); ``` El framework también usa este servicio internamente para prevenir la serialización hasta que las tareas asíncronas estén completas. Estas incluyen, pero no se limitan a, una navegación del Router en curso y una petición de `HttpClient` incompleta. ## Pruebas y Depuración ### Usar Zoneless en `TestBed` La función provider de zoneless también puede usarse con `TestBed` para ayudar a asegurar que los componentes bajo prueba sean compatibles con una aplicación Angular Zoneless. ```typescript TestBed.configureTestingModule({ providers: [provideZonelessChangeDetection()] }); const fixture = TestBed.createComponent(MyComponent); await fixture.whenStable(); ``` Para asegurar que las pruebas tengan el comportamiento más similar al código de producción, evita usar `fixture.detectChanges()` cuando sea posible. Esto fuerza la ejecución de la detección de cambios cuando Angular de otra manera no habría programado la detección de cambios. Las pruebas deberían asegurar que estas notificaciones están ocurriendo y permitir que Angular maneje cuándo sincronizar el estado en lugar de forzarlo manualmente en la prueba. Para suites de pruebas existentes, usar `fixture.detectChanges()` es un patrón común y probablemente no vale el esfuerzo de convertirlas a `await fixture.whenStable()`. `TestBed` aún aplicará que el componente del fixture sea compatible con `OnPush` y lanzará `ExpressionChangedAfterItHasBeenCheckedError` si encuentra que los valores de la plantilla fueron actualizados sin una notificación de cambio (es decir, `fixture.componentInstance.someValue = 'newValue';`). Si el componente se usa en producción, este problema debería abordarse actualizando el componente para usar signals para el estado o llamar a `ChangeDetectorRef.markForCheck()`. Si el componente solo se usa como wrapper de prueba y nunca se usa en una aplicación, es aceptable usar `fixture.changeDetectorRef.markForCheck()`. ### Verificación en modo debug para asegurar que las actualizaciones se detectan Angular también proporciona una herramienta adicional para ayudar a verificar que una aplicación está haciendo actualizaciones al estado de una manera compatible con zoneless. `provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})` puede usarse para verificar periódicamente que ningún enlace ha sido actualizado sin una notificación. Angular lanza `ExpressionChangedAfterItHasBeenCheckedError` si hay un enlace actualizado que no se habría refrescado por la detección de cambios zoneless. 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. 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', }), ), ] }; ``` ### Deshabilitando 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