Maintenu par une équipe dédiée chez Google, Angular fournit un large ensemble d'outils, d'API et de libraries pour simplifier et fluidifier votre flux de développement. Angular vous donne une plateforme solide sur laquelle créer des applications rapides et fiables, qui grandissent avec la taille de votre équipe comme avec celle de votre base de code. Angular.dev est le site officiel de la documentation d'Angular.

Un aperçu de ce qu'est le développement avec Angular

Des instructions pas à pas dans votre navigateur

Démarrez rapidement avec Angular grâce aux projets en ligne, ou en local avec votre terminal. ## Essayer en ligne {#play-online} Si vous voulez simplement essayer Angular dans votre navigateur sans configurer de projet, vous pouvez utiliser notre bac à sable en ligne : ## Créer un nouveau projet en local {#set-up-a-new-project-locally} Si vous démarrez un nouveau projet, vous voudrez très probablement créer un projet local afin de pouvoir utiliser des outils comme Git. ### Prérequis {#prerequisites} - **Node.js** - [v22.22.3 ou plus récent](/reference/versions) - **Éditeur de texte** - Nous recommandons [Visual Studio Code](https://code.visualstudio.com/) - **Terminal** - Nécessaire pour exécuter les commandes de l'[Angular CLI](/tools/cli) - **Outil de développement** - Pour améliorer votre flux de développement, nous recommandons l'[Angular Language Service](/tools/language-service) ### Instructions {#instructions} Le guide suivant vous accompagne dans la création d'un projet Angular en local. #### Installer l'Angular CLI {#install-angular-cli} Ouvrez un terminal (si vous utilisez [Visual Studio Code](https://code.visualstudio.com/), vous pouvez ouvrir un [terminal intégré](https://code.visualstudio.com/docs/editor/integrated-terminal)) et exécutez la commande suivante : ```shell // npm npm install -g @angular/cli ``` ```shell // pnpm pnpm install -g @angular/cli ``` ```shell // yarn yarn global add @angular/cli ``` ```shell // bun bun install -g @angular/cli ``` Si vous rencontrez des problèmes pour exécuter cette commande sous Windows ou Unix, consultez la [documentation de la CLI](/tools/cli/setup-local#install-the-angular-cli) pour plus d'informations. #### Créer un nouveau projet {#create-a-new-project} Dans votre terminal, exécutez la commande CLI [`ng new`](cli/new) avec le nom de projet souhaité. Dans les exemples suivants, nous utiliserons le nom de projet `my-first-angular-app`. ```shell ng new ``` Plusieurs options de configuration vous seront proposées pour votre projet. Utilisez les flèches et la touche Entrée pour naviguer et sélectionner les options souhaitées. Si vous n'avez pas de préférence, appuyez simplement sur Entrée pour accepter les options par défaut et poursuivre la configuration. Une fois les options de configuration choisies et la configuration terminée par la CLI, vous devriez voir le message suivant : ```text ✔ Packages installed successfully. Successfully initialized git. ``` Vous êtes maintenant prêt à exécuter votre projet en local ! #### Exécuter votre nouveau projet en local {#running-your-new-project-locally} Dans votre terminal, placez-vous dans votre nouveau projet Angular. ```shell cd my-first-angular-app ``` Toutes vos dépendances devraient être installées à ce stade (vous pouvez le vérifier en contrôlant la présence d'un dossier `node_modules` dans votre projet). Vous pouvez donc démarrer votre projet avec la commande : ```shell npm start ``` Si tout se passe bien, vous devriez voir un message de confirmation similaire dans votre terminal : ```text Watch mode enabled. Watching for file changes... NOTE: Raw file sizes do not reflect development server per-request transformations. ➜ Local: http://localhost:4200/ ➜ press h + enter to show help ``` Vous pouvez maintenant ouvrir l'adresse indiquée dans `Local` (par exemple `http://localhost:4200`) pour voir votre application. Bon code ! 🎉 ### Utiliser l'IA pour le développement {#using-ai-for-development} Pour commencer à développer dans votre IDE assisté par IA préféré, [consultez les règles de prompt et les bonnes pratiques Angular](/ai/develop-with-ai). ## Prochaines étapes {#next-steps} Maintenant que vous avez créé votre projet Angular, vous pouvez en apprendre davantage sur Angular avec notre [guide des Fondamentaux](/essentials) ou choisir un sujet dans nos guides approfondis ! # Guide de style Angular ## Introduction {#introduction} Ce guide couvre un ensemble de conventions de style pour le code des applications Angular. Ces recommandations ne sont pas nécessaires au fonctionnement d'Angular, mais établissent plutôt un ensemble de pratiques de code qui favorisent la cohérence dans l'écosystème Angular. Un ensemble cohérent de pratiques facilite le partage de code et le passage d'un projet à l'autre. Ce guide ne couvre _pas_ TypeScript ni les pratiques de code générales sans lien avec Angular. Pour TypeScript, consultez le [guide de style TypeScript de Google](https://google.github.io/styleguide/tsguide.html). ### En cas de doute, privilégiez la cohérence {#when-in-doubt-prefer-consistency} Chaque fois que vous rencontrez une situation où ces règles contredisent le style d'un fichier particulier, donnez la priorité à la cohérence au sein du fichier. Mélanger différentes conventions de style dans un même fichier crée plus de confusion que de s'écarter des recommandations de ce guide. ## Nommage {#naming} ### Séparez les mots des noms de fichiers par des tirets {#separate-words-in-file-names-with-hyphens} Séparez les mots d'un nom de fichier par des tirets (`-`). Par exemple, un composant nommé `UserProfile` a pour nom de fichier `user-profile.ts`. ### Utilisez le même nom pour les tests d'un fichier, avec `.spec` à la fin {#use-the-same-name-for-a-files-tests-with-spec-at-the-end} Pour les tests unitaires, terminez les noms de fichiers par `.spec.ts`. Par exemple, le fichier de test unitaire du composant `UserProfile` a pour nom de fichier `user-profile.spec.ts`. ### Faites correspondre les noms de fichiers à l'identifiant TypeScript qu'ils contiennent {#match-file-names-to-the-typescript-identifier-within} Les noms de fichiers doivent généralement décrire le contenu du code du fichier. Quand le fichier contient une classe TypeScript, le nom du fichier doit refléter le nom de cette classe. Par exemple, un fichier contenant un composant nommé `UserProfile` a pour nom `user-profile.ts`. Si le fichier contient plus d'un identifiant principal nommable, choisissez un nom qui décrit le thème commun du code qu'il contient. Si le code d'un fichier ne relève pas d'un thème ou d'un domaine fonctionnel commun, envisagez de le répartir dans différents fichiers. Évitez les noms de fichiers trop génériques comme `helpers.ts`, `utils.ts` ou `common.ts`. ### Utilisez le même nom de fichier pour le TypeScript, le template et les styles d'un composant {#use-the-same-file-name-for-a-components-typescript-template-and-styles} Les composants se composent généralement d'un fichier TypeScript, d'un fichier de template et d'un fichier de style. Ces fichiers doivent partager le même nom avec des extensions différentes. Par exemple, un composant `UserProfile` peut avoir les fichiers `user-profile.ts`, `user-profile.html` et `user-profile.css`. Si un composant a plus d'un fichier de style, ajoutez au nom des mots supplémentaires qui décrivent les styles propres à ce fichier. Par exemple, `UserProfile` pourrait avoir les fichiers de style `user-profile-settings.css` et `user-profile-subscription.css`. ## Structure du projet {#project-structure} ### Tout le code de l'application se trouve dans un répertoire nommé `src` {#all-the-applications-code-goes-in-a-directory-named-src} Tout votre code d'interface Angular (TypeScript, HTML et styles) doit se trouver dans un répertoire nommé `src`. Le code sans lien avec l'interface, comme les fichiers de configuration ou les scripts, doit se trouver en dehors du répertoire `src`. Cela garde le répertoire racine de l'application cohérent d'un projet Angular à l'autre et crée une séparation claire entre le code d'interface et le reste du code de votre projet. ### Lancez le bootstrap de votre application dans un fichier nommé `main.ts`, directement dans `src` {#bootstrap-your-application-in-a-file-named-maints-directly-inside-src} Le code qui démarre une application Angular, autrement dit son **bootstrap**, doit toujours se trouver dans un fichier nommé `main.ts`. Il représente le point d'entrée principal de l'application. ### Regroupez les fichiers étroitement liés dans le même répertoire {#group-closely-related-files-together-in-the-same-directory} Les composants Angular se composent d'un fichier TypeScript et, éventuellement, d'un template et d'un ou plusieurs fichiers de style. Regroupez-les dans le même répertoire. Les tests unitaires doivent se trouver dans le même répertoire que le code testé. Évitez de rassembler des tests sans rapport entre eux dans un unique répertoire `tests`. ### Organisez votre projet par domaine fonctionnel {#organize-your-project-by-feature-areas} Organisez votre projet en sous-répertoires selon les fonctionnalités de votre application ou les thèmes communs du code de ces répertoires. Par exemple, la structure du projet d'un site de cinéma, MovieReel, pourrait ressembler à ceci : ``` src/ ├─ movie-reel/ │ ├─ show-times/ │ │ ├─ film-calendar/ │ │ ├─ film-details/ │ ├─ reserve-tickets/ │ │ ├─ payment-info/ │ │ ├─ purchase-confirmation/ ``` Évitez de créer des sous-répertoires selon le type de code qu'ils contiennent. Par exemple, évitez de créer des répertoires comme `components`, `directives` et `services`. Évitez de placer tant de fichiers dans un même répertoire qu'il devient difficile à lire ou à parcourir. À mesure que le nombre de fichiers d'un répertoire augmente, envisagez de le découper davantage en sous-répertoires supplémentaires. ### Un concept par fichier {#one-concept-per-file} Privilégiez des fichiers source centrés sur un seul _concept_. Pour les classes Angular en particulier, cela signifie généralement un composant, une directive ou un service par fichier. Il est toutefois acceptable qu'un fichier contienne plus d'un composant ou d'une directive si vos classes sont relativement petites et qu'elles forment ensemble un seul et même concept. En cas de doute, choisissez l'approche qui conduit à des fichiers plus petits. ## Injection de dépendances {#dependency-injection} ### Préférez la fonction `inject` à l'injection par paramètres du constructeur {#prefer-the-inject-function-over-constructor-parameter-injection} Préférez la fonction [`inject`](/api/core/inject) à l'injection par paramètres du constructeur. La fonction [`inject`](/api/core/inject) fonctionne de la même façon que l'injection par paramètres du constructeur, mais offre plusieurs avantages de style : - [`inject`](/api/core/inject) est généralement plus lisible, surtout quand une classe injecte de nombreuses dépendances. - Il est syntaxiquement plus simple d'ajouter des commentaires aux dépendances injectées - [`inject`](/api/core/inject) offre une meilleure inférence de types. - Quand vous ciblez ES2022+ avec [`useDefineForClassFields`](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields), vous évitez de séparer la déclaration et l'initialisation des champs lorsque ceux-ci lisent des dépendances injectées. [Vous pouvez refactoriser le code existant vers `inject` avec un outil automatique](reference/migrations/inject-function). ## Composants et directives {#components-and-directives} ### Choisir les selectors des composants {#choosing-component-selectors} Consultez le [guide des composants pour savoir comment choisir les selectors des composants](guide/components/selectors#choosing-a-selector). ### Nommer les membres des composants et des directives {#naming-component-and-directive-members} Consultez le guide des composants pour en savoir plus sur le [nommage des propriétés d'input](guide/components/inputs#choosing-input-names) et le [nommage des propriétés d'output](guide/components/outputs#choosing-event-names). ### Choisir les selectors des directives {#choosing-directive-selectors} Les directives doivent utiliser le même [préfixe propre à l'application](guide/components/selectors#selector-prefixes) que vos composants. Quand vous utilisez un attribute selector pour une directive, utilisez un nom d'attribut en camelCase. Par exemple, si votre application s'appelle « MovieReel » et que vous créez une directive qui ajoute une infobulle à un élément, vous pourriez utiliser le selector `[mrTooltip]`. ### Regroupez les propriétés propres à Angular avant les méthodes {#group-angular-specific-properties-before-methods} Les composants et les directives doivent regrouper les propriétés propres à Angular, généralement vers le haut de la déclaration de la classe. Cela inclut les dépendances injectées, les inputs, les outputs et les queries. Définissez ces propriétés, ainsi que les autres, avant les méthodes de la classe. Cette pratique permet de trouver plus facilement les API de template et les dépendances de la classe. ### Concentrez les composants et les directives sur la présentation {#keep-components-and-directives-focused-on-presentation} Le code de vos composants et de vos directives doit généralement concerner l'interface affichée sur la page. Pour le code qui a du sens par lui-même, découplé de l'interface, préférez le déplacer dans d'autres fichiers. Par exemple, vous pouvez extraire les règles de validation de formulaire ou les transformations de données dans des fonctions ou des classes séparées. ### Évitez une logique trop complexe dans les templates {#avoid-overly-complex-logic-in-templates} Les templates Angular sont conçus pour accueillir des [expressions proches de JavaScript](guide/templates/expression-syntax). Tirez parti de ces expressions pour exprimer une logique relativement simple directement dans les expressions de template. Cependant, quand le code d'un template devient trop complexe, déplacez la logique dans le code TypeScript (généralement avec un [computed](guide/signals#computed-signals)). Il n'existe pas de règle stricte et définitive qui détermine ce qui est « complexe ». Faites preuve de discernement. ### Utilisez `protected` pour les membres de classe utilisés uniquement par le template d'un composant {#use-protected-on-class-members-that-are-only-used-by-a-components-template} Les membres publics d'une classe de composant définissent intrinsèquement une API publique accessible via l'injection de dépendances et les [queries](guide/components/queries). Préférez l'accès `protected` pour tous les membres destinés à être lus depuis le template du composant. ```ts @Component({ ..., template: `

`, }) export class UserProfile { firstName = input(); lastName = input(); // `fullName` is not part of the component's public API, but is used in the template. protected fullName = computed(() => `${this.firstName()} ${this.lastName()}`); } ``` ### Utilisez `readonly` pour les propriétés qui ne doivent pas changer {#use-readonly-for-properties-that-shouldnt-change} Marquez comme `readonly` les propriétés des composants et des directives initialisées par Angular. Cela inclut les propriétés initialisées par `input`, `model`, `output` et les queries. Le modificateur d'accès readonly garantit que la valeur définie par Angular n'est pas écrasée. ```ts @Component(/* ... */) export class UserProfile { readonly userId = input(); readonly userSaved = output(); readonly userName = model(); } ``` Pour les composants et les directives qui utilisent les API `@Input`, `@Output` et de query à base de décorateurs, ce conseil s'applique aux propriétés d'output et aux queries, mais pas aux propriétés d'input. ```ts @Component(/* ... */) export class UserProfile { @Output() readonly userSaved = new EventEmitter(); @ViewChildren(PaymentMethod) readonly paymentMethods?: QueryList; } ``` ### Préférez `class` et `style` à `ngClass` et `ngStyle` {#prefer-class-and-style-over-ngclass-and-ngstyle} Préférez les bindings `class` et `style` aux directives [`NgClass`](/api/common/NgClass) et [`NgStyle`](/api/common/NgStyle). ```html {prefer}

``` ```html {avoid}

``` Les bindings `class` et `style` utilisent tous deux une syntaxe plus simple, très proche des attributs HTML standard. Vos templates sont ainsi plus faciles à lire et à comprendre, en particulier pour les développeurs qui connaissent les bases du HTML. De plus, les directives `NgClass` et `NgStyle` entraînent un coût de performance supplémentaire par rapport à la syntaxe de binding `class` et `style` intégrée. Pour plus de détails, consultez le [guide des bindings](/guide/templates/binding#css-class-and-style-property-bindings) ### Nommez les event handlers d'après ce qu'ils _font_, pas d'après l'événement déclencheur {#name-event-handlers-for-what-they-do-not-for-the-triggering-event} Préférez nommer les event handlers d'après l'action qu'ils effectuent plutôt que d'après l'événement déclencheur : ```html {prefer} ``` ```html {avoid} ``` Des noms parlants comme celui-ci permettent de comprendre plus facilement ce que fait un événement en lisant le template. Pour les événements clavier, vous pouvez utiliser les modificateurs d'événements clavier d'Angular avec des noms de handlers précis : ```html

```

Parfois, la logique de gestion d'un événement est particulièrement longue ou complexe, ce qui rend peu pratique la déclaration d'un
seul handler bien nommé. Dans ces cas, vous pouvez vous rabattre sur un nom comme 'handleKeydown' puis
déléguer à des comportements plus précis selon les détails de l'événement :

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

### Gardez les méthodes de cycle de vie simples {#keep-lifecycle-methods-simple}

Évitez de placer une logique longue ou complexe dans les lifecycle hooks comme `ngOnInit`. Préférez plutôt créer
des méthodes bien nommées pour contenir cette logique, puis _appeler ces méthodes_ dans vos lifecycle hooks.
Les noms des lifecycle hooks décrivent _quand_ ils s'exécutent, ce qui signifie que le code qu'ils contiennent n'a pas de
nom parlant qui décrit ce qu'il fait.

```ts
{prefer}
ngOnInit() {
  this.startLogging();
  this.runBackgroundTask();
}
```

```ts
{avoid}
ngOnInit() {
  this.logger.setMode('info');
  this.logger.monitorErrors();
  // ...and all the rest of the code that would be unrolled from these methods.
}
```

### Utilisez les interfaces des lifecycle hooks {#use-lifecycle-hook-interfaces}

Angular fournit une interface TypeScript pour chaque méthode de cycle de vie. Quand vous ajoutez un lifecycle hook à
votre classe, importez et implémentez (`implement`) ces interfaces pour garantir que les méthodes sont correctement nommées.

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

@Component(/* ... */)
export class UserProfile implements OnInit {
  // The `OnInit` interface ensures this method is named correctly.
  ngOnInit() {
    /* ... */
  }
}
```
Les composants sont les principales briques des applications Angular. Chaque composant représente une partie d'une page web plus grande. Organiser une application en composants aide à structurer votre projet, en séparant clairement le code en parties spécifiques, faciles à maintenir et à faire évoluer.

## Définir un composant {#defining-a-component}

Chaque composant comporte quelques parties principales :

1. Un [décorateur](https://www.typescriptlang.org/docs/handbook/decorators.html) `@Component` qui contient la configuration utilisée par Angular.
2. Un template HTML qui contrôle ce qui est rendu dans le DOM.
3. Un [selector CSS](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors) qui définit comment le composant est utilisé dans le HTML.
4. Une classe TypeScript avec des comportements, comme la gestion des saisies de l'utilisateur ou l'envoi de requêtes à un serveur.

Voici un exemple simplifié d'un composant `UserProfile`.

```typescript
{header: "user-profile.ts"}
@Component({
  selector: 'user-profile',
  template: `
    <h1>User profile</h1>
    <p>This is the user profile page</p>
  `,
})
export class UserProfile {
  /* Your component code goes here */
}
```

Le décorateur `@Component` accepte aussi, de façon facultative, une propriété `styles` pour le CSS que vous souhaitez appliquer à votre template :

```typescript
{header: "user-profile.ts"}
@Component({
  selector: 'user-profile',
  template: `
    <h1>User profile</h1>
    <p>This is the user profile page</p>
  `,
  styles: `
    h1 {
      font-size: 3em;
    }
  `,
})
export class UserProfile {
  /* Your component code goes here */
}
```

### Séparer le HTML et le CSS dans des fichiers distincts {#separating-html-and-css-into-separate-files}

Vous pouvez définir le HTML et le CSS d'un composant dans des fichiers distincts avec `templateUrl` et `styleUrl` :

```typescript
{header: "user-profile.ts"}
@Component({
  selector: 'user-profile',
  templateUrl: 'user-profile.html',
  styleUrl: 'user-profile.css',
})
export class UserProfile {
  // Component behavior is defined in here
}
```

```html
{header: "user-profile.html"}
<h1>User profile</h1>
<p>This is the user profile page</p>
```

```css
{header: "user-profile.css"}
h1 {
  font-size: 3em;
}
```

## Utiliser des composants {#using-components}

Vous construisez une application en composant plusieurs composants entre eux. Par exemple, si vous créez une page de profil utilisateur, vous pourriez découper la page en plusieurs composants comme ceci :

```mermaid
flowchart TD
    A[UserProfile]-->B
    A-->C
    B[UserBiography]-->D
    C[ProfilePhoto]
    D[UserAddress]
```

Ici, le composant `UserProfile` utilise plusieurs autres composants pour produire la page finale.

Pour importer et utiliser un composant, vous devez :

1. Dans le fichier TypeScript de votre composant, ajouter une instruction `import` pour le composant que vous voulez utiliser.
2. Dans votre décorateur `@Component`, ajouter une entrée au tableau `imports` pour le composant que vous voulez utiliser.
3. Dans le template de votre composant, ajouter un élément qui correspond au selector du composant que vous voulez utiliser.

Voici un exemple d'un composant `UserProfile` qui importe un composant `ProfilePhoto` :

```typescript
{header: "user-profile.ts"}
import {Component} from '@angular/core';
import {ProfilePhoto} from './profile-photo';

@Component({
  selector: 'user-profile',
  imports: [ProfilePhoto],
  template: `
    <h1>User profile</h1>
    <profile-photo />
    <p>This is the user profile page</p>
  `,
})
export class UserProfile {
  // Component behavior is defined in here
}
```

TIP: Vous voulez en savoir plus sur les composants Angular ? Consultez le [guide approfondi des composants](guide/components) pour tous les détails.

## Étape suivante {#next-step}

Maintenant que vous savez comment fonctionnent les composants dans Angular, il est temps d'apprendre à ajouter et gérer des données dynamiques dans votre application.
# Selectors de composants

TIP: Ce guide suppose que vous avez déjà lu le [guide des Fondamentaux](essentials). Commencez par celui-ci si vous découvrez Angular.

Chaque composant définit
un [selector CSS](https://developer.mozilla.org/docs/Web/CSS/CSS_selectors) qui détermine comment
le composant est utilisé :

```typescript
{highlight: [2]}
@Component({
  selector: 'profile-photo',
  ...
})
export class ProfilePhoto { }
```

Vous utilisez un composant en créant un élément HTML correspondant dans les templates d'_autres_ composants :

```typescript
{highlight: [3]}
@Component({
  template: `
    <profile-photo />
    <button>Upload a new profile photo</button>`,
  ...,
})
export class UserProfile { }
```

**Angular fait correspondre les selectors de manière statique, à la compilation**. Modifier le DOM à l'exécution, que ce soit via
des bindings Angular ou avec les API du DOM, n'a aucun effet sur les composants rendus.

**Un élément ne peut correspondre qu'à un seul selector de composant.** Si plusieurs selectors de composants correspondent à un
même élément, Angular signale une erreur.

**Les selectors de composants sont sensibles à la casse.**

## Types de selectors {#types-of-selectors}

Angular prend en charge un sous-ensemble limité
des [types de selectors CSS de base](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) dans
les selectors de composants :

| **Type de selector** | **Description** | **Exemples** |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Selector de type | Sélectionne les éléments selon leur nom de balise HTML, ou nom de nœud. | `profile-photo` |
| Selector d'attribute | Sélectionne les éléments selon la présence d'un attribut HTML et, de façon facultative, une valeur exacte pour cet attribut. | `[dropzone]` `[type="reset"]` |
| Selector de classe | Sélectionne les éléments selon la présence d'une classe CSS. | `.menu-item` |

Pour les valeurs d'attribut, Angular permet de faire correspondre une valeur d'attribut exacte avec l'opérateur d'égalité (`=`).
Angular ne prend pas en charge les autres opérateurs de valeur d'attribut.

Les selectors de composants Angular ne prennent pas en charge les combinateurs, notamment
le [combinateur de descendance](https://developer.mozilla.org/docs/Web/CSS/Descendant_combinator)
ou le [combinateur d'enfant](https://developer.mozilla.org/docs/Web/CSS/Child_combinator).

Les selectors de composants Angular ne permettent pas
de spécifier des [namespaces](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course).

### La pseudo-classe `:not` {#the-not-pseudo-class}

Angular prend en charge [la pseudo-classe `:not`](https://developer.mozilla.org/docs/Web/CSS/:not).
Vous pouvez ajouter cette pseudo-classe à n'importe quel autre selector pour restreindre les éléments auxquels le
selector d'un composant correspond. Par exemple, vous pourriez définir un selector d'attribute `[dropzone]` et empêcher
la correspondance avec les éléments `textarea` :

```typescript
{highlight: [2]}
@Component({
  selector: '[dropzone]:not(textarea)',
  ...
})
export class DropZone { }
```

Angular ne prend en charge aucune autre pseudo-classe ni aucun pseudo-élément dans les selectors de composants.

### Combiner des selectors {#combining-selectors}

Vous pouvez combiner plusieurs selectors en les concaténant. Par exemple, vous pouvez cibler les éléments `<button>`
qui spécifient `type="reset"` :

```typescript
{highlight: [2]}
@Component({
  selector: 'button[type="reset"]',
  ...
})
export class ResetButton { }
```

Vous pouvez aussi définir plusieurs selectors avec une liste séparée par des virgules :

```typescript
{highlight: [2]}
@Component({
  selector: 'drop-zone, [dropzone]',
  ...
})
export class DropZone { }
```

Angular crée un composant pour chaque élément qui correspond à _l'un quelconque_ des selectors de la liste.

## Choisir un selector {#choosing-a-selector}

La grande majorité des composants devraient utiliser un nom de custom element comme selector. Tous les noms
de custom elements devraient inclure un tiret, comme le décrit
[la spécification HTML](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name).
Par défaut, Angular signale une erreur s'il rencontre un nom de balise personnalisé qui ne correspond à aucun
composant disponible, ce qui évite les bugs dus à des noms de composants mal orthographiés.

Consultez [Configuration avancée des composants](guide/components/advanced-configuration) pour plus de détails sur
l'utilisation des [custom elements natifs](https://developer.mozilla.org/docs/Web/Web_Components) dans
les templates Angular.

### Préfixes de selectors {#selector-prefixes}

L'équipe Angular recommande d'utiliser un préfixe court et cohérent pour tous les composants personnalisés
définis dans votre projet. Par exemple, si vous deviez construire YouTube avec Angular, vous pourriez
préfixer vos composants avec `yt-`, avec des composants comme `yt-menu`, `yt-player`, etc. Placer
vos selectors dans un namespace de cette façon indique immédiatement d'où vient un composant donné. Par
défaut, l'Angular CLI utilise `app-`.

IMPORTANT: Angular utilise le préfixe de selector `ng` pour ses propres API du framework. N'utilisez jamais `ng` comme préfixe de selector pour vos propres composants personnalisés.

### Quand utiliser un selector d'attribute {#when-to-use-an-attribute-selector}

Envisagez un selector d'attribute quand vous souhaitez créer un composant sur un élément natif
standard. Par exemple, si vous souhaitez créer un composant de bouton personnalisé, vous pouvez tirer parti de
l'élément standard `<button>` en utilisant un selector d'attribute :

```typescript
{highlight: [2]}
@Component({
  selector: 'button[yt-upload]',
   ...
})
export class YouTubeUploadButton { }
```

Cette approche permet aux consommateurs du composant d'utiliser directement toutes les API standard de l'élément
sans travail supplémentaire. C'est particulièrement utile pour les attributs ARIA comme `aria-label`.

Angular ne signale pas d'erreur quand il rencontre des attributs personnalisés qui ne correspondent à aucun
composant disponible. Lorsqu'ils utilisent des composants avec des selectors d'attribute, les consommateurs peuvent oublier d'importer le
composant ou son NgModule, ce qui empêche le rendu du composant.
Consultez [Importer et utiliser des composants](guide/components#imports-in-the-component-decorator) pour plus d'informations.

Les composants qui définissent des selectors d'attribute devraient utiliser des attributs en minuscules et en dash-case. Vous pouvez
suivre la même recommandation de préfixe décrite ci-dessus.
# Styliser les composants

TIP: Ce guide suppose que vous avez déjà lu le [guide des Fondamentaux](essentials). Commencez par celui-ci si vous découvrez Angular.

Les composants peuvent, de façon facultative, inclure des styles CSS qui s'appliquent au DOM de ce composant :

```typescript
{highlight:[4]}
@Component({
  selector: 'profile-photo',
  template: `<img src="profile-photo.jpg" alt="Your profile photo" />`,
  styles: `
    img {
      border-radius: 50%;
    }
  `,
})
export class ProfilePhoto {}
```

Vous pouvez aussi choisir d'écrire vos styles dans des fichiers distincts :

```typescript
{highlight:[4]}
@Component({
  selector: 'profile-photo',
  templateUrl: 'profile-photo.html',
  styleUrl: 'profile-photo.css',
})
export class ProfilePhoto {}
```

Quand Angular compile votre composant, ces styles sont émis avec la sortie JavaScript de votre
composant. Cela signifie que les styles de composant participent au système de modules JavaScript. Quand vous
rendez un composant Angular, le framework inclut automatiquement les styles qui lui sont associés, même lors du
lazy loading d'un composant.

Angular fonctionne avec n'importe quel outil qui produit du CSS,
notamment [Sass](https://sass-lang.com), [Less](https://lesscss.org)
et [Stylus](https://stylus-lang.com).

## Portée des styles {#style-scoping}

Chaque composant possède un paramètre d'**encapsulation des vues** qui détermine comment le framework limite la portée des
styles d'un composant. Il existe quatre modes d'encapsulation des vues : `Emulated`, `ShadowDom`, `ExperimentalIsolatedShadowDom` et `None`.
Vous pouvez spécifier le mode dans le décorateur `@Component` :

```typescript
{highlight:[3]}
@Component({
  ...,
  encapsulation: ViewEncapsulation.None,
})
export class ProfilePhoto { }
```

### ViewEncapsulation.Emulated {#viewencapsulationemulated}

Par défaut, Angular utilise l'encapsulation émulée pour que les styles d'un composant ne s'appliquent qu'aux éléments
définis dans le template de ce composant. Dans ce mode, le framework génère un attribut HTML unique
pour chaque instance de composant, ajoute cet attribut aux éléments du template du composant et
insère cet attribut dans les selectors CSS définis dans les styles de votre composant.

Ce mode garantit que les styles d'un composant ne débordent pas et n'affectent pas les autres composants. En revanche,
les styles globaux définis en dehors d'un composant peuvent tout de même affecter les éléments à l'intérieur d'un composant qui utilise
l'encapsulation émulée.

En mode émulé, Angular prend en charge
la pseudo-classe [`:host`](https://developer.mozilla.org/docs/Web/CSS/:host).
Bien que la pseudo-classe [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context)
soit dépréciée dans les navigateurs modernes, le compilateur d'Angular la prend entièrement en charge. Les deux pseudo-classes
peuvent être utilisées sans dépendre du
[Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM) natif.
Pendant la compilation, le framework transforme ces pseudo-classes en attributs, si bien qu'elles ne
suivent pas les règles de ces pseudo-classes natives à l'exécution (par exemple la compatibilité des navigateurs ou la spécificité). Le mode
d'encapsulation émulée d'Angular ne prend en charge aucune autre pseudo-classe liée au Shadow DOM, comme
`::shadow` ou `::part`.

#### `::ng-deep` {#ng-deep}

Le mode d'encapsulation émulée d'Angular prend en charge une pseudo-classe personnalisée, `::ng-deep`.
**L'équipe Angular déconseille fortement toute nouvelle utilisation de `::ng-deep`**. Ces API sont conservées
uniquement pour la rétrocompatibilité.

Quand un selector contient `::ng-deep`, Angular cesse d'appliquer les limites de l'encapsulation des vues à partir de ce point du selector. Toute partie du selector qui suit `::ng-deep` peut correspondre à des éléments situés en dehors du template du composant.

Par exemple :

- un selector de règle CSS comme `p a`, avec l'encapsulation émulée, correspondra aux éléments `<a>` descendants d'un élément `<p>`,
  tous deux situés dans le template du composant lui-même.

- Un selector comme `::ng-deep p a` correspondra aux éléments `<a>` situés n'importe où dans l'application, descendants d'un élément `<p>` situé n'importe où dans l'application.

Il se comporte donc en pratique comme un style global.

- Dans `p ::ng-deep a`, Angular exige que l'élément `<p>` provienne du template du composant lui-même, mais l'élément `<a>` peut se trouver n'importe où dans l'application.

En pratique, l'élément `<a>` peut donc se trouver dans le template du composant, ou dans n'importe lequel de ses contenus projetés ou enfants.

- Avec `:host ::ng-deep p a`, les éléments `<a>` et `<p>` doivent tous deux être des descendants du host element du composant.

Ils peuvent provenir du template du composant ou des vues de ses composants enfants, mais pas d'ailleurs dans l'application.

### ViewEncapsulation.ShadowDom {#viewencapsulationshadowdom}

Ce mode limite la portée des styles à l'intérieur d'un composant en
utilisant [l'API standard du web Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM).
Quand vous activez ce mode, Angular attache une shadow root au host element du composant et rend
le template et les styles du composant dans le shadow tree correspondant.

Les styles à l'intérieur du shadow tree ne peuvent pas affecter les éléments situés en dehors de ce shadow tree.

Activer l'encapsulation `ShadowDom` a toutefois des conséquences qui vont au-delà de la portée des styles. Rendre le
composant dans un shadow tree affecte la propagation des événements, l'interaction
avec [l'API `<slot>`](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots)
et la façon dont les outils de développement du navigateur affichent les éléments. Comprenez toujours toutes les implications de l'utilisation du
Shadow DOM dans votre application avant d'activer cette option.

### ViewEncapsulation.ExperimentalIsolatedShadowDom {#viewencapsulationexperimentalisolatedshadowdom}

Se comporte comme ci-dessus, sauf que ce mode garantit strictement que _seuls_ les styles de ce composant s'appliquent aux éléments du
template du composant. Les styles globaux ne peuvent pas affecter les éléments d'un shadow tree et les styles à l'intérieur du
shadow tree ne peuvent pas affecter les éléments situés en dehors de ce shadow tree.

### ViewEncapsulation.None {#viewencapsulationnone}

Ce mode désactive toute encapsulation des styles pour le composant. Tous les styles associés au
composant se comportent comme des styles globaux.

NOTE: Dans les modes `Emulated` et `ShadowDom`, Angular ne garantit pas à 100 % que les styles de votre composant remplaceront toujours les styles provenant de l'extérieur.
On suppose que ces styles ont la même spécificité que les styles de votre composant en cas de conflit.

## Définir des styles dans les templates {#defining-styles-in-templates}

Vous pouvez utiliser l'élément `<style>` dans le template d'un composant pour définir des styles supplémentaires. Le
mode d'encapsulation des vues du composant s'applique aux styles définis de cette façon.

Angular ne prend pas en charge les bindings à l'intérieur des éléments style.

## Référencer des fichiers de style externes {#referencing-external-style-files}

Les templates de composant peuvent
utiliser [l'élément `<link>`](https://developer.mozilla.org/docs/Web/HTML/Element/link) pour
référencer des fichiers CSS. De plus, votre CSS peut
utiliser [la règle `@import`](https://developer.mozilla.org/docs/Web/CSS/@import) pour référencer
des fichiers CSS. Angular traite ces références comme des styles _externes_. Les styles externes ne sont pas affectés par
l'encapsulation des vues émulée.

## Appliquer un namespace aux propriétés personnalisées CSS {#namespacing-css-custom-properties}

Angular peut ajouter un préfixe aux propriétés personnalisées CSS (aussi appelées variables CSS) que les
styles de votre composant déclarent et lisent. Les propriétés personnalisées sont héritées le long de l'arbre du DOM, donc quand quelque chose
en dehors de votre application définit une propriété personnalisée comme `--primary-color` sur un élément
ancêtre, vos composants lisent cette valeur. Cela compte quand votre application partage une page avec une autre
application ou avec du balisage que vous ne contrôlez pas. Angular n'applique pas de namespace aux propriétés personnalisées tant que
vous ne le lui demandez pas, et une application qui possède sa page n'a pas besoin de namespace.

Pour limiter la portée des propriétés personnalisées des styles de vos composants à votre application, ajoutez
[`provideCssVarNamespacing`](api/platform-browser/provideCssVarNamespacing) aux providers de votre
application. Il utilise l'[`APP_ID`](api/core/APP_ID) de l'application comme namespace :

```ts
{header: "app.config.ts"}
import {APP_ID, ApplicationConfig} from '@angular/core';
import {provideCssVarNamespacing} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [{provide: APP_ID, useValue: 'my-app'}, provideCssVarNamespacing()],
};
```

Angular préfixe les propriétés personnalisées des styles de vos composants avec ce namespace suivi d'un
tiret bas, si bien que `--primary-color` devient `--my-app_primary-color`. Le préfixe s'applique aux
déclarations, aux références `var()`, aux règles `@property` et aux style bindings comme
`[style.--primary-color]`, y compris les style bindings qu'un composant déclare dans son objet `host`.

`APP_ID` vaut `ng` sauf si vous le définissez, donc donnez à chaque application de la page son propre `APP_ID`.
Sinon, les applications partagent un préfixe et entrent de nouveau en conflit. Pour utiliser un namespace différent de
l'identifiant de l'application, passez-le à `provideCssVarNamespacing`. Angular ajoute lui-même le tiret bas :
`provideCssVarNamespacing('my-app_')` produit `--my-app__primary-color`.

Angular applique le namespace aux styles qu'il compile dans un composant : les `styles` et le `styleUrl` du
composant, les styles que vous [écrivez dans un élément `<style>`](#defining-styles-in-templates) de son
template, les feuilles de style que son template référence avec un `<link rel="stylesheet">` relatif, et
les styles d'un composant qui utilise `ViewEncapsulation.None`. Angular n'applique pas de namespace à une feuille de style que le navigateur
charge à l'exécution, comme une feuille de style globale listée dans votre configuration de build ou un
[style externe](#referencing-external-style-files) que votre build n'intègre pas.

Le namespace s'applique à chaque composant compilé par Angular, y compris les composants des libraries
que vous installez. Quand les styles d'une library lisent une propriété personnalisée définie par une feuille de style globale, comme
les propriétés d'un thème, la référence ne correspond plus, le navigateur utilise la valeur de repli de `var()`
s'il y en a une ou, à défaut,
[la valeur héritée ou initiale de la propriété](https://www.w3.org/TR/css-variables-1/#invalid-variables),
et aucune erreur n'est signalée. Avant d'activer le namespace dans une
application existante, passez en revue les propriétés personnalisées partagées entre vos feuilles de style globales et
vos composants.

IMPORTANT: Angular ne réécrit les noms des propriétés personnalisées que dans les styles et les bindings qu'il compile.
Partout ailleurs, le nom que vous écrivez est conservé, et rien ne signale l'incohérence.

Angular ne réécrit pas le nom dans :

- Les attributs de style statiques, comme `style="--primary-color: red"`, y compris l'entrée `style` de l'objet
  `host` d'un composant.
- Les style bindings sous forme d'objet ou de chaîne, comme `[style]="{'--primary-color': color}"`,
  `[style]="'--primary-color: red'"` et `ngStyle`, y compris l'entrée `[style]` de l'objet `host`
  d'un composant.
- Les noms de propriétés personnalisées à l'intérieur de la valeur d'un binding, comme
  `[style.border-color]="'var(--primary-color)'"`.
- Les appels à `Renderer2.setStyle`.

Chacun de ces cas produit une propriété que vos styles avec namespace ne lisent plus. Appliquez vous-même le namespace à ces
noms, comme décrit dans
[Utiliser les propriétés avec namespace en TypeScript](#using-namespaced-properties-in-typescript).

### Exclure des propriétés du namespace {#opting-out-of-namespacing}

Pour déclarer ou lire une propriété personnalisée à laquelle Angular n'applique pas de namespace, comme une propriété définie dans une
feuille de style globale, préfixez son nom par `--global--`. Angular retire `--global` et laisse inchangés
le `--` restant et le reste du nom :

```css
:host {
  /* Declares --accent-color and reads --brand-color, not --my-app_brand-color. */
  --global--accent-color: navy;
  color: var(--global--brand-color);
}
```

Écrivez deux tirets après `global`. Un seul tiret, comme dans `--global-brand-color`, ne suffit pas à exclure la propriété,
et Angular applique le namespace à ce nom comme à n'importe quel autre. Évitez les noms qui commencent par `--global-` suivi
d'autre chose qu'un second tiret ; une future version majeure prévoit de les rejeter au moment du build.
Angular retire `--global` dans toutes les applications, y compris celles qui ne configurent jamais
de namespace.

### Utiliser les propriétés avec namespace en TypeScript {#using-namespaced-properties-in-typescript}

Préférez un style binding comme `[style.--primary-color]`, auquel Angular applique le namespace pour vous. Quand
vous passez plutôt par une API du DOM, passez le nom que vous avez écrit dans vos styles à
[`CssVarNamespacer`](api/platform-browser/CssVarNamespacer), y compris le `--` initial :

```typescript
{header: "profile-photo.ts"}
import {Component, ElementRef, inject} from '@angular/core';
import {CssVarNamespacer} from '@angular/platform-browser';

@Component({
  selector: 'profile-photo',
  template: `<img src="profile-photo.jpg" alt="Your profile photo" />`,
  styles: `
    img {
      border: 2px solid var(--primary-color);
    }
  `,
})
export class ProfilePhoto {
  private readonly host: HTMLElement = inject(ElementRef).nativeElement;
  private readonly cssVarNamespacer = inject(CssVarNamespacer);

setPrimaryColor(color: string): void {
    this.host.style.setProperty(this.cssVarNamespacer.namespace('--primary-color'), color);
  }
}
```

Utilisez le nom simple pour une propriété que vous avez déclarée avec `--global--`, car Angular ne leur applique jamais
de namespace. Pour tout le reste, `namespace` renvoie le nom inchangé quand une application ne configure
aucun namespace, si bien qu'une library peut l'appeler pour les propriétés personnalisées que ses propres styles déclarent.
# Accepter des données avec les propriétés d'input

TIP: Ce guide suppose que vous avez déjà lu le [guide des Fondamentaux](essentials). Commencez par celui-ci si vous découvrez Angular. Si vous connaissez d'autres frameworks web, les propriétés d'input sont similaires aux _props_.

Quand vous utilisez un composant, vous souhaitez généralement lui transmettre des données. Un composant spécifie les données qu'il accepte en déclarant
des **inputs** :

```ts
{highlight:[6]}
import {Component, input} from '@angular/core';

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

Cela vous permet de lier la propriété dans un template :

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

Si un input a une valeur par défaut, TypeScript déduit le type à partir de cette valeur par défaut :

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

Vous pouvez déclarer explicitement un type pour l'input en spécifiant un paramètre générique à la fonction.

Si un input sans valeur par défaut n'est pas défini, sa valeur est `undefined` :

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

**Angular enregistre les inputs de manière statique, à la compilation**. Les inputs ne peuvent pas être ajoutés ni supprimés à l'exécution.

La fonction `input` a une signification particulière pour le compilateur Angular. **Vous pouvez appeler `input` exclusivement dans les initialiseurs de propriétés des composants et des directives.**

Quand vous étendez une classe de composant, **les inputs sont hérités par la classe enfant.**

**Les noms des inputs sont sensibles à la casse.**

## Lire les inputs {#reading-inputs}

La fonction `input` renvoie un `InputSignal`. Vous pouvez lire la valeur en appelant le signal :

```ts
{highlight:[9]}
import {Component, input, computed} from '@angular/core';

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

// Create a computed expression that reads the value input
  label = computed(() => `The slider's value is ${this.value()}`);
}
```

Les signals créés par la fonction `input` sont en lecture seule.

## Inputs obligatoires {#required-inputs}

Vous pouvez déclarer qu'un input est obligatoire (`required`) en appelant `input.required` au lieu de `input` :

```ts
{highlight:[4]}
@Component(/* ... */)
export class CustomSlider {
  // Declare a required input named value. Returns an `InputSignal<number>`.
  value = input.required<number>();
}
```

Angular impose que les inputs obligatoires _doivent_ être définis quand le composant est utilisé dans un template. Si vous essayez d'utiliser un composant sans spécifier tous ses inputs obligatoires, Angular signale une erreur au moment du build.

Les inputs obligatoires n'incluent pas automatiquement `undefined` dans le paramètre générique de l'`InputSignal` renvoyé.

## Configurer les inputs {#configuring-inputs}

La fonction `input` accepte en second paramètre un objet de configuration qui vous permet de modifier le fonctionnement de l'input.

### Transformations d'input {#input-transforms}

Vous pouvez spécifier une fonction `transform` pour modifier la valeur d'un input quand elle est définie par 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" />
```

Dans l'exemple ci-dessus, chaque fois que la valeur de `systemVolume` change, Angular exécute `trimString` et affecte le résultat à `label`.

Le cas d'usage le plus courant des transformations d'input est d'accepter un éventail plus large de types de valeurs dans les templates, incluant souvent `null` et `undefined`.

**Une fonction de transformation d'input doit pouvoir être analysée statiquement au moment du build.** Vous ne pouvez pas définir des fonctions de transformation de façon conditionnelle ni comme résultat de l'évaluation d'une expression.

**Les fonctions de transformation d'input devraient toujours être des [fonctions pures](https://en.wikipedia.org/wiki/Pure_function).** Dépendre d'un état extérieur à la fonction de transformation peut entraîner un comportement imprévisible.

#### Vérification de type {#type-checking}

Quand vous spécifiez une transformation d'input, le type du paramètre de la fonction de transformation détermine les types de valeurs qui peuvent être affectées à l'input dans un template.

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

function appendPx(value: number): string {
  return `${value}px`;
}
```

Dans l'exemple ci-dessus, l'input `widthPx` accepte un `number` alors que la propriété `InputSignal` renvoie une `string`.

#### Transformations intégrées {#built-in-transformations}

Angular inclut deux fonctions de transformation intégrées pour les deux scénarios les plus courants : la conversion de valeurs en booléens et en nombres.

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

@Component(/* ... */)
export class CustomSlider {
  disabled = input(false, {transform: booleanAttribute});
  value = input(0, {transform: numberAttribute});
}
```

`booleanAttribute` imite le comportement des [attributs booléens](https://developer.mozilla.org/docs/Glossary/Boolean/HTML) HTML standard, où la
_présence_ de l'attribut indique une valeur « true ». Cependant, le `booleanAttribute` d'Angular traite la chaîne littérale `"false"` comme le booléen `false`.

`numberAttribute` tente de convertir la valeur donnée en nombre, et produit `NaN` si la conversion échoue.

### Alias d'input {#input-aliases}

Vous pouvez spécifier l'option `alias` pour changer le nom d'un input dans les templates.

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  value = input(0, {alias: 'sliderValue'});
}
```

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

Cet alias n'a pas d'effet sur l'utilisation de la propriété dans le code TypeScript.

Même si vous devriez en général éviter de donner des alias aux inputs des composants, cette fonctionnalité peut être utile pour renommer des propriétés tout en conservant un alias pour le nom d'origine, ou pour éviter des collisions avec le nom de propriétés natives des éléments du DOM.

## Inputs model {#model-inputs}

Les **inputs model** sont un type particulier d'input qui permet à un composant de propager de nouvelles valeurs vers son composant parent.

Quand vous créez un composant, vous pouvez définir un input model de la même manière qu'un input standard.

Les deux types d'input permettent de lier une valeur à la propriété. Cependant, **les inputs model permettent à l'auteur du composant d'écrire des valeurs dans la propriété**. Si la propriété est liée par un two-way binding, la nouvelle valeur se propage à ce binding.

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

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

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

Dans l'exemple ci-dessus, `CustomSlider` peut écrire des valeurs dans son input model `value`, qui propage ensuite ces valeurs vers le signal `volume` de `MediaControls`. Ce binding garde les valeurs de `value` et `volume` synchronisées. Notez que le binding transmet l'instance du signal `volume`, et non la _valeur_ du signal.

Pour le reste, les inputs model fonctionnent comme les inputs standard. Vous pouvez lire la valeur en appelant la fonction du signal, y compris dans des [contextes réactifs](guide/signals#reactive-contexts) comme `computed` et `effect`.

Consultez [Two-way binding](guide/templates/two-way-binding) pour plus de détails sur le two-way binding dans les templates.

### Two-way binding avec des propriétés simples {#two-way-binding-with-plain-properties}

Vous pouvez lier une propriété JavaScript simple à un input model.

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

Dans l'exemple ci-dessus, `CustomSlider` peut écrire des valeurs dans son input model `value`, qui propage ensuite ces valeurs vers la propriété `volume` de `MediaControls`. Ce binding garde les valeurs de `value` et `volume` synchronisées.

### Événements `change` implicites {#implicit-change-events}

Quand vous déclarez un input model dans un composant ou une directive, Angular crée automatiquement un [output](guide/components/outputs) correspondant pour ce model. Le nom de l'output est le nom de l'input model suffixé par « Change ».

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

Angular émet cet événement de changement chaque fois que vous écrivez une nouvelle valeur dans l'input model en appelant ses méthodes `set` ou `update`.

Consultez [Événements personnalisés avec les outputs](guide/components/outputs) pour plus de détails sur les outputs.

### Personnaliser les inputs model {#customizing-model-inputs}

Vous pouvez marquer un input model comme [obligatoire](#required-inputs) ou lui fournir un [alias](#input-aliases) de la même manière qu'un input standard.

Les inputs model ne prennent pas en charge les transformations d'input.

### Quand utiliser les inputs model {#when-to-use-model-inputs}

Utilisez les inputs model quand vous voulez qu'un composant prenne en charge le two-way binding. C'est généralement approprié quand un composant sert à modifier une valeur en fonction des interactions de l'utilisateur. Le plus souvent, les contrôles de formulaire personnalisés, comme un sélecteur de date ou une combobox, devraient utiliser des inputs model pour leur valeur principale.

## Choisir les noms des inputs {#choosing-input-names}

Évitez de choisir des noms d'inputs qui entrent en collision avec les propriétés des éléments du DOM comme HTMLElement. Les collisions de noms créent une confusion : on ne sait plus si la propriété liée appartient au composant ou à l'élément du DOM.

N'ajoutez pas de préfixes aux inputs des composants comme vous le feriez pour les selectors de composants. Comme un élément donné ne peut héberger qu'un seul composant, on peut considérer que toutes les propriétés personnalisées appartiennent au composant.

## Déclarer des inputs avec le décorateur `@Input` {#declaring-inputs-with-the-input-decorator}

TIP: Même si l'équipe Angular recommande d'utiliser la fonction `input` basée sur les signals pour les nouveaux projets, l'API d'origine `@Input`, basée sur un décorateur, reste entièrement prise en charge.

Vous pouvez aussi déclarer les inputs d'un composant en ajoutant le décorateur `@Input` à une propriété :

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  @Input() value = 0;
}
```

Le binding à un input est identique pour les inputs basés sur les signals et pour ceux basés sur un décorateur :

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

### Personnaliser les inputs basés sur un décorateur {#customizing-decorator-based-inputs}

Le décorateur `@Input` accepte un objet de configuration qui vous permet de modifier le fonctionnement de l'input.

#### Inputs obligatoires {#required-inputs-decorator}

Vous pouvez spécifier l'option `required` pour imposer qu'un input donné ait toujours une valeur.

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  @Input({required: true}) value = 0;
}
```

Si vous essayez d'utiliser un composant sans spécifier tous ses inputs obligatoires, Angular signale une erreur au moment du build.

#### Transformations d'input {#input-transforms-decorator}

Vous pouvez spécifier une fonction `transform` pour modifier la valeur d'un input quand elle est définie par Angular. Cette fonction de transformation fonctionne exactement comme les fonctions de transformation des inputs basés sur les signals décrites ci-dessus.

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

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

#### Alias d'input {#input-aliases-decorator}

Vous pouvez spécifier l'option `alias` pour changer le nom d'un input dans les templates.

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  @Input({alias: 'sliderValue'}) value = 0;
}
```

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

Le décorateur `@Input` accepte aussi l'alias comme premier paramètre, à la place de l'objet de configuration.

Les alias d'input fonctionnent de la même manière que pour les inputs basés sur les signals décrits ci-dessus.

### Inputs avec getters et setters {#inputs-with-getters-and-setters}

Avec les inputs basés sur un décorateur, une propriété implémentée avec un getter et un setter peut être un input :

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

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

private internalValue = 0;
}
```

Vous pouvez même créer un input _en écriture seule_ en ne définissant qu'un setter public :

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

private internalValue = 0;
}
```

**Préférez les transformations d'input aux getters et setters** lorsque c'est possible.

Évitez les getters et setters complexes ou coûteux. Angular peut invoquer le setter d'un input plusieurs fois, ce qui peut nuire aux performances de l'application si le setter effectue des opérations coûteuses, comme des manipulations du DOM.

## Spécifier les inputs dans le décorateur `@Component` {#specify-inputs-in-the-component-decorator}

En plus du décorateur `@Input`, vous pouvez aussi spécifier les inputs d'un composant avec la propriété `inputs` du décorateur `@Component`. Cela peut être utile quand un composant hérite d'une propriété d'une classe de base :

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

Vous pouvez en plus spécifier un alias d'input dans la liste `inputs` en plaçant l'alias après un deux-points dans la chaîne :

```ts
{highlight:[4]}
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }
```
# Événements personnalisés avec les outputs

TIP: Ce guide suppose que vous avez déjà lu le [guide des Fondamentaux](essentials). Commencez par celui-ci si vous découvrez Angular.

Les composants Angular peuvent définir des événements personnalisés en affectant une propriété à la fonction `output` :

```ts
{highlight:[5]}
@Component({
  /*...*/
})
export class ExpandablePanel {
  panelClosed = output<void>();
}
```

```html
<expandable-panel (panelClosed)="savePanelState()" />
```

La fonction `output` renvoie un `OutputEmitterRef`. Vous pouvez émettre un événement en appelant la méthode `emit` sur l'`OutputEmitterRef` :

```ts
this.panelClosed.emit();
```

Angular appelle **outputs** les propriétés initialisées avec la fonction `output`. Vous pouvez utiliser les outputs pour déclencher des événements personnalisés, comme les événements natifs du navigateur tels que `click`.

**Les événements personnalisés d'Angular ne remontent pas dans le DOM**.

**Les noms des outputs sont sensibles à la casse.**

Quand vous étendez une classe de composant, **les outputs sont hérités par la classe enfant.**

La fonction `output` a une signification particulière pour le compilateur Angular. **Vous pouvez appeler `output` exclusivement dans les initialiseurs de propriétés des composants et des directives.**

## Émettre des données d'événement {#emitting-event-data}

Vous pouvez transmettre des données d'événement en appelant `emit` :

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

// You can emit custom event objects
this.thumbDropped.emit({
  pointerX: 123,
  pointerY: 456,
});
```

Quand vous définissez un event listener dans un template, vous pouvez accéder aux données de l'événement via la variable `$event` :

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

Recevez les données de l'événement dans le composant parent :

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

```

## Personnaliser le nom des outputs {#customizing-output-names}

La fonction `output` accepte un paramètre qui vous permet de spécifier un nom différent pour l'événement dans un template :

```ts
@Component(/* ... */)
export class CustomSlider {
  changed = output({alias: 'valueChanged'});
}
```

```html
<custom-slider (valueChanged)="saveVolume()" />
```

Cet alias n'a pas d'effet sur l'utilisation de la propriété dans le code TypeScript.

Même si vous devriez en général éviter de donner des alias aux outputs des composants, cette fonctionnalité peut être utile pour renommer des propriétés tout en conservant un alias pour le nom d'origine, ou pour éviter des collisions avec le nom d'événements natifs du DOM.

## S'abonner aux outputs par programmation {#subscribing-to-outputs-programmatically}

Quand vous créez un composant dynamiquement, vous pouvez vous abonner par programmation aux événements des outputs
depuis l'instance du composant. Le type `OutputRef` inclut une méthode `subscribe` :

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

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

Angular nettoie automatiquement les abonnements aux événements quand il détruit des composants ayant des abonnés. Vous pouvez aussi vous désabonner manuellement d'un événement. La fonction `subscribe` renvoie un `OutputRefSubscription` doté d'une méthode `unsubscribe` :

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

// ...

eventSubscription.unsubscribe();
```

## Choisir les noms d'événements {#choosing-event-names}

Évitez de choisir des noms d'outputs qui entrent en collision avec les événements des éléments du DOM comme HTMLElement. Les collisions de noms créent une confusion : on ne sait plus si la propriété liée appartient au composant ou à l'élément du DOM.

N'ajoutez pas de préfixes aux outputs des composants comme vous le feriez pour les selectors de composants. Comme un élément donné ne peut héberger qu'un seul composant, on peut considérer que toutes les propriétés personnalisées appartiennent au composant.

Utilisez toujours des noms d'outputs en [camelCase](https://en.wikipedia.org/wiki/Camel_case). Évitez de préfixer les noms d'outputs par « on ».

## Utiliser les outputs avec RxJS {#using-outputs-with-rxjs}

Consultez [Interopérabilité RxJS avec les outputs des composants et des directives](ecosystem/rxjs-interop/output-interop) pour plus de détails sur l'interopérabilité entre les outputs et RxJS.

## Déclarer des outputs avec le décorateur `@Output` {#declaring-outputs-with-the-output-decorator}

TIP: Même si l'équipe Angular recommande d'utiliser la fonction `output` pour les nouveaux projets, l'API
d'origine `@Output`, basée sur un décorateur, reste entièrement prise en charge.

Vous pouvez aussi définir des événements personnalisés en affectant à une propriété un nouvel `EventEmitter` et en ajoutant le décorateur `@Output` :

```ts
@Component(/* ... */)
export class ExpandablePanel {
  @Output() panelClosed = new EventEmitter<void>();
}
```

Vous pouvez émettre un événement en appelant la méthode `emit` sur l'`EventEmitter`.

### Alias avec le décorateur `@Output` {#aliases-with-the-output-decorator}

Le décorateur `@Output` accepte un paramètre qui vous permet de spécifier un nom différent pour l'événement dans un template :

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

```html
<custom-slider (valueChanged)="saveVolume()" />
```

Cet alias n'a pas d'effet sur l'utilisation de la propriété dans le code TypeScript.

## Spécifier les outputs dans le décorateur `@Component` {#specify-outputs-in-the-component-decorator}

En plus du décorateur `@Output`, vous pouvez aussi spécifier les outputs d'un composant avec la propriété `outputs` du décorateur `@Component`. Cela peut être utile quand un composant hérite d'une propriété d'une classe de base :

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

Vous pouvez en plus spécifier un alias d'output dans la liste `outputs` en plaçant l'alias après un deux-points dans la chaîne :

```ts
// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged: volumeChanged'],
})
export class CustomSlider extends BaseSlider {}
```
# Projection de contenu avec ng-content

TIP: Ce guide suppose que vous avez déjà lu le [guide des Fondamentaux](essentials). Lisez-le d'abord si vous découvrez Angular.

Vous avez souvent besoin de créer des composants qui servent de conteneurs pour différents types de contenu. Par
exemple, vous pouvez vouloir créer un composant de carte personnalisé :

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

**Vous pouvez utiliser l'élément `<ng-content>` comme placeholder pour indiquer où le contenu doit être placé** :

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

TIP: `<ng-content>` fonctionne de manière similaire
à [l'élément natif `<slot>`](https://developer.mozilla.org/docs/Web/HTML/Element/slot),
mais avec certaines fonctionnalités propres à Angular.

Quand vous utilisez un composant avec `<ng-content>`, tous les enfants du host element du composant sont
rendus, ou **projetés**, à l'emplacement de ce `<ng-content>` :

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

```html

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

```html

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

Angular appelle **contenu** d'un composant tous les enfants qui lui sont passés de cette façon. Il
se distingue de la **vue** du composant, qui désigne les éléments définis dans le template
du composant.

**L'élément `<ng-content>` n'est ni un composant ni un élément du DOM**. Il s'agit plutôt d'un
placeholder spécial qui indique à Angular où rendre le contenu. Le compilateur d'Angular traite
tous les éléments `<ng-content>` au moment du build. Vous ne pouvez pas insérer, supprimer ni modifier `<ng-content>` à
l'exécution. Vous ne pouvez pas ajouter de directives, de styles ni d'attributs arbitraires à `<ng-content>`.

IMPORTANT: Vous ne devez pas inclure `<ng-content>` de manière conditionnelle avec `@if`, `@for` ou `@switch`. Angular
instancie et crée toujours les nœuds du DOM pour le contenu rendu dans un placeholder `<ng-content>`, même si
ce placeholder `<ng-content>` est masqué. Pour le rendu conditionnel du contenu d'un composant,
consultez [Fragments de template](api/core/ng-template).

## Plusieurs placeholders de contenu {#multiple-content-placeholders}

Angular permet de projeter plusieurs éléments différents dans différents placeholders `<ng-content>`
en fonction d'un selector CSS. En reprenant l'exemple de carte ci-dessus, vous pouvez créer deux placeholders pour
le titre et le corps de la carte grâce à l'attribut `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

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

```typescript

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

```html

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

Le placeholder `<ng-content>` prend en charge les mêmes selectors CSS
que les [selectors de composant](guide/components/selectors).

Si vous incluez un ou plusieurs placeholders `<ng-content>` avec un attribut `select` et
un placeholder `<ng-content>` sans attribut `select`, ce dernier capture tous les éléments qui
ne correspondent à aucun attribut `select` :

```html

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

```html

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

```html

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

Si un composant n'inclut pas de placeholder `<ng-content>` sans attribut `select`, les
éléments qui ne correspondent à aucun des placeholders du composant ne sont pas rendus dans le DOM.

## Contenu de repli {#fallback-content}

Angular peut afficher un _contenu de repli_ pour le placeholder `<ng-content>` d'un composant si ce composant n'a aucun contenu enfant correspondant. Vous pouvez définir un contenu de repli en ajoutant du contenu enfant directement dans l'élément `<ng-content>`.

```html

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

```html

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

```html

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

## Définir un alias de contenu pour la projection {#aliasing-content-for-projection}

Angular prend en charge un attribut spécial, `ngProjectAs`, qui vous permet de définir un selector CSS sur
n'importe quel élément. Chaque fois qu'un élément portant `ngProjectAs` est comparé à un placeholder
`<ng-content>`, Angular utilise la valeur de `ngProjectAs` au lieu de l'identité de l'élément :

```html

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

```html

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

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

```html

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

`ngProjectAs` ne prend en charge que des valeurs statiques et ne peut pas être lié à des expressions dynamiques.

## Mises en garde {#caveats}

### Le contenu projeté vit dans la vue du parent {#projected-content-lives-in-the-parents-view}

Même si le contenu projeté est _rendu_ à l'intérieur du composant qui le reçoit, il appartient toujours au composant qui l'a déclaré. Angular le suit comme une partie de la vue du parent, ce qui a quelques effets de bord qu'il est bon de connaître.

**Détection de changements :** le contenu projeté est vérifié quand le _parent_ exécute la détection de changements. Si le composant qui le reçoit utilise `OnPush`, Angular peut ignorer la vérification du template de ce composant, mais il n'ignorera pas le contenu projeté, car celui-ci appartient au parent.

```html

<onpush-wrapper>
  
  <expensive-component />
</onpush-wrapper>
```

**Injection de dépendances :** le contenu projeté obtient ses dépendances depuis l'injector du parent, et non depuis les `viewProviders` du composant qui le reçoit. Consultez [Providers et viewProviders](guide/di/hierarchical-dependency-injection) pour plus de détails.

### Certains composants de library ne prennent pas en charge les enfants projetés {#some-library-components-dont-support-projected-children}

Certains composants (menus, onglets, listes) utilisent `ContentChildren` pour trouver leurs enfants et mettre en place des comportements comme la navigation au clavier, la gestion du focus ou les attributs ARIA. Ils sont écrits en partant du principe qu'ils possèdent directement leurs enfants, si bien que projeter du contenu externe à l'intérieur a tendance à provoquer des dysfonctionnements subtils.

Par exemple, envelopper des éléments `<mat-menu-item>` dans une couche supplémentaire et les projeter dans `<mat-menu>` peut casser silencieusement la navigation au clavier et la prise en charge des lecteurs d'écran. La query trouve toujours les éléments, mais la configuration interne qui les rend interactifs peut ne pas fonctionner correctement quand les éléments proviennent d'un contexte de vue différent.

Si un composant de library gère le comportement de ses enfants, consultez sa documentation avant de recourir à la projection de contenu : elle n'est peut-être pas prise en charge.
# Cycle de vie des composants

TIP: Ce guide suppose que vous avez déjà lu le [guide des Fondamentaux](essentials). Lisez-le d'abord si vous découvrez Angular.

Le **cycle de vie** d'un composant est la séquence d'étapes qui se déroulent entre la création du composant
et sa destruction. Chaque étape représente une partie différente du processus par lequel Angular effectue le rendu
des composants et vérifie au fil du temps s'ils doivent être mis à jour.

Dans vos composants, vous pouvez implémenter des **lifecycle hooks** pour exécuter du code pendant ces étapes.
Les lifecycle hooks liés à une instance de composant précise sont implémentés comme des méthodes de votre
classe de composant. Les lifecycle hooks liés à l'application Angular dans son ensemble sont implémentés
comme des fonctions qui acceptent un callback.

Le cycle de vie d'un composant est étroitement lié à la manière dont Angular vérifie au fil du temps les changements de vos composants.
Pour comprendre ce cycle de vie, il vous suffit de savoir qu'Angular parcourt
l'arbre de votre application de haut en bas, en vérifiant les changements des bindings de template. Les lifecycle
hooks décrits ci-dessous s'exécutent pendant ce parcours. Ce parcours visite chaque
composant exactement une fois : évitez donc toujours d'apporter d'autres changements d'état au milieu du
processus.

## Résumé {#summary}

<div class="docs-table docs-scroll-track-transparent">
  <table>
    <tr>
      <td><strong>Phase</strong></td>
      <td><strong>Méthode</strong></td>
      <td><strong>Résumé</strong></td>
    </tr>
    <tr>
      <td>Création</td>
      <td><code>constructor</code></td>
      <td>
        <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes/constructor" target="_blank">
          Constructeur de classe JavaScript standard
        </a>. S'exécute quand Angular instancie le composant.
      </td>
    </tr>
    <tr>
      <td rowspan="7">Détection<br>de changements</td>
      <td><code>ngOnInit</code>
      </td>
      <td>S'exécute une fois, après qu'Angular a initialisé tous les inputs du composant.</td>
    </tr>
    <tr>
      <td><code>ngOnChanges</code></td>
      <td>S'exécute chaque fois que les inputs du composant ont changé.</td>
    </tr>
    <tr>
      <td><code>ngDoCheck</code></td>
      <td>S'exécute chaque fois que ce composant est vérifié pour détecter des changements.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentInit</code></td>
      <td>S'exécute une fois, après l'initialisation du <em>contenu</em> du composant.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentChecked</code></td>
      <td>S'exécute chaque fois que le contenu de ce composant a été vérifié pour détecter des changements.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewInit</code></td>
      <td>S'exécute une fois, après l'initialisation de la <em>vue</em> du composant.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewChecked</code></td>
      <td>S'exécute chaque fois que la vue du composant a été vérifiée pour détecter des changements.</td>
    </tr>
    <tr>
      <td rowspan="2">Rendu</td>
      <td><code>afterNextRender</code></td>
      <td>S'exécute une fois, la prochaine fois que <strong>tous</strong> les composants ont été rendus dans le DOM.</td>
    </tr>
    <tr>
      <td><code>afterEveryRender</code></td>
      <td>S'exécute chaque fois que <strong>tous</strong> les composants ont été rendus dans le DOM.</td>
    </tr>
    <tr>
      <td>Destruction</td>
      <td><code>ngOnDestroy</code></td>
      <td>S'exécute une fois, avant la destruction du composant.</td>
    </tr>
  </table>
</div>

### ngOnInit {#ngoninit}

La méthode `ngOnInit` s'exécute après qu'Angular a initialisé tous les inputs du composant avec leurs
valeurs initiales. Le `ngOnInit` d'un composant s'exécute exactement une fois.

Cette étape a lieu _avant_ l'initialisation du propre template du composant. Vous pouvez donc
mettre à jour l'état du composant en fonction des valeurs initiales de ses inputs.

### ngOnChanges {#ngonchanges}

La méthode `ngOnChanges` s'exécute après le changement de n'importe quel input du composant.

Cette étape a lieu _avant_ la vérification du propre template du composant. Vous pouvez donc mettre à jour
l'état du composant en fonction des valeurs initiales de ses inputs.

Pendant l'initialisation, le premier `ngOnChanges` s'exécute avant `ngOnInit`.

#### Inspecter les changements {#inspecting-changes}

La méthode `ngOnChanges` accepte un argument `SimpleChanges`. Cet objet est
un [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)
qui associe le nom de chaque input du composant à un objet `SimpleChange`. Chaque `SimpleChange` contient la
valeur précédente de l'input, sa valeur actuelle et un indicateur précisant s'il s'agit du premier changement
de l'input.

Vous pouvez, de façon facultative, passer la classe courante ou this comme premier argument générique pour un typage plus strict.

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

ngOnChanges(changes: SimpleChanges<UserProfile>) {
    if (changes.name) {
      console.log(`Previous: ${changes.name.previousValue}`);
      console.log(`Current: ${changes.name.currentValue}`);
      console.log(`Is first ${changes.name.firstChange}`);
    }
  }
}
```

Si vous fournissez un `alias` pour des propriétés d'input, le Record `SimpleChanges` utilise toujours le
nom de la propriété TypeScript comme clé, et non l'alias.

### ngOnDestroy {#ngondestroy}

La méthode `ngOnDestroy` s'exécute une fois, juste avant la destruction d'un composant. Angular détruit un
composant lorsqu'il n'est plus affiché sur la page, par exemple lorsqu'il est masqué par `@if` ou lors de la navigation
vers une autre page.

#### DestroyRef {#destroyref}

Comme alternative à la méthode `ngOnDestroy`, vous pouvez injecter une instance de `DestroyRef`. Vous pouvez
enregistrer un callback à invoquer lors de la destruction du composant en appelant la méthode `onDestroy`
de `DestroyRef`.

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

Vous pouvez passer l'instance de `DestroyRef` à des fonctions ou à des classes situées hors de votre composant. Utilisez ce
pattern si vous avez d'autre code qui doit exécuter un nettoyage lorsque le composant est
détruit.

Vous pouvez aussi utiliser `DestroyRef` pour garder le code de mise en place près du code de nettoyage, plutôt que de placer
tout le code de nettoyage dans la méthode `ngOnDestroy`.

##### Détecter la destruction d'une instance {#detecting-instance-destruction}

`DestroyRef` fournit une propriété `destroyed` qui permet de vérifier si une instance donnée a déjà été détruite. C'est utile pour éviter des opérations sur des composants détruits, en particulier avec une logique différée ou asynchrone.

En vérifiant `destroyRef.destroyed`, vous pouvez empêcher l'exécution de code après le nettoyage de l'instance, et éviter ainsi des erreurs comme `NG0911: View has already been destroyed.`.

### ngDoCheck {#ngdocheck}

La méthode `ngDoCheck` s'exécute avant chaque vérification par Angular des changements du template d'un composant.

Vous pouvez utiliser ce lifecycle hook pour vérifier manuellement des changements d'état en dehors de la
détection de changements normale d'Angular, en mettant à jour manuellement l'état du composant.

Cette méthode s'exécute très fréquemment et peut avoir un impact important sur les performances de votre page. Évitez
de définir ce hook autant que possible, et ne l'utilisez que si vous n'avez pas d'autre solution.

Pendant l'initialisation, le premier `ngDoCheck` s'exécute après `ngOnInit`.

### ngAfterContentInit {#ngaftercontentinit}

La méthode `ngAfterContentInit` s'exécute une fois, après l'initialisation de tous les enfants imbriqués dans le composant (son
_contenu_).

Vous pouvez utiliser ce lifecycle hook pour lire les résultats des
[content queries](guide/components/queries#content-queries). Vous pouvez accéder à l'état initialisé
de ces queries, mais toute tentative de modifier un état dans cette méthode provoque une
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)

### ngAfterContentChecked {#ngaftercontentchecked}

La méthode `ngAfterContentChecked` s'exécute chaque fois que les enfants imbriqués dans le composant (son
_contenu_) ont été vérifiés pour détecter des changements.

Vous pouvez accéder ici à l'état mis à jour
des [content queries](guide/components/queries#content-queries), mais toute tentative de
modifier un état dans cette méthode provoque
une [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### ngAfterViewInit {#ngafterviewinit}

La méthode `ngAfterViewInit` s'exécute une fois, après l'initialisation de tous les enfants du template du composant (sa
_vue_).

Vous pouvez utiliser ce lifecycle hook pour lire les résultats des
[view queries](guide/components/queries#view-queries). Vous pouvez accéder à l'état initialisé de
ces queries, mais toute tentative de modifier un état dans cette méthode provoque une
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)

### ngAfterViewChecked {#ngafterviewchecked}

La méthode `ngAfterViewChecked` s'exécute chaque fois que les enfants du template du composant (sa
_vue_) ont été vérifiés pour détecter des changements.

Vous pouvez accéder à l'état mis à jour des [view queries](guide/components/queries#view-queries)
ici, mais toute tentative de
modifier un état dans cette méthode provoque
une [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### afterEveryRender et afterNextRender {#aftereveryrender-and-afternextrender}

Les fonctions `afterEveryRender` et `afterNextRender` vous permettent d'enregistrer un **callback de rendu** à
invoquer après qu'Angular a terminé le rendu de _tous les composants_ de la page dans le DOM.

Ces fonctions diffèrent des autres lifecycle hooks décrits dans ce guide. Au lieu d'une
méthode de classe, ce sont des fonctions standalone qui acceptent un callback. L'exécution des callbacks
de rendu n'est liée à aucune instance de composant précise : il s'agit d'un hook à l'échelle de l'application.

`afterEveryRender` et `afterNextRender` doivent être appelées dans
un [contexte d'injection](guide/di/dependency-injection-context), généralement le
constructeur d'un composant.

Vous pouvez utiliser les callbacks de rendu pour effectuer des opérations manuelles sur le DOM.
Consultez [Utiliser les API du DOM](guide/components/dom-apis) pour savoir comment manipuler le DOM dans Angular.

Les callbacks de rendu ne s'exécutent ni pendant le rendu côté serveur (SSR), ni pendant le prérendu au moment du build.

#### Phases de after\*Render {#afterrender-phases}

Avec `afterEveryRender` ou `afterNextRender`, vous pouvez, de façon facultative, découper le travail en phases. La
phase vous permet de contrôler l'enchaînement des opérations sur le DOM, en plaçant les opérations d'_écriture_
avant les opérations de _lecture_ afin de minimiser le
[layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing). Pour
communiquer d'une phase à l'autre, une fonction de phase peut renvoyer une valeur de résultat accessible dans la
phase suivante.

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

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

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

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

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

Il existe quatre phases, exécutées dans l'ordre suivant :

| Phase            | Description                                                                                                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`      | Utilisez cette phase pour lire les propriétés et les styles du DOM qui affectent la mise en page et qui sont strictement nécessaires aux calculs suivants. Évitez cette phase si possible, en privilégiant les phases `write` et `read`. |
| `write`          | Utilisez cette phase pour écrire les propriétés et les styles du DOM qui affectent la mise en page.                                                                                                                                   |
| `mixedReadWrite` | Phase par défaut. Utilisez-la pour toute opération qui doit à la fois lire et écrire des propriétés et des styles affectant la mise en page. Évitez cette phase si possible, en privilégiant les phases explicites `write` et `read`.            |
| `read`           | Utilisez cette phase pour lire les propriétés du DOM qui affectent la mise en page.                                                                                                                                           |

## Interfaces de cycle de vie {#lifecycle-interfaces}

Angular fournit une interface TypeScript pour chaque méthode de cycle de vie. Vous pouvez, de façon facultative, importer
et les implémenter (`implement`) pour vous assurer que votre implémentation ne contient aucune faute de frappe ou
d'orthographe.

Chaque interface porte le même nom que la méthode correspondante, sans le préfixe `ng`. Par exemple,
l'interface de `ngOnInit` est `OnInit`.

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

## Ordre d'exécution {#execution-order}

Les diagrammes suivants montrent l'ordre d'exécution des lifecycle hooks d'Angular.

### Pendant l'initialisation {#during-initialization}

```mermaid
graph TD;
id[constructor]-->CHANGE;
subgraph CHANGE [Détection de changements]
direction TB
ngOnChanges-->ngOnInit;
ngOnInit-->ngDoCheck;
ngDoCheck-->ngAfterContentInit;
ngDoCheck-->ngAfterViewInit
ngAfterContentInit-->ngAfterContentChecked
ngAfterViewInit-->ngAfterViewChecked
end
CHANGE--Rendu-->afterNextRender-->afterEveryRender
```

### Mises à jour suivantes {#subsequent-updates}

```mermaid
graph TD;
subgraph CHANGE [Détection de changements]
direction TB
ngOnChanges-->ngDoCheck
ngDoCheck-->ngAfterContentChecked;
ngDoCheck-->ngAfterViewChecked
end
CHANGE--Rendu-->afterEveryRender
```

### Ordre avec les directives {#ordering-with-directives}

Lorsque vous placez une ou plusieurs directives sur le même élément qu'un composant, que ce soit dans un template ou avec
la propriété `hostDirectives`, le framework ne garantit aucun ordre d'exécution d'un lifecycle hook donné
entre le composant et les directives d'un même élément. Ne vous fiez jamais à un ordre
observé, car il peut changer dans les versions ultérieures d'Angular.
Les templates de composant ne sont pas du simple HTML statique : ils peuvent utiliser les données de la classe de votre composant et mettre en place des event handlers pour les interactions de l'utilisateur.

## Afficher du texte dynamique {#showing-dynamic-text}

Dans Angular, un _binding_ crée une connexion dynamique entre le template d'un composant et ses données. Cette connexion garantit que les modifications des données du composant mettent automatiquement à jour le template rendu.

Vous pouvez créer un binding pour afficher du texte dynamique dans un template avec des doubles accolades :

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

Quand Angular rend le composant, vous voyez :

```html
<h1>Profile for pro_programmer_123</h1>
```

Angular maintient automatiquement le binding à jour quand la valeur du signal change. En reprenant
l'exemple ci-dessus, si nous mettons à jour la valeur du signal `userName` :

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

La page rendue se met à jour pour refléter la nouvelle valeur :

```html
<h1>Profile for cool_coder_789</h1>
```

## Définir des propriétés et des attributs dynamiques {#setting-dynamic-properties-and-attributes}

Angular permet de lier des valeurs dynamiques à des propriétés du DOM avec des crochets :

```typescript
@Component({
  /*...*/
  // Set the `disabled` property of the button based on the value of `isValidUserId`.
  template: `<button [disabled]="!isValidUserId()">Save changes</button>`,
})
export class UserProfile {
  isValidUserId = signal(false);
}
```

Vous pouvez aussi lier des _attributs_ HTML en préfixant le nom de l'attribut par `attr.` :

```html

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

Angular met automatiquement à jour les propriétés et les attributs du DOM quand la valeur liée change.

## Gérer les interactions de l'utilisateur {#handling-user-interaction}

Angular vous permet d'ajouter des event listeners à un élément de votre template avec des parenthèses :

```typescript
@Component({
  /*...*/
  // Add an 'click' event handler that calls the `cancelSubscription` method.
  template: `<button (click)="cancelSubscription()">Cancel subscription</button>`,
})
export class UserProfile {
  /* ... */

cancelSubscription() {
    /* Your event handling code goes here. */
  }
}
```

Si vous devez passer l'objet [événement](https://developer.mozilla.org/docs/Web/API/Event) à votre event listener, vous pouvez utiliser la variable intégrée `$event` d'Angular dans l'appel de fonction :

```typescript
@Component({
  /*...*/
  // Add an 'click' event handler that calls the `cancelSubscription` method.
  template: `<button (click)="cancelSubscription($event)">Cancel subscription</button>`,
})
export class UserProfile {
  /* ... */

cancelSubscription(event: Event) {
    /* Your event handling code goes here. */
  }
}
```

## Control flow avec `@if` et `@for` {#control-flow-with-if-and-for}

Vous pouvez masquer et afficher des parties d'un template selon une condition avec le bloc `@if` d'Angular :

```html
<h1>User profile</h1>

@if (isAdmin()) {
  <h2>Admin settings</h2>
  
}
```

Le bloc `@if` accepte aussi un bloc `@else` facultatif :

```html
<h1>User profile</h1>

@if (isAdmin()) {
  <h2>Admin settings</h2>
  
} @else {
  <h2>User settings</h2>
  
}
```

Vous pouvez répéter une partie d'un template plusieurs fois avec le bloc `@for` d'Angular :

```html
<h1>User profile</h1>

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

Angular utilise le mot-clé `track`, visible dans l'exemple ci-dessus, pour associer les données aux éléments du DOM créés par `@for`. Consultez [_Pourquoi track est-il important dans les blocs @for ?_](guide/templates/control-flow#why-is-track-in-for-blocks-important) pour plus d'informations.

TIP: Vous voulez en savoir plus sur les templates Angular ? Consultez le [guide approfondi des templates](guide/templates) pour tous les détails.

## Étape suivante {#next-step}

Maintenant que votre application a des données dynamiques et des templates, il est temps d'apprendre à enrichir les templates en masquant ou en affichant certains éléments selon une condition, en itérant sur des éléments, et plus encore.
# Ajouter des event listeners

Angular permet de définir des event listeners sur un élément de votre template en indiquant le nom de l'événement entre parenthèses, accompagné d'une instruction qui s'exécute chaque fois que l'événement se produit.

## Écouter les événements natifs {#listening-to-native-events}

Pour ajouter des event listeners à un élément HTML, entourez l'événement de parenthèses, `()`, ce qui vous permet de spécifier une instruction d'écoute.

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

Dans cet exemple, Angular appelle `updateField` chaque fois que l'élément `<input>` émet un événement `keyup`.

Vous pouvez ajouter des event listeners pour n'importe quel événement natif, comme `click`, `keydown`, `mouseover`, etc. Pour en savoir plus, consultez [la liste de tous les événements disponibles sur les éléments sur MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element#events).

## Accéder à l'argument de l'événement {#accessing-the-event-argument}

Dans chaque event listener de template, Angular fournit une variable nommée `$event` qui contient une référence à l'objet de l'événement.

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

## Utiliser les modificateurs de touches {#using-key-modifiers}

Quand vous souhaitez capturer des événements clavier pour une touche précise, vous pourriez écrire du code comme celui-ci :

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

Cependant, comme ce scénario est courant, Angular vous permet de filtrer les événements en spécifiant une touche précise à l'aide du caractère point (`.`). Le code peut ainsi être simplifié comme suit :

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

Vous pouvez également ajouter des modificateurs de touches supplémentaires :

```html

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

Angular prend en charge les modificateurs `alt`, `control`, `meta` et `shift`.

Vous pouvez spécifier la touche (key) ou le code que vous souhaitez lier aux événements clavier. Les champs key et code font partie nativement de l'objet d'événement clavier du navigateur. Par défaut, l'event binding suppose que vous souhaitez utiliser les [valeurs Key des événements clavier](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values).

Angular vous permet aussi de spécifier les [valeurs Code des événements clavier](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values) grâce au suffixe intégré `code`.

```html

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

Cela peut être utile pour gérer les événements clavier de manière cohérente entre différents systèmes d'exploitation. Par exemple, quand vous utilisez la touche Alt sur les appareils macOS, la propriété `key` indique la touche en fonction du caractère déjà modifié par la touche Alt. Une combinaison comme Alt + S renvoie donc une valeur `key` de `'ß'`. La propriété `code`, en revanche, correspond au bouton physique ou virtuel pressé, et non au caractère produit.

## Écouter sur des cibles globales {#listening-on-global-targets}

Les noms de cibles globales peuvent servir de préfixe à un événement. Les 3 cibles globales prises en charge sont `window`, `document` et `body`.

```typescript
@Component({
  /* ... */
  host: {
    '(window:click)': 'onWindowClick()',
    '(document:click)': 'onDocumentClick()',
    '(body:click)': 'onBodyClick()',
  },
})
export class MyView {}
```

## Empêcher le comportement par défaut d'un événement {#preventing-event-default-behavior}

Si votre event handler doit remplacer le comportement natif du navigateur, vous pouvez utiliser la [méthode `preventDefault`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) de l'objet de l'événement :

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

Si l'instruction de l'event handler s'évalue à `false`, Angular appelle automatiquement `preventDefault()`, comme pour les [attributs natifs d'event handler](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes). _Privilégiez toujours un appel explicite à `preventDefault`_, car cette approche rend l'intention du code évidente.

## Étendre la gestion des événements {#extend-event-handling}

Le système d'événements d'Angular est extensible grâce à des plugins d'événements personnalisés, enregistrés avec le jeton d'injection `EVENT_MANAGER_PLUGINS`.

### Implémenter un plugin d'événements {#implementing-event-plugin}

Pour créer un plugin d'événements personnalisé, étendez la classe `EventManagerPlugin` et implémentez les méthodes requises.

```ts
import {Injectable} from '@angular/core';
import {EventManagerPlugin} from '@angular/platform-browser';

@Injectable()
export class DebounceEventPlugin extends EventManagerPlugin {
  constructor() {
    super(document);
  }

// Define which events this plugin supports
  override supports(eventName: string) {
    return /debounce/.test(eventName);
  }

// Handle the event registration
  override addEventListener(element: HTMLElement, eventName: string, handler: Function) {
    // Parse the event: e.g., "click.debounce.500"
    // event: "click", delay: 500
    const [event, , delay = '300'] = eventName.split('.');

let timeoutId: ReturnType<typeof setTimeout>;

const listener = (e: Event) => {
      clearTimeout(timeoutId);
      timeoutId = setTimeout(() => {
        handler(e);
      }, Number(delay));
    };

element.addEventListener(event, listener);

// Return cleanup function
    return () => {
      clearTimeout(timeoutId);
      element.removeEventListener(event, listener);
    };
  }
}
```

Enregistrez votre plugin personnalisé avec le jeton `EVENT_MANAGER_PLUGINS` dans les providers de votre application :

```ts
import {bootstrapApplication, EVENT_MANAGER_PLUGINS} from '@angular/platform-browser';
import {App} from './app';
import {DebounceEventPlugin} from './debounce-event-plugin';

bootstrapApplication(App, {
  providers: [
    {
      provide: EVENT_MANAGER_PLUGINS,
      useClass: DebounceEventPlugin,
      multi: true,
    },
  ],
});
```

Une fois le plugin enregistré, vous pouvez utiliser votre syntaxe d'événement personnalisée dans les templates, ainsi qu'avec la propriété `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('Searching for:', query);
  }
}
```

```ts
@Component({
  ...,
  host: {
    '(click.debounce.500)': 'handleDebouncedClick()',
  },
})
export class AwesomeCard {
  handleDebouncedClick(): void {
   console.log('Debounced click!');
  }
}
```
# Lier du texte, des propriétés et des attributs dynamiques

Dans Angular, un **binding** crée une connexion dynamique entre le template d'un composant et ses données. Cette connexion garantit que les modifications des données du composant mettent automatiquement à jour le template rendu.

## Afficher du texte dynamique avec l'interpolation de texte {#render-dynamic-text-with-text-interpolation}

Vous pouvez lier du texte dynamique dans les templates avec des doubles accolades, ce qui indique à Angular qu'il est responsable de l'expression qu'elles contiennent et de sa bonne mise à jour. C'est ce qu'on appelle l'**interpolation de texte**.

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

Dans cet exemple, quand l'extrait est rendu dans la page, Angular remplace `{{ theme }}` par `dark`.

```html

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

Les bindings qui changent au fil du temps doivent lire leurs valeurs depuis des [signals](/guide/signals). Angular suit les signals lus dans le template et met à jour la page rendue quand les valeurs de ces signals changent.

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

<p>Your color preference is {{ theme() }}.</p> 
  `
  ...
})
export class App {
  welcomeMessage = "Welcome, enjoy this app that we built for you";
  theme = signal('dark');
}
```

Pour plus de détails, consultez le [guide des signals](/guide/signals).

Pour poursuivre l'exemple du thème, si un utilisateur clique sur un bouton qui met à jour le signal `theme` à `'light'` après le chargement de la page, la page se met à jour en conséquence :

```html

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

Vous pouvez utiliser l'interpolation de texte partout où vous écririez normalement du texte en HTML.

Les valeurs d'expression sont converties en chaîne de caractères. `null` et `undefined` sont rendus sous forme de chaîne vide. Les objets et les tableaux sont convertis à l'aide de la méthode `toString` de la valeur.

## Lier des propriétés et des attributs dynamiques {#binding-dynamic-properties-and-attributes}

Angular permet de lier des valeurs dynamiques à des propriétés d'objets et à des attributs HTML avec des crochets.

Vous pouvez vous lier aux propriétés de l'instance DOM d'un élément HTML, d'une instance de [composant](/guide/components) ou d'une instance de [directive](/guide/directives).

### Propriétés des éléments natifs {#native-element-properties}

Chaque élément HTML possède une représentation DOM correspondante. Par exemple, chaque élément HTML `<button>` correspond à une instance de `HTMLButtonElement` dans le DOM. Dans Angular, vous utilisez les property bindings pour affecter des valeurs directement à la représentation DOM de l'élément.

```html

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

Dans cet exemple, chaque fois que `isFormValid` change, Angular définit automatiquement la propriété `disabled` de l'instance de `HTMLButtonElement`.

### Propriétés de composants et de directives {#component-and-directive-properties}

Quand un élément est un composant Angular, vous pouvez utiliser les property bindings pour définir les propriétés d'input du composant avec la même syntaxe à crochets.

```html

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

Dans cet exemple, chaque fois que `mySelection` change, Angular définit automatiquement la propriété `value` de l'instance de `MyListbox`.

Vous pouvez également vous lier aux propriétés des directives.

```html

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

### Attributs {#attributes}

Quand vous devez définir des attributs HTML qui n'ont pas de propriété DOM correspondante, comme les attributs SVG, vous pouvez lier des attributs aux éléments de votre template avec le préfixe `attr.`.

```html

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

Dans cet exemple, chaque fois que `listRole` change, Angular définit automatiquement l'attribut `role` de l'élément `<ul>` en appelant `setAttribute`.

Si la valeur d'un attribute binding est `null` ou `undefined`, Angular supprime l'attribut en appelant `removeAttribute`.

### Interpolation de texte dans les propriétés et les attributs {#text-interpolation-in-properties-and-attributes}

Vous pouvez aussi utiliser la syntaxe d'interpolation de texte dans les propriétés et les attributs, en utilisant la syntaxe à doubles accolades au lieu de placer des crochets autour du nom de la propriété ou de l'attribut. Avec cette syntaxe, Angular traite l'affectation comme un property binding.

```html

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

## Bindings de classes CSS et de propriétés de style {#css-class-and-style-property-bindings}

Angular offre des fonctionnalités supplémentaires pour lier des classes CSS et des propriétés de style CSS aux éléments.

### Classes CSS {#css-classes}

Vous pouvez créer un class binding CSS pour ajouter ou retirer une classe CSS d'un élément selon que la valeur liée est [truthy ou falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).

```html

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

Vous pouvez aussi vous lier directement à la propriété `class`. Angular accepte trois types de valeur :

| Description de la valeur de `class` | Type TypeScript |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Une chaîne contenant une ou plusieurs classes CSS séparées par des espaces | `string` |
| Un tableau de chaînes de classes CSS | `string[]` |
| Un objet dont chaque nom de propriété est un nom de classe CSS et dont chaque valeur correspondante détermine, selon qu'elle est truthy ou non, si cette classe est appliquée à l'élément. | `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,
  });
}
```

L'exemple ci-dessus produit le DOM suivant :

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

Angular découpe une valeur de chaîne sur les espaces et ignore les chaînes vides.

Quand vous utilisez à la fois des classes CSS statiques, un binding direct à `class` et des bindings à des classes spécifiques, Angular combine intelligemment toutes les classes dans le résultat rendu.

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

Dans l'exemple ci-dessus, Angular rend l'élément `ul` avec les trois classes CSS.

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

Angular ne garantit aucun ordre particulier des classes CSS sur les éléments rendus.

Quand vous liez `class` à un tableau ou à un objet, Angular compare la valeur précédente à la valeur actuelle avec l'opérateur d'égalité stricte (`===`). Vous devez créer une nouvelle instance d'objet ou de tableau quand vous modifiez ces valeurs pour qu'Angular applique les mises à jour.

Si un élément possède plusieurs bindings pour la même classe CSS, Angular résout les conflits en suivant son ordre de priorité des styles.

NOTE: Les class bindings ne prennent pas en charge plusieurs noms de classe séparés par des espaces dans une même clé. Ils ne prennent pas non plus en charge les mutations d'objets, car la référence du binding reste la même. Si vous avez besoin de l'un ou de l'autre, utilisez la directive [ngClass](/api/common/NgClass).

### Propriétés de style CSS {#css-style-properties}

Vous pouvez aussi vous lier directement aux propriétés de style CSS d'un élément.

```html

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

Vous pouvez en outre préciser l'unité des propriétés CSS qui en acceptent une.

```html

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

Vous pouvez aussi définir plusieurs valeurs de style dans un seul binding. Angular accepte les types de valeur suivants :

| Description de la valeur de `style` | Type TypeScript |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Une chaîne contenant zéro, une ou plusieurs déclarations CSS, comme `"display: flex; margin: 8px"`. | `string` |
| Un objet dont chaque nom de propriété est un nom de propriété CSS et dont chaque valeur correspondante est la valeur de cette propriété 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',
  });
}
```

L'exemple ci-dessus produit le DOM suivant.

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

Quand vous liez `style` à un objet, Angular compare la valeur précédente à la valeur actuelle avec l'opérateur d'égalité stricte (`===`). Vous devez créer une nouvelle instance d'objet quand vous modifiez ces valeurs pour qu'Angular applique les mises à jour.

Si un élément possède plusieurs bindings pour la même propriété de style, Angular résout les conflits en suivant son ordre de priorité des styles.

## Attributs ARIA {#aria-attributes}

Angular permet de lier des valeurs de chaîne aux attributs ARIA.

```html
<button type="button" [aria-label]="actionLabel()">
  {{ actionLabel() }}
</button>
```

Angular écrit la valeur de chaîne dans l'attribut `aria-label` de l'élément et le supprime quand la valeur liée est `null` ou `undefined`.

Certaines fonctionnalités ARIA exposent des propriétés DOM ou des inputs de directive qui acceptent des valeurs structurées (comme des références d'éléments). Utilisez les property bindings standard dans ces cas-là. Consultez le [guide d'accessibilité](/best-practices/a11y#aria-attributes-and-properties) pour des exemples et des conseils supplémentaires.
# Control flow

Les templates Angular prennent en charge des blocs de control flow qui vous permettent d'afficher, de masquer et de répéter des éléments de manière conditionnelle.

## Afficher du contenu de manière conditionnelle avec `@if`, `@else if` et `@else` {#conditionally-display-content-with-if-else-if-and-else}

Le bloc `@if` affiche son contenu de manière conditionnelle quand son expression de condition est truthy :

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

Si vous souhaitez afficher un contenu alternatif, vous pouvez le faire en fournissant un nombre quelconque de blocs `@else if` et un unique bloc `@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 }}
}
```

### Référencer le résultat de l'expression conditionnelle {#referencing-the-conditional-expressions-result}

La condition `@if` permet d'enregistrer le résultat de l'expression conditionnelle dans une variable pour la réutiliser à l'intérieur du bloc.

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

Cela peut être utile pour référencer des expressions plus longues, qui seraient plus faciles à lire et à maintenir dans le template.

## Répéter du contenu avec le bloc `@for` {#repeat-content-with-the-for-block}

Le bloc `@for` parcourt une collection et rend le contenu d'un bloc de manière répétée. La collection peut être n'importe quel [itérable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols) JavaScript, mais Angular dispose d'optimisations de performances supplémentaires pour les valeurs de type `Array`.

Une boucle `@for` typique ressemble à ceci :

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

Le bloc `@for` d'Angular ne prend pas en charge les instructions qui modifient le flux, comme `continue` ou `break` en JavaScript.

### Pourquoi `track` est-il important dans les blocs `@for` ? {#why-is-track-in-for-blocks-important}

L'expression `track` permet à Angular de maintenir une relation entre vos données et les nœuds DOM de la page. Angular peut ainsi optimiser les performances en exécutant le minimum d'opérations DOM nécessaires quand les données changent.

Bien utiliser track peut améliorer considérablement les performances de rendu de votre application quand vous bouclez sur des collections de données.

Dans l'expression `track`, choisissez une propriété qui identifie de manière unique chaque élément. Si votre modèle de données inclut une propriété d'identification unique, généralement `id` ou `uuid`, utilisez cette valeur. Si vos données n'incluent pas de champ de ce type, envisagez sérieusement d'en ajouter un.

Pour les collections statiques qui ne changent jamais, vous pouvez utiliser `$index` pour indiquer à Angular de suivre chaque élément par son index dans la collection.

Si aucune autre option n'est disponible, vous pouvez utiliser l'élément lui-même comme clé de suivi. Cela indique à Angular de suivre l'élément par l'identité de sa référence, avec l'opérateur d'égalité stricte (`===`). Évitez cette option autant que possible, car elle peut ralentir considérablement les mises à jour du rendu : Angular n'a aucun moyen de savoir quel élément de données correspond à quels nœuds DOM.

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

NOTE: Contrairement à `*ngFor`, le bloc `@for` privilégie la réutilisation des vues. Si une propriété suivie change mais que la référence de l'objet reste la même, Angular met à jour les bindings de la vue (y compris les inputs des composants) au lieu de détruire et de recréer l'élément entier.

### Variables contextuelles dans les blocs `@for` {#contextual-variables-in-for-blocks}

À l'intérieur des blocs `@for`, plusieurs variables implicites sont toujours disponibles :

| Variable | Signification |
| -------- | --------------------------------------------- |
| `$count` | Nombre d'éléments de la collection parcourue |
| `$index` | Index de la ligne courante |
| `$first` | Indique si la ligne courante est la première |
| `$last`  | Indique si la ligne courante est la dernière |
| `$even`  | Indique si l'index de la ligne courante est pair |
| `$odd`   | Indique si l'index de la ligne courante est impair |

Ces variables sont toujours disponibles sous ces noms, mais vous pouvez leur donner un alias avec un segment `let` :

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

Les alias sont utiles quand vous imbriquez des blocs `@for` : ils vous permettent de lire, depuis un bloc `@for` interne, les variables du bloc `@for` externe.

### Fournir un contenu de repli pour les blocs `@for` avec le bloc `@empty` {#providing-a-fallback-for-for-blocks-with-the-empty-block}

Vous pouvez inclure une section `@empty` facultative juste après le contenu du bloc `@for`. Le contenu du bloc `@empty` s'affiche quand il n'y a aucun élément :

```html
@for (item of items; track item.name) {
  <li>{{ item.name }}</li>
} @empty {
  <li>There are no items.</li>
}
```

## Afficher du contenu de manière conditionnelle avec le bloc `@switch` {#conditionally-display-content-with-the-switch-block}

Si le bloc `@if` convient à la plupart des scénarios, le bloc `@switch` offre une syntaxe alternative pour rendre des données de manière conditionnelle. Sa syntaxe ressemble beaucoup à l'instruction `switch` de JavaScript.

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

La valeur de l'expression conditionnelle est comparée à l'expression de chaque cas avec l'opérateur d'égalité stricte (`===`).

**`@switch` n'a pas de fallthrough** (passage au cas suivant) : vous n'avez donc pas besoin d'un équivalent à une instruction `break` ou `return` dans le bloc.

Vous pouvez spécifier plusieurs conditions pour un même bloc en enchaînant des instructions `@case` consécutives.

Vous pouvez inclure un bloc `@default` facultatif. Le contenu du bloc `@default` s'affiche si aucune des expressions de cas précédentes ne correspond à la valeur du switch.

Si aucun `@case` ne correspond à l'expression et qu'il n'y a pas de bloc `@default`, rien n'est affiché.

### Vérification de type exhaustive {#exhaustive-type-checking}

`@switch` prend en charge la vérification de type exhaustive, ce qui permet à Angular de vérifier à la compilation que toutes les valeurs possibles d'un type union sont traitées.

En utilisant `@default never;`, vous déclarez explicitement qu'il ne doit rester aucun cas. Si le type union est étendu par la suite et qu'un nouveau cas n'est couvert par aucun @case, le vérificateur de types des templates d'Angular signale une erreur, ce qui vous aide à repérer tôt les branches manquantes.

NOTE: La vérification d'exhaustivité repose sur le rétrécissement de type (type narrowing) de TypeScript, qui ne fonctionne que sur des variables. Elle ne fonctionne pas si la condition du switch est un appel de fonction ou un signal (par exemple, `@switch (state())`). Pour contourner ce problème, affectez le signal à une variable `@let`, par exemple : `@let mySignal = this.mySignal()`.

```typescript
@Component({
  template: `
    @switch (state) {
      @case ('loggedOut') {
        <button>Login</button>
      }

@case ('loggedIn') {
        <p>Welcome back!</p>
      }

@default never;
      
    }
  `,
})
export class AppComponent {
  state: 'loggedOut' | 'loading' | 'loggedIn' = 'loggedOut';
}
```

Quand l'expression évaluée par le switch est imbriquée dans une union, vous devez spécifier explicitement l'expression dont l'exhaustivité doit être vérifiée.

```typescript
@Component({
  template: `
    @switch (state.mode) {
      @case ('show') {
        {{ state.menu }};
      }
      @case ('hide') {}
      @default never(state);
    }
  `,
})
export class App {
  state!: {mode: 'hide'} | {mode: 'show'; menu: number};
}
```
# Variables dans les templates

Angular propose deux types de déclarations de variables dans les templates : les variables de template locales et les variables de référence de template.

HELPFUL: Dans ce guide, « template » ne désigne pas l'ensemble du fichier de template HTML. Le terme désigne uniquement une construction ou une expression de template précise au sein du fichier.

## Variables de template locales avec `@let` {#local-template-variables-with-let}

La syntaxe `@let` d'Angular vous permet de définir une variable locale et de la réutiliser dans un template, de manière similaire à la [syntaxe `let` de JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let).

### Utiliser `@let` {#using-let}

Utilisez `@let` pour déclarer une variable dont la valeur repose sur le résultat d'une expression de template. Angular maintient automatiquement la valeur de la variable à jour avec l'expression donnée, de manière similaire aux [bindings](/guide/templates/binding).

```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...';
```

Chaque bloc `@let` peut déclarer exactement une variable. Vous ne pouvez pas déclarer plusieurs variables dans le même bloc en les séparant par une virgule.

### Référencer la valeur de `@let` {#referencing-the-value-of-let}

Une fois que vous avez déclaré une variable avec `@let`, vous pouvez la réutiliser dans le même template :

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

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

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

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

### Réassignation {#assignability}

Une différence essentielle entre `@let` et le `let` de JavaScript est que `@let` ne peut pas être réassignée après sa déclaration. En revanche, Angular maintient automatiquement la valeur de la variable à jour avec l'expression donnée.

```html
@let value = 1;

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

### Portée des variables {#variable-scope}

Les déclarations `@let` ont pour portée la vue courante et ses descendants. Angular crée une nouvelle vue aux frontières des composants et partout où un template peut contenir du contenu dynamique, comme les blocs de control flow, les blocs `@defer` ou les directives structurelles.

Comme les déclarations `@let` ne sont pas remontées (hoisting), elles ne sont **pas** accessibles depuis les vues parentes ni depuis les éléments frères :

```html
@let topLevel = value;

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

{{ topLevel }}

{{ insideDiv }}

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

@let nested = value;

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

{{ nested }}
```

### Syntaxe complète {#full-syntax}

La syntaxe `@let` est formellement définie ainsi :

- Le mot-clé `@let`.
- Suivi d'un ou plusieurs espaces, sans compter les retours à la ligne.
- Suivi d'un nom JavaScript valide et de zéro ou plusieurs espaces.
- Suivi du symbole = et de zéro ou plusieurs espaces.
- Suivi d'une expression Angular, qui peut s'étendre sur plusieurs lignes.
- Terminé par le symbole `;`.

## Variables de référence de template {#template-reference-variables}

Les variables de référence de template vous permettent de déclarer une variable qui référence une valeur provenant d'un élément de votre template.

Une variable de référence de template peut faire référence à :

- un élément du DOM dans un template (y compris les [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements))
- un composant ou une directive Angular
- un [TemplateRef](/api/core/TemplateRef) issu d'un [ng-template](/api/core/ng-template)

Vous pouvez utiliser les variables de référence de template pour lire, dans une partie du template, des informations provenant d'une autre partie de ce même template.

### Déclarer une variable de référence de template {#declaring-a-template-reference-variable}

Vous pouvez déclarer une variable sur un élément d'un template en ajoutant un attribut qui commence par le caractère dièse (`#`) suivi du nom de la variable.

```html

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

### Assigner des valeurs aux variables de référence de template {#assigning-values-to-template-reference-variables}

Angular assigne une valeur aux variables de template en fonction de l'élément sur lequel la variable est déclarée.

Si vous déclarez la variable sur un composant Angular, la variable fait référence à l'instance du composant.

```html

<my-datepicker #startDate />
```

Si vous déclarez la variable sur un élément `<ng-template>`, la variable fait référence à une instance de TemplateRef qui représente le template. Pour plus d'informations, consultez [Comment Angular utilise la syntaxe avec astérisque, \*,](/guide/directives/structural-directives#structural-directive-shorthand) dans [Directives structurelles](/guide/directives/structural-directives).

```html

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

Si vous déclarez la variable sur tout autre élément affiché, la variable fait référence à l'instance de `HTMLElement`.

```html

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

#### Assigner une référence à une directive Angular {#assigning-a-reference-to-an-angular-directive}

Les directives Angular peuvent avoir une propriété `exportAs` qui définit un nom par lequel la directive peut être référencée dans un template :

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

Lorsque vous déclarez une variable de template sur un élément, vous pouvez assigner à cette variable une instance de directive en indiquant ce nom `exportAs` :

```html

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

Vous ne pouvez pas faire référence à une directive qui ne définit pas de nom `exportAs`.

### Utiliser les variables de référence de template avec les queries {#using-template-reference-variables-with-queries}

En plus d'utiliser les variables de template pour lire des valeurs depuis une autre partie du même template, vous pouvez aussi utiliser ce style de déclaration de variable pour « marquer » un élément pour les [queries de composant et de directive](/guide/components/queries).

Lorsque vous voulez interroger un élément précis d'un template, vous pouvez déclarer une variable de template sur cet élément, puis interroger l'élément à partir du nom de la variable.

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

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

Consultez [Référencer des enfants avec des queries](/guide/components/queries) pour plus d'informations sur les queries.

### Portée des variables de template {#template-variable-scope}

Tout comme les variables dans du code JavaScript ou TypeScript, les variables de template ont pour portée le template qui les déclare.

De même, les [blocs de control flow](guide/templates/control-flow) comme `@if` et `@for`, les [directives structurelles](guide/directives/structural-directives) et les déclarations `<ng-template>` créent une nouvelle portée de template imbriquée, tout comme les instructions de flux de contrôle de JavaScript telles que `if` et `for` créent de nouvelles portées lexicales. Vous ne pouvez pas accéder aux variables de template d'un de ces templates imbriqués depuis l'extérieur de ses limites.

HELPFUL: Ne définissez une variable qu'une seule fois dans le template afin que sa valeur à l'exécution reste prévisible.

#### Accès depuis un template imbriqué {#accessing-in-a-nested-template}

Un template interne peut accéder aux variables de template définies par le template externe.

Dans l'exemple suivant, modifier le texte de l'`<input>` modifie la valeur du `<span>`, car Angular répercute immédiatement les changements via la variable de template `ref1`.

```html
<input #ref1 type="text" [(ngModel)]="firstExample" />

@if (true) {
  <span>Value: {{ ref1.value }}</span>
}
```

Dans ce cas, le bloc `@if` crée une nouvelle portée de template, qui inclut la variable `ref1` de sa portée parente.

En revanche, accéder dans le template parent à une variable de template d'une portée enfant ne fonctionne pas :

```html
{avoid}
@if (true) {
  <input #ref2 type="text" [(ngModel)]="secondExample" />
}

<span>Value: {{ ref2?.value }}</span>
```

Ici, `ref2` est déclarée dans la portée enfant créée par `@if` et n'est pas accessible depuis le template parent.
# Chargement différé avec `@defer`

Les vues différables, aussi appelées blocs `@defer`, réduisent la taille du bundle initial de votre application en différant le chargement du code qui n'est pas strictement nécessaire au rendu initial d'une page. Cela se traduit souvent par un chargement initial plus rapide et une amélioration des Core Web Vitals (CWV), principalement le Largest Contentful Paint (LCP) et le Time to First Byte (TTFB).

Pour utiliser cette fonctionnalité, vous pouvez envelopper de manière déclarative une section de votre template dans un bloc @defer :

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

Le code de tous les composants, directives et pipes présents dans le bloc `@defer` est placé dans un fichier JavaScript séparé et chargé uniquement lorsque c'est nécessaire, après le rendu du reste du template.

Les vues différables prennent en charge divers déclencheurs, des options de préchargement et des sous-blocs pour gérer les états de placeholder, de chargement et d'erreur.

## Quelles dépendances sont différées ? {#which-dependencies-are-deferred}

Les composants, les directives, les pipes et les styles CSS des composants peuvent être différés lors du chargement d'une application.

Pour que les dépendances d'un bloc `@defer` soient différées, elles doivent remplir deux conditions :

1. **Elles doivent être standalone.** Les dépendances non standalone ne peuvent pas être différées et sont toujours chargées immédiatement, même si elles se trouvent dans des blocs `@defer`.
1. **Elles ne peuvent pas être référencées en dehors des blocs `@defer` dans le même fichier.** Si elles sont référencées en dehors du bloc `@defer` ou dans des queries ViewChild, les dépendances seront chargées immédiatement.

Les dépendances _transitives_ des composants, directives et pipes utilisés dans le bloc `@defer` n'ont pas besoin d'être strictement standalone : les dépendances transitives peuvent toujours être déclarées dans un `NgModule` et participer au chargement différé.

Le compilateur d'Angular produit une instruction d'[import dynamique](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) pour chaque composant, directive et pipe utilisé dans le bloc `@defer`. Le contenu principal du bloc est rendu une fois que tous les imports sont résolus. Angular ne garantit aucun ordre particulier pour ces imports.

## Gérer les différentes étapes du chargement différé {#how-to-manage-different-stages-of-deferred-loading}

Les blocs `@defer` disposent de plusieurs sous-blocs qui vous permettent de gérer élégamment les différentes étapes du processus de chargement différé.

### `@defer`

Il s'agit du bloc principal, qui définit la section de contenu chargée de manière différée. Il n'est pas rendu initialement : le contenu différé est chargé et rendu dès que le [déclencheur](#controlling-deferred-content-loading-with-triggers) spécifié se produit ou que la condition `when` est remplie.

Par défaut, un bloc `@defer` est déclenché lorsque le navigateur passe à l'état [inactif](/guide/templates/defer#idle).

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

### Afficher le contenu du placeholder avec `@placeholder` {#show-placeholder-content-with-placeholder}

Par défaut, les blocs defer n'affichent aucun contenu avant d'être déclenchés.

Le bloc `@placeholder` est un bloc optionnel qui déclare le contenu à afficher avant que le bloc `@defer` ne soit déclenché.

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

Bien qu'il soit optionnel, certains déclencheurs peuvent nécessiter la présence d'un `@placeholder` ou d'une [variable de référence de template](/guide/templates/variables#template-reference-variables) pour fonctionner. Consultez la section [Déclencheurs](#controlling-deferred-content-loading-with-triggers) pour plus de détails.

Angular remplace le contenu du placeholder par le contenu principal une fois le chargement terminé. Vous pouvez utiliser n'importe quel contenu dans la section placeholder, y compris du HTML simple, des composants, des directives et des pipes. Gardez à l'esprit que _les dépendances du bloc placeholder sont chargées immédiatement_.

Le bloc `@placeholder` accepte un paramètre optionnel pour spécifier la durée `minimum` pendant laquelle ce placeholder doit être affiché après le rendu initial de son contenu.

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

Ce paramètre `minimum` s'exprime en millisecondes (ms) ou en secondes (s). Vous pouvez l'utiliser pour éviter un clignotement rapide du contenu du placeholder lorsque les dépendances différées sont récupérées rapidement.

### Afficher un contenu de chargement avec `@loading` {#show-loading-content-with-loading}

Le bloc `@loading` est un bloc optionnel qui vous permet de déclarer le contenu affiché pendant le chargement des dépendances différées. Il remplace le bloc `@placeholder` dès que le chargement est déclenché.

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

Ses dépendances sont chargées immédiatement (comme pour `@placeholder`).

Le bloc `@loading` accepte deux paramètres optionnels pour aider à éviter le clignotement rapide du contenu qui peut se produire lorsque les dépendances différées sont récupérées rapidement :

- `minimum` - la durée minimale pendant laquelle ce placeholder doit être affiché
- `after` - le délai à attendre après le début du chargement avant d'afficher le template de chargement

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

Les deux paramètres s'expriment en millisecondes (ms) ou en secondes (s). De plus, les minuteurs des deux paramètres démarrent immédiatement après le déclenchement du chargement.

### Afficher un état d'erreur en cas d'échec du chargement différé avec `@error` {#show-error-state-when-deferred-loading-fails-with-error}

Le bloc `@error` est un bloc optionnel qui s'affiche si le chargement différé échoue. Comme pour `@placeholder` et `@loading`, les dépendances du bloc @error sont chargées immédiatement.

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

## Contrôler le chargement du contenu différé avec des déclencheurs {#controlling-deferred-content-loading-with-triggers}

Vous pouvez spécifier des **déclencheurs** qui contrôlent le moment où Angular charge et affiche le contenu différé.

Lorsqu'un bloc `@defer` est déclenché, il remplace le contenu du placeholder par le contenu chargé de manière différée.

Plusieurs déclencheurs d'événements peuvent être définis en les séparant par un point-virgule, `;`, et seront évalués comme des conditions OU.

Il existe deux types de déclencheurs : `on` et `when`.

### `on`

`on` spécifie une condition qui détermine quand le bloc `@defer` est déclenché.

Les déclencheurs disponibles sont les suivants :

| Déclencheur                   | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| [`idle`](#idle)               | Se déclenche lorsque le navigateur est inactif. Accepte un délai d'expiration optionnel. |
| [`viewport`](#viewport)       | Se déclenche lorsque le contenu spécifié entre dans le viewport        |
| [`interaction`](#interaction) | Se déclenche lorsque l'utilisateur interagit avec l'élément spécifié  |
| [`hover`](#hover)             | Se déclenche lorsque la souris survole la zone spécifiée               |
| [`immediate`](#immediate)     | Se déclenche immédiatement après la fin du rendu du contenu non différé |
| [`timer`](#timer)             | Se déclenche après une durée donnée                                    |

#### `idle`

Le déclencheur `idle` charge le contenu différé dès que le navigateur a atteint un état d'inactivité, en s'appuyant sur requestIdleCallback. C'est le comportement par défaut d'un bloc defer.

Vous pouvez éventuellement spécifier un délai d'expiration en millisecondes, transmis à [`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback). Si le navigateur ne planifie pas le callback assez tôt, le travail s'exécutera au plus tard à l'expiration du délai spécifié.

```html

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

@defer (on idle(500)) {
  <large-cmp />
}
```

##### Personnaliser le comportement de `idle` {#customizing-idle-behavior}

Vous pouvez personnaliser le déclencheur `idle` en fournissant votre propre implémentation de `IdleService` et en l'enregistrant avec `provideIdleServiceWith` dans les providers de votre application.

```ts
@Service()
class CustomIdleService implements IdleService {
  requestOnIdle(callback: (deadline?: IdleDeadline) => void, options?: IdleRequestOptions): number {
    // Custom idle scheduling logic can be implemented here.
    return requestIdleCallback(callback, options);
  }

cancelOnIdle(id: number) {
    // Implement custom idle cancellation here.
  }
}

bootstrapApplication(App, {
  providers: [provideIdleServiceWith(CustomIdleService)],
});
```

#### `viewport`

Le déclencheur `viewport` charge le contenu différé lorsque le contenu spécifié entre dans le viewport, à l'aide de l'[API Intersection Observer](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API). Le contenu observé peut être le contenu du `@placeholder` ou une référence explicite à un élément.

Par défaut, le bloc `@defer` surveille l'entrée du placeholder dans le viewport. Les placeholders utilisés de cette manière doivent avoir un unique élément racine.

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

Vous pouvez aussi spécifier une [variable de référence de template](/guide/templates/variables) dans le même template que le bloc `@defer` comme élément dont l'entrée dans le viewport est surveillée. Cette variable est transmise en paramètre du déclencheur viewport.

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

Si vous souhaitez personnaliser les options de l'`IntersectionObserver`, le déclencheur `viewport` accepte un objet littéral. Celui-ci prend en charge toutes les propriétés du second paramètre d'`IntersectionObserver`, à l'exception de `root`. Lorsque vous utilisez la notation objet littéral, vous devez transmettre votre déclencheur via la propriété `trigger`.

```html
<div #greeting>Hello!</div>

@defer (on viewport({trigger: greeting, rootMargin: '100px', threshold: 0.5})) {
  <greetings-cmp />
}

@defer (on viewport({rootMargin: '100px', threshold: 0.5})) {
  <greetings-cmp />
} @placeholder {
  <div>Implied trigger</div>
}
```

#### `interaction`

Le déclencheur `interaction` charge le contenu différé lorsque l'utilisateur interagit avec l'élément spécifié via des événements `click` ou `keydown`.

Par défaut, le placeholder sert d'élément d'interaction. Les placeholders utilisés de cette manière doivent avoir un unique élément racine.

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

Vous pouvez aussi spécifier une [variable de référence de template](/guide/templates/variables) dans le même template que le bloc `@defer` comme élément dont les interactions sont surveillées. Cette variable est transmise en paramètre du déclencheur interaction.

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

#### `hover`

Le déclencheur `hover` charge le contenu différé lorsque la souris a survolé la zone de déclenchement, via les événements `mouseover` et `focusin`.

Par défaut, le placeholder sert d'élément d'interaction. Les placeholders utilisés de cette manière doivent avoir un unique élément racine.

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

Vous pouvez aussi spécifier une [variable de référence de template](/guide/templates/variables) dans le même template que le bloc `@defer` comme élément survolé. Cette variable est transmise en paramètre du déclencheur hover.

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

#### `immediate`

Le déclencheur `immediate` charge immédiatement le contenu différé. Cela signifie que le bloc différé se charge dès que tout le reste du contenu non différé a fini son rendu.

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

#### `timer`

Le déclencheur `timer` charge le contenu différé après une durée spécifiée.

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

Le paramètre de durée doit être spécifié en millisecondes (`ms`) ou en secondes (`s`).

### `when`

Le déclencheur `when` accepte une expression conditionnelle personnalisée et charge le contenu différé lorsque la condition devient truthy.

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

Il s'agit d'une opération ponctuelle : le bloc `@defer` ne revient pas au placeholder si la condition repasse à une valeur falsy après être devenue truthy.

## Précharger des données avec `prefetch` {#prefetching-data-with-prefetch}

En plus de spécifier une condition qui détermine quand le contenu différé est affiché, vous pouvez éventuellement spécifier un **déclencheur de préchargement**. Ce déclencheur vous permet de charger le JavaScript associé au bloc `@defer` avant que le contenu différé ne soit affiché.

Le préchargement permet des comportements plus avancés, comme commencer à précharger des ressources avant qu'un utilisateur n'ait réellement vu un bloc defer ou interagi avec lui, alors qu'il pourrait bientôt le faire, ce qui rend les ressources disponibles plus rapidement.

Vous pouvez spécifier un déclencheur de préchargement de la même manière que le déclencheur principal du bloc, mais en le préfixant du mot-clé `prefetch`. Le déclencheur principal du bloc et le déclencheur de préchargement sont séparés par un point-virgule (`;`).

Dans l'exemple ci-dessous, le préchargement démarre lorsque le navigateur devient inactif, et le contenu du bloc n'est rendu qu'une fois que l'utilisateur interagit avec le placeholder.

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

@defer (on interaction; prefetch on idle(500)) {
  <large-cmp />
}
```

## Tester les blocs `@defer` {#testing-defer-blocks}

Angular fournit des API TestBed pour simplifier le test des blocs `@defer` et le déclenchement de leurs différents états pendant les tests. Par défaut, les blocs `@defer` se déroulent dans les tests comme ils le feraient dans une application réelle. Si vous voulez parcourir les états manuellement, vous pouvez passer le comportement des blocs defer à `Manual` dans la configuration de TestBed.

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

## `@defer` fonctionne-t-il avec `NgModule` ? {#does-defer-work-with-ngmodule}

Les blocs `@defer` sont compatibles à la fois avec les composants, directives et pipes standalone et avec ceux basés sur NgModule. Cependant, **seuls les composants, directives et pipes standalone peuvent être différés**. Les dépendances basées sur NgModule ne sont pas différées et sont incluses dans le bundle chargé immédiatement.

## Compatibilité entre les blocs `@defer` et le Hot Module Reload (HMR) {#compatibility-between-defer-blocks-and-hot-module-reload-hmr}

Lorsque le Hot Module Replacement (HMR) est actif, tous les chunks des blocs `@defer` sont récupérés immédiatement, sans tenir compte des déclencheurs configurés. Pour rétablir le comportement standard des déclencheurs, vous devez désactiver le HMR en servant votre application avec l'option `--no-hmr`.

## Comment `@defer` fonctionne-t-il avec le rendu côté serveur (SSR) et la génération de site statique (SSG) ? {#how-does-defer-work-with-server-side-rendering-ssr-and-static-site-generation-ssg}

Par défaut, lors du rendu d'une application sur le serveur (en SSR ou en SSG), les blocs defer rendent toujours leur `@placeholder` (ou rien si aucun placeholder n'est spécifié) et les déclencheurs ne sont pas invoqués. Côté client, le contenu du `@placeholder` est hydraté et les déclencheurs sont activés.

Pour rendre le contenu principal des blocs `@defer` sur le serveur (en SSR comme en SSG), vous pouvez activer [la fonctionnalité d'hydratation incrémentale](/guide/incremental-hydration) et configurer des déclencheurs `hydrate` pour les blocs concernés.

## Fichiers barrel et chunks lazy {#barrel-files-and-lazy-chunks}

Si vous utilisez `@defer` mais ne voyez pas de chunk lazy séparé dans la sortie de votre build, vérifiez la façon dont vous importez le composant différé. L'import via un fichier barrel (`index.ts`) est un coupable fréquent : les bundlers considèrent le barrel comme un module unique et conservent tous ses exports ensemble, si bien que votre composant se retrouve dans le bundle principal, indépendamment de `@defer`.

```typescript
{header: "index.ts"}
export {HeavyComponent} from './heavy.component';
export {OtherComponent} from './other.component';
```

```typescript
{header: "parent.component.ts"}
import {Component} from '@angular/core';
import {HeavyComponent} from './index'; // pulls in OtherComponent too

@Component({
  imports: [HeavyComponent],
  template: `@defer {
    <heavy-component />
  }`,
})
export class ParentComponent {}
```

La solution est simple : importez directement depuis le fichier propre au composant :

```typescript
import {HeavyComponent} from './heavy.component';
```

Cela suffit pour que le bundler le place dans son propre chunk et le charge en lazy loading lorsque le déclencheur se déclenche.

## Bonnes pratiques pour différer des vues {#best-practices-for-deferring-views}

### Évitez les chargements en cascade avec des blocs `@defer` imbriqués {#avoid-cascading-loads-with-nested-defer-blocks}

Lorsque vous avez des blocs `@defer` imbriqués, ils doivent avoir des déclencheurs différents afin d'éviter de se charger simultanément, ce qui provoquerait des requêtes en cascade et pourrait nuire aux performances de chargement de la page.

### Évitez les décalages de mise en page {#avoid-layout-shifts}

Évitez de différer des composants visibles dans le viewport de l'utilisateur lors du chargement initial. Cela peut nuire aux Core Web Vitals en augmentant le cumulative layout shift (CLS).

Si cela s'avère nécessaire, évitez les déclencheurs `immediate`, `timer`, `viewport` et `when` personnalisés qui provoquent le chargement du contenu pendant le rendu initial de la page.

### Pensez à l'accessibilité {#keep-accessibility-in-mind}

Lorsque vous utilisez des blocs `@defer`, tenez compte de l'impact sur les utilisateurs de technologies d'assistance comme les lecteurs d'écran.
Les lecteurs d'écran qui se positionnent sur une section différée liront d'abord le contenu du placeholder ou de chargement, mais peuvent ne pas annoncer les changements lorsque le contenu différé se charge.

Pour que les changements du contenu différé soient annoncés aux lecteurs d'écran, vous pouvez envelopper votre bloc `@defer` dans un élément doté d'une région 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>
```

Ainsi, les changements sont annoncés à l'utilisateur lors des transitions (placeholder → chargement → contenu/erreur).
# Syntaxe des expressions

Les expressions Angular sont basées sur JavaScript, mais en diffèrent sur quelques points clés. Ce guide présente les similitudes et les différences entre les expressions Angular et le JavaScript standard.

## Valeurs littérales {#value-literals}

Angular prend en charge un sous-ensemble des [valeurs littérales](https://developer.mozilla.org/en-US/docs/Glossary/Literal) de JavaScript.

### Valeurs littérales prises en charge {#supported-value-literals}

| Type de littéral       | Exemples de valeurs             |
| ---------------------- | ------------------------------- |
| Chaîne de caractères   | `'Hello'`, `"World"`            |
| Booléen                | `true`, `false`                 |
| Nombre                 | `123`, `3.14`                   |
| Objet                  | `{name: 'Alice'}`               |
| Tableau                | `['Onion', 'Cheese', 'Garlic']` |
| null                   | `null`                          |
| RegExp                 | `/\d+/`                         |
| Template string        | `` `Hello ${name}` ``           |
| Template string étiquetée | `` tag`Hello ${name}` ``        |

### Valeurs littérales non prises en charge {#unsupported-value-literals}

| Type de littéral | Exemples de valeurs |
| ------------ | -------------- |
| BigInt       | `1n`           |

## Globales {#globals}

Les expressions Angular prennent en charge les [globales](https://developer.mozilla.org/en-US/docs/Glossary/Global_object) suivantes :

- [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)

Aucune autre globale JavaScript n'est prise en charge. Parmi les globales JavaScript courantes figurent `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt`, etc.

## Variables locales {#local-variables}

Angular met automatiquement à disposition, dans certains contextes, des variables locales spéciales utilisables dans les expressions. Ces variables spéciales commencent toujours par le caractère dollar (`$`).

Par exemple, les blocs `@for` fournissent plusieurs variables locales correspondant à des informations sur la boucle, comme `$index`.

## Quels opérateurs sont pris en charge ? {#what-operators-are-supported}

### Opérateurs pris en charge {#supported-operators}

Angular prend en charge les opérateurs suivants du JavaScript standard.

| Opérateur                     | Exemple(s)                                     |
| ----------------------------- | ---------------------------------------------- |
| Addition / Concaténation      | `1 + 2`                                        |
| Soustraction                  | `52 - 3`                                       |
| Multiplication                | `41 * 6`                                       |
| Division                      | `20 / 4`                                       |
| Reste (modulo)                | `17 % 5`                                       |
| Exponentiation                | `10 ** 3`                                      |
| Parenthèses                   | `9 * (8 + 4)`                                  |
| Conditionnel (ternaire)       | `a > b ? true : false`                         |
| ET (logique)                  | `&&`                                           |
| OU (logique)                  | `\|\|`                                         |
| NON (logique)                 | `!`                                            |
| Nullish coalescing            | `possiblyNullValue ?? 'default'`               |
| Opérateurs de comparaison     | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==`, `!=` |
| Négation unaire               | `-x`                                           |
| Plus unaire                   | `+y`                                           |
| Accesseur de propriété        | `person['name']`                               |
| typeof                        | `typeof 42`                                    |
| void                          | `void 1`                                       |
| in                            | `'model' in car`                               |
| instanceof                    | `car instanceof Automobile`                    |
| Affectation                   | `a = b`                                        |
| Affectation après addition    | `a += b`                                       |
| Affectation après soustraction | `a -= b`                                       |
| Affectation après multiplication | `a *= b`                                       |
| Affectation après division    | `a /= b`                                       |
| Affectation du reste          | `a %= b`                                       |
| Affectation après exponentiation | `a **= b`                                      |
| Affectation après ET logique  | `a &&= b`                                      |
| Affectation après OU logique  | `a \|\|= b`                                    |
| Affectation de nullish coalescing   | `a ??= b`                                      |
| Décomposition dans les littéraux d'objet | `{...obj, foo: 'bar'}`                         |
| Décomposition dans les littéraux de tableau | `[...arr, 1, 2, 3]`                            |
| Décomposition dans les appels de fonction | `fn(...args)`                                  |
| Fonction fléchée              | `items.filter((i) => i.active)`                |

NOTE: Les opérateurs d'affectation et d'incrémentation/décrémentation ne sont valides que dans les [instructions d'event listener](#event-listener-statements). Les utiliser dans un binding ou une interpolation provoque une erreur de compilation, sauf s'ils se trouvent dans une fonction fléchée.

Les fonctions fléchées doivent avoir une expression comme corps. Les pipes ne peuvent pas être utilisés dans une fonction fléchée, mais vous pouvez passer une fonction fléchée en argument à un pipe.

Les expressions Angular prennent également en charge les opérateurs non standard suivants :

| Opérateur                       | Exemple(s)                     |
| ------------------------------- | ------------------------------ |
| [Pipe](/guide/templates/pipes)  | `{{ total \| currency }}`      |
| Chaînage optionnel\*            | `someObj.someProp?.nestedProp` |
| Assertion non nulle (TypeScript) | `someObj!.someProp`            |

### Migration de la navigation sécurisée {#safe-navigation-migration}

Avant Angular 22, l'opérateur de chaînage optionnel (`?.`) renvoyait `null` lorsque l'opérande de gauche valait `null` ou `undefined`, alors que l'opérateur `?.` du JavaScript standard renvoie `undefined`.
Depuis Angular 22, le comportement de l'opérateur de chaînage optionnel dans les expressions Angular est aligné sur celui du JavaScript standard.

Lors de la migration vers la v22, les schematics de `ng update` ont ajouté une fonction magique `$safeNavigationMigration` aux expressions existantes pour préserver l'ancien comportement qui renvoie `null`.

```html
{{ $safeNavigationMigration(foo?.bar) }}
```

`$safeNavigationMigration` est **uniquement une aide temporaire à la migration**. Elle indique au compilateur de compiler l'expression de navigation sécurisée qu'elle entoure avec l'ancienne sémantique qui renvoie null plutôt qu'avec la sémantique `?.` du JavaScript standard. Ce n'est pas une vraie fonction et elle ne peut pas être appelée depuis TypeScript.

NOTE: Privilégiez la migration des expressions pour qu'elles ne dépendent plus de la distinction entre `null` et `undefined`, afin de pouvoir retirer `$safeNavigationMigration`. Cette fonction pourrait être supprimée dans une future version d'Angular.

### Opérateurs non pris en charge {#unsupported-operators}

| Opérateur             | Exemple(s)                        |
| --------------------- | --------------------------------- |
| Tous les opérateurs bit à bit | `&`, `&=`, `~`, `\|=`, `^=`, etc. |
| Déstructuration d'objet | `const { name } = person`         |
| Déstructuration de tableau | `const [firstItem] = items`       |
| Opérateur virgule     | `x = (x++, x)`                    |
| new                   | `new Car()`                       |

## Contexte lexical des expressions {#lexical-context-for-expressions}

Les expressions Angular sont évaluées dans le contexte de la classe du composant ainsi que des [variables de template](/guide/templates/variables), variables locales et globales pertinentes.

Quand vous faites référence aux membres de la classe du composant, `this` est toujours implicite. Cependant, si un template déclare une [variable de template](guide/templates/variables) portant le même nom qu'un membre, la variable masque ce membre. Vous pouvez faire référence sans ambiguïté à un tel membre de la classe en utilisant explicitement `this.`. Cela peut être utile lors de la création d'une déclaration `@let` qui masque un membre de la classe, par exemple pour affiner le type d'un signal.

## Déclarations {#declarations}

De manière générale, les déclarations ne sont pas prises en charge dans les expressions Angular. Cela inclut, sans s'y limiter :

| Déclarations                      | Exemple(s)                                  |
| --------------------------------- | ------------------------------------------- |
| Variables                         | `let label = 'abc'`, `const item = 'apple'` |
| Fonctions                         | `function myCustomFunction() { }`           |
| Fonctions fléchées avec un corps en bloc | `() => { }`                                 |
| Classes                           | `class Rectangle { }`                       |

## Instructions d'event listener {#event-listener-statements}

Les event handlers sont des **instructions** et non des expressions. Bien qu'ils prennent en charge toute la syntaxe des expressions Angular, il existe deux différences clés :

1. Les instructions **prennent en charge** les opérateurs d'affectation (mais pas les affectations par déstructuration)
1. Les instructions **ne prennent pas en charge** les pipes
# Directives d'attribute

Les directives d'attribute modifient l'apparence ou le comportement des éléments du DOM et des composants Angular.

## Utiliser les bindings de template pour un comportement ponctuel {#use-template-bindings-for-one-off-behavior}

La syntaxe de template d'Angular couvre déjà la modification des classes, des styles, des propriétés et des événements d'un seul élément :

- Les [bindings de classe et de style](guide/templates/binding#css-class-and-style-property-bindings) ajoutent et retirent des classes CSS et des styles inline.
- Les [property bindings et attribute bindings](guide/templates/binding) définissent des propriétés du DOM et des attributs HTML.
- Les [event listeners](guide/templates/event-listeners) répondent aux interactions de l'utilisateur.

Les directives d'attribute sont utiles quand vous voulez regrouper ce type de comportement dans une unité réutilisable que vous pouvez appliquer à n'importe quel élément ou composant.

## Créer une directive d'attribute {#building-an-attribute-directive}

Une directive d'attribute personnalisée est une classe JavaScript dotée du décorateur `@Directive()`. Le `selector` du décorateur définit l'attribut qui applique la directive. Les crochets en font un attribute selector : la directive correspond donc aux éléments qui portent cet attribut. Par convention, utilisez un préfixe comme `app` pour éviter les collisions de noms :

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

@Directive({
  selector: '[appHighlight]',
})
export class HighlightDirective {}
```

HELPFUL: La commande CLI [`ng generate directive`](tools/cli/schematics) génère une directive accompagnée de son fichier de test.

Une directive peut modifier son host de manière déclarative avec des host bindings, ou de manière impérative grâce à une référence au host element. Cet exemple [injecte](guide/di) [`ElementRef`](api/core/ElementRef) et accède à l'élément via sa propriété `nativeElement` pour passer l'arrière-plan en jaune :

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

IMPORTANT: Les directives _ne prennent pas en charge_ les namespaces.

```html
{avoid}
<p app:Highlight>This is invalid</p>
```

## Appliquer une directive d'attribute {#applying-an-attribute-directive}

Pour appliquer la directive, ajoutez son selector comme attribut sur un élément :

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

Angular crée une instance de `HighlightDirective` pour cet élément `<p>`, injecte une référence à l'élément et passe son arrière-plan en jaune.

## Gérer les événements utilisateur {#handling-user-events}

Pour répondre aux interactions de l'utilisateur, liez les événements du host element à des méthodes de gestion via la propriété `host` du décorateur `@Directive()`. La directive suivante met en surbrillance le host element tant que le pointeur le survole et retire la surbrillance quand le pointeur en sort :

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

La propriété `host` associe les événements `mouseenter` et `mouseleave` aux méthodes `onMouseEnter()` et `onMouseLeave()`, qui délèguent à un helper `highlight()` chargé de définir la couleur d'arrière-plan du host element. Pour en savoir plus sur les bindings d'événements du host, consultez [lier des valeurs au host element](guide/components/host-elements#binding-to-the-host-element).

## Accepter des valeurs en input {#accepting-input-values}

Comme les composants, les directives acceptent des inputs via la fonction [`input()`](guide/components/inputs). Donnez à un input le même nom que le selector pour qu'un seul binding applique la directive et lui transmette une valeur :

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

Lisez l'input en l'appelant comme un signal, et utilisez une valeur par défaut quand aucune couleur n'est définie :

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

Dans le template, liez la valeur au selector. Comme l'input porte le même nom que le selector, `[appHighlight]` applique la directive et définit sa valeur. Ici, `color` est une propriété du composant :

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

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

Une directive peut déclarer plusieurs inputs. La directive suivante ajoute un input `defaultColor`, puis se rabat successivement sur `appHighlight`, `defaultColor` et enfin `red` :

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

Liez les deux inputs sur le même élément. Comme `defaultColor` reçoit une chaîne statique plutôt qu'une expression dynamique, il n'a pas besoin de crochets :

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

## Désactiver le traitement d'Angular avec `NgNonBindable` {#deactivating-angular-processing-with-ngnonbindable}

Pour empêcher l'évaluation des expressions dans le navigateur, ajoutez `ngNonBindable` au host element.
`ngNonBindable` désactive l'interpolation, les directives et le binding dans les templates.

Dans l'exemple suivant, l'expression `{{ 1 + 1 }}` s'affiche telle qu'elle apparaît dans votre éditeur de code, et n'affiche pas `2`.

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

Appliquer `ngNonBindable` à un élément arrête le binding pour les éléments enfants de cet élément.
Cependant, `ngNonBindable` laisse les directives fonctionner sur l'élément auquel vous appliquez `ngNonBindable`.
Dans l'exemple suivant, la directive `appHighlight` reste active, mais Angular n'évalue pas l'expression `{{ 1 + 1 }}`.

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

Si vous appliquez `ngNonBindable` à un élément parent, Angular désactive l'interpolation et tout type de binding, comme le property binding ou l'event binding, pour les enfants de cet élément.

## Et ensuite ? {#whats-next}
# Directives structurelles

Les directives structurelles sont des directives appliquées à un élément `<ng-template>` qui rendent le contenu de cet `<ng-template>` de manière conditionnelle ou répétée.

Pour le rendu conditionnel et répété du quotidien, utilisez les [blocs de control flow](guide/templates/control-flow) intégrés d'Angular (`@if`, `@for` et `@switch`). Écrivez une directive structurelle quand vous avez besoin d'un comportement de rendu réutilisable que le control flow ne couvre pas, comme conditionner l'affichage d'un contenu à une vérification de permission ou fournir à un template des données issues d'une source externe.

## Exemple de cas d'usage {#example-use-case}

Ce guide utilise comme fil conducteur une directive appelée `SelectDirective`. La directive récupère des données depuis une source de données donnée et rend son template quand ces données sont disponibles. Elle tient son nom du mot-clé SQL `SELECT` et correspond à un attribute selector, `[select]`.

`SelectDirective` possède un input nommé `selectFrom`, qui désigne la source de données à utiliser. Le préfixe `select` de cet input est important pour la [syntaxe abrégée](#structural-directive-shorthand). La directive instancie son `<ng-template>` avec un contexte de template qui fournit les données sélectionnées.

Utiliser cette directive directement sur un `<ng-template>` ressemble à ceci :

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

La directive structurelle peut attendre que les données soient disponibles, puis rendre son `<ng-template>`.

HELPFUL: L'élément `<ng-template>` d'Angular définit un template qui ne rend rien par défaut. Si vous enveloppez des éléments dans un `<ng-template>` sans appliquer de directive structurelle, ces éléments ne sont pas rendus.

Pour plus d'informations, consultez la documentation de l'[API ng-template](api/core/ng-template).

## Syntaxe abrégée des directives structurelles {#structural-directive-shorthand}

Angular prend en charge une syntaxe abrégée pour les directives structurelles, qui évite d'écrire explicitement un élément `<ng-template>`.

Les directives structurelles peuvent être appliquées directement sur un élément en préfixant l'attribute selector de la directive par un astérisque (`*`), comme `*select`. Angular transforme l'astérisque placé devant une directive structurelle en un `<ng-template>` qui héberge la directive et entoure l'élément et ses descendants.

Vous pouvez l'utiliser avec `SelectDirective` de la manière suivante :

```html
<p *select="let data; from: source">The data is: {{ data }}</p>
```

Cet exemple montre la flexibilité de la syntaxe abrégée des directives structurelles, parfois appelée _microsyntaxe_.

Utilisée de cette façon, seuls la directive structurelle et ses bindings sont appliqués au `<ng-template>`. Les autres attributs ou bindings de la balise `<p>` restent inchangés. Par exemple, ces deux formes sont équivalentes :

```html

<p class="data-view" *select="let data; from: source">The data is: {{ data }}</p>

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

La syntaxe abrégée est développée selon un ensemble de conventions. Une [grammaire](#structural-directive-syntax-reference) plus complète est définie plus bas, mais dans l'exemple ci-dessus, cette transformation s'explique ainsi :

La première partie de l'expression `*select` est `let data`, qui déclare une variable de template `data`. Comme aucune affectation ne suit, la variable de template est liée à la propriété `$implicit` du contexte de template.

Le deuxième élément de syntaxe est une paire clé-expression, `from source`. `from` est une clé de binding et `source` une expression de template ordinaire. Les clés de binding sont associées à des propriétés en les convertissant en PascalCase et en les préfixant du selector de la directive structurelle. La clé `from` est associée à `selectFrom`, qui est ensuite liée à l'expression `source`. C'est pourquoi beaucoup de directives structurelles ont des inputs tous préfixés par le selector de la directive structurelle.

## Une seule directive structurelle par élément {#one-structural-directive-per-element}

Vous ne pouvez appliquer qu'une seule directive structurelle par élément avec la syntaxe abrégée. En effet, il n'existe qu'un seul élément `<ng-template>` dans lequel cette directive est déployée. Plusieurs directives nécessiteraient plusieurs `<ng-template>` imbriqués, et on ne saurait pas quelle directive doit passer en premier. `<ng-container>` permet de créer des couches d'enveloppe quand plusieurs directives structurelles doivent être appliquées autour du même élément du DOM ou du même composant, ce qui permet à l'utilisateur de définir la structure imbriquée.

## Créer une directive structurelle {#creating-a-structural-directive}

Une directive structurelle est une classe de directive qui injecte deux dépendances :

- [`TemplateRef`](api/core/TemplateRef) donne à la directive accès au contenu du `<ng-template>` auquel elle est appliquée.
- [`ViewContainerRef`](api/core/ViewContainerRef) représente l'emplacement dans le DOM où la directive peut rendre ce template.

La directive contrôle le rendu en créant, ou non, des vues intégrées à partir du template dans le view container. La `SelectDirective` complète ressemble à ceci :

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

export interface DataSource<T> {
  load(): Promise<T>;
}

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

selectFrom = input.required<DataSource<unknown>>();

async ngOnInit() {
    const data = await this.selectFrom().load();
    this.viewContainerRef.createEmbeddedView(this.templateRef, {
      // Create the embedded view with a context object that contains
      // the data via the key `$implicit`.
      $implicit: data,
    });
  }
}
```

L'input `selectFrom` désigne la source de données que lit la directive. Il utilise [`input.required()`](guide/components/inputs#required-inputs), car la directive ne peut rien faire d'utile sans source de données.

Quand Angular initialise la directive, celle-ci charge les données puis rend le template en appelant `createEmbeddedView()`. Le second argument est l'_objet de contexte_ du template : les valeurs auxquelles le template peut se lier avec des déclarations `let`. Affecter les données à la clé `$implicit` en fait la valeur par défaut que reçoit `let-data` (ou `let data` en syntaxe abrégée).

NOTE: Cet exemple rend son template une seule fois, à l'initialisation de la directive. Il ne refait pas le rendu quand la source de données liée change.

Une fois la directive fonctionnelle, envisagez d'[ajouter la prise en charge de la vérification de types du template](#typing-the-directives-context).

HELPFUL: La commande CLI [`ng generate directive`](tools/cli/schematics) génère une directive accompagnée de son fichier de test.

## Référence de la syntaxe des directives structurelles {#structural-directive-syntax-reference}

Quand vous écrivez vos propres directives structurelles, utilisez la syntaxe suivante :

```ts
{hideCopy}
_: prefix = "( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )_";
```

Les motifs suivants décrivent chaque partie de la grammaire des directives structurelles :

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

### Comment Angular traduit la syntaxe abrégée {#how-angular-translates-shorthand}

Angular traduit la syntaxe abrégée des directives structurelles en syntaxe de binding normale de la manière suivante :

### Exemples de syntaxe abrégée {#shorthand-examples}

Le tableau suivant présente des exemples de syntaxe abrégée :

| Syntaxe abrégée                                                       | Interprétation de la syntaxe par Angular                                                                      |
| :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `*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">`                                                               |

## Améliorer la vérification de types des templates pour les directives personnalisées {#improving-template-type-checking-for-custom-directives}

Vous pouvez améliorer la vérification de types des templates pour les directives personnalisées en ajoutant des guards de template à la définition de votre directive.
Ces guards aident le vérificateur de types des templates d'Angular à détecter les erreurs dans le template à la compilation, ce qui peut éviter des erreurs à l'exécution.
Deux types de guards sont possibles :

- `ngTemplateGuard_(input)` permet de contrôler comment une expression d'input doit être affinée en fonction du type d'un input précis.
- `ngTemplateContextGuard` sert à déterminer le type de l'objet de contexte du template, en fonction du type de la directive elle-même.

Cette section fournit des exemples des deux types de guards.
Pour plus d'informations, consultez [Vérification de types des templates](tools/cli/template-typecheck 'Template type-checking guide').

### Affinage de type avec les guards de template {#type-narrowing-with-template-guards}

Une directive structurelle dans un template contrôle si ce template est rendu à l'exécution. Certaines directives structurelles veulent effectuer un affinage de type en fonction du type de l'expression d'input.

Deux affinages sont possibles avec les guards d'input :

- Affiner l'expression d'input à partir d'une fonction d'assertion de type TypeScript.
- Affiner l'expression d'input en fonction de son caractère truthy.

Pour affiner l'expression d'input en définissant une fonction d'assertion de type :

```ts
// This directive only renders its template if the actor is a user.
// You want to assert that within the template, the type of the `actor`
// expression is narrowed to `User`.
@Directive(...)
class ActorIsUser {
  actor = input<User | Robot>();

static ngTemplateGuard_actor(dir: ActorIsUser, expr: User | Robot): expr is User {
    // The return statement is unnecessary in practice, but included to
    // prevent TypeScript errors.
    return true;
  }
}
```

La vérification de types se comporte dans le template comme si `ngTemplateGuard_actor` avait été vérifié sur l'expression liée à l'input.

Certaines directives ne rendent leurs templates que lorsqu'un input est truthy. Il n'est pas possible de capturer toute la sémantique du caractère truthy dans une fonction d'assertion de type ; à la place, un type littéral `'binding'` peut indiquer au vérificateur de types des templates que l'expression du binding elle-même doit servir de guard :

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

static ngTemplateGuard_condition: 'binding';
}
```

Le vérificateur de types des templates se comporte comme si l'expression liée à `condition` avait été vérifiée comme truthy dans le template.

### Typer le contexte de la directive {#typing-the-directives-context}

Si votre directive structurelle fournit un contexte au template instancié, vous pouvez le typer correctement dans le template en fournissant une fonction d'assertion de type statique `ngTemplateContextGuard`. Cette fonction peut utiliser le type de la directive pour en déduire le type du contexte, ce qui est utile quand le type de la directive est générique.

Pour la `SelectDirective` décrite plus haut, vous pouvez implémenter un `ngTemplateContextGuard` pour spécifier correctement le type des données, même si la source de données est générique.

```ts
// Declare an interface for the template context:
export interface SelectTemplateContext<T> {
  $implicit: T;
}

@Directive(...)
export class SelectDirective<T> {
  // The directive's generic type `T` will be inferred from the `DataSource` type
  // passed to the input.
  selectFrom = input.required<DataSource<T>>();

// Narrow the type of the context using the generic type of the directive.
  static ngTemplateContextGuard<T>(dir: SelectDirective<T>, ctx: any): ctx is SelectTemplateContext<T> {
    // As before the guard body is not used at runtime, and included only to avoid
    // TypeScript errors.
    return true;
  }
}
```

## Et ensuite ? {#whats-next}
# API de composition de directives

Les directives Angular offrent un excellent moyen d'encapsuler des comportements réutilisables. Les directives peuvent appliquer des attributs, des classes CSS et des event listeners à un élément.

L'_API de composition de directives_ vous permet d'appliquer des directives au host element d'un composant _depuis_ la classe TypeScript du composant.

## Ajouter des directives à un composant {#adding-directives-to-a-component}

Vous appliquez des directives à un composant en ajoutant une propriété `hostDirectives` au décorateur du composant. Ces directives sont appelées _host directives_.

Dans cet exemple, la directive `MenuBehavior` est appliquée au host element de `AdminMenu`. Cela fonctionne de la même manière que l'application de `MenuBehavior` à l'élément `<admin-menu>` dans un template.

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

Quand le framework rend un composant, Angular crée aussi une instance de chaque host directive. Les host bindings des directives s'appliquent au host element du composant. Par défaut, les inputs et les outputs des host directives ne sont pas exposés dans l'API publique du composant. Consultez [Inclure des inputs et des outputs](#including-inputs-and-outputs) ci-dessous pour plus d'informations.

Les host directives s'accompagnent des contraintes suivantes :

- **Angular applique les host directives de manière statique, à la compilation.** Vous ne pouvez pas ajouter
  dynamiquement des directives à l'exécution.
- **Les directives utilisées dans `hostDirectives` ne peuvent pas spécifier `standalone: false`.**
- **Angular ignore le `selector` des directives appliquées dans la propriété `hostDirectives`.**

## Inclure des inputs et des outputs {#including-inputs-and-outputs}

Quand vous appliquez `hostDirectives` à votre composant, les inputs et les outputs des host directives ne sont pas inclus par défaut dans l'API de votre composant. Vous pouvez inclure explicitement des inputs et des outputs dans l'API de votre composant en développant l'entrée dans `hostDirectives` :

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

En spécifiant explicitement les inputs et les outputs, les consommateurs du composant qui utilise `hostDirectives` peuvent les lier dans un template :

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

De plus, vous pouvez définir des alias pour les inputs et les outputs d'une host directive afin de personnaliser l'API de votre composant :

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

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

## Ajouter des directives à une autre directive {#adding-directives-to-another-directive}

Vous pouvez aussi ajouter `hostDirectives` à d'autres directives, en plus des composants. Cela permet l'agrégation transitive de plusieurs comportements.

L'exemple suivant définit deux directives, `Menu` et `Tooltip`, puis compose leur comportement dans `MenuWithTooltip`. Enfin, il applique `MenuWithTooltip` à `SpecializedMenuWithTooltip`.

Quand `SpecializedMenuWithTooltip` est utilisée dans un template, elle crée des instances de `Menu`, `Tooltip` et `MenuWithTooltip`. Les host bindings de chacune de ces directives s'appliquent au host element de `SpecializedMenuWithTooltip`.

```ts
@Directive({/* ... */})
export class Menu {}

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

// MenuWithTooltip can compose behaviors from multiple other directives
@Directive({
  hostDirectives: [Tooltip, Menu],
})
export class MenuWithTooltip {}

// CustomWidget can apply the already-composed behaviors from MenuWithTooltip
@Directive({
  hostDirectives: [MenuWithTooltip],
})
export class SpecializedMenuWithTooltip {}
```

## Sémantique des host directives {#host-directive-semantics}

### Ordre d'exécution des directives {#directive-execution-order}

Les host directives suivent le même cycle de vie que les composants et les directives utilisés directement dans un template. Cependant, les host directives exécutent toujours leur constructeur, leurs lifecycle hooks et leurs bindings _avant_ le composant ou la directive auquel elles sont appliquées.

L'exemple suivant montre une utilisation minimale d'une host directive :

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

L'ordre d'exécution est ici le suivant :

1. `MenuBehavior` est instanciée
2. `AdminMenu` est instancié
3. `MenuBehavior` reçoit ses inputs (`ngOnInit`)
4. `AdminMenu` reçoit ses inputs (`ngOnInit`)
5. `MenuBehavior` applique ses host bindings
6. `AdminMenu` applique ses host bindings

Cet ordre des opérations signifie que les composants qui utilisent `hostDirectives` peuvent surcharger n'importe quel host binding spécifié par une host directive.

Cet ordre des opérations s'étend aux chaînes imbriquées de host directives, comme le montre l'exemple suivant.

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

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

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

Dans l'exemple ci-dessus, l'ordre d'exécution est le suivant :

1. `Tooltip` est instanciée
2. `CustomTooltip` est instanciée
3. `EvenMoreCustomTooltip` est instanciée
4. `Tooltip` reçoit ses inputs (`ngOnInit`)
5. `CustomTooltip` reçoit ses inputs (`ngOnInit`)
6. `EvenMoreCustomTooltip` reçoit ses inputs (`ngOnInit`)
7. `Tooltip` applique ses host bindings
8. `CustomTooltip` applique ses host bindings
9. `EvenMoreCustomTooltip` applique ses host bindings

### Injection de dépendances {#dependency-injection}

Un composant ou une directive qui spécifie `hostDirectives` peut injecter les instances de ces host directives, et inversement.

Quand vous appliquez des host directives à un composant, le composant et les host directives peuvent tous définir des providers.

Si un composant ou une directive utilisant `hostDirectives` et ses host directives fournissent le même jeton d'injection, les providers définis par la classe qui utilise `hostDirectives` ont la priorité sur ceux définis par les host directives.

### Dédoublonnage des host directives {#host-directive-de-duplication}

Quand la même directive apparaît plusieurs fois dans l'arbre résolu des host directives, elle est automatiquement dédoublonnée au lieu de lever une erreur. Deux règles déterministes décident quelle correspondance est conservée.

#### La correspondance dans le template a la priorité {#template-match-takes-precedence}

Si une directive correspond à un élément une fois via un **selector de template** et apparaît aussi comme **host directive**, Angular ne conserve que la correspondance dans le template et écarte toutes les correspondances en tant que host directive.

Le modèle mental est le suivant : une correspondance en tant que host directive représente `Partial<YourDirective>`, une application partielle où seuls les inputs et les outputs explicitement listés dans `hostDirectives` sont exposés, tandis qu'une correspondance dans le template représente la directive complète avec toute son API publique.

@Directive({selector: '[hoverable]'})
export class Hoverable {}

```ts
@Component({
  selector: 'app-button',
  hostDirectives: [Hoverable],
})
export class Button {}
```

```html


<app-button hoverable></app-button>
```

#### Les correspondances multiples en tant que host directive sont fusionnées {#multiple-host-directive-matches-are-merged}

Si la même directive apparaît **plusieurs fois en tant que host directive**, par exemple quand deux directives déclarent une dépendance commune dans leurs `hostDirectives`, Angular fusionne toutes les instances en une seule instance de directive. Les mappings d'inputs et d'outputs de toutes les instances sont combinés.

Cela résout le classique [problème du diamant](https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem) dans la composition de host directives :

```ts
// A shared behavior that both triggers need
@Directive({
  host: {
    '[attr.data-trigger-id]': 'triggerId()',
  },
})
export class TriggerRef {
  readonly triggerId = input(`trigger-${crypto.randomUUID()}`);
}

// Two separate triggers, each declaring TriggerRef as a host directive
@Directive({
  selector: '[popoverTrigger]',
  hostDirectives: [TriggerRef],
})
export class PopoverTrigger {
  readonly triggerRef = inject(TriggerRef);
}

@Directive({
  selector: '[dropdownTrigger]',
  hostDirectives: [TriggerRef],
})
export class DropdownTrigger {
  readonly triggerRef = inject(TriggerRef);
}
```

```html

<button popoverTrigger dropdownTrigger>Actions</button>
```

HELPFUL: Comme Angular ne produit qu'une seule instance de la directive partagée, `PopoverTrigger` et `DropdownTrigger` reçoivent tous deux la même instance de `TriggerRef` quand ils l'injectent.

#### Alias en conflit {#conflicting-aliases}

Quand Angular fusionne des correspondances de host directive en double, il fusionne aussi leurs mappings d'inputs et d'outputs.

Si deux instances de la même host directive exposent le **même input ou output sous des alias différents**, Angular lève une erreur à la compilation ([NG8024](errors/NG8024)).

```ts
@Directive({
  selector: '[popoverTrigger]',
  hostDirectives: [{directive: TriggerRef, inputs: ['triggerId: popoverTriggerId']}],
})
export class PopoverTrigger {}

@Directive({
  selector: '[dropdownTrigger]',
  hostDirectives: [
    {directive: TriggerRef, inputs: ['triggerId: dropdownTriggerId']}, // different alias!
  ],
})
export class DropdownTrigger {}
```

```html

<button popoverTrigger dropdownTrigger></button>
```

Pour résoudre ce problème, assurez-vous que les deux chemins exposent l'input ou l'output partagé sous le même alias, ou ne l'exposent pas du tout.

## Et ensuite ? {#whats-next}
# Premiers pas avec NgOptimizedImage

La directive `NgOptimizedImage` facilite l'adoption des bonnes pratiques de performance pour le chargement des images.

La directive garantit que le chargement de l'image [Largest Contentful Paint (LCP)](https://web.dev/lcp) est prioritaire en :

- Définissant automatiquement l'attribut `fetchpriority` sur la balise `<img>`
- Chargeant par défaut les autres images en lazy loading
- Générant automatiquement une balise link de preconnect dans le head du document
- Générant automatiquement un attribut `srcset`
- Générant un [preload hint](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) si l'application utilise le SSR

En plus d'optimiser le chargement de l'image LCP, `NgOptimizedImage` impose un certain nombre de bonnes pratiques pour les images, comme :

- Utiliser des [URL de CDN d'images pour appliquer des optimisations d'image](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)
- Empêcher le décalage de mise en page en exigeant `width` et `height`
- Avertir si `width` ou `height` ont été définis de manière incorrecte
- Avertir si l'image sera visuellement déformée lors du rendu

Si vous utilisez une image d'arrière-plan en CSS, [commencez ici](#how-to-migrate-your-background-image).

NOTE: Bien que la directive `NgOptimizedImage` soit devenue une fonctionnalité stable dans Angular 15, elle a été rétroportée et est également disponible comme fonctionnalité stable dans les versions 13.4.0 et 14.3.0.

## Premiers pas {#getting-started}

<docs-workflow>
<docs-step title="Importer la directive `NgOptimizedImage` {#import-ngoptimizedimage-directive}">
Importez la directive `NgOptimizedImage` depuis `@angular/common` :

```ts
import {NgOptimizedImage} from '@angular/common';
```

puis ajoutez-la au tableau `imports` d'un composant standalone ou d'un NgModule :

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

</docs-step>
<docs-step title="(Facultatif) Configurer un loader {#optional-set-up-a-loader}">
Un loader d'images n'est pas **obligatoire** pour utiliser NgOptimizedImage, mais l'utiliser avec un CDN d'images permet de bénéficier de puissantes fonctionnalités de performance, notamment des `srcset` automatiques pour vos images.

Un bref guide de configuration d'un loader est disponible dans la section [Configurer un loader d'images](#configuring-an-image-loader-for-ngoptimizedimage) à la fin de cette page.
</docs-step>
<docs-step title="Activer la directive {#enable-the-directive}">
Pour activer la directive `NgOptimizedImage`, remplacez l'attribut `src` de votre image par `ngSrc`.

```html
<img ngSrc="cat.jpg" />
```

Si vous utilisez un [loader tiers intégré](#built-in-loaders), veillez à omettre le chemin de l'URL de base dans `src`, car le loader l'ajoutera automatiquement en préfixe.
</docs-step>
<docs-step title="Marquer les images comme `priority` {#mark-images-as-priority}">
Marquez toujours l'[image LCP](https://web.dev/lcp/#what-elements-are-considered) de votre page comme `priority` pour rendre son chargement prioritaire.

```html
<img ngSrc="cat.jpg" width="400" height="200" priority />
```

Marquer une image comme `priority` applique les optimisations suivantes :

- Définit `fetchpriority=high` (pour en savoir plus sur les priority hints, voir [ici](https://web.dev/priority-hints))
- Définit `loading=eager` (pour en savoir plus sur le lazy loading natif, voir [ici](https://web.dev/browser-level-image-lazy-loading))
- Génère automatiquement un [élément link de preload](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) en cas de [rendu sur le serveur](guide/ssr).

Angular affiche un avertissement pendant le développement si l'élément LCP est une image dépourvue de l'attribut `priority`. L'élément LCP d'une page peut varier selon plusieurs facteurs, comme les dimensions de l'écran de l'utilisateur ; une page peut donc avoir plusieurs images à marquer comme `priority`. Consultez [CSS for Web Vitals](https://web.dev/css-web-vitals/#images-and-largest-contentful-paint-lcp) pour plus de détails.
</docs-step>
<docs-step title="Indiquer la largeur et la hauteur {#include-width-and-height}">
Afin d'éviter les [décalages de mise en page liés aux images](https://web.dev/css-web-vitals/#images-and-layout-shifts), NgOptimizedImage exige que vous indiquiez une hauteur et une largeur pour votre image, comme suit :

```html
<img ngSrc="cat.jpg" width="400" height="200" />
```

Pour les **images responsives** (images stylées pour s'agrandir et se réduire en fonction du viewport), les attributs `width` et `height` doivent correspondre à la taille intrinsèque du fichier image. Pour les images responsives, il est également important de [définir une valeur pour `sizes`.](#responsive-images)

Pour les **images de taille fixe**, les attributs `width` et `height` doivent refléter la taille de rendu souhaitée de l'image. Le ratio d'aspect de ces attributs doit toujours correspondre au ratio d'aspect intrinsèque de l'image.

NOTE: Si vous ne connaissez pas la taille de vos images, envisagez d'utiliser le « mode fill » pour hériter de la taille du conteneur parent, comme décrit ci-dessous.
</docs-step>
</docs-workflow>

## Utiliser le mode `fill` {#using-fill-mode}

Lorsque vous voulez qu'une image remplisse l'élément qui la contient, vous pouvez utiliser l'attribut `fill`. C'est souvent utile pour obtenir un comportement d'« image d'arrière-plan ». Cela peut aussi être utile lorsque vous ne connaissez pas la largeur et la hauteur exactes de votre image, mais que vous disposez d'un conteneur parent de taille connue dans lequel vous souhaitez faire tenir votre image (voir « object-fit » ci-dessous).

Lorsque vous ajoutez l'attribut `fill` à votre image, vous n'avez pas besoin d'inclure `width` et `height`, et vous ne devez pas le faire, comme dans cet exemple :

```html
<img ngSrc="cat.jpg" fill />
```

Vous pouvez utiliser la propriété CSS [object-fit](https://developer.mozilla.org/docs/Web/CSS/object-fit) pour modifier la manière dont l'image remplit son conteneur. Si vous stylez votre image avec `object-fit: "contain"`, l'image conservera son ratio d'aspect et sera « letterboxée » pour tenir dans l'élément. Si vous définissez `object-fit: "cover"`, l'élément conservera son ratio d'aspect, remplira entièrement l'élément, et une partie du contenu pourra être « rognée ».

Consultez des exemples visuels de ce qui précède dans la [documentation MDN sur object-fit.](https://developer.mozilla.org/docs/Web/CSS/object-fit)

Vous pouvez aussi styler votre image avec la [propriété object-position](https://developer.mozilla.org/docs/Web/CSS/object-position) pour ajuster sa position dans l'élément qui la contient.

IMPORTANT: Pour que l'image « fill » s'affiche correctement, son élément parent **doit** être stylé avec `position: "relative"`, `position: "fixed"` ou `position: "absolute"`.

## Comment migrer votre image d'arrière-plan {#how-to-migrate-your-background-image}

Voici une procédure simple, étape par étape, pour migrer de `background-image` vers `NgOptimizedImage`. Dans ces étapes, nous appellerons « élément conteneur » l'élément qui possède une image d'arrière-plan :

1. Supprimez le style `background-image` de l'élément conteneur.
2. Assurez-vous que l'élément conteneur a `position: "relative"`, `position: "fixed"` ou `position: "absolute"`.
3. Créez un nouvel élément image comme enfant de l'élément conteneur, en utilisant `ngSrc` pour activer la directive `NgOptimizedImage`.
4. Ajoutez l'attribut `fill` à cet élément. N'incluez pas `height` ni `width`.
5. Si vous pensez que cette image pourrait être votre [élément LCP](https://web.dev/lcp/), ajoutez l'attribut `priority` à l'élément image.

Vous pouvez ajuster la manière dont l'image d'arrière-plan remplit le conteneur comme décrit dans la section [Utiliser le mode fill](#using-fill-mode).

## Utiliser des placeholders {#using-placeholders}

### Placeholders automatiques {#automatic-placeholders}

NgOptimizedImage peut afficher un placeholder automatique en basse résolution pour votre image si vous utilisez un CDN ou un hébergeur d'images qui fournit un redimensionnement automatique des images. Tirez parti de cette fonctionnalité en ajoutant l'attribut `placeholder` à votre image :

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder />
```

L'ajout de cet attribut demande automatiquement une seconde version, plus petite, de l'image à l'aide du loader d'images que vous avez spécifié. Cette petite image est appliquée comme style `background-image` avec un flou CSS pendant le chargement de votre image. Si aucun loader d'images n'est fourni, aucune image de placeholder ne peut être générée et une erreur est levée.

La taille par défaut des placeholders générés est de 30px de large. Vous pouvez modifier cette taille en indiquant une valeur en pixels dans le provider `IMAGE_CONFIG`, comme ci-dessous :

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```

Si vous voulez des bords nets autour de votre placeholder flouté, vous pouvez envelopper votre image dans une `<div>` conteneur avec le style `overflow: hidden`. Tant que la `<div>` a la même taille que l'image (par exemple en utilisant le style `width: fit-content`), les « bords flous » du placeholder seront masqués.

### Placeholders en data URL {#data-url-placeholders}

Vous pouvez aussi spécifier un placeholder à l'aide d'une [data URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) en base64, sans loader d'images. Le format de la data URL est `data:image/[imagetype];[data]`, où `[imagetype]` est le format de l'image, comme `png`, et `[data]` est l'encodage en base64 de l'image. Cet encodage peut être effectué en ligne de commande ou en JavaScript. Pour les commandes précises, consultez [la documentation MDN](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs#encoding_data_into_base64_format). Voici un exemple de placeholder en data URL, avec des données tronquées :

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder="data:image/png;base64,iVBORw0K..." />
```

Cependant, les data URL volumineuses augmentent la taille de vos bundles Angular et ralentissent le chargement de la page. Si vous ne pouvez pas utiliser de loader d'images, l'équipe Angular recommande de garder les images de placeholder en base64 sous 4 Ko et de les utiliser exclusivement pour les images critiques. En plus de réduire les dimensions du placeholder, envisagez de changer le format d'image ou les paramètres utilisés lors de l'enregistrement des images. À très basse résolution, ces paramètres peuvent avoir un effet important sur la taille du fichier.

### Placeholders non floutés {#non-blurred-placeholders}

Par défaut, NgOptimizedImage applique un effet de flou CSS aux placeholders d'image. Pour afficher un placeholder sans flou, fournissez un argument `placeholderConfig` avec un objet qui inclut la propriété `blur` définie à false. Par exemple :

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

## Ajuster le style des images {#adjusting-image-styling}

Selon le style de l'image, l'ajout des attributs `width` et `height` peut modifier le rendu de l'image. `NgOptimizedImage` vous avertit si le style de votre image l'affiche avec un ratio d'aspect déformé.

Vous pouvez généralement corriger cela en ajoutant `height: auto` ou `width: auto` aux styles de votre image. Pour plus d'informations, consultez l'[article web.dev sur la balise `<img>`](https://web.dev/patterns/web-vitals-patterns/images/img-tag).

Si les attributs `width` et `height` de l'image vous empêchent de la dimensionner comme vous le souhaitez en CSS, envisagez plutôt d'utiliser le mode `fill` et de styler l'élément parent de l'image.

## Fonctionnalités de performance {#performance-features}

NgOptimizedImage inclut un certain nombre de fonctionnalités conçues pour améliorer les performances de chargement de votre application. Ces fonctionnalités sont décrites dans cette section.

### Ajouter des resource hints {#add-resource-hints}

Un [resource hint `preconnect`](https://web.dev/preconnect-and-dns-prefetch) pour l'origine de vos images garantit que l'image LCP se charge le plus rapidement possible.

Les liens de preconnect sont générés automatiquement pour les domaines fournis en argument à un [loader](#optional-set-up-a-loader). Si l'origine d'une image ne peut pas être identifiée automatiquement et qu'aucun lien de preconnect n'est détecté pour l'image LCP, `NgOptimizedImage` émet un avertissement pendant le développement. Dans ce cas, vous devez ajouter manuellement un resource hint à `index.html`. Dans le `<head>` du document, ajoutez une balise `link` avec `rel="preconnect"`, comme ci-dessous :

```html
<link rel="preconnect" href="https://my.cdn.origin" />
```

Pour désactiver les avertissements de preconnect, injectez le jeton `PRECONNECT_CHECK_BLOCKLIST` :

```ts
providers: [
{provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

```

Pour plus d'informations sur la génération automatique du preconnect, voir [ici](#why-is-a-preconnect-element-not-being-generated-for-my-image-domain).

### Demander les images à la bonne taille avec le `srcset` automatique {#request-images-at-the-correct-size-with-automatic-srcset}

Définir un [attribut `srcset`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset) garantit que le navigateur demande une image à la bonne taille pour le viewport de votre utilisateur, afin de ne pas perdre de temps à télécharger une image trop grande. `NgOptimizedImage` génère un `srcset` approprié pour l'image, en fonction de la présence et de la valeur de l'[attribut `sizes`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) sur la balise image.

#### Images de taille fixe {#fixed-size-images}

Si votre image doit avoir une taille « fixe » (c'est-à-dire la même taille sur tous les appareils, à la [densité de pixels](https://web.dev/codelab-density-descriptors/) près), il n'est pas nécessaire de définir un attribut `sizes`. Un `srcset` peut être généré automatiquement à partir des attributs width et height de l'image, sans autre information requise.

Exemple de srcset généré :

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

#### Images responsives {#responsive-images}

Si votre image doit être responsive (c'est-à-dire s'agrandir et se réduire selon la taille du viewport), vous devrez définir un [attribut `sizes`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) pour générer le `srcset`.

Si vous n'avez jamais utilisé `sizes`, un bon point de départ consiste à le définir en fonction de la largeur du viewport. Par exemple, si votre CSS fait occuper à l'image 100 % de la largeur du viewport, définissez `sizes` à `100vw` et le navigateur sélectionnera l'image du `srcset` la plus proche de la largeur du viewport (après prise en compte de la densité de pixels). Si votre image n'occupera probablement que la moitié de l'écran (par ex. dans une barre latérale), définissez `sizes` à `50vw` pour que le navigateur sélectionne une image plus petite. Et ainsi de suite.

Si ce qui précède ne couvre pas le comportement souhaité pour votre image, consultez la documentation sur les [valeurs avancées de sizes](#advanced-sizes-values).

Notez que pour les images chargées en lazy loading, `NgOptimizedImage` ajoute automatiquement `"auto"` en préfixe à la valeur `sizes` fournie. Cette optimisation améliore la précision de la sélection dans le srcset sur les navigateurs qui prennent en charge `sizes="auto"`, et elle est ignorée par ceux qui ne la prennent pas en charge. Les images qui ne sont pas chargées en lazy loading, comme les images `priority`, conservent la valeur `sizes` telle que fournie.

Par défaut, les points de rupture responsives sont :

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

Si vous souhaitez personnaliser ces points de rupture, vous pouvez le faire avec le provider `IMAGE_CONFIG` :

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],
```

Si vous souhaitez définir manuellement un attribut `srcset`, vous pouvez fournir le vôtre avec l'attribut `ngSrcset` :

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" />
```

Si l'attribut `ngSrcset` est présent, `NgOptimizedImage` génère et définit le `srcset` en fonction des tailles indiquées. N'incluez pas de noms de fichiers d'images dans `ngSrcset` : la directive déduit cette information de `ngSrc`. La directive prend en charge à la fois les descripteurs de largeur (par ex. `100w`) et les descripteurs de densité (par ex. `1x`).

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw" />
```

### Désactiver la génération automatique du srcset {#disabling-automatic-srcset-generation}

Pour désactiver la génération du srcset pour une seule image, vous pouvez ajouter l'attribut `disableOptimizedSrcset` sur l'image :

```html
<img ngSrc="about.jpg" disableOptimizedSrcset />
```

### Désactiver le lazy loading des images {#disabling-image-lazy-loading}

Par défaut, `NgOptimizedImage` définit `loading=lazy` pour toutes les images qui ne sont pas marquées `priority`. Vous pouvez désactiver ce comportement pour les images non prioritaires en définissant l'attribut `loading`. Cet attribut accepte les valeurs `eager`, `auto` et `lazy`. [Consultez la documentation de l'attribut standard `loading` des images pour plus de détails](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/loading#value).

```html
<img ngSrc="cat.jpg" width="400" height="200" loading="eager" />
```

### Contrôler le décodage des images {#controlling-image-decoding}

Par défaut, `NgOptimizedImage` définit `decoding="auto"` pour toutes les images. Cela permet au navigateur de choisir le moment optimal pour décoder une image après l'avoir récupérée. Lorsqu'une image est marquée comme `priority`, Angular définit automatiquement `decoding="sync"` pour que l'image soit décodée et affichée le plus tôt possible, ce qui aide à améliorer les performances du **Largest Contentful Paint (LCP)**.

Vous pouvez remplacer la valeur par défaut `auto` pour les images non prioritaires en définissant explicitement l'attribut `decoding`. Les images prioritaires utilisent toujours `decoding="sync"`.  
[Consultez la documentation de l'attribut standard `decoding` des images pour plus de détails](https://developer.mozilla.org/docs/Web/HTML/Element/img#decoding).

```html

<img ngSrc="gallery/landscape.jpg" width="1200" height="800" />

<img ngSrc="gallery/preview.jpg" width="600" height="400" decoding="async" />

<img ngSrc="awesome.jpg" width="500" height="625" priority />

<img ngSrc="hero.jpg" width="1600" height="900" decoding="sync" />
```

**Valeurs autorisées**

- `auto` (par défaut) : laisse le navigateur choisir la stratégie optimale.
- `async` : décode l'image de manière asynchrone, en évitant si possible de bloquer le thread principal.
- `sync` : décode l'image immédiatement ; peut bloquer le rendu, mais garantit que les pixels sont prêts dès que l'image est disponible.

### Valeurs avancées de 'sizes' {#advanced-sizes-values}

Vous pouvez vouloir afficher des images avec des largeurs variables selon la taille des écrans. Un exemple courant de ce pattern est une mise en page en grille ou en colonnes qui affiche une seule colonne sur les appareils mobiles et deux colonnes sur les appareils plus grands. Vous pouvez exprimer ce comportement dans l'attribut `sizes`, à l'aide d'une syntaxe de « media query », comme ci-dessous :

```html
<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw" />
```

Dans l'exemple ci-dessus, l'attribut `sizes` signifie : « Je m'attends à ce que cette image occupe 100 % de la largeur de l'écran sur les appareils de moins de 768px de large. Sinon, je m'attends à ce qu'elle occupe 50 % de la largeur de l'écran. »

Pour plus d'informations sur l'attribut `sizes`, consultez [web.dev](https://web.dev/learn/design/responsive-images/#sizes) ou [mdn](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes).

## Configurer un loader d'images pour `NgOptimizedImage` {#configuring-an-image-loader-for-ngoptimizedimage}

Un « loader » est une fonction qui génère une [URL de transformation d'image](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options) pour un fichier image donné. Lorsque c'est approprié, `NgOptimizedImage` définit les transformations de taille, de format et de qualité d'une image.

`NgOptimizedImage` fournit à la fois un loader générique qui n'applique aucune transformation, et des loaders pour divers services d'images tiers. La directive permet aussi d'écrire votre propre loader personnalisé.

| Type de loader                            | Comportement                                                                                                                                                                                                                       |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Loader générique                         | L'URL renvoyée par le loader générique correspond toujours à la valeur de `src`. Autrement dit, ce loader n'applique aucune transformation. Les sites qui utilisent Angular pour servir des images constituent le principal cas d'usage prévu pour ce loader. |
| Loaders pour les services d'images tiers | L'URL renvoyée par les loaders des services d'images tiers suit les conventions d'API propres à ce service d'images.                                                                                              |
| Loaders personnalisés                         | Le comportement d'un loader personnalisé est défini par son développeur. Utilisez un loader personnalisé si votre service d'images n'est pas pris en charge par les loaders préconfigurés fournis avec `NgOptimizedImage`.                                   |

En fonction des services d'images couramment utilisés avec les applications Angular, `NgOptimizedImage` fournit des loaders préconfigurés pour fonctionner avec les services d'images suivants :

Pour utiliser le **loader générique**, aucune modification de code supplémentaire n'est nécessaire. C'est le comportement par défaut.

### Loaders intégrés {#built-in-loaders}

Pour utiliser un loader existant pour un **service d'images tiers**, ajoutez la fabrique de provider du service choisi au tableau `providers`. Dans l'exemple ci-dessous, le loader Imgix est utilisé :

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

L'URL de base de vos ressources d'images doit être passée en argument à la fabrique de provider. Pour la plupart des sites, cette URL de base doit correspondre à l'un des motifs suivants :

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

Pour en savoir plus sur la structure de l'URL de base, consultez la documentation du fournisseur de CDN correspondant.

### Loaders personnalisés {#custom-loaders}

Pour utiliser un **loader personnalisé**, fournissez votre fonction de loader comme valeur du jeton d'injection `IMAGE_LOADER`. Dans l'exemple ci-dessous, la fonction de loader personnalisée renvoie une URL commençant par `https://example.com` qui inclut `src`, `width` et `height` comme paramètres d'URL.

```ts
providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}&height=${config.height}`;
    },
  },
],
```

Une fonction de loader pour la directive `NgOptimizedImage` prend en argument un objet de type `ImageLoaderConfig` (issu de `@angular/common`) et renvoie l'URL absolue de la ressource image. L'objet `ImageLoaderConfig` contient la propriété `src`, ainsi que les propriétés facultatives `width`, `height` et `loaderParams`.

NOTE: même si la propriété `width` n'est pas toujours présente, un loader personnalisé doit l'utiliser pour permettre de demander des images de différentes largeurs, afin que `ngSrcset` fonctionne correctement.

### La propriété `loaderParams` {#the-loaderparams-property}

La directive `NgOptimizedImage` prend en charge un attribut supplémentaire, appelé `loaderParams`, spécialement conçu pour l'utilisation de loaders personnalisés. L'attribut `loaderParams` prend comme valeur un objet avec des propriétés quelconques, et ne fait rien par lui-même. Les données de `loaderParams` sont ajoutées à l'objet `ImageLoaderConfig` passé à votre loader personnalisé, et peuvent servir à contrôler le comportement du loader.

Un usage courant de `loaderParams` consiste à contrôler les fonctionnalités avancées d'un CDN d'images.

### Utiliser la propriété `transform` avec les loaders intégrés {#using-the-transform-property-with-built-in-loaders}

Les loaders intégrés pour Cloudinary, Cloudflare, ImageKit et Imgix prennent en charge une propriété spéciale `transform` dans `loaderParams`. Cette propriété vous permet d'appliquer des transformations d'image personnalisées fournies par votre CDN.

La propriété `transform` accepte deux formats :

#### Format chaîne {#string-format}

Fournissez les transformations sous forme de chaîne séparée par des virgules, en utilisant la syntaxe de transformation de votre CDN :

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: 'e_grayscale,r_10'}"
/>
```

#### Format objet {#object-format}

Fournissez les transformations sous forme d'objet avec des paires clé-valeur.

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: {e: 'grayscale', r: 10}}"
/>
```

NOTE: La propriété `transform` n'est pas prise en charge par le loader Netlify, car le CDN d'images de Netlify ne fournit pas de paramètres de transformation personnalisés.

### Exemple de loader personnalisé {#example-custom-loader}

Voici un exemple de fonction de loader personnalisée. Cette fonction d'exemple concatène `src`, `width` et `height`, et utilise `loaderParams` pour contrôler une fonctionnalité de CDN personnalisée pour les coins arrondis :

```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.height) {
    queryParams.push(`h=${config.height}`);
  }
  if (config.loaderParams?.roundedCorners) {
    queryParams.push('mask=corners&corner-radius=5');
  }
  return url + queryParams.join('&');
};
```

Notez que dans l'exemple ci-dessus, nous avons inventé le nom de propriété 'roundedCorners' pour contrôler une fonctionnalité de notre loader personnalisé. Nous pourrions ensuite utiliser cette fonctionnalité lors de la création d'une image, comme suit :

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

## Questions fréquentes {#frequently-asked-questions}

### NgOptimizedImage prend-il en charge la propriété CSS `background-image` ? {#does-ngoptimizedimage-support-the-background-image-css-property}

NgOptimizedImage ne prend pas directement en charge la propriété CSS `background-image`, mais la directive est conçue pour s'adapter facilement au cas d'usage d'une image servant d'arrière-plan à un autre élément.

Pour une procédure étape par étape de migration de `background-image` vers `NgOptimizedImage`, consultez la section [Comment migrer votre image d'arrière-plan](#how-to-migrate-your-background-image) ci-dessus.

### Pourquoi ne puis-je pas utiliser `src` avec `NgOptimizedImage` ? {#why-cant-i-use-src-with-ngoptimizedimage}

L'attribut `ngSrc` a été choisi comme déclencheur de NgOptimizedImage pour des raisons techniques liées à la manière dont le navigateur charge les images. NgOptimizedImage modifie programmatiquement l'attribut `loading` : si le navigateur voit l'attribut `src` avant que ces modifications ne soient effectuées, il commence immédiatement à télécharger le fichier image, et les modifications de chargement sont ignorées.

### Pourquoi aucun élément preconnect n'est-il généré pour le domaine de mes images ? {#why-is-a-preconnect-element-not-being-generated-for-my-image-domain}

La génération du preconnect repose sur une analyse statique de votre application. Cela signifie que le domaine des images doit être inclus directement dans le paramètre du loader, comme dans l'exemple suivant :

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

Si vous utilisez une variable pour passer la chaîne du domaine au loader, ou si vous n'utilisez pas de loader, l'analyse statique ne pourra pas identifier le domaine et aucun lien de preconnect ne sera généré. Dans ce cas, vous devez ajouter manuellement un lien de preconnect dans le head du document, comme [décrit ci-dessus](#add-resource-hints).

### Puis-je utiliser deux domaines d'images différents dans la même page ? {#can-i-use-two-different-image-domains-in-the-same-page}

Le pattern de provider des [loaders d'images](#configuring-an-image-loader-for-ngoptimizedimage) est conçu pour être aussi simple que possible dans le cas d'usage courant d'un seul CDN d'images utilisé dans un composant. Il reste toutefois tout à fait possible de gérer plusieurs CDN d'images avec un seul provider.

Pour cela, nous recommandons d'écrire un [loader d'images personnalisé](#custom-loaders) qui utilise la [propriété `loaderParams`](#the-loaderparams-property) pour transmettre un indicateur précisant quel CDN d'images utiliser, puis qui invoque le loader approprié en fonction de cet indicateur.

### Pouvez-vous ajouter un nouveau loader intégré pour mon CDN préféré ? {#can-you-add-a-new-built-in-loader-for-my-preferred-cdn}

Pour des raisons de maintenance, nous ne prévoyons pas actuellement de prendre en charge d'autres loaders intégrés dans le dépôt Angular. Nous encourageons plutôt les développeurs à publier tout loader d'images supplémentaire sous forme de packages tiers.

### Puis-je l'utiliser avec la balise `<picture>` ? {#can-i-use-this-with-the-picture-tag}

Non, mais c'est prévu dans notre feuille de route, alors restez à l'écoute.

Si vous attendez cette fonctionnalité, votez pour l'issue GitHub [ici](https://github.com/angular/angular/issues/56594).

### Comment trouver mon image LCP avec les Chrome DevTools ? {#how-do-i-find-my-lcp-image-with-chrome-devtools}

1. Dans l'onglet Performance des Chrome DevTools, cliquez sur le bouton « start profiling and reload page » en haut à gauche. Il ressemble à une icône d'actualisation de page.

2. Cela déclenche un snapshot de profilage de votre application Angular.

3. Une fois le résultat du profilage disponible, sélectionnez « LCP » dans la section des timings.

4. Une entrée de résumé devrait apparaître dans le panneau du bas. Vous trouverez l'élément LCP sur la ligne « related node ». Cliquer dessus affiche l'élément dans le panneau Elements.

NOTE: Cela n'identifie que l'élément LCP dans le viewport de la page que vous testez. Il est également recommandé d'utiliser l'émulation mobile pour identifier l'élément LCP sur les écrans plus petits.
Dans Angular, vous utilisez des _signals_ pour créer et gérer l'état. Un signal est une enveloppe légère autour d'une valeur.

Utilisez la fonction `signal` pour créer un signal qui contient un état local :

```typescript
import {signal} from '@angular/core';

// Create a signal with the `signal` function.
const firstName = signal('Morgan');

// Read a signal value by calling it— signals are functions.
console.log(firstName());

// Change the value of this signal by calling its `set` method with a new value.
firstName.set('Jaime');

// You can also use the `update` method to change the value
// based on the previous value.
firstName.update((name) => name.toUpperCase());
```

Angular suit l'endroit où les signals sont lus et le moment où ils sont mis à jour. Le framework utilise ces informations pour effectuer du travail supplémentaire, comme mettre à jour le DOM avec le nouvel état. Cette capacité à réagir aux changements de valeur des signals au fil du temps s'appelle la _réactivité_.

## Expressions computed {#computed-expressions}

Un `computed` est un signal qui produit sa valeur à partir d'autres signals.

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());

console.log(firstNameCapitalized()); // MORGAN
```

Un signal `computed` est en lecture seule ; il n'a pas de méthode `set` ni `update`. À la place, la valeur du signal `computed` change automatiquement quand l'un des signals qu'il lit change :

```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
```

## Utiliser les signals dans les composants {#using-signals-in-components}

Utilisez `signal` et `computed` dans vos composants pour créer et gérer l'état :

```ts
@Component({
  /* ... */
})
export class UserProfile {
  isTrial = signal(false);
  isTrialExpired = signal(false);
  showTrialDuration = computed(() => this.isTrial() && !this.isTrialExpired());

activateTrial() {
    this.isTrial.set(true);
  }
}
```

TIP: Vous voulez en savoir plus sur les Angular Signals ? Consultez le [guide approfondi des signals](guide/signals) pour tous les détails.

## Étape suivante {#next-step}

Maintenant que vous savez déclarer et gérer des données dynamiques, il est temps d'apprendre à utiliser ces données dans les templates.
# État dépendant avec `linkedSignal`

Vous pouvez utiliser la fonction `signal` pour contenir un état dans votre code Angular. Parfois, cet état dépend d'un _autre_ état. Par exemple, imaginez un composant qui permet à l'utilisateur de sélectionner un mode de livraison pour une commande :

```typescript
@Component({
  /* ... */
})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// Select the first shipping option by default.
  selectedOption = signal(this.shippingOptions()[0]);

changeShipping(newOptionIndex: number) {
    this.selectedOption.set(this.shippingOptions()[newOptionIndex]);
  }
}
```

Dans cet exemple, `selectedOption` vaut par défaut la première option, mais change si l'utilisateur sélectionne une autre option. Mais `shippingOptions` est un signal — sa valeur peut changer ! Si `shippingOptions` change, `selectedOption` peut contenir une valeur qui n'est plus une option valide.

**La fonction `linkedSignal` vous permet de créer un signal qui contient un état intrinsèquement _lié_ à un autre état.** Si l'on reprend l'exemple ci-dessus, `linkedSignal` peut remplacer `signal` :

```ts
@Component({
  /* ... */
})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// Initialize selectedOption to the first shipping option.
  selectedOption = linkedSignal(() => this.shippingOptions()[0]);

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }
}
```

`linkedSignal` fonctionne comme `signal`, à une différence près : au lieu de passer une valeur par défaut, vous passez une _fonction de calcul_, exactement comme pour `computed`. Quand la valeur du calcul change, la valeur du `linkedSignal` devient le résultat du calcul. Cela permet de garantir que le `linkedSignal` a toujours une valeur valide.

L'exemple suivant montre comment la valeur d'un `linkedSignal` peut changer en fonction de l'état auquel il est lié :

```ts
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'
```

## Prendre en compte l'état précédent {#accounting-for-previous-state}

Dans certains cas, le calcul d'un `linkedSignal` doit prendre en compte la valeur précédente du `linkedSignal`.

Dans l'exemple ci-dessus, `selectedOption` revient toujours à la première option quand `shippingOptions` change. Vous pouvez cependant vouloir conserver la sélection de l'utilisateur si l'option qu'il a choisie se trouve toujours dans la liste. Pour cela, vous pouvez créer un `linkedSignal` avec une _source_ et un _calcul_ séparés :

```ts
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` is set to the `computation` result whenever this `source` changes.
    source: this.shippingOptions,
    computation: (newOptions, previous) => {
      // If the newOptions contain the previously selected option, preserve that selection.
      // Otherwise, default to the first option.
      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'},
    ]);
  }
}
```

Quand vous créez un `linkedSignal`, vous pouvez passer un objet avec des propriétés `source` et `computation` séparées au lieu de fournir uniquement un calcul.

La `source` peut être n'importe quel signal, comme un `computed` ou un `input` de composant. Le `linkedSignal` met à jour sa valeur quand la `source` change ou quand l'un des signals référencés dans `computation` change, en prenant comme valeur le résultat de la `computation` fournie.

La `computation` est une fonction qui reçoit la nouvelle valeur de `source` et un objet `previous`. L'objet `previous` a deux propriétés : `previous.source` est la valeur précédente de `source`, et `previous.value` est la valeur précédente du `linkedSignal`. Vous pouvez utiliser ces valeurs précédentes pour déterminer le nouveau résultat du calcul.

HELPFUL: Quand vous utilisez le paramètre `previous`, il est nécessaire de fournir explicitement les arguments de type génériques de `linkedSignal`. Le premier type générique correspond au type de `source` et le second détermine le type de sortie de `computation`.

## Comparaison d'égalité personnalisée {#custom-equality-comparison}

Comme tout autre signal, `linkedSignal` peut être configuré avec une fonction d'égalité personnalisée. Cette fonction est utilisée par les dépendances en aval pour déterminer si la valeur du `linkedSignal` (le résultat d'un calcul) a changé :

```typescript
const activeUser = signal({id: 123, name: 'Morgan', isAdmin: true});

const activeUserEditCopy = linkedSignal(() => activeUser(), {
  // Consider the user as the same if it's the same `id`.
  equal: (a, b) => a.id === b.id,
});

// Or, if separating `source` and `computation`
const activeUserEditCopy = linkedSignal({
  source: activeUser,
  computation: (user) => user,
  equal: (a, b) => a.id === b.id,
});
```

## Personnaliser l'opération set {#customizing-the-set-operation}

Vous pouvez parfois vouloir que les opérations `set` et `update` d'un `linkedSignal` écrivent dans la source de vérité au lieu de mettre à jour directement la valeur du `linkedSignal`. Vous pouvez personnaliser ce comportement en passant une fonction `set` dans les options.

La fonction `set` personnalisée reçoit deux arguments :

1. La nouvelle valeur à définir.
2. Une fonction `rawSet`, que vous pouvez appeler pour mettre à jour directement l'état interne du `linkedSignal` (comme le fait le comportement par défaut).

NOTE: Utiliser `rawSet` vous permet de mettre à jour directement la valeur du `linkedSignal`. Cela peut être utile pour éviter l'exécution du calcul, par exemple s'il s'agit d'une dérivation coûteuse et que vous connaissez déjà le résultat.

### Écrire dans un signal source {#writing-back-to-a-source-signal}

Prenons un composant qui affiche une température en Fahrenheit et permet de la modifier, mais qui utilise un signal en Celsius comme source de vérité :

```typescript
const tempC = signal(0);
const tempF = linkedSignal(() => (tempC() * 9) / 5 + 32, {
  set: (valF) => tempC.set(((valF - 32) * 5) / 9),
});

console.log(tempF()); // 32

// Setting Fahrenheit updates Celsius, which reactively updates Fahrenheit
tempF.set(212);
console.log(tempC()); // 100
console.log(tempF()); // 212
```

### Mettre à jour une propriété dans un objet parent {#updating-a-property-inside-a-parent-object}

Un autre scénario courant consiste à mettre à jour une propriété précise dans un objet parent. Le parent est contenu dans un signal, et vous vous liez à une propriété imbriquée :

```typescript
interface Order {
  id: number;
  shippingMethod: string;
}

const order = signal<Order>({
  id: 42,
  shippingMethod: 'Ground',
});

const shippingMethod = linkedSignal(() => order().shippingMethod, {
  set: (newMethod) => {
    // Perform an immutable update to write the change back to the order
    order.update((currentOrder) => ({
      ...currentOrder,
      shippingMethod: newMethod,
    }));
  },
});

console.log(shippingMethod()); // 'Ground'

// Updating the shippingMethod updates the parent order object
shippingMethod.set('Air');
console.log(order()); // { id: 42, shippingMethod: 'Air' }
console.log(shippingMethod()); // 'Air'
```
# Réactivité asynchrone avec les resources

Toutes les API de signals sont synchrones : `signal`, `computed`, `input`, etc. Pourtant, les applications doivent souvent gérer des données disponibles de manière asynchrone. Une `Resource` vous permet d'intégrer des données asynchrones dans le code de votre application basé sur les signals, tout en vous permettant d'accéder à ces données de manière synchrone.

Vous pouvez utiliser une `Resource` pour effectuer n'importe quel type d'opération asynchrone, mais le cas d'usage le plus courant d'une `Resource` est la récupération de données depuis un serveur. L'exemple suivant crée une resource pour récupérer des données utilisateur.

Le moyen le plus simple de créer une `Resource` est la fonction `resource`.

```typescript
import {computed, resource, Signal} from '@angular/core';

const userId: Signal<string> = getUserId();

const userResource = resource({
  // Define a reactive computation.
  // The params value recomputes whenever any read signals change.
  params: () => ({id: userId()}),

// Define an async loader that retrieves data.
  // The resource calls this function every time the `params` value changes.
  loader: ({params}) => fetchUser(params),
});

// Create a computed signal based on the result of the resource's loader function.
const firstName = computed(() => {
  if (userResource.hasValue()) {
    // `hasValue` serves 2 purposes:
    // - It acts as type guard to strip `undefined` from the type
    // - It protects against reading a throwing `value` when the resource is in error state
    return userResource.value().firstName;
  }

// fallback in case the resource value is `undefined` or if the resource is in error state
  return undefined;
});
```

La fonction `resource` accepte un objet `ResourceOptions` avec deux propriétés principales : `params` et `loader`.

La propriété `params` définit un calcul réactif qui produit une valeur de paramètre. Chaque fois que les signals lus dans ce calcul changent, la resource produit une nouvelle valeur de paramètre, comme le fait `computed`.

La propriété `loader` définit un `ResourceLoader` : une fonction asynchrone qui récupère un état. La resource appelle le loader chaque fois que le calcul `params` produit une nouvelle valeur, en lui passant cette valeur. Consultez la section [Loaders de resources](#resource-loaders) ci-dessous pour plus de détails.

`Resource` possède un signal `value` qui contient les résultats du loader.

## Loaders de resources {#resource-loaders}

Quand vous créez une resource, vous spécifiez un `ResourceLoader`. Ce loader est une fonction asynchrone qui accepte un unique paramètre (un objet `ResourceLoaderParams`) et renvoie une valeur.

L'objet `ResourceLoaderParams` contient trois propriétés : `params`, `previous` et `abortSignal`.

| Propriété     | Description                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`      | La valeur du calcul `params` de la resource.                                                                                                    |
| `previous`    | Un objet avec une propriété `status`, contenant le `ResourceStatus` précédent.                                                                   |
| `abortSignal` | Un [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). Consultez [Annuler des requêtes](#aborting-requests) ci-dessous pour plus de détails. |

Si le calcul `params` renvoie `undefined`, la fonction loader ne s'exécute pas et le statut de la resource devient `'idle'`.

### Resources en streaming {#streaming-resources}

Certaines sources de données asynchrones produisent plusieurs valeurs au fil du temps au lieu de renvoyer un résultat unique. C'est le cas par exemple des WebSockets, des Server-Sent Events (SSE) et des écouteurs `onSnapshot` de Firestore.

Utilisez `stream` pour ces sources de données mises à jour en continu. Contrairement à `loader`, qui se résout une fois pour chaque requête, `stream` renvoie un signal dont la valeur peut continuer à se mettre à jour à mesure que de nouvelles données deviennent disponibles.

Utilisez `loader` pour les opérations asynchrones ponctuelles, comme la récupération de données depuis un endpoint HTTP.

Dans cet exemple, `userUpdates` simule une source externe comme une connexion WebSocket ou SSE.

```typescript
const userUpdates = signal({value: 'Alice'});

const userResource = resource({
  stream: () => userUpdates,
});

// Simulate a new value arriving from the external data source:
userUpdates.set({value: 'Bob'});
```

### Annuler des requêtes {#aborting-requests}

Une resource annule une opération de chargement en cours si le calcul `params` change pendant que la resource charge.

Vous pouvez utiliser l'`abortSignal` de `ResourceLoaderParams` pour réagir aux requêtes annulées. Par exemple, la fonction native `fetch` accepte un `AbortSignal` :

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params, abortSignal}): Promise<User> => {
    // fetch cancels any outstanding HTTP requests when the given `AbortSignal`
    // indicates that the request has been aborted.
    return fetch(`users/${params.id}`, {signal: abortSignal}).then((res) => res.json());
  },
});
```

Consultez [`AbortSignal` sur MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) pour plus de détails sur l'annulation de requêtes avec `AbortSignal`.

### Rechargement {#reloading}

Vous pouvez déclencher programmatiquement le `loader` d'une resource en appelant la méthode `reload`.

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();
```

## Statut d'une resource {#resource-status}

L'objet resource possède plusieurs propriétés signal permettant de lire le statut du loader asynchrone.

| Propriété   | Description                                                                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`     | La valeur la plus récente de la resource, ou la valeur par défaut (`undefined` sauf si `defaultValue` est défini) si aucune valeur n'a été reçue. Lire `value()` lève une erreur quand le statut est `'error'`. |
| `hasValue`  | Indique si la resource a une valeur.                                                                                                                                                        |
| `error`     | La dernière erreur rencontrée lors de l'exécution du loader de la resource, ou `undefined` si aucune erreur ne s'est produite.                                                              |
| `isLoading` | Indique si le loader de la resource est en cours d'exécution.                                                                                                                               |
| `status`    | Le `ResourceStatus` précis de la resource, comme décrit ci-dessous.                                                                                                                         |

Le signal `status` fournit un `ResourceStatus` précis qui décrit l'état de la resource à l'aide d'une constante de type chaîne.

| Statut        | `value()`         | Description                                                                  |
| ------------- | :---------------- | ---------------------------------------------------------------------------- |
| `'idle'`      | `undefined`       | La resource n'a pas de requête valide et le loader ne s'est pas exécuté.    |
| `'error'`     | Lève une erreur   | Le loader a rencontré une erreur.                                            |
| `'loading'`   | `undefined`       | Le loader s'exécute suite au changement de la valeur `params`.               |
| `'reloading'` | Valeur précédente | Le loader s'exécute suite à l'appel de la méthode `reload` de la resource.  |
| `'resolved'`  | Valeur résolue    | Le loader a terminé.                                                         |
| `'local'`     | Valeur définie localement | La valeur de la resource a été définie localement via `.set()` ou `.update()` |

Vous pouvez utiliser ces informations de statut pour afficher conditionnellement des éléments d'interface utilisateur, comme des indicateurs de chargement et des messages d'erreur.

## Mettre en cache les données de `resource` avec le SSR {#caching-resource-data-with-ssr}

Quand une application est rendue sur le serveur, un loader de resource s'exécute une fois pour produire le HTML initial. Pendant l'hydratation, le navigateur exécute normalement à nouveau le même loader.

Pour réutiliser le résultat du serveur, fournissez un `id` pour la resource. Angular stocke la valeur résolue dans `TransferState` sur le serveur et l'utilise côté client pour initialiser la resource dans un état `'resolved'`.

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
  id: 'user-unique-id',
});
```

La valeur de `id` doit être unique dans votre application et identique sur le serveur et le client, afin qu'Angular puisse faire correspondre l'entrée en cache à la resource qui l'a demandée.

IMPORTANT: Comme la valeur en cache est sérialisée dans le HTML de la page, évitez de définir `id` sur les resources qui chargent des données propres à l'utilisateur ayant déclenché le rendu côté serveur, en particulier si le HTML rendu peut être mis en cache ou partagé entre utilisateurs.

## Chaîner des resources {#chaining-resources}

Parfois, une resource dépend du résultat d'une autre. Vous pouvez exprimer cette dépendance avec la fonction `chain` disponible dans l'objet de contexte de `params`.

```typescript
import {resource} from '@angular/core';

const userResource = resource({
  params: () => ({id: getUserId()}),
  loader: ({params}) => fetchUser(params),
});

const companyResource = resource({
  params: ({chain}) => chain(userResource)?.companyId,
  loader: ({params: companyId}) => fetchCompany(companyId),
});
```

Ici, `companyResource` dépend du `companyId` de l'utilisateur, qui n'est connu qu'une fois `userResource` chargée. `chain(userResource)` lit la valeur de `userResource` et propage automatiquement son statut à `companyResource` :

- Si `userResource` est **idle**, `companyResource` devient également `idle`.
- Si `userResource` est **loading** ou **reloading**, `companyResource` passe à l'état `loading` et son loader ne s'exécute pas. Notez que pendant `reloading`, `chain` ne renvoie pas la valeur résolue précédemment.
- Si `userResource` est dans un état **error**, `companyResource` passe également à l'état `error`.
- Si `userResource` est **resolved** ou **local**, `chain` renvoie sa valeur actuelle, que `companyResource` utilise alors comme params.

Quand `chain` propage un statut de `userResource` (`idle`, `loading`, `reloading` ou `error`), la fonction params ne continue pas. Quand `userResource` est `resolved` ou `local`, `chain` renvoie sa valeur, qui peut elle-même être `undefined`. L'exemple gère ce cas avec `chain(userResource)?.companyId`, de sorte qu'une valeur `undefined` donne des params `undefined` et que `companyResource` devient `idle`.

NOTE: Passez directement la valeur chaînée comme valeur de params, au lieu de l'envelopper dans un objet. Une valeur de params comme `{companyId: undefined}` reste une valeur définie : le loader s'exécuterait donc avec un `companyId` `undefined` au lieu que la resource devienne `idle`.

### Chaîner ou lire directement les valeurs d'une resource {#chaining-vs-reading-resource-values-directly}

Vous pourriez être tenté de lire directement la valeur d'une resource dans `params` :

```typescript
{avoid, header: 'reads value() directly without status propagation'}
const companyResource = resource({
  params: () => {
    const user = userResource.value(); // may be undefined
    return user ? {companyId: user.companyId} : undefined;
  },
  loader: ({params}) => fetchCompany(params.companyId),
});
```

Même si cela fonctionne, renvoyer `undefined` depuis `params` fait passer la resource à l'état `idle` au lieu de refléter l'état réel de la resource en amont. Il est préférable d'utiliser `chain`, car cette fonction reflète correctement les états `loading` et `error`.

N'utilisez `chain` que lorsque la resource en aval effectue son propre travail asynchrone qui dépend de la valeur en amont. Si vous avez seulement besoin de dériver une valeur de manière synchrone à partir d'une resource, utilisez plutôt `computed`.

## Récupération de données réactive avec `httpResource` {#reactive-data-fetching-with-httpresource}

[`httpResource`](/guide/http/http-resource) est une enveloppe autour de `HttpClient` qui vous fournit le statut de la requête et la réponse sous forme de signals. Elle effectue les requêtes HTTP via la pile HTTP d'Angular, intercepteurs compris.

## Composition de resources avec des snapshots {#resource-composition-with-snapshots}

Un `ResourceSnapshot` est une représentation structurée de l'état actuel d'une resource. Chaque resource possède une propriété `snapshot` qui fournit un signal de son état actuel.

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

const userSnapshot = userResource.snapshot;
```

Chaque snapshot contient un `status` et soit une `value`, soit une `error`.

### Composer des resources avec des snapshots {#composing-resources-with-snapshots}

IMPORTANT: `resourceFromSnapshots` est [expérimental](reference/releases#experimental). Vous pouvez l'essayer dès maintenant, mais il pourrait changer avant d'être stable.

Vous pouvez créer de nouvelles resources à partir de snapshots avec `resourceFromSnapshots`. Cela permet la composition avec des API de signals comme `computed` et `linkedSignal` pour transformer le comportement d'une resource.

```ts
import {
  Component,
  input,
  linkedSignal,
  resourceFromSnapshots,
  Resource,
  ResourceSnapshot,
} from '@angular/core';
import {httpResource} from '@angular/common/http';

function withPreviousValue<T>(input: Resource<T>): Resource<T> {
  const derived = linkedSignal<ResourceSnapshot<T>, ResourceSnapshot<T>>({
    source: input.snapshot,
    computation: (snap, previous) => {
      if (snap.status === 'loading' && previous && previous.value.status !== 'error') {
        // When the input resource enters loading state, we keep the value
        // from its previous state, if any.
        return {status: 'loading' as const, value: previous.value.value};
      }

// Otherwise we simply forward the state of the input resource.
      return snap;
    },
  });

return resourceFromSnapshots(derived);
}

@Component({/*... */})
export class AwesomeProfile {
  userId = input.required<number>();
  user = withPreviousValue(httpResource(() => `/user/${this.userId()}`));
  // When userId changes, user.value() keeps the old user data until the new one loads
}
```
TIP: Consultez les [Fondamentaux](essentials/dependency-injection) d'Angular avant de vous plonger dans ce guide approfondi.

À mesure qu'une application grandit, les développeurs ont souvent besoin de réutiliser et de partager des fonctionnalités entre différentes parties du code. L'[injection de dépendances (DI)](https://en.wikipedia.org/wiki/Dependency_injection) vous y aide en vous permettant de fournir des dépendances à une classe au lieu de les créer directement à l'intérieur de celle-ci. Les différentes parties de l'application deviennent ainsi plus réutilisables et plus faciles à gérer.

L'injection de dépendances est un pattern populaire, car elle permet aux développeurs de relever des défis courants, comme :

- **Une meilleure maintenabilité du code** : l'injection de dépendances favorise une séparation claire des responsabilités, ce qui facilite le refactoring du code et réduit la duplication.
- **La scalabilité** : vous pouvez réutiliser des fonctionnalités modulaires dans différentes parties d'une application, ce qui facilite sa montée en charge.
- **De meilleurs tests** : la DI permet aux tests unitaires d'utiliser des [doublures de test](https://en.wikipedia.org/wiki/Test_double) à la place des implémentations réelles si nécessaire.

## Comment fonctionne l'injection de dépendances dans Angular ? {#how-does-dependency-injection-work-in-angular}

Une dépendance est n'importe quel objet, valeur, fonction ou service dont une classe a besoin pour fonctionner, mais qu'elle ne crée pas elle-même. Vous la fournissez plutôt depuis l'extérieur, ce qui crée une relation claire entre les différentes parties de l'application.

Vous interagissez avec un système d'injection de dépendances de deux façons principales :

- Vous pouvez _fournir_, c'est-à-dire mettre à disposition, des valeurs.
- Vous pouvez _injecter_, c'est-à-dire demander, ces valeurs en tant que dépendances.

Dans ce contexte, les « valeurs » peuvent désigner n'importe quelle valeur JavaScript, y compris des objets, des fonctions ou des instances de classe. Les types de dépendances injectées les plus courants sont :

- **Les valeurs de configuration** : constantes propres à l'environnement, URL d'API, feature flags, etc.
- **Les fabriques** : fonctions qui créent des objets ou des valeurs selon des conditions d'exécution
- **Les services** : classes qui fournissent des fonctionnalités communes, de la logique métier ou de l'état

Les composants et les directives Angular participent automatiquement à la DI : vous pouvez donc y injecter des dépendances et les rendre disponibles pour l'injection.

## Que sont les services ? {#what-are-services}

Un _service_ Angular est une classe TypeScript décorée avec `@Service`, ce qui vous permet d'injecter une instance de la classe en tant que dépendance. Les services sont le moyen le plus courant de partager des données et des fonctionnalités dans une application.

Les types de services les plus courants sont :

- **Les clients de données :** ils masquent les détails des requêtes envoyées à un serveur pour récupérer et modifier des données
- **La gestion d'état :** ils définissent un état partagé entre plusieurs composants ou pages
- **L'authentification et l'autorisation :** ils gèrent l'authentification des utilisateurs, le stockage des jetons et le contrôle d'accès
- **La journalisation et la gestion des erreurs :** ils établissent une API commune pour journaliser ou communiquer les états d'erreur à l'utilisateur
- **La gestion et la diffusion d'événements :** ils gèrent les événements ou les notifications qui ne sont pas associés à un composant spécifique, ou diffusent des événements et des notifications aux composants, selon le [pattern observateur](https://en.wikipedia.org/wiki/Observer_pattern)
- **Les fonctions utilitaires :** ils proposent des fonctions utilitaires réutilisables, comme le formatage de données, la validation ou des calculs

L'exemple suivant déclare un service nommé `AnalyticsLogger` :

```ts
import {Service} from '@angular/core';

@Service()
export class AnalyticsLogger {
  trackEvent(category: string, value: string) {
    console.log('Analytics event logged:', {
      category,
      value,
      timestamp: new Date().toISOString(),
    });
  }
}
```

NOTE: Le décorateur `@Service` rend ce service disponible dans toute votre application en tant que singleton. C'est l'approche recommandée pour la plupart des services.

HELPFUL: Le décorateur [`@Service`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator) est un raccourci ergonomique pour `@Injectable({providedIn: 'root'})`.

## Injecter des dépendances avec `inject()` {#injecting-dependencies-with-inject}

Vous pouvez injecter des dépendances avec la fonction `inject()` d'Angular.

Voici l'exemple d'une barre de navigation qui injecte `AnalyticsLogger` et le service `Router` d'Angular pour permettre aux utilisateurs de naviguer vers une autre page tout en suivant l'événement.

```typescript
import {Component, inject} from '@angular/core';
import {Router} from '@angular/router';
import {AnalyticsLogger} from './analytics-logger';

@Component({
  selector: 'app-navbar',
  template: `<a href="#" (click)="navigateToDetail($event)">Detail Page</a>`,
})
export class Navbar {
  private router = inject(Router);
  private analytics = inject(AnalyticsLogger);

navigateToDetail(event: Event) {
    event.preventDefault();
    this.analytics.trackEvent('navigation', '/details');
    this.router.navigate(['/details']);
  }
}
```

### Où peut-on utiliser `inject()` ? {#where-can-inject-be-used}

Vous pouvez injecter des dépendances pendant la construction d'un composant, d'une directive ou d'un service. L'appel à [`inject`](/api/core/inject) peut se trouver soit dans le `constructor`, soit dans l'initialiseur d'un champ. Voici quelques exemples courants :

```ts
@Component(/* ... */)
export class MyComponent {
  // ✅ In class field initializer
  private service = inject(MyService);

// ✅ In constructor body
  private anotherService: MyService;

constructor() {
    this.anotherService = inject(MyService);
  }
}
```

```ts
@Directive({...})
export class MyDirective {
  // ✅ In class field initializer
  private element = inject(ElementRef);
}
```

```ts
import {Service, inject} from '@angular/core';
import {HttpClient} from '@angular/common/http';

@Service()
export class MyService {
  // ✅ In a service
  private http = inject(HttpClient);
}
```

```ts
export const authGuard = () => {
  // ✅ In a route guard
  const auth = inject(AuthService);
  return auth.isAuthenticated();
};
```

Angular utilise le terme « contexte d'injection » pour décrire tout endroit de votre code où vous pouvez appeler [`inject`](/api/core/inject). Si la construction des composants, directives et services est le cas le plus courant, consultez les [contextes d'injection](/guide/di/dependency-injection-context) pour plus de détails.

Pour plus d'informations, consultez la [documentation de l'API inject](api/core/inject#usage-notes).

## Prochaines étapes {#next-steps}

Maintenant que vous comprenez les bases de l'injection de dépendances dans Angular, vous êtes prêt à apprendre à créer vos propres services.

Le guide suivant, [Créer et utiliser des services](guide/di/creating-and-using-services), vous montrera :

- Comment créer un service avec l'Angular CLI ou manuellement
- Comment fonctionne le pattern `providedIn: 'root'`
- Comment injecter des services dans des composants et d'autres services

Cela couvre le cas d'usage le plus courant des services dans les applications Angular.
# Créer et utiliser des services

Les services sont des morceaux de code réutilisables que vous pouvez partager dans votre application Angular. Vous les utilisez généralement pour gérer la récupération de données, la logique métier ou d'autres fonctionnalités auxquelles plusieurs composants doivent accéder.

## Créer un service {#creating-a-service}

Vous pouvez créer un service avec l'[Angular CLI](tools/cli) à l'aide de la commande suivante :

```bash
ng generate service CUSTOM_NAME
```

Cette commande crée un fichier dédié `CUSTOM_NAME.ts` dans votre répertoire `src`.

Vous pouvez aussi créer un service manuellement en ajoutant le décorateur `@Service()` à une classe TypeScript. Cela indique à Angular que vous pouvez utiliser la classe comme une dépendance injectable.

L'exemple suivant définit un service qui permet aux utilisateurs d'ajouter et de récupérer des données :

```ts
{header: "src/app/basic-data-store.ts"}
import {Service} from '@angular/core';

@Service()
export class BasicDataStore {
  private data: string[] = [];

addData(item: string): void {
    this.data.push(item);
  }

getData(): string[] {
    return [...this.data];
  }
}
```

## Comment les services deviennent disponibles {#how-services-become-available}

Par défaut, les services sont fournis au niveau racine. Quand un service est fourni globalement, Angular garantit trois avantages principaux :

- **Instance singleton :** une seule instance partagée est créée pour toute l'application.
- **Disponibilité globale :** le service est automatiquement accessible partout, sans enregistrement manuel de provider.
- **Tree-shaking :** le service est exclu du bundle de production final si votre code ne l'utilise jamais explicitement.

### Utiliser le décorateur `@Service` ou `@Injectable` {#using-the-service-vs-injectable-decorator}

Le décorateur `@Service` est un raccourci moderne et ergonomique pour la syntaxe traditionnelle `@Injectable({ providedIn: 'root' })`.

Utilisez ce tableau récapitulatif pour choisir le décorateur adapté à votre situation :

| Fonctionnalité / besoin                       | `@Service` | `@Injectable`                           |
| --------------------------------------------- | ---------- | --------------------------------------- |
| **Prise en charge de la fonction `inject()`** | Oui        | Oui                                     |
| **DI par le constructeur**                    | ❌ Non     | Oui                                     |
| **Provider singleton racine implicite**       | Oui        | ❌ Non (nécessite `{providedIn: 'root'}`) |
| **Clés de provider avancées (`useClass`, etc.)** | ❌ Non  | Oui                                     |
| **Fabriques d'initialisation personnalisées** | Oui        | Oui                                     |
| **Portées autres que root (`platform`, etc.)** | ❌ Non    | Oui                                     |

### Remplacer l'implémentation par une fabrique {#replacing-the-implementation-with-a-factory}

Si vous devez contrôler la façon dont le singleton est créé, par exemple pour utiliser une autre implémentation selon l'environnement, passez une fonction `factory`.

La fabrique s'exécute dans un [contexte d'injection](guide/di/dependency-injection-context) : vous pouvez donc y utiliser [`inject()`](api/core/inject) pour lire d'autres dépendances.

Le service `Analytics` suivant ne fait rien en local, pour que les événements ne polluent pas la console pendant le développement. En production, la fabrique lit un jeton `ANALYTICS_ENABLED` et renvoie une sous-classe `GoogleAnalytics` qui transmet les événements au véritable outil de suivi :

```ts
{header: "src/app/analytics.ts"}
import {inject, InjectionToken, Service} from '@angular/core';
import {ANALYTICS_ENABLED} from './token';

@Service({
  factory: () => (inject(ANALYTICS_ENABLED) ? new GoogleAnalytics() : new Analytics()),
})
export class Analytics {
  track(event: string, payload?: Record<string, unknown>) {
    // No-op by default.
  }
}

class GoogleAnalytics extends Analytics {
  override track(event: string, payload?: Record<string, unknown>) {
    // Dispatches an analytics event to Google Analytics
  }
}
```

NOTE: L'option `factory` remplace les options `useClass`, `useValue`, `useExisting` et `useFactory` de `@Injectable`. Si vous avez besoin de l'une d'elles, continuez à utiliser `@Injectable`.

### Désactiver la fourniture automatique {#opting-out-of-automatic-provisioning}

Par défaut, `@Service` fournit la classe dans l'injector racine. Si vous voulez la fournir manuellement, par exemple pour limiter sa portée à une route ou à un composant précis, définissez `autoProvided: false` :

```ts
{header: "src/app/analytics-logger.ts"}
import {Service} from '@angular/core';

@Service({autoProvided: false})
export class AnalyticsLogger {
  trackEvent(name: string) {
    console.log('event:', name);
  }
}
```

Il vous appartient alors d'ajouter le service à un tableau `providers`, comme avec un simple `@Injectable()` :

### Quand utiliser `@Service` ou `@Injectable` {#when-to-use-service-vs-injectable}

Optez pour `@Service` quand vous créez une nouvelle classe singleton qui utilise `inject()` pour ses dépendances. Continuez à utiliser `@Injectable` quand vous avez besoin de l'un des éléments suivants :

- **L'injection de dépendances par le constructeur.** `@Service` ne prend en charge que la fonction [`inject()`](api/core/inject).
- **Une configuration avancée du provider**, comme `useClass`, `useValue`, `useExisting` ou `useFactory`. `@Service` expose à la place une seule option `factory`.
- **Des portées autres que root**, comme `providedIn: 'platform'`.

## Injecter un service {#injecting-a-service}

Une fois que vous avez créé un service avec `providedIn: 'root'`, vous pouvez l'injecter n'importe où dans votre application avec la fonction `inject()` de `@angular/core`.

### Injecter dans un composant {#injecting-into-a-component}

```typescript
import {Component, inject} from '@angular/core';
import {BasicDataStore} from './basic-data-store';

@Component({
  selector: 'app-example',
  template: `
    <div>
      <p>{{ dataStore.getData() }}</p>
      <button (click)="dataStore.addData('More data')">Add more data</button>
    </div>
  `,
})
export class Example {
  dataStore = inject(BasicDataStore);
}
```

### Injecter dans un autre service {#injecting-into-another-service}

```ts
import {inject, Service} from '@angular/core';
import {AdvancedDataStore} from './advanced-data-store';

@Service()
export class BasicDataStore {
  private advancedDataStore = inject(AdvancedDataStore);
  private data: string[] = [];

addData(item: string): void {
    this.data.push(item);
  }

getData(): string[] {
    return [...this.data, ...this.advancedDataStore.getData()];
  }
}
```

## Prochaines étapes {#next-steps}

Si `providedIn: 'root'` couvre la plupart des cas d'usage, Angular propose aussi d'autres façons de configurer les services pour des scénarios plus spécialisés :

- **Instances propres à un composant** - quand des composants ont besoin de leurs propres instances isolées d'un service
- **Configuration manuelle** - pour les services qui nécessitent une configuration à l'exécution
- **Providers de fabrique** - pour créer dynamiquement des services selon des conditions d'exécution
- **Providers de valeur** - pour fournir des objets de configuration ou des constantes

Vous pouvez en apprendre davantage sur ces patterns avancés dans le guide suivant : [définir des providers de dépendances](/guide/di/defining-dependency-providers).
# Définir des providers de dépendances

Angular propose deux façons de rendre des services disponibles pour l'injection :

1. **Fourniture automatique** - En utilisant `providedIn` dans le décorateur `@Injectable`, le décorateur [`@Service`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator), ou en fournissant une fabrique dans la configuration de l'`InjectionToken`
2. **Fourniture manuelle** - En utilisant le tableau `providers` dans les composants, les directives, les routes ou la configuration de l'application

Dans le [guide précédent](/guide/di/creating-and-using-services), vous avez appris à créer des services avec `providedIn: 'root'`, qui couvre la plupart des cas d'usage courants. Ce guide explore d'autres patterns de configuration des providers, automatique comme manuelle.

## Fourniture automatique pour les dépendances qui ne sont pas des classes {#automatic-provision-for-non-class-dependencies}

Si le décorateur `@Injectable` avec `providedIn: 'root'` fonctionne très bien pour les services (des classes), vous pourriez avoir besoin de fournir globalement d'autres types de valeurs, comme des objets de configuration, des fonctions ou des valeurs primitives. Angular propose `InjectionToken` à cet effet.

### Qu'est-ce qu'un InjectionToken ? {#what-is-an-injectiontoken}

Un `InjectionToken` est un objet que le système d'injection de dépendances d'Angular utilise pour identifier de manière unique les valeurs à injecter. Voyez-le comme une clé spéciale qui vous permet de stocker et de récupérer n'importe quel type de valeur dans le système de DI d'Angular :

```ts
import {InjectionToken} from '@angular/core';

// Create a token for a string value
export const API_URL = new InjectionToken<string>('api.url');

// Create a token for a function
export const LOGGER = new InjectionToken<(msg: string) => void>('logger.function');

// Create a token for a complex type
export interface Config {
  apiUrl: string;
  timeout: number;
}
export const CONFIG_TOKEN = new InjectionToken<Config>('app.config');
```

NOTE: Le paramètre de type chaîne (par exemple `'api.url'`) est une description destinée uniquement au débogage : Angular identifie les jetons par leur référence d'objet, et non par cette chaîne.

### InjectionToken avec `providedIn: 'root'` {#injectiontoken-with-providedin-root}

Un `InjectionToken` qui possède une `factory` est par défaut en `providedIn: 'root'` (mais cela peut être remplacé via la propriété `providedIn`).

```ts
{header: "/app/config.token.ts"}
import {InjectionToken, Component, inject} from '@angular/core';

export interface AppConfig {
  apiUrl: string;
  version: string;
  features: Record<string, boolean>;
}

// Globally available configuration using providedIn
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config', {
  providedIn: 'root',
  factory: () => ({
    apiUrl: 'https://api.example.com',
    version: '1.0.0',
    features: {
      darkMode: true,
      analytics: false,
    },
  }),
});

// No need to add to providers array - available everywhere!
@Component({
  selector: 'app-header',
  template: `<h1>Version: {{ config.version }}</h1>`,
})
export class Header {
  config = inject(APP_CONFIG); // Automatically available
}
```

### Quand utiliser un InjectionToken avec des fonctions de fabrique {#when-to-use-injectiontoken-with-factory-functions}

Un InjectionToken avec une fonction de fabrique est idéal quand vous ne pouvez pas utiliser de classe mais devez fournir des dépendances globalement :

```ts
{header: "/app/logger.token.ts"}
import {InjectionToken, inject} from '@angular/core';
import {APP_CONFIG} from './config.token';

// Logger function type
export type LoggerFn = (level: string, message: string) => void;

// Global logger function with dependencies
export const LOGGER_FN = new InjectionToken<LoggerFn>('logger.function', {
  providedIn: 'root',
  factory: () => {
    const config = inject(APP_CONFIG);

return (level: string, message: string) => {
      if (config.features.logging !== false) {
        console[level](`[${new Date().toISOString()}] ${message}`);
      }
    };
  },
});
```

```ts
{header: "/app/storage.token.ts"}
// Providing browser APIs as tokens
export const LOCAL_STORAGE = new InjectionToken<Storage>('localStorage', {
  // providedIn: 'root' is configured as the default
  factory: () => window.localStorage,
});

export const SESSION_STORAGE = new InjectionToken<Storage>('sessionStorage', {
  providedIn: 'root',
  factory: () => window.sessionStorage,
});
```

```ts
{header: "/app/feature-flags.token.ts"}
// Complex configuration with runtime logic
export const FEATURE_FLAGS = new InjectionToken<Map<string, boolean>>('feature.flags', {
  providedIn: 'root',
  factory: () => {
    const flags = new Map<string, boolean>();

// Parse from environment or URL params
    const urlParams = new URLSearchParams(window.location.search);
    const enableBeta = urlParams.get('beta') === 'true';

flags.set('betaFeatures', enableBeta);
    flags.set('darkMode', true);
    flags.set('newDashboard', false);

return flags;
  },
});
```

Cette approche offre plusieurs avantages :

- **Aucune configuration manuelle de provider nécessaire** - Fonctionne exactement comme `providedIn: 'root'` pour les services
- **Compatible avec le tree-shaking** - Inclus uniquement s'il est réellement utilisé
- **Typage sûr** - Prise en charge complète de TypeScript pour les valeurs qui ne sont pas des classes
- **Peut injecter d'autres dépendances** - Les fonctions de fabrique peuvent utiliser `inject()` pour accéder à d'autres services

## Comprendre la configuration manuelle des providers {#understanding-manual-provider-configuration}

Quand vous avez besoin de plus de contrôle que ce qu'offre `providedIn: 'root'`, vous pouvez configurer manuellement les providers. La configuration manuelle via le tableau `providers` est utile quand :

1. **Le service n'a pas de `providedIn`** - Les services sans fourniture automatique doivent être fournis manuellement
2. **Vous voulez une nouvelle instance** - Pour créer une instance distincte au niveau du composant ou de la directive au lieu d'utiliser l'instance partagée
3. **Vous avez besoin d'une configuration à l'exécution** - Quand le comportement du service dépend de valeurs connues à l'exécution
4. **Vous fournissez des valeurs qui ne sont pas des classes** - Objets de configuration, fonctions ou valeurs primitives

### Exemple : service sans `providedIn` {#example-service-without-providedin}

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

// Service without providedIn
@Injectable()
export class LocalDataStore {
  private data: string[] = [];

addData(item: string) {
    this.data.push(item);
  }
}

// Component must provide it
@Component({
  selector: 'app-example',
  // A provider is required here because the `LocalDataStore` service has no providedIn.
  providers: [LocalDataStore],
  template: `...`,
})
export class Example {
  dataStore = inject(LocalDataStore);
}
```

### Exemple : créer des instances propres à un composant {#example-creating-component-specific-instances}

Les services avec `providedIn: 'root'` peuvent être remplacés au niveau du composant. Cela lie l'instance du service à la durée de vie d'un composant. Par conséquent, quand le composant est détruit, le service fourni est lui aussi détruit.

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

@Injectable({providedIn: 'root'})
export class DataStore {
  private data: ListItem[] = [];
}

// This component gets its own instance
@Component({
  selector: 'app-isolated',
  // Creates new instance of `DataStore` rather than using the root-provided instance.
  providers: [DataStore],
  template: `...`,
})
export class Isolated {
  dataStore = inject(DataStore); // Component-specific instance
}
```

## Hiérarchie des injectors dans Angular {#injector-hierarchy-in-angular}

Le système d'injection de dépendances d'Angular est hiérarchique. Quand un composant demande une dépendance, Angular commence par l'injector de ce composant et remonte l'arbre jusqu'à trouver un provider pour cette dépendance. Chaque composant de l'arbre de votre application peut avoir son propre injector, et ces injectors forment une hiérarchie qui reflète votre arbre de composants.

Cette hiérarchie permet :

- **Des instances avec portée** : différentes parties de votre application peuvent avoir différentes instances du même service
- **Le remplacement de comportement** : les composants enfants peuvent remplacer les providers des composants parents
- **L'efficacité mémoire** : les services ne sont instanciés que là où c'est nécessaire

Dans Angular, tout élément portant un composant ou une directive peut fournir des valeurs à tous ses descendants.

```mermaid
graph TD
    subgraph platform
        subgraph root
            direction TB
            A[SocialApp] --> B[UserProfile]
            A --> C[FriendList]
            C --> D[FriendEntry]
        end
    end
```

Dans l'exemple ci-dessus :

1. `SocialApp` peut fournir des valeurs pour `UserProfile` et `FriendList`
2. `FriendList` peut fournir des valeurs à injecter dans `FriendEntry`, mais ne peut pas fournir de valeurs à injecter dans `UserProfile` car celui-ci ne fait pas partie de son arbre

## Déclarer un provider {#declaring-a-provider}

Voyez le système d'injection de dépendances d'Angular comme une table de hachage ou un dictionnaire. Chaque objet de configuration de provider définit une paire clé-valeur :

- **Clé (identifiant du provider)** : l'identifiant unique que vous utilisez pour demander une dépendance
- **Valeur** : ce qu'Angular doit renvoyer quand ce jeton est demandé

Quand vous fournissez manuellement des dépendances, vous voyez généralement cette syntaxe abrégée :

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [LocalService], // Service without providedIn
})
export class Example {}
```

Il s'agit en réalité d'un raccourci pour une configuration de provider plus détaillée :

```ts
{
  // This is the shorthand version
  providers: [LocalService],

// This is the full version
  providers: [
    { provide: LocalService, useClass: LocalService }
  ]
}
```

### Objet de configuration de provider {#provider-configuration-object}

Chaque objet de configuration de provider comporte deux parties principales :

1. **Identifiant du provider** : la clé unique qu'Angular utilise pour obtenir la dépendance (définie via la propriété `provide`)
2. **Valeur** : la dépendance réelle qu'Angular doit récupérer, configurée avec différentes clés selon le type souhaité :
   - `useClass` - Fournit une classe JavaScript
   - `useValue` - Fournit une valeur statique
   - `useFactory` - Fournit une fonction de fabrique qui renvoie la valeur
   - `useExisting` - Fournit un alias vers un provider existant

### Identifiants de provider {#provider-identifiers}

Les identifiants de provider permettent au système d'injection de dépendances (DI) d'Angular de récupérer une dépendance grâce à un ID unique. Vous pouvez générer des identifiants de provider de deux façons :

1. [Noms de classe](#class-names)
2. [Jetons d'injection](#injection-tokens)

#### Noms de classe {#class-names}

Les noms de classe utilisent directement la classe importée comme identifiant :

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [{provide: LocalService, useClass: LocalService}],
})
export class Example {
  /* ... */
}
```

La classe sert à la fois d'identifiant et d'implémentation, c'est pourquoi Angular propose le raccourci `providers: [LocalService]`.

#### Jetons d'injection {#injection-tokens}

Angular fournit une classe [`InjectionToken`](api/core/InjectionToken) intégrée qui crée une référence d'objet unique pour des valeurs injectables, ou quand vous voulez fournir plusieurs implémentations de la même interface.

```ts
{header: "/app/tokens.ts"}
import {InjectionToken} from '@angular/core';
import {DataService} from './data-service.interface';

export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');
```

NOTE: La chaîne `'DataService'` est une description utilisée uniquement à des fins de débogage. Angular identifie le jeton par sa référence d'objet, et non par cette chaîne.

Utilisez le jeton dans la configuration de votre provider :

```typescript
import {Component, inject} from '@angular/core';
import {LocalDataService} from './local-data-service';
import {DATA_SERVICE_TOKEN} from './tokens';

@Component({
  selector: 'app-example',
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN);
}
```

#### Les interfaces TypeScript peuvent-elles servir d'identifiants pour l'injection ? {#can-typescript-interfaces-be-identifiers-for-injection}

Les interfaces TypeScript ne peuvent pas être utilisées pour l'injection, car elles n'existent pas à l'exécution :

```ts
// ❌ This won't work!
interface DataService {
  getData(): string[];
}

// Interfaces disappear after TypeScript compilation
@Component({
  providers: [
    {provide: DataService, useClass: LocalDataService}, // Error!
  ],
})
export class Example {
  private dataService = inject(DataService); // Error!
}

// ✅ Use InjectionToken instead
export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');

@Component({
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN); // Works!
}
```

L'InjectionToken fournit une valeur à l'exécution que le système de DI d'Angular peut utiliser, tout en conservant la sûreté du typage grâce au paramètre de type générique de TypeScript.

### Types de valeurs de provider {#provider-value-types}

#### useClass

`useClass` fournit une classe JavaScript comme dépendance. C'est le comportement par défaut avec la syntaxe abrégée :

```ts
// Shorthand
providers: [DataService];

// Full syntax
providers: [{provide: DataService, useClass: DataService}];

// Different implementation
providers: [{provide: DataService, useClass: MockDataService}];

// Conditional implementation
providers: [
  {
    provide: StorageService,
    useClass: environment.production ? CloudStorageService : LocalStorageService,
  },
];
```

#### Exemple pratique : substitution du logger {#practical-example-logger-substitution}

Vous pouvez substituer des implémentations pour étendre des fonctionnalités :

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

// Base logger
@Injectable()
export class Logger {
  log(message: string) {
    console.log(message);
  }
}

// Enhanced logger with timestamp
@Injectable()
export class BetterLogger extends Logger {
  override log(message: string) {
    super.log(`[${new Date().toISOString()}] ${message}`);
  }
}

// Logger that includes user context
@Injectable()
export class EvenBetterLogger extends Logger {
  private userService = inject(UserService);

override log(message: string) {
    const name = this.userService.user.name;
    super.log(`Message to ${name}: ${message}`);
  }
}

// In your component
@Component({
  selector: 'app-example',
  providers: [
    UserService, // EvenBetterLogger needs this
    {provide: Logger, useClass: EvenBetterLogger},
  ],
})
export class Example {
  private logger = inject(Logger); // Gets EvenBetterLogger instance
}
```

#### useValue

`useValue` fournit n'importe quel type de données JavaScript comme valeur statique :

```ts
providers: [
  {provide: API_URL_TOKEN, useValue: 'https://api.example.com'},
  {provide: MAX_RETRIES_TOKEN, useValue: 3},
  {provide: FEATURE_FLAGS_TOKEN, useValue: {darkMode: true, beta: false}},
];
```

IMPORTANT: Les types et interfaces TypeScript ne peuvent pas servir de valeurs de dépendance. Ils n'existent qu'à la compilation.

#### Exemple pratique : configuration de l'application {#practical-example-application-configuration}

Un cas d'usage courant de `useValue` est de fournir la configuration de l'application :

```ts
// Define configuration interface
export interface AppConfig {
  apiUrl: string;
  appTitle: string;
  features: {
    darkMode: boolean;
    analytics: boolean;
  };
}

// Create injection token
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config');

// Define configuration
const appConfig: AppConfig = {
  apiUrl: 'https://api.example.com',
  appTitle: 'My Application',
  features: {
    darkMode: true,
    analytics: false,
  },
};

// Provide in bootstrap
bootstrapApplication(AppComponent, {
  providers: [{provide: APP_CONFIG, useValue: appConfig}],
});

// Use in component
@Component({
  selector: 'app-header',
  template: `<h1>{{ title }}</h1>`,
})
export class Header {
  private config = inject(APP_CONFIG);
  title = this.config.appTitle;
}
```

#### useFactory

`useFactory` fournit une fonction qui génère une nouvelle valeur à injecter :

```ts
export const loggerFactory = (config: AppConfig) => {
  return new LoggerService(config.logLevel, config.endpoint);
};

providers: [
  {
    provide: LoggerService,
    useFactory: loggerFactory,
    deps: [APP_CONFIG], // Dependencies for the factory function
  },
];
```

Vous pouvez marquer des dépendances de la fabrique comme optionnelles :

```ts
import {Optional} from '@angular/core';

providers: [
  {
    provide: MyService,
    useFactory: (required: RequiredService, optional?: OptionalService) => {
      return new MyService(required, optional || new DefaultService());
    },
    deps: [RequiredService, [new Optional(), OptionalService]],
  },
];
```

#### Exemple pratique : client d'API basé sur la configuration {#practical-example-configuration-based-api-client}

Voici un exemple complet qui montre comment utiliser une fabrique pour créer un service avec une configuration connue à l'exécution :

```ts
// Service that needs runtime configuration
class ApiClient {
  constructor(
    private http: HttpClient,
    private baseUrl: string,
    private rateLimitMs: number,
  ) {}

async fetchData(endpoint: string) {
    // Apply rate limiting based on user tier
    await this.applyRateLimit();
    return this.http.get(`${this.baseUrl}/${endpoint}`);
  }

private async applyRateLimit() {
    // Simplified example - real implementation would track request timing
    return new Promise((resolve) => setTimeout(resolve, this.rateLimitMs));
  }
}

// Factory function that configures based on user tier
import {inject, Component} from '@angular/core';
import {HttpClient} from '@angular/common/http';
const apiClientFactory = () => {
  const http = inject(HttpClient);
  const userService = inject(UserService);

// Assuming userService provides these values
  const baseUrl = userService.getApiBaseUrl();
  const rateLimitMs = userService.getRateLimit();

return new ApiClient(http, baseUrl, rateLimitMs);
};

// Provider configuration
export const apiClientProvider = {
  provide: ApiClient,
  useFactory: apiClientFactory,
};

// Usage in component
@Component({
  selector: 'app-dashboard',
  providers: [apiClientProvider],
})
export class Dashboard {
  private apiClient = inject(ApiClient);
}
```

#### useExisting

`useExisting` crée un alias vers un provider déjà défini. Les deux jetons renvoient la même instance :

```ts
providers: [
  NewLogger, // The actual service
  {provide: OldLogger, useExisting: NewLogger}, // The alias
];
```

IMPORTANT: Ne confondez pas `useExisting` avec `useClass`. `useClass` crée des instances distinctes, tandis que `useExisting` garantit que vous obtenez la même instance singleton.

### Providers multiples {#multiple-providers}

Utilisez l'option `multi: true` quand plusieurs providers contribuent des valeurs au même jeton :

```ts
export const INTERCEPTOR_TOKEN = new InjectionToken<Interceptor[]>('interceptors');

providers: [
  {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
  {provide: INTERCEPTOR_TOKEN, useClass: LoggingInterceptor, multi: true},
  {provide: INTERCEPTOR_TOKEN, useClass: RetryInterceptor, multi: true},
];
```

Quand vous injectez `INTERCEPTOR_TOKEN`, vous recevez un tableau contenant les instances des trois intercepteurs.

## Où pouvez-vous déclarer des providers ? {#where-can-you-specify-providers}

Angular propose plusieurs niveaux où enregistrer des providers, chacun ayant des implications différentes sur la portée, le cycle de vie et les performances :

- [**Bootstrap de l'application**](#application-bootstrap) - Des singletons globaux disponibles partout
- [**Sur un élément (composant ou directive)**](#component-or-directive-providers) - Des instances isolées pour des arbres de composants spécifiques
- [**Route**](#route-providers) - Des services propres à une fonctionnalité pour les modules chargés en lazy loading

### Bootstrap de l'application {#application-bootstrap}

Utilisez des providers au niveau de l'application dans `bootstrapApplication` quand :

- **Le service est utilisé dans plusieurs domaines fonctionnels** - Des services comme les clients HTTP, la journalisation ou l'authentification, dont de nombreuses parties de votre application ont besoin
- **Vous voulez un vrai singleton** - Une seule instance partagée par toute l'application
- **Le service n'a pas de configuration propre à un composant** - Des utilitaires génériques qui fonctionnent de la même façon partout
- **Vous fournissez une configuration globale** - Points de terminaison d'API, feature flags ou paramètres d'environnement

```ts
{header: "main.ts"}
bootstrapApplication(App, {
  providers: [
    {provide: API_BASE_URL, useValue: 'https://api.example.com'},
    {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
    LoggingService, // Used throughout the app
    {provide: ErrorHandler, useClass: GlobalErrorHandler},
  ],
});
```

**Avantages :**

- Une instance unique réduit la consommation de mémoire
- Disponible partout sans configuration supplémentaire
- Plus simple pour gérer l'état global

**Inconvénients :**

- Toujours inclus dans votre bundle JavaScript, même si la valeur n'est jamais injectée
- Difficile à personnaliser par fonctionnalité
- Plus difficile de tester des composants individuels de manière isolée

#### Pourquoi fournir au bootstrap plutôt qu'utiliser `providedIn: 'root'` ? {#why-provide-during-bootstrap-instead-of-using-providedin-root}

Vous pourriez vouloir un provider au bootstrap quand :

- Le provider a des effets de bord (par exemple, l'installation du router côté client)
- Le provider nécessite une configuration (par exemple, des routes)
- Vous utilisez le pattern `provideSomething` d'Angular (par exemple, `provideRouter`, `provideHttpClient`)

### Providers de composant ou de directive {#component-or-directive-providers}

Utilisez des providers de composant ou de directive quand :

- **Le service a un état propre au composant** - Validateurs de formulaire, caches propres à un composant ou gestionnaires d'état d'interface
- **Vous avez besoin d'instances isolées** - Chaque composant a besoin de sa propre copie du service
- **Le service n'est utilisé que par un seul arbre de composants** - Des services spécialisés qui n'ont pas besoin d'un accès global
- **Vous créez des composants réutilisables** - Des composants qui doivent fonctionner de manière indépendante avec leurs propres services

```typescript
// Specialized form component with its own validation service
@Component({
  selector: 'app-advanced-form',
  providers: [
    FormValidationService, // Each form gets its own validator
    {provide: FORM_CONFIG, useValue: {strictMode: true}},
  ],
})
export class AdvancedForm {}

// Modal component with isolated state management
@Component({
  selector: 'app-modal',
  providers: [
    ModalStateService, // Each modal manages its own state
  ],
})
export class Modal {}
```

**Avantages :**

- Meilleure encapsulation et meilleure isolation
- Plus simple de tester les composants individuellement
- Plusieurs instances peuvent coexister avec des configurations différentes

**Inconvénients :**

- Une nouvelle instance est créée pour chaque composant (consommation de mémoire plus élevée)
- Aucun état partagé entre les composants
- Doit être fourni partout où c'est nécessaire
- Toujours inclus dans le même bundle JavaScript que le composant ou la directive, même si la valeur n'est jamais injectée

NOTE: Si plusieurs directives sur le même élément fournissent le même jeton, l'une d'elles l'emporte, mais laquelle n'est pas définie.

### Providers de route {#route-providers}

Utilisez des providers au niveau de la route pour :

- **Les services propres à une fonctionnalité** - Des services nécessaires uniquement pour certaines routes ou certains modules de fonctionnalité
- **Les dépendances des modules chargés en lazy loading** - Des services qui ne doivent être chargés qu'avec certaines fonctionnalités
- **La configuration propre à une route** - Des paramètres qui varient selon la zone de l'application

```ts
{header: "routes.ts"}
export const routes: Routes = [
  {
    path: 'admin',
    providers: [
      AdminService, // Only loaded with admin routes
      {provide: FEATURE_FLAGS, useValue: {adminMode: true}},
    ],
    loadChildren: () => import('./admin/admin.routes'),
  },
  {
    path: 'shop',
    providers: [
      ShoppingCartService, // Isolated shopping state
      PaymentService,
    ],
    loadChildren: () => import('./shop/shop.routes'),
  },
];
```

Les services fournis au niveau de la route sont disponibles pour tous les composants et toutes les directives de cette route, ainsi que pour ses guards et ses resolvers.

Comme ces services sont instanciés indépendamment des composants de la route, ils n'ont pas directement accès aux informations propres à la route.

## Patterns pour les auteurs de libraries {#library-author-patterns}

Quand vous créez une library Angular, vous devez souvent proposer des options de configuration flexibles à ses utilisateurs tout en conservant des API propres. Les libraries d'Angular elles-mêmes illustrent des patterns puissants pour y parvenir.

### Le pattern `provide` {#the-provide-pattern}

Au lieu d'obliger les utilisateurs à configurer manuellement des providers complexes, les auteurs de libraries peuvent exporter des fonctions qui renvoient des configurations de providers :

```ts
{header: "/libs/analytics/src/providers.ts"}
import {InjectionToken, Provider, inject} from '@angular/core';

// Configuration interface
export interface AnalyticsConfig {
  trackingId: string;
  enableDebugMode?: boolean;
  anonymizeIp?: boolean;
}

// Internal token for configuration
const ANALYTICS_CONFIG = new InjectionToken<AnalyticsConfig>('analytics.config');

// Main service that uses the configuration
export class AnalyticsService {
  private config = inject(ANALYTICS_CONFIG);

track(event: string, properties?: any) {
    // Implementation using config
  }
}

// Provider function for consumers
export function provideAnalytics(config: AnalyticsConfig): Provider[] {
  return [{provide: ANALYTICS_CONFIG, useValue: config}, AnalyticsService];
}
```

```ts
{header: "main.ts"}
// Usage in consumer app
bootstrapApplication(App, {
  providers: [
    provideAnalytics({
      trackingId: 'GA-12345',
      enableDebugMode: !environment.production,
    }),
  ],
});
```

### Patterns de providers avancés avec options {#advanced-provider-patterns-with-options}

Pour des scénarios plus complexes, vous pouvez combiner plusieurs approches de configuration :

```ts
{header: "/libs/http-client/src/provider.ts"}
import {Provider, InjectionToken, inject} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';

// Feature flags for optional functionality
export enum HttpFeatures {
  Interceptors = 'interceptors',
  Caching = 'caching',
  Retry = 'retry',
}

// Configuration interfaces
export interface HttpConfig {
  baseUrl?: string;
  timeout?: number;
  headers?: Record<string, string>;
}

export interface RetryConfig {
  maxAttempts: number;
  delayMs: number;
}

// Internal tokens
const HTTP_CONFIG = new InjectionToken<HttpConfig>('http.config');
const RETRY_CONFIG = new InjectionToken<RetryConfig>('retry.config');
const HTTP_FEATURES = new InjectionToken<Set<HttpFeatures>>('http.features');

// Core service
class HttpClientService {
  private config = inject(HTTP_CONFIG, {optional: true});
  private features = inject(HTTP_FEATURES);

get(url: string) {
    // Use config and check features
  }
}

// Feature services
class RetryInterceptor {
  private config = inject(RETRY_CONFIG);
  // Retry logic
}

class CacheInterceptor {
  // Caching logic
}

// Main provider function
export function provideHttpClient(config?: HttpConfig, ...features: HttpFeature[]): Provider[] {
  const providers: Provider[] = [
    {provide: HTTP_CONFIG, useValue: config || {}},
    {provide: HTTP_FEATURES, useValue: new Set(features.map((f) => f.kind))},
    HttpClientService,
  ];

// Add feature-specific providers
  features.forEach((feature) => {
    providers.push(...feature.providers);
  });

return providers;
}

// Feature configuration functions
export interface HttpFeature {
  kind: HttpFeatures;
  providers: Provider[];
}

export function withInterceptors(...interceptors: any[]): HttpFeature {
  return {
    kind: HttpFeatures.Interceptors,
    providers: interceptors.map((interceptor) => ({
      provide: INTERCEPTOR_TOKEN,
      useClass: interceptor,
      multi: true,
    })),
  };
}

export function withCaching(): HttpFeature {
  return {
    kind: HttpFeatures.Caching,
    providers: [CacheInterceptor],
  };
}

export function withRetry(config: RetryConfig): HttpFeature {
  return {
    kind: HttpFeatures.Retry,
    providers: [{provide: RETRY_CONFIG, useValue: config}, RetryInterceptor],
  };
}

// Consumer usage with multiple features
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      {baseUrl: 'https://api.example.com'},
      withInterceptors(AuthInterceptor, LoggingInterceptor),
      withCaching(),
      withRetry({maxAttempts: 3, delayMs: 1000}),
    ),
  ],
});
```

### Pourquoi utiliser des fonctions de provider plutôt qu'une configuration directe ? {#why-use-provider-functions-instead-of-direct-configuration}

Les fonctions de provider offrent plusieurs avantages aux auteurs de libraries :

1. **Encapsulation** - Les jetons internes et les détails d'implémentation restent privés
2. **Typage sûr** - TypeScript garantit une configuration correcte à la compilation
3. **Flexibilité** - Composez facilement des fonctionnalités avec le pattern `with*`
4. **Pérennité** - L'implémentation interne peut évoluer sans casser le code des utilisateurs
5. **Cohérence** - S'aligne sur les propres patterns d'Angular (`provideRouter`, `provideHttpClient`, etc.)

Ce pattern est largement utilisé dans les libraries d'Angular elles-mêmes et est considéré comme une bonne pratique pour les auteurs de libraries qui doivent fournir des services configurables.
# Lazy loading des services

IMPORTANT: Pour que le lazy loading fonctionne, le service que vous chargez doit être fourni automatiquement. Décorez-le avec `@Injectable({providedIn: 'root'})` ou avec [`@Service()`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator). Sans fourniture automatique, Angular n'a aucun moyen de construire le service après son chargement.

La fonction `injectAsync` d'Angular vous permet de charger un service à la demande, uniquement quand il est réellement nécessaire. C'est utile quand un service dépend d'une library volumineuse ou d'une fonctionnalité rarement utilisée, et que vous ne voulez pas en payer le coût lors du chargement initial de la page.

Quand vous utilisez `injectAsync`, votre bundler place le code du service dans un chunk JavaScript séparé, téléchargé la première fois que vous demandez l'instance. Une fois chargé, Angular résout le service via le système de DI habituel : il peut donc toujours dépendre d'autres injectables et se comporte comme n'importe quel autre singleton.

## Injecter un service en lazy loading {#lazily-injecting-a-service}

Imaginez un `ReportExporter` qui dépend d'une library de tableur volumineuse. La plupart des utilisateurs ouvrent le rapport ; seuls quelques-uns cliquent sur **Export**. Chargez l'exportateur à la demande :

```typescript
import {Component, injectAsync} from '@angular/core';

@Component({
  selector: 'app-report',
  template: `<button (click)="export()">Export</button>`,
})
export class Report {
  private exporter = injectAsync(() => import('./report-exporter').then((m) => m.ReportExporter));

async export() {
    const exporter = await this.exporter();
    exporter.export();
  }
}
```

Le premier appel à `this.exporter()` déclenche l'import dynamique et résout le service depuis la DI. Les appels suivants réutilisent la même promise : le chunk n'est donc récupéré qu'une seule fois.

Si le service chargé en lazy loading est l'[export par défaut](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export), passez directement l'import dynamique : Angular extrait le `default` pour vous :

```ts
{header: "report-exporter.ts"}
@Service()
export default class ReportExporter {
  /* … */
}
```

```ts
{header: "report.ts"}
private exporter = injectAsync(() => import('./report-exporter'));
```

## Précharger la dépendance {#prefetching-the-dependency}

Par défaut, le chunk chargé en lazy loading n'est récupéré que lorsque vous appelez la fonction renvoyée. Vous pouvez lancer le téléchargement plus tôt en passant un déclencheur `prefetch` dans les options. Un déclencheur est n'importe quelle fonction qui renvoie une `Promise` ; quand elle est résolue, Angular lance le loader.

Angular fournit `onIdle`, un déclencheur intégré qui attend que le navigateur soit inactif :

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

@Component({/* … */})
export class Report {
  private exporter = injectAsync(() => import('./report-exporter').then((m) => m.ReportExporter), {
    prefetch: onIdle,
  });
}
```

Vous pouvez aussi configurer `onIdle` avec un temps d'attente maximal, pour que le préchargement ait toujours lieu dans un délai connu, même sur des pages chargées :

```ts
injectAsync(loader, {prefetch: () => onIdle({timeout: 1_000})});
```

NOTE: Le préchargement est opportuniste. Si l'utilisateur appelle la fonctionnalité avant que le préchargement ne se déclenche, Angular charge tout de même la dépendance immédiatement et résout votre `await` dès qu'elle est prête.

## Fournir un déclencheur de préchargement personnalisé {#provide-a-custom-prefetch-trigger}

Un `PrefetchTrigger` est simplement une fonction qui renvoie une promise ; le loader s'exécute dès que la promise est résolue. Utilisez-le pour aligner le préchargement sur vos propres événements, comme un survol ou un tick d'un scheduler :

```ts
import {PrefetchTrigger} from '@angular/core';

export function onHover(target: HTMLElement): PrefetchTrigger {
  return () =>
    new Promise<void>((resolve) => {
      target.addEventListener('pointerenter', () => resolve(), {once: true});
    });
}
```
# Contexte d'injection

Le système d'injection de dépendances (DI) repose sur un contexte d'exécution dans lequel l'injector courant est disponible.

Les injectors ne fonctionnent donc que lorsque vous exécutez du code dans ce contexte.

Vous disposez d'un contexte d'injection dans les situations suivantes :

- Pendant la construction (via le `constructor`) d'une classe instanciée par le système de DI, comme un `@Injectable` ou un `@Component`.
- Dans les initialiseurs de champs de ces classes.
- Dans la fonction de fabrique spécifiée pour `useFactory` d'un `Provider` ou d'un `@Injectable`.
- Dans la fonction `factory` spécifiée pour un `InjectionToken`.
- Dans une stack frame qui s'exécute dans un contexte d'injection.

Savoir quand vous êtes dans un contexte d'injection vous permet d'utiliser la fonction [`inject`](api/core/inject) pour récupérer des dépendances.

NOTE: Pour des exemples simples d'utilisation de `inject()` dans les constructeurs de classe et les initialiseurs de champs, consultez le [guide de présentation](/guide/di#where-can-inject-be-used).

## Stack frame dans le contexte {#stack-frame-in-context}

Certaines API sont conçues pour s'exécuter dans un contexte d'injection. C'est le cas, par exemple, des guards du router. Cela vous permet d'utiliser [`inject`](api/core/inject) dans la fonction de la guard pour accéder à des services.

Voici un exemple pour `CanActivateFn`

```ts
{highlight: [3]}
const canActivateTeam: CanActivateFn = (
  route: ActivatedRouteSnapshot,
  state: RouterStateSnapshot,
) => {
  return inject(PermissionsService).canActivate(inject(UserToken), route.params.id);
};
```

## Exécuter dans un contexte d'injection {#run-within-an-injection-context}

Si vous devez exécuter une fonction dans un contexte d'injection sans vous y trouver déjà, vous pouvez utiliser `runInInjectionContext`.
Cela nécessite d'avoir accès à un injector, comme l'`EnvironmentInjector` :

```ts
{highlight: [7], header:"hero.service.ts"}
@Service()
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // Do what you need with the injected service
    });
  }
}
```

Notez que [`inject`](/api/core/inject) ne renvoie une instance que si l'injector peut résoudre le jeton demandé.

## Vérifier le contexte {#asserts-the-context}

Angular fournit la fonction utilitaire `assertInInjectionContext` pour vérifier que le contexte courant est un contexte d'injection et lever une erreur claire si ce n'est pas le cas. Passez une référence à la fonction appelante pour que le message d'erreur désigne le bon point d'entrée de l'API. Le message obtenu est plus clair et plus exploitable que l'erreur d'injection générique par défaut.

```ts
import {ElementRef, assertInInjectionContext, inject} from '@angular/core';

export function injectNativeElement<T extends Element>(): T {
  assertInInjectionContext(injectNativeElement);
  return inject(ElementRef).nativeElement;
}
```

Vous pouvez ensuite appeler cette fonction utilitaire **depuis un contexte d'injection** (constructeur, initialiseur de champ, fabrique de provider ou code exécuté via `runInInjectionContext`) :

```ts
import {Component, inject} from '@angular/core';
import {injectNativeElement} from './dom-helpers';

@Component({/* … */})
export class PreviewCard {
  readonly hostEl = injectNativeElement<HTMLElement>(); // Field initializer runs in an injection context.

onAction() {
    const anotherRef = injectNativeElement<HTMLElement>(); // Fails: runs outside an injection context.
  }
}
```

## Utiliser la DI en dehors d'un contexte {#using-di-outside-of-a-context}

Si vous appelez [`inject`](api/core/inject) ou `assertInInjectionContext` en dehors d'un contexte d'injection, Angular lève l'[erreur NG0203](/errors/NG0203).
# Injectors hiérarchiques

Ce guide couvre en profondeur le système hiérarchique d'injection de dépendances d'Angular, y compris les règles de résolution, les modificateurs et les patterns avancés.

NOTE: Pour les concepts de base sur la hiérarchie des injectors et la portée des providers, consultez le [guide sur la définition des providers de dépendances](guide/di/defining-dependency-providers#injector-hierarchy-in-angular).

## Types de hiérarchies d'injectors {#types-of-injector-hierarchies}

Angular possède deux hiérarchies d'injectors :

| Hiérarchies d'injectors         | Détails                                                                                                                                                                   |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Hiérarchie `EnvironmentInjector` | Configurez un `EnvironmentInjector` dans cette hiérarchie avec `@Service()` ou le tableau `providers` de `ApplicationConfig`.                                           |
| Hiérarchie `ElementInjector`     | Créée implicitement pour chaque élément du DOM. Un `ElementInjector` est vide par défaut, sauf si vous le configurez dans la propriété `providers` de `@Directive()` ou `@Component()`. |
Pour les applications basées sur `NgModule`, vous pouvez fournir des dépendances avec la hiérarchie `ModuleInjector` à l'aide d'une annotation `@NgModule()` ou `@Injectable()`.
### `EnvironmentInjector` {#environmentinjector}

L'`EnvironmentInjector` peut être configuré de deux façons, en utilisant :

- Le décorateur `@Service()`
- Le tableau `providers` de `ApplicationConfig`
Il est préférable d'utiliser le décorateur `@Service()` plutôt que le tableau `providers` de `ApplicationConfig`. Avec `@Service`, les outils d'optimisation peuvent effectuer du tree-shaking, qui supprime les services que votre application n'utilise pas. Cela réduit la taille des bundles.

Le tree-shaking est particulièrement utile pour une library, car l'application qui utilise la library n'a pas forcément besoin de l'injecter.
L'`EnvironmentInjector` est configuré par `ApplicationConfig.providers`.

Fournissez des services avec `@Service()` de la façon suivante :

```ts
{highlight:[4]}
import {Service} from '@angular/core';

@Service() // <--provides this service in the root EnvironmentInjector
export class ItemService {
  name = 'telephone';
}
```

Les décorateurs `@Service()` ou `@Injectable()` identifient une classe de service.

### ModuleInjector {#moduleinjector}

Dans le cas des applications basées sur `NgModule`, le ModuleInjector peut être configuré de deux façons, en utilisant :

- Le décorateur `@Service()`,
- La propriété `providedIn` de `@Injectable()` pour faire référence à `root` ou `platform`
- Le tableau `providers` de `@NgModule()`

Le `ModuleInjector` est configuré par les propriétés `@NgModule.providers` et `NgModule.imports`. Le `ModuleInjector` est l'aplatissement de tous les tableaux de providers accessibles en suivant récursivement `NgModule.imports`.

Des hiérarchies `ModuleInjector` enfants sont créées lors du lazy loading d'autres `@NgModules`.

### Injector de plateforme {#platform-injector}

Il existe deux autres injectors au-dessus de `root` : un `EnvironmentInjector` supplémentaire et le `NullInjector()`.

Voyez comment Angular effectue le bootstrap de l'application avec le code suivant dans `main.ts` :

```ts
bootstrapApplication(App, appConfig);
```

La méthode `bootstrapApplication()` crée un injector enfant de l'injector de plateforme, configuré par l'instance de `ApplicationConfig`.
Il s'agit de l'`EnvironmentInjector` `root`.

La méthode `bootstrapApplication()` crée également (ou réutilise) l'injector de plateforme, qui contient les dépendances propres à la plateforme.
Cela permet à plusieurs applications de partager une configuration de plateforme.
Par exemple, un navigateur n'a qu'une seule barre d'adresse, quel que soit le nombre d'applications en cours d'exécution.
Vous pouvez configurer des providers supplémentaires propres à la plateforme au niveau de la plateforme en fournissant `extraProviders` via la fonction `platformBrowser()`.

L'injector parent suivant dans la hiérarchie est le `NullInjector()`, qui est le sommet de l'arbre.
Si vous êtes remonté si haut dans l'arbre que vous cherchez un service dans le `NullInjector()`, vous obtiendrez une erreur, sauf si vous avez utilisé `@Optional()`, car au bout du compte, tout se termine au `NullInjector()`, qui renvoie une erreur ou, dans le cas de `@Optional()`, `null`.
Pour plus d'informations sur `@Optional()`, consultez la [section `@Optional()`](#optional) de ce guide.

Le diagramme suivant représente la relation entre le `ModuleInjector` `root` et ses injectors parents, telle que décrite dans les paragraphes précédents.

```mermaid
stateDiagram-v2
    elementInjector: EnvironmentInjector<br>(configured by Angular)<br>has special things like DomSanitizer => providedIn 'platform'
    rootInjector: root EnvironmentInjector<br>(configured by AppConfig)<br>has things for your app => bootstrapApplication(..., AppConfig)
    nullInjector: NullInjector<br>always throws an error unless<br>you use @Optional()

direction BT
    rootInjector --> elementInjector
    elementInjector --> nullInjector
```

Si le nom `root` est un alias spécial, les autres hiérarchies `EnvironmentInjector` n'ont pas d'alias.
Vous avez la possibilité de créer des hiérarchies `EnvironmentInjector` chaque fois qu'un composant chargé dynamiquement est créé, par exemple avec le Router, qui crée des hiérarchies `EnvironmentInjector` enfants.

Toutes les requêtes remontent jusqu'à l'injector racine, que vous l'ayez configuré avec l'instance de `ApplicationConfig` passée à la méthode `bootstrapApplication()` ou que vous ayez enregistré tous les providers avec `root` dans leurs propres services.
Si vous configurez un provider à l'échelle de l'application dans l'`ApplicationConfig` de `bootstrapApplication`, il remplace celui configuré pour `root` dans les métadonnées de `@Injectable()`.
Vous pouvez le faire pour configurer un provider autre que celui par défaut pour un service partagé entre plusieurs applications.

Voici un exemple où la configuration du router de composants inclut une [location strategy](guide/routing/common-router-tasks#locationstrategy-and-browser-url-styles) autre que celle par défaut, en listant son provider dans la liste `providers` de l'`ApplicationConfig`.

```ts
providers: [{provide: LocationStrategy, useClass: HashLocationStrategy}];
```

Pour les applications basées sur `NgModule`, configurez les providers à l'échelle de l'application dans les `providers` de l'`AppModule`.
### `ElementInjector` {#elementinjector}

Angular crée implicitement des hiérarchies `ElementInjector` pour chaque élément du DOM.

Fournir un service dans le décorateur `@Component()` via sa propriété `providers` ou `viewProviders` configure un `ElementInjector`.
Par exemple, le `TestComponent` suivant configure l'`ElementInjector` en fournissant le service comme suit :

```ts
{highlight:[3]}
@Component({
  /* … */
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```

HELPFUL: Consultez la section [règles de résolution](#resolution-rules) pour comprendre la relation entre l'arbre `EnvironmentInjector`, le `ModuleInjector` et l'arbre `ElementInjector`.

Lorsque vous fournissez des services dans un composant, ce service est disponible via l'`ElementInjector` de cette instance du composant.
Il peut aussi être visible dans les composants et directives enfants, selon les règles de visibilité décrites dans la section [règles de résolution](#resolution-rules).

Lorsque l'instance du composant est détruite, l'instance du service l'est aussi.

#### `@Directive()` et `@Component()` {#directive-and-component}

Un composant est un type particulier de directive, ce qui signifie que, tout comme `@Directive()` possède une propriété `providers`, `@Component()` en possède une aussi.
Cela signifie que les directives comme les composants peuvent configurer des providers, avec la propriété `providers`.
Lorsque vous configurez un provider pour un composant ou une directive avec la propriété `providers`, ce provider appartient à l'`ElementInjector` de ce composant ou de cette directive.
Les composants et directives présents sur le même élément partagent un injector.

## Règles de résolution {#resolution-rules}

Pour résoudre un jeton pour un composant ou une directive, Angular procède en deux phases :

1. Auprès de ses parents dans la hiérarchie `ElementInjector`.
2. Auprès de ses parents dans la hiérarchie `EnvironmentInjector`.

Lorsqu'un composant déclare une dépendance, Angular essaie de la satisfaire avec son propre `ElementInjector`.
Si l'injector du composant n'a pas le provider, il transmet la requête à l'`ElementInjector` de son composant parent.

Les requêtes continuent de remonter jusqu'à ce qu'Angular trouve un injector capable de les traiter ou qu'il n'y ait plus de hiérarchies `ElementInjector` ancêtres.

Si Angular ne trouve le provider dans aucune hiérarchie `ElementInjector`, il revient à l'élément d'où provient la requête et cherche dans la hiérarchie `EnvironmentInjector`.
Si Angular ne trouve toujours pas le provider, il lève une erreur.

Si vous avez enregistré un provider pour le même jeton de DI à différents niveaux, Angular utilise le premier qu'il rencontre pour résoudre la dépendance.
Si, par exemple, un provider est enregistré localement dans le composant qui a besoin d'un service,
Angular ne cherche pas d'autre provider pour ce même service.

HELPFUL: Pour les applications basées sur `NgModule`, Angular cherche dans la hiérarchie `ModuleInjector` s'il ne trouve pas de provider dans les hiérarchies `ElementInjector`.

## Modificateurs de résolution {#resolution-modifiers}

Le comportement de résolution d'Angular peut être modifié avec `optional`, `self`, `skipSelf` et `host`.
Importez chacun d'eux depuis `@angular/core` et utilisez-les dans la configuration de [`inject`](/api/core/inject) lorsque vous injectez votre service.

### Types de modificateurs {#types-of-modifiers}

Les modificateurs de résolution se répartissent en trois catégories :

- Que faire si Angular ne trouve pas ce que vous cherchez : c'est `optional`
- Où commencer la recherche : c'est `skipSelf`
- Où arrêter la recherche : `host` et `self`

Par défaut, Angular commence toujours par l'`Injector` courant et poursuit la recherche jusqu'en haut.
Les modificateurs vous permettent de changer l'emplacement de départ, ou _self_, et l'emplacement d'arrivée.

De plus, vous pouvez combiner tous les modificateurs, sauf :

- `host` et `self`
- `skipSelf` et `self`.

### `optional` {#optional}

`optional` permet à Angular de considérer un service que vous injectez comme optionnel.
Ainsi, s'il ne peut pas être résolu à l'exécution, Angular résout le service à `null` au lieu de lever une erreur.
Dans l'exemple suivant, le service `OptionalService` n'est fourni ni dans le service, ni dans `ApplicationConfig`, ni dans un `@NgModule()`, ni dans la classe du composant ; il n'est donc disponible nulle part dans l'application.

```ts
{header:"src/app/optional/optional.ts"}
export class Optional {
  public optional? = inject(OptionalService, {optional: true});
}
```

### `self` {#self}

Utilisez `self` pour qu'Angular ne consulte que l'`ElementInjector` du composant ou de la directive courant.

Un bon cas d'usage de `self` consiste à injecter un service uniquement s'il est disponible sur le host element courant.
Pour éviter les erreurs dans cette situation, combinez `self` avec `optional`.

Par exemple, dans le `SelfNoData` suivant, remarquez le `LeafService` injecté en tant que propriété.

```ts
{header: 'self-no-data.ts', highlight: [7]}
@Component({
  selector: 'app-self-no-data',
  templateUrl: './self-no-data.html',
  styleUrls: ['./self-no-data.css'],
})
export class SelfNoData {
  public leaf = inject(LeafService, {optional: true, self: true});
}
```

Dans cet exemple, il existe un provider parent et injecter le service renverrait sa valeur ; cependant, injecter le service avec `self` et `optional` renvoie `null`, car `self` indique à l'injector d'arrêter sa recherche au host element courant.

Un autre exemple montre la classe du composant avec un provider pour `FlowerService`.
Dans ce cas, l'injector ne cherche pas au-delà de l'`ElementInjector` courant, car il y trouve le `FlowerService` et renvoie la tulipe 🌷.

```ts
{header:"src/app/self/self.ts"}
@Component({
  selector: 'app-self',
  templateUrl: './self.html',
  styleUrls: ['./self.css'],
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class Self {
  public flower = inject(FlowerService, {self: true});
}
```

### `skipSelf` {#skipself}

`skipSelf` est l'inverse de `self`.
Avec `skipSelf`, Angular commence sa recherche d'un service dans l'`ElementInjector` parent, plutôt que dans l'injector courant.
Ainsi, si l'`ElementInjector` parent utilisait la valeur fougère <code>🌿</code> pour `emoji`, mais que vous aviez la feuille d'érable <code>🍁</code> dans le tableau `providers` du composant, Angular ignorerait la feuille d'érable <code>🍁</code> et utiliserait la fougère <code>🌿</code>.

Pour le voir dans le code, supposez que la valeur suivante pour `emoji` soit celle qu'utilisait le composant parent, comme dans ce service :

```ts
{header: 'leaf.service.ts'}
export class LeafService {
  emoji = '🌿';
}
```

Imaginez que dans le composant enfant, vous ayez une valeur différente, la feuille d'érable 🍁, mais que vous vouliez utiliser la valeur du parent à la place.
C'est là que vous utiliseriez `skipSelf` :

```ts
{header:"skipself.ts" highlight:[[6],[10]]}
@Component({
  selector: 'app-skipself',
  templateUrl: './skipself.html',
  styleUrls: ['./skipself.css'],
  // Angular would ignore this LeafService instance
  providers: [{provide: LeafService, useValue: {emoji: '🍁'}}],
})
export class Skipself {
  // Use skipSelf as inject option
  public leaf = inject(LeafService, {skipSelf: true});
}
```

Dans ce cas, la valeur obtenue pour `emoji` serait la fougère <code>🌿</code>, et non la feuille d'érable <code>🍁</code>.

#### Option `skipSelf` avec `optional` {#skipself-option-with-optional}

Utilisez l'option `skipSelf` avec `optional` pour éviter une erreur si la valeur est `null`.

Dans l'exemple suivant, le service `Person` est injecté lors de l'initialisation de la propriété.
`skipSelf` indique à Angular d'ignorer l'injector courant, et `optional` évite une erreur si le service `Person` était `null`.

```ts
class Person {
  parent = inject(Person, {optional: true, skipSelf: true});
}
```

### `host` {#host}

`host` vous permet de désigner un composant comme dernier arrêt dans l'arbre des injectors lors de la recherche de providers.

Même s'il existe une instance du service plus haut dans l'arbre, Angular ne poursuit pas la recherche.
Utilisez `host` comme suit :

```ts
{header:"host.ts" highlight:[[6],[9]]}
@Component({
  selector: 'app-host',
  templateUrl: './host.html',
  styleUrls: ['./host.css'],
  // provide the service
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class Host {
  // use host when injecting the service
  flower = inject(FlowerService, {host: true, optional: true});
}
```

Comme `Host` utilise l'option `host`, quelle que soit la valeur de `flower.emoji` dont dispose le parent de `Host`, `Host` utilisera la tulipe <code>🌷</code>.

### Modificateurs avec l'injection par constructeur {#modifiers-with-constructor-injection}

De la même manière que précédemment, le comportement de l'injection par constructeur peut être modifié avec `@Optional()`, `@Self()`, `@SkipSelf()` et `@Host()`.

Importez chacun d'eux depuis `@angular/core` et utilisez-les dans le constructeur de la classe du composant lorsque vous injectez votre service.

```ts
{header:"self-no-data.ts" highlight:[2]}
export class SelfNoData {
  constructor(@Self() @Optional() public leaf?: LeafService) {}
}
```

## Structure logique du template {#logical-structure-of-the-template}

Lorsque vous fournissez des services dans la classe du composant, ces services sont visibles dans l'arbre `ElementInjector` en fonction de l'endroit et de la manière dont vous les fournissez.

Comprendre la structure logique sous-jacente du template Angular vous donne les bases pour configurer les services et, par conséquent, contrôler leur visibilité.

Les composants sont utilisés dans vos templates, comme dans l'exemple suivant :

```html
<app-root> <app-child />; </app-root>
```

HELPFUL: En général, vous déclarez les composants et leurs templates dans des fichiers séparés.
Pour comprendre le fonctionnement du système d'injection, il est utile de les considérer du point de vue d'un arbre logique combiné.
Le terme _logique_ le distingue de l'arbre de rendu, qui est l'arbre DOM de votre application.
Pour indiquer l'emplacement des templates des composants, ce guide utilise le pseudo-élément `<#VIEW>`, qui n'existe pas réellement dans l'arbre de rendu et ne sert qu'à construire un modèle mental.

Voici un exemple de la façon dont les arbres de vues de `<app-root>` et `<app-child>` sont combinés en un seul arbre logique :

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …content goes here…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Comprendre l'idée de la démarcation `<#VIEW>` est particulièrement important lorsque vous configurez des services dans la classe du composant.

## Exemple : fournir des services dans `@Component()` {#example-providing-services-in-component}

La façon dont vous fournissez des services avec un décorateur `@Component()` (ou `@Directive()`) détermine leur visibilité.
Les sections suivantes présentent `providers` et `viewProviders`, ainsi que les façons de modifier la visibilité des services avec `skipSelf` et `host`.

Une classe de composant peut fournir des services de deux façons :

| Tableaux                         | Détails                                        |
| :--------------------------- | :--------------------------------------------- |
| Avec un tableau `providers`      | `@Component({ providers: [SomeService] })`     |
| Avec un tableau `viewProviders`  | `@Component({ viewProviders: [SomeService] })` |

Dans les exemples ci-dessous, vous verrez l'arbre logique d'une application Angular.
Pour illustrer le fonctionnement de l'injector dans le contexte des templates, l'arbre logique représente la structure HTML de l'application.
Par exemple, l'arbre logique montrera que `<child-component>` est un enfant direct de `<parent-component>`.

Dans l'arbre logique, vous verrez des attributs spéciaux : `@Provide`, `@Inject` et `@ApplicationConfig`.
Ce ne sont pas de vrais attributs : ils servent à montrer ce qui se passe en coulisses.

| Attribut de service Angular | Détails                                                                                  |
| :------------------------ | :--------------------------------------------------------------------------------------- |
| `@Inject(Token)=>Value`   | Si `Token` est injecté à cet emplacement de l'arbre logique, sa valeur serait `Value`. |
| `@Provide(Token=Value)`   | Indique que `Token` est fourni avec `Value` à cet emplacement de l'arbre logique.    |
| `@ApplicationConfig`      | Indique qu'un `EnvironmentInjector` de repli doit être utilisé à cet emplacement.      |

### Structure de l'application d'exemple {#example-app-structure}

L'application d'exemple possède un `FlowerService` fourni dans `root` avec une valeur `emoji` d'hibiscus rouge <code>🌺</code>.

```ts
{header:"flower.service.ts"}
@Service()
export class FlowerService {
  emoji = '🌺';
}
```

Prenons une application composée uniquement d'un `App` et d'un `Child`.
La vue rendue la plus simple ressemblerait à des éléments HTML imbriqués comme ceux-ci :

```html
<app-root>
  
  <app-child>  </app-child>
</app-root>
```

Cependant, en coulisses, Angular utilise une représentation logique des vues comme suit pour résoudre les requêtes d'injection :

```html
<app-root> 
  <#VIEW>
    <app-child> 
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Le `<#VIEW>` représente ici une instance d'un template.
Remarquez que chaque composant possède son propre `<#VIEW>`.

Connaître cette structure vous aide à décider comment fournir et injecter vos services, et vous donne un contrôle total sur leur visibilité.

Supposons maintenant que `<app-root>` injecte le `FlowerService` :

```typescript
export class App {
  flower = inject(FlowerService);
}
```

Ajoutez un binding au template de `<app-root>` pour visualiser le résultat :

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

Le résultat affiché dans la vue serait :

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

Dans l'arbre logique, cela serait représenté comme suit :

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child>
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Lorsque `<app-root>` demande le `FlowerService`, c'est à l'injector de résoudre le jeton `FlowerService`.
La résolution du jeton se fait en deux phases :

1. L'injector détermine l'emplacement de départ dans l'arbre logique et l'emplacement d'arrivée de la recherche.
   L'injector commence à l'emplacement de départ et cherche le jeton à chaque niveau de vue de l'arbre logique.
   Si le jeton est trouvé, il est renvoyé.

1. Si le jeton n'est pas trouvé, l'injector cherche l'`EnvironmentInjector` parent le plus proche auquel déléguer la requête.

Dans cet exemple, les contraintes sont les suivantes :

1. Commencer par le `<#VIEW>` appartenant à `<app-root>` et terminer par `<app-root>`.
   - Normalement, le point de départ de la recherche est le point d'injection.
     Cependant, ici `<app-root>` est un composant. Les `@Component` sont particuliers, car ils incluent aussi leurs propres `viewProviders` ; c'est pourquoi la recherche commence au `<#VIEW>` appartenant à `<app-root>`.
     Ce ne serait pas le cas pour une directive correspondant au même emplacement.
   - L'emplacement d'arrivée se trouve être le composant lui-même, car c'est le composant le plus haut de cette application.

1. L'`EnvironmentInjector` fourni par l'`ApplicationConfig` sert d'injector de repli lorsque le jeton d'injection est introuvable dans les hiérarchies `ElementInjector`.

### Utiliser le tableau `providers` {#using-the-providers-array}

Maintenant, dans la classe `Child`, ajoutez un provider pour `FlowerService` afin d'illustrer des règles de résolution plus complexes dans les sections suivantes :

```ts
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // use the providers array to provide a service
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
})
export class Child {
  // inject the service
  flower = inject(FlowerService);
}
```

Maintenant que le `FlowerService` est fourni dans le décorateur `@Component()`, lorsque `<app-child>` demande le service, l'injector n'a besoin de chercher que jusqu'à l'`ElementInjector` de `<app-child>`.
Il n'a pas besoin de poursuivre la recherche plus loin dans l'arbre des injectors.

L'étape suivante consiste à ajouter un binding au template de `Child`.

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

Pour afficher les nouvelles valeurs, ajoutez `<app-child>` en bas du template de `App` afin que la vue affiche aussi le tournesol :

```text
{hideCopy}
Child Component
Emoji from FlowerService: 🌻
```

Dans l'arbre logique, cela est représenté comme suit :

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>

<p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
  <app-child @Provide(FlowerService="🌻" )
             @Inject(FlowerService)=>"🌻"> 
    <#VIEW> 
    <h2>Child Component</h2>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌻)</p>
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Lorsque `<app-child>` demande le `FlowerService`, l'injector commence sa recherche au `<#VIEW>` appartenant à `<app-child>` $le `<#VIEW>` est inclus parce que l'injection se fait depuis `@Component()`$ et la termine à `<app-child>`.
Dans ce cas, le `FlowerService` est résolu dans le tableau `providers` de `<app-child>`, avec le tournesol <code>🌻</code>.
L'injector n'a pas besoin de chercher plus loin dans l'arbre des injectors.
Il s'arrête dès qu'il trouve le `FlowerService` et ne voit jamais l'hibiscus rouge <code>🌺</code>.

### Utiliser le tableau `viewProviders` {#using-the-viewproviders-array}

Utilisez le tableau `viewProviders` comme autre moyen de fournir des services dans le décorateur `@Component()`.
Utiliser `viewProviders` rend les services visibles dans le `<#VIEW>`.

HELPFUL: Les étapes sont les mêmes qu'avec le tableau `providers`, à ceci près que vous utilisez le tableau `viewProviders` à la place.

Pour des instructions pas à pas, poursuivez avec cette section.
Si vous savez le mettre en place vous-même, passez directement à [Modifier la disponibilité des services](#visibility-of-provided-tokens).

Pour la démonstration, nous créons un `AnimalService` afin d'illustrer `viewProviders`.
Commencez par créer un `AnimalService` avec une propriété `emoji` valant la baleine <code>🐳</code> :

```typescript
import {Service} from '@angular/core';

@Service()
export class AnimalService {
  emoji = '🐳';
}
```

En suivant le même pattern qu'avec le `FlowerService`, injectez l'`AnimalService` dans la classe `App` :

```ts
export class App {
  public flower = inject(FlowerService);
  public animal = inject(AnimalService);
}
```

HELPFUL: Vous pouvez laisser en place tout le code lié au `FlowerService`, car il permettra une comparaison avec l'`AnimalService`.

Ajoutez un tableau `viewProviders` et injectez aussi l'`AnimalService` dans la classe de `<app-child>`, mais donnez à `emoji` une valeur différente.
Ici, sa valeur est le chien 🐶.

```typescript
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // provide services
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
  viewProviders: [{provide: AnimalService, useValue: {emoji: '🐶'}}],
})
export class Child {
  // inject services
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

Ajoutez des bindings aux templates de `Child` et de `App`.
Dans le template de `Child`, ajoutez le binding suivant :

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Ajoutez également le même binding au template de `App` :

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Vous devriez maintenant voir les deux valeurs dans le navigateur :

```text
{hideCopy}
App
Emoji from AnimalService: 🐳

Child Component
Emoji from AnimalService: 🐶
```

L'arbre logique de cet exemple avec `viewProviders` est le suivant :

```html
<app-root @ApplicationConfig
          @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService=>"🐶")>

<p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Comme dans l'exemple du `FlowerService`, l'`AnimalService` est fourni dans le décorateur `@Component()` de `<app-child>`.
Cela signifie que, puisque l'injector cherche d'abord dans l'`ElementInjector` du composant, il trouve la valeur chien <code>🐶</code> de l'`AnimalService`.
Il n'a pas besoin de poursuivre la recherche dans l'arbre `ElementInjector`, ni de chercher dans le `ModuleInjector`.

### `providers` ou `viewProviders` {#providers-vs-viewproviders}

Le champ `viewProviders` est conceptuellement similaire à `providers`, mais il existe une différence notable.
Les providers de `viewProviders` ne sont visibles que dans la propre vue du composant : le contenu projeté dans le composant via `<ng-content>` ne peut pas les voir.

Pour voir la différence entre `providers` et `viewProviders`, ajoutez un autre composant à l'exemple et appelez-le `Inspector`.
`Inspector` sera un enfant de `Child`.
Dans `inspector.ts`, injectez le `FlowerService` et l'`AnimalService` lors de l'initialisation des propriétés :

```typescript
export class Inspector {
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

Vous n'avez pas besoin de tableau `providers` ni `viewProviders`.
Ensuite, dans `inspector.html`, ajoutez le même balisage que dans les composants précédents :

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

N'oubliez pas d'ajouter `Inspector` au tableau `imports` de `Child`.

```ts
@Component({
  ...
  imports: [Inspector]
})
```

Ensuite, ajoutez le code suivant à `child.html` :

```html
...

<div class="container">
  <h3>Content projection</h3>
  <ng-content />
</div>
<h3>Inside the view</h3>

<app-inspector />
```

`<ng-content>` vous permet de projeter du contenu, et `<app-inspector>` dans le template de `Child` fait d'`Inspector` un composant enfant de `Child`.

Ensuite, ajoutez le code suivant à `app.html` pour tirer parti de la projection de contenu.

```html
<app-child>
  <app-inspector />
</app-child>
```

Le navigateur affiche maintenant ce qui suit (les exemples précédents sont omis par souci de concision) :

```text
{hideCopy}
...
Content projection

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐳

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐶
```

Ces quatre bindings montrent la différence entre `providers` et `viewProviders`.
Rappelez-vous que l'emoji chien <code>🐶</code> est déclaré dans le `<#VIEW>` de `Child` et n'est pas visible par le contenu projeté.
Le contenu projeté voit à la place la baleine <code>🐳</code>.

Vous vous demandez peut-être pourquoi le `<app-inspector>` projeté peut tout de même voir <code>🐳</code>, c'est-à-dire l'`AnimalService` fourni à la racine.
La raison est que la DI d'Angular suit **l'endroit où un composant a été déclaré**, et non l'endroit où il finit par être rendu.
`<app-inspector>` se trouve dans le template de `App`, à l'intérieur du `<#VIEW>` de `App` ; sa recherche ne passe donc jamais par le `<#VIEW>` de `Child`.
Le projeter dans `Child` lui coupe l'accès aux `viewProviders` de `Child` (<code>🐶</code>), mais l'`AnimalService` racine (<code>🐳</code>) reste accessible en remontant l'arbre.

En revanche, dans la sortie suivante, l'`Inspector` est un véritable composant enfant de `Child` : `Inspector` se trouve dans le `<#VIEW>`, donc lorsqu'il demande l'`AnimalService`, il voit le chien <code>🐶</code>.

L'`AnimalService` dans l'arbre logique ressemblerait à ceci :

```html
<app-root @ApplicationConfig
          @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService=>"🐶")>

<p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>

<div class="container">
      <h3>Content projection</h3>
      <app-inspector @Inject(AnimalService) animal=>"🐳">
        <p>Emoji from AnimalService: {{animal.emoji}} (🐳)</p>
      </app-inspector>
    </div>

<app-inspector>
      <#VIEW @Inject(AnimalService) animal=>"🐶">
      <p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
    </
    #VIEW>
    </app-inspector>
  </
  #VIEW>
  </app-child>

</#VIEW>
</app-root>
```

Le `<app-inspector>` projeté obtient <code>🐳</code>, car <code>🐶</code> appartient à la vue de `Child` et le contenu projeté ne peut pas l'atteindre.
<code>🐳</code> est accessible parce que `<app-inspector>` a été déclaré dans le template de `App` ; il peut donc encore remonter jusqu'à l'`AnimalService` racine.

Le `<app-inspector>` qui se trouve directement dans le template de `Child` (non projeté) obtient <code>🐶</code> : il est à l'intérieur du `<#VIEW>`, il n'y a donc aucune frontière à franchir.

### Donner au contenu projeté l'accès à un injector de vue {#giving-projected-content-access-to-a-view-injector}

Le contenu projeté avec `<ng-content>` ne peut pas voir les `viewProviders` d'un composant, car Angular résout l'injection auprès de l'injector où le contenu est déclaré, et non là où il est rendu.

Lorsque vous voulez précisément que le contenu projeté atteigne un service au niveau de la vue (ou l'instance du composant qui projette elle-même), acceptez le contenu sous forme de template au lieu de `<ng-content>` et rendez-le avec un injector explicite.

Modifiez `Child` pour fournir `AnimalService` dans `viewProviders`, récupérer le template projeté avec une query et le rendre via [`NgTemplateOutlet`](/api/common/NgTemplateOutlet), avec `ngTemplateOutletInjector` défini sur un injector qui peut voir ce service :

```ts
@Component({
  selector: 'app-child',
  viewProviders: [AnimalService],
  imports: [NgTemplateOutlet],
  template: `
    <ng-container [ngTemplateOutlet]="content()" [ngTemplateOutletInjector]="injector" />
  `,
})
export class Child {
  readonly content = contentChild.required(TemplateRef);
  readonly injector = inject(Injector);
}
```

Le consommateur enveloppe le balisage projeté dans un `<ng-template>` :

```html
<app-child>
  <ng-template>
    <app-inspector />
  </ng-template>
</app-child>
```

`Child` crée maintenant `<app-inspector>` au niveau de l'outlet avec son propre injector ; `AnimalService` se résout donc en chien <code>🐶</code>, même si le balisage est écrit dans le template de `App`. Le coût est un peu de balisage supplémentaire des deux côtés par rapport à `<ng-content>`.

### Visibilité des jetons fournis {#visibility-of-provided-tokens}

Les décorateurs de visibilité influencent l'endroit où la recherche du jeton d'injection commence et se termine dans l'arbre logique.
Pour cela, placez la configuration de visibilité au point d'injection, c'est-à-dire lors de l'appel à `inject()`, plutôt qu'au point de déclaration.

Pour modifier l'endroit où l'injector commence à chercher `FlowerService`, ajoutez `skipSelf` à l'appel `inject()` de `<app-child>` où `FlowerService` est injecté.
Cet appel est un initialiseur de propriété dans `<app-child>`, comme le montre `child.ts` :

```typescript
flower = inject(FlowerService, {skipSelf: true});
```

Avec `skipSelf`, l'injector de `<app-child>` ne cherche pas le `FlowerService` en lui-même.
L'injector commence plutôt à chercher le `FlowerService` dans l'`ElementInjector` de `<app-root>`, où il ne trouve rien.
Il revient ensuite au `ModuleInjector` de `<app-child>` et trouve la valeur hibiscus rouge <code>🌺</code>, disponible parce que `<app-child>` et `<app-root>` partagent le même `ModuleInjector`.
L'interface affiche ce qui suit :

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

Dans un arbre logique, cette même idée pourrait ressembler à ceci :

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
  <app-child @Provide(FlowerService="🌻" )>
    <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺">

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Bien que `<app-child>` fournisse le tournesol <code>🌻</code>, l'application affiche l'hibiscus rouge <code>🌺</code>, car `skipSelf` amène l'injector courant (`app-child`) à s'ignorer lui-même et à chercher dans son parent.

Si vous ajoutez maintenant `host` (en plus de `skipSelf`), le résultat sera `null`.
En effet, `host` limite la borne supérieure de la recherche au `<#VIEW>` de `app-child`.
Voici l'idée dans l'arbre logique :

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW> 
  <app-child @Provide(FlowerService="🌻" )> 
    <#VIEW inject(FlowerService, {skipSelf: true, host: true, optional:true})=>null>
  </
  #VIEW>
  </app-parent>
</#VIEW>
</app-root>
```

Ici, les services et leurs valeurs sont les mêmes, mais `host` empêche l'injector de chercher `FlowerService` au-delà du `<#VIEW>` ; il ne le trouve donc pas et renvoie `null`.

### `skipSelf` et `viewProviders` {#skipself-and-viewproviders}

Rappelez-vous que `<app-child>` fournit l'`AnimalService` dans le tableau `viewProviders` avec la valeur chien <code>🐶</code>.
Comme l'injector n'a qu'à consulter l'`ElementInjector` de `<app-child>` pour trouver l'`AnimalService`, il ne voit jamais la baleine <code>🐳</code>.

Comme dans l'exemple du `FlowerService`, si vous ajoutez `skipSelf` à l'appel `inject()` de l'`AnimalService`, l'injector ne cherchera pas l'`AnimalService` dans l'`ElementInjector` du `<app-child>` courant.
L'injector commencera plutôt par l'`ElementInjector` de `<app-root>`.

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```

Avec `skipSelf` dans `<app-child>`, l'arbre logique ressemble à ceci :

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService, SkipSelf=>"🐳")>

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Avec `skipSelf` dans `<app-child>`, l'injector commence sa recherche de l'`AnimalService` dans l'`ElementInjector` de `<app-root>` et trouve la baleine 🐳.

### `host` et `viewProviders` {#host-and-viewproviders}

Si vous utilisez uniquement `host` pour l'injection de l'`AnimalService`, le résultat est le chien <code>🐶</code>, car l'injector trouve l'`AnimalService` dans le `<#VIEW>` de `<app-child>` lui-même.
`Child` configure les `viewProviders` de sorte que l'emoji chien soit fourni comme valeur de l'`AnimalService`.
Vous pouvez aussi voir `host` dans l'appel `inject()` :

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ]
})
export class Child {
  animal = inject(AnimalService, { host: true })
}
```

`host: true` amène l'injector à chercher jusqu'à atteindre la limite du `<#VIEW>`.

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {host: true}=>"🐶")> 
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Ajoutez un tableau `viewProviders` avec un troisième animal, le hérisson <code>🦔</code>, aux métadonnées `@Component()` de `app.ts` :

```typescript
@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styleUrls: [ './app.css' ],
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🦔' } },
  ],
})
```

Ensuite, ajoutez `skipSelf` en plus de `host` à l'appel `inject()` qui injecte l'`AnimalService` dans `child.ts`.
Voici `host` et `skipSelf` dans l'initialisation de la propriété `animal` :

```typescript
export class Child {
  animal = inject(AnimalService, {host: true, skipSelf: true});
}
```

Lorsque `host` et `skipSelf` étaient appliqués au `FlowerService`, qui se trouve dans le tableau `providers`, le résultat était `null`, car `skipSelf` commence sa recherche dans l'injector de `<app-child>`, mais `host` arrête la recherche au `<#VIEW>`, où il n'y a pas de `FlowerService`.
Dans l'arbre logique, vous pouvez voir que le `FlowerService` est visible dans `<app-child>`, et non dans son `<#VIEW>`.

En revanche, l'`AnimalService`, fourni dans le tableau `viewProviders` de `App`, est visible.

La représentation de l'arbre logique montre pourquoi :

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW @Provide(AnimalService="🦔")
  @Inject(AnimalService, @Optional)=>"🦔">

<app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {skipSelf:true, host: true, optional: true})=>"🦔">
    
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

`skipSelf` amène l'injector à commencer sa recherche de l'`AnimalService` à `<app-root>`, et non à `<app-child>` d'où provient la requête, et `host` arrête la recherche au `<#VIEW>` de `<app-root>`.
Comme l'`AnimalService` est fourni via le tableau `viewProviders`, l'injector trouve le hérisson <code>🦔</code> dans le `<#VIEW>`.

## Exemple : cas d'usage de `ElementInjector` {#example-elementinjector-use-cases}

La possibilité de configurer un ou plusieurs providers à différents niveaux ouvre des possibilités utiles.

### Scénario : isolation de service {#scenario-service-isolation}

Des raisons d'architecture peuvent vous amener à restreindre l'accès à un service au domaine de l'application auquel il appartient.
Par exemple, supposons que nous construisions un `VillainsList` qui affiche une liste de méchants.
Il récupère ces méchants depuis un `VillainsService`.

Si vous fournissez `VillainsService` dans l'`AppModule` racine, `VillainsService` sera visible partout dans l'application.
Si vous modifiez ensuite le `VillainsService`, vous risquez de casser quelque chose dans d'autres composants qui auraient commencé à dépendre de ce service par accident.

Fournissez plutôt le `VillainsService` dans les métadonnées `providers` du `VillainsList`, comme ceci :

```typescript
@Component({
  selector: 'app-villains-list',
  templateUrl: './villains-list.html',
  providers: [VillainsService],
})
export class VillainsList {}
```

En fournissant `VillainsService` dans les métadonnées de `VillainsList` et nulle part ailleurs, le service n'est disponible que dans `VillainsList` et son arbre de sous-composants.

`VillainsService` est un singleton par rapport à `VillainsList`, car c'est là qu'il est déclaré.
Tant que `VillainsList` n'est pas détruit, il s'agira de la même instance de `VillainsService` ; mais s'il existe plusieurs instances de `VillainsList`, chaque instance de `VillainsList` aura sa propre instance de `VillainsService`.

### Scénario : plusieurs sessions d'édition {#scenario-multiple-edit-sessions}

De nombreuses applications permettent aux utilisateurs de travailler sur plusieurs tâches ouvertes en même temps.
Par exemple, dans une application de préparation des déclarations d'impôts, le préparateur peut travailler sur plusieurs déclarations, en passant de l'une à l'autre tout au long de la journée.

Pour illustrer ce scénario, imaginez un `HeroList` qui affiche une liste de super-héros.

Pour ouvrir la déclaration d'impôts d'un héros, le préparateur clique sur le nom d'un héros, ce qui ouvre un composant permettant de modifier cette déclaration.
Chaque déclaration d'impôts de héros sélectionnée s'ouvre dans son propre composant, et plusieurs déclarations peuvent être ouvertes en même temps.

Chaque composant de déclaration d'impôts présente les caractéristiques suivantes :

- Il constitue sa propre session d'édition de déclaration d'impôts
- Il peut modifier une déclaration sans affecter celle d'un autre composant
- Il peut enregistrer les modifications de sa déclaration ou les annuler

Supposons que le `HeroTaxReturnEditor` contienne la logique de gestion et de restauration des modifications.
Ce serait une tâche simple pour une déclaration d'impôts de héros.
Dans la réalité, avec un modèle de données de déclaration riche, la gestion des modifications serait délicate.
Vous pourriez déléguer cette gestion à un service d'assistance, comme le fait cet exemple.

Le `HeroTaxReturnService` met en cache une seule `HeroTaxReturn`, suit les modifications de cette déclaration et peut l'enregistrer ou la restaurer.
Il délègue également au `HeroService`, singleton à l'échelle de l'application, qu'il obtient par injection.

```typescript
import {inject, Service} from '@angular/core';
import {HeroTaxReturn} from './hero';
import {HeroesService} from './heroes.service';

@Service({autoProvided: false})
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();
  }
}
```

Voici le `HeroTaxReturnEditor` qui utilise le `HeroTaxReturnService`.

```typescript
import {Component, effect, inject, 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.html',
  styleUrls: ['./hero-tax-return.css'],
  providers: [HeroTaxReturnService],
})
export class HeroTaxReturnEditor {
  message = '';

close = output<void>();

taxReturn = input.required<HeroTaxReturn>();

private heroTaxReturnService = inject(HeroTaxReturnService);

constructor() {
    effect(() => {
      this.heroTaxReturnService.taxReturn = this.taxReturn();
    });
  }

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 _déclaration à modifier_ arrive via l'input signal `taxReturn`.
Un `effect` initialise l'instance propre au composant du `HeroTaxReturnService` avec la déclaration reçue chaque fois que l'input change.
Le getter du service renvoie toujours ce que le service considère comme l'état courant du héros.
Le composant demande également au service d'enregistrer et de restaurer cette déclaration d'impôts.

Cela ne fonctionnera pas si le service est un singleton à l'échelle de l'application.
Tous les composants partageraient la même instance du service, et chaque composant écraserait la déclaration d'impôts appartenant à un autre héros.

Pour éviter cela, configurez l'injector au niveau du composant de `HeroTaxReturnEditor` pour qu'il fournisse le service, avec la propriété `providers` des métadonnées du composant.

```typescript
providers: [HeroTaxReturnService];
```

Le `HeroTaxReturnEditor` possède son propre provider du `HeroTaxReturnService`.
Rappelez-vous que chaque _instance_ de composant possède son propre injector.
Fournir le service au niveau du composant garantit que _chaque_ instance du composant obtient une instance privée du service. Ainsi, aucune déclaration d'impôts n'est écrasée.

HELPFUL: Le reste du code du scénario s'appuie sur d'autres fonctionnalités et techniques d'Angular, que vous pouvez découvrir ailleurs dans la documentation.

### Scénario : providers spécialisés {#scenario-specialized-providers}

Une autre raison de fournir à nouveau un service à un autre niveau est de substituer une implémentation _plus spécialisée_ de ce service, plus profondément dans l'arbre des composants.

Par exemple, prenons un composant `Car` qui inclut des informations sur l'entretien des pneus et dépend d'autres services pour fournir plus de détails sur la voiture.

L'injector racine, noté (A), utilise des providers _génériques_ pour les détails de `CarService` et `EngineService`.

1. Composant `Car` (A). Le composant (A) affiche les données d'entretien des pneus d'une voiture et spécifie des services génériques pour fournir plus d'informations sur la voiture.

2. Composant enfant (B). Le composant (B) définit ses propres providers _spécialisés_ pour `CarService` et `EngineService`, dotés de capacités particulières adaptées à ce qui se passe dans le composant (B).

3. Composant enfant (C), enfant du composant (B). Le composant (C) définit son propre provider, encore _plus spécialisé_, pour `CarService`.

```mermaid
graph TD;
subgraph COMPONENT_A[Component A]
subgraph COMPONENT_B[Component B]
COMPONENT_C[Component 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
```

En coulisses, chaque composant configure son propre injector avec zéro, un ou plusieurs providers définis pour ce composant lui-même.

Lorsque vous résolvez une instance de `Car` dans le composant le plus profond (C), son injector produit :

- Une instance de `Car` résolue par l'injector (C)
- Un `Engine` résolu par l'injector (B)
- Ses `Tires` résolus par l'injector racine (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
```

## En savoir plus sur l'injection de dépendances {#more-on-dependency-injection}
# Optimiser la taille de l'application cliente avec des jetons d'injection légers

Cette page présente une vue d'ensemble conceptuelle d'une technique d'injection de dépendances recommandée pour les développeurs de libraries.
Concevoir votre library avec des _jetons d'injection légers_ aide à optimiser la taille du bundle des applications clientes qui utilisent votre library.

Vous pouvez gérer la structure des dépendances entre vos composants et vos services injectables pour optimiser la taille du bundle en utilisant des providers compatibles avec le tree-shaking.
Normalement, cela garantit que si un composant ou un service fourni n'est jamais réellement utilisé par l'application, le compilateur peut retirer son code du bundle.

En raison de la façon dont Angular stocke les jetons d'injection, il est possible qu'un tel composant ou service inutilisé se retrouve quand même dans le bundle.
Cette page décrit un design pattern d'injection de dépendances qui permet un tree-shaking correct grâce aux jetons d'injection légers.

Le design pattern des jetons d'injection légers est particulièrement important pour les développeurs de libraries.
Il garantit que, quand une application n'utilise qu'une partie des fonctionnalités de votre library, le code inutilisé peut être éliminé du bundle de l'application cliente.

Quand une application utilise votre library, il se peut que votre library fournisse certains services que l'application cliente n'utilise pas.
Dans ce cas, le développeur de l'application s'attend à ce que ce service soit éliminé par le tree-shaking et ne contribue pas à la taille de l'application compilée.
Comme le développeur de l'application ne peut ni connaître ni corriger un problème de tree-shaking dans la library, c'est au développeur de la library de s'en charger.
Pour éviter la rétention de composants inutilisés, votre library doit utiliser le design pattern des jetons d'injection légers.

## Quand les jetons sont conservés {#when-tokens-are-retained}

Pour mieux expliquer dans quelles conditions un jeton est conservé, prenons une library qui fournit un composant de carte.
Ce composant contient un corps et peut contenir un en-tête facultatif :

```html
<lib-card>
  <lib-header>…</lib-header>
</lib-card>
```

Dans une implémentation probable, le composant `<lib-card>` utilise `contentChild` ou `contentChildren` pour obtenir `<lib-header>` et `<lib-body>`, comme ceci :

```ts
{highlight: [14]}
import {Component, contentChild} from '@angular/core';

@Component({
  selector: 'lib-header',
  …,
})
class LibHeader {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCard {
  readonly header = contentChild(LibHeader);
}
```

Comme `<lib-header>` est facultatif, l'élément peut apparaître dans le template sous sa forme minimale, `<lib-card />`.
Dans ce cas, `<lib-header>` n'est pas utilisé et vous vous attendriez à ce qu'il soit éliminé par le tree-shaking, mais ce n'est pas ce qui se passe.
En effet, `LibCard` contient en réalité deux références à `LibHeader` :

```ts
readonly header = contentChild(LibHeader);
```

- L'une de ces références est en _position de type_, c'est-à-dire qu'elle spécifie `LibHeader` comme type : `readonly header: Signal<LibHeader|undefined>`.
- L'autre référence est en _position de valeur_, c'est-à-dire que `LibHeader` est la valeur passée à la fonction `contentChild` : `contentChild(LibHeader)`.

Le compilateur traite différemment les références de jetons selon leur position :

- Le compilateur efface les références en _position de type_ après la conversion depuis TypeScript : elles n'ont donc aucun impact sur le tree-shaking.
- Le compilateur doit conserver les références en _position de valeur_ à l'exécution, ce qui **empêche** le composant d'être éliminé par le tree-shaking.

Dans l'exemple, le compilateur conserve le jeton `LibHeader` qui apparaît en position de valeur.
Cela empêche le composant référencé d'être éliminé par le tree-shaking, même si l'application n'utilise en réalité `<lib-header>` nulle part.
Si le code, le template et les styles de `LibHeader` deviennent trop volumineux, l'inclure inutilement peut augmenter considérablement la taille de l'application cliente.

## Quand utiliser le pattern des jetons d'injection légers {#when-to-use-the-lightweight-injection-token-pattern}

Le problème de tree-shaking survient quand un composant est utilisé comme jeton d'injection.
Cela peut arriver dans deux cas :

- Le jeton est utilisé en position de valeur d'une [content query](guide/components/queries#content-queries).
- Le jeton est utilisé avec la fonction `inject`.

Dans l'exemple suivant, les deux utilisations du jeton `CustomOther` entraînent la conservation de `CustomOther`, ce qui l'empêche d'être éliminé par le tree-shaking quand il n'est pas utilisé :

```ts
{highlight: [[2],[4]]}
class App {
  private readonly other = inject(CustomOther, {optional: true});

readonly header = contentChild(CustomOther);
}
```

Si les jetons utilisés uniquement comme spécificateurs de type sont supprimés lors de la conversion en JavaScript, tous les jetons utilisés pour l'injection de dépendances sont nécessaires à l'exécution.
Quand vous utilisez `inject(CustomOther)`, `CustomOther` est passé en tant qu'argument valeur.
Le jeton est alors en position de valeur, ce qui amène le tree-shaker à conserver la référence.

HELPFUL: Les libraries doivent utiliser des [providers compatibles avec le tree-shaking](guide/di/defining-dependency-providers) pour tous leurs services, en fournissant les dépendances au niveau racine plutôt que dans des composants ou des modules.

## Utiliser des jetons d'injection légers {#using-lightweight-injection-tokens}

Le design pattern des jetons d'injection légers consiste à utiliser une petite classe abstraite comme jeton d'injection, puis à fournir l'implémentation réelle plus tard.
La classe abstraite est conservée, elle n'est pas éliminée par le tree-shaking, mais elle est petite et n'a pas d'impact notable sur la taille de l'application.

L'exemple suivant montre comment cela fonctionne pour `LibHeader` :

```ts
{highlight: [[1],[5], [15]]}
abstract class LibHeaderToken {}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeader}],
  …,
})
class LibHeader extends LibHeaderToken {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCard {
  readonly header = contentChild(LibHeaderToken);
}
```

Dans cet exemple, l'implémentation de `LibCard` ne fait plus référence à `LibHeader`, ni en position de type, ni en position de valeur.
Cela permet à `LibHeader` d'être entièrement éliminé par le tree-shaking.
`LibHeaderToken` est conservé, mais ce n'est qu'une déclaration de classe, sans implémentation concrète.
Il est petit et n'a pas d'impact notable sur la taille de l'application quand il est conservé après la compilation.

C'est `LibHeader` lui-même qui implémente la classe abstraite `LibHeaderToken`.
Vous pouvez utiliser ce jeton en toute sécurité comme provider dans la définition du composant, ce qui permet à Angular d'injecter correctement le type concret.

En résumé, le pattern des jetons d'injection légers se compose des éléments suivants :

1. Un jeton d'injection léger représenté par une classe abstraite.
2. Une définition de composant qui implémente la classe abstraite.
3. L'injection du pattern léger, avec `contentChild` ou `contentChildren`.
4. Un provider dans l'implémentation du jeton d'injection léger, qui associe le jeton d'injection léger à l'implémentation.

### Utiliser le jeton d'injection léger pour définir une API {#use-the-lightweight-injection-token-for-api-definition}

Un composant qui injecte un jeton d'injection léger peut avoir besoin d'appeler une méthode de la classe injectée.
Le jeton est désormais une classe abstraite. Comme le composant injectable implémente cette classe, vous devez aussi déclarer une méthode abstraite dans la classe abstraite du jeton d'injection léger.
L'implémentation de la méthode, avec tout le code qu'elle ajoute, réside dans le composant injectable, qui peut être éliminé par le tree-shaking.
Cela permet au parent de communiquer avec l'enfant, s'il est présent, de manière typée.

Par exemple, `LibCard` interroge désormais `LibHeaderToken` plutôt que `LibHeader`.
L'exemple suivant montre comment le pattern permet à `LibCard` de communiquer avec `LibHeader` sans jamais faire référence à `LibHeader` :

```ts
{highlight: [[2],[7],[11],[19]]}
abstract class LibHeaderToken {
  abstract doSomething(): void;
}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeader}],
})
class LibHeader extends LibHeaderToken {
  doSomething(): void {
    // Concrete implementation of `doSomething`
  }
}

@Component({
  selector: 'lib-card',
})
class LibCard implements AfterContentInit {
  readonly header = contentChild(LibHeaderToken);

ngAfterContentInit(): void {
    if (this.header() !== undefined) {
      this.header()!.doSomething();
    }
  }
}
```

Dans cet exemple, le parent interroge le jeton pour obtenir le composant enfant et stocke la référence du composant obtenu s'il est présent.
Avant d'appeler une méthode de l'enfant, le composant parent vérifie que le composant enfant est présent.
Si le composant enfant a été éliminé par le tree-shaking, il n'existe aucune référence à celui-ci à l'exécution, ni aucun appel à sa méthode.

### Nommer votre jeton d'injection léger {#naming-your-lightweight-injection-token}

Les jetons d'injection légers ne sont utiles qu'avec des composants.
Le [guide de style Angular](style-guide) recommande de nommer les composants sans le suffixe `Component`.
L'exemple `LibHeader` suit cette convention.

Vous devez conserver le lien entre le composant et son jeton tout en les distinguant.
Le style recommandé consiste à utiliser le nom de base du composant suivi du suffixe `Token` pour nommer vos jetons d'injection légers : `LibHeaderToken`.
# Interopérabilité RxJS avec les signals Angular

Le package `@angular/core/rxjs-interop` propose des API qui vous aident à intégrer RxJS et les signals Angular.

## Créer un signal à partir d'un observable RxJS avec `toSignal` {#create-a-signal-from-an-rxjs-observable-with-tosignal}

Utilisez la fonction `toSignal` pour créer un signal qui suit la valeur d'un observable. Elle se comporte de manière similaire au pipe `async` dans les templates, mais elle est plus flexible et peut être utilisée n'importe où dans une application.

```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);

// Get a `Signal` representing the `counterObservable`'s value.
  counter = toSignal(this.counterObservable, {initialValue: 0});
}
```

Comme le pipe `async`, `toSignal` s'abonne immédiatement à l'observable, ce qui peut déclencher des effets de bord. L'abonnement créé par `toSignal` se désabonne automatiquement de l'observable donné lorsque le composant ou le service qui appelle `toSignal` est détruit.

IMPORTANT: `toSignal` crée un abonnement. Évitez de l'appeler plusieurs fois pour le même observable, et réutilisez plutôt le signal qu'il renvoie.

### Contexte d'injection {#injection-context}

Par défaut, `toSignal` doit s'exécuter dans un [contexte d'injection](guide/di/dependency-injection-context), par exemple pendant la construction d'un composant ou d'un service. Si aucun contexte d'injection n'est disponible, vous pouvez spécifier manuellement l'`Injector` à utiliser à la place.

### Valeurs initiales {#initial-values}

Les observables ne produisent pas forcément de valeur de manière synchrone lors de l'abonnement, mais les signals exigent toujours une valeur courante. Il existe plusieurs façons de gérer cette valeur « initiale » des signals créés par `toSignal`.

#### L'option `initialValue` {#the-initialvalue-option}

Comme dans l'exemple ci-dessus, vous pouvez spécifier une option `initialValue` avec la valeur que le signal doit renvoyer avant la première émission de l'observable.

#### Valeurs initiales `undefined` {#undefined-initial-values}

Si vous ne fournissez pas d'`initialValue`, le signal obtenu renvoie `undefined` jusqu'à ce que l'observable émette. Ce comportement est similaire à celui du pipe `async`, qui renvoie `null`.

#### L'option `requireSync` {#the-requiresync-option}

Certains observables émettent de manière synchrone de façon garantie, comme `BehaviorSubject`. Dans ce cas, vous pouvez spécifier l'option `requireSync: true`.

Lorsque `requireSync` vaut `true`, `toSignal` impose que l'observable émette de manière synchrone lors de l'abonnement. Cela garantit que le signal a toujours une valeur, et qu'aucun type `undefined` ni valeur initiale n'est nécessaire.

### `manualCleanup` {#manualcleanup}

Par défaut, `toSignal` se désabonne automatiquement de l'observable lorsque le composant ou le service qui le crée est détruit.

Pour modifier ce comportement, vous pouvez passer l'option `manualCleanup`. Vous pouvez utiliser ce paramètre pour les observables qui se terminent naturellement d'eux-mêmes.

#### Comparaison d'égalité personnalisée {#custom-equality-comparison}

Certains observables peuvent émettre des valeurs **égales** bien qu'elles diffèrent par leur référence ou par un détail mineur. L'option `equal` vous permet de définir une **fonction d'égalité personnalisée** pour déterminer quand deux valeurs consécutives doivent être considérées comme identiques.

Lorsque deux valeurs émises sont considérées comme égales, le signal obtenu **n'est pas mis à jour**. Cela évite les calculs redondants, les mises à jour du DOM ou la réexécution inutile des effects.

```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, or 22 randomly
  );

// Only update if the temperature changes
  temperature = toSignal(this.temperature$, {
    initialValue: {temperature: 20},
    equal: (prev, curr) => prev.temperature === curr.temperature,
  });
}
```

### Erreur et complétion {#error-and-completion}

Si un observable utilisé dans `toSignal` produit une erreur, cette erreur est levée lors de la lecture du signal.

Si un observable utilisé dans `toSignal` se termine, le signal continue de renvoyer la dernière valeur émise avant la complétion.

## Créer un observable RxJS à partir d'un signal avec `toObservable` {#create-an-rxjs-observable-from-a-signal-with-toobservable}

Utilisez l'utilitaire `toObservable` pour créer un `Observable` qui suit la valeur d'un signal. La valeur du signal est surveillée par un `effect` qui émet la valeur vers l'observable lorsqu'elle change.

```ts
import {Component, signal, Signal, inject} from '@angular/core';
import {toObservable} from '@angular/core/rxjs-interop';
import {switchMap} from 'rxjs';

@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)));
}
```

Lorsque le signal `query` change, l'observable `query$` émet la dernière recherche et déclenche une nouvelle requête HTTP.

### Contexte d'injection {#injection-context-to-observable}

Par défaut, `toObservable` doit s'exécuter dans un [contexte d'injection](guide/di/dependency-injection-context), par exemple pendant la construction d'un composant ou d'un service. Si aucun contexte d'injection n'est disponible, vous pouvez spécifier manuellement l'`Injector` à utiliser à la place.

### Timing de `toObservable` {#timing-of-toobservable}

`toObservable` utilise un effect pour suivre la valeur du signal dans un `ReplaySubject`. Lors de l'abonnement, la première valeur (si elle est disponible) peut être émise de manière synchrone, et toutes les valeurs suivantes seront asynchrones.

Contrairement aux observables, les signals ne fournissent jamais de notification synchrone des changements. Même si vous mettez à jour la valeur d'un signal plusieurs fois, `toObservable` n'émettra la valeur qu'une fois le signal stabilisé.

```ts
const obs$ = toObservable(mySignal);
obs$.subscribe((value) => console.log(value));

mySignal.set(1);
mySignal.set(2);
mySignal.set(3);
```

Ici, seule la dernière valeur (3) sera affichée dans la console.

## Utiliser `rxResource` pour les données asynchrones {#using-rxresource-for-async-data}

La [fonction `resource`](/guide/signals/resource) d'Angular vous permet d'intégrer des données asynchrones dans le code de votre application basé sur les signals. En s'appuyant sur ce pattern, `rxResource` vous permet de définir une resource dont la source de données est définie sous la forme d'un `Observable` RxJS. Au lieu d'accepter une fonction `loader`, `rxResource` accepte une fonction `stream` qui renvoie un `Observable` RxJS.

```typescript
import {Component, inject, input} from '@angular/core';
import {rxResource} from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class UserProfile {
  // This component relies on a service that exposes data through an RxJS Observable.
  private userData = inject(MyUserDataClient);

protected userId = input<string>();

private userResource = rxResource({
    params: () => ({userId: this.userId()}),

// The `stream` property expects a factory function that returns
    // a data stream as an RxJS Observable.
    stream: ({params}) => this.userData.load(params.userId),
  });
}
```

La propriété `stream` accepte une fonction de fabrique pour un `Observable` RxJS. Cette fonction de fabrique reçoit la valeur `params` de la resource et renvoie un `Observable`. La resource appelle cette fonction de fabrique chaque fois que le calcul de `params` produit une nouvelle valeur. Consultez [Loaders de resources](/guide/signals/resource#resource-loaders) pour plus de détails sur les paramètres transmis à la fonction de fabrique.

Pour tout le reste, `rxResource` se comporte comme `resource` et fournit les mêmes API pour spécifier des paramètres, lire des valeurs, vérifier l'état de chargement et examiner les erreurs.

L'`Observable` renvoyé par `stream` doit toujours émettre une valeur ou une erreur avant de se terminer ; consultez [`NG0991`](/errors/NG0991) pour savoir ce qui se passe dans le cas contraire et comment l'éviter.
# Interopérabilité RxJS avec les outputs de composants et de directives

TIP: Ce guide suppose que vous connaissez les [outputs de composants et de directives](guide/components/outputs).

Le package `@angular/core/rxjs-interop` propose deux API liées aux outputs de composants et de directives.

## Créer un output à partir d'un observable RxJS {#creating-an-output-based-on-an-rxjs-observable}

La fonction `outputFromObservable` vous permet de créer un output de composant ou de directive qui émet en fonction d'un observable RxJS :

```ts
{highlight:[9]}
import {Directive} from '@angular/core';
import {outputFromObservable} from '@angular/core/rxjs-interop';
import {Observable} from 'rxjs';

@Directive(/* ... */)
class Draggable {
  pointerMoves$: Observable<PointerMovements> = listenToPointerMoves();

// Whenever `pointerMoves$` emits, the `pointerMove` event fires.
  pointerMove = outputFromObservable(this.pointerMoves$);
}
```

La fonction `outputFromObservable` a une signification particulière pour le compilateur Angular. **Vous ne pouvez appeler `outputFromObservable` que dans les initialiseurs de propriétés de composants et de directives.**

Lorsque vous vous abonnez (`subscribe`) à l'output, Angular transmet automatiquement l'abonnement à l'observable sous-jacent. Angular cesse de transmettre les valeurs lorsque le composant ou la directive est détruit.

HELPFUL: Envisagez d'utiliser directement `output()` si vous pouvez émettre les valeurs de manière impérative.

## Créer un observable RxJS à partir d'un output de composant ou de directive {#creating-an-rxjs-observable-from-a-component-or-directive-output}

La fonction `outputToObservable` vous permet de créer un observable RxJS à partir d'un output de composant.

```ts
{highlight:[11]}
import {outputToObservable} from '@angular/core/rxjs-interop';
import {Component, output} from '@angular/core';

@Component(/*...*/)
class CustomSlider {
    valueChange = output<number>();
}

// Instance reference to `CustomSlider`.
const slider: CustomSlider = createSlider();

outputToObservable(slider.valueChange) // Observable<number>
    .pipe(...)
    .subscribe(...);
```

HELPFUL: Envisagez d'utiliser directement la méthode `subscribe` de `OutputRef` si elle répond à vos besoins.
# Configurer `HttpClient`

`HttpClient` est disponible par défaut pour l'injection à partir d'Angular v21.

## Fournir `HttpClient` via l'injection de dépendances {#providing-httpclient-through-dependency-injection}

Vous pouvez utiliser la fonction utilitaire `provideHttpClient` pour configurer l'ensemble de fonctionnalités HTTP par défaut ou ajouter des fonctionnalités dans les `providers` de l'application, dans `app.config.ts`.

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
};
```

Si votre application utilise plutôt un bootstrap basé sur les NgModules, vous pouvez inclure `provideHttpClient` dans les providers du NgModule de votre application pour configurer l'ensemble de fonctionnalités HTTP par défaut ou ajouter des fonctionnalités :

```ts
@NgModule({
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
  // ... other application configuration
})
export class AppModule {}
```

Vous pouvez ensuite injecter le service `HttpClient` en tant que dépendance de vos composants, services ou autres classes :

```ts
@Service()
export class ConfigService {
  private http = inject(HttpClient);
  // This service can now make HTTP requests via `this.http`.
}
```

## Configurer les fonctionnalités de `HttpClient` {#configuring-features-of-httpclient}

`provideHttpClient` accepte une liste de configurations de fonctionnalités optionnelles pour activer ou configurer différents aspects du client. Cette section détaille ces fonctionnalités optionnelles et leur utilisation.

### `withXhr` {#withxhr}

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withXhr())],
};
```

Par défaut, `HttpClient` utilise l'API [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) pour effectuer les requêtes. La fonctionnalité `withXhr` fait plutôt utiliser au client l'API [`XMLHttpRequest`](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest).

`fetch` est une API plus moderne, disponible dans quelques environnements où `XMLHttpRequest` n'est pas pris en charge. Elle présente toutefois quelques limitations, comme l'absence d'événements de progression pour l'envoi (upload).
La prise en charge de XHR côté serveur est **dépréciée** et doit être supprimée dans Angular 23. La library `xhr2` sous-jacente ne gère pas les redirections de manière sûre : elle peut transmettre les en-têtes `Authorization` lors de redirections cross-origin et est exposée à des dénis de service (DoS) via des boucles de redirection. Pour les applications SSR, utilisez plutôt le backend `fetch` par défaut.
### `withInterceptors(...)` {#withinterceptors}

`withInterceptors` configure l'ensemble des fonctions intercepteurs qui traiteront les requêtes effectuées via `HttpClient`. Consultez le [guide des intercepteurs](guide/http/interceptors) pour plus d'informations.

### `withInterceptorsFromDi()` {#withinterceptorsfromdi}

`withInterceptorsFromDi` inclut l'ancien style d'intercepteurs à base de classes dans la configuration de `HttpClient`. Consultez le [guide des intercepteurs](guide/http/interceptors) pour plus d'informations.

HELPFUL: Les intercepteurs fonctionnels (via `withInterceptors`) ont un ordre d'exécution plus prévisible et nous les recommandons plutôt que les intercepteurs basés sur la DI.

### `withRequestsMadeViaParent()` {#withrequestsmadeviaparent}

Par défaut, lorsque vous configurez `HttpClient` avec `provideHttpClient` dans un injector donné, cette configuration remplace toute configuration de `HttpClient` éventuellement présente dans l'injector parent.

Lorsque vous ajoutez `withRequestsMadeViaParent()`, `HttpClient` est au contraire configuré pour transmettre les requêtes à l'instance de `HttpClient` de l'injector parent, une fois qu'elles sont passées par les intercepteurs configurés à ce niveau. C'est utile si vous voulez _ajouter_ des intercepteurs dans un injector enfant tout en faisant passer la requête par les intercepteurs de l'injector parent.

CRITICAL: Vous devez configurer une instance de `HttpClient` au-dessus de l'injector courant ; sinon, cette option n'est pas valide et vous obtiendrez une erreur à l'exécution en essayant de l'utiliser.

### `withJsonpSupport()` {#withjsonpsupport}
`withJsonpSupport`, `HttpClientJsonpModule` et la méthode `.jsonp()` de `HttpClient` sont dépréciés, car JSONP peut provoquer des vulnérabilités de cross-site scripting (XSS). Utilisez plutôt des requêtes HTTP standard avec [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS).
Inclure `withJsonpSupport` active la méthode `.jsonp()` de `HttpClient`, qui effectue une requête GET via la [convention JSONP](https://en.wikipedia.org/wiki/JSONP) pour charger des données entre domaines.

HELPFUL: Préférez utiliser [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) plutôt que JSONP pour effectuer des requêtes entre domaines lorsque c'est possible.

### `withXsrfConfiguration(...)` {#withxsrfconfiguration}

Inclure cette option permet de personnaliser la fonctionnalité de sécurité XSRF intégrée à `HttpClient`. Consultez le [guide de sécurité](best-practices/security) pour plus d'informations.

### `withNoXsrfProtection()` {#withnoxsrfprotection}

Inclure cette option désactive la fonctionnalité de sécurité XSRF intégrée à `HttpClient`. Consultez le [guide de sécurité](best-practices/security) pour plus d'informations.

## Configuration basée sur `HttpClientModule` {#httpclientmodule-based-configuration}

Certaines applications configurent `HttpClient` avec l'ancienne API basée sur les NgModules.

Ce tableau liste les NgModules disponibles dans `@angular/common/http` et leur correspondance avec les fonctions de configuration de provider ci-dessus.

| **NgModule**                            | Équivalent `provideHttpClient()`                         |
| --------------------------------------- | -------------------------------------------------------- |
| `HttpClientModule`                      | `provideHttpClient(withInterceptorsFromDi(), withXhr())` |
| `HttpClientJsonpModule` (déprécié)      | `withJsonpSupport()` (déprécié)                          |
| `HttpClientXsrfModule.withOptions(...)` | `withXsrfConfiguration(...)`                             |
| `HttpClientXsrfModule.disable()`        | `withNoXsrfProtection()`                                 |

NOTE: `HttpClientModule` et `HttpClientXsrfModule` sont également dépréciés. Utilisez plutôt `provideHttpClient` avec les fonctionnalités correspondantes.
Lorsque `HttpClientModule` est présent dans plusieurs injectors, le comportement des intercepteurs est mal défini et dépend des options exactes et de l'ordre des providers et des imports.

Préférez `provideHttpClient` pour les configurations à plusieurs injectors, car son comportement est plus stable. Consultez la fonctionnalité `withRequestsMadeViaParent` ci-dessus.

# Effectuer des requêtes HTTP

`HttpClient` dispose de méthodes correspondant aux différents verbes HTTP utilisés pour effectuer des requêtes, aussi bien pour charger des données que pour appliquer des mutations sur le serveur. Chaque méthode renvoie un [`Observable` RxJS](https://rxjs.dev/guide/observable) qui, lorsqu'on s'y abonne, envoie la requête puis émet les résultats quand le serveur répond.

NOTE: Les `Observable`s créés par `HttpClient` peuvent faire l'objet d'un nombre quelconque d'abonnements et effectuent une nouvelle requête au backend pour chaque abonnement.

Un objet d'options passé à la méthode de requête permet d'ajuster diverses propriétés de la requête ainsi que le type de réponse renvoyé.

## Récupérer des données JSON {#fetching-json-data}

Récupérer des données depuis un backend nécessite souvent d'effectuer une requête GET avec la méthode [`HttpClient.get()`](api/common/http/HttpClient#get). Cette méthode prend deux arguments : l'URL de l'endpoint (une chaîne) depuis lequel récupérer les données, et un objet d'_options facultatif_ pour configurer la requête.

Par exemple, pour récupérer des données de configuration depuis une API hypothétique avec la méthode `HttpClient.get()` :

```ts
http.get<Config>('/api/config').subscribe((config) => {
  // process the configuration.
});
```

Remarquez l'argument de type générique, qui indique que les données renvoyées par le serveur seront de type `Config`. Cet argument est facultatif ; si vous l'omettez, les données renvoyées seront de type `Object`.

TIP: Lorsque vous manipulez des données de structure incertaine, susceptibles de contenir des valeurs `undefined` ou `null`, envisagez d'utiliser le type `unknown` plutôt que `Object` comme type de réponse.

CRITICAL: Le type générique des méthodes de requête est une **assertion** de type sur les données renvoyées par le serveur. `HttpClient` ne vérifie pas que les données réellement renvoyées correspondent à ce type.

## Récupérer d'autres types de données {#fetching-other-types-of-data}

Par défaut, `HttpClient` suppose que les serveurs renvoient des données JSON. Lorsque vous interagissez avec une API non JSON, vous pouvez indiquer à `HttpClient` le type de réponse attendu au moment d'effectuer la requête. Cela se fait avec l'option `responseType`.

| **Valeur de `responseType`** | **Type de réponse renvoyé**                                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `'json'` (par défaut)       | Données JSON du type générique donné                                                                                                       |
| `'text'`                 | Données de type chaîne                                                                                                                               |
| `'arraybuffer'`          | [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) contenant les octets bruts de la réponse |
| `'blob'`                 | Instance de [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                        |

Par exemple, vous pouvez demander à `HttpClient` de télécharger les octets bruts d'une image `.jpeg` dans un `ArrayBuffer` :

```ts
http.get('/images/dog.jpg', {responseType: 'arraybuffer'}).subscribe((buffer) => {
  console.log('The image is ' + buffer.byteLength + ' bytes large');
});
```
Comme la valeur de `responseType` influe sur le type renvoyé par `HttpClient`, elle doit avoir un type littéral et non un type `string`.

C'est automatiquement le cas si l'objet d'options passé à la méthode de requête est un objet littéral, mais si vous extrayez les options de la requête dans une variable ou une méthode utilitaire, vous devrez peut-être le spécifier explicitement comme littéral, par exemple `responseType: 'text' as const`.
## Modifier l'état du serveur {#mutating-server-state}

Les API serveur qui effectuent des mutations nécessitent souvent des requêtes POST avec un corps de requête qui spécifie le nouvel état ou la modification à apporter.

La méthode [`HttpClient.post()`](api/common/http/HttpClient#post) se comporte de manière similaire à `get()` et accepte un argument `body` supplémentaire avant ses options :

```ts
http.post<Config>('/api/config', newConfig).subscribe((config) => {
  console.log('Updated config:', config);
});
```

De nombreux types de valeurs différents peuvent être fournis comme `body` de la requête, et `HttpClient` les sérialise en conséquence :

| **Type de `body`**                                                                                                               | **Sérialisé en**                                    |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| chaîne                                                                                                                        | Texte brut                                           |
| nombre, booléen, tableau ou objet simple                                                                                       | JSON                                                 |
| [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                       | données brutes du buffer                             |
| [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                     | données brutes avec le type de contenu du `Blob`              |
| [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData)                                                             | données encodées en `multipart/form-data`                   |
| [`HttpParams`](api/common/http/HttpParams) ou [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | chaîne au format `application/x-www-form-urlencoded` |

IMPORTANT: N'oubliez pas d'appeler `.subscribe()` sur les `Observable`s des requêtes de mutation pour que la requête soit réellement envoyée.

## Définir les paramètres d'URL {#setting-url-parameters}

Spécifiez les paramètres de requête à inclure dans l'URL de la requête avec l'option `params`.

Passer un objet littéral est la façon la plus simple de configurer les paramètres d'URL :

```ts
http
  .get('/api/config', {
    params: {filter: 'all'},
  })
  .subscribe((config) => {
    // ...
  });
```

Vous pouvez aussi passer une instance de `HttpParams` si vous avez besoin de plus de contrôle sur la construction ou la sérialisation des paramètres.

IMPORTANT: Les instances de `HttpParams` sont _immuables_ et ne peuvent pas être modifiées directement. Les méthodes de mutation comme `append()` renvoient plutôt une nouvelle instance de `HttpParams` à laquelle la mutation est appliquée.

```ts
const baseParams = new HttpParams().set('filter', 'all');

http
  .get('/api/config', {
    params: baseParams.set('details', 'enabled'),
  })
  .subscribe((config) => {
    // ...
  });
```

Vous pouvez instancier `HttpParams` avec un `HttpParameterCodec` personnalisé qui détermine comment `HttpClient` encode les paramètres dans l'URL.

### Encodage personnalisé des paramètres {#custom-parameter-encoding}

Par défaut, `HttpParams` utilise le [`HttpUrlEncodingCodec`](api/common/http/HttpUrlEncodingCodec) intégré pour encoder et décoder les clés et les valeurs des paramètres.

Vous pouvez fournir votre propre implémentation de [`HttpParameterCodec`](api/common/http/HttpParameterCodec) pour personnaliser la façon dont l'encodage et le décodage sont appliqués.

```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});
  }
}
```

## Définir les en-têtes de requête {#setting-request-headers}

Spécifiez les en-têtes de requête à inclure dans la requête avec l'option `headers`.

Passer un objet littéral est la façon la plus simple de configurer les en-têtes de requête :

```ts
http
  .get('/api/config', {
    headers: {
      'X-Debug-Level': 'verbose',
    },
  })
  .subscribe((config) => {
    // ...
  });
```

Vous pouvez aussi passer une instance de `HttpHeaders` si vous avez besoin de plus de contrôle sur la construction des en-têtes.

IMPORTANT: Les instances de `HttpHeaders` sont _immuables_ et ne peuvent pas être modifiées directement. Les méthodes de mutation comme `append()` renvoient plutôt une nouvelle instance de `HttpHeaders` à laquelle la mutation est appliquée.

```ts
const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http
  .get<Config>('/api/config', {
    headers: baseHeaders.set('X-Debug-Level', 'verbose'),
  })
  .subscribe((config) => {
    // ...
  });
```

## Interagir avec les événements de réponse du serveur {#interacting-with-the-server-response-events}

Par commodité, `HttpClient` renvoie par défaut un `Observable` des données renvoyées par le serveur (le corps de la réponse). Il est parfois souhaitable d'examiner la réponse elle-même, par exemple pour récupérer certains en-têtes de réponse.

Pour accéder à la réponse complète, définissez l'option `observe` à `'response'` :

```ts
http.get<Config>('/api/config', {observe: 'response'}).subscribe((res) => {
  console.log('Response status:', res.status);
  console.log('Body:', res.body);
});
```
Comme la valeur de `observe` influe sur le type renvoyé par `HttpClient`, elle doit avoir un type littéral et non un type `string`.

C'est automatiquement le cas si l'objet d'options passé à la méthode de requête est un objet littéral, mais si vous extrayez les options de la requête dans une variable ou une méthode utilitaire, vous devrez peut-être le spécifier explicitement comme littéral, par exemple `observe: 'response' as const`.
## Recevoir les événements de progression bruts {#receiving-raw-progress-events}

En plus du corps ou de l'objet de la réponse, `HttpClient` peut aussi renvoyer un flux d'_événements_ bruts correspondant à des moments précis du cycle de vie de la requête. Ces événements indiquent notamment quand la requête est envoyée, quand l'en-tête de la réponse est renvoyé et quand le corps est complet. Ils peuvent aussi inclure des _événements de progression_ qui rendent compte de l'état de l'envoi et du téléchargement pour les corps de requête ou de réponse volumineux.

Les événements de progression sont désactivés par défaut (car ils ont un coût en performances), mais peuvent être activés avec les options `reportUploadProgress` et `reportDownloadProgress`.

NOTE: Le backend fetch par défaut de `HttpClient` ne prend pas en charge les événements de progression d'_envoi_ (upload) et lève une erreur si vous définissez `reportUploadProgress`. Si votre application a besoin des événements de progression d'envoi, configurez `HttpClient` avec `withXhr()` dans `provideHttpClient(...)`.

Pour observer le flux d'événements, définissez l'option `observe` à `'events'` :

```ts
http
  .get('/api/download', {
    reportDownloadProgress: true,
    observe: 'events',
  })
  .subscribe((event) => {
    switch (event.type) {
      case HttpEventType.DownloadProgress:
        console.log('Downloaded ' + event.loaded + ' out of ' + event.total + ' bytes');
        break;
      case HttpEventType.Response:
        console.log('Finished downloading!');
        break;
    }
  });
```
Comme la valeur de `observe` influe sur le type renvoyé par `HttpClient`, elle doit avoir un type littéral et non un type `string`.

C'est automatiquement le cas si l'objet d'options passé à la méthode de requête est un objet littéral, mais si vous extrayez les options de la requête dans une variable ou une méthode utilitaire, vous devrez peut-être le spécifier explicitement comme littéral, par exemple `observe: 'events' as const`.
Chaque `HttpEvent` émis dans le flux d'événements possède un `type` qui indique ce que l'événement représente :

| **Valeur de `type`**                 | **Signification de l'événement**                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `HttpEventType.Sent`             | La requête a été envoyée au serveur                                      |
| `HttpEventType.UploadProgress`   | Un `HttpUploadProgressEvent` qui rend compte de la progression de l'envoi du corps de la requête      |
| `HttpEventType.ResponseHeader`   | L'en-tête de la réponse a été reçu, y compris le statut et les en-têtes           |
| `HttpEventType.DownloadProgress` | Un `HttpDownloadProgressEvent` qui rend compte de la progression du téléchargement du corps de la réponse |
| `HttpEventType.Response`         | La réponse complète a été reçue, y compris son corps                 |
| `HttpEventType.User`             | Un événement personnalisé provenant d'un intercepteur HTTP.                                           |

## Gérer l'échec d'une requête {#handling-request-failure}

Une requête HTTP peut échouer de trois façons :

- Une erreur réseau ou de connexion peut empêcher la requête d'atteindre le serveur backend.
- Une requête n'a pas répondu à temps alors que l'option de timeout était définie.
- Le backend peut recevoir la requête mais échouer à la traiter, et renvoyer une réponse d'erreur.

`HttpClient` capture tous ces types d'erreurs dans une `HttpErrorResponse` qu'il renvoie via le canal d'erreur de l'`Observable`. Les erreurs réseau et de timeout ont un code de `status` égal à `0`. Pour les timeouts, `error` est une `DOMException` nommée `TimeoutError` ; pour les erreurs réseau, c'est l'erreur levée par `fetch` (ou un [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent) avec `withXhr()`). Les erreurs du backend ont le code de `status` d'échec renvoyé par le backend, et la réponse d'erreur comme `error`. Inspectez la réponse pour identifier la cause de l'erreur et l'action appropriée pour la gérer.

La [library RxJS](https://rxjs.dev/) propose plusieurs opérateurs qui peuvent être utiles pour la gestion des erreurs.

Vous pouvez utiliser l'opérateur `catchError` pour transformer une réponse d'erreur en une valeur pour l'interface. Cette valeur peut indiquer à l'interface d'afficher une page ou une valeur d'erreur, et capturer la cause de l'erreur si nécessaire.

Des erreurs passagères, comme des interruptions réseau, peuvent parfois faire échouer une requête de manière inattendue ; il suffit alors de relancer la requête pour qu'elle réussisse. RxJS fournit plusieurs opérateurs de _retry_ qui se réabonnent automatiquement à un `Observable` en échec sous certaines conditions. Par exemple, l'opérateur `retry()` tente automatiquement de se réabonner un nombre de fois donné.

### Timeouts {#timeouts}

Pour définir un timeout sur une requête, vous pouvez définir l'option `timeout` à un nombre de millisecondes, avec les autres options de la requête. Si la requête au backend ne se termine pas dans le délai spécifié, elle est annulée et une erreur est émise.

NOTE: Le timeout ne s'applique qu'à la requête HTTP au backend elle-même. Ce n'est pas un timeout pour toute la chaîne de traitement de la requête. Cette option n'est donc pas affectée par les délais introduits par les intercepteurs.

```ts
http
  .get('/api/config', {
    timeout: 3000,
  })
  .subscribe({
    next: (config) => {
      console.log('Config fetched successfully:', config);
    },
    error: (err) => {
      // If the request times out, an error will have been emitted.
    },
  });
```

## Options fetch avancées {#advanced-fetch-options}

Le `HttpClient` d'Angular prend en charge des options avancées de l'API fetch qui peuvent améliorer les performances et l'expérience utilisateur. Ces options sont disponibles avec le backend fetch, qui est celui par défaut.

### Options fetch {#fetch-options}

Les options suivantes offrent un contrôle fin du comportement des requêtes avec le backend fetch.

#### Connexions keep-alive {#keep-alive-connections}

L'option `keepalive` permet à une requête de survivre à la page qui l'a initiée. C'est particulièrement utile pour les requêtes d'analytics ou de journalisation qui doivent aboutir même si l'utilisateur quitte la page.

```ts
http
  .post('/api/analytics', analyticsData, {
    keepalive: true,
  })
  .subscribe();
```

#### Contrôle de la mise en cache HTTP {#http-caching-control}

L'option `cache` contrôle la façon dont la requête interagit avec le cache HTTP du navigateur, ce qui peut améliorer sensiblement les performances des requêtes répétées.

```ts
//  Use cached response regardless of freshness
http
  .get('/api/config', {
    cache: 'force-cache',
  })
  .subscribe((config) => {
    // ...
  });

// Always fetch from network, bypass cache
http
  .get('/api/live-data', {
    cache: 'no-cache',
  })
  .subscribe((data) => {
    // ...
  });

// Use cached response only, fail if not in cache
http
  .get('/api/static-data', {
    cache: 'only-if-cached',
  })
  .subscribe((data) => {
    // ...
  });
```

#### Priorité des requêtes pour les Core Web Vitals {#request-priority-for-core-web-vitals}

L'option `priority` vous permet d'indiquer l'importance relative d'une requête, ce qui aide les navigateurs à optimiser le chargement des ressources pour de meilleurs scores Core Web Vitals.

```ts
// High priority for critical resources
http
  .get('/api/user-profile', {
    priority: 'high',
  })
  .subscribe((profile) => {
    // ...
  });

// Low priority for non-critical resources
http
  .get('/api/recommendations', {
    priority: 'low',
  })
  .subscribe((recommendations) => {
    // ...
  });

// Auto priority (default) lets the browser decide
http
  .get('/api/settings', {
    priority: 'auto',
  })
  .subscribe((settings) => {
    // ...
  });
```

Valeurs de `priority` disponibles :

- `'high'` : priorité haute, chargée tôt (par exemple, données utilisateur critiques, contenu au-dessus de la ligne de flottaison)
- `'low'` : priorité basse, chargée quand les ressources sont disponibles (par exemple, analytics, données préchargées)
- `'auto'` : le navigateur détermine la priorité selon le contexte de la requête (par défaut)

TIP: Utilisez `priority: 'high'` pour les requêtes qui affectent le Largest Contentful Paint (LCP) et `priority: 'low'` pour celles qui n'ont pas d'impact sur l'expérience utilisateur initiale.

#### Mode de requête {#request-mode}

L'option `mode` contrôle la façon dont la requête gère les requêtes cross-origin et détermine le type de réponse.

```ts
// Same-origin requests only
http
  .get('/api/local-data', {
    mode: 'same-origin',
  })
  .subscribe((data) => {
    // ...
  });

// CORS-enabled cross-origin requests
http
  .get('https://api.external.com/data', {
    mode: 'cors',
  })
  .subscribe((data) => {
    // ...
  });

// No-CORS mode for simple cross-origin requests
http
  .get('https://external-api.com/public-data', {
    mode: 'no-cors',
  })
  .subscribe((data) => {
    // ...
  });
```

Valeurs de `mode` disponibles :

- `'same-origin'` : n'autorise que les requêtes same-origin, échoue pour les requêtes cross-origin
- `'cors'` : autorise les requêtes cross-origin avec CORS (par défaut)
- `'no-cors'` : autorise les requêtes cross-origin simples sans CORS ; la réponse est opaque

TIP: Dans le navigateur, utilisez `mode: 'same-origin'` pour les requêtes sensibles qui ne doivent jamais partir en cross-origin.

IMPORTANT: Pendant le SSR sur Node.js, `HttpClient` utilise l'[implémentation de Fetch de Node.js basée sur Undici](https://nodejs.org/api/globals.html#fetch). [Undici n'applique pas les vérifications CORS des navigateurs](https://undici.nodejs.org/#cors) : `mode: 'same-origin'` ne restreint donc pas les requêtes côté serveur. Validez les URL influencées par l'utilisateur à l'aide d'une liste d'autorisation.

#### Gestion des redirections {#redirect-handling}

L'option `redirect` indique comment gérer les réponses de redirection du serveur.

```ts
// Follow redirects automatically (default behavior)
http
  .get('/api/resource', {
    redirect: 'follow',
  })
  .subscribe((data) => {
    // ...
  });

// Prevent automatic redirects
http
  .get('/api/resource', {
    redirect: 'manual',
  })
  .subscribe((response) => {
    // Handle redirect manually
  });

// Treat redirects as errors
http
  .get('/api/resource', {
    redirect: 'error',
  })
  .subscribe({
    next: (data) => {
      // Success response
    },
    error: (err) => {
      // Redirect responses will trigger this error handler
    },
  });
```

Valeurs de `redirect` disponibles :

- `'follow'` : suit automatiquement les redirections (par défaut)
- `'error'` : traite les redirections comme des erreurs
- `'manual'` : ne suit pas automatiquement les redirections et renvoie la réponse de redirection

TIP: Utilisez `redirect: 'manual'` lorsque vous devez gérer les redirections avec une logique personnalisée.

#### Gestion des identifiants {#credentials-handling}

L'option `credentials` contrôle si les cookies, les en-têtes d'autorisation et les autres identifiants sont envoyés avec les requêtes cross-origin. C'est particulièrement important dans les scénarios d'authentification.

```ts
// Include credentials for cross-origin requests
http
  .get('https://api.example.com/protected-data', {
    credentials: 'include',
  })
  .subscribe((data) => {
    // ...
  });

// Never send credentials (default for cross-origin)
http
  .get('https://api.example.com/public-data', {
    credentials: 'omit',
  })
  .subscribe((data) => {
    // ...
  });

// Send credentials only for same-origin requests
http
  .get('/api/user-data', {
    credentials: 'same-origin',
  })
  .subscribe((data) => {
    // ...
  });

// withCredentials overrides credentials setting
http
  .get('https://api.example.com/data', {
    credentials: 'omit', // This will be ignored
    withCredentials: true, // This forces credentials: 'include'
  })
  .subscribe((data) => {
    // Request will include credentials despite credentials: 'omit'
  });

// Legacy approach (still supported)
http
  .get('https://api.example.com/data', {
    withCredentials: true,
  })
  .subscribe((data) => {
    // Equivalent to credentials: 'include'
  });
```

IMPORTANT: L'option `withCredentials` a la priorité sur l'option `credentials`. Si les deux sont spécifiées, `withCredentials: true` produit toujours `credentials: 'include'`, quelle que soit la valeur explicite de `credentials`.

Valeurs de `credentials` disponibles :

- `'omit'` : n'envoie jamais d'identifiants
- `'same-origin'` : n'envoie les identifiants que pour les requêtes same-origin (par défaut)
- `'include'` : envoie toujours les identifiants, même pour les requêtes cross-origin

TIP: Utilisez `credentials: 'include'` lorsque vous devez envoyer des cookies ou des en-têtes d'authentification à un autre domaine qui prend en charge CORS. Évitez de mélanger les options `credentials` et `withCredentials` pour ne pas créer de confusion.

IMPORTANT: Pendant le SSR sur Node.js, `credentials: 'include'` ne transmet pas automatiquement les cookies de la requête entrante du navigateur. L'option `credentials` ne supprime pas les en-têtes `Cookie` ou `Authorization` que vous ajoutez explicitement. [Undici autorise certains en-têtes que les navigateurs interdisent](https://undici.nodejs.org/#forbidden-and-safelisted-header-names) : ne transmettez donc les en-têtes d'identifiants qu'à des origines de confiance.

#### Referrer {#referrer}

L'option `referrer` vous permet de contrôler les informations de referrer envoyées avec la requête. C'est important pour des raisons de confidentialité et de sécurité.

```ts
// Send a specific referrer URL
http
  .get('/api/data', {
    referrer: 'https://example.com/page',
  })
  .subscribe((data) => {
    // ...
  });

// Use the current page as referrer (default behavior)
http
  .get('/api/analytics', {
    referrer: 'about:client',
  })
  .subscribe((data) => {
    // ...
  });
```

L'option `referrer` accepte :

- Une chaîne d'URL valide : définit l'URL de referrer précise à envoyer
- Une chaîne vide `''` : n'envoie aucune information de referrer
- `'about:client'` : utilise le referrer par défaut (l'URL de la page courante)

TIP: Utilisez `referrer: ''` pour les requêtes sensibles lorsque vous ne voulez pas divulguer l'URL de la page d'origine.

#### Referrer policy {#referrer-policy}

L'option `referrerPolicy` contrôle la quantité d'informations de referrer (l'URL de la page qui effectue la requête) envoyée avec une requête HTTP. Ce paramètre influe à la fois sur la confidentialité et sur les analytics, et vous permet de trouver un équilibre entre visibilité des données et sécurité.

```ts
// Send no referrer information regardless of the current page
http
  .get('/api/data', {
    referrerPolicy: 'no-referrer',
  })
  .subscribe();

// Send origin only (e.g. https://example.com)
http
  .get('/api/analytics', {
    referrerPolicy: 'origin',
  })
  .subscribe();
```

L'option `referrerPolicy` accepte :

- `'no-referrer'` N'envoie jamais l'en-tête `Referer`.
- `'no-referrer-when-downgrade'` Envoie le referrer pour les requêtes same-origin et sécurisées (HTTPS→HTTPS), mais l'omet lors d'une navigation d'une origine sécurisée vers une origine moins sécurisée (HTTPS→HTTP).
- `'origin'` N'envoie que l'origine (schéma, host, port) du referrer, sans le chemin ni la query string.
- `'origin-when-cross-origin'` Envoie l'URL complète pour les requêtes same-origin, mais uniquement l'origine pour les requêtes cross-origin.
- `'same-origin'` Envoie l'URL complète pour les requêtes same-origin et aucun referrer pour les requêtes cross-origin.
- `'strict-origin'` N'envoie que l'origine, et seulement si le niveau de sécurité du protocole n'est pas dégradé (par exemple, HTTPS→HTTPS). Omet le referrer en cas de dégradation.
- `'strict-origin-when-cross-origin'` Comportement par défaut des navigateurs. Envoie l'URL complète pour les requêtes same-origin, l'origine pour les requêtes cross-origin sans dégradation, et omet le referrer en cas de dégradation.
- `'unsafe-url'` Envoie toujours l'URL complète (y compris le chemin et la query string). Cela peut exposer des données sensibles et doit être utilisé avec prudence.

TIP: Préférez des valeurs prudentes comme `'no-referrer'`, `'origin'` ou `'strict-origin-when-cross-origin'` pour les requêtes sensibles en matière de confidentialité.

#### Intégrité {#integrity}

L'option `integrity` vous permet de vérifier que la réponse n'a pas été altérée en fournissant un hash cryptographique du contenu attendu. C'est particulièrement utile pour charger des scripts ou d'autres ressources depuis des CDN.

```ts
// Verify response integrity with SHA-256 hash
http
  .get('/api/script.js', {
    integrity: 'sha256-ABC123...',
    responseType: 'text',
  })
  .subscribe((script) => {
    // Script content is verified against the hash
  });
```

IMPORTANT: L'option `integrity` exige une correspondance exacte entre le contenu de la réponse et le hash fourni. Si le contenu ne correspond pas, la requête échoue avec une erreur réseau.

CRITICAL: Pendant le SSR, l'implémentation de Fetch lit l'intégralité du corps de la réponse pour vérifier `integrity` avant de renvoyer une réponse, comme l'exige le [Fetch Standard](https://fetch.spec.whatwg.org/#concept-main-fetch). Angular n'applique [`maxResponseBodySize`](/guide/ssr#configuring-the-response-body-size-limit) qu'après que Fetch a renvoyé une réponse : cette limite ne restreint donc pas les données mises en mémoire tampon pendant la vérification d'intégrité.

TIP: Utilisez l'intégrité des sous-ressources (subresource integrity) lorsque vous chargez des ressources critiques depuis des sources externes, pour garantir qu'elles n'ont pas été modifiées. Générez les hashs avec des outils comme `openssl`.

## Les `Observable`s HTTP {#http-observables}

Chaque méthode de requête de `HttpClient` construit et renvoie un `Observable` du type de réponse demandé. Il est important de comprendre le fonctionnement de ces `Observable`s quand on utilise `HttpClient`.

`HttpClient` produit ce que RxJS appelle des `Observable`s « froids » (cold) : aucune requête n'a réellement lieu tant qu'on ne s'est pas abonné à l'`Observable`. Ce n'est qu'à ce moment-là que la requête est réellement envoyée au serveur. S'abonner plusieurs fois au même `Observable` déclenche plusieurs requêtes au backend. Chaque abonnement est indépendant.

TIP: Vous pouvez voir les `Observable`s de `HttpClient` comme des _plans_ des véritables requêtes au serveur.

Une fois l'abonnement effectué, se désabonner annule la requête en cours. C'est très utile si l'abonnement à l'`Observable` passe par le pipe `async`, car la requête est automatiquement annulée si l'utilisateur quitte la page courante. De plus, si vous utilisez l'`Observable` avec un combinateur RxJS comme `switchMap`, cette annulation nettoie les requêtes obsolètes.

Une fois la réponse renvoyée, les `Observable`s de `HttpClient` se terminent généralement (même si des intercepteurs peuvent influer sur ce comportement).

Grâce à cette terminaison automatique, il n'y a généralement aucun risque de fuite mémoire si les abonnements à `HttpClient` ne sont pas nettoyés. Toutefois, comme pour toute opération asynchrone, nous vous recommandons fortement de nettoyer les abonnements lorsque le composant qui les utilise est détruit ; sinon, le callback d'abonnement risque de s'exécuter et de rencontrer des erreurs en tentant d'interagir avec le composant détruit.

TIP: Utiliser le pipe `async` ou l'opération `toSignal` pour s'abonner aux `Observable`s garantit que les abonnements sont correctement libérés.

## Bonnes pratiques {#best-practices}

Même si `HttpClient` peut être injecté et utilisé directement depuis les composants, nous vous recommandons généralement de créer des services réutilisables et injectables qui isolent et encapsulent la logique d'accès aux données. Par exemple, ce `UserService` encapsule la logique de requête des données d'un utilisateur à partir de son identifiant :

```ts
@Service()
export class UserService {
  private http = inject(HttpClient);

getUser(id: string): Observable<User> {
    return this.http.get<User>(`/api/user/${id}`);
  }
}
```

Dans un composant, vous pouvez combiner `@if` avec le pipe `async` pour n'afficher l'interface des données qu'une fois leur chargement terminé :

```typescript
import {AsyncPipe} from '@angular/common';
import {Component, input, inject, effect} from '@angular/core';
import {Observable} from 'rxjs';

@Component({
  imports: [AsyncPipe],
  template: `
    @if (user$ | async; as user) {
      <p>Name: {{ user.name }}</p>
      <p>Biography: {{ user.biography }}</p>
    }
  `,
})
export class UserProfile {
  userId = input.required<string>();
  user$!: Observable<User>;

private userService = inject(UserService);

constructor() {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```
# Intercepteurs

`HttpClient` prend en charge une forme de middleware appelée _intercepteurs_.

TLDR: Les intercepteurs sont des middlewares qui permettent d'extraire des requêtes individuelles des patterns courants comme les nouvelles tentatives, la mise en cache, la journalisation et l'authentification.

`HttpClient` prend en charge deux types d'intercepteurs : fonctionnels et basés sur la DI. Nous recommandons d'utiliser des intercepteurs fonctionnels, car leur comportement est plus prévisible, en particulier dans les configurations complexes. Les exemples de ce guide utilisent des intercepteurs fonctionnels, et nous traitons les [intercepteurs basés sur la DI](#di-based-interceptors) dans une section dédiée à la fin.

## Intercepteurs {#interceptors}

Les intercepteurs sont généralement des fonctions que vous pouvez exécuter pour chaque requête et qui disposent de larges capacités pour agir sur le contenu et le déroulement global des requêtes et des réponses. Vous pouvez installer plusieurs intercepteurs, qui forment une chaîne d'intercepteurs dans laquelle chaque intercepteur traite la requête ou la réponse avant de la transmettre à l'intercepteur suivant de la chaîne.

Vous pouvez utiliser des intercepteurs pour mettre en œuvre divers patterns courants, par exemple :

- Ajouter des en-têtes d'authentification aux requêtes sortantes vers une API donnée.
- Relancer les requêtes en échec avec un backoff exponentiel.
- Mettre en cache les réponses pendant une certaine durée, ou jusqu'à leur invalidation par des mutations.
- Personnaliser l'analyse (parsing) des réponses.
- Mesurer les temps de réponse du serveur et les journaliser.
- Piloter des éléments d'interface comme un indicateur de chargement pendant les opérations réseau.
- Regrouper et traiter par lots les requêtes effectuées dans un certain intervalle de temps.
- Faire échouer automatiquement les requêtes après un délai ou un timeout configurable.
- Interroger régulièrement le serveur (polling) et rafraîchir les résultats.

## Définir un intercepteur {#defining-an-interceptor}

Dans sa forme de base, un intercepteur est une fonction qui reçoit la `HttpRequest` sortante et une fonction `next` représentant l'étape de traitement suivante dans la chaîne d'intercepteurs.

Par exemple, ce `loggingInterceptor` journalise l'URL de la requête sortante avec `console.log` avant de transmettre la requête :

```ts
export function loggingInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  console.log(req.url);
  return next(req);
}
```

Pour que cet intercepteur intercepte réellement les requêtes, vous devez configurer `HttpClient` pour qu'il l'utilise.

## Configurer les intercepteurs {#configuring-interceptors}

Vous déclarez l'ensemble des intercepteurs à utiliser lors de la configuration de `HttpClient` via l'injection de dépendances, à l'aide de la fonctionnalité `withInterceptors` :

```ts
bootstrapApplication(App, {
  providers: [provideHttpClient(withInterceptors([loggingInterceptor, cachingInterceptor]))],
});
```

Les intercepteurs que vous configurez sont chaînés dans l'ordre où vous les avez listés dans les providers. Dans l'exemple ci-dessus, le `loggingInterceptor` traiterait la requête puis la transmettrait au `cachingInterceptor`.

### Intercepter les événements de réponse {#intercepting-response-events}

Un intercepteur peut transformer le flux `Observable` de `HttpEvent` renvoyé par `next` afin d'accéder à la réponse ou de la manipuler. Comme ce flux inclut tous les événements de réponse, il peut être nécessaire d'inspecter le `.type` de chaque événement pour identifier l'objet de réponse 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, 'returned a response with status', event.status);
      }
    }),
  );
}
```

TIP: Les intercepteurs associent naturellement les réponses à leurs requêtes sortantes, car ils transforment le flux de réponse dans une closure qui capture l'objet de la requête.

## Modifier les requêtes {#modifying-requests}

La plupart des aspects des instances de `HttpRequest` et `HttpResponse` sont _immuables_, et les intercepteurs ne peuvent pas les modifier directement. À la place, les intercepteurs appliquent des mutations en clonant ces objets avec l'opération `.clone()`, et en précisant quelles propriétés doivent être modifiées dans la nouvelle instance. Cela peut impliquer d'effectuer des mises à jour immuables sur la valeur elle-même (comme `HttpHeaders` ou `HttpParams`).

Par exemple, pour ajouter un en-tête à une requête :

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```

Cette immuabilité permet à la plupart des intercepteurs d'être idempotents si la même `HttpRequest` est soumise plusieurs fois à la chaîne d'intercepteurs. Cela peut se produire pour plusieurs raisons, notamment quand une requête est relancée après un échec.

CRITICAL: Le corps d'une requête ou d'une réponse n'est **pas** protégé contre les mutations profondes. Si un intercepteur doit modifier le corps, veillez à gérer son exécution multiple sur la même requête.

## Injection de dépendances dans les intercepteurs {#dependency-injection-in-interceptors}

Les intercepteurs s'exécutent dans le _contexte d'injection_ de l'injector qui les a enregistrés, et peuvent utiliser l'API [`inject`](/api/core/inject) d'Angular pour récupérer des dépendances.

Par exemple, supposons qu'une application dispose d'un service appelé `AuthService`, qui crée des jetons d'authentification pour les requêtes sortantes. Un intercepteur peut injecter et utiliser ce service :

```ts
export function authInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn) {
  // Inject the current `AuthService` and use it to get an authentication token:
  const authToken = inject(AuthService).getAuthToken();

// Clone the request to add the authentication header.
  const newReq = req.clone({
    headers: req.headers.append('X-Authentication-Token', authToken),
  });
  return next(newReq);
}
```

## Métadonnées de requête et de réponse {#request-and-response-metadata}

Il est souvent utile d'inclure dans une requête des informations qui ne sont pas envoyées au backend, mais qui sont spécifiquement destinées aux intercepteurs. Les `HttpRequest` disposent d'un objet `.context` qui stocke ce type de métadonnées sous la forme d'une instance de `HttpContext`. Cet objet fonctionne comme une map typée, avec des clés de type `HttpContextToken`.

Pour illustrer le fonctionnement de ce système, utilisons des métadonnées pour contrôler si un intercepteur de mise en cache est activé pour une requête donnée.

### Définir des jetons de contexte {#defining-context-tokens}

Pour stocker, dans la map `.context` d'une requête, le fait que l'intercepteur de mise en cache doive ou non mettre en cache cette requête, définissez un nouveau `HttpContextToken` qui servira de clé :

```ts
export const CACHING_ENABLED = new HttpContextToken<boolean>(() => true);
```

La fonction fournie crée la valeur par défaut du jeton pour les requêtes qui ne lui ont pas explicitement attribué de valeur. L'utilisation d'une fonction garantit que, si la valeur du jeton est un objet ou un tableau, chaque requête obtient sa propre instance.

### Lire le jeton dans un intercepteur {#reading-the-token-in-an-interceptor}

Un intercepteur peut ensuite lire le jeton et choisir d'appliquer ou non une logique de mise en cache en fonction de sa valeur :

```ts
export function cachingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  if (req.context.get(CACHING_ENABLED)) {
    // apply caching logic
    return ...;
  } else {
    // caching has been disabled for this request
    return next(req);
  }
}
```

### Définir des jetons de contexte lors d'une requête {#setting-context-tokens-when-making-a-request}

Lorsque vous effectuez une requête via l'API `HttpClient`, vous pouvez fournir des valeurs pour des `HttpContextToken` :

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```

Les intercepteurs peuvent lire ces valeurs depuis le `HttpContext` de la requête.

### Le contexte de requête est mutable {#the-request-context-is-mutable}

Contrairement aux autres propriétés des `HttpRequest`, le `HttpContext` associé est _mutable_. Si un intercepteur modifie le contexte d'une requête qui est ensuite relancée, ce même intercepteur observera la mutation du contexte lors de sa nouvelle exécution. C'est utile pour transmettre un état d'une tentative à l'autre si nécessaire.

## Réponses synthétiques {#synthetic-responses}

La plupart des intercepteurs se contentent d'invoquer le handler `next` tout en transformant la requête ou la réponse, mais ce n'est pas strictement obligatoire. Cette section présente plusieurs façons dont un intercepteur peut intégrer un comportement plus avancé.

Les intercepteurs ne sont pas tenus d'invoquer `next`. Ils peuvent à la place choisir de construire des réponses par un autre mécanisme, par exemple à partir d'un cache ou en envoyant la requête par un mécanisme alternatif.

Il est possible de construire une réponse avec le constructeur `HttpResponse` :

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```

## Exploiter les informations de redirection {#working-with-redirect-information}

Lorsque `HttpClient` utilise le backend fetch, les réponses incluent une propriété `redirected` qui indique si la réponse résulte d'une redirection. Cette propriété est alignée sur la spécification native de l'API Fetch et peut être utile dans les intercepteurs pour gérer les scénarios de redirection.

Un intercepteur peut accéder aux informations de redirection et agir en conséquence :

```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('Request to', req.url, 'was redirected to', event.url);
        // Handle redirect logic - maybe update analytics, security checks, etc.
      }
    }),
  );
}
```

Vous pouvez aussi utiliser les informations de redirection pour mettre en œuvre une logique conditionnelle dans vos intercepteurs :

```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) {
        // Check if we were redirected to a login page
        if (event.url?.includes('/login')) {
          // Handle authentication redirect
          handleAuthRedirect();
        }
      }
    }),
  );
}
```

## Exploiter les types de réponse {#working-with-response-types}

Lorsque `HttpClient` utilise le backend fetch, les réponses incluent une propriété `responseType` qui indique comment le navigateur a traité la réponse en fonction des politiques CORS et du mode de la requête. Cette propriété est alignée sur la spécification native de l'API Fetch et fournit des informations précieuses pour déboguer les problèmes CORS et comprendre l'accessibilité des réponses.

La propriété `responseType` de la réponse peut prendre les valeurs suivantes :

- `'basic'` - Réponse de même origine avec tous les en-têtes accessibles
- `'cors'` - Réponse cross-origin avec des en-têtes CORS correctement configurés
- `'opaque'` - Réponse cross-origin sans CORS, les en-têtes et le corps peuvent être limités
- `'opaqueredirect'` - Réponse à une requête redirigée en mode no-cors
- `'error'` - Une erreur réseau s'est produite

Un intercepteur peut utiliser les informations de type de réponse pour le débogage CORS et la gestion des erreurs :

```ts
export function responseTypeInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response) {
        // Handle different response types appropriately
        switch (event.responseType) {
          case 'opaque':
            // Limited access to response data
            console.warn('Limited response data due to CORS policy');
            break;
          case 'cors':
          case 'basic':
            // Full access to response data
            break;
          case 'error':
            // Handle network errors
            console.error('Network error in response');
            break;
        }
      }
    }),
  );
}
```

## Intercepteurs basés sur la DI {#di-based-interceptors}

`HttpClient` prend aussi en charge des intercepteurs définis comme des classes injectables et configurés via le système de DI. Les capacités des intercepteurs basés sur la DI sont identiques à celles des intercepteurs fonctionnels, mais le mécanisme de configuration diffère.

Un intercepteur basé sur la DI est une classe injectable qui implémente l'interface `HttpInterceptor` :

```ts
@Injectable()
export class LoggingInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, handler: HttpHandler): Observable<HttpEvent<any>> {
    console.log('Request URL: ' + req.url);
    return handler.handle(req);
  }
}
```

Les intercepteurs basés sur la DI se configurent via un multi provider d'injection de dépendances :

```ts
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      // DI-based interceptors must be explicitly enabled.
      withInterceptorsFromDi(),
    ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
  ],
});
```

Les intercepteurs basés sur la DI s'exécutent dans l'ordre d'enregistrement de leurs providers. Dans une application dotée d'une configuration de DI étendue et hiérarchique, cet ordre peut être très difficile à prévoir.
# Tester les requêtes

Comme pour toute dépendance externe, vous devez mocker le backend HTTP afin que vos tests puissent simuler l'interaction avec un serveur distant. La library `@angular/common/http/testing` fournit des outils pour capturer les requêtes effectuées par l'application, faire des assertions sur celles-ci et mocker les réponses pour émuler le comportement de votre backend.

La library de test est conçue pour un pattern dans lequel l'application exécute du code et effectue d'abord des requêtes. Le test vérifie ensuite que certaines requêtes ont été effectuées ou non, fait des assertions sur ces requêtes, et fournit enfin des réponses en « vidant » (flush) chaque requête attendue.

Enfin, les tests peuvent vérifier que l'application n'a effectué aucune requête inattendue.

## Configuration pour les tests {#setup-for-testing}

Pour commencer à tester l'utilisation de `HttpClient`, configurez `TestBed` et incluez `provideHttpClientTesting()` dans la configuration de votre test. `HttpClient` est fourni par l'environnement de test d'Angular, et `provideHttpClientTesting()` le configure pour utiliser un backend de test au lieu du vrai réseau. Il fournit aussi `HttpTestingController`, que vous utiliserez pour interagir avec le backend de test, définir des attentes sur les requêtes effectuées et renvoyer (flush) des réponses à ces requêtes. `HttpTestingController` peut être injecté depuis `TestBed` une fois configuré.

```ts
TestBed.configureTestingModule({
  providers: [
    // ... other test providers
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```

Désormais, lorsque vos tests effectuent des requêtes, celles-ci atteignent le backend de test au lieu du backend habituel. Vous pouvez utiliser `httpTesting` pour faire des assertions sur ces requêtes.

### Configurer `HttpClient` dans les tests {#configuring-httpclient-in-tests}

Si un test doit configurer des fonctionnalités de `HttpClient`, comme des intercepteurs, incluez `provideHttpClient(...)` avant `provideHttpClientTesting()`.
IMPORTANT: Pensez à fournir `provideHttpClient()` **avant** `provideHttpClientTesting()`, car `provideHttpClientTesting()` écrase certaines parties de `provideHttpClient()`. Procéder dans l'ordre inverse risque de casser vos tests.

```ts
TestBed.configureTestingModule({
  providers: [provideHttpClient(withInterceptors([authInterceptor])), provideHttpClientTesting()],
});
```

## Attendre des requêtes et y répondre {#expecting-and-answering-requests}

Par exemple, vous pouvez écrire un test qui s'attend à ce qu'une requête GET soit effectuée et qui fournit un mock de réponse :

```ts
TestBed.configureTestingModule({
  providers: [ConfigService, provideHttpClientTesting()],
});

const httpTesting = TestBed.inject(HttpTestingController);

// Load `ConfigService` and request the current configuration.
const service = TestBed.inject(ConfigService);
const config$ = service.getConfig<Config>();

// `firstValueFrom` subscribes to the `Observable`, which makes the HTTP request,
// and creates a `Promise` of the response.
const configPromise = firstValueFrom(config$);

// At this point, the request is pending, and we can assert it was made
// via the `HttpTestingController`:
const req = httpTesting.expectOne('/api/config', 'Request to load the configuration');

// We can assert various properties of the request if desired.
expect(req.request.method).toBe('GET');

// Flushing the request causes it to complete, delivering the result.
req.flush(DEFAULT_CONFIG);

// We can then assert that the response was successfully delivered by the `ConfigService`:
expect(await configPromise).toEqual(DEFAULT_CONFIG);

// Finally, we can assert that no other requests were made.
httpTesting.verify();
```

NOTE: `expectOne` échoue si le test a effectué plus d'une requête correspondant aux critères donnés.

Au lieu de faire une assertion sur `req.method`, vous pouvez utiliser une forme étendue de `expectOne` qui vérifie aussi la méthode de la requête :

```ts
const req = httpTesting.expectOne(
  {
    method: 'GET',
    url: '/api/config',
  },
  'Request to load the configuration',
);
```

HELPFUL: Les API d'attente comparent l'URL complète des requêtes, query parameters compris.

La dernière étape, qui vérifie qu'aucune requête ne reste en attente, est suffisamment courante pour que vous la déplaciez dans une étape `afterEach()` :

```ts
afterEach(() => {
  // Verify that none of the tests make any extra HTTP requests.
  TestBed.inject(HttpTestingController).verify();
});
```

## Gérer plusieurs requêtes à la fois {#handling-more-than-one-request-at-once}

Si vous devez répondre à des requêtes en double dans votre test, utilisez l'API `match()` au lieu de `expectOne()`. Elle prend les mêmes arguments mais renvoie un tableau des requêtes correspondantes. Une fois renvoyées, ces requêtes sont exclues des correspondances futures, et c'est à vous de les vider (flush) et de les vérifier.

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // Handle responding to each request.
}
```

## Correspondance avancée {#advanced-matching}

Toutes les fonctions de correspondance acceptent une fonction prédicat pour une logique de correspondance personnalisée :

```ts
// Look for one request that has a request body.
const requestsWithBody = httpTesting.expectOne((req) => req.body !== null);
```

La fonction `expectNone` vérifie qu'aucune requête ne correspond aux critères donnés.

```ts
// Assert that no mutation requests have been issued.
httpTesting.expectNone((req) => req.method !== 'GET');
```

## Tester la gestion des erreurs {#testing-error-handling}

Vous devriez tester les réactions de votre application quand des requêtes HTTP échouent.

### Erreurs du backend {#backend-errors}

Pour tester la gestion des erreurs du backend (quand le serveur renvoie un code de statut d'échec), videz (flush) les requêtes avec une réponse d'erreur qui émule ce que votre backend renverrait en cas d'échec d'une requête.

```ts
const req = httpTesting.expectOne('/api/config');
req.flush('Failed!', {status: 500, statusText: 'Internal Server Error'});

// Assert that the application successfully handled the backend error.
```

### Erreurs réseau {#network-errors}

Les requêtes peuvent aussi échouer à cause d'erreurs réseau, qui se manifestent sous forme d'erreurs `ProgressEvent`. Celles-ci peuvent être transmises avec la méthode `error()` :

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// Assert that the application successfully handled the network error.
```

## Tester un intercepteur {#testing-an-interceptor}

Vous devriez tester que vos intercepteurs fonctionnent dans les conditions souhaitées.

Par exemple, une application peut devoir ajouter à chaque requête sortante un jeton d'authentification généré par un service.
Ce comportement peut être assuré à l'aide d'un intercepteur :

```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 configuration de `TestBed` pour cet intercepteur doit s'appuyer sur la fonctionnalité `withInterceptors`.

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // Testing one interceptor at a time is recommended.
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```

Le `HttpTestingController` peut récupérer l'instance de la requête, que vous pouvez ensuite inspecter pour vous assurer que la requête a bien été modifiée.

```ts
const service = TestBed.inject(AuthService);
const http = TestBed.inject(HttpClient);

// Make an HTTP request.
const response = firstValueFrom(http.get('/api/config'));

const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```

Un intercepteur similaire pourrait être implémenté avec des intercepteurs basés sur des classes :

```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);
  }
}
```

Pour le tester, la configuration de `TestBed` doit plutôt être la suivante :

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    provideHttpClient(withInterceptorsFromDi()),
    provideHttpClientTesting(),
    // We rely on the HTTP_INTERCEPTORS token to register the AuthInterceptor as an HttpInterceptor
    {provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true},
  ],
});
```
# Reactive forms

Les reactive forms proposent une approche pilotée par le modèle pour gérer les saisies de formulaire dont les valeurs évoluent au fil du temps.
Ce guide vous montre comment créer et mettre à jour un contrôle de formulaire simple, utiliser plusieurs contrôles dans un groupe, valider les valeurs d'un formulaire et créer des formulaires dynamiques dans lesquels vous pouvez ajouter ou retirer des contrôles à l'exécution.

## Présentation des reactive forms {#overview-of-reactive-forms}

Les reactive forms adoptent une approche explicite et immuable pour gérer l'état d'un formulaire à un instant donné.
Chaque modification de l'état du formulaire renvoie un nouvel état, ce qui préserve l'intégrité du modèle entre les modifications.
Les reactive forms reposent sur des flux observables, dans lesquels les saisies et les valeurs du formulaire sont fournies sous forme de flux accessibles de manière synchrone.

Les reactive forms facilitent aussi les tests, car vous avez l'assurance que vos données sont cohérentes et prévisibles quand vous les demandez.
Tous les consommateurs de ces flux peuvent manipuler les données en toute sécurité.

Les reactive forms se distinguent des [template-driven forms](guide/forms/template-driven-forms) sur plusieurs points.
Les reactive forms offrent un accès synchrone au modèle de données, l'immuabilité grâce aux opérateurs d'observables et le suivi des modifications via des flux observables.

Les template-driven forms permettent de modifier directement les données dans votre template, mais sont moins explicites que les reactive forms, car ils s'appuient sur des directives intégrées au template ainsi que sur des données mutables pour suivre les modifications de manière asynchrone.
Consultez la [présentation des formulaires](guide/forms) pour une comparaison détaillée des deux paradigmes.

## Ajouter un contrôle de formulaire simple {#adding-a-basic-form-control}

L'utilisation des contrôles de formulaire se fait en trois étapes.

1. Générez un nouveau composant et enregistrez le module des reactive forms. Ce module déclare les directives nécessaires pour utiliser les reactive forms.
1. Instanciez un nouveau `FormControl`.
1. Enregistrez le `FormControl` dans le template.

Vous pouvez ensuite afficher le formulaire en ajoutant le composant au template.

Les exemples suivants montrent comment ajouter un contrôle de formulaire unique.
Dans l'exemple, l'utilisateur saisit son nom dans un champ de saisie ; le formulaire capture cette valeur et affiche la valeur courante de l'élément de contrôle de formulaire.

<docs-workflow>

<docs-step title="Générer un nouveau composant et importer le ReactiveFormsModule {#generate-a-new-component-and-import-the-reactiveformsmodule}">
Utilisez la commande CLI `ng generate component` pour générer un composant dans votre projet, puis importez `ReactiveFormsModule` depuis le package `@angular/forms` et ajoutez-le au tableau `imports` de votre composant.

<docs-code header="name-editor.component.ts (extrait)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="imports" />
</docs-step>

<docs-step title="Déclarer une instance de FormControl {#declare-a-formcontrol-instance}">
Utilisez le constructeur de `FormControl` pour définir sa valeur initiale, ici une chaîne vide. En créant ces contrôles dans la classe de votre composant, vous pouvez immédiatement écouter, mettre à jour et valider l'état de la saisie du formulaire.

<docs-code header="name-editor.component.ts" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="create-control"/>
</docs-step>

<docs-step title="Enregistrer le contrôle dans le template {#register-the-control-in-the-template}">
Après avoir créé le contrôle dans la classe du composant, vous devez l'associer à un élément de contrôle de formulaire dans le template. Mettez à jour le template avec le contrôle de formulaire en utilisant le binding `formControl` fourni par `FormControlDirective`, qui est lui aussi inclus dans le `ReactiveFormsModule`.

<docs-code header="name-editor.component.html" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="control-binding" />

Grâce à la syntaxe de binding du template, le contrôle de formulaire est maintenant enregistré sur l'élément de saisie `name` du template. Le contrôle de formulaire et l'élément du DOM communiquent entre eux : la vue reflète les modifications du modèle, et le modèle reflète les modifications de la vue.
</docs-step>

<docs-step title="Afficher le composant {#display-the-component}">
Le `FormControl` assigné à la propriété `name` s'affiche quand le composant `<app-name-editor>` est ajouté à un template.

<docs-code header="app.component.html (éditeur de nom)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-name-editor"/>
</docs-step>
</docs-workflow>

### Afficher la valeur d'un contrôle de formulaire {#displaying-a-form-control-value}

Vous pouvez afficher la valeur des manières suivantes :

- Via l'observable `valueChanges`, qui vous permet d'écouter les modifications de la valeur du formulaire dans le template avec `AsyncPipe` ou dans la classe du composant avec la méthode `subscribe()`
- Avec la propriété `value`, qui vous donne un snapshot de la valeur courante

L'exemple suivant montre comment afficher la valeur courante avec l'interpolation dans le template.

<docs-code header="name-editor.component.html (valeur du contrôle)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="display-value"/>

La valeur affichée change à mesure que vous modifiez l'élément de contrôle de formulaire.

Les reactive forms donnent accès aux informations sur un contrôle donné via les propriétés et méthodes fournies avec chaque instance.
Ces propriétés et méthodes de la classe sous-jacente [AbstractControl](api/forms/AbstractControl 'API reference') servent à contrôler l'état du formulaire et à déterminer quand afficher des messages lors de la [validation des saisies](#validating-form-input 'Learn more about validating form input').

Découvrez les autres propriétés et méthodes de `FormControl` dans la [référence de l'API](api/forms/FormControl 'Detailed syntax reference').

### Remplacer la valeur d'un contrôle de formulaire {#replacing-a-form-control-value}

Les reactive forms disposent de méthodes pour modifier la valeur d'un contrôle par programmation, ce qui vous permet de mettre à jour la valeur sans interaction de l'utilisateur.
Une instance de contrôle de formulaire fournit une méthode `setValue()` qui met à jour la valeur du contrôle de formulaire et valide la structure de la valeur fournie par rapport à la structure du contrôle.
Par exemple, quand vous récupérez des données de formulaire depuis une API backend ou un service, utilisez la méthode `setValue()` pour mettre à jour le contrôle avec sa nouvelle valeur, en remplaçant entièrement l'ancienne.

L'exemple suivant ajoute à la classe du composant une méthode qui met à jour la valeur du contrôle à _Nancy_ avec la méthode `setValue()`.

<docs-code header="name-editor.component.ts (mise à jour de la valeur)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="update-value"/>

Mettez à jour le template avec un bouton pour simuler une mise à jour du nom.
Quand vous cliquez sur le bouton **Update Name**, la valeur saisie dans l'élément de contrôle de formulaire est reflétée comme sa valeur courante.

<docs-code header="name-editor.component.html (mise à jour de la valeur)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="update-value"/>

Le model de formulaire est la source de vérité du contrôle : quand vous cliquez sur le bouton, la valeur de la saisie est donc modifiée dans la classe du composant, ce qui écrase sa valeur courante.

HELPFUL: Dans cet exemple, vous utilisez un seul contrôle.
Quand vous utilisez la méthode `setValue()` avec une instance de [groupe de formulaire](#grouping-form-controls) ou de [tableau de formulaire](#creating-dynamic-forms), la valeur doit correspondre à la structure du groupe ou du tableau.

## Regrouper des contrôles de formulaire {#grouping-form-controls}

Les formulaires contiennent généralement plusieurs contrôles liés entre eux.
Les reactive forms proposent deux façons de regrouper plusieurs contrôles liés dans un même formulaire de saisie.

| Groupes de formulaire | Détails |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Groupe de formulaire | Définit un formulaire avec un ensemble fixe de contrôles que vous pouvez gérer ensemble. Les bases des groupes de formulaire sont abordées dans cette section. Vous pouvez aussi [imbriquer des groupes de formulaire](#creating-nested-form-groups 'See more about nesting groups') pour créer des formulaires plus complexes. |
| Tableau de formulaire | Définit un formulaire dynamique, dans lequel vous pouvez ajouter et retirer des contrôles à l'exécution. Vous pouvez aussi imbriquer des tableaux de formulaire pour créer des formulaires plus complexes. Pour en savoir plus sur cette option, consultez [Créer des formulaires dynamiques](#creating-dynamic-forms). |

De la même façon qu'une instance de contrôle de formulaire vous donne le contrôle d'un champ de saisie unique, une instance de groupe de formulaire suit l'état d'un groupe d'instances de contrôle de formulaire $par exemple, un formulaire$.
Chaque contrôle d'une instance de groupe de formulaire est suivi par son nom lors de la création du groupe de formulaire.
L'exemple suivant montre comment gérer plusieurs instances de contrôle de formulaire dans un même groupe.

Générez un composant `ProfileEditor` et importez les classes `FormGroup` et `FormControl` depuis le package `@angular/forms`.

```shell
ng generate component ProfileEditor
```

<docs-code header="profile-editor.component.ts (imports)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="imports"/>

Pour ajouter un groupe de formulaire à ce composant, suivez les étapes suivantes.

1. Créez une instance de `FormGroup`.
1. Associez le model et la vue du `FormGroup`.
1. Enregistrez les données du formulaire.

<docs-workflow>

<docs-step title="Créer une instance de FormGroup {#create-a-formgroup-instance}">
Créez dans la classe du composant une propriété nommée `profileForm` et affectez-lui une nouvelle instance de groupe de formulaire. Pour initialiser le groupe de formulaire, passez au constructeur un objet dont les clés nommées sont associées à leur contrôle.

Pour le formulaire de profil, ajoutez deux instances de contrôle de formulaire nommées `firstName` et `lastName`

<docs-code header="profile-editor.component.ts (groupe de formulaire)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="formgroup"/>

Les contrôles de formulaire individuels sont maintenant rassemblés dans un groupe. Une instance de `FormGroup` fournit la valeur de son model sous la forme d'un objet construit à partir des valeurs de chaque contrôle du groupe. Une instance de groupe de formulaire possède les mêmes propriétés (comme `value` et `untouched`) et méthodes (comme `setValue()`) qu'une instance de contrôle de formulaire.
</docs-step>

<docs-step title="Associer le model et la vue du FormGroup {#associate-the-formgroup-model-and-view}">
Un groupe de formulaire suit le statut et les modifications de chacun de ses contrôles : si l'un des contrôles change, le contrôle parent émet lui aussi un nouveau statut ou une nouvelle valeur. Le model du groupe est maintenu à partir de ses membres. Après avoir défini le model, vous devez mettre à jour le template pour refléter le model dans la vue.

<docs-code header="profile-editor.component.html (groupe de formulaire du template)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroup"/>

De la même façon qu'un groupe de formulaire contient un groupe de contrôles, le `FormGroup` _profileForm_ est lié à l'élément `form` avec la directive `FormGroup`, ce qui crée une couche de communication entre le model et le formulaire contenant les saisies. L'input `formControlName` fourni par la directive `FormControlName` lie chaque saisie individuelle au contrôle de formulaire défini dans le `FormGroup`. Les contrôles de formulaire communiquent avec leurs éléments respectifs. Ils communiquent aussi leurs modifications à l'instance de groupe de formulaire, qui constitue la source de vérité pour la valeur du model.
</docs-step>

<docs-step title="Enregistrer les données du formulaire {#save-form-data}">
Le composant `ProfileEditor` accepte les saisies de l'utilisateur, mais dans un scénario réel, vous voulez capturer la valeur du formulaire et la rendre disponible pour un traitement ultérieur en dehors du composant. La directive `FormGroup` écoute l'événement `submit` émis par l'élément `form` et émet un événement `ngSubmit` que vous pouvez lier à une fonction de callback. Ajoutez un event listener `ngSubmit` à la balise `form` avec la méthode de callback `onSubmit()`.

<docs-code header="profile-editor.component.html (événement submit)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="ng-submit"/>

La méthode `onSubmit()` du composant `ProfileEditor` capture la valeur courante de `profileForm`. Utilisez `output()` pour garder le formulaire encapsulé et fournir la valeur du formulaire en dehors du composant. L'exemple suivant utilise `console.warn` pour afficher un message dans la console du navigateur.

<docs-code header="profile-editor.component.ts (méthode de soumission)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="on-submit"/>

L'événement `submit` est émis par la balise `form` via l'événement DOM natif. Vous déclenchez l'événement en cliquant sur un bouton de type `submit`. Cela permet à l'utilisateur d'appuyer sur la touche **Entrée** pour soumettre le formulaire rempli.

Utilisez un élément `button` pour ajouter un bouton en bas du formulaire afin de déclencher la soumission du formulaire.

<docs-code header="profile-editor.component.html (bouton de soumission)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="submit-button"/>

Le bouton de l'extrait précédent possède aussi un binding `disabled` qui désactive le bouton quand `profileForm` est invalide. Vous n'effectuez encore aucune validation, donc le bouton est toujours activé. La validation de formulaire de base est abordée dans la section [Valider les saisies du formulaire](#validating-form-input).
</docs-step>

<docs-step title="Afficher le composant {#display-the-component-form-group}">
Pour afficher le composant `ProfileEditor` qui contient le formulaire, ajoutez-le au template d'un composant.

<docs-code header="app.component.html (éditeur de profil)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-profile-editor"/>

`ProfileEditor` vous permet de gérer les instances de contrôle de formulaire des contrôles `firstName` et `lastName` au sein de l'instance de groupe de formulaire.
</docs-step>
</docs-workflow>

### Créer des groupes de formulaire imbriqués {#creating-nested-form-groups}

Les groupes de formulaire peuvent accepter comme enfants à la fois des instances de contrôle de formulaire individuelles et d'autres instances de groupe de formulaire.
Cela facilite la maintenance des models de formulaire complexes et leur regroupement logique.

Quand vous construisez des formulaires complexes, il est plus simple de gérer les différentes zones d'information dans des sections plus petites.
Utiliser une instance de groupe de formulaire imbriquée vous permet de découper les grands groupes de formulaire en groupes plus petits et plus faciles à gérer.

Pour créer des formulaires plus complexes, suivez les étapes suivantes.

1. Créez un groupe imbriqué.
1. Regroupez le formulaire imbriqué dans le template.

Certains types d'informations se rangent naturellement dans un même groupe.
Un nom et une adresse sont des exemples typiques de tels groupes imbriqués, et sont utilisés dans les exemples suivants.

<docs-workflow>
<docs-step title="Créer un groupe imbriqué {#create-a-nested-group}">
Pour créer un groupe imbriqué dans `profileForm`, ajoutez un élément imbriqué `address` à l'instance de groupe de formulaire.

<docs-code header="profile-editor.component.ts (groupe de formulaire imbriqué)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="nested-formgroup"/>

Dans cet exemple, `address group` combine les contrôles existants `firstName` et `lastName` avec les nouveaux contrôles `street`, `city`, `state` et `zip`. Même si l'élément `address` du groupe de formulaire est un enfant de l'élément global `profileForm` du groupe de formulaire, les mêmes règles s'appliquent aux modifications de valeur et de statut. Les modifications de statut et de valeur du groupe de formulaire imbriqué se propagent au groupe de formulaire parent, ce qui maintient la cohérence avec le modèle global.
</docs-step>

<docs-step title="Regrouper le formulaire imbriqué dans le template {#group-the-nested-form-in-the-template}">
Après avoir mis à jour le model dans la classe du composant, mettez à jour le template pour connecter l'instance de groupe de formulaire et ses éléments de saisie. Ajoutez au template de `ProfileEditor` le groupe de formulaire `address` contenant les champs `street`, `city`, `state` et `zip`.

<docs-code header="profile-editor.component.html (groupe de formulaire imbriqué du template)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroupname"/>

Le formulaire `ProfileEditor` s'affiche comme un seul groupe, mais le model est découpé davantage pour représenter les zones de regroupement logique.

Affichez la valeur de l'instance de groupe de formulaire dans le template du composant avec la propriété `value` et `JsonPipe`.
</docs-step>
</docs-workflow>

### Mettre à jour des parties du modèle de données {#updating-parts-of-the-data-model}

Quand vous mettez à jour la valeur d'une instance de groupe de formulaire qui contient plusieurs contrôles, vous pouvez vouloir ne mettre à jour que certaines parties du modèle.
Cette section explique comment mettre à jour des parties spécifiques du modèle de données d'un contrôle de formulaire.

Il existe deux façons de mettre à jour la valeur du model :

| Méthodes        | Détails |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setValue()`   | Définit une nouvelle valeur pour un contrôle individuel. La méthode `setValue()` respecte strictement la structure du groupe de formulaire et remplace entièrement la valeur du contrôle. |
| `patchValue()` | Remplace toutes les propriétés définies dans l'objet qui ont changé dans le model de formulaire. |

Les vérifications strictes de la méthode `setValue()` aident à détecter les erreurs d'imbrication dans les formulaires complexes, tandis que `patchValue()` échoue silencieusement sur ces erreurs.

Dans `ProfileEditorComponent`, utilisez la méthode `updateProfile` avec l'exemple suivant pour mettre à jour le prénom et l'adresse de l'utilisateur.

<docs-code header="profile-editor.component.ts (patch de la valeur)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="patch-value"/>

Simulez une mise à jour en ajoutant au template un bouton qui met à jour le profil de l'utilisateur à la demande.

<docs-code header="profile-editor.component.html (mise à jour de la valeur)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="patch-value"/>

Quand un utilisateur clique sur le bouton, le model `profileForm` est mis à jour avec de nouvelles valeurs pour `firstName` et `street`. Notez que `street` est fourni dans un objet à l'intérieur de la propriété `address`.
C'est nécessaire, car la méthode `patchValue()` applique la mise à jour en suivant la structure du model.
`patchValue()` ne met à jour que les propriétés que le model de formulaire définit.

## Utiliser le service FormBuilder pour générer des contrôles {#using-the-formbuilder-service-to-generate-controls}

Créer manuellement des instances de contrôle de formulaire peut devenir répétitif quand vous gérez plusieurs formulaires.
Le service `FormBuilder` fournit des méthodes pratiques pour générer des contrôles.

Suivez les étapes suivantes pour tirer parti de ce service.

1. Importez la classe `FormBuilder`.
1. Injectez le service `FormBuilder`.
1. Générez le contenu du formulaire.

Les exemples suivants montrent comment refactoriser le composant `ProfileEditor` pour utiliser le service FormBuilder afin de créer les instances de contrôle de formulaire et de groupe de formulaire.

<docs-workflow>
<docs-step title="Importer la classe FormBuilder {#import-the-formbuilder-class}">
Importez la classe `FormBuilder` depuis le package `@angular/forms`.

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder-imports"/>

</docs-step>

<docs-step title="Injecter le service FormBuilder {#inject-the-formbuilder-service}">
Le service `FormBuilder` est un provider injectable issu du module des reactive forms. Utilisez la fonction `inject()` pour injecter cette dépendance dans votre composant.

<docs-code header="profile-editor.component.ts (initialisation de la propriété)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="inject-form-builder"/>

</docs-step>
<docs-step title="Générer les contrôles de formulaire {#generate-form-controls}">
Le service `FormBuilder` dispose de trois méthodes : `control()`, `group()` et `array()`. Ce sont des méthodes de fabrique qui génèrent des instances dans les classes de vos composants, notamment des contrôles de formulaire, des groupes de formulaire et des tableaux de formulaire. Utilisez la méthode `group` pour créer les contrôles de `profileForm`.

<docs-code header="profile-editor.component.ts (FormBuilder)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder"/>

Dans l'exemple précédent, vous utilisez la méthode `group()` avec le même objet pour définir les propriétés du model. La valeur de chaque nom de contrôle est un tableau contenant la valeur initiale comme premier élément.

TIP: Vous pouvez définir le contrôle avec seulement la valeur initiale, mais si vos contrôles nécessitent une validation synchrone ou asynchrone, ajoutez les validateurs synchrones et asynchrones comme deuxième et troisième éléments du tableau. Comparez l'utilisation du FormBuilder avec la création manuelle des instances.
</docs-step>

</docs-workflow>

## Valider les saisies du formulaire {#validating-form-input}

La _validation de formulaire_ sert à garantir que les saisies de l'utilisateur sont complètes et correctes.
Cette section explique comment ajouter un validateur unique à un contrôle de formulaire et afficher le statut global du formulaire.
La validation de formulaire est traitée plus en détail dans le guide [Validation de formulaire](guide/forms/form-validation).

Suivez les étapes suivantes pour ajouter une validation de formulaire.

1. Importez une fonction de validation dans le composant de votre formulaire.
1. Ajoutez le validateur au champ du formulaire.
1. Ajoutez la logique de gestion du statut de validation.

La validation la plus courante consiste à rendre un champ obligatoire.
L'exemple suivant montre comment ajouter une validation obligatoire au contrôle `firstName` et afficher le résultat de la validation.

<docs-workflow>
<docs-step title="Importer une fonction de validation {#import-a-validator-function}">
Les reactive forms incluent un ensemble de fonctions de validation pour les cas d'usage courants. Ces fonctions reçoivent le contrôle à valider et renvoient un objet d'erreur ou une valeur nulle selon le résultat de la vérification.

Importez la classe `Validators` depuis le package `@angular/forms`.

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="validator-imports"/>
</docs-step>

<docs-step title="Rendre un champ obligatoire {#make-a-field-required}">
Dans le composant `ProfileEditor`, ajoutez la méthode statique `Validators.required` comme deuxième élément du tableau du contrôle `firstName`.

<docs-code header="profile-editor.component.ts (validateur required)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="required-validator"/>
</docs-step>

<docs-step title="Afficher le statut du formulaire {#display-form-status}">
Quand vous ajoutez un champ obligatoire au contrôle de formulaire, son statut initial est invalide. Ce statut invalide se propage à l'élément de groupe de formulaire parent, ce qui rend son statut invalide. Accédez au statut courant de l'instance de groupe de formulaire via sa propriété `status`.

Affichez le statut courant de `profileForm` avec l'interpolation.

<docs-code header="profile-editor.component.html (affichage du statut)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="display-status"/>

Le bouton **Submit** est désactivé, car `profileForm` est invalide en raison du contrôle de formulaire `firstName` obligatoire. Une fois la saisie `firstName` remplie, le formulaire devient valide et le bouton **Submit** est activé.

Pour en savoir plus sur la validation de formulaire, consultez le guide [Validation de formulaire](guide/forms/form-validation).
</docs-step>
</docs-workflow>

## Créer des formulaires dynamiques {#creating-dynamic-forms}

`FormArray` est une alternative à `FormGroup` pour gérer un nombre quelconque de contrôles non nommés.
Comme avec les instances de groupe de formulaire, vous pouvez insérer et retirer dynamiquement des contrôles dans les instances de tableau de formulaire, et la valeur ainsi que le statut de validation de l'instance de tableau de formulaire sont calculés à partir de ses contrôles enfants.
En revanche, vous n'avez pas besoin de définir une clé nommée pour chaque contrôle : c'est donc une excellente option si vous ne connaissez pas à l'avance le nombre de valeurs enfants.

Pour définir un formulaire dynamique, suivez les étapes suivantes.

1. Importez la classe `FormArray`.
1. Définissez un contrôle `FormArray`.
1. Accédez au contrôle `FormArray` avec une méthode getter.
1. Affichez le tableau de formulaire dans un template.

L'exemple suivant vous montre comment gérer un tableau d'_alias_ dans `ProfileEditor`.

<docs-workflow>
<docs-step title="Importer la classe `FormArray` {#import-the-formarray-class}">
Importez la classe `FormArray` depuis `@angular/forms` pour l'utiliser comme information de type. Le service `FormBuilder` est prêt à créer une instance de `FormArray`.

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-array-imports"/>
</docs-step>

<docs-step title="Définir un contrôle `FormArray` {#define-a-formarray-control}">
Vous pouvez initialiser un tableau de formulaire avec un nombre quelconque de contrôles, de zéro à plusieurs, en les définissant dans un tableau. Ajoutez une propriété `aliases` à l'instance de groupe de formulaire de `profileForm` pour définir le tableau de formulaire.

Utilisez la méthode `FormBuilder.array()` pour définir le tableau, et la méthode `FormBuilder.control()` pour remplir le tableau avec un contrôle initial.

<docs-code header="profile-editor.component.ts (tableau de formulaire aliases)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases"/>

Le contrôle aliases de l'instance de groupe de formulaire contient maintenant un seul contrôle, jusqu'à ce que d'autres contrôles soient ajoutés dynamiquement.
</docs-step>

<docs-step title="Accéder au contrôle `FormArray` {#access-the-formarray-control}">
Un getter donne accès aux alias de l'instance de tableau de formulaire, plutôt que de répéter la méthode `profileForm.get()` pour obtenir chaque instance. L'instance de tableau de formulaire représente un nombre indéfini de contrôles dans un tableau. Il est pratique d'accéder à un contrôle via un getter, et cette approche se répète facilement pour d'autres contrôles. <br />

Utilisez la syntaxe getter pour créer une propriété de classe `aliases` qui récupère le contrôle de tableau de formulaire des alias depuis le groupe de formulaire parent.

<docs-code header="profile-editor.component.ts (getter aliases)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases-getter"/>

Comme le contrôle renvoyé est de type `AbstractControl`, vous devez fournir un type explicite pour accéder à la syntaxe des méthodes de l'instance de tableau de formulaire. Définissez une méthode pour insérer dynamiquement un contrôle d'alias dans le tableau de formulaire des alias. La méthode `FormArray.push()` insère le contrôle comme nouvel élément du tableau, et vous pouvez aussi passer un tableau de contrôles à FormArray.push() pour enregistrer plusieurs contrôles à la fois.

<docs-code header="profile-editor.component.ts (ajout d'un alias)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="add-alias"/>

Dans le template, chaque contrôle s'affiche comme un champ de saisie distinct.

</docs-step>

<docs-step title="Afficher le tableau de formulaire dans le template {#display-the-form-array-in-the-template}">

Pour rattacher les alias de votre model de formulaire, vous devez les ajouter au template. De la même façon que l'input `formGroupName` fourni par `FormGroupName`, `formArrayName` relie l'instance de tableau de formulaire au template avec `FormArrayName`.

Ajoutez le HTML de template suivant après la `<div>` qui ferme l'élément `formGroupName`.

<docs-code header="profile-editor.component.html (template du tableau de formulaire aliases)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="formarrayname"/>

Le bloc `@for` parcourt chaque instance de contrôle de formulaire fournie par l'instance de tableau de formulaire aliases. Comme les éléments d'un tableau de formulaire ne sont pas nommés, vous affectez l'index à la variable `i` et le passez à chaque contrôle pour le lier à l'input `formControlName`.

Chaque fois qu'une nouvelle instance d'alias est ajoutée, la nouvelle instance de tableau de formulaire reçoit son contrôle en fonction de l'index. Cela vous permet de suivre chaque contrôle individuel lors du calcul du statut et de la valeur du contrôle racine.

NOTE: Dans les applications zoneless, modifier le model d'un reactive form (par exemple en appelant `FormArray.push()`) ne planifie pas automatiquement la détection de changements du composant. Si votre template dépend de modifications structurelles du model, comme `aliases.controls`, assurez-vous que le composant notifie Angular pour lancer la détection de changements, par exemple en reliant un observable des formulaires à `ChangeDetectorRef.markForCheck()` :

```ts
import {ChangeDetectorRef, Component, inject} from '@angular/core';
import {takeUntilDestroyed} from '@angular/core/rxjs-interop';

@Component({/* ... */})
export class ProfileEditor {
  private readonly cdr = inject(ChangeDetectorRef);

constructor() {
    this.profileForm.valueChanges
      .pipe(takeUntilDestroyed())
      .subscribe(() => this.cdr.markForCheck());
  }
}
```

</docs-step>

### Utiliser `FormArrayDirective` pour les tableaux de formulaire de premier niveau {#using-formarraydirective-for-top-level-form-arrays}

Vous pouvez lier un `FormArray` directement à un élément `<form>` en utilisant la `FormArrayDirective`.  
C'est utile quand le formulaire n'utilise pas de `FormGroup` de premier niveau et que le tableau lui-même représente l'ensemble du model de formulaire.

```typescript
import {Component} from '@angular/core';
import {FormArray, FormControl, ReactiveFormsModule} from '@angular/forms';

@Component({
  selector: 'form-array-example',
  imports: [ReactiveFormsModule],
  template: `
    <form [formArray]="form">
      @for (control of form.controls; track $index) {
        <input [formControlName]="$index" />
      }
    </form>
  `,
})
export class FormArrayExampleComponent {
  controls = [new FormControl('fish'), new FormControl('cat'), new FormControl('dog')];

form = new FormArray(this.controls);
}
```

<docs-step title="Ajouter un alias {#add-an-alias}">

Au départ, le formulaire contient un seul champ `Alias`. Pour ajouter un autre champ, cliquez sur le bouton **Add Alias**. Vous pouvez aussi valider le tableau d'alias rapporté par le model de formulaire, affiché par `Form Value` en bas du template. Au lieu d'une instance de contrôle de formulaire pour chaque alias, vous pouvez composer une autre instance de groupe de formulaire avec des champs supplémentaires. Le processus de définition d'un contrôle pour chaque élément reste le même.
</docs-step>

</docs-workflow>

## Événements unifiés de changement d'état des contrôles {#unified-control-state-change-events}

Tous les contrôles de formulaire exposent un flux unique et unifié d'**événements de changement d'état des contrôles** via l'observable `events` d'`AbstractControl` (`FormControl`, `FormGroup`, `FormArray` et `FormRecord`).
Ce flux unifié vous permet de réagir aux changements d'état de **valeur**, de **statut**, **pristine**, **touched** et **reset**, ainsi qu'aux **actions au niveau du formulaire** comme la **soumission**, ce qui vous permet de gérer toutes les mises à jour avec un seul abonnement au lieu de brancher plusieurs observables.

### Types d'événements {#event-types}

Chaque élément émis par `events` est une instance d'une classe d'événement spécifique :

- **`ValueChangeEvent`** — quand la **valeur** du contrôle change.
- **`StatusChangeEvent`** — quand le **statut de validation** du contrôle passe à l'une des valeurs de `FormControlStatus` (`VALID`, `INVALID`, `PENDING` ou `DISABLED`).
- **`PristineChangeEvent`** — quand l'état **pristine/dirty** du contrôle change.
- **`TouchedChangeEvent`** — quand l'état **touched/untouched** du contrôle change.
- **`FormResetEvent`** — quand un contrôle ou un formulaire est réinitialisé, soit via l'API `reset()`, soit via une action native.
- **`FormSubmittedEvent`** — quand le formulaire est soumis.

Toutes les classes d'événement étendent `ControlEvent` et incluent une référence `source` vers l'`AbstractControl` à l'origine du changement, ce qui est utile dans les grands formulaires.

```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');
      }
    });
  }
}
```

### Filtrer des événements spécifiques {#filtering-specific-events}

Privilégiez les opérateurs RxJS quand vous n'avez besoin que d'un sous-ensemble des types d'événements.

```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));
```

### Unifier plusieurs abonnements {#unifying-from-multiple-subscriptions}

**Avant**

```ts
import {combineLatest} from 'rxjs';

combineLatest([control.valueChanges, control.statusChanges]).subscribe(([value, status]) => {
  /* ... */
});
```

**Après**

```ts
control.events.subscribe((e) => {
  // Handle ValueChangeEvent, StatusChangeEvent, etc.
});
```

NOTE: Lors d'un changement de valeur, l'émission a lieu juste après la mise à jour de la valeur de ce contrôle. La valeur d'un contrôle parent (par exemple si ce FormControl fait partie d'un FormGroup) est mise à jour plus tard : accéder à la valeur d'un contrôle parent (avec la propriété `value`) depuis le callback de cet événement peut donc renvoyer une valeur qui n'a pas encore été mise à jour. Abonnez-vous plutôt aux `events` du contrôle parent.

## Gérer l'état des contrôles de formulaire {#managing-form-control-state}

Les reactive forms suivent l'état des contrôles via **touched/untouched** et **pristine/dirty**. Angular les met à jour automatiquement lors des interactions avec le DOM, mais vous pouvez aussi les gérer par programmation.

**[`markAsTouched`](api/forms/FormControl#markAsTouched)** — Marque un contrôle ou un formulaire comme touché, à la suite d'événements de focus et de blur qui ne modifient pas la valeur. Se propage par défaut aux contrôles parents.

```ts
// Show validation errors after user leaves a field
onEmailBlur() {
  const email = this.form.get('email');
  email.markAsTouched();
}
```

**[`markAsUntouched`](api/forms/FormControl#markAsUntouched)** — Marque un contrôle ou un formulaire comme non touché. Se répercute sur tous les contrôles enfants et recalcule le statut touched de tous les contrôles parents.

```ts
// Reset form state after successful submission
onSubmitSuccess() {
  this.form.markAsUntouched();
  this.form.markAsPristine();
}
```

**[`markAsDirty`](api/forms/FormControl#markAsDirty)** — Marque un contrôle ou un formulaire comme modifié (dirty), ce qui signifie que la valeur a changé. Se propage par défaut aux contrôles parents.

```ts
// Mark programmatically changed values as modified
autofillAddress() {
  const previousAddress = getAddress();
  this.form.patchValue(previousAddress, { emitEvent: false });
  this.form.markAsDirty();
}
```

**[`markAsPristine`](api/forms/FormControl#markAsPristine)** — Marque un contrôle ou un formulaire comme intact (pristine). Marque tous les contrôles enfants comme intacts et recalcule le statut pristine de tous les contrôles parents.

```ts
// Reset pristine state after saving to track new changes
saveForm() {
  this.api.save(this.form.value).subscribe(() => {
    this.form.markAsPristine();
  });
}
```

**[`markAllAsDirty`](api/forms/FormControl#markAllAsDirty)** — Marque le contrôle ou le formulaire et tous ses contrôles descendants comme modifiés (dirty).

```ts
// Mark imported data as dirty
loadData(data: FormData) {
  this.form.patchValue(data);
  this.form.markAllAsDirty();
}
```

**[`markAllAsTouched`](api/forms/FormControl#markAllAsTouched)** — Marque le contrôle ou le formulaire et tous ses contrôles descendants comme touchés. Utile pour afficher les erreurs de validation sur l'ensemble du formulaire.

```ts
// Show all validation errors before submission
onSubmit() {
  if (this.form.invalid) {
    this.form.markAllAsTouched();
    return;
  }
  this.saveForm();
}
```

## Contrôler l'émission et la propagation des événements {#controlling-event-emission-and-propagation}

Quand vous mettez à jour des contrôles de formulaire par programmation, vous contrôlez précisément la manière dont les modifications se propagent dans la hiérarchie du formulaire et si des événements sont émis.

### Comprendre l'émission des événements {#understanding-event-emission}

Par défaut (`emitEvent: true`), toute modification d'un contrôle émet des événements via les observables `valueChanges` et `statusChanges`. Définir `emitEvent: false` supprime ces émissions, ce qui est utile pour définir des valeurs par programmation sans déclencher de comportement réactif comme la sauvegarde automatique, pour éviter des mises à jour circulaires entre contrôles, ou pour effectuer des mises à jour groupées où les événements ne doivent être émis qu'une seule fois à la fin.

```ts
@Component({/* ... */})
export class BlogPostEditor {
  postForm = new FormGroup({
    title: new FormControl(''),
    content: new FormControl(''),
  });

constructor() {
    // Auto-save draft every time user types
    this.postForm.valueChanges.subscribe((formValue) => {
      this.autosaveDraft(formValue);
    });
  }

loadExistingDraft(savedDraft: {title: string; content: string}) {
    // Restore draft without triggering auto-save
    this.postForm.setValue(savedDraft, {emitEvent: false});
  }
}
```

### Comprendre le contrôle de la propagation {#understanding-propagation-control}

Par défaut (`onlySelf: false`), les mises à jour se répercutent sur les contrôles parents, dont les valeurs et le statut de validation sont recalculés. Définir `onlySelf: true` limite la mise à jour au contrôle courant et empêche la notification du parent. C'est utile pour les opérations groupées où vous voulez déclencher manuellement une seule fois la mise à jour du parent.

```ts
updatePostalCodeValidator(country: string) {
  const postal = this.addressForm.get('postalCode');

const validators = country === 'US'
    ? [Validators.maxLength(5)]
    : [Validators.maxLength(7)];

postal.setValidators(validators);
  postal.updateValueAndValidity({ onlySelf: true, emitEvent: false });
}
```

HELPFUL: Pour gérer dynamiquement les validateurs à l'exécution, consultez la section [Gérer dynamiquement les validateurs dans les reactive forms](guide/forms/form-validation#managing-validators-dynamically-in-reactive-forms) du guide Validation de formulaire.

## Fonctions utilitaires pour affiner les types de contrôles de formulaire {#utility-functions-for-narrowing-form-control-types}

Angular fournit quatre fonctions utilitaires qui aident à déterminer le type concret d'un `AbstractControl`. Ces fonctions agissent comme des **type guards** et affinent le type du contrôle quand elles renvoient `true`, ce qui vous permet d'accéder en toute sécurité aux propriétés propres au sous-type dans le même bloc.

Ces helpers sont particulièrement utiles dans les **validateurs personnalisés**, où la signature de la fonction reçoit un `AbstractControl`, alors que la logique est destinée à un type de contrôle précis.

```ts
import {AbstractControl, isFormArray} from '@angular/forms';

export function positiveValues(control: AbstractControl) {
  if (!isFormArray(control)) {
    return null; // Not a FormArray: validator is not applicable.
  }

// Safe to access FormArray-specific API after narrowing.
  const hasNegative = control.controls.some((c) => c.value < 0);
  return hasNegative ? {positiveValues: true} : null;
}
```

## Résumé de l'API des reactive forms {#reactive-forms-api-summary}

Le tableau suivant liste les classes de base et les services utilisés pour créer et gérer les contrôles de formulaire des reactive forms.
Pour le détail complet de la syntaxe, consultez la documentation de référence de l'API du [package Forms](api#angular_forms 'API reference').

### Classes {#classes}

| Classe             | Détails |
| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AbstractControl` | La classe de base abstraite des classes concrètes de contrôle de formulaire `FormControl`, `FormGroup` et `FormArray`. Elle fournit leurs comportements et propriétés communs. |
| `FormControl`     | Gère la valeur et le statut de validité d'un contrôle de formulaire individuel. Il correspond à un contrôle de formulaire HTML comme `<input>` ou `<select>`. |
| `FormGroup`       | Gère la valeur et l'état de validité d'un groupe d'instances d'`AbstractControl`. Les propriétés du groupe incluent ses contrôles enfants. Le formulaire de premier niveau de votre composant est un `FormGroup`. |
| `FormArray`       | Gère la valeur et l'état de validité d'un tableau indexé numériquement d'instances d'`AbstractControl`. |
| `FormBuilder`     | Un service injectable qui fournit des méthodes de fabrique pour créer des instances de contrôles. |
| `FormRecord`      | Suit la valeur et l'état de validité d'une collection d'instances de `FormControl`, qui ont toutes le même type de valeur. |

### Directives {#directives}

| Directive              | Détails |
| :--------------------- | :----------------------------------------------------------------------------------------- |
| `FormControlDirective` | Synchronise une instance autonome de `FormControl` avec un élément de contrôle de formulaire. |
| `FormControlName`      | Synchronise par son nom un `FormControl` d'une instance existante de `FormGroup` avec un élément de contrôle de formulaire. |
| `FormGroupDirective`   | Synchronise une instance existante de `FormGroup` avec un élément du DOM. |
| `FormGroupName`        | Synchronise une instance imbriquée de `FormGroup` avec un élément du DOM. |
| `FormArrayName`        | Synchronise une instance imbriquée de `FormArray` avec un élément du DOM. |
| `FormArrayDirective`   | Synchronise une instance autonome de `FormArray` avec un élément du DOM. |
# Formulaires typés

Depuis Angular 14, les reactive forms sont strictement typés par défaut.

Pour suivre ce guide, vous devez déjà connaître les [reactive forms d'Angular](guide/forms/reactive-forms).

## Présentation des formulaires typés {#overview-of-typed-forms}

<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" title="Les formulaires typés dans Angular" />

Avec les reactive forms d'Angular, vous spécifiez explicitement un _model de formulaire_. Pour prendre un exemple simple, considérez ce formulaire de connexion basique :

```ts
const login = new FormGroup({
  email: new FormControl(''),
  password: new FormControl(''),
});
```

Angular fournit de nombreuses API pour interagir avec ce `FormGroup`. Par exemple, vous pouvez appeler `login.value`, `login.controls`, `login.patchValue`, etc. (Pour la référence complète de l'API, consultez la [documentation de l'API](api/forms/FormGroup).)

Dans les versions précédentes d'Angular, la plupart de ces API incluaient `any` quelque part dans leurs types, et interagir avec la structure des contrôles, ou avec les valeurs elles-mêmes, n'était pas sûr au niveau du typage. Par exemple, vous pouviez écrire le code invalide suivant :

```ts
const emailDomain = login.value.email.domain;
```

Avec des reactive forms strictement typés, le code ci-dessus ne compile pas, car `email` n'a pas de propriété `domain`.

En plus de cette sûreté supplémentaire, les types apportent diverses autres améliorations, comme une meilleure autocomplétion dans les IDE et un moyen explicite de spécifier la structure du formulaire.

Ces améliorations ne s'appliquent actuellement qu'aux _reactive_ forms (pas aux [_template-driven_ forms](guide/forms/template-driven-forms)).

## Formulaires non typés {#untyped-forms}

Les formulaires non typés sont toujours pris en charge et continueront de fonctionner comme avant. Pour les utiliser, vous devez importer les symboles `Untyped` depuis `@angular/forms` :

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

Chaque symbole `Untyped` a exactement la même sémantique que dans les versions précédentes d'Angular. En retirant les préfixes `Untyped`, vous pouvez activer les types de manière progressive.

## `FormControl` : premiers pas {#formcontrol-getting-started}

Le formulaire le plus simple possible se compose d'un seul contrôle :

```ts
const email = new FormControl('angularrox@gmail.com');
```

Le type de ce contrôle sera automatiquement inféré comme `FormControl<string|null>`. TypeScript appliquera automatiquement ce type dans toute l'[API `FormControl`](api/forms/FormControl), par exemple `email.value`, `email.valueChanges` et `email.setValue(...)`.

### Nullabilité {#nullability}

Vous vous demandez peut-être : pourquoi le type de ce contrôle inclut-il `null` ? C'est parce que le contrôle peut devenir `null` à tout moment, en appelant reset :

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

TypeScript vous obligera à toujours gérer la possibilité que le contrôle soit devenu `null`. Si vous voulez rendre ce contrôle non nullable, vous pouvez utiliser l'option `nonNullable`. Le contrôle sera alors réinitialisé à sa valeur initiale, au lieu de `null` :

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

Pour rappel, cette option modifie le comportement de votre formulaire à l'exécution quand `.reset()` est appelé, et doit être activée avec précaution.

### Spécifier un type explicite {#specifying-an-explicit-type}

Il est possible de spécifier le type, au lieu de s'appuyer sur l'inférence. Considérez un contrôle initialisé à `null`. Comme la valeur initiale est `null`, TypeScript inférera `FormControl<null>`, ce qui est plus restreint que ce que nous voulons.

```ts
const email = new FormControl(null);
email.setValue('angularrox@gmail.com'); // Error!
```

Pour éviter cela, nous spécifions explicitement le type `string|null` :

```ts
const email = new FormControl<string | null>(null);
email.setValue('angularrox@gmail.com');
```

## `FormArray` : collections dynamiques et homogènes {#formarray-dynamic-homogenous-collections}

Un `FormArray` contient une liste ouverte de contrôles. Le paramètre de type correspond au type de chaque contrôle interne :

```ts
const names = new FormArray([new FormControl('Alex')]);
names.push(new FormControl('Jess'));
```

Passez un tableau de contrôles à `aliases.push()` quand vous devez ajouter plusieurs entrées à la fois.

```ts
const aliases = new FormArray([new FormControl('ng')]);
aliases.push([new FormControl('ngDev'), new FormControl('ngAwesome')]);
```

Les contrôles internes de ce `FormArray` auront le type `FormControl<string|null>`.

Si vous voulez avoir plusieurs types d'éléments différents dans le tableau, vous devez utiliser `UntypedFormArray`, car TypeScript ne peut pas inférer quel type d'élément se trouvera à quelle position.

Un `FormArray` fournit aussi une méthode `clear()` pour retirer tous les contrôles qu'il contient :

```ts
const aliases = new FormArray([new FormControl('ngDev'), new FormControl('ngAwesome')]);
aliases.clear();
console.log(aliases.length); // 0
```

## `FormGroup` et `FormRecord` {#formgroup-and-formrecord}

Angular fournit le type `FormGroup` pour les formulaires dont l'ensemble de clés est énuméré, et un type appelé `FormRecord` pour les groupes ouverts ou dynamiques.

### Valeurs partielles {#partial-values}

Reprenons un formulaire de connexion :

```ts
const login = new FormGroup({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});
```

Sur n'importe quel `FormGroup`, il est [possible de désactiver des contrôles](api/forms/FormGroup). Un contrôle désactivé n'apparaît pas dans la valeur du groupe.

Par conséquent, le type de `login.value` est `Partial<{email: string, password: string}>`. Le `Partial` de ce type signifie que chaque membre peut être undefined.

Plus précisément, le type de `login.value.email` est `string|undefined`, et TypeScript vous obligera à gérer la valeur potentiellement `undefined` (si vous avez activé `strictNullChecks`).

Si vous voulez accéder à la valeur _en incluant_ les contrôles désactivés, et ainsi éviter les champs potentiellement `undefined`, vous pouvez utiliser `login.getRawValue()`.

### Contrôles optionnels et groupes dynamiques {#optional-controls-and-dynamic-groups}

Certains formulaires ont des contrôles qui peuvent être présents ou non, et qui peuvent être ajoutés et retirés à l'exécution. Vous pouvez représenter ces contrôles avec des _champs optionnels_ :

```ts
interface LoginForm {
  email: FormControl<string>;
  password?: FormControl<string>;
}

const login = new FormGroup<LoginForm>({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});

Dans ce formulaire, nous spécifions explicitement le type, ce qui nous permet de rendre le contrôle `password` optionnel. TypeScript garantira que seuls les contrôles optionnels peuvent être ajoutés ou retirés.

### `FormRecord` {#formrecord}

Certains usages de `FormGroup` ne correspondent pas au schéma ci-dessus, car les clés ne sont pas connues à l'avance. La classe `FormRecord` est conçue pour ce cas :

```ts
const addresses = new FormRecord<FormControl<string | null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

N'importe quel contrôle de type `string|null` peut être ajouté à ce `FormRecord`.

Si vous avez besoin d'un `FormGroup` à la fois dynamique (ouvert) et hétérogène (les contrôles sont de types différents), aucune amélioration de la sûreté du typage n'est possible, et vous devez utiliser `UntypedFormGroup`.

Un `FormRecord` peut aussi être construit avec le `FormBuilder` :

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```

## `FormBuilder` et `NonNullableFormBuilder` {#formbuilder-and-nonnullableformbuilder}

La classe `FormBuilder` a elle aussi été mise à jour pour prendre en charge les nouveaux types, de la même manière que dans les exemples ci-dessus.

De plus, un builder supplémentaire est disponible : `NonNullableFormBuilder`. Ce type est un raccourci pour spécifier `{nonNullable: true}` sur chaque contrôle, et peut éliminer beaucoup de code répétitif dans les grands formulaires non nullables. Vous pouvez y accéder via la propriété `nonNullable` d'un `FormBuilder` :

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

Dans l'exemple ci-dessus, les deux contrôles internes seront non nullables (c'est-à-dire que `nonNullable` sera défini).

Vous pouvez aussi l'injecter sous le nom `NonNullableFormBuilder`.
# Créer un template-driven form

Ce tutoriel vous montre comment créer un template-driven form. Les éléments de contrôle du formulaire sont liés à des propriétés de données dotées d'une validation des saisies. La validation des saisies aide à préserver l'intégrité des données, et le style améliore l'expérience utilisateur.

Les template-driven forms utilisent le [two-way binding](guide/templates/two-way-binding) pour mettre à jour le modèle de données du composant quand des modifications sont faites dans le template, et inversement.
Angular prend en charge deux approches de conception pour les formulaires interactifs. Les template-driven forms vous permettent d'utiliser des directives spécifiques aux formulaires dans votre template Angular. Les reactive forms proposent une approche pilotée par le modèle pour construire des formulaires.

Les template-driven forms sont un excellent choix pour les formulaires petits ou simples, tandis que les reactive forms passent mieux à l'échelle et conviennent aux formulaires complexes. Pour une comparaison des deux approches, consultez [Choisir une approche](guide/forms#choosing-an-approach)
Vous pouvez créer presque n'importe quel type de formulaire avec un template Angular : formulaires de connexion, formulaires de contact et à peu près tous les formulaires métier.
Vous pouvez disposer les contrôles de façon créative et les lier aux données de votre modèle objet.
Vous pouvez définir des règles de validation et afficher les erreurs de validation, autoriser sous condition la saisie dans certains contrôles, déclencher un retour visuel intégré, et bien plus encore.

## Objectifs {#objectives}

Ce tutoriel vous apprend à :

- Créer un formulaire Angular avec un composant et un template
- Utiliser `ngModel` pour créer des two-way bindings qui lisent et écrivent les valeurs des contrôles de saisie
- Fournir un retour visuel grâce à des classes CSS spéciales qui suivent l'état des contrôles
- Afficher les erreurs de validation aux utilisateurs et autoriser sous condition la saisie dans les contrôles de formulaire selon l'état du formulaire
- Partager des informations entre éléments HTML à l'aide de [variables de référence de template](guide/templates/variables#template-reference-variables)

## Créer un template-driven form {#build-a-template-driven-form}

Les template-driven forms s'appuient sur des directives définies dans le `FormsModule`.

| Directives     | Détails                                                                                                                                                                                                                                                                         |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NgModel`      | Réconcilie les changements de valeur de l'élément de formulaire associé avec les changements du modèle de données, ce qui vous permet de répondre aux saisies de l'utilisateur avec de la validation et de la gestion d'erreurs.                                                     |
| `NgForm`       | Crée une instance `FormGroup` de premier niveau et la lie à un élément `<form>` pour suivre la valeur agrégée du formulaire et son état de validation. Dès que vous importez `FormsModule`, cette directive est active par défaut sur toutes les balises `<form>`. Vous n'avez pas besoin d'ajouter de selector particulier. |
| `NgModelGroup` | Crée une instance `FormGroup` et la lie à un élément du DOM.                                                                                                                                                                                                                      |

### Aperçu des étapes {#step-overview}

Au cours de ce tutoriel, vous liez un exemple de formulaire à des données et gérez les saisies de l'utilisateur en suivant les étapes ci-dessous.

1. Créez le formulaire de base.
   - Définissez un exemple de modèle de données
   - Incluez l'infrastructure nécessaire, comme le `FormsModule`
1. Liez les contrôles de formulaire aux propriétés de données à l'aide de la directive `ngModel` et de la syntaxe du two-way binding.
   - Examinez comment `ngModel` signale l'état des contrôles à l'aide de classes CSS
   - Nommez les contrôles pour les rendre accessibles à `ngModel`
1. Suivez la validité des saisies et l'état des contrôles avec `ngModel`.
   - Ajoutez du CSS personnalisé pour fournir un retour visuel sur l'état
   - Affichez et masquez les messages d'erreur de validation
1. Répondez à un événement natif de clic sur un bouton HTML en ajoutant des données au modèle.
1. Gérez la soumission du formulaire à l'aide de la propriété d'output [`ngSubmit`](api/forms/NgForm#ngSubmit) du formulaire.
   - Désactivez le bouton **Submit** tant que le formulaire n'est pas valide
   - Après la soumission, remplacez le formulaire terminé par un autre contenu sur la page

## Créer le formulaire {#build-the-form}

1. L'application d'exemple fournie crée la classe `Actor`, qui définit le modèle de données reflété dans le formulaire.

<docs-code header="actor.ts" language="typescript" path="adev/src/content/examples/forms/src/app/actor.ts"/>

1. La mise en page et les détails du formulaire sont définis dans la classe `ActorFormComponent`.

<docs-code header="actor-form.component.ts (v1)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="v1"/>

La valeur « app-actor-form » du `selector` du composant signifie que vous pouvez placer ce formulaire dans un template parent avec la balise `<app-actor-form>`.

1. Le code suivant crée une nouvelle instance d'acteur, afin que le formulaire initial puisse afficher un exemple d'acteur.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="Marilyn"/>

Cette démo utilise des données factices pour `model` et `skills`.
   Dans une vraie application, vous injecteriez un service de données pour obtenir et enregistrer de vraies données, ou vous exposeriez ces propriétés sous forme d'inputs et d'outputs.

1. Le composant active la fonctionnalité Forms en important le module `FormsModule`.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="imports"/>

1. Le formulaire est affiché dans la mise en page de l'application définie par le template du composant racine.

<docs-code header="app.component.html" language="html" path="adev/src/content/examples/forms/src/app/app.component.html"/>

Le template initial définit la mise en page d'un formulaire avec deux groupes de formulaire et un bouton de soumission.
   Les groupes de formulaire correspondent à deux propriétés du modèle de données Actor : name et studio.
   Chaque groupe comporte un libellé et une zone de saisie.
   - L'élément de contrôle `<input>` **Name** possède l'attribut HTML5 `required`
   - L'élément de contrôle `<input>` **Studio** ne l'a pas, car `studio` est facultatif

Le bouton **Submit** porte quelques classes de style.
   À ce stade, la mise en page du formulaire est entièrement en HTML5 pur, sans binding ni directive.

1. L'exemple de formulaire utilise quelques classes de style de [Twitter Bootstrap](https://getbootstrap.com/css) : `container`, `form-group`, `form-control` et `btn`.
   Pour utiliser ces styles, la feuille de style de l'application importe la library.

<docs-code header="styles.css" path="adev/src/content/examples/forms/src/styles.1.css"/>

1. Le formulaire exige que la compétence d'un acteur soit choisie dans une liste prédéfinie de `skills` gérée en interne dans `ActorFormComponent`.
   La boucle Angular `@for` parcourt les valeurs de données pour remplir l'élément `<select>`.

<docs-code header="actor-form.component.html (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="skills"/>

Si vous lancez l'application maintenant, vous voyez la liste des compétences dans le contrôle de sélection.
Les éléments de saisie ne sont pas encore liés à des valeurs de données ni à des événements : ils sont donc encore vides et n'ont aucun comportement.

## Lier les contrôles de saisie aux propriétés de données {#bind-input-controls-to-data-properties}

L'étape suivante consiste à lier les contrôles de saisie aux propriétés `Actor` correspondantes avec le two-way binding, afin qu'ils répondent aux saisies de l'utilisateur en mettant à jour le modèle de données, et qu'ils répondent aussi aux changements programmatiques des données en mettant à jour l'affichage.

La directive `ngModel` déclarée dans le `FormsModule` vous permet de lier les contrôles de votre template-driven form aux propriétés de votre modèle de données.
Quand vous incluez la directive avec la syntaxe du two-way binding, `[(ngModel)]`, Angular peut suivre la valeur du contrôle et les interactions de l'utilisateur avec celui-ci, et garder la vue synchronisée avec le model.

1. Modifiez le fichier de template `actor-form.component.html`.
1. Trouvez la balise `<input>` à côté du libellé **Name**.
1. Ajoutez la directive `ngModel` avec la syntaxe du two-way binding `[(ngModel)]="..."`.

<docs-code header="actor-form.component.html (extrait)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModelName-1"/>

HELPFUL: Cet exemple comporte une interpolation de diagnostic temporaire après chaque balise input, `{{model.name}}`, pour afficher la valeur actuelle de la propriété correspondante. Le commentaire vous rappelle de supprimer les lignes de diagnostic quand vous avez fini d'observer le two-way binding en action.

### Accéder à l'état global du formulaire {#access-the-overall-form-status}

Quand vous avez importé le `FormsModule` dans votre composant, Angular a automatiquement créé et attaché une directive [NgForm](api/forms/NgForm) à la balise `<form>` du template (car `NgForm` a le selector `form`, qui correspond aux éléments `<form>`).

Pour accéder au `NgForm` et à l'état global du formulaire, déclarez une [variable de référence de template](guide/templates/variables#template-reference-variables).

1. Modifiez le fichier de template `actor-form.component.html`.
1. Ajoutez à la balise `<form>` une variable de référence de template, `#actorForm`, et définissez sa valeur comme suit.

<docs-code header="actor-form.component.html (extrait)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="template-variable"/>

La variable de template `actorForm` est désormais une référence à l'instance de la directive `NgForm` qui gouverne le formulaire dans son ensemble.

1. Lancez l'application.
1. Commencez à taper dans la zone de saisie **Name**.

À mesure que vous ajoutez et supprimez des caractères, vous les voyez apparaître et disparaître du modèle de données.

La ligne de diagnostic qui affiche les valeurs interpolées montre que les valeurs circulent réellement de la zone de saisie vers le model, et inversement.

### Nommer les éléments de contrôle {#naming-control-elements}

Quand vous utilisez `[(ngModel)]` sur un élément, vous devez définir un attribut `name` pour cet élément.
Angular utilise le nom attribué pour enregistrer l'élément auprès de la directive `NgForm` attachée à l'élément `<form>` parent.

L'exemple a ajouté un attribut `name` à l'élément `<input>` et l'a défini à « name », ce qui est logique pour le nom de l'acteur.
N'importe quelle valeur unique convient, mais un nom descriptif est utile.

1. Ajoutez des bindings `[(ngModel)]` et des attributs `name` similaires à **Studio** et **Skill**.
1. Vous pouvez maintenant supprimer les messages de diagnostic qui affichent les valeurs interpolées.
1. Pour vérifier que le two-way binding fonctionne pour tout le modèle d'acteur, ajoutez en haut du template du composant un nouveau binding de texte avec le pipe [`json`](api/common/JsonPipe), qui sérialise les données en chaîne de caractères.

Après ces modifications, le template du formulaire devrait ressembler à ceci :

<docs-code header="actor-form.component.html (extrait)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModel-2"/>

Vous remarquerez que :

- Chaque élément `<input>` possède une propriété `id`.
  Elle est utilisée par l'attribut `for` de l'élément `<label>` pour associer le libellé à son contrôle de saisie.
  Il s'agit d'une [fonctionnalité HTML standard](https://developer.mozilla.org/docs/Web/HTML/Element/label).

- Chaque élément `<input>` possède aussi la propriété `name` requise, qu'Angular utilise pour enregistrer le contrôle auprès du formulaire.

Une fois les effets observés, vous pouvez supprimer le binding de texte `{{ model | json }}`.

## Suivre l'état du formulaire {#track-form-states}

Angular applique la classe `ng-submitted` aux éléments `form` une fois le formulaire soumis. Cette classe peut servir à modifier le style du formulaire après sa soumission.

## Suivre l'état des contrôles {#track-control-states}

Ajouter la directive `NgModel` à un contrôle lui ajoute des noms de classes qui décrivent son état.
Ces classes peuvent servir à modifier le style d'un contrôle selon son état.

Le tableau suivant décrit les noms de classes qu'Angular applique selon l'état du contrôle.

Angular applique aussi la classe `ng-submitted` aux éléments `form` lors de la soumission, mais pas aux contrôles à l'intérieur de l'élément `form`.

Vous utilisez ces classes CSS pour définir les styles de votre contrôle selon son état.

### Observer l'état des contrôles {#observe-control-states}

Pour voir comment le framework ajoute et retire les classes, ouvrez les outils de développement du navigateur et inspectez l'élément `<input>` qui représente le nom de l'acteur.

1. À l'aide des outils de développement de votre navigateur, trouvez l'élément `<input>` qui correspond à la zone de saisie **Name**.
   Vous pouvez voir que l'élément possède plusieurs classes CSS en plus de « form-control ».

1. Au premier affichage, les classes indiquent que sa valeur est valide, que la valeur n'a pas été modifiée depuis l'initialisation ou la réinitialisation, et que le contrôle n'a pas été visité depuis l'initialisation ou la réinitialisation.

```html
<input class="form-control ng-untouched ng-pristine ng-valid" />
   ```

1. Effectuez les actions suivantes sur la zone `<input>` **Name** et observez les classes qui apparaissent.
   - Regardez sans toucher.
     Les classes indiquent qu'il est non touché, intact (pristine) et valide.

- Cliquez dans la zone du nom, puis cliquez en dehors.
     Le contrôle a maintenant été visité, et l'élément porte la classe `ng-touched` au lieu de la classe `ng-untouched`.

- Ajoutez des barres obliques à la fin du nom.
     Il est maintenant touché et modifié (dirty).

- Effacez le nom.
     La valeur devient alors invalide, donc la classe `ng-invalid` remplace la classe `ng-valid`.

### Créer un retour visuel pour les états {#create-visual-feedback-for-states}

La paire `ng-valid`/`ng-invalid` est particulièrement intéressante, car vous voulez envoyer un
signal visuel fort quand les valeurs sont invalides.
Vous voulez aussi signaler les champs obligatoires.

Vous pouvez signaler à la fois les champs obligatoires et les données invalides avec une barre colorée
à gauche de la zone de saisie.

Pour modifier l'apparence de cette façon, suivez les étapes ci-dessous.

1. Ajoutez des définitions pour les classes CSS `ng-*`.
1. Ajoutez ces définitions de classes dans un nouveau fichier `forms.css`.
1. Ajoutez le nouveau fichier au projet, au même niveau que `index.html` :

<docs-code header="forms.css" language="css" path="adev/src/content/examples/forms/src/assets/forms.css"/>

1. Dans le fichier `index.html`, modifiez la balise `<head>` pour inclure la nouvelle feuille de style.

<docs-code header="index.html (styles)" path="adev/src/content/examples/forms/src/index.html" region="styles"/>

### Afficher et masquer les messages d'erreur de validation {#show-and-hide-validation-error-messages}

La zone de saisie **Name** est obligatoire, et la vider fait passer la barre au rouge.
Cela indique que quelque chose ne va pas, mais l'utilisateur ne sait pas quoi ni comment y remédier.
Vous pouvez fournir un message utile en vérifiant l'état du contrôle et en y réagissant.

La liste déroulante **Skill** est aussi obligatoire, mais elle n'a pas besoin de ce type de gestion d'erreurs, car la liste de sélection limite déjà le choix à des valeurs valides.

Pour définir et afficher un message d'erreur au moment opportun, suivez les étapes ci-dessous.

<docs-workflow>
<docs-step title="Ajouter une référence locale à l'input {#add-a-local-reference-to-the-input}">
Ajoutez à la balise `input` une variable de référence de template qui vous permet d'accéder au contrôle Angular de la zone de saisie depuis le template. Dans l'exemple, la variable est `#name="ngModel"`.

La variable de référence de template (`#name`) est définie à `"ngModel"`, car c'est la valeur de la propriété [`NgModel.exportAs`](api/core/Directive#exportAs). Cette propriété indique à Angular comment relier une variable de référence à une directive.
</docs-step>

<docs-step title="Ajouter le message d'erreur {#add-the-error-message}">
Ajoutez un `<div>` qui contient un message d'erreur adapté.
</docs-step>

<docs-step title="Rendre le message d'erreur conditionnel {#make-the-error-message-conditional}">
Affichez ou masquez le message d'erreur en liant des propriétés du contrôle `name` à la propriété `hidden` de l'élément `<div>` du message.
</docs-step>

<docs-code header="actor-form.component.html (hidden-error-msg)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="hidden-error-msg"/>

<docs-step title="Ajouter un message d'erreur conditionnel au nom {#add-a-conditional-error-message-to-name}">
Ajoutez un message d'erreur conditionnel à la zone de saisie `name`, comme dans l'exemple suivant.

<docs-code header="actor-form.component.html (extrait)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="name-with-error-msg"/>
</docs-step>
</docs-workflow>
Dans cet exemple, vous masquez le message quand le contrôle est soit valide, soit _intact (pristine)_.
Intact signifie que l'utilisateur n'a pas modifié la valeur depuis son affichage dans ce formulaire.
Si vous ignorez l'état `pristine`, vous ne masqueriez le message que lorsque la valeur est valide.
Si vous arrivez dans ce composant avec un nouvel acteur vierge ou un acteur invalide, vous verrez le message d'erreur immédiatement, avant même d'avoir fait quoi que ce soit.

Vous voudrez peut-être que le message ne s'affiche que lorsque l'utilisateur effectue une modification invalide.
Masquer le message tant que le contrôle est dans l'état `pristine` permet d'atteindre cet objectif.
Vous verrez l'importance de ce choix quand vous ajouterez un nouvel acteur au formulaire à l'étape suivante.
## Ajouter un nouvel acteur {#add-a-new-actor}

Cet exercice montre comment répondre à un événement natif de clic sur un bouton HTML en ajoutant des données au modèle.
Pour permettre aux utilisateurs du formulaire d'ajouter un nouvel acteur, vous allez ajouter un bouton **New Actor** qui répond à un événement de clic.

1. Dans le template, placez un élément `<button>` « New Actor » en bas du formulaire.
1. Dans le fichier du composant, ajoutez la méthode de création d'acteur au modèle de données des acteurs.

<docs-code header="actor-form.component.ts (méthode New Actor)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="new-actor"/>

1. Liez l'événement de clic du bouton à une méthode de création d'acteur, `newActor()`.

<docs-code header="actor-form.component.html (bouton New Actor)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="new-actor-button-no-reset"/>

1. Relancez l'application et cliquez sur le bouton **New Actor**.

Le formulaire se vide, et les barres _obligatoire_ à gauche de la zone de saisie sont rouges, ce qui indique que les propriétés `name` et `skill` sont invalides.
   Remarquez que les messages d'erreur sont masqués.
   C'est parce que le formulaire est intact : vous n'avez encore rien modifié.

1. Saisissez un nom et cliquez à nouveau sur **New Actor**.

L'application affiche maintenant un message d'erreur `Name is required`, car la zone de saisie n'est plus intacte.
   Le formulaire se souvient que vous avez saisi un nom avant de cliquer sur **New Actor**.

1. Pour rétablir l'état intact des contrôles du formulaire, effacez tous les indicateurs de façon impérative en appelant la méthode `reset()` du formulaire après avoir appelé la méthode `newActor()`.

<docs-code header="actor-form.component.html (réinitialiser le formulaire)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="new-actor-button-form-reset"/>

Désormais, cliquer sur **New Actor** réinitialise à la fois le formulaire et les indicateurs de ses contrôles.

## Soumettre le formulaire avec `ngSubmit` {#submit-the-form-with-ngsubmit}

L'utilisateur doit pouvoir soumettre ce formulaire après l'avoir rempli.
Le bouton **Submit** en bas du formulaire ne fait rien par lui-même, mais il déclenche un événement de soumission du formulaire du fait de son type (`type="submit"`).

Pour répondre à cet événement, suivez les étapes ci-dessous.

<docs-workflow>

<docs-step title="Écouter ngOnSubmit {#listen-to-ngonsubmit}">
Liez la propriété d'événement [`ngSubmit`](api/forms/NgForm#ngSubmit) du formulaire à la méthode `onSubmit()` du composant actor-form.

<docs-code header="actor-form.component.html (ngSubmit)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngSubmit"/>
</docs-step>

<docs-step title="Lier la propriété disabled {#bind-the-disabled-property}">
Utilisez la variable de référence de template `#actorForm` pour accéder au formulaire qui contient le bouton **Submit** et créer un event binding.

Vous allez lier la propriété du formulaire qui indique sa validité globale à la propriété `disabled` du bouton **Submit**.

<docs-code header="actor-form.component.html (submit-button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submit-button"/>
</docs-step>

<docs-step title="Lancer l'application {#run-the-application}">
Remarquez que le bouton est activé, même s'il ne fait encore rien d'utile.
</docs-step>

<docs-step title="Supprimer la valeur de Name {#delete-the-name-value}">
Cela enfreint la règle « obligatoire » : le message d'erreur s'affiche, et remarquez que le bouton **Submit** est aussi désactivé.

Vous n'avez pas eu à relier explicitement l'état activé du bouton à la validité du formulaire.
Le `FormsModule` l'a fait automatiquement quand vous avez défini une variable de référence de template sur l'élément de formulaire enrichi, puis fait référence à cette variable dans le contrôle du bouton.
</docs-step>
</docs-workflow>

### Répondre à la soumission du formulaire {#respond-to-form-submission}

Pour montrer une réponse à la soumission du formulaire, vous pouvez masquer la zone de saisie des données et afficher autre chose à sa place.

<docs-workflow>
<docs-step title="Envelopper le formulaire {#wrap-the-form}">
Enveloppez tout le formulaire dans un `<div>` et liez sa propriété `hidden` à la propriété `ActorFormComponent.submitted`.

<docs-code header="actor-form.component.html (extrait)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="edit-div"/>

Le formulaire principal est visible dès le départ, car la propriété `submitted` vaut false jusqu'à ce que vous soumettiez le formulaire, comme le montre ce fragment de `ActorFormComponent` :

<docs-code header="actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="submitted"/>

Quand vous cliquez sur le bouton **Submit**, l'indicateur `submitted` passe à true et le formulaire disparaît.
</docs-step>

<docs-step title="Ajouter l'état soumis {#add-the-submitted-state}">
Pour afficher autre chose pendant que le formulaire est à l'état soumis, ajoutez le HTML suivant sous le nouveau `<div>` d'enveloppe.

<docs-code header="actor-form.component.html (extrait)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submitted"/>

Ce `<div>`, qui affiche un acteur en lecture seule avec des bindings d'interpolation, n'apparaît que lorsque le composant est à l'état soumis.

L'affichage alternatif comprend un bouton _Edit_ dont l'événement de clic est lié à une expression qui efface l'indicateur `submitted`.
</docs-step>

<docs-step title="Tester le bouton Edit {#test-the-edit-button}">
Cliquez sur le bouton *Edit* pour revenir à l'affichage du formulaire modifiable.
</docs-step>
</docs-workflow>

## Résumé {#summary}

Le formulaire Angular présenté sur cette page tire parti des fonctionnalités suivantes
du framework pour prendre en charge la modification des données, la validation, et plus encore.

- Un template de formulaire HTML Angular
- Une classe de composant de formulaire avec un décorateur `@Component`
- La gestion de la soumission du formulaire par un binding sur la propriété d'événement `NgForm.ngSubmit`
- Des variables de référence de template comme `#actorForm` et `#name`
- La syntaxe `[(ngModel)]` pour le two-way binding
- L'utilisation d'attributs `name` pour la validation et le suivi des changements des éléments de formulaire
- La propriété `valid` de la variable de référence sur les contrôles de saisie, qui indique si un contrôle est valide ou doit afficher des messages d'erreur
- Le contrôle de l'état activé du bouton **Submit** par un binding sur la validité de `NgForm`
- Des classes CSS personnalisées qui fournissent aux utilisateurs un retour visuel sur les contrôles invalides

Voici le code de la version finale de l'application :
# Valider les saisies de formulaire

Vous pouvez améliorer la qualité globale des données en validant l'exactitude et la complétude des saisies de l'utilisateur.
Cette page montre comment valider les saisies de l'utilisateur depuis l'interface et afficher des messages de validation utiles, aussi bien dans les reactive forms que dans les template-driven forms.

## Valider les saisies dans les template-driven forms {#validating-input-in-template-driven-forms}

Pour ajouter de la validation à un template-driven form, ajoutez les mêmes attributs de validation que pour la [validation native des formulaires HTML](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5/Constraint_validation).
Angular utilise des directives pour faire correspondre ces attributs aux fonctions de validation du framework.

Chaque fois que la valeur d'un contrôle de formulaire change, Angular exécute la validation et génère soit une liste d'erreurs de validation qui aboutit à un statut `INVALID`, soit `null`, qui aboutit à un statut `VALID`.

Vous pouvez ensuite inspecter l'état du contrôle en exportant `ngModel` dans une variable de template locale.
L'exemple suivant exporte `NgModel` dans une variable nommée `name` :

<docs-code header="actor-form-template.component.html (name)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="name-with-error-msg"/>

Remarquez les fonctionnalités suivantes illustrées par l'exemple.

- L'élément `<input>` porte les attributs de validation HTML : `required` et `minlength`.
  Il porte aussi une directive de validateur personnalisée, `forbiddenName`.
  Pour plus d'informations, consultez la section [Validateurs personnalisés](#defining-custom-validators).

- `#name="ngModel"` exporte `NgModel` dans une variable locale nommée `name`.
  `NgModel` reflète de nombreuses propriétés de son instance de `FormControl` sous-jacente : vous pouvez donc l'utiliser dans le template pour vérifier les états du contrôle comme `valid` et `dirty`.
  Pour la liste complète des propriétés de contrôle, consultez la référence d'API [AbstractControl](api/forms/AbstractControl).
  - Le `@if` le plus externe affiche un ensemble de messages imbriqués, mais seulement si `name` est invalide et que le contrôle est soit `dirty`, soit `touched`.

- Chaque `@if` imbriqué peut présenter un message personnalisé pour l'une des erreurs de validation possibles.
    Il y a des messages pour `required`, `minlength` et `forbiddenName`.

HELPFUL: Pour éviter que le validateur n'affiche des erreurs avant que l'utilisateur ait eu l'occasion de modifier le formulaire, vérifiez l'état `dirty` ou `touched` du contrôle.

- Quand l'utilisateur modifie la valeur du champ observé, le contrôle est marqué comme modifié (dirty)
- Quand l'élément du contrôle de formulaire perd le focus, le contrôle est marqué comme touché (touched)

## Valider les saisies dans les reactive forms {#validating-input-in-reactive-forms}

Dans un reactive form, la source de vérité est la classe du composant.
Au lieu d'ajouter des validateurs via des attributs dans le template, vous ajoutez des fonctions de validation directement au model du contrôle de formulaire dans la classe du composant.
Angular appelle ensuite ces fonctions chaque fois que la valeur du contrôle change.

### Fonctions de validation {#validator-functions}

Les fonctions de validation peuvent être synchrones ou asynchrones.

| Type de validateur   | Détails |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Validateurs synchrones  | Fonctions synchrones qui prennent une instance de contrôle et renvoient immédiatement soit un ensemble d'erreurs de validation, soit `null`. Passez-les comme deuxième argument lorsque vous instanciez un `FormControl`. |
| Validateurs asynchrones | Fonctions asynchrones qui prennent une instance de contrôle et renvoient une Promise ou un Observable qui émet plus tard un ensemble d'erreurs de validation ou `null`. Passez-les comme troisième argument lorsque vous instanciez un `FormControl`. |

Pour des raisons de performances, Angular n'exécute les validateurs asynchrones que si tous les validateurs synchrones réussissent.
Chacun doit se terminer avant que les erreurs ne soient définies.

### Fonctions de validation intégrées {#built-in-validator-functions}

Vous pouvez choisir d'[écrire vos propres fonctions de validation](#defining-custom-validators), ou utiliser certains des validateurs intégrés d'Angular.

Les validateurs intégrés disponibles sous forme d'attributs dans les template-driven forms, comme `required` et `minlength`, sont tous disponibles sous forme de fonctions dans la classe `Validators`.
Pour la liste complète des validateurs intégrés, consultez la référence d'API [Validators](api/forms/Validators).

Pour transformer le formulaire d'acteur en reactive form, utilisez certains de ces mêmes
validateurs intégrés, cette fois sous forme de fonctions, comme dans l'exemple suivant.

<docs-code header="actor-form-reactive.component.ts (fonctions de validation)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" region="form-group"/>

Dans cet exemple, le contrôle `name` met en place deux validateurs intégrés, `Validators.required` et `Validators.minLength(4)`, et un validateur personnalisé, `forbiddenNameValidator`.

Tous ces validateurs sont synchrones : ils sont donc passés comme deuxième argument.
Remarquez que vous pouvez prendre en charge plusieurs validateurs en passant les fonctions sous forme de tableau.

Cet exemple ajoute aussi quelques méthodes getter.
Dans un reactive form, vous pouvez toujours accéder à n'importe quel contrôle de formulaire via la méthode `get` de son groupe parent, mais il est parfois utile de définir des getters comme raccourcis pour le template.

Si vous regardez à nouveau le template de l'input `name`, il est assez similaire à l'exemple template-driven.

<docs-code header="actor-form-reactive.component.html (name avec message d'erreur)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="name-with-error-msg"/>

Ce formulaire diffère de la version template-driven en ce qu'il n'exporte plus aucune directive. À la place, il utilise le getter `name` défini dans la classe du composant.

Remarquez que l'attribut `required` est toujours présent dans le template. Bien qu'il ne soit pas nécessaire à la validation, il doit être conservé pour des raisons d'accessibilité.

## Définir des validateurs personnalisés {#defining-custom-validators}

Les validateurs intégrés ne correspondent pas toujours exactement au cas d'usage de votre application : vous devez donc parfois créer un validateur personnalisé.

Prenez la fonction `forbiddenNameValidator` de l'exemple précédent.
Voici à quoi ressemble la définition de cette fonction.

<docs-code header="forbidden-name.directive.ts (forbiddenNameValidator)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="custom-validator"/>

La fonction est une fabrique qui prend une expression régulière pour détecter un nom interdit _spécifique_ et renvoie une fonction de validation.

Dans cet exemple, le nom interdit est « bob » : le validateur rejette donc tout nom d'acteur contenant « bob ».
Ailleurs, il pourrait rejeter « alice » ou tout nom correspondant à l'expression régulière de configuration.

La fabrique `forbiddenNameValidator` renvoie la fonction de validation configurée.
Cette fonction prend un objet contrôle Angular et renvoie _soit_ null si la valeur du contrôle est valide, _soit_ un objet d'erreur de validation.
L'objet d'erreur de validation a généralement une propriété dont le nom est la clé de validation, `'forbiddenName'`, et dont la valeur est un dictionnaire arbitraire de valeurs que vous pourriez insérer dans un message d'erreur, `{name}`.

Les validateurs asynchrones personnalisés sont similaires aux validateurs synchrones, mais ils doivent renvoyer une promise ou un observable qui émet plus tard null ou un objet d'erreur de validation.
Dans le cas d'un observable, celui-ci doit se terminer : le formulaire utilise alors la dernière valeur émise pour la validation.

### Ajouter des validateurs personnalisés aux reactive forms {#adding-custom-validators-to-reactive-forms}

Dans les reactive forms, ajoutez un validateur personnalisé en passant la fonction directement au `FormControl`.

### Ajouter des validateurs personnalisés aux template-driven forms {#adding-custom-validators-to-template-driven-forms}

Dans les template-driven forms, ajoutez au template une directive qui encapsule la fonction de validation.
Par exemple, la directive `ForbiddenValidatorDirective` correspondante sert d'enveloppe autour de `forbiddenNameValidator`.

Angular reconnaît le rôle de la directive dans le processus de validation, car la directive s'enregistre auprès du provider `NG_VALIDATORS`, comme le montre l'exemple suivant.
`NG_VALIDATORS` est un provider prédéfini avec une collection extensible de validateurs.

<docs-code header="forbidden-name.directive.ts (providers)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive-providers"/>

La classe de la directive implémente ensuite l'interface `Validator`, afin de s'intégrer facilement aux formulaires Angular.
Voici le reste de la directive, pour vous donner une idée de la façon dont l'ensemble s'articule.

<docs-code header="forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive"/>

Une fois la `ForbiddenValidatorDirective` prête, vous pouvez ajouter son selector, `appForbiddenName`, à n'importe quel élément de saisie pour l'activer.
Par exemple :

<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" region="name-input"/>

HELPFUL: Remarquez que la directive de validation personnalisée est instanciée avec `useExisting` plutôt qu'avec `useClass`.
Le validateur enregistré doit être _cette instance_ de la `ForbiddenValidatorDirective`, c'est-à-dire l'instance présente dans le formulaire dont la propriété `forbiddenName` est liée à « bob ».

Si vous remplaciez `useExisting` par `useClass`, vous enregistreriez une nouvelle instance de classe, qui n'a pas de `forbiddenName`.

## Classes CSS de statut des contrôles {#control-status-css-classes}

Angular reflète automatiquement de nombreuses propriétés des contrôles sur l'élément du contrôle de formulaire sous forme de classes CSS.
Utilisez ces classes pour styliser les éléments des contrôles de formulaire selon l'état du formulaire.
Les classes suivantes sont actuellement prises en charge.

- `.ng-valid`
- `.ng-invalid`
- `.ng-pending`
- `.ng-pristine`
- `.ng-dirty`
- `.ng-untouched`
- `.ng-touched`
- `.ng-submitted` $uniquement sur l'élément de formulaire englobant$

Dans l'exemple suivant, le formulaire d'acteur utilise les classes `.ng-valid` et `.ng-invalid` pour
définir la couleur de la bordure de chaque contrôle de formulaire.

<docs-code header="forms.css (classes de statut)" path="adev/src/content/examples/form-validation/src/assets/forms.css"/>

## Validation inter-champs {#cross-field-validation}

Un validateur inter-champs est un [validateur personnalisé](#defining-custom-validators 'Read about custom validators') qui compare les valeurs de différents champs d'un formulaire et les accepte ou les rejette en combinaison.
Par exemple, vous pouvez avoir un formulaire qui propose des options mutuellement incompatibles : l'utilisateur peut choisir A ou B, mais pas les deux.
Certaines valeurs de champs peuvent aussi dépendre d'autres ; un utilisateur pourrait n'être autorisé à choisir B que si A est également choisi.

Les exemples de validation inter-champs suivants montrent comment :

- Valider les saisies d'un reactive form ou d'un template-driven form à partir des valeurs de deux contrôles frères,
- Afficher un message d'erreur descriptif une fois que l'utilisateur a interagi avec le formulaire et que la validation a échoué.

Les exemples utilisent la validation inter-champs pour s'assurer que les acteurs ne réutilisent pas leur propre nom dans leur rôle en remplissant l'Actor Form.
Les validateurs y parviennent en vérifiant que les noms des acteurs et les rôles ne correspondent pas.

### Ajouter la validation inter-champs aux reactive forms {#adding-cross-validation-to-reactive-forms}

Le formulaire a la structure suivante :

```ts
const actorForm = new FormGroup({
  'name': new FormControl(),
  'role': new FormControl(),
  'skill': new FormControl(),
});
```

Remarquez que `name` et `role` sont des contrôles frères.
Pour évaluer les deux contrôles dans un seul validateur personnalisé, vous devez effectuer la validation dans un contrôle ancêtre commun : le `FormGroup`.
Vous interrogez le `FormGroup` pour obtenir ses contrôles enfants afin de pouvoir comparer leurs valeurs.

Pour ajouter un validateur au `FormGroup`, passez le nouveau validateur comme deuxième argument lors de sa création.

```ts
const actorForm = new FormGroup(
  {
    'name': new FormControl(),
    'role': new FormControl(),
    'skill': new FormControl(),
  },
  {validators: unambiguousRoleValidator},
);
```

Le code du validateur est le suivant.

<docs-code header="unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" region="cross-validation-validator"/>

Le validateur `unambiguousRoleValidator` implémente l'interface `ValidatorFn`.
Il prend un objet contrôle Angular en argument et renvoie soit null si le formulaire est valide, soit `ValidationErrors` dans le cas contraire.

Le validateur récupère les contrôles enfants en appelant la méthode [get](api/forms/AbstractControl#get) du `FormGroup`, puis compare les valeurs des contrôles `name` et `role`.

Si les valeurs ne correspondent pas, le rôle est sans ambiguïté, les deux sont valides et le validateur renvoie null.
Si elles correspondent, le rôle de l'acteur est ambigu et le validateur doit marquer le formulaire comme invalide en renvoyant un objet d'erreur.

Pour offrir une meilleure expérience utilisateur, le template affiche un message d'erreur approprié lorsque le formulaire est invalide.

<docs-code header="actor-form-reactive.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="cross-validation-error-message"/>

Ce `@if` affiche l'erreur si le `FormGroup` contient l'erreur de validation inter-champs renvoyée par le validateur `unambiguousRoleValidator`, mais seulement si l'utilisateur a fini d'[interagir avec le formulaire](#control-status-css-classes).

### Ajouter la validation inter-champs aux template-driven forms {#adding-cross-validation-to-template-driven-forms}

Pour un template-driven form, vous devez créer une directive qui encapsule la fonction de validation.
Vous fournissez cette directive comme validateur à l'aide du [jeton `NG_VALIDATORS`](/api/forms/NG_VALIDATORS), comme le montre l'exemple suivant.

<docs-code header="unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" region="cross-validation-directive"/>

Vous devez ajouter la nouvelle directive au template HTML.
Comme le validateur doit être enregistré au niveau le plus élevé du formulaire, le template suivant place la directive sur la balise `form`.

<docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="cross-validation-register-validator"/>

Pour offrir une meilleure expérience utilisateur, un message d'erreur approprié s'affiche lorsque le formulaire est invalide.

<docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="cross-validation-error-message"/>

C'est identique dans les template-driven forms et les reactive forms.

## Créer des validateurs asynchrones {#creating-asynchronous-validators}

Les validateurs asynchrones implémentent les interfaces `AsyncValidatorFn` et `AsyncValidator`.
Ils sont très similaires à leurs équivalents synchrones, avec les différences suivantes.

- Les fonctions `validate()` doivent renvoyer une promise ou un observable,
- L'observable renvoyé doit être fini, c'est-à-dire qu'il doit se terminer à un moment donné.
  Pour convertir un observable infini en observable fini, faites passer l'observable par un opérateur de filtrage comme `first`, `last`, `take` ou `takeUntil`.

La validation asynchrone a lieu après la validation synchrone, et n'est effectuée que si la validation synchrone réussit.
Cette vérification permet aux formulaires d'éviter des processus de validation asynchrone potentiellement coûteux $comme une requête HTTP$ si les méthodes de validation plus basiques ont déjà détecté une saisie invalide.

Une fois la validation asynchrone commencée, le contrôle de formulaire passe dans un état `pending`.
Inspectez la propriété `pending` du contrôle et utilisez-la pour donner un retour visuel sur l'opération de validation en cours.

Un pattern d'interface courant consiste à afficher un spinner pendant l'exécution de la validation asynchrone.
L'exemple suivant montre comment y parvenir dans un template-driven form.

```html
<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator />

@if (model.pending) {
  <app-spinner />
}
```

### Implémenter un validateur asynchrone personnalisé {#implementing-a-custom-async-validator}

Dans l'exemple suivant, un validateur asynchrone garantit que les acteurs sont choisis pour un rôle qui n'est pas déjà attribué.
De nouveaux acteurs passent constamment des auditions et d'anciens acteurs prennent leur retraite : la liste des rôles disponibles ne peut donc pas être récupérée à l'avance.
Pour valider le rôle saisi, le validateur doit lancer une opération asynchrone pour consulter une base de données centrale de tous les acteurs actuellement engagés.

Le code suivant crée la classe du validateur, `UniqueRoleValidator`, qui implémente l'interface `AsyncValidator`.

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator"/>

La propriété `actorsService` est initialisée avec une instance du jeton `ActorsService`, qui définit l'interface suivante.

```ts
interface ActorsService {
  isRoleTaken: (role: string) => Observable<boolean>;
}
```

Dans une application réelle, `ActorsService` serait chargé d'effectuer une requête HTTP vers la base de données des acteurs pour vérifier si le rôle est disponible.
Du point de vue du validateur, l'implémentation réelle du service n'a pas d'importance : l'exemple peut donc simplement s'appuyer sur l'interface `ActorsService`.

Au début de la validation, `UniqueRoleValidator` délègue à la méthode `isRoleTaken()` d'`ActorsService` avec la valeur actuelle du contrôle.
À ce stade, le contrôle est marqué comme `pending` et reste dans cet état jusqu'à ce que la chaîne d'observables renvoyée par la méthode `validate()` se termine.

La méthode `isRoleTaken()` envoie une requête HTTP qui vérifie si le rôle est disponible, et renvoie `Observable<boolean>` comme résultat.
La méthode `validate()` fait passer la réponse par l'opérateur `map` et la transforme en résultat de validation.

La méthode, comme tout validateur, renvoie ensuite `null` si le formulaire est valide, et `ValidationErrors` dans le cas contraire.
Ce validateur gère les erreurs éventuelles avec l'opérateur `catchError`.
Dans ce cas, le validateur traite l'erreur de `isRoleTaken()` comme une validation réussie, car l'échec d'une requête de validation ne signifie pas nécessairement que le rôle est invalide.
Vous pourriez gérer l'erreur différemment et renvoyer plutôt l'objet `ValidationError`.

Au bout d'un certain temps, la chaîne d'observables se termine et la validation asynchrone est achevée.
L'indicateur `pending` passe à `false`, et la validité du formulaire est mise à jour.

### Ajouter des validateurs asynchrones aux reactive forms {#adding-async-validators-to-reactive-forms}

Pour utiliser un validateur asynchrone dans les reactive forms, commencez par injecter le validateur dans une propriété de la classe du composant.

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-inject"/>

Ensuite, passez la fonction de validation directement au `FormControl` pour l'appliquer.

Dans l'exemple suivant, la fonction `validate` de `UniqueRoleValidator` est appliquée à `roleControl` en la passant à l'option `asyncValidators` du contrôle et en la liant à l'instance de `UniqueRoleValidator` injectée dans `ActorFormReactiveComponent`.
La valeur de `asyncValidators` peut être soit une seule fonction de validation asynchrone, soit un tableau de fonctions.
Pour en savoir plus sur les options de `FormControl`, consultez la référence d'API [AbstractControlOptions](api/forms/AbstractControlOptions).

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-usage"/>

### Ajouter des validateurs asynchrones aux template-driven forms {#adding-async-validators-to-template-driven-forms}

Pour utiliser un validateur asynchrone dans les template-driven forms, créez une nouvelle directive et enregistrez-y le provider `NG_ASYNC_VALIDATORS`.

Dans l'exemple ci-dessous, la directive injecte la classe `UniqueRoleValidator`, qui contient la logique de validation proprement dite, et l'invoque dans la fonction `validate`, déclenchée par Angular lorsque la validation doit avoir lieu.

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator-directive"/>

Ensuite, comme pour les validateurs synchrones, ajoutez le selector de la directive à un élément de saisie pour l'activer.

<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" region="role-input"/>

### Optimiser les performances des validateurs asynchrones {#optimizing-performance-of-async-validators}

Par défaut, tous les validateurs s'exécutent après chaque changement de valeur du formulaire.
Avec les validateurs synchrones, cela n'a normalement pas d'impact notable sur les performances de l'application.
Les validateurs asynchrones, en revanche, effectuent généralement une sorte de requête HTTP pour valider le contrôle.
Envoyer une requête HTTP après chaque frappe au clavier pourrait surcharger l'API backend, et doit être évité si possible.

Vous pouvez retarder la mise à jour de la validité du formulaire en changeant la propriété `updateOn` de `change` (par défaut) à `submit` ou `blur`.

Avec les template-driven forms, définissez la propriété dans le template.

```html
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}" />
```

Avec les reactive forms, définissez la propriété dans l'instance de `FormControl`.

```ts
new FormControl('', {updateOn: 'blur'});
```

## Gérer les validateurs dynamiquement dans les reactive forms {#managing-validators-dynamically-in-reactive-forms}

Dans les reactive forms complexes, vous pouvez avoir besoin d'ajouter, de supprimer ou de modifier des validateurs en fonction des saisies de l'utilisateur ou de l'état de l'application.
Angular fournit plusieurs méthodes sur `AbstractControl` pour gérer les validateurs à l'exécution sans recréer les contrôles de formulaire.

### Ajouter et supprimer des validateurs {#adding-and-removing-validators}

Les méthodes [`addValidators`](api/forms/AbstractControl#addValidators) et [`removeValidators`](api/forms/AbstractControl#removeValidators) vous permettent de modifier les validateurs d'un contrôle après son initialisation.

```ts
onCountryChange(country: string) {
    const postalCodeControl = this.profileForm.get('postalCode');

if (country === 'US') {
      // Add validators for US postal codes
      postalCodeControl.addValidators([Validators.required, Validators.pattern(/^\d{5}$/)]);
    } else {
      // Remove validators when not US
      postalCodeControl.removeValidators([Validators.required]);
    }

postalCodeControl.updateValueAndValidity();
}
```

### Remplacer tous les validateurs {#replacing-all-validators}

Utilisez [`setValidators`](api/forms/AbstractControl#setValidators) pour remplacer tous les validateurs synchrones existants d'un contrôle, ou [`clearValidators`](api/forms/AbstractControl#clearValidators) pour supprimer tous les validateurs.

```ts
toggleStrictNameValidation(isStrict: boolean) {
  const nameControl = this.profileForm.get('name');

if (isStrict) {
    // Set strict validation rules
    nameControl.setValidators([
      Validators.required,
      Validators.minLength(3),
      Validators.pattern(/^[a-zA-Z]+$/),
    ]);
  } else {
    // Clear all validators
    nameControl.clearValidators();
  }

nameControl.updateValueAndValidity();
}
```

Le même pattern s'applique aux validateurs asynchrones avec [`addAsyncValidators`](api/forms/AbstractControl#addAsyncValidators), [`removeAsyncValidators`](api/forms/AbstractControl#removeAsyncValidators), [`setAsyncValidators`](api/forms/AbstractControl#setAsyncValidators) et [`clearAsyncValidators`](api/forms/AbstractControl#clearAsyncValidators).

### Déclencher les mises à jour de la validation {#triggering-validation-updates}

Après avoir modifié les validateurs, appelez [`updateValueAndValidity`](api/forms/AbstractControl#updateValueAndValidity) pour recalculer le statut de validation du contrôle.
Cette méthode accepte des options pour contrôler le comportement de la mise à jour.

```ts
// Update control and notify parent
control.updateValueAndValidity();

// Update control only, don't notify parent or emit events
control.updateValueAndValidity({onlySelf: true, emitEvent: false});
```

## Interaction avec la validation native des formulaires HTML {#interaction-with-native-html-form-validation}

Par défaut, Angular désactive la [validation native des formulaires HTML](https://developer.mozilla.org/docs/Web/Guide/HTML/Constraint_validation) en ajoutant l'attribut `novalidate` sur le `<form>` englobant, et utilise des directives pour faire correspondre ces attributs aux fonctions de validation du framework.
Si vous voulez utiliser la validation native **en combinaison** avec la validation d'Angular, vous pouvez la réactiver avec la directive `ngNativeValidate`.
Consultez la [documentation de l'API](api/forms/NgForm#native-dom-validation-ui) pour plus de détails.
# Créer des formulaires dynamiques

De nombreux formulaires, comme les questionnaires, peuvent se ressembler beaucoup dans leur format et leur objectif.
Pour générer plus rapidement et plus facilement différentes versions d'un tel formulaire, vous pouvez créer un _template de formulaire dynamique_ basé sur des métadonnées qui décrivent le modèle objet métier.
Utilisez ensuite ce template pour générer automatiquement de nouveaux formulaires en fonction des changements du modèle de données.

Cette technique est particulièrement utile quand vous avez un type de formulaire dont le contenu doit changer fréquemment pour répondre à des exigences métier et réglementaires en évolution rapide.
Un cas d'usage typique est le questionnaire.
Vous pouvez avoir besoin de recueillir les saisies des utilisateurs dans différents contextes.
Le format et le style des formulaires que voit un utilisateur doivent rester constants, tandis que les questions que vous devez réellement poser varient selon le contexte.

Dans ce tutoriel, vous allez créer un formulaire dynamique qui présente un questionnaire simple.
Vous créez une application en ligne pour des héros en recherche d'emploi.
L'agence modifie constamment le processus de candidature, mais grâce au formulaire dynamique,
vous pouvez créer les nouveaux formulaires à la volée sans modifier le code de l'application.

Le tutoriel vous guide à travers les étapes suivantes :

1. Activer les reactive forms dans un projet.
1. Établir un modèle de données pour représenter les contrôles de formulaire.
1. Remplir le modèle avec des données d'exemple.
1. Développer un composant pour créer dynamiquement des contrôles de formulaire.

Le formulaire que vous créez utilise la validation des saisies et des styles pour améliorer l'expérience utilisateur.
Il comporte un bouton Submit qui n'est activé que lorsque toutes les saisies de l'utilisateur sont valides, et signale les saisies invalides par un code couleur et des messages d'erreur.

Cette version de base peut évoluer pour prendre en charge une plus grande variété de questions, un rendu plus soigné et une meilleure expérience utilisateur.

## Activer les reactive forms dans votre projet {#enable-reactive-forms-for-your-project}

Les formulaires dynamiques reposent sur les reactive forms.

Pour donner à l'application accès aux directives des reactive forms, importez `ReactiveFormsModule` depuis le package `@angular/forms` dans les composants qui en ont besoin.
## Créer un modèle objet de formulaire {#create-a-form-object-model}

Un formulaire dynamique nécessite un modèle objet capable de décrire tous les scénarios requis par les fonctionnalités du formulaire.
L'exemple de formulaire de candidature pour héros est un ensemble de questions : chaque contrôle du formulaire doit poser une question et accepter une réponse.

Le modèle de données de ce type de formulaire doit représenter une question.
L'exemple inclut le `DynamicFormQuestionComponent`, qui définit une question comme l'objet fondamental du modèle.

La classe `QuestionBase` suivante est une classe de base pour un ensemble de contrôles capables de représenter la question et sa réponse dans le formulaire.

<docs-code header="question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>

### Définir les classes de contrôles {#define-control-classes}

À partir de cette base, l'exemple dérive deux nouvelles classes, `TextboxQuestion` et `DropdownQuestion`, qui représentent différents types de contrôles.
Quand vous créerez le template du formulaire à l'étape suivante, vous instancierez ces types de questions spécifiques afin d'afficher dynamiquement les contrôles appropriés.

Le type de contrôle `TextboxQuestion` est représenté dans un template de formulaire par un élément `<input>`. Il présente une question et permet aux utilisateurs de saisir une réponse. L'attribut `type` de l'élément est défini à partir du champ `type` indiqué dans l'argument `options` (par exemple `text`, `email`, `url`).

<docs-code header="question-textbox.ts" path="adev/src/content/examples/dynamic-form/src/app/question-textbox.ts"/>

Le type de contrôle `DropdownQuestion` présente une liste de choix dans une liste déroulante.

<docs-code header="question-dropdown.ts" path="adev/src/content/examples/dynamic-form/src/app/question-dropdown.ts"/>

### Composer les groupes de formulaire {#compose-form-groups}

Un formulaire dynamique utilise un service pour créer des ensembles groupés de contrôles de saisie, à partir du model de formulaire.
Le `QuestionControlService` suivant rassemble un ensemble d'instances `FormGroup` qui consomment les métadonnées du modèle de questions.
Vous pouvez définir des valeurs par défaut et des règles de validation.

<docs-code header="question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>

## Composer le contenu du formulaire dynamique {#compose-dynamic-form-contents}

Le formulaire dynamique lui-même est représenté par un composant conteneur, que vous ajouterez à une étape ultérieure.
Chaque question est représentée dans le template du composant de formulaire par une balise `<app-question>`, qui correspond à une instance de `DynamicFormQuestionComponent`.

Le `DynamicFormQuestionComponent` se charge d'afficher les détails d'une question individuelle à partir des valeurs de l'objet question lié aux données.
Le formulaire s'appuie sur une [directive `[formGroup]`](api/forms/FormGroupDirective 'API reference') pour relier le HTML du template aux objets de contrôle sous-jacents.
Le `DynamicFormQuestionComponent` crée des groupes de formulaire et les remplit avec les contrôles définis dans le modèle de questions, en précisant les règles d'affichage et de validation.
Le rôle du `DynamicFormQuestionComponent` est de présenter les types de questions définis dans votre modèle.
Vous n'avez que deux types de questions pour l'instant, mais vous pouvez en imaginer bien d'autres.
Le bloc `@switch` du template détermine le type de question à afficher.
Le switch utilise des directives ayant les selectors [`formControlName`](api/forms/FormControlName 'FormControlName directive API reference') et [`formGroup`](api/forms/FormGroupDirective 'FormGroupDirective API reference').
Ces deux directives sont définies dans `ReactiveFormsModule`.

### Fournir les données {#supply-data}

Un autre service est nécessaire pour fournir l'ensemble précis de questions à partir duquel construire un formulaire donné.
Pour cet exercice, vous créez le `QuestionService` pour fournir ce tableau de questions à partir des données d'exemple codées en dur.
Dans une application réelle, le service pourrait récupérer les données depuis un système backend.
L'essentiel, cependant, est que vous contrôlez entièrement les questions de candidature des héros via les objets renvoyés par `QuestionService`.
Pour maintenir le questionnaire au fil de l'évolution des exigences, il vous suffit d'ajouter, de modifier et de supprimer des objets du tableau `questions`.

Le `QuestionService` fournit un ensemble de questions sous la forme d'un tableau lié à l'`input()` questions.

<docs-code header="question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/>

## Créer un template de formulaire dynamique {#create-a-dynamic-form-template}

Le composant `DynamicFormComponent` est le point d'entrée et le conteneur principal du formulaire, représenté par `<app-dynamic-form>` dans un template.

Le composant `DynamicFormComponent` présente une liste de questions en liant chacune d'elles à un élément `<app-question>` qui correspond au `DynamicFormQuestionComponent`.
### Afficher le formulaire {#display-the-form}

Pour afficher une instance du formulaire dynamique, le template shell `AppComponent` transmet le tableau `questions` renvoyé par le `QuestionService` au composant conteneur du formulaire, `<app-dynamic-form>`.

<docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/>

Cette séparation entre modèle et données vous permet de réutiliser les composants pour tout type d'enquête, tant qu'il est compatible avec le modèle objet _question_.

### Garantir des données valides {#ensuring-valid-data}

Le template du formulaire utilise un data binding dynamique des métadonnées pour afficher le formulaire sans faire d'hypothèse codée en dur sur des questions spécifiques.
Il ajoute dynamiquement à la fois les métadonnées des contrôles et les critères de validation.

Pour garantir des saisies valides, le bouton _Save_ est désactivé tant que le formulaire n'est pas dans un état valide.
Quand le formulaire est valide, cliquez sur _Save_ et l'application affiche les valeurs actuelles du formulaire au format JSON.

La figure suivante montre le formulaire final.

## Prochaines étapes {#next-steps}
Angular Router (`@angular/router`) est la library officielle pour gérer la navigation dans les applications Angular et une partie centrale du framework. Elle est incluse par défaut dans tous les projets créés avec Angular CLI.

## Pourquoi le routing est-il nécessaire dans une SPA ? {#why-is-routing-necessary-in-a-spa}

Lorsque vous naviguez vers une URL dans votre navigateur web, le navigateur effectue normalement une requête réseau vers un serveur web et affiche la page HTML renvoyée. Lorsque vous naviguez vers une autre URL, par exemple en cliquant sur un lien, le navigateur effectue une nouvelle requête réseau et remplace toute la page par une nouvelle.

Une application monopage (SPA) se distingue en ce que le navigateur n'effectue une requête vers un serveur web que pour la première page, `index.html`. Ensuite, un router côté client prend le relais et contrôle le contenu affiché en fonction de l'URL. Lorsqu'un utilisateur navigue vers une autre URL, le router met à jour le contenu de la page sur place, sans déclencher de rechargement complet de la page.

## Comment Angular gère le routing {#how-angular-manages-routing}

Le routing dans Angular se compose de trois parties principales :

1. Les **routes** définissent quel composant s'affiche lorsqu'un utilisateur visite une URL donnée.
2. Les **outlets** sont des placeholders dans vos templates qui chargent et affichent dynamiquement des composants en fonction de la route active.
3. Les **liens** permettent aux utilisateurs de naviguer entre les différentes routes de votre application sans déclencher de rechargement complet de la page.

En outre, la library de routing d'Angular offre des fonctionnalités supplémentaires, comme :

- Les routes imbriquées
- La navigation programmatique
- Les paramètres de route, les query parameters et les routes wildcard
- Les informations sur la route activée avec `ActivatedRoute`
- La récupération de données avec les resources de route et les resolvers
- Les effets de View Transitions
- Les guards de navigation

## Étapes suivantes {#next-steps}

Découvrez comment [définir des routes avec le router d'Angular](/guide/routing/define-routes).
# Définir des routes

Les routes sont les briques de base de la navigation dans une application Angular.

## Que sont les routes ? {#what-are-routes}

Dans Angular, une **route** est un objet qui définit quel composant doit s'afficher pour un chemin ou un motif d'URL donné, ainsi que des options de configuration supplémentaires sur ce qui se passe quand un utilisateur navigue vers cette URL.

Voici un exemple simple de route :

```ts
import {AdminPage} from './app-admin';

const adminPage = {
  path: 'admin',
  component: AdminPage,
};
```

Avec cette route, quand un utilisateur visite le chemin `/admin`, l'application affiche le composant `AdminPage`.

### Gérer les routes dans votre application {#managing-routes-in-your-application}

La plupart des projets définissent les routes dans un fichier séparé dont le nom contient `routes`.

Une collection de routes ressemble à ceci :

```ts
import {Routes} from '@angular/router';
import {HomePage} from './home-page';
import {AdminPage} from './admin-page';

export const routes: Routes = [
  {
    path: '',
    component: HomePage,
  },
  {
    path: 'admin',
    component: AdminPage,
  },
];
```

TIP: Si vous avez généré un projet avec Angular CLI, vos routes sont définies dans `src/app/app.routes.ts`.

### Ajouter le router à votre application {#adding-the-router-to-your-application}

Lorsque vous effectuez le bootstrap d'une application Angular sans Angular CLI, vous pouvez passer un objet de configuration qui contient un tableau `providers`.

Dans le tableau `providers`, vous pouvez ajouter le router Angular à votre application en ajoutant un appel à la fonction `provideRouter` avec vos routes.

```ts
import {ApplicationConfig} from '@angular/core';
import {provideRouter} from '@angular/router';

import {routes} from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    // ...
  ],
};
```

## Chemins d'URL des routes {#route-url-paths}

### Chemins d'URL statiques {#static-url-paths}

Les chemins d'URL statiques désignent des routes dont les chemins sont prédéfinis et ne changent pas en fonction de paramètres dynamiques. Ce sont des routes qui correspondent exactement à une chaîne `path` et dont le résultat est fixe.

En voici quelques exemples :

- "/admin"
- "/blog"
- "/settings/account"

### Définir des chemins d'URL avec des paramètres de route {#define-url-paths-with-route-parameters}

Les URL paramétrées vous permettent de définir des chemins dynamiques qui font correspondre plusieurs URL à un même composant, tout en affichant dynamiquement des données en fonction des paramètres de l'URL.

Vous pouvez définir ce type de motif en ajoutant des paramètres à la chaîne `path` de votre route et en préfixant chaque paramètre par le caractère deux-points (`:`).

IMPORTANT: Les paramètres sont distincts des informations de la [query string](https://en.wikipedia.org/wiki/Query_string) de l'URL.
Pour en savoir plus, consultez [les query parameters dans Angular dans ce guide](/guide/routing/read-route-state#query-parameters).

L'exemple suivant affiche un composant de profil utilisateur en fonction de l'identifiant d'utilisateur passé dans l'URL.

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile/user-profile';

const routes: Routes = [{path: 'user/:id', component: UserProfile}];
```

Dans cet exemple, des URL comme `/user/leeroy` et `/user/jenkins` affichent le composant `UserProfile`. Ce composant peut ensuite lire le paramètre `id` et l'utiliser pour effectuer d'autres traitements, comme récupérer des données. Consultez le [guide sur la lecture de l'état de la route](/guide/routing/read-route-state) pour en savoir plus sur la lecture des paramètres de route.

Un nom de paramètre de route valide doit commencer par une lettre (a-z, A-Z) et ne peut contenir que :

- des lettres (a-z, A-Z)
- des chiffres (0-9)
- le tiret bas (\_)
- le trait d'union (-)

Vous pouvez aussi définir des chemins avec plusieurs paramètres :

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile';
import {SocialMediaFeed} from './social-media-feed';

const routes: Routes = [
  {path: 'user/:id/:social-media', component: SocialMediaFeed},
  {path: 'user/:id', component: UserProfile},
];
```

Avec ce nouveau chemin, les utilisateurs peuvent visiter `/user/leeroy/youtube` et `/user/leeroy/bluesky` et voir les fils de réseaux sociaux correspondants, en fonction du paramètre, pour l'utilisateur leeroy.

Consultez [Lire l'état de la route](/guide/routing/read-route-state) pour en savoir plus sur la lecture des paramètres de route.

### Routes wildcard {#wildcards}

Quand vous devez intercepter toutes les routes d'un chemin donné, la solution est une route wildcard, définie avec le double astérisque (`**`).

Un exemple courant consiste à définir un composant « Page introuvable ».

```ts
import {Routes} from '@angular/router';
import {Home} from './home/home';
import {UserProfile} from './user-profile';
import {NotFound} from './not-found';

const routes: Routes = [
  {path: 'home', component: Home},
  {path: 'user/:id', component: UserProfile},
  {path: '**', component: NotFound},
];
```

Avec ce tableau de routes, l'application affiche le composant `NotFound` quand l'utilisateur visite un chemin autre que `home` et `user/:id`.

TIP: Les routes wildcard sont généralement placées à la fin d'un tableau de routes.

## Comment Angular fait correspondre les URL {#how-angular-matches-urls}

Quand vous définissez des routes, l'ordre est important, car Angular applique une stratégie où la première correspondance l'emporte. Autrement dit, dès qu'Angular fait correspondre une URL au `path` d'une route, il arrête d'examiner les routes suivantes. Placez donc toujours les routes les plus spécifiques avant les moins spécifiques.

L'exemple suivant montre des routes définies de la plus spécifique à la moins spécifique :

```ts
const routes: Routes = [
  {path: '', component: Home}, // Empty path
  {path: 'users/new', component: NewUser}, // Static, most specific
  {path: 'users/:id', component: UserDetail}, // Dynamic
  {path: 'users', component: Users}, // Static, less specific
  {path: '**', component: NotFound}, // Wildcard - always last
];
```

Si un utilisateur visite `/users/new`, le router Angular passe par les étapes suivantes :

1. Il vérifie `''` : pas de correspondance
1. Il vérifie `users/new` : correspondance ! Il s'arrête là
1. Il n'atteint jamais `users/:id`, même si cette route pourrait correspondre
1. Il n'atteint jamais `users`
1. Il n'atteint jamais `**`

## Redirections {#redirects}

Vous pouvez définir une route qui redirige vers une autre route au lieu d'afficher un composant :

```ts
import {Routes} from '@angular/router';
import {Blog} from './home/blog';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: Blog,
  },
];
```

Si vous modifiez ou supprimez une route, certains utilisateurs peuvent encore cliquer sur des liens ou des favoris obsolètes pointant vers cette route. Vous pouvez ajouter une redirection pour diriger ces utilisateurs vers une route alternative appropriée plutôt que vers une page « introuvable ».

## Titres de page {#page-titles}

Vous pouvez associer un **titre** à chaque route. Angular met automatiquement à jour le [titre de la page](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) quand une route s'active. Définissez toujours des titres de page appropriés pour votre application, car ils sont nécessaires pour offrir une expérience accessible.

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {About} from './about';
import {Products} from './products';

const routes: Routes = [
  {
    path: '',
    component: Home,
    title: 'Home Page',
  },
  {
    path: 'about',
    component: About,
    title: 'About Us',
  },
];
```

La propriété `title` de la page peut être définie dynamiquement avec une fonction resolver à l'aide de [`ResolveFn`](/api/router/ResolveFn).

```ts
const titleResolver: ResolveFn<string> = (route) => route.queryParams['id'];
const routes: Routes = [
  // ...
  {
    path: 'products',
    component: Products,
    title: titleResolver,
  },
];
```

Les titres de route peuvent aussi être définis via un service qui étend la classe abstraite [`TitleStrategy`](/api/router/TitleStrategy). Par défaut, Angular utilise la [`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy).

### Utiliser TitleStrategy pour les titres de page {#using-titlestrategy-for-page-titles}

Pour les scénarios avancés où vous avez besoin de contrôler de façon centralisée la composition du titre du document, implémentez une `TitleStrategy`.

`TitleStrategy` est un jeton que vous pouvez fournir pour remplacer la stratégie de titre utilisée par défaut par Angular. Vous pouvez fournir une `TitleStrategy` personnalisée pour mettre en œuvre des conventions comme l'ajout d'un suffixe propre à l'application, la mise en forme des titres à partir d'un fil d'Ariane ou la génération dynamique des titres à partir des données de la route.

```ts
import {inject, Injectable} from '@angular/core';
import {Title} from '@angular/platform-browser';
import {TitleStrategy, RouterStateSnapshot} from '@angular/router';

@Injectable()
export class AppTitleStrategy extends TitleStrategy {
  private readonly title = inject(Title);

updateTitle(snapshot: RouterStateSnapshot): void {
    // PageTitle is equal to the "Title" of a route if it's set
    // If its not set it will use the "title" given in index.html
    const pageTitle = this.buildTitle(snapshot) || this.title.getTitle();
    this.title.setTitle(`MyAwesomeApp - ${pageTitle}`);
  }
}
```

Pour utiliser la stratégie personnalisée, fournissez-la avec le jeton `TitleStrategy` au niveau de l'application :

```ts
import {provideRouter, TitleStrategy} from '@angular/router';
import {AppTitleStrategy} from './app-title.strategy';

export const appConfig = {
  providers: [provideRouter(routes), {provide: TitleStrategy, useClass: AppTitleStrategy}],
};
```

## Providers au niveau de la route pour l'injection de dépendances {#route-level-providers-for-dependency-injection}

Chaque route possède une propriété `providers` qui vous permet de fournir des dépendances au contenu de cette route via l'[injection de dépendances](/guide/di).

C'est utile par exemple dans les applications qui proposent des services différents selon que l'utilisateur est administrateur ou non.

```ts
export const ROUTES: Route[] = [
  {
    path: 'admin',
    providers: [AdminService, {provide: ADMIN_API_KEY, useValue: '12345'}],
    children: [
      {path: 'users', component: AdminUsers},
      {path: 'teams', component: AdminTeams},
    ],
  },
  // ... other application routes that don't
  //     have access to ADMIN_API_KEY or AdminService.
];
```

Dans cet exemple de code, le chemin `admin` contient une propriété de données protégée, `ADMIN_API_KEY`, qui n'est accessible qu'aux enfants de sa section. Par conséquent, aucun autre chemin ne peut accéder aux données fournies via `ADMIN_API_KEY`.

Consultez le [guide de l'injection de dépendances](/guide/di) pour en savoir plus sur les providers et l'injection dans Angular.

## Associer des données aux routes {#associating-data-with-routes}

Les données de route vous permettent d'attacher des informations supplémentaires aux routes. Vous pouvez configurer le comportement des composants en fonction de ces données.

Il existe deux façons de travailler avec les données de route : les données statiques, qui restent constantes, et les données dynamiques, qui peuvent changer selon les conditions d'exécution.

### Données statiques {#static-data}

Vous pouvez associer des données statiques arbitraires à une route via la propriété `data`, afin de centraliser par exemple des métadonnées propres à la route (suivi analytics, permissions, etc.) :

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {About} from './about';
import {Products} from './products';

const routes: Routes = [
  {
    path: 'about',
    component: About,
    data: {analyticsId: '456'},
  },
  {
    path: '',
    component: Home,
    data: {analyticsId: '123'},
  },
];
```

Dans cet exemple de code, la page d'accueil et la page « À propos » sont configurées avec un `analyticsId` spécifique, qui serait ensuite utilisé dans leurs composants respectifs pour le suivi analytics des pages.

Vous pouvez lire ces données statiques en injectant l'`ActivatedRoute`. Consultez [Lire l'état de la route](/guide/routing/read-route-state) pour en savoir plus.

### Données dynamiques avec les resources et les resolvers {#dynamic-data-with-resources-and-resolvers}

Quand vous devez récupérer des données pour une route, le router Angular prend en charge les resources de route réactives ainsi que les resolvers de données :

- [Récupérer des données avec les resources](/guide/routing/data-fetching-with-resources) : récupérez des données de façon réactive avec les API `Resource` des signals d'Angular.
- [Resolvers de données de route](/guide/routing/data-resolvers) : récupérez des données avant l'activation de la route à l'aide de fonctions resolver.

## Routes imbriquées {#nested-routes}

Les routes imbriquées, aussi appelées routes enfants, sont une technique courante pour gérer des routes de navigation plus complexes, où un composant possède une sous-vue qui change en fonction de l'URL.

Vous pouvez ajouter des routes enfants à n'importe quelle définition de route avec la propriété `children` :

```ts
const routes: Routes = [
  {
    path: 'product/:id',
    component: Product,
    children: [
      {
        path: 'info',
        component: ProductInfo,
      },
      {
        path: 'reviews',
        component: ProductReviews,
      },
    ],
  },
];
```

L'exemple ci-dessus définit une route pour une page produit qui permet à l'utilisateur d'afficher soit les informations du produit, soit les avis, en fonction de l'URL.

La propriété `children` accepte un tableau d'objets `Route`.

Pour afficher les routes enfants, le composant parent (`Product` dans l'exemple ci-dessus) contient son propre `<router-outlet>`.

```html

<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

Après avoir ajouté des routes enfants à la configuration et un `<router-outlet>` au composant, la navigation entre les URL qui correspondent aux routes enfants met à jour uniquement l'outlet imbriqué.

## Étapes suivantes {#next-steps}
# Afficher les routes avec des outlets

La directive `RouterOutlet` est un placeholder qui marque l'emplacement où le router doit afficher le composant correspondant à l'URL courante.

```html
<app-header />

<router-outlet />
<app-footer />
```

```ts
import {Component} from '@angular/core';
import {RouterOutlet} from '@angular/router';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  templateUrl: './app.html',
  styleUrl: './app.css',
})
export class App {}
```

Dans cet exemple, si une application définit les routes suivantes :

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {Products} from './products';

const routes: Routes = [
  {
    path: '',
    component: Home,
    title: 'Home Page',
  },
  {
    path: 'products',
    component: Products,
    title: 'Our Products',
  },
];
```

Quand un utilisateur visite `/products`, Angular affiche ceci :

```html
<app-header />
<app-products />
<app-footer />
```

Si l'utilisateur revient à la page d'accueil, Angular affiche alors :

```html
<app-header />
<app-home />
<app-footer />
```

Lors de l'affichage d'une route, l'élément `<router-outlet>` reste présent dans le DOM comme point de référence pour les navigations futures. Angular insère le contenu routé juste après l'élément outlet, en tant qu'élément frère.

```html

<app-header />
<router-outlet />
<app-footer />
```

```html

<app-header />
<router-outlet />
<app-admin-page />
<app-footer />
```

## Imbriquer des routes avec des routes enfants {#nesting-routes-with-child-routes}

À mesure que votre application gagne en complexité, vous voudrez peut-être créer des routes relatives à un autre composant que votre composant racine. Cela vous permet de créer des expériences où seule une partie de l'application change quand l'URL change, au lieu de donner aux utilisateurs l'impression que la page entière est rechargée.

Ces routes imbriquées sont appelées routes enfants. Cela signifie que vous ajoutez un second `<router-outlet>` à votre application, en plus du `<router-outlet>` de AppComponent.

Dans cet exemple, le composant `Settings` affiche le panneau voulu en fonction de ce que l'utilisateur sélectionne. Une particularité des routes enfants est que le composant possède souvent ses propres `<nav>` et `<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 />
```

Une route enfant est une route comme les autres : elle a besoin à la fois d'un `path` et d'un `component`. La seule différence est que vous placez les routes enfants dans un tableau children au sein de la route parente.

```ts
const routes: Routes = [
  {
    path: 'settings',
    component: Settings, // this is the component with the <router-outlet> in the template
    children: [
      {
        path: 'profile', // child route path
        component: Profile, // child route component that the router renders
      },
      {
        path: 'security',
        component: Security, // another child route component that the router renders
      },
    ],
  },
];
```

Une fois les `routes` et le `<router-outlet>` correctement configurés, votre application utilise des routes imbriquées !

## Routes secondaires avec des outlets nommés {#secondary-routes-with-named-outlets}

Une page peut avoir plusieurs outlets : vous pouvez attribuer un nom à chaque outlet pour indiquer quel contenu appartient à quel outlet.

```html
<app-header />
<router-outlet />
<router-outlet name="read-more" />
<router-outlet name="additional-actions" />
<app-footer />
```

Chaque outlet doit avoir un nom unique. Le nom ne peut pas être défini ni modifié dynamiquement. Par défaut, le nom est `'primary'`.

Angular fait correspondre le nom de l'outlet à la propriété `outlet` définie sur chaque route :

```ts
{
  path: 'user/:id',
  component: UserDetails,
  outlet: 'additional-actions'
}
```

## Événements de cycle de vie de l'outlet {#outlet-lifecycle-events}

Un router outlet peut émettre quatre événements de cycle de vie :

| Événement    | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `activate`   | Quand un nouveau composant est instancié                                     |
| `deactivate` | Quand un composant est détruit                                            |
| `attach`     | Quand la `RouteReuseStrategy` demande à l'outlet d'attacher le sous-arbre |
| `detach`     | Quand la `RouteReuseStrategy` demande à l'outlet de détacher le sous-arbre |

Vous pouvez ajouter des event listeners avec la syntaxe standard d'event binding :

```html
<router-outlet
  (activate)="onActivate($event)"
  (deactivate)="onDeactivate($event)"
  (attach)="onAttach($event)"
  (detach)="onDetach($event)"
/>
```

Consultez la [documentation d'API de RouterOutlet](/api/router/RouterOutlet?tab=api) pour en savoir plus.

## Transmettre des données contextuelles aux composants routés {#passing-contextual-data-to-routed-components}

Transmettre des données contextuelles aux composants routés nécessite souvent un état global ou des configurations de route complexes. Pour simplifier cela, chaque `RouterOutlet` accepte un input `routerOutletData`. Les composants routés et leurs enfants peuvent lire ces données sous forme de signal grâce au jeton d'injection `ROUTER_OUTLET_DATA`, ce qui permet une configuration propre à chaque outlet sans modifier les définitions de routes.

```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 Dashboard {}
```

Le composant routé peut injecter les données fournies par l'outlet avec `ROUTER_OUTLET_DATA` :

```typescript
import {Component, inject, Signal} from '@angular/core';
import {ROUTER_OUTLET_DATA} from '@angular/router';

@Component({
  selector: 'app-stats',
  template: `<p>Stats view (layout: {{ outletData().layout }})</p>`,
})
export class Stats {
  outletData = inject(ROUTER_OUTLET_DATA) as Signal<{layout: string}>;
}
```

Quand Angular active `Stats` dans cet outlet, ce composant reçoit `{ layout: 'sidebar' }` comme données injectées.

NOTE: Quand l'input `routerOutletData` n'est pas défini, la valeur du signal injecté est `undefined` par défaut.

---

## Prochaines étapes {#next-steps}

Découvrez comment [naviguer vers des routes](/guide/routing/navigate-to-routes) avec le router Angular.
# Naviguer vers des routes

La directive RouterLink est l'approche déclarative d'Angular pour la navigation. Elle vous permet d'utiliser des éléments d'ancre standard (`<a>`) qui s'intègrent parfaitement au système de routing d'Angular.

## Comment utiliser RouterLink {#how-to-use-routerlink}

Au lieu d'utiliser des éléments d'ancre `<a>` classiques avec un attribut `href`, ajoutez une directive RouterLink avec le chemin approprié afin de tirer parti du routing d'Angular.

```typescript
import {RouterLink} from '@angular/router';
import {Component} from '@angular/core';

@Component({
  template: `
    <nav>
      <a routerLink="/user-profile">User profile</a>
      <a routerLink="/settings">Settings</a>
    </nav>
  `,
  imports: [RouterLink],
  ...
})
export class App {}
```

### Utiliser des liens absolus ou relatifs {#using-absolute-or-relative-links}

Dans le routing d'Angular, les **URL relatives** vous permettent de définir des chemins de navigation relatifs à l'emplacement de la route courante. Elles s'opposent aux **URL absolues**, qui contiennent le chemin complet avec le protocole (par exemple, `http://`) et le **domaine racine** (par exemple, `google.com`).

```html

<a href="https://www.angular.dev/essentials">Angular Essentials Guide</a>

<a href="/essentials">Angular Essentials Guide</a>
```

Dans cet exemple, le premier exemple contient le chemin complet avec le protocole (c'est-à-dire `https://`) et le domaine racine (c'est-à-dire `angular.dev`) explicitement définis pour la page des Fondamentaux. À l'inverse, le second exemple suppose que l'utilisateur se trouve déjà sur le bon domaine racine pour `/essentials`.

De manière générale, les URL relatives sont préférables, car elles sont plus faciles à maintenir d'une application à l'autre : elles n'ont pas besoin de connaître leur position absolue dans la hiérarchie de routing.

### Fonctionnement des URL relatives {#how-relative-urls-work}

Le routing d'Angular propose deux syntaxes pour définir des URL relatives : les chaînes de caractères et les tableaux.

```html

<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

HELPFUL: Passer une chaîne de caractères est la manière la plus courante de définir des URL relatives.

Lorsque vous devez définir des paramètres dynamiques dans une URL relative, utilisez la syntaxe en tableau :

```html
<a [routerLink]="['user', currentUserId]">Current User</a>
```

De plus, le routing d'Angular vous permet d'indiquer si le chemin doit être relatif à l'URL courante ou au domaine racine, selon que le chemin relatif est préfixé ou non par une barre oblique (`/`).

Par exemple, si l'utilisateur se trouve sur `example.com/settings`, voici comment définir différents chemins relatifs selon les scénarios :

```html

<a routerLink="notifications">Notifications</a>
<a routerLink="/settings/notifications">Notifications</a>

<a routerLink="/team/123/user/456">User 456</a>
<a [routerLink]="['/team', teamId, 'user', userId]">Current User</a>
```

## Navigation programmatique vers des routes {#programmatic-navigation-to-routes}

Alors que `RouterLink` gère la navigation déclarative dans les templates, Angular fournit une navigation programmatique pour les scénarios où vous devez naviguer en fonction de la logique, des actions de l'utilisateur ou de l'état de l'application. En injectant `Router`, vous pouvez naviguer dynamiquement vers des routes, passer des paramètres et contrôler le comportement de la navigation dans votre code TypeScript.

### `router.navigate()`

Vous pouvez utiliser la méthode `router.navigate()` pour naviguer de manière programmatique entre les routes en indiquant un tableau de chemin d'URL.

```typescript
import {Router} from '@angular/router';
import {Component, inject} from '@angular/core';

@Component({
  selector: 'app-dashboard',
  template: ` <button (click)="navigateToProfile()">View Profile</button> `,
})
export class AppDashboard {
  private router = inject(Router);

navigateToProfile() {
    // Standard navigation
    this.router.navigate(['/profile']);

// With route parameters
    this.router.navigate(['/users', userId]);

// With query parameters
    this.router.navigate(['/search'], {
      queryParams: {category: 'books', sort: 'price'},
    });

// With matrix parameters
    this.router.navigate(['/products', {featured: true, onSale: true}]);
  }
}
```

`router.navigate()` prend en charge les scénarios de routing simples comme complexes : vous pouvez passer des paramètres de route, des [query parameters](/guide/routing/read-route-state#query-parameters) et contrôler le comportement de la navigation.

Vous pouvez aussi construire des chemins de navigation dynamiques relatifs à l'emplacement de votre composant dans l'arbre de routes, à l'aide de l'option `relativeTo`.

```typescript
import {Router, ActivatedRoute} from '@angular/router';
import {Component, inject} from '@angular/core';

@Component({
  selector: 'app-user-detail',
  template: `
    <button (click)="navigateToEdit()">Edit User</button>
    <button (click)="navigateToParent()">Back to List</button>
  `,
})
export class UserDetail {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

// Navigate to a sibling route
  navigateToEdit() {
    // From: /users/123
    // To:   /users/123/edit
    this.router.navigate(['edit'], {relativeTo: this.route});
  }

// Navigate to parent
  navigateToParent() {
    // From: /users/123
    // To:   /users
    this.router.navigate(['..'], {relativeTo: this.route});
  }

navigateToList() {
    // Angular resolves the commands array as a single navigation path relative to the current route.
    // From: /users/123
    // Result: /users/list
    this.router.navigate(['..', 'list'], {relativeTo: this.route});
  }
}
```

Pour remonter de plusieurs niveaux, tous les segments `..` doivent se trouver dans le **premier élément** du tableau de commandes. Le router n'analyse `..` que dans la première chaîne de commande : les éléments suivants du tableau sont traités comme des segments de chemin littéraux.

```typescript
{prefer}
// From: /team/123/users/456
// Result: /team/123/settings
this.router.navigate(['../../settings'], {relativeTo: this.route});
```

Lorsque vous utilisez `relativeTo`, ne préfixez jamais la première commande par `/`. Un `/` initial rend la navigation absolue et ignore complètement `relativeTo`.

```typescript
{prefer}
// From: /team/123/users/456
// Result: /team/123/users/456/edit
this.router.navigate(['edit'], {relativeTo: this.route});
```

```typescript
{avoid}
// From: /team/123/users/456
// Leading '/' causes absolute navigation — relativeTo is ignored
// Result: /edit
this.router.navigate(['/edit'], {relativeTo: this.route});
```

### `router.navigateByUrl()`

La méthode `router.navigateByUrl()` offre un moyen direct de naviguer de manière programmatique à l'aide de chaînes de chemin d'URL plutôt que de segments en tableau. Cette méthode est idéale lorsque vous disposez d'un chemin d'URL complet et devez effectuer une navigation absolue, en particulier avec des URL fournies de l'extérieur ou dans des scénarios de liens profonds (deep linking).

```ts
// Standard route navigation
router.navigateByUrl('/products');

// Navigate to nested route
router.navigateByUrl('/products/featured');

// Complete URL with parameters and fragment
router.navigateByUrl('/products/123?view=details#reviews');

// Navigate with query parameters
router.navigateByUrl('/search?category=books&sortBy=price');

// With matrix parameters
router.navigateByUrl('/sales-awesome;isOffer=true;showModal=false');
```

Si vous devez remplacer l'URL courante dans l'historique, `navigateByUrl` accepte aussi un objet de configuration doté d'une option `replaceUrl`.

```ts
// Replace current URL in history
router.navigateByUrl('/checkout', {
  replaceUrl: true,
});
```

### Afficher une URL différente dans la barre d'adresse {#display-a-different-url-in-the-address-bar}

Vous pouvez passer une option browserUrl à navigateByUrl pour afficher dans la barre d'adresse du navigateur une URL différente de celle utilisée pour la correspondance des routes.

C'est utile lorsque vous voulez rediriger un utilisateur vers une autre route, comme une page d'erreur, sans changer l'URL qu'il a initialement tenté de visiter.

```ts
router.navigateByUrl('/not-found', {browserUrl: '/products/missing-item'});
```

Angular navigue vers la route `/not-found` et l'affiche, mais la barre d'adresse du navigateur indique `/products/missing-item`.

NOTE: `browserUrl` n'affecte que ce qui apparaît dans la barre d'adresse du navigateur.

## Personnaliser l'URL du navigateur avec RouterLink {#customizing-the-browser-url-with-routerlink}

La directive `RouterLink` prend aussi en charge un input `browserUrl`, qui vous permet de contrôler l'URL affichée dans la barre d'adresse du navigateur lors d'un clic sur un lien, indépendamment de la route vers laquelle Angular navigue.

```html

<a [routerLink]="['/dashboard']" [browserUrl]="'/home'">Go to Dashboard</a>
```

Vous pouvez aussi lier un `UrlTree` pour des cas d'usage plus dynamiques :

```typescript
import {Component, inject} from '@angular/core';
import {Router, RouterLink, UrlTree} from '@angular/router';

@Component({
  template: `
    <a [routerLink]="['/products', product.id]" [browserUrl]="displayUrl">
      {{ product.name }}
    </a>
  `,
  imports: [RouterLink],
})
export class ProductList {
  private router = inject(Router);

product = {id: 42, name: 'Widget'};

// Create a UrlTree to display in the address bar
  displayUrl: UrlTree = this.router.createUrlTree(['/products', 'widget']);
}
```

## Prochaines étapes {#next-steps}

Découvrez comment [lire l'état de la route](/guide/routing/read-route-state) pour créer des composants réactifs et sensibles au contexte.
# Lire l'état de la route

Le router d'Angular vous permet de lire et d'utiliser les informations associées à une route pour créer des composants réactifs et conscients de leur contexte.

## Obtenir des informations sur la route courante avec ActivatedRoute {#get-information-about-the-current-route-with-activatedroute}

`ActivatedRoute` est un service de `@angular/router` qui fournit toutes les informations associées à la route courante.

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component({
  selector: 'app-product',
})
export class Product {
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    console.log(this.activatedRoute);
  }
}
```

`ActivatedRoute` peut fournir différentes informations sur la route. Voici quelques propriétés courantes :

| Propriété     | Détails                                                                                                                           |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------- |
| `url`         | Un `Observable` des chemins de la route, représentés sous forme de tableau d'objets `UrlSegment` pour chaque partie du chemin de la route. |
| `data`        | Un `Observable` qui contient l'objet `data` fourni pour la route. Contient aussi les valeurs résolues par la resolve guard. |
| `params`      | Un `Observable` qui contient les paramètres obligatoires et facultatifs propres à la route.                                         |
| `queryParams` | Un `Observable` qui contient les query parameters disponibles pour toutes les routes.                                                       |
| `resources`   | Un enregistrement facultatif d'instances de `Resource` définies sur la route (quand `withRouterResources` est activé).                          |

Consultez la [documentation de l'API `ActivatedRoute`](/api/router/ActivatedRoute) pour la liste complète de ce à quoi vous pouvez accéder dans la route.

## Comprendre les snapshots de route {#understanding-route-snapshots}

Les navigations entre pages sont des événements dans le temps, et vous pouvez accéder à l'état du router à un instant donné en récupérant un snapshot de la route.

Les snapshots de route contiennent les informations essentielles sur la route, notamment ses paramètres, ses données et ses routes enfants. De plus, les snapshots sont statiques et ne refléteront pas les changements futurs.

Voici un exemple d'accès à un snapshot de route :

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component(/* ... */)
export class UserProfile {
  readonly userId: string | null;
  private route = inject(ActivatedRoute);

constructor() {
    // Example URL: https://www.angular.dev/users/123?role=admin&status=active#contact

// Access route parameters from snapshot
    this.userId = this.route.snapshot.paramMap.get('id');

// Access multiple route elements
    const snapshot = this.route.snapshot;
    console.log({
      url: snapshot.url, // Array of UrlSegments matched by this route
      // Route parameters object: {id: '123'}
      params: snapshot.params,
      // Query parameters object: {role: 'admin', status: 'active'}
      queryParams: snapshot.queryParams, // Query parameters
    });
  }
}
```

Consultez la [documentation de l'API `ActivatedRoute`](/api/router/ActivatedRoute) et la [documentation de l'API `ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) pour la liste complète des propriétés accessibles.

## Lire les paramètres d'une route {#reading-parameters-on-a-route}

Les développeurs peuvent exploiter deux types de paramètres d'une route : les paramètres de route et les query parameters.

### Paramètres de route {#route-parameters}

Les paramètres de route vous permettent de transmettre des données à un composant via l'URL. C'est utile quand vous voulez afficher un contenu précis en fonction d'un identifiant présent dans l'URL, comme un ID d'utilisateur ou de produit.

Vous pouvez [définir des paramètres de route](/guide/routing/define-routes#define-url-paths-with-route-parameters) en préfixant le nom du paramètre par deux-points (`:`).

```typescript
import {Routes} from '@angular/router';
import {Product} from './product';

const routes: Routes = [{path: 'product/:id', component: Product}];
```

Vous pouvez accéder aux paramètres en vous abonnant à `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 ProductDetail {
  productId = signal('');
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    // Access route parameters
    this.activatedRoute.params.subscribe((params) => {
      this.productId.set(params['id']);
    });
  }
}
```

### Query parameters {#query-parameters}

Les [query parameters](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) offrent un moyen souple de transmettre des données facultatives via les URL sans modifier la structure de la route. Contrairement aux paramètres de route, les query parameters peuvent persister d'une navigation à l'autre et sont parfaits pour gérer le filtrage, le tri, la pagination et d'autres éléments d'interface avec état.

```typescript
// Single parameter structure
// /products?category=electronics
router.navigate(['/products'], {
  queryParams: {category: 'electronics'},
});

// Multiple parameters
// /products?category=electronics&sort=price&page=1
router.navigate(['/products'], {
  queryParams: {
    category: 'electronics',
    sort: 'price',
    page: 1,
  },
});
```

Vous pouvez accéder aux query parameters avec `route.queryParams`.

Voici un exemple de `ProductList` qui met à jour les query parameters influant sur l'affichage d'une liste de produits :

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute, Router} from '@angular/router';

@Component({
  selector: 'app-product-list',
  template: `
    <div>
      <select (change)="updateSort($event)">
        <option value="price">Price</option>
        <option value="name">Name</option>
      </select>
      
    </div>
  `,
})
export class ProductList {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {
    // Access query parameters reactively
    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;
    // Update URL with new query parameter
    this.router.navigate([], {
      queryParams: {sort},
      queryParamsHandling: 'merge', // Preserve other query parameters
    });
  }
}
```

Dans cet exemple, les utilisateurs peuvent utiliser un élément select pour trier la liste de produits par nom ou par prix. L'event handler de changement associé met à jour les query parameters de l'URL, ce qui déclenche à son tour un événement de changement qui peut lire les query parameters mis à jour et actualiser la liste de produits.

Pour plus d'informations, consultez la [documentation officielle de QueryParamsHandling](/api/router/QueryParamsHandling).

### Paramètres matriciels {#matrix-parameters}

Les paramètres matriciels sont des paramètres facultatifs qui appartiennent à un segment d'URL précis, au lieu de s'appliquer à la route entière. Contrairement aux query parameters, qui apparaissent après un `?` et s'appliquent globalement, les paramètres matriciels utilisent des points-virgules (`;`) et sont limités à des segments de chemin individuels.

Les paramètres matriciels sont utiles quand vous devez transmettre des données auxiliaires à un segment de route précis sans modifier la définition de la route ni son comportement de correspondance. Comme les query parameters, ils n'ont pas besoin d'être définis dans votre configuration de routes.

```ts
// URL format: /path;key=value
// Multiple parameters: /path;key1=value1;key2=value2

// Navigate with matrix parameters
this.router.navigate(['/awesome-products', {view: 'grid', filter: 'new'}]);
// Results in URL: /awesome-products;view=grid;filter=new
```

**Avec ActivatedRoute**

```ts
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component(/* ... */)
export class AwesomeProducts {
  private route = inject(ActivatedRoute);

constructor() {
    // Access matrix parameters via params
    this.route.params.subscribe((params) => {
      const view = params['view']; // e.g., 'grid'
      const filter = params['filter']; // e.g., 'new'
    });
  }
}
```

NOTE: Comme alternative à `ActivatedRoute`, les paramètres matriciels sont aussi liés aux inputs du composant lorsque vous utilisez `withComponentInputBinding`.

## Détecter la route active avec RouterLinkActive {#detect-active-current-route-with-routerlinkactive}

Vous pouvez utiliser la directive `RouterLinkActive` pour styliser dynamiquement les éléments de navigation en fonction de la route active. C'est courant dans les éléments de navigation pour indiquer aux utilisateurs quelle est la route active.

```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>
```

Dans cet exemple, le router d'Angular applique la classe `active-button` au bon lien d'ancre et `ariaCurrentWhenActive` à `page` quand l'URL correspond au `routerLink` associé.

Si vous devez ajouter plusieurs classes à l'élément, vous pouvez utiliser soit une chaîne séparée par des espaces, soit un tableau :

```html

<a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>

<a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
```

Définir `routerLinkActive` seul ne définit pas `aria-current`. Définissez l'input `ariaCurrentWhenActive`, comme dans l'exemple ci-dessus, afin que les utilisateurs malvoyants (qui peuvent ne pas percevoir le style différent appliqué) puissent aussi identifier le lien actif.

### Stratégie de correspondance des routes {#route-matching-strategy}

Par défaut, `RouterLinkActive` considère tout ancêtre dans la route comme une correspondance.

```html
<a [routerLink]="['/user/jane']" routerLinkActive="active-link"> User </a>
<a [routerLink]="['/user/jane/role/admin']" routerLinkActive="active-link"> Role </a>
```

Quand l'utilisateur visite `/user/jane/role/admin`, les deux liens ont la classe `active-link`.

### N'appliquer RouterLinkActive que sur une correspondance exacte de la route {#only-apply-routerlinkactive-on-exact-route-matches}

Si vous voulez appliquer la classe uniquement en cas de correspondance exacte, vous devez fournir à la directive `routerLinkActiveOptions` un objet de configuration contenant la valeur `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 vous voulez contrôler plus précisément la correspondance d'une route, notez que `exact: true` n'est en réalité qu'un raccourci syntaxique pour l'ensemble complet des options de correspondance :

```typescript
// `exact: true` is equivalent to
{
  paths: 'exact',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'exact',
}

// `exact: false` is equivalent
{
  paths: 'subset',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'subset',
}
```

Pour plus d'informations, consultez la documentation officielle de [isActiveMatchOptions](/api/router/IsActiveMatchOptions).

### Appliquer RouterLinkActive à un ancêtre {#apply-routerlinkactive-to-an-ancestor}

La directive RouterLinkActive peut aussi être appliquée à un élément ancêtre afin de permettre aux développeurs de styliser les éléments comme ils le souhaitent.

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

Pour plus d'informations, consultez la [documentation de l'API de RouterLinkActive](/api/router/RouterLinkActive).

## Vérifier si une URL est active {#check-if-a-url-is-active}

La fonction `isActive` renvoie un signal computed qui suit si une URL donnée est actuellement active dans le router. Le signal se met à jour automatiquement quand l'état du router change.

```typescript
import {Component, inject} from '@angular/core';
import {isActive, Router} from '@angular/router';

@Component({
  template: `
    <div [class.active]="isSettingsActive()">
      <h2>Settings</h2>
    </div>
  `,
})
export class Panel {
  private router = inject(Router);

isSettingsActive = isActive('/settings', this.router, {
    paths: 'subset',
    queryParams: 'ignored',
    fragment: 'ignored',
    matrixParams: 'ignored',
  });
}
```
# Autres tâches courantes de routing

Ce guide couvre d'autres tâches courantes liées à l'utilisation du router Angular dans votre application.

## Obtenir les informations de route {#getting-route-information}

Souvent, quand un utilisateur navigue dans votre application, vous voulez transmettre des informations d'un composant à un autre.
Par exemple, imaginez une application qui affiche une liste de courses.
Chaque article de la liste possède un `id` unique.
Pour modifier un article, les utilisateurs cliquent sur un bouton Modifier, qui ouvre un composant `EditGroceryItem`.
Vous voulez que ce composant récupère l'`id` de l'article pour afficher les bonnes informations à l'utilisateur.

Utilisez une route pour transmettre ce type d'information aux composants de votre application.
Pour cela, utilisez la fonctionnalité `withComponentInputBinding` avec `provideRouter` ou l'option `bindToComponentInputs` de `RouterModule.forRoot`.

Pour obtenir des informations d'une route :

<docs-workflow>

<docs-step title="Ajouter `withComponentInputBinding` {#add-withcomponentinputbinding}">

Ajoutez la fonctionnalité `withComponentInputBinding` à la méthode `provideRouter`.

```ts
providers: [provideRouter(appRoutes, withComponentInputBinding())];
```

</docs-step>

<docs-step title="Ajouter un `input` au composant {#add-an-input-to-the-component}">

Modifiez le composant pour qu'il ait une propriété `input()` correspondant au nom du paramètre.

```ts
id = input.required<string>();
hero = computed(() => this.service.getHero(this.id()));
```

</docs-step>
<docs-step title="Facultatif : utiliser une valeur par défaut {#optional-use-a-default-value}">
Le router attribue des valeurs à tous les inputs en fonction de la route courante quand `withComponentInputBinding` est activé.
Le router attribue `undefined` si aucune donnée de route ne correspond à la clé de l'input, par exemple quand un query parameter facultatif est absent.
Incluez `undefined` dans le type de l'`input` lorsqu'il est possible qu'un input ne soit pas trouvé par la route.

Fournissez une valeur par défaut soit avec l'option `transform` de l'input, soit en gérant un état local avec un `linkedSignal`.

```ts
id = input.required({
  transform: (maybeUndefined: string | undefined) => maybeUndefined ?? '0',
});
// or
id = input<string | undefined>();
internalId = linkedSignal(() => this.id() ?? getDefaultId());
```

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

NOTE: Vous pouvez lier aux inputs du composant toutes les données de route sous forme de paires clé-valeur : resources de route, données de route statiques ou résolues, paramètres de chemin, paramètres matriciels et query parameters.

### Priorité du binding des inputs {#input-binding-priority}

Quand plusieurs sources de route définissent des clés identiques, le router résout les collisions selon l'ordre de priorité suivant (de la plus haute à la plus basse) :

1. **Resources de route** : les valeurs définies dans la map `resources` de la route. Les resources bloquantes lient leur valeur déballée (`resource.value()`), tandis que les resources non bloquantes lient l'instance de `Resource`.
2. **Données de route et resolvers** : les données statiques définies dans `data` ou les valeurs résolues via `resolve`.
3. **Paramètres de chemin et paramètres matriciels** : les paramètres issus du chemin de l'URL (comme `:id`) et les paramètres matriciels.
4. **Query parameters** : les paramètres issus de la query string (comme `?id=123`).

Par exemple, si une route possède à la fois un paramètre de chemin `:id` et un query parameter `?id=...`, la valeur du paramètre de chemin est liée à l'input `id` du composant. Si la route définit aussi une resource nommée `id`, la valeur de la resource l'emporte sur les deux.

### Désactiver le binding des query parameters {#disable-query-parameter-binding}

Utilisez `ComponentInputBindingOptions` pour désactiver le binding des query parameters si vous gérez les query parameters séparément :

```ts
provideRouter(appRoutes, withComponentInputBinding({queryParams: false}));
```

### Configurer le comportement des inputs absents des données du router {#configure-behavior-for-inputs-not-available-in-router-data}

Par défaut, le router définit un input à `undefined` s'il n'était pas disponible dans les données du router lors d'une navigation. Cela garantit que des données obsolètes ne sont pas conservées.

Si vous voulez éviter de définir `undefined` pour les inputs qui n'ont _jamais_ été disponibles dans les données du router pour l'instance de composant active, vous pouvez définir l'option `unmatchedInputBehavior` à `'undefinedIfStale'` :

```ts
provideRouter(appRoutes, withComponentInputBinding({unmatchedInputBehavior: 'undefinedIfStale'}));
```

Quand vous combinez `unmatchedInputBehavior: 'undefinedIfStale'` avec `queryParams: false`, les inputs conservent leurs valeurs initiales sauf s'ils sont explicitement fournis par le router. L'exception concerne les paramètres matriciels : si un paramètre matriciel est fourni lors d'une navigation puis retiré lors d'une suivante, le router définit l'input à `undefined` pour éviter de conserver des données obsolètes.

```ts
provideRouter(
  appRoutes,
  withComponentInputBinding({
    queryParams: false,
    unmatchedInputBehavior: 'undefinedIfStale',
  }),
);
```

### Hériter des données de la route parente {#inherit-parent-route-data}

Par défaut, les routes enfants héritent des paramètres et des données des routes parentes (équivalent à `paramsInheritanceStrategy: 'always'`). Vous pouvez donc accéder directement aux informations de la route parente dans les composants enfants.

Si vous devez restaurer l'ancien comportement, où les paramètres n'étaient hérités que des routes à chemin vide, vous pouvez définir `paramsInheritanceStrategy` à `'emptyOnly'` :

```ts
provideRouter(routes, withRouterConfig({paramsInheritanceStrategy: 'emptyOnly'}));
```

Consultez les [options de configuration du router](guide/routing/customizing-route-behavior#router-configuration-options) pour les autres paramètres disponibles.

## Afficher une page 404 {#displaying-a-404-page}

Pour afficher une page 404, configurez une [route wildcard](guide/routing/define-routes#wildcards) dont la propriété `component` désigne le composant à utiliser pour votre page 404, comme ceci :

```ts
const routes: Routes = [
  {path: 'first-component', component: First},
  {path: 'second-component', component: Second},
  {path: '**', component: PageNotFound}, // Wildcard route for a 404 page
];
```

La dernière route, dont le `path` vaut `**`, est une route wildcard.
Le router sélectionne cette route si l'URL demandée ne correspond à aucun des chemins précédents de la liste et envoie l'utilisateur vers `PageNotFound`.

## Tableau de paramètres de lien {#link-parameters-array}

Un tableau de paramètres de lien contient les éléments suivants pour la navigation du router :

- Le chemin de la route vers le composant de destination
- Les paramètres de route obligatoires et facultatifs qui entrent dans l'URL de la route

Liez la directive `RouterLink` à un tel tableau comme ceci :

```html
<a [routerLink]="['/heroes']">Heroes</a>
```

Voici un tableau à deux éléments lorsqu'on spécifie un paramètre de route :

```html
<a [routerLink]="['/hero', hero.id]">
  <span class="badge">{{ hero.id }}</span
  >{{ hero.name }}
</a>
```

Fournissez les paramètres de route facultatifs dans un objet, comme dans `{ foo: 'foo' }` :

```html
<a [routerLink]="['/crisis-center', {foo: 'foo'}]">Crisis Center</a>
```

Cette syntaxe transmet des paramètres matriciels, qui sont des paramètres facultatifs associés à un segment d'URL précis. En savoir plus sur les [paramètres matriciels](/guide/routing/read-route-state#matrix-parameters).

Ces trois exemples couvrent les besoins d'une application avec un seul niveau de routing.
Cependant, avec un router enfant, comme dans le centre de crise, vous créez de nouvelles possibilités de tableaux de liens.

L'exemple minimal de `RouterLink` suivant s'appuie sur une route enfant par défaut spécifiée pour le centre de crise.

```html
<a [routerLink]="['/crisis-center']">Crisis Center</a>
```

Remarquez les points suivants :

- Le premier élément du tableau identifie la route parente $`/crisis-center`$
- Cette route parente n'a pas de paramètres
- Il n'y a pas de valeur par défaut pour la route enfant, vous devez donc en choisir une
- Vous naviguez vers `CrisisList`, dont le chemin de route est `/`, mais vous n'avez pas besoin d'ajouter explicitement la barre oblique

Considérez le lien de router suivant, qui navigue de la racine de l'application jusqu'à la Dragon Crisis :

```html
<a [routerLink]="['/crisis-center', 1]">Dragon Crisis</a>
```

- Le premier élément du tableau identifie la route parente $`/crisis-center`$
- Cette route parente n'a pas de paramètres
- Le deuxième élément identifie la route enfant de détail d'une crise particulière $`/:id`$
- La route enfant de détail nécessite un paramètre de route `id`
- Vous avez ajouté l'`id` de la Dragon Crisis comme deuxième élément du tableau $`1`$
- Le chemin obtenu est `/crisis-center/1`

Vous pourriez aussi redéfinir le template de `App` exclusivement avec les routes du Crisis Center :

```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 App {}
```

En résumé, vous pouvez écrire des applications avec un, deux niveaux de routing ou plus.
Le tableau de paramètres de lien offre la flexibilité nécessaire pour représenter n'importe quelle profondeur de routing et n'importe quelle séquence valide de chemins de route, de paramètres de router $obligatoires$ et d'objets de paramètres de route $facultatifs$.

## `LocationStrategy` et styles d'URL du navigateur {#locationstrategy-and-browser-url-styles}

Quand le router navigue vers une nouvelle vue de composant, il met à jour l'emplacement et l'historique du navigateur avec une URL pour cette vue.

Les navigateurs HTML5 modernes prennent en charge [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'), une technique qui modifie l'emplacement et l'historique du navigateur sans déclencher de requête de page vers le serveur.
Le router peut composer une URL « naturelle », impossible à distinguer d'une URL qui nécessiterait autrement un chargement de page.

Voici l'URL du Crisis Center dans ce style « HTML5 pushState » :

```text
localhost:3002/crisis-center
```

Les navigateurs plus anciens envoient des requêtes de page au serveur quand l'URL de l'emplacement change, sauf si le changement se produit après un « # » $appelé « hash »$.
Les routers peuvent tirer parti de cette exception en composant des URL de route internes à l'application avec des hashes.
Voici une « URL hash » qui mène au Crisis Center.

```text
localhost:3002/src/#/crisis-center
```

Le router prend en charge les deux styles avec deux providers de `LocationStrategy` :

La fonction `RouterModule.forRoot()` définit la `LocationStrategy` sur `PathLocationStrategy`, ce qui en fait la stratégie par défaut.
Vous pouvez aussi passer à `HashLocationStrategy` avec une surcharge pendant le processus de bootstrap.

HELPFUL: Pour plus d'informations sur les providers et le processus de bootstrap, consultez [Injection de dépendances](guide/di/defining-dependency-providers).
# Créer des correspondances de route personnalisées

Le router d'Angular prend en charge une stratégie de correspondance puissante que vous pouvez utiliser pour aider les utilisateurs à naviguer dans votre application.
Cette stratégie de correspondance prend en charge les routes statiques, les routes variables avec paramètres, les routes wildcard, etc.
Vous pouvez aussi construire votre propre correspondance de motifs personnalisée pour les situations où les URL sont plus complexes.

Dans ce tutoriel, vous allez construire un route matcher personnalisé à l'aide de `UrlMatcher` d'Angular.
Ce matcher recherche un identifiant X (anciennement Twitter) dans l'URL.

## Objectifs {#objectives}

Implémenter `UrlMatcher` d'Angular pour créer un route matcher personnalisé.

## Créer une application d'exemple {#create-a-sample-application}

À l'aide de l'Angular CLI, créez une nouvelle application, _angular-custom-route-match_.
En plus du squelette d'application Angular par défaut, vous allez aussi créer un composant _profile_.

1. Créez un nouveau projet Angular, _angular-custom-route-match_.

```shell
ng new angular-custom-route-match
   ```

Lorsque la question `Would you like to add Angular routing?` s'affiche, sélectionnez `Y`.

Lorsque la question `Which stylesheet format would you like to use?` s'affiche, sélectionnez `CSS`.

Au bout de quelques instants, un nouveau projet, `angular-custom-route-match`, est prêt.

1. Depuis votre terminal, placez-vous dans le répertoire `angular-custom-route-match`.
1. Créez un composant, _profile_.

```shell
ng generate component profile
   ```

1. Dans votre éditeur de code, ouvrez le fichier `profile.html` et remplacez le contenu placeholder par le HTML suivant.

<docs-code header="profile.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.html"/>

1. Dans votre éditeur de code, ouvrez le fichier `app.html` et remplacez le contenu placeholder par le HTML suivant.

<docs-code header="app.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.html"/>

## Configurer les routes de votre application {#configure-your-routes-for-your-application}

Une fois le squelette de votre application en place, vous devez ensuite ajouter les fonctionnalités de routing au fichier `app.config.ts`.
Dans le cadre de ce processus, vous allez créer un URL matcher personnalisé qui recherche un identifiant X dans l'URL.
Cet identifiant se reconnaît au symbole `@` qui le précède.

1. Dans votre éditeur de code, ouvrez votre fichier `app.config.ts`.
1. Ajoutez une instruction `import` pour `provideRouter` et `withComponentInputBinding` d'Angular, ainsi que pour les routes de l'application.

```ts
import {provideRouter, withComponentInputBinding} from '@angular/router';

import {routes} from './app.routes';
   ```

1. Dans le tableau des providers, ajoutez une instruction `provideRouter(routes, withComponentInputBinding())`.

1. Définissez le route matcher personnalisé en ajoutant le code suivant aux routes de l'application.

<docs-code header="app.routes.ts" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.routes.ts" region="matcher"/>

Ce matcher personnalisé est une fonction qui effectue les tâches suivantes :

- Le matcher vérifie que le tableau ne contient qu'un seul segment
- Le matcher utilise une expression régulière pour vérifier que le format du nom d'utilisateur correspond
- En cas de correspondance, la fonction renvoie l'URL entière, en définissant un paramètre de route `username` comme sous-chaîne du chemin
- En l'absence de correspondance, la fonction renvoie null et le router continue de chercher d'autres routes qui correspondent à l'URL

HELPFUL: Un URL matcher personnalisé se comporte comme n'importe quelle autre définition de route. Définissez des routes enfants ou des routes chargées en lazy loading comme vous le feriez pour n'importe quelle autre route.

## Lire les paramètres de route {#reading-the-route-parameters}

Une fois le matcher personnalisé en place, vous pouvez maintenant lier le paramètre de route dans le composant `profile`.

Dans votre éditeur de code, ouvrez votre fichier `profile.ts` et créez un `input` correspondant au paramètre `username`.
Nous avons ajouté la fonctionnalité `withComponentInputBinding` plus tôt
dans `provideRouter`. Elle permet au `Router` de lier des informations directement aux composants des routes.

```ts
username = input.required<string>();
```

## Tester votre URL matcher personnalisé {#test-your-custom-url-matcher}

Une fois votre code en place, vous pouvez maintenant tester votre URL matcher personnalisé.

1. Dans une fenêtre de terminal, exécutez la commande `ng serve`.

```shell
ng serve
   ```

1. Ouvrez un navigateur à l'adresse `http://localhost:4200`.

Vous devriez voir une page web unique, composée d'une phrase qui indique `Navigate to my profile`.

1. Cliquez sur le lien **my profile**.

Une nouvelle phrase, `Hello, Angular!`, apparaît sur la page.

## Prochaines étapes {#next-steps}

La correspondance de motifs avec le router d'Angular vous offre une grande flexibilité lorsque votre application comporte des URL dynamiques.
Pour en savoir plus sur le router d'Angular, consultez les sujets suivants :
HELPFUL: Ce contenu s'inspire de [Custom Route Matching with the Angular Router](https://medium.com/@brandontroberts/custom-route-matching-with-the-angular-router-fbdd48665483), par [Brandon Roberts](https://x.com/brandontroberts).
# Rendu serveur et hybride

Angular livre par défaut toutes les applications en rendu côté client (CSR). Si cette approche fournit une charge initiale légère, elle introduit des compromis : temps de chargement plus lents, métriques de performance dégradées et besoins en ressources plus élevés, puisque l'appareil de l'utilisateur effectue la plupart des calculs. C'est pourquoi de nombreuses applications obtiennent des gains de performances significatifs en intégrant le rendu côté serveur (SSR) dans une stratégie de rendu hybride.

## Qu'est-ce que le rendu hybride ? {#what-is-hybrid-rendering}

Le rendu hybride permet aux développeurs de tirer parti des avantages du rendu côté serveur (SSR), du prérendu (aussi appelé « génération de site statique » ou SSG) et du rendu côté client (CSR) pour optimiser votre application Angular. Il vous donne un contrôle fin sur la façon dont les différentes parties de votre application sont rendues, afin d'offrir à vos utilisateurs la meilleure expérience possible.

## Mettre en place le rendu hybride {#setting-up-hybrid-rendering}

Vous pouvez créer un **nouveau** projet avec rendu hybride en utilisant le flag de rendu côté serveur (c'est-à-dire `--ssr`) avec la commande `ng new` d'Angular CLI :

```shell
ng new --ssr
```

Vous pouvez aussi activer le rendu hybride en ajoutant le rendu côté serveur à un projet existant avec la commande `ng add` :

```shell
ng add @angular/ssr
```

NOTE: Par défaut, Angular prérend toute votre application et génère un fichier serveur. Pour désactiver ce comportement et créer une application entièrement statique, définissez `outputMode` à `static`. Pour activer le SSR, mettez à jour les routes serveur pour qu'elles utilisent `RenderMode.Server`. Pour plus de détails, consultez [`Server routing`](#server-routing) et [`Generate a fully static application`](#generate-a-fully-static-application).

## Routing côté serveur {#server-routing}

### Configurer les routes serveur {#configuring-server-routes}

Vous pouvez créer une configuration de routes serveur en déclarant un tableau d'objets [`ServerRoute`](api/ssr/ServerRoute 'API reference'). Cette configuration se trouve généralement dans un fichier nommé `app.routes.server.ts`.

```typescript
{header: "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,
  },
];
```

Vous pouvez ajouter cette configuration à votre application avec [`provideServerRendering`](api/ssr/provideServerRendering 'API reference') en utilisant la fonction [`withRoutes`](api/ssr/withRoutes 'API reference') :

```typescript
{header: "app.config.server.ts"}
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {serverRoutes} from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
    // ... other providers ...
  ],
};
```

Lorsque vous utilisez le [pattern App shell](ecosystem/service-workers/app-shell), vous devez indiquer le composant à utiliser comme app shell pour les routes rendues côté client. Pour cela, utilisez la fonctionnalité [`withAppShell`](api/ssr/withAppShell 'API reference') :

```typescript
import {provideServerRendering, withRoutes, withAppShell} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {AppShell} from './app-shell';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes), withAppShell(AppShell)),
    // ... other providers ...
  ],
};
```

### Modes de rendu {#rendering-modes}

La configuration du routing côté serveur vous permet d'indiquer comment chaque route de votre application doit être rendue en définissant un [`RenderMode`](api/ssr/RenderMode 'API reference') :

| Mode de rendu       | Description                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Serveur (SSR)**   | Rend l'application sur le serveur pour chaque requête, en envoyant au navigateur une page HTML entièrement remplie. |
| **Client (CSR)**    | Rend l'application dans le navigateur. C'est le comportement par défaut d'Angular.                               |
| **Prérendu (SSG)**  | Prérend l'application au moment du build, en générant des fichiers HTML statiques pour chaque route.                      |

#### Choisir un mode de rendu {#choosing-a-rendering-mode}

Chaque mode de rendu présente des avantages et des inconvénients différents. Vous pouvez choisir les modes de rendu en fonction des besoins spécifiques de votre application.

##### Rendu côté client (CSR) {#client-side-rendering-csr}

Le rendu côté client offre le modèle de développement le plus simple, puisque vous pouvez écrire du code en supposant qu'il s'exécute toujours dans un navigateur web. Cela vous permet d'utiliser un large éventail de libraries côté client qui supposent, elles aussi, s'exécuter dans un navigateur.

Le rendu côté client offre généralement de moins bonnes performances que les autres modes de rendu, car il doit télécharger, analyser et exécuter le JavaScript de votre page avant que l'utilisateur puisse voir le moindre contenu rendu. Si votre page récupère d'autres données depuis le serveur pendant le rendu, les utilisateurs doivent aussi attendre ces requêtes supplémentaires avant de pouvoir consulter le contenu complet.

Si votre page est indexée par des robots d'indexation, le rendu côté client peut nuire au référencement (SEO), car les robots d'indexation limitent la quantité de JavaScript qu'ils exécutent lorsqu'ils indexent une page.

Avec le rendu côté client, le serveur n'a aucun travail à effectuer pour rendre une page, hormis servir des ressources JavaScript statiques. Vous pouvez tenir compte de ce facteur si le coût du serveur vous préoccupe.

Les applications qui proposent des expériences installables et hors ligne grâce aux [service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) peuvent s'appuyer sur le rendu côté client sans avoir besoin de communiquer avec un serveur.

##### Rendu côté serveur (SSR) {#server-side-rendering-ssr}

Le rendu côté serveur offre des chargements de page plus rapides que le rendu côté client. Au lieu d'attendre le téléchargement et l'exécution du JavaScript, le serveur rend directement un document HTML dès qu'il reçoit une requête du navigateur. L'utilisateur ne subit que la latence nécessaire au serveur pour récupérer les données et rendre la page demandée. Ce mode élimine aussi le besoin de requêtes réseau supplémentaires depuis le navigateur, puisque votre code peut récupérer les données pendant le rendu sur le serveur.

Le rendu côté serveur offre généralement un excellent référencement (SEO), car les robots d'indexation reçoivent un document HTML entièrement rendu.

Le rendu côté serveur vous oblige à écrire du code qui ne dépend pas strictement des API du navigateur, et restreint votre choix parmi les libraries JavaScript qui supposent s'exécuter dans un navigateur.

Avec le rendu côté serveur, votre serveur exécute Angular pour produire une réponse HTML à chaque requête, ce qui peut augmenter les coûts d'hébergement du serveur.

##### Prérendu au moment du build {#build-time-prerendering}

Le prérendu offre des chargements de page plus rapides que le rendu côté client et que le rendu côté serveur. Comme le prérendu crée les documents HTML _au moment du build_, le serveur peut répondre directement aux requêtes avec le document HTML statique, sans aucun travail supplémentaire.

Le prérendu exige que toutes les informations nécessaires au rendu d'une page soient disponibles _au moment du build_. Les pages prérendues ne peuvent donc inclure aucune donnée propre à l'utilisateur qui charge la page. Le prérendu est surtout utile pour les pages identiques pour tous les utilisateurs de votre application.

Comme le prérendu a lieu au moment du build, il peut allonger sensiblement vos builds de production. Utiliser [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') pour produire un grand nombre de documents HTML peut affecter la taille totale des fichiers de vos déploiements, et donc ralentir ces derniers.

Le prérendu offre généralement un excellent référencement (SEO), car les robots d'indexation reçoivent un document HTML entièrement rendu.

Le prérendu vous oblige à écrire du code qui ne dépend pas strictement des API du navigateur, et restreint votre choix parmi les libraries JavaScript qui supposent s'exécuter dans un navigateur.

Le prérendu n'entraîne qu'un surcoût infime par requête serveur, puisque votre serveur répond avec des documents HTML statiques. Les fichiers statiques sont aussi facilement mis en cache par les Content Delivery Networks (CDN), les navigateurs et les couches de cache intermédiaires, pour des chargements de page suivants encore plus rapides. Les sites entièrement statiques peuvent aussi être déployés uniquement via un CDN ou un serveur de fichiers statiques, ce qui évite de maintenir un runtime serveur personnalisé pour votre application. Cela améliore la scalabilité en déchargeant le serveur web de l'application, ce qui est particulièrement intéressant pour les applications à fort trafic.

NOTE: Avec le service worker d'Angular, la première requête est rendue par le serveur, mais toutes les requêtes suivantes sont gérées par le service worker et rendues côté client.

### Définir les en-têtes et les codes de statut {#setting-headers-and-status-codes}

Vous pouvez définir des en-têtes et des codes de statut personnalisés pour des routes serveur individuelles grâce aux propriétés `headers` et `status` de la configuration `ServerRoute`.

```typescript
{header: "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
];
```

### Redirections {#redirects}

Angular gère différemment, côté serveur, les redirections indiquées par la propriété [`redirectTo`](api/router/Route#redirectTo 'API reference') dans les configurations de routes.

**Rendu côté serveur (SSR)**
Les redirections sont effectuées à l'aide de redirections HTTP standard (par exemple 301, 302) pendant le processus de rendu côté serveur.

**Prérendu (SSG)**
Les redirections sont implémentées comme des « soft redirects » à l'aide de balises [`<meta http-equiv="refresh">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#refresh) dans le HTML prérendu.

### Personnaliser le prérendu au moment du build (SSG) {#customizing-build-time-prerendering-ssg}

Lorsque vous utilisez [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), vous pouvez indiquer plusieurs options de configuration pour personnaliser le processus de prérendu et de diffusion.

#### Routes paramétrées {#parameterized-routes}

Pour chaque route avec [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), vous pouvez indiquer une fonction [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference'). Cette fonction vous permet de contrôler quels paramètres produisent des documents prérendus distincts.

La fonction [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') renvoie une `Promise` qui se résout en un tableau d'objets. Chaque objet est une map clé-valeur qui associe le nom d'un paramètre de route à sa valeur. Par exemple, si vous définissez une route comme `post/:id`, `getPrerenderParams ` pourrait renvoyer le tableau `[{id: '123'}, {id: '456'}]`, et ainsi rendre des documents distincts pour `post/123` et `post/456`.

Le corps de [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') peut utiliser la fonction [`inject`](api/core/inject 'API reference') d'Angular pour injecter des dépendances et effectuer tout traitement permettant de déterminer quelles routes prérendre. Cela inclut généralement des requêtes pour récupérer les données nécessaires à la construction du tableau de valeurs de paramètres.

Vous pouvez aussi utiliser cette fonction avec des routes wildcard (par exemple `/**`) : le nom du paramètre sera alors `"**"` et la valeur renvoyée sera les segments du chemin, comme `foo/bar`. Vous pouvez les combiner avec d'autres paramètres (par exemple `/post/:id/**`) pour gérer des configurations de routes plus complexes.

```ts
{header: "app.routes.server.ts"}
import {RenderMode, ServerRoute} from '@angular/ssr';
import {inject} from '@angular/core';

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
    },
  },
];
```

Comme [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') s'applique exclusivement à [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), cette fonction s'exécute toujours _au moment du build_. `getPrerenderParams` ne doit dépendre d'aucune API propre au navigateur ou au serveur pour obtenir ses données.

IMPORTANT: Lorsque vous utilisez [`inject`](api/core/inject 'API reference') dans `getPrerenderParams`, n'oubliez pas que `inject` doit être utilisé de manière synchrone. Il ne peut pas être appelé dans des callbacks asynchrones ni après une instruction `await`. Pour plus d'informations, consultez `runInInjectionContext`.

#### Stratégies de repli {#fallback-strategies}

Lorsque vous utilisez le mode [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), vous pouvez indiquer une stratégie de repli pour gérer les requêtes vers des chemins qui n'ont pas été prérendus.

Les stratégies de repli disponibles sont :

- **Server :** se replie sur le rendu côté serveur. C'est le comportement **par défaut** si aucune propriété `fallback` n'est indiquée.
- **Client :** se replie sur le rendu côté client.
- **None :** aucun repli. Angular ne gère pas les requêtes vers des chemins qui ne sont pas prérendus.

```ts
{header: "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'}];
    },
  },
];
```

## Écrire des composants compatibles avec le serveur {#authoring-server-compatible-components}

Certaines API et capacités courantes du navigateur peuvent ne pas être disponibles sur le serveur. Les applications ne peuvent pas utiliser les objets globaux propres au navigateur comme `window`, `document`, `navigator` ou `location`, ni certaines propriétés de `HTMLElement`.

En général, le code qui dépend de symboles propres au navigateur ne doit être exécuté que dans le navigateur, et non sur le serveur. Vous pouvez l'imposer grâce aux lifecycle hooks `afterEveryRender` et `afterNextRender`. Ceux-ci ne sont exécutés que dans le navigateur et sont ignorés sur le serveur.

```typescript
import {Component, ElementRef, 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);
    });
  }
}
```

NOTE: Préférez les [providers propres à chaque plateforme](guide/ssr#providing-platform-specific-implementations) aux vérifications à l'exécution avec `isPlatformBrowser` ou `isPlatformServer`.

IMPORTANT: Évitez d'utiliser `isPlatformBrowser` dans les templates avec `@if` ou d'autres conditions pour rendre un contenu différent sur le serveur et sur le client. Cela provoque des incohérences d'hydratation et des décalages de mise en page (layout shifts), ce qui dégrade l'expérience utilisateur et les [Core Web Vitals](https://web.dev/learn-core-web-vitals/). Utilisez plutôt `afterNextRender` pour l'initialisation propre au navigateur et gardez un contenu rendu identique sur toutes les plateformes.

## Définir les providers sur le serveur {#setting-providers-on-the-server}

Côté serveur, les valeurs des providers de premier niveau sont définies une seule fois, lorsque le code de l'application est initialement analysé et évalué.
Cela signifie que les providers configurés avec `useValue` conservent leur valeur d'une requête à l'autre, jusqu'au redémarrage de l'application serveur.

Si vous voulez générer une nouvelle valeur pour chaque requête, utilisez un provider de fabrique avec `useFactory`. La fonction de fabrique s'exécute pour chaque requête entrante, ce qui garantit qu'une nouvelle valeur est créée et associée au jeton à chaque fois.

## Fournir des implémentations propres à chaque plateforme {#providing-platform-specific-implementations}

Lorsque votre application a besoin d'un comportement différent dans le navigateur et sur le serveur, fournissez des implémentations de service distinctes pour chaque plateforme. Cette approche centralise la logique propre à chaque plateforme dans des services dédiés.

```ts
export abstract class AnalyticsService {
  abstract trackEvent(name: string): void;
}
```

Créez l'implémentation pour le navigateur :

```ts
@Injectable()
export class BrowserAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Sends the event to the browser-based third-party analytics provider
  }
}
```

Créez l'implémentation pour le serveur :

```ts
@Injectable()
export class ServerAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Records the event on the server
  }
}
```

Enregistrez l'implémentation pour le navigateur dans la configuration principale de votre application :

```ts
{header: "app.config.ts"}
export const appConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: BrowserAnalyticsService}],
};
```

Remplacez-la par l'implémentation serveur dans votre configuration serveur :

```ts
{header: "app.config.server.ts"}
const serverConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: ServerAnalyticsService}],
};
```

Injectez et utilisez le service dans vos composants :

```ts
@Component(/* ... */)
export class Checkout {
  private analytics = inject(AnalyticsService);

onAction() {
    this.analytics.trackEvent('action');
  }
}
```

## Accéder à Document via la DI {#accessing-document-via-di}

Lorsque vous travaillez avec le rendu côté serveur, évitez de référencer directement des variables globales propres au navigateur comme `document`. Utilisez plutôt le jeton [`DOCUMENT`](api/core/DOCUMENT) pour accéder à l'objet document de manière indépendante de la plateforme.

```ts
import {inject, DOCUMENT, Service} from '@angular/core';

@Service()
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: Pour gérer les balises meta, Angular fournit le service `Meta`.

## Accéder à la requête et à la réponse via la DI {#accessing-request-and-response-via-di}

Le package `@angular/core` fournit plusieurs jetons pour interagir avec l'environnement de rendu côté serveur. Ces jetons vous donnent accès à des informations et à des objets essentiels dans votre application Angular pendant le SSR.

- **[`REQUEST`](api/core/REQUEST 'API reference') :** donne accès à l'objet de la requête courante, de type [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) de la Web API. Cela vous permet d'accéder aux en-têtes, aux cookies et aux autres informations de la requête.
- **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API reference') :** donne accès aux options d'initialisation de la réponse, de type [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters) de la Web API. Cela vous permet de définir dynamiquement les en-têtes et le code de statut de la réponse. Utilisez ce jeton pour définir les en-têtes ou les codes de statut qui doivent être déterminés à l'exécution.
- **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API reference') :** donne accès à un contexte supplémentaire lié à la requête courante. Ce contexte peut être passé comme second paramètre de la fonction [`handle`](api/ssr/AngularAppEngine#handle 'API reference'). On l'utilise généralement pour fournir des informations supplémentaires liées à la requête qui ne font pas partie de la Web API standard.

```typescript
import {inject, REQUEST, Component} 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: Les jetons ci-dessus valent `null` dans les cas suivants :<ul class="docs-list">
  <li>Pendant les processus de build.</li>
  <li>Lorsque l'application est rendue dans le navigateur (CSR).</li>
  <li>Lors de la génération de site statique (SSG).</li>
  <li>Pendant l'extraction des routes en développement (au moment de la requête).</li>
</ul>

## Générer une application entièrement statique {#generate-a-fully-static-application}

Par défaut, Angular prérend toute votre application et génère un fichier serveur pour gérer les requêtes. Cela permet à votre application de servir du contenu prérendu aux utilisateurs. Cependant, si vous préférez un site entièrement statique sans serveur, vous pouvez désactiver ce comportement en définissant `outputMode` à `static` dans votre fichier de configuration `angular.json`.

Lorsque `outputMode` vaut `static`, Angular génère des fichiers HTML prérendus pour chaque route au moment du build, mais il ne génère pas de fichier serveur et ne nécessite pas de serveur Node.js pour servir l'application. C'est utile pour un déploiement chez des hébergeurs statiques, lorsqu'aucun serveur backend n'est nécessaire.

Pour cela, mettez à jour votre fichier `angular.json` comme suit :

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```

## Mettre en cache les données avec HttpClient {#caching-data-when-using-httpclient}

`HttpClient` met en cache les requêtes réseau sortantes lorsqu'il s'exécute sur le serveur. Ces informations sont sérialisées et transférées au navigateur dans le HTML initial envoyé par le serveur. Dans le navigateur, `HttpClient` vérifie s'il dispose de données dans le cache et, si c'est le cas, les réutilise au lieu d'effectuer une nouvelle requête HTTP pendant le rendu initial de l'application. `HttpClient` cesse d'utiliser le cache dès qu'une application devient [stable](api/core/ApplicationRef#isStable) dans le navigateur.

### Configurer la taille maximale du corps de réponse {#configuring-the-response-body-size-limit}

Lorsque `HttpClient` utilise le backend fetch par défaut pendant le rendu côté serveur, Angular limite chaque corps de réponse à 1 Mo. Cette limite empêche le serveur de mettre en mémoire tampon des réponses anormalement volumineuses pendant le rendu. Si une réponse dépasse la limite configurée, la requête échoue avec l'erreur [NG02825](errors/NG02825).

Si votre application doit récupérer des réponses plus volumineuses pendant le rendu serveur, définissez `maxResponseBodySize` dans les options de `provideServerRendering` :

```ts
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {serverRoutes} from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      {
        maxResponseBodySize: 5 * 1024 * 1024, // 5MB
      },
      withRoutes(serverRoutes),
    ),
  ],
};
```

`maxResponseBodySize` s'exprime en octets et s'applique globalement aux requêtes `HttpClient` côté serveur qui utilisent le backend fetch.

IMPORTANT: Gardez cette limite aussi basse que votre application le permet. L'augmenter permet aux requêtes côté serveur de mettre en mémoire tampon des corps de réponse plus volumineux, ce qui peut accroître la consommation mémoire et le risque de déni de service. Déplacez de préférence les téléchargements volumineux en dehors du rendu serveur.

CRITICAL: Pendant le SSR, l'implémentation de Fetch lit l'intégralité du corps de la réponse pour vérifier `integrity` avant de renvoyer une réponse, comme l'exige le [Fetch Standard](https://fetch.spec.whatwg.org/#concept-main-fetch). Angular n'applique [`maxResponseBodySize`](/guide/ssr#configuring-the-response-body-size-limit) qu'une fois que Fetch a renvoyé une réponse ; cette limite ne contraint donc pas les données mises en mémoire tampon pendant la vérification d'intégrité.

### Configurer les options de mise en cache {#configuring-the-caching-options}

Vous pouvez personnaliser la façon dont Angular met en cache les réponses HTTP pendant le rendu côté serveur (SSR) et les réutilise pendant l'hydratation en configurant `HttpTransferCacheOptions`.  
Cette configuration est fournie globalement avec `withHttpTransferCacheOptions` dans `provideClientHydration()`.

Par défaut, `HttpClient` met en cache toutes les requêtes `HEAD` et `GET` qui ne contiennent pas d'en-tête `Authorization`, `Proxy-Authorization` ou `Cookie` et qui ne sont pas envoyées avec `withCredentials` ou avec des modes `credentials` de la Fetch API susceptibles d'envoyer des identifiants. Angular ignore aussi le transfer cache lorsqu'une requête ou une réponse contient des directives `Cache-Control` qui interdisent la mise en cache (`no-store`, `no-cache` ou `private`), ou lorsque l'option `cache` de la Fetch API vaut `no-store` ou `no-cache`. Les réponses qui portent un en-tête `Set-Cookie` sont également ignorées. Vous pouvez remplacer les paramètres de filtrage des requêtes avec `withHttpTransferCacheOptions` dans la configuration de l'hydratation.

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includeHeaders: ['ETag', 'Cache-Control'],
        filter: (req) => !req.url.includes('/api/profile'),
        includePostRequests: true,
        includeRequestsWithAuthHeaders: false,
      }),
    ),
  ],
});
```

### `includeHeaders` {#includeheaders}

Indique quels en-têtes de la réponse du serveur doivent être inclus dans les entrées mises en cache.  
Aucun en-tête n'est inclus par défaut.

```ts
withHttpTransferCacheOptions({
  includeHeaders: ['ETag', 'Cache-Control'],
});
```

IMPORTANT: Évitez d'inclure des en-têtes sensibles comme les jetons d'authentification. Ils peuvent faire fuiter des données propres à un utilisateur d'une requête à l'autre.

Inclure `Cache-Control` dans `includeHeaders` rend seulement cet en-tête disponible dans la réponse hydratée. Angular évalue déjà automatiquement les en-têtes `Cache-Control` pour décider si une requête ou une réponse est éligible au transfer cache.

### `includePostRequests` {#includepostrequests}

Par défaut, seules les requêtes `GET` et `HEAD` sont mises en cache.  
Vous pouvez activer la mise en cache des requêtes `POST` lorsqu'elles servent d'opérations de lecture, comme les requêtes GraphQL.

```ts
withHttpTransferCacheOptions({
  includePostRequests: true,
});
```

N'utilisez cette option que lorsque les requêtes `POST` sont **idempotentes** et peuvent être réutilisées sans risque entre le rendu serveur et le rendu client.

### `includeRequestsWithAuthHeaders` {#includerequestswithauthheaders}

Détermine si les requêtes contenant les en-têtes `Authorization`, `Proxy‑Authorization` ou `Cookie` sont éligibles à la mise en cache.  
Par défaut, elles sont exclues pour éviter de mettre en cache des réponses propres à un utilisateur.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithAuthHeaders: true,
});
```

Activez cette option uniquement lorsque les en-têtes d'authentification n'affectent **pas** le contenu de la réponse (par exemple, des jetons publics pour des API d'analytics).

### `includeRequestsWithCredentials` {#includerequestswithcredentials}

Détermine si les requêtes envoyées avec `withCredentials` ou avec les modes `credentials` de la Fetch API (`include` ou `same-origin`) sont éligibles à la mise en cache.  
Par défaut, elles sont exclues pour éviter de mettre en cache des réponses propres à un utilisateur.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithCredentials: true,
});
```

Activez cette option uniquement lorsque les requêtes avec identifiants renvoient des réponses qui peuvent être mises en cache sans risque.

### `includeNonCacheableRequests` {#includenoncacheablerequests}

Détermine si les requêtes et les réponses contenant des directives `Cache-Control` qui interdisent la mise en cache (`no-store`, `no-cache` ou `private`), les réponses avec un en-tête `Set-Cookie`, ou les requêtes utilisant les options `cache` de la Fetch API (`no-store` ou `no-cache`) sont éligibles à la mise en cache.  
Par défaut, elles sont exclues afin de respecter les directives de mise en cache HTTP.

```ts
withHttpTransferCacheOptions({
  includeNonCacheableRequests: true,
});
```

Activez cette option uniquement lorsque vous devez contourner les restrictions de cache-control pour le transfer cache.

### Surcharges par requête {#perrequest-overrides}

Vous pouvez surcharger le comportement de mise en cache d'une requête précise avec l'option de requête `transferCache`.

```ts
// Include specific headers for this request
http.get('/api/profile', {transferCache: {includeHeaders: ['CustomHeader']}});
```

### Désactiver la mise en cache {#disabling-caching}

Vous pouvez désactiver la mise en cache HTTP des requêtes envoyées depuis le serveur, soit globalement, soit individuellement.

#### Globalement {#globally}

Pour désactiver la mise en cache de toutes les requêtes de votre application, utilisez la fonctionnalité `withNoHttpTransferCache` :

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoHttpTransferCache,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoHttpTransferCache())],
});
```

#### Filtrage {#filtering}

Vous pouvez aussi désactiver sélectivement la mise en cache de certaines requêtes avec l'option [`filter`](api/common/http/HttpTransferCacheOptions) de `withHttpTransferCacheOptions`. Par exemple, vous pouvez désactiver la mise en cache pour un endpoint d'API précis :

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        filter: (req) => !req.url.includes('/api/sensitive-data'),
      }),
    ),
  ],
});
```

Utilisez cette option pour exclure les endpoints qui renvoient des données dynamiques ou propres à un utilisateur (par exemple `/api/profile`).

#### Par requête {#per-request}

Pour désactiver la mise en cache d'une requête individuelle, vous pouvez indiquer l'option [`transferCache`](api/common/http/HttpRequest#transferCache) dans une `HttpRequest`.

```ts
httpClient.get('/api/sensitive-data', {transferCache: false});
```

`HttpTransferCache` ne met pas en cache les requêtes ou les réponses qui refusent explicitement la mise en cache. Angular ignore les entrées du transfer cache lorsqu'une requête contient un en-tête `Cache-Control` avec `no-store`, `no-cache` ou `private`, ou lorsque la requête utilise l'option `cache` de la Fetch API définie à `no-store` ou `no-cache`. Les réponses avec `Cache-Control: no-store`, `Cache-Control: no-cache` ou `Cache-Control: private` ne sont pas non plus stockées dans le transfer cache. Les réponses qui contiennent un en-tête `Set-Cookie` ne sont pas stockées non plus, car elles portent généralement un état propre à l'utilisateur.

NOTE: Si votre application utilise des origines HTTP différentes pour effectuer les appels d'API sur le serveur et sur le client, le jeton `HTTP_TRANSFER_CACHE_ORIGIN_MAP` vous permet d'établir une correspondance entre ces origines, afin que la fonctionnalité `HttpTransferCache` reconnaisse ces requêtes comme identiques et réutilise, pendant l'hydratation côté client, les données mises en cache sur le serveur.

## Configurer un serveur {#configuring-a-server}

### Node.js {#nodejs}

`@angular/ssr/node` étend `@angular/ssr` spécifiquement pour les environnements Node.js. Il fournit des API qui facilitent la mise en œuvre du rendu côté serveur dans votre application Node.js. Pour la liste complète des fonctions et des exemples d'utilisation, consultez la [référence de l'API `@angular/ssr/node`](api/ssr/node/AngularNodeAppEngine).

```ts
{header: "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);
```

### Hors Node.js {#non-nodejs}

`@angular/ssr` fournit les API essentielles pour effectuer le rendu côté serveur de votre application Angular sur des plateformes autres que Node.js. Il s'appuie sur les objets standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) et [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) de la Web API, ce qui vous permet d'intégrer le SSR d'Angular dans divers environnements serveur. Pour des informations détaillées et des exemples, consultez la [référence de l'API `@angular/ssr`](api/ssr/AngularAppEngine).

```ts
{header: "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.handle(req);

// ...
});
```

## Sécurité {#security}

Pour des informations détaillées sur la prévention de la falsification de requête côté serveur (SSRF) et la configuration des hôtes autorisés, consultez le guide [Sécurité côté serveur](best-practices/security#preventing-server-side-request-forgery-ssrf).
# Hydratation

## Qu'est-ce que l'hydratation {#what-is-hydration}

L'hydratation est le processus qui restaure côté client l'application rendue côté serveur. Cela inclut notamment la réutilisation des structures DOM rendues par le serveur, la conservation de l'état de l'application, le transfert des données de l'application déjà récupérées par le serveur, ainsi que d'autres processus.

## Pourquoi l'hydratation est-elle importante ? {#why-is-hydration-important}

L'hydratation améliore les performances de l'application en évitant le travail supplémentaire de recréation des nœuds DOM. Angular essaie plutôt de faire correspondre, à l'exécution, les éléments DOM existants à la structure de l'application et réutilise les nœuds DOM lorsque c'est possible. Il en résulte une amélioration des performances mesurable à l'aide des statistiques [Core Web Vitals (CWV)](https://web.dev/learn-core-web-vitals/), comme la réduction du First Input Delay ([FID](https://web.dev/fid/)) et du Largest Contentful Paint ([LCP](https://web.dev/lcp/)), ainsi que du Cumulative Layout Shift ([CLS](https://web.dev/cls/)). L'amélioration de ces chiffres a aussi un effet sur des aspects comme les performances SEO.

Sans hydratation activée, les applications Angular rendues côté serveur détruisent et rendent à nouveau le DOM de l'application, ce qui peut provoquer un scintillement visible de l'interface. Ce nouveau rendu peut avoir un impact négatif sur les [Core Web Vitals](https://web.dev/learn-core-web-vitals/) comme le [LCP](https://web.dev/lcp/) et provoquer un décalage de mise en page. Activer l'hydratation permet de réutiliser le DOM existant et évite ce scintillement.

## Comment activer l'hydratation dans Angular {#how-do-you-enable-hydration-in-angular}

L'hydratation ne peut être activée que pour les applications rendues côté serveur (SSR). Suivez d'abord le [guide SSR d'Angular](guide/ssr) pour activer le rendu côté serveur.

### Avec Angular CLI {#using-angular-cli}

Si vous avez utilisé Angular CLI pour activer le SSR (soit lors de la création de l'application, soit plus tard via `ng add @angular/ssr`), le code qui active l'hydratation devrait déjà être inclus dans votre application.

### Configuration manuelle {#manual-setup}

Si vous avez une configuration personnalisée et n'avez pas utilisé Angular CLI pour activer le SSR, vous pouvez activer l'hydratation manuellement en ouvrant le composant ou le module principal de votre application et en important `provideClientHydration` depuis `@angular/platform-browser`. Ajoutez ensuite ce provider à la liste des providers du bootstrap de votre application.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration()]
});
```

Si vous utilisez des NgModules, ajoutez plutôt `provideClientHydration` à la liste des providers du module racine de votre application.

```typescript
import {provideClientHydration} from '@angular/platform-browser';
import {NgModule} from '@angular/core';

@NgModule({
  declarations: [App],
  exports: [App],
  bootstrap: [App],
  providers: [provideClientHydration()],
})
export class AppModule {}
```

IMPORTANT: Assurez-vous que l'appel à `provideClientHydration()` est aussi inclus dans l'ensemble des providers utilisé pour le bootstrap de l'application sur le **serveur**. Dans les applications qui suivent la structure de projet par défaut (générée par la commande `ng new`), ajouter l'appel au `AppModule` racine devrait suffire, puisque ce module est importé par le module serveur. Si vous utilisez une configuration personnalisée, ajoutez l'appel à `provideClientHydration()` à la liste des providers de la configuration du bootstrap côté serveur.

### Vérifier que l'hydratation est activée {#verify-that-hydration-is-enabled}

Après avoir configuré l'hydratation et démarré votre serveur, chargez votre application dans le navigateur.

HELPFUL: Vous devrez probablement corriger les cas de manipulation directe du DOM avant que l'hydratation fonctionne pleinement, soit en passant à des constructions Angular, soit en utilisant `ngSkipHydration`. Consultez [Contraintes](#constraints), [Manipulation directe du DOM](#direct-dom-manipulation) et [Comment ignorer l'hydratation pour certains composants](#how-to-skip-hydration-for-particular-components) pour plus de détails.

Lorsque l'application s'exécute en mode développement, vous pouvez confirmer que l'hydratation est activée en ouvrant les outils de développement de votre navigateur et en consultant la console. Vous devriez voir un message contenant des statistiques liées à l'hydratation, comme le nombre de composants et de nœuds hydratés. Angular calcule ces statistiques à partir de tous les composants rendus sur une page, y compris ceux qui proviennent de libraries tierces.

Vous pouvez aussi utiliser [l'extension de navigateur Angular DevTools](tools/devtools) pour voir l'état d'hydratation des composants d'une page. Angular DevTools permet également d'activer une surcouche indiquant quelles parties de la page ont été hydratées. En cas d'erreur d'incohérence d'hydratation, DevTools met aussi en évidence le composant à l'origine de l'erreur.

## Capturer et rejouer les événements {#capturing-and-replaying-events}

Lorsqu'une application est rendue sur le serveur, elle est visible dans le navigateur dès que le HTML produit est chargé. Les utilisateurs peuvent penser qu'ils peuvent interagir avec la page, mais les event listeners ne sont attachés qu'une fois l'hydratation terminée. La fonctionnalité Event Replay capture tous les événements qui se produisent avant l'hydratation et les rejoue une fois l'hydratation terminée.

L'event replay est activé en même temps que [l'hydratation incrémentale](guide/incremental-hydration). Si vous désactivez l'hydratation incrémentale avec `withNoIncrementalHydration()`, vous pouvez toujours activer l'event replay à l'aide de la fonction `withEventReplay()` :

```typescript
import {
  provideClientHydration,
  withEventReplay,
  withNoIncrementalHydration,
  bootstrapApplication,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration(), withEventReplay())],
});
```

### Fonctionnement de l'event replay {#how-event-replay-works}

Event Replay est une fonctionnalité qui améliore l'expérience utilisateur en capturant les événements utilisateur déclenchés avant la fin du processus d'hydratation. Ces événements sont ensuite rejoués, ce qui garantit qu'aucune de ces interactions n'est perdue.

L'Event Replay se décompose en trois phases principales :

- **Capture des interactions utilisateur**<br>
  Avant l'**hydratation**, l'Event Replay capture et stocke toutes les interactions que l'utilisateur peut effectuer, comme les clics et d'autres événements natifs du navigateur.

- **Stockage des événements**<br>
  L'**Event Contract** conserve en mémoire toutes les interactions enregistrées à l'étape précédente, ce qui garantit qu'elles ne sont pas perdues et pourront être rejouées plus tard.

- **Relance des événements**<br>
  Une fois l'**hydratation** terminée, Angular invoque à nouveau les événements capturés.

L'event replay prend en charge les _événements natifs du navigateur_, par exemple `click`, `mouseover` et `focusin`. Pour en savoir plus sur JSAction, la library sur laquelle repose l'event replay, consultez [son readme](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme).

Cette fonctionnalité garantit une expérience utilisateur cohérente, en évitant que les actions effectuées par l'utilisateur avant l'hydratation soient ignorées.

## Contraintes {#constraints}

L'hydratation impose à votre application quelques contraintes qui n'existent pas sans hydratation. Votre application doit générer la même structure DOM à la fois sur le serveur et sur le client. Le processus d'hydratation s'attend à ce que l'arbre DOM ait la même structure aux deux endroits. Cela inclut aussi les espaces blancs et les nœuds de commentaire qu'Angular produit pendant le rendu sur le serveur. Ces espaces blancs et ces nœuds doivent être présents dans le HTML généré par le processus de rendu côté serveur.

IMPORTANT: Le HTML produit par l'opération de rendu côté serveur **ne doit pas** être modifié entre le serveur et le client.

En cas d'incohérence entre les structures de l'arbre DOM du serveur et du client, le processus d'hydratation rencontrera des problèmes en essayant de faire correspondre ce qui était attendu avec ce qui est réellement présent dans le DOM. Les composants qui manipulent directement le DOM à l'aide des API DOM natives en sont la cause la plus fréquente.

### Manipulation directe du DOM {#direct-dom-manipulation}

Si vous avez des composants qui manipulent le DOM à l'aide des API DOM natives ou qui utilisent `innerHTML` ou `outerHTML`, le processus d'hydratation rencontrera des erreurs. Les cas précis où la manipulation du DOM pose problème sont, par exemple, l'accès au `document`, la recherche d'éléments spécifiques et l'injection de nœuds supplémentaires avec `appendChild`. Détacher des nœuds DOM et les déplacer à d'autres endroits provoque également des erreurs.

En effet, Angular n'a pas connaissance de ces modifications du DOM et ne peut pas les résoudre pendant le processus d'hydratation. Angular s'attend à une certaine structure, mais en rencontre une différente au moment d'hydrater. Cette incohérence entraîne un échec de l'hydratation et lève une erreur d'incohérence DOM ([voir ci-dessous](#errors)).

Le mieux est de refactoriser votre composant pour éviter ce type de manipulation du DOM. Essayez, si possible, d'utiliser les API Angular pour effectuer ce travail. Si vous ne pouvez pas refactoriser ce comportement, utilisez l'attribut `ngSkipHydration` ([décrit ci-dessous](#how-to-skip-hydration-for-particular-components)) jusqu'à ce que vous puissiez passer à une solution compatible avec l'hydratation.

### Structure HTML valide {#valid-html-structure}

Dans certains cas, un template de composant dont la structure HTML n'est pas valide peut provoquer une erreur d'incohérence DOM pendant l'hydratation.

Voici, à titre d'exemple, quelques-uns des cas les plus courants de ce problème.

- `<table>` sans `<tbody>`
- `<div>` à l'intérieur d'un `<p>`
- `<a>` à l'intérieur d'un autre `<a>`

Si vous n'êtes pas sûr que votre HTML soit valide, vous pouvez utiliser un [validateur de syntaxe](https://validator.w3.org/) pour le vérifier.

NOTE: Bien que le standard HTML n'exige pas l'élément `<tbody>` dans les tableaux, les navigateurs modernes créent automatiquement un élément `<tbody>` dans les tableaux qui n'en déclarent pas. En raison de cette incohérence, déclarez toujours explicitement un élément `<tbody>` dans vos tableaux pour éviter les erreurs d'hydratation.

### Configuration de la conservation des espaces blancs {#preserve-whitespaces-configuration}

Lorsque vous utilisez l'hydratation, nous recommandons de conserver le réglage par défaut `false` pour `preserveWhitespaces`. Si ce réglage ne figure pas dans votre tsconfig, la valeur sera `false` et aucune modification n'est nécessaire. Si vous choisissez d'activer la conservation des espaces blancs en ajoutant `preserveWhitespaces: true` à votre tsconfig, vous risquez de rencontrer des problèmes d'hydratation. Il ne s'agit pas encore d'une configuration entièrement prise en charge.

HELPFUL: Assurez-vous que ce réglage est défini de manière **cohérente** dans `tsconfig.server.json` pour votre serveur et dans `tsconfig.app.json` pour vos builds navigateur. Une valeur différente entre les deux casse l'hydratation.

Si vous choisissez de définir ce réglage dans votre tsconfig, nous recommandons de le définir uniquement dans `tsconfig.app.json`, dont `tsconfig.server.json` hérite par défaut.

### Les implémentations personnalisées ou noop de Zone.js ne sont pas encore prises en charge {#custom-or-noop-zonejs-are-not-yet-supported}

L'hydratation s'appuie sur un signal de Zone.js indiquant que l'application devient stable, afin qu'Angular puisse démarrer le processus de sérialisation sur le serveur ou le nettoyage post-hydratation sur le client pour supprimer les nœuds DOM restés non réclamés.

Fournir une implémentation personnalisée ou « noop » de Zone.js peut modifier le moment où survient l'événement « stable », et donc déclencher la sérialisation ou le nettoyage trop tôt ou trop tard. Il ne s'agit pas encore d'une configuration entièrement prise en charge, et vous devrez peut-être ajuster le moment de l'événement `onStable` dans l'implémentation personnalisée de Zone.js.

## Erreurs {#errors}

Vous pouvez rencontrer plusieurs erreurs liées à l'hydratation, depuis des incohérences de nœuds jusqu'aux cas où `ngSkipHydration` a été utilisé sur un nœud host invalide. Le cas d'erreur le plus courant est dû à une manipulation directe du DOM via des API natives, qui empêche l'hydratation de trouver ou de faire correspondre, côté client, la structure d'arbre DOM attendue qui a été rendue par le serveur. L'autre cas où vous pouvez rencontrer ce type d'erreur a été mentionné plus haut, dans la section [Structure HTML valide](#valid-html-structure). Assurez-vous donc que le HTML de vos templates utilise une structure valide, et vous éviterez ce cas d'erreur.

Pour une référence complète des erreurs liées à l'hydratation, consultez le [guide de référence des erreurs](/errors).

## Comment ignorer l'hydratation pour certains composants {#how-to-skip-hydration-for-particular-components}

Certains composants peuvent ne pas fonctionner correctement avec l'hydratation activée, en raison de l'un des problèmes mentionnés précédemment, comme la [manipulation directe du DOM](#direct-dom-manipulation). Pour contourner le problème, vous pouvez ajouter l'attribut `ngSkipHydration` à la balise d'un composant afin d'ignorer l'hydratation de l'ensemble du composant.

```html
<app-example ngSkipHydration />
```

Vous pouvez aussi définir `ngSkipHydration` sous forme de host binding.

```typescript
@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}
```

L'attribut `ngSkipHydration` force Angular à ignorer l'hydratation de l'ensemble du composant et de ses enfants. Utiliser cet attribut signifie que le composant se comporte comme si l'hydratation n'était pas activée : il se détruit et effectue à nouveau son rendu.

HELPFUL: Cela corrige les problèmes de rendu, mais vous perdez les avantages de l'hydratation pour ce composant (et ses enfants). Vous devrez adapter l'implémentation de votre composant pour éviter les patterns qui cassent l'hydratation (par exemple la manipulation directe du DOM) afin de pouvoir supprimer l'annotation qui ignore l'hydratation.

L'attribut `ngSkipHydration` ne peut être utilisé que sur les nœuds host de composants. Angular lève une erreur si cet attribut est ajouté à d'autres nœuds.

Gardez à l'esprit qu'ajouter l'attribut `ngSkipHydration` au composant racine de votre application désactiverait de fait l'hydratation pour toute votre application. Utilisez cet attribut avec prudence et discernement. Il est conçu comme un contournement de dernier recours. Les composants qui cassent l'hydratation doivent être considérés comme des bugs à corriger.

## Moment de l'hydratation et stabilité de l'application {#hydration-timing-and-application-stability}

La stabilité de l'application est un élément important du processus d'hydratation. L'hydratation et tous les processus post-hydratation n'ont lieu qu'une fois que l'application a signalé sa stabilité. La stabilité peut être retardée de plusieurs façons, par exemple par la définition de timeouts et d'intervalles, des promises non résolues ou des microtâches en attente. Dans ces cas, vous pouvez rencontrer l'erreur [Application remains unstable](errors/NG0506), qui indique que votre application n'a pas atteint l'état stable au bout de 10 secondes. Si vous constatez que votre application ne s'hydrate pas tout de suite, examinez ce qui affecte la stabilité de l'application et refactorisez votre code pour éviter ces délais.

### Déboguer la stabilité de l'application {#debugging-application-stability}

L'utilitaire `provideStabilityDebugging` aide à identifier pourquoi votre application ne parvient pas à se stabiliser. Cet utilitaire est fourni par défaut en mode développement lorsque vous utilisez `provideClientHydration`. Vous pouvez aussi l'ajouter manuellement aux providers de l'application, par exemple pour l'utiliser dans des bundles de production ou avec le SSR sans hydratation. La fonctionnalité affiche des informations dans la console si l'application met plus de temps que prévu à se stabiliser.

```typescript
import {provideStabilityDebugging} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import 'zone.js/plugins/task-tracking'; // Use if you have Zone.js with `provideZoneChangeDetection`

bootstrapApplication(App, {
  providers: [provideStabilityDebugging()],
});
```

Une fois activé, l'utilitaire affiche dans la console les tâches en attente (`PendingTasks`). Si votre application utilise Zone.js, vous pouvez aussi importer `zone.js/plugins/task-tracking` pour voir quelles macrotâches empêchent la zone Angular de se stabiliser. Ce plugin fournit la stack trace de la création de la macrotâche, ce qui vous aide efficacement à identifier l'origine du délai.

IMPORTANT: Angular ne retire pas le plugin de suivi des tâches de zone.js ni cet utilitaire des bundles de production. Utilisez-les uniquement pour déboguer temporairement des problèmes de stabilité pendant le développement, y compris pour les builds de production optimisés.

## I18N {#i18n}

HELPFUL: Par défaut, Angular ignore l'hydratation des composants qui utilisent des blocs i18n, ce qui revient à refaire entièrement le rendu de ces composants.

Pour activer l'hydratation des blocs i18n, vous pouvez ajouter [`withI18nSupport`](/api/platform-browser/withI18nSupport) à votre appel à `provideClientHydration`.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration(withI18nSupport())]
});
```

## Un rendu cohérent côté serveur et côté client {#consistent-rendering-across-server-side-and-client-side}

Évitez d'introduire des blocs `@if` et d'autres conditions qui affichent un contenu différent lors du rendu côté serveur et lors du rendu côté client, par exemple un bloc `@if` utilisant la fonction `isPlatformBrowser` d'Angular. Ces différences de rendu provoquent des décalages de mise en page, ce qui nuit à l'expérience de l'utilisateur final et aux Core Web Vitals.

## Libraries tierces qui manipulent le DOM {#third-party-libraries-with-dom-manipulation}

Un certain nombre de libraries tierces dépendent de la manipulation du DOM pour effectuer leur rendu. Les graphiques D3 en sont un exemple typique. Ces libraries fonctionnaient sans hydratation, mais elles peuvent provoquer des erreurs d'incohérence DOM lorsque l'hydratation est activée. Pour l'instant, si vous rencontrez des erreurs d'incohérence DOM avec l'une de ces libraries, vous pouvez ajouter l'attribut `ngSkipHydration` au composant qui effectue son rendu à l'aide de cette library.

## Scripts tiers qui manipulent le DOM {#third-party-scripts-with-dom-manipulation}

De nombreux scripts tiers, comme les traceurs publicitaires et les outils d'analytics, modifient le DOM avant que l'hydratation puisse avoir lieu. Ces scripts peuvent provoquer des erreurs d'hydratation, car la page ne correspond plus à la structure attendue par Angular. Dans la mesure du possible, différez plutôt ce type de script jusqu'après l'hydratation. Envisagez d'utiliser [`AfterNextRender`](api/core/afterNextRender) pour retarder le script jusqu'à ce que les processus post-hydratation aient eu lieu.

## Hydratation incrémentale {#incremental-hydration}

L'hydratation incrémentale est une forme avancée d'hydratation qui permet un contrôle plus fin du moment où l'hydratation a lieu. Consultez le [guide de l'hydratation incrémentale](guide/incremental-hydration) pour plus d'informations.
# Hydratation incrémentale

L'**hydratation incrémentale** est un type avancé d'[hydratation](guide/hydration) qui peut laisser des sections de votre application déshydratées et déclencher _progressivement_ l'hydratation de ces sections lorsqu'elles deviennent nécessaires.

## Pourquoi utiliser l'hydratation incrémentale ? {#why-use-incremental-hydration}

L'hydratation incrémentale est une amélioration des performances qui s'appuie sur l'hydratation complète de l'application. Elle peut produire des bundles initiaux plus petits tout en offrant à l'utilisateur final une expérience comparable à celle d'une hydratation complète de l'application. Des bundles plus petits améliorent les temps de chargement initiaux, en réduisant le [First Input Delay (FID)](https://web.dev/fid) et le [Cumulative Layout Shift (CLS)](https://web.dev/cls).

L'hydratation incrémentale vous permet aussi d'utiliser des vues différables (`@defer`) pour du contenu qui ne pouvait pas être différé auparavant. En particulier, vous pouvez désormais utiliser des vues différables pour du contenu situé au-dessus de la ligne de flottaison. Avant l'hydratation incrémentale, placer un bloc `@defer` au-dessus de la ligne de flottaison entraînait le rendu du contenu du placeholder, ensuite remplacé par le contenu du template principal du bloc `@defer`. Cela provoquait un décalage de mise en page. Avec l'hydratation incrémentale, le template principal du bloc `@defer` est rendu sans décalage de mise en page lors de l'hydratation.

## Comment activer l'hydratation incrémentale dans Angular ? {#how-do-you-enable-incremental-hydration-in-angular}

Vous pouvez activer l'hydratation incrémentale pour les applications qui utilisent déjà le rendu côté serveur (SSR) avec hydratation. Suivez d'abord le [guide SSR d'Angular](guide/ssr) pour activer le rendu côté serveur, puis le [guide de l'hydratation d'Angular](guide/hydration) pour activer l'hydratation.

L'hydratation incrémentale est activée par défaut lorsque vous utilisez `provideClientHydration()`.

```ts
import {bootstrapApplication, provideClientHydration} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration()],
});
```

NOTE: L'hydratation incrémentale dépend de l'[event replay](guide/hydration#capturing-and-replaying-events) et l'active automatiquement. Si `withEventReplay()` figure déjà dans votre liste, vous pouvez le retirer sans risque.

Pour désactiver l'hydratation incrémentale, utilisez `withNoIncrementalHydration()` :

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoIncrementalHydration,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration())],
});
```

## Comment fonctionne l'hydratation incrémentale ? {#how-does-incremental-hydration-work}

L'hydratation incrémentale s'appuie sur l'[hydratation](guide/hydration) complète de l'application, les [vues différables](/guide/templates/defer) et l'[event replay](guide/hydration#capturing-and-replaying-events). Avec l'hydratation incrémentale, vous pouvez ajouter aux blocs `@defer` des déclencheurs supplémentaires qui définissent des frontières d'hydratation incrémentale. Ajouter un déclencheur `hydrate` à un bloc defer indique à Angular qu'il doit charger les dépendances de ce bloc defer pendant le rendu côté serveur et rendre le template principal plutôt que le `@placeholder`. Lors du rendu côté client, les dépendances restent différées, et le contenu du bloc defer reste déshydraté jusqu'à ce que son déclencheur `hydrate` se déclenche. Ce déclencheur indique au bloc defer de récupérer ses dépendances et d'hydrater le contenu. Tous les événements du navigateur déclenchés par l'utilisateur avant l'hydratation, plus précisément ceux qui correspondent aux listeners enregistrés dans votre composant, sont mis en file d'attente et rejoués une fois le processus d'hydratation terminé.

## Contrôler l'hydratation du contenu avec des déclencheurs {#controlling-hydration-of-content-with-triggers}

Vous pouvez spécifier des **déclencheurs d'hydratation** qui contrôlent le moment où Angular charge et hydrate le contenu différé. Ce sont des déclencheurs supplémentaires, utilisables en complément des déclencheurs `@defer` habituels.

Chaque bloc `@defer` peut avoir plusieurs déclencheurs d'hydratation, séparés par un point-virgule (`;`). Angular déclenche l'hydratation dès que _l'un_ des déclencheurs se déclenche.

Il existe trois types de déclencheurs d'hydratation : `hydrate on`, `hydrate when` et `hydrate never`.

### `hydrate on`

`hydrate on` spécifie une condition qui détermine quand l'hydratation du bloc `@defer` est déclenchée.

Les déclencheurs disponibles sont les suivants :

| Déclencheur                                         | Description                                                            |
| --------------------------------------------------- | ---------------------------------------------------------------------- |
| [`hydrate on idle`](#hydrate-on-idle)               | Se déclenche lorsque le navigateur est inactif. Accepte un délai d'expiration optionnel. |
| [`hydrate on viewport`](#hydrate-on-viewport)       | Se déclenche lorsque le contenu spécifié entre dans le viewport        |
| [`hydrate on interaction`](#hydrate-on-interaction) | Se déclenche lorsque l'utilisateur interagit avec l'élément spécifié  |
| [`hydrate on hover`](#hydrate-on-hover)             | Se déclenche lorsque la souris survole la zone spécifiée               |
| [`hydrate on immediate`](#hydrate-on-immediate)     | Se déclenche immédiatement après la fin du rendu du contenu non différé |
| [`hydrate on timer`](#hydrate-on-timer)             | Se déclenche après une durée donnée                                    |

#### `hydrate on idle`

Le déclencheur `hydrate on idle` charge les dépendances de la vue différable et hydrate le contenu dès que le navigateur a atteint un état d'inactivité, en s'appuyant sur `requestIdleCallback`.

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

@defer (hydrate on idle(500)) {
  <large-cmp />
}
```

#### `hydrate on viewport`

Le déclencheur `hydrate on viewport` charge les dépendances de la vue différable et hydrate la partie correspondante de l'application lorsque le contenu spécifié entre dans le viewport, à l'aide de l'
[API Intersection Observer](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`

Le déclencheur `hydrate on interaction` charge les dépendances de la vue différable et hydrate le contenu lorsque l'utilisateur interagit avec l'élément spécifié via des
événements `click` ou `keydown`.

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

#### `hydrate on hover`

Le déclencheur `hydrate on hover` charge les dépendances de la vue différable et hydrate le contenu lorsque la souris a survolé la zone de déclenchement, via les
événements `mouseover` et `focusin`.

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

#### `hydrate on immediate`

Le déclencheur `hydrate on immediate` charge les dépendances de la vue différable et hydrate immédiatement le contenu. Cela signifie que le bloc différé se charge dès
que tout le reste du contenu non différé a fini son rendu.

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

#### `hydrate on timer`

Le déclencheur `hydrate on timer` charge les dépendances de la vue différable et hydrate le contenu après une durée spécifiée.

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

Le paramètre de durée doit être spécifié en millisecondes (`ms`) ou en secondes (`s`).

### `hydrate when`

Le déclencheur `hydrate when` accepte une expression conditionnelle personnalisée, charge les dépendances de la vue différable et hydrate le contenu lorsque la
condition devient truthy.

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

NOTE: Les conditions `hydrate when` ne se déclenchent que lorsqu'elles portent sur le bloc `@defer` déshydraté le plus haut dans l'arbre. La condition fournie au déclencheur est
définie dans le composant parent, qui doit exister avant de pouvoir être déclenché. Si le bloc parent est déshydraté, Angular ne peut pas encore
résoudre cette expression.

### `hydrate never`

`hydrate never` permet aux utilisateurs d'indiquer que le contenu du bloc defer doit rester déshydraté indéfiniment, devenant de fait du contenu
statique. Notez que cela ne s'applique qu'au rendu initial. Lors d'un rendu côté client ultérieur, un bloc `@defer` avec `hydrate never`
récupérera quand même ses dépendances, car l'hydratation ne s'applique qu'au chargement initial du contenu rendu côté serveur. Dans l'exemple ci-dessous, les rendus
côté client ultérieurs chargeront les dépendances du bloc `@defer` à l'entrée dans le viewport.

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

NOTE: Utiliser `hydrate never` empêche l'hydratation de tout le sous-arbre imbriqué d'un bloc `@defer` donné. Aucun autre déclencheur `hydrate` ne se déclenche pour le contenu imbriqué sous ce bloc.

## Déclencheurs d'hydratation et déclencheurs habituels {#hydrate-triggers-alongside-regular-triggers}

Les déclencheurs d'hydratation sont des déclencheurs supplémentaires, utilisés en complément des déclencheurs habituels d'un bloc `@defer`. L'hydratation est une optimisation du chargement initial, ce qui signifie que les déclencheurs d'hydratation ne s'appliquent qu'à ce chargement initial. Tout rendu côté client ultérieur utilise toujours le déclencheur habituel.

```html
@defer (on idle; hydrate on interaction) {
  <example-cmp />
} @placeholder {
  <div>Example Placeholder</div>
}
```

Dans cet exemple, lors du chargement initial, c'est `hydrate on interaction` qui s'applique. L'hydratation est déclenchée lors d'une interaction avec le composant `<example-cmp />`. Lors de tout chargement de page ultérieur rendu côté client, par exemple lorsqu'un utilisateur clique sur un routerLink qui charge une page contenant ce composant, c'est `on idle` qui s'applique.

## Comment l'hydratation incrémentale fonctionne-t-elle avec des blocs `@defer` imbriqués ? {#how-does-incremental-hydration-work-with-nested-defer-blocks}

Le système de composants et de dépendances d'Angular est hiérarchique, ce qui signifie que l'hydratation d'un composant nécessite que tous ses parents soient aussi hydratés. Ainsi, si l'hydratation est déclenchée pour un bloc `@defer` enfant au sein d'un ensemble de blocs `@defer` déshydratés imbriqués, l'hydratation est déclenchée depuis le bloc `@defer` déshydraté le plus haut jusqu'à l'enfant déclenché, dans cet ordre.

```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>
}
```

Dans l'exemple ci-dessus, survoler le bloc `@defer` imbriqué déclenche l'hydratation. Le bloc `@defer` parent contenant `<parent-block-cmp />` est hydraté en premier, puis le bloc `@defer` enfant contenant `<child-block-cmp />` est hydraté ensuite.

## Contraintes {#constraints}

L'hydratation incrémentale a les mêmes contraintes que l'hydratation complète de l'application, notamment les limites sur la manipulation directe du DOM et l'exigence d'une structure HTML valide. Consultez la section [Contraintes du guide de l'hydratation](guide/hydration#constraints) pour plus de détails.

## Faut-il toujours spécifier des blocs `@placeholder` ? {#do-i-still-need-to-specify-placeholder-blocks}

Oui. Le contenu du bloc `@placeholder` n'est pas utilisé pour l'hydratation incrémentale, mais un `@placeholder` reste nécessaire pour les rendus côté client ultérieurs. Si votre contenu ne se trouvait pas sur la route faisant partie du chargement initial, toute navigation vers la route qui contient votre bloc `@defer` effectue le rendu comme un bloc `@defer` classique. Le `@placeholder` est donc rendu dans ces cas de rendu côté client.
# Tests unitaires

Tester votre application Angular vous aide à vérifier qu'elle fonctionne comme prévu. Les tests unitaires sont essentiels pour détecter les bugs tôt, garantir la qualité du code et faciliter un refactoring sans risque.

NOTE: Ce guide couvre la configuration de test par défaut des nouveaux projets Angular CLI, qui utilise Vitest. Si vous migrez un projet existant depuis Karma, consultez le [guide de migration de Karma vers Vitest](guide/testing/migrating-to-vitest). Karma reste pris en charge ; pour plus d'informations, consultez le [guide de test avec Karma](guide/testing/karma).

## Configuration pour les tests {#set-up-for-testing}

L'Angular CLI télécharge et installe tout ce dont vous avez besoin pour tester une application Angular avec le [framework de test Vitest](https://vitest.dev). Les nouveaux projets incluent `vitest` et `jsdom` par défaut.

Vitest exécute vos tests unitaires dans un environnement Node.js. Pour simuler le DOM du navigateur, Vitest utilise une library appelée `jsdom`. L'exécution des tests est ainsi plus rapide, car elle évite le coût du lancement d'un navigateur. Vous pouvez remplacer `jsdom` par une alternative comme `happy-dom` en l'installant et en désinstallant `jsdom`. Actuellement, `jsdom` et `happy-dom` sont les libraries d'émulation du DOM prises en charge.

Le projet que vous créez avec la CLI est immédiatement prêt à être testé. Exécutez la commande [`ng test`](cli/test) :

```shell
ng test
```

La commande `ng test` compile l'application en _mode watch_ et lance le [test runner Vitest](https://vitest.dev).

La sortie de la console ressemble à ceci :

```shell
✓ src/app/app.spec.ts (2)
   ✓ App should create the app
   ✓ App should render title
 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  18:18:01
   Duration  2.46s (transform 615ms, setup 2ms, collect 2.21s, tests 5ms)
```

La commande `ng test` surveille aussi les modifications de vos fichiers. Si vous modifiez un fichier et l'enregistrez, les tests s'exécutent à nouveau.

## Configuration {#configuration}

L'Angular CLI gère pour vous l'essentiel de la configuration de Vitest. Vous pouvez personnaliser le comportement des tests en modifiant les options de la cible `test` dans votre fichier `angular.json`.

### Options d'angular.json {#angularjson-options}

- `include` : patterns glob des fichiers à inclure dans les tests. Par défaut : `['**/*.spec.ts', '**/*.test.ts']`.
- `exclude` : patterns glob des fichiers à exclure des tests.
- `setupFiles` : liste de chemins vers des fichiers de configuration globale (par ex. des polyfills ou des mocks globaux) exécutés avant vos tests.
- `providersFile` : chemin vers un fichier qui exporte par défaut un tableau de providers Angular pour l'environnement de test. C'est utile pour configurer des providers de test globaux, injectés dans vos tests.
- `coverage` : booléen qui active ou désactive le rapport de couverture de code. Par défaut : `false`.
- `browsers` : tableau de noms de navigateurs pour exécuter les tests dans un vrai navigateur (par ex. `["chromium"]`). Nécessite l'installation d'un provider de navigateur. Consultez la section [Exécuter les tests dans un navigateur](#running-tests-in-a-browser) pour plus de détails.

### Configuration et providers de test globaux {#global-test-setup-and-providers}

Les options `setupFiles` et `providersFile` sont particulièrement utiles pour gérer la configuration de test globale.

Par exemple, vous pouvez créer un fichier `src/test-providers.ts` pour fournir `provideHttpClientTesting` à tous vos tests :

```typescript
{header: "src/test-providers.ts"}
import {EnvironmentProviders, Provider} from '@angular/core';
import {provideHttpClientTesting} from '@angular/common/http/testing';

const testProviders: (Provider | EnvironmentProviders)[] = [provideHttpClientTesting()];

export default testProviders;
```

Vous référencez ensuite ce fichier dans votre `angular.json` :

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "providersFile": "src/test-providers.ts"
          }
        }
      }
    }
  }
}
```

HELPFUL: Quand vous créez de nouveaux fichiers TypeScript pour la configuration des tests ou les providers, comme `src/test-providers.ts`, assurez-vous qu'ils sont inclus dans le fichier de configuration TypeScript des tests de votre projet (généralement `tsconfig.spec.json`). Le compilateur TypeScript peut ainsi traiter correctement ces fichiers pendant les tests.

### Configuration avancée de Vitest {#advanced-vitest-configuration}

Pour les cas d'usage avancés, vous pouvez fournir un fichier de configuration Vitest personnalisé avec l'option `runnerConfig` dans `angular.json`.

IMPORTANT: Si une configuration personnalisée donne accès à des options avancées, l'équipe Angular n'assure aucun support pour le contenu du fichier de configuration ni pour les plugins tiers. La CLI écrase aussi certaines propriétés (`test.projects`, `test.include`) pour garantir une intégration correcte.

Vous pouvez créer un fichier de configuration Vitest (par ex. `vitest-base.config.ts`) et le référencer dans votre `angular.json` :

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "runnerConfig": "vitest-base.config.ts"
          }
        }
      }
    }
  }
}
```

Vous pouvez aussi générer un fichier de configuration de base avec la CLI :

```shell
ng generate config vitest
```

Cela crée un fichier `vitest-base.config.ts` que vous pouvez personnaliser.

HELPFUL: Pour en savoir plus sur la configuration de Vitest, consultez la [documentation officielle de Vitest](https://vitest.dev/config/).

## Couverture de code {#code-coverage}

Vous pouvez générer un rapport de couverture de code en ajoutant l'option `--coverage` à la commande `ng test`. Le rapport est généré dans le répertoire `coverage/`.

Pour des informations plus détaillées, consultez le [guide de la couverture de code](guide/testing/code-coverage).

## Exécuter les tests dans un navigateur {#running-tests-in-a-browser}

Si l'environnement Node.js par défaut est plus rapide pour la plupart des tests unitaires, vous pouvez aussi exécuter vos tests dans un vrai navigateur. C'est utile pour les tests qui reposent sur des API propres au navigateur (comme le rendu) ou pour le débogage.

Pour exécuter les tests dans un navigateur, vous devez d'abord installer un provider de navigateur. Pour en savoir plus sur le mode navigateur de Vitest, consultez la [documentation officielle](https://vitest.dev/guide/browser).

Une fois le provider installé, vous pouvez exécuter vos tests dans le navigateur en configurant l'option `browsers` dans `angular.json` ou en utilisant l'option CLI `--browsers`. Par défaut, les tests s'exécutent dans un navigateur avec interface (headed). Si la variable d'environnement `CI` est définie, le mode headless est utilisé à la place. Pour contrôler explicitement le mode headless, vous pouvez ajouter le suffixe `Headless` au nom du navigateur (par ex. `chromiumHeadless`).

```bash
# Example for Playwright (headed)
ng test --browsers=chromium

# Example for Playwright (headless)
ng test --browsers=chromiumHeadless

# Example for WebdriverIO (headed)
ng test --browsers=chrome

# Example for WebdriverIO (headless)
ng test --browsers=chromeHeadless
```

Choisissez l'un des providers de navigateur suivants selon vos besoins :

### Playwright {#playwright}

[Playwright](https://playwright.dev/) est une library d'automatisation de navigateur qui prend en charge Chromium, Firefox et WebKit.

```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
```
### WebdriverIO {#webdriverio}

[WebdriverIO](https://webdriver.io/) est un framework de test d'automatisation pour navigateurs et mobiles qui prend en charge Chrome, Firefox, Safari et Edge.

```shell
// npm
npm install --save-dev @vitest/browser-webdriverio webdriverio
```
```shell
// yarn
yarn add --dev @vitest/browser-webdriverio webdriverio
```
```shell
// pnpm
pnpm add -D @vitest/browser-webdriverio webdriverio
```
```shell
// bun
bun add --dev @vitest/browser-webdriverio webdriverio
```
### Preview {#preview}

Le provider `@vitest/browser-preview` est conçu pour les environnements WebContainer comme StackBlitz et n'est pas destiné à un usage en CI/CD.

```shell
// npm
npm install --save-dev @vitest/browser-preview
```
```shell
// yarn
yarn add --dev @vitest/browser-preview
```
```shell
// pnpm
pnpm add -D @vitest/browser-preview
```
```shell
// bun
bun add --dev @vitest/browser-preview
```
HELPFUL: Pour une configuration plus avancée propre au navigateur, consultez la section [Configuration avancée de Vitest](#advanced-vitest-configuration).

## Autres frameworks de test {#other-test-frameworks}

Vous pouvez aussi écrire les tests unitaires d'une application Angular avec d'autres libraries de test et d'autres test runners. Chaque library et chaque runner a ses propres procédures d'installation, sa configuration et sa syntaxe.

## Tester en intégration continue {#testing-in-continuous-integration}

Une suite de tests robuste est un élément clé d'un pipeline d'intégration continue (CI). Les serveurs de CI vous permettent d'automatiser l'exécution de vos tests à chaque commit et à chaque pull request.

Pour tester votre application Angular sur un serveur de CI, exécutez la commande de test standard :

```shell
ng test
```

La plupart des serveurs de CI définissent une variable d'environnement `CI=true`, que `ng test` détecte. Vos tests sont alors automatiquement configurés pour s'exécuter en mode non interactif, en une seule passe.

Si votre serveur de CI ne définit pas cette variable, ou si vous devez forcer manuellement l'exécution en une seule passe, vous pouvez utiliser les options `--no-watch` et `--no-progress` :

```shell
ng test --no-watch --no-progress
```

## Plus d'informations sur les tests {#more-information-on-testing}

Une fois votre application configurée pour les tests, les guides de test suivants pourraient vous être utiles.

|                                                                    | Détails                                                                           |
| :----------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| [Couverture de code](guide/testing/code-coverage)                  | La part de votre application couverte par vos tests et comment exiger un seuil minimal. |
| [Tester les services](guide/testing/services)                      | Comment tester les services utilisés par votre application.                       |
| [Bases du test de composants](guide/testing/components-basics)     | Les bases du test des composants Angular.                                         |
| [Scénarios de test de composants](guide/testing/components-scenarios) | Différents scénarios et cas d'usage du test de composants.                     |
| [Tester les directives d'attribute](guide/testing/attribute-directives) | Comment tester vos directives d'attribute.                                   |
| [Tester les pipes](guide/testing/pipes)                            | Comment tester les pipes.                                                         |
| [Déboguer les tests](guide/testing/debugging)                      | Les bugs de test courants.                                                        |
| [API utilitaires de test](guide/testing/utility-apis)              | Les fonctionnalités de test d'Angular.                                            |
# Couverture de code

Les rapports de couverture de code vous montrent les parties de votre base de code qui ne sont peut-être pas correctement testées par vos tests unitaires.

## Prérequis {#prerequisites}

Pour générer des rapports de couverture de code avec Vitest, vous devez installer le package `@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
```
## Générer un rapport {#generating-a-report}

Pour générer un rapport de couverture, ajoutez l'option `--coverage` à la commande `ng test` :

```shell
ng test --coverage
```

Une fois les tests exécutés, la commande crée un nouveau répertoire `coverage/` dans le projet. Ouvrez le fichier `index.html` pour afficher un rapport contenant votre code source et ses valeurs de couverture de code.

Si vous voulez créer des rapports de couverture de code à chaque exécution des tests, vous pouvez définir l'option `coverage` à `true` dans votre fichier `angular.json` :

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true
          }
        }
      }
    }
  }
}
```

## Imposer des seuils de couverture de code {#enforcing-code-coverage-thresholds}

Les pourcentages de couverture de code vous permettent d'estimer quelle part de votre code est testée. Si votre équipe fixe un minimum à couvrir par des tests unitaires, vous pouvez imposer ce minimum dans votre configuration.

Par exemple, supposons que vous vouliez que la base de code ait une couverture de code d'au moins 80 %. Pour cela, ajoutez l'option `coverageThresholds` à votre fichier `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
            }
          }
        }
      }
    }
  }
}
```

Désormais, si votre couverture descend sous 80 % lorsque vous exécutez vos tests, la commande échoue.

## Configuration avancée {#advanced-configuration}

Vous pouvez configurer plusieurs autres options de couverture dans votre fichier `angular.json` :

- `coverageInclude` : patterns glob des fichiers à inclure dans le rapport de couverture.
- `coverageExclude` : patterns glob des fichiers à exclure du rapport de couverture.
- `coverageReporters` : un tableau de reporters à utiliser (par exemple `html`, `lcov`, `json`).
- `coverageWatermarks` : un objet qui définit les seuils `[low, high]` du reporter HTML, qui peuvent influer sur le code couleur du rapport.

```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]
            }
          }
        }
      }
    }
  }
}
```
# Tester les services

Les services contiennent généralement la logique métier de votre application, sur laquelle s'appuient les composants. Tester les services permet de vérifier que cette logique fonctionne correctement de manière isolée, indépendamment de tout composant ou template.

Ce guide utilise [Vitest](https://vitest.dev/), que les projets Angular CLI incluent par défaut. Pour en savoir plus sur la configuration des tests, consultez le [guide de présentation des tests](guide/testing#set-up-for-testing).

## Tester un service {#testing-a-service}

Prenons un service `Calculator` qui effectue des opérations arithmétiques de base :

```ts
{ header: 'calculator.ts' }
import {Service} from '@angular/core';

@Service()
export class Calculator {
  add(a: number, b: number): number {
    return a + b;
  }

subtract(a: number, b: number): number {
    return a - b;
  }
}
```

Pour tester ce service, configurez un `TestBed`, l'utilitaire de test d'Angular qui crée un environnement de test isolé pour chaque test. Il met en place l'injection de dépendances et vous permet de récupérer des instances de services, en simulant la manière dont Angular assemble les éléments dans une vraie application.

```ts
{ header: 'calculator.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {beforeEach, describe, expect, it} from 'vitest';
import {Calculator} from './calculator';

describe('Calculator', () => {
  let service: Calculator;

beforeEach(() => {
    // Injects the Calculator service which is available to Angular
    // because the service uses `@Service`
    service = TestBed.inject(Calculator);
  });

it('adds two numbers', () => {
    expect(service.add(1, 2)).toBe(3);
  });

it('subtracts two numbers', () => {
    expect(service.subtract(5, 3)).toBe(2);
  });
});
```

Dans l'exemple ci-dessus, le bloc `beforeEach` injecte une nouvelle instance du service avant chaque test. Cela garantit que chaque test s'exécute de manière isolée, sans état hérité des tests précédents.

## Tester des services avec des dépendances {#testing-services-with-dependencies}

La plupart des services dépendent d'autres services pour fonctionner correctement. Par défaut, `TestBed` fournit les vraies implémentations de ces dépendances, ce qui signifie que vos tests exercent les chemins de code réellement utilisés par votre application. Parfois, cependant, une dépendance peut être complexe, lente ou imprévisible. Dans ces cas-là, vous pouvez la remplacer par un substitut contrôlé.

Prenons un service `OrderTotal` qui s'appuie sur un `TaxCalculator` pour calculer le prix final d'une commande :

```ts
{ header: 'tax-calculator.ts' }
import {Service} from '@angular/core';

@Service()
export class TaxCalculator {
  calculate(subtotal: number): number {
    return subtotal * 0.05;
  }
}
```

```ts
{ header: 'order-total.ts' }
import {inject, Service} from '@angular/core';
import {TaxCalculator} from './tax-calculator';

@Service()
export class OrderTotal {
  private taxCalculator = inject(TaxCalculator);

total(subtotal: number): number {
    return subtotal + this.taxCalculator.calculate(subtotal);
  }
}
```

Dans cet exemple, `OrderTotal` utilise `inject()` pour demander `TaxCalculator` au système d'injection de dépendances d'Angular. Par défaut, `TestBed` fournit le vrai `TaxCalculator`, ce qui convient parfaitement à des calculs simples comme celui-ci. En revanche, si `TaxCalculator` impliquait une logique complexe, des requêtes réseau ou des résultats imprévisibles, vous pourriez vouloir le remplacer par un substitut contrôlé.

### Remplacer une dépendance par un stub {#replacing-a-dependency-with-a-stub}

Un stub permet de remplacer une dépendance ou une méthode par une autre qui renvoie des valeurs prévisibles, ce qui peut rendre les résultats des tests plus faciles à vérifier.

Pour tester `OrderTotal` sans dépendre du vrai `TaxCalculator`, vous pouvez fournir un stub dans la configuration du `TestBed`.

```ts
{ header: 'order-total.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {beforeEach, describe, expect, it, vi, type Mocked} from 'vitest';
import {OrderTotal} from './order-total';
import {TaxCalculator} from './tax-calculator';

// Vitest's `Mocked` utility type ensures the stub is type-safe,
// while `vi.fn()` creates a mock function for each method
const taxCalculatorStub: Mocked<TaxCalculator> = {
  calculate: vi.fn(),
};

describe('OrderTotal', () => {
  let service: OrderTotal;

beforeEach(() => {
    // `mockReturnValue` sets a controlled return value for the stub
    taxCalculatorStub.calculate.mockReturnValue(5);

TestBed.configureTestingModule({
      // The `providers` array accepts a provider object where `provide`
      // specifies the dependency to replace and `useValue` defines the stub
      providers: [{provide: TaxCalculator, useValue: taxCalculatorStub}],
    });
    service = TestBed.inject(OrderTotal);
  });

it('adds tax to the subtotal', () => {
    expect(service.total(100)).toBe(105);
  });
});
```

Avec ce stub, chaque fois que `OrderTotal` demande `TaxCalculator`, le `TestBed` sait qu'il doit utiliser `taxCalculatorStub` à la place. Comme le stub renvoie toujours 5, le test vérifie que `OrderTotal` ajoute correctement le montant de la taxe au sous-total, que le taux de taxe change ou non dans `TaxCalculator`.

### Vérifier les interactions avec des spies {#verifying-interactions-with-spies}

Un stub contrôle ce que renvoie une dépendance, mais vous avez parfois aussi besoin de vérifier qu'un service a appelé sa dépendance avec les bons arguments. Vous pouvez le faire avec des spies, qui enregistrent la manière dont une fonction est appelée. Avec Vitest, cette fonctionnalité est intégrée à `vi.fn()` et vous permet de faire des assertions sur les interactions entre services.

```ts
{ header: 'order-total.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {afterEach, beforeEach, describe, expect, it, vi, type Mocked} from 'vitest';
import {OrderTotal} from './order-total';
import {TaxCalculator} from './tax-calculator';

const taxCalculatorStub: Mocked<TaxCalculator> = {
  calculate: vi.fn(),
};

describe('OrderTotal', () => {
  let service: OrderTotal;

beforeEach(() => {
    taxCalculatorStub.calculate.mockReturnValue(5);

TestBed.configureTestingModule({
      providers: [{provide: TaxCalculator, useValue: taxCalculatorStub}],
    });
    service = TestBed.inject(OrderTotal);
  });

afterEach(() => {
    taxCalculatorStub.calculate.mockClear();
  });

it('adds tax to the subtotal', () => {
    expect(service.total(100)).toBe(105);
  });

// Verify the interaction with a spy
  it('calls the tax calculator', () => {
    service.total(100);
    expect(taxCalculatorStub.calculate).toHaveBeenCalledExactlyOnceWith(100);
  });
});
```

Le nouveau test vérifie que `OrderTotal` a appelé `TaxCalculator.calculate` lors du calcul du total. C'est utile pour vérifier que l'interaction entre les services s'est déroulée correctement.

## Tester les services HTTP {#testing-http-services}

De nombreux services utilisent le `HttpClient` d'Angular pour récupérer des données depuis un serveur. Angular fournit des utilitaires de test dédiés à `HttpClient`, qui vous permettent de contrôler les réponses HTTP sans effectuer de vraies requêtes réseau.

Pour en savoir plus sur le test des services qui utilisent `HttpClient`, consultez le [guide sur les tests HTTP](guide/http/testing).
# Bases du test de composants

Un composant, contrairement à toutes les autres parties d'une application Angular, combine un template HTML et une classe TypeScript.
Le composant, c'est véritablement le template et la classe _qui fonctionnent ensemble_.
Pour tester correctement un composant, vous devez vérifier qu'ils fonctionnent ensemble comme prévu.

De tels tests nécessitent de créer le host element du composant dans le DOM du navigateur, comme le fait Angular, et d'examiner l'interaction de la classe du composant avec le DOM telle que la décrit son template.

Le `TestBed` d'Angular facilite ce type de test, comme vous le verrez dans les sections suivantes.
Mais dans de nombreux cas, _tester la classe du composant seule_, sans faire intervenir le DOM, permet de valider une grande partie du comportement du composant de manière simple et plus évidente.

## Tester le DOM d'un composant {#component-dom-testing}

Un composant ne se résume pas à sa classe.
Un composant interagit avec le DOM et avec d'autres composants.
Les classes seules ne peuvent pas vous dire si le composant va s'afficher correctement, réagir aux saisies et aux gestes de l'utilisateur, ou s'intégrer à ses composants parent et enfants.

- `Lightswitch.clicked()` est-il lié à quelque chose qui permette à l'utilisateur de l'invoquer ?
- `Lightswitch.message` est-il affiché ?
- L'utilisateur peut-il réellement sélectionner le héros affiché par le composant `DashboardHero` ?
- Le nom du héros s'affiche-t-il comme prévu $par exemple en majuscules$ ?
- Le message de bienvenue est-il affiché par le template du composant `Welcome` ?

Ces questions ne posent peut-être pas de difficulté pour les composants simples présentés précédemment.
Mais de nombreux composants ont des interactions complexes avec les éléments du DOM décrits dans leurs templates, ce qui fait apparaître et disparaître du HTML à mesure que l'état du composant change.

Pour répondre à ce genre de questions, vous devez créer les éléments du DOM associés aux composants, examiner le DOM pour confirmer que l'état du composant s'affiche correctement aux moments appropriés, et simuler l'interaction de l'utilisateur avec l'écran pour déterminer si ces interactions font que le composant se comporte comme prévu.

Pour écrire ce genre de tests, vous utiliserez des fonctionnalités supplémentaires du `TestBed` ainsi que d'autres utilitaires de test.

### Tests générés par la CLI {#cli-generated-tests}

Par défaut, la CLI crée pour vous un fichier de test initial quand vous lui demandez de générer un nouveau composant.

Par exemple, la commande CLI suivante génère un composant `Banner` dans le dossier `app/banner` $avec un template et des styles inline$ :

```shell
ng generate component banner --inline-template --inline-style
```

Elle génère aussi un fichier de test initial pour le composant, `banner.spec.ts`, qui ressemble à ceci :

```ts
import {ComponentFixture, TestBed} from '@angular/core/testing';
import {Banner} from './banner';

describe('Banner', () => {
  let component: Banner;
  let fixture: ComponentFixture<Banner>;

beforeEach(async () => {
    TestBed.configureTestingModule({});

fixture = TestBed.createComponent(Banner);
    component = fixture.componentInstance;
    await fixture.whenStable();
  });

it('should create', () => {
    expect(component).toBeTruthy();
  });
});
```

### Réduire la configuration {#reduce-the-setup}

Seules les trois dernières lignes de ce fichier testent réellement le composant, et elles se contentent de vérifier qu'Angular peut créer le composant.

Le reste du fichier est du code de configuration standard qui anticipe des tests plus avancés, qui _pourraient_ devenir nécessaires si le composant évolue vers quelque chose de conséquent.

Vous découvrirez ces fonctionnalités de test avancées dans les sections suivantes.
Pour l'instant, vous pouvez réduire radicalement ce fichier de test à une taille plus raisonnable :

```ts
describe('Banner (minimal)', () => {
  it('should create', () => {
    const fixture = TestBed.createComponent(Banner);
    const component = fixture.componentInstance;
    expect(component).toBeDefined();
  });
});
```

Plus tard, vous appellerez `TestBed.configureTestingModule()` avec des imports, des providers et d'autres déclarations selon vos besoins de test.
Des méthodes `override` facultatives permettent d'affiner davantage certains aspects de la configuration.

NOTE: `TestBed.compileComponents` n'est nécessaire que lorsque des blocs `@defer` sont utilisés dans les composants testés.

### `createComponent()` {#createcomponent}

Après avoir configuré `TestBed`, appelez sa méthode `createComponent()`.

```ts
const fixture = TestBed.createComponent(Banner);
```

`TestBed.createComponent()` crée une instance du composant `Banner`, ajoute un élément correspondant au DOM du test runner et renvoie une [`ComponentFixture`](#componentfixture).

IMPORTANT: Ne reconfigurez pas `TestBed` après avoir appelé `createComponent`.

La méthode `createComponent` fige la définition actuelle de `TestBed`, qui n'accepte alors plus aucune configuration.

Vous ne pouvez plus appeler aucune méthode de configuration de `TestBed`, ni `configureTestingModule()`, ni aucune des méthodes `override...`.
Si vous essayez, `TestBed` lève une erreur.

### `ComponentFixture` {#componentfixture}

La [`ComponentFixture`](api/core/testing/ComponentFixture) est un harnais de test qui permet d'interagir avec le composant créé et l'élément correspondant.

Accédez à l'instance du composant via la fixture et confirmez qu'elle existe avec une attente :

```ts
const component = fixture.componentInstance;
expect(component).toBeDefined();
```

### `beforeEach()` {#beforeeach}

Vous ajouterez d'autres tests à mesure que ce composant évoluera.
Plutôt que de dupliquer la configuration de `TestBed` pour chaque test, refactorisez pour extraire la configuration dans un `beforeEach()` et quelques variables auxiliaires :

```ts
describe('Banner (with beforeEach)', () => {
  let component: Banner;
  let fixture: ComponentFixture<Banner>;

beforeEach(async () => {
    fixture = TestBed.createComponent(Banner);
    component = fixture.componentInstance;

await fixture.whenStable(); // necessary to wait for the initial rendering
  });

it('should create', () => {
    expect(component).toBeDefined();
  });
});
```

HELPFUL: En attendant le rendu initial dans le `beforeEach` avec `await fixture.whenStable`, les tests individuels peuvent être synchrones.

Ajoutez maintenant un test qui récupère l'élément du composant depuis `fixture.nativeElement` et recherche le texte attendu.

```ts
it('should contain "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  expect(bannerElement.textContent).toContain('banner works!');
});
```

### Créer une fonction `setup` {#create-a-setup-function}

Comme alternative à `beforeEach`, vous pouvez aussi créer une fonction de configuration que vous appellerez dans chaque test.
Une fonction de configuration a l'avantage d'être personnalisable via des paramètres.

Voici un exemple de ce à quoi pourrait ressembler une fonction de configuration :

```ts
function setup(providers?: Provider[]): ComponentFixture<Banner> {
  TestBed.configureTestingModule({providers});
  return TestBed.createComponent(Banner);
}
```

### `nativeElement` {#nativeelement}

La valeur de `ComponentFixture.nativeElement` est de type `any`.
Vous rencontrerez plus tard `DebugElement.nativeElement`, qui est lui aussi de type `any`.

Angular ne peut pas savoir à la compilation quel type d'élément HTML est le `nativeElement`, ni même s'il s'agit d'un élément HTML.
L'application peut s'exécuter sur une _plateforme autre qu'un navigateur_, comme le serveur ou un environnement Node, où l'élément peut avoir une API réduite, voire ne pas exister du tout.

Les tests de ce guide sont conçus pour s'exécuter dans un navigateur, donc une valeur `nativeElement` sera toujours un `HTMLElement` ou l'une de ses classes dérivées.

Sachant qu'il s'agit d'une forme d'`HTMLElement`, utilisez le `querySelector` HTML standard pour explorer plus profondément l'arbre des éléments.

Voici un autre test qui appelle `HTMLElement.querySelector` pour récupérer l'élément paragraphe et y rechercher le texte de la bannière :

```ts
it('should have <p> with "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  const p = bannerElement.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

### `DebugElement` {#debugelement}

La _fixture_ d'Angular fournit directement l'élément du composant via `fixture.nativeElement`.

```ts
const bannerElement: HTMLElement = fixture.nativeElement;
```

Il s'agit en réalité d'une méthode de commodité, implémentée sous la forme `fixture.debugElement.nativeElement`.

```ts
const bannerDe: DebugElement = fixture.debugElement;
const bannerEl: HTMLElement = bannerDe.nativeElement;
```

Ce chemin détourné vers l'élément a une bonne raison d'être.

Les propriétés du `nativeElement` dépendent de l'environnement d'exécution.
Vous pourriez exécuter ces tests sur une plateforme _autre qu'un navigateur_, qui n'a pas de DOM ou dont l'émulation du DOM ne prend pas en charge l'intégralité de l'API `HTMLElement`.

Angular s'appuie sur l'abstraction `DebugElement` pour fonctionner de manière sûre sur _toutes les plateformes prises en charge_.
Au lieu de créer un arbre d'éléments HTML, Angular crée un arbre de `DebugElement` qui enveloppe les _éléments natifs_ de la plateforme d'exécution.
La propriété `nativeElement` extrait l'élément enveloppé par le `DebugElement` et renvoie l'objet élément propre à la plateforme.

Comme les tests d'exemple de ce guide sont conçus pour s'exécuter uniquement dans un navigateur, un `nativeElement` est toujours, dans ces tests, un `HTMLElement` dont vous pouvez explorer les méthodes et propriétés familières dans un test.

Voici le test précédent, réimplémenté avec `fixture.debugElement.nativeElement` :

```ts
it('should find the <p> with fixture.debugElement.nativeElement', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const bannerEl: HTMLElement = bannerDe.nativeElement;
  const p = bannerEl.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

Le `DebugElement` possède d'autres méthodes et propriétés utiles dans les tests, comme vous le verrez ailleurs dans ce guide.

Vous importez le symbole `DebugElement` depuis la library core d'Angular.

```ts
import {DebugElement} from '@angular/core';
```

### `By.css()` {#bycss}

Bien que les tests de ce guide s'exécutent tous dans le navigateur, certaines applications peuvent s'exécuter sur une plateforme différente, au moins une partie du temps.

Par exemple, le composant peut d'abord être rendu sur le serveur dans le cadre d'une stratégie visant à accélérer le lancement de l'application sur les appareils mal connectés.
Le renderer côté serveur peut ne pas prendre en charge l'intégralité de l'API des éléments HTML.
S'il ne prend pas en charge `querySelector`, le test précédent pourrait échouer.

Le `DebugElement` propose des méthodes de query qui fonctionnent sur toutes les plateformes prises en charge.
Ces méthodes de query prennent une fonction _prédicat_ qui renvoie `true` quand un nœud de l'arbre de `DebugElement` correspond aux critères de sélection.

Vous créez un _prédicat_ à l'aide d'une classe `By` importée depuis une library propre à la plateforme d'exécution.
Voici l'import de `By` pour la plateforme navigateur :

```ts
import {By} from '@angular/platform-browser';
```

L'exemple suivant réimplémente le test précédent avec `DebugElement.query()` et la méthode `By.css` du navigateur.

```ts
it('should find the <p> with fixture.debugElement.query(By.css)', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const paragraphDe = bannerDe.query(By.css('p'));
  const p: HTMLElement = paragraphDe.nativeElement;
  expect(p.textContent).toEqual('banner works!');
});
```

Quelques observations notables :

- La méthode statique `By.css()` sélectionne les nœuds `DebugElement` avec un [selector CSS standard](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS selectors').
- La query renvoie un `DebugElement` pour le paragraphe.
- Vous devez extraire l'élément enveloppé dans ce résultat pour obtenir l'élément paragraphe.

Quand vous filtrez par selector CSS et ne testez que les propriétés de l'_élément natif_ d'un navigateur, l'approche `By.css` peut être excessive.

Il est souvent plus simple et plus clair de filtrer avec une méthode standard de `HTMLElement` comme `querySelector()` ou `querySelectorAll()`.
# Scénarios de test de composants

Ce guide explore des cas d'usage courants du test de composants.

## Binding de composant {#component-binding}

Dans l'application d'exemple, le composant `Banner` présente un titre statique dans le template HTML.

Après quelques modifications, le composant `Banner` présente un titre dynamique grâce à un binding sur la propriété `title` du composant, comme ceci.

```typescript
{header: "banner.ts"}
import {Component, signal} from '@angular/core';

@Component({
  selector: 'app-banner',
  template: '<h1>{{ title() }}</h1>',
  styles: ['h1 { color: green; font-size: 350%}'],
})
export class Banner {
  title = signal('Test Tour of Heroes');
}
```

Aussi minimal soit-il, vous décidez d'ajouter un test pour confirmer que le composant affiche réellement le bon contenu là où vous l'attendez.

### Récupérer le `<h1>` {#query-for-the-h1}

Vous allez écrire une série de tests qui inspectent la valeur de l'élément `<h1>` qui encapsule le binding d'interpolation de la propriété _title_.

Vous modifiez le `beforeEach` pour trouver cet élément avec un `querySelector` HTML standard et l'assigner à la variable `h1`.

```ts
{header: "banner.component.spec.ts"}
let component: Banner;
let fixture: ComponentFixture<Banner>;
let h1: HTMLElement;

beforeEach(() => {
  fixture = TestBed.createComponent(Banner);
  component = fixture.componentInstance; // Banner test instance
  h1 = fixture.nativeElement.querySelector('h1');
});
```

### `createComponent()` ne lie pas les données {#createcomponent-does-not-bind-data}

Pour votre premier test, vous aimeriez vérifier que l'écran affiche le `title` par défaut.
Votre premier réflexe est d'écrire un test qui inspecte immédiatement le `<h1>`, comme ceci :

```ts
it('should display original title', () => {
  expect(h1.textContent).toContain(component.title());
});
```

_Ce test échoue_ avec le message :

```shell
{hideCopy}
expected '' to contain 'Test Tour of Heroes'.
```

Le binding a lieu quand Angular effectue la **détection de changements**.

En production, la détection de changements se déclenche automatiquement quand Angular crée un composant ou quand l'utilisateur saisit une touche, par exemple.

`TestBed.createComponent` ne déclenche pas la détection de changements de manière synchrone ; un fait confirmé dans le test révisé :

```ts
it('no title in the DOM after createComponent()', () => {
  expect(h1.textContent).toEqual('');
});
```

### `whenStable()` {#whenstable}

Vous pouvez demander au `TestBed` d'attendre l'exécution de la détection de changements avec `await fixture.whenStable()`.
Ce n'est qu'alors que le `<h1>` contient le titre attendu.

```ts
it('should display original title', async () => {
  await fixture.whenStable();
  expect(h1.textContent).toContain(component.title());
});
```

Le report de la détection de changements est intentionnel et utile.
Il donne au testeur l'occasion d'inspecter et de modifier l'état du composant _avant qu'Angular n'initie le data binding et n'appelle les [lifecycle hooks](guide/components/lifecycle)_.

Voici un autre test qui modifie la propriété `title` du composant _avant_ d'appeler `fixture.whenStable()`.

```ts
it('should display a different test title', async () => {
  component.title.set('Test Title');
  await fixture.whenStable();
  expect(h1.textContent).toContain('Test Title');
});
```

### Lier des signals aux inputs {#binding-signals-to-inputs}

Pour refléter les changements des inputs et écouter les outputs, vous pouvez lier dynamiquement des signals aux inputs et des fonctions aux outputs.

```ts
import {inputBinding, outputBinding} from '@angular/core';
import {TestBed} from '@angular/core/testing';

const fixture = TestBed.createComponent(ValueDisplay, {
  bindings: [
    inputBinding('value', value),
    outputBinding('valueChange', () =>  (/* ... */) ),
  ],
});
```

### Modifier la valeur d'un champ avec `dispatchEvent()` {#change-an-input-value-with-dispatchevent}

Pour simuler une saisie de l'utilisateur, trouvez l'élément input et définissez sa propriété `value`.

Mais il existe une étape intermédiaire essentielle.

Angular ne sait pas que vous avez défini la propriété `value` de l'élément input.
Il ne lira pas cette propriété tant que vous n'aurez pas déclenché l'événement `input` de l'élément en appelant `dispatchEvent()`.

L'exemple suivant, un composant qui utilise le `TitleCasePipe`, illustre la bonne séquence.

```ts
it('should convert hero name to Title Case', async () => {
  const hostElement = fixture.nativeElement;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## Composant avec une dépendance {#component-with-a-dependency}

Les composants ont souvent des dépendances envers des services.

Le composant `Welcome` affiche un message de bienvenue à l'utilisateur connecté.
Il sait qui est l'utilisateur grâce à une propriété du service `UserAuthentication` injecté :

```typescript
import {Component, inject, OnInit, signal} from '@angular/core';
import {UserAuthentication} from '../model/user.authentication';

@Component({
  selector: 'app-welcome',
  template: '<h3 class="welcome"><i>{{ welcome() }}</i></h3>',
})
export class Welcome {
  private userAuth = inject(UserAuthentication);
  welcome = signal(
    this.userAuth.isLoggedIn() ? `Welcome, ${this.userAuth.user().name}` : 'Please log in.',
  );
}
```

Le composant `Welcome` contient une logique de décision qui interagit avec le service, une logique qui rend ce composant digne d'être testé.

### Fournir des doublures de test pour les services {#provide-service-test-doubles}

Un _composant sous test_ n'a pas besoin de recevoir les vrais services.

Injecter le vrai `UserAuthentication` pourrait être difficile.
Le vrai service pourrait demander à l'utilisateur ses identifiants de connexion et tenter de joindre un serveur d'authentification.
Ces comportements peuvent être difficiles à intercepter. Gardez à l'esprit que l'utilisation de doublures de test fait que le test se comporte différemment de la production : utilisez-les donc avec parcimonie.

### Récupérer les services injectés {#get-injected-services}

Les tests ont besoin d'accéder au `UserAuthentication` injecté dans le composant `Welcome`.

Angular dispose d'un système d'injection hiérarchique.
Il peut y avoir des injectors à plusieurs niveaux, depuis l'injector racine créé par le `TestBed` jusqu'au bas de l'arbre de composants.

La manière la plus sûre de récupérer le service injecté, celle qui **_fonctionne toujours_**,
consiste à **le récupérer depuis l'injector du _composant sous test_**.
L'injector du composant est une propriété du `DebugElement` de la fixture.

```ts
// UserAuthentication actually injected into the component
userAuth = fixture.debugElement.injector.get(UserAuthentication);
```

HELPFUL: Ce n'est _généralement_ pas nécessaire. Les services sont souvent fournis à la racine ou via les surcharges du TestBed, et peuvent être récupérés plus facilement avec `TestBed.inject()` (voir ci-dessous).

### `TestBed.inject()` {#testbedinject}

C'est plus facile à retenir et moins verbeux que de récupérer un service via le `DebugElement` de la fixture.

Dans cette suite de tests, le _seul_ provider de `UserAuthentication` est le module de test racine : vous pouvez donc appeler `TestBed.inject()` sans risque, comme suit :

```ts
userAuth = TestBed.inject(UserAuthentication);
```

HELPFUL: Pour un cas d'usage dans lequel `TestBed.inject()` ne fonctionne pas, consultez la section [_Surcharger les providers d'un composant_](#override-component-providers), qui explique quand et pourquoi vous devez plutôt récupérer le service depuis l'injector du composant.

### Configuration finale et tests {#final-setup-and-tests}

Voici le `beforeEach()` complet, avec `TestBed.inject()` :

```ts
let fixture: ComponentFixture<Welcome>;
let comp: Welcome;
let userAuth: UserAuthentication; // the TestBed injected service
let el: HTMLElement; // the DOM element with the welcome message

beforeEach(() => {
  fixture = TestBed.createComponent(Welcome);
  comp = fixture.componentInstance;

// UserAuthentication from the root injector
  userAuth = TestBed.inject(UserAuthentication);

//  get the "welcome" element by CSS selector (e.g., by class name)
  el = fixture.nativeElement.querySelector('.welcome');
});
```

Et voici quelques tests :

```ts
it('should welcome the user', async () => {
  await fixture.whenStable();
  const content = el.textContent;

expect(content, '"Welcome ..."').toContain('Welcome');
  expect(content, 'expected name').toContain('Test User');
});

it('should welcome "Bubba"', async () => {
  userAuth.user.set({name: 'Bubba'}); // welcome message hasn't been shown yet
  await fixture.whenStable();

expect(el.textContent).toContain('Bubba');
});

it('should request login if not logged in', async () => {
  userAuth.isLoggedIn.set(false); // welcome message hasn't been shown yet
  await fixture.whenStable();
  const content = el.textContent;

expect(content, 'not welcomed').not.toContain('Welcome');
  expect(content, '"log in"').toMatch(/log in/i);
});
```

Le premier est un test de bon sens (sanity test) ; il confirme que `UserAuthentication` est appelé et fonctionne.

HELPFUL: Le 2e argument de `expect` $par exemple, `'expected name'`$ est un libellé d'échec optionnel.
Si l'attente échoue, Vitest ajoute ce libellé au message d'échec de l'attente.
Dans une spec contenant plusieurs attentes, il peut aider à comprendre ce qui s'est mal passé et quelle attente a échoué.

Les tests restants confirment la logique du composant quand le service renvoie différentes valeurs.
Le deuxième test valide l'effet d'un changement du nom de l'utilisateur.
Le troisième test vérifie que le composant affiche le bon message quand aucun utilisateur n'est connecté.

## Composant avec un service asynchrone {#component-with-async-service}

Dans cet exemple, le template du composant `About` héberge un composant `Twain`.
Le composant `Twain` affiche des citations de Mark Twain.

```html
<p class="twain">
  <i>{{ quote | async }}</i>
</p>
<button type="button" (click)="getQuote()">Next quote</button>
@if (errorMessage()) {
  <p class="error">{{ errorMessage() }}</p>
}
```

HELPFUL: La valeur de la propriété `quote` du composant passe par un `AsyncPipe`.
Cela signifie que la propriété renvoie soit une `Promise`, soit un `Observable`.

Dans cet exemple, la méthode `TwainQuotes.getQuote()` vous indique que la propriété `quote` renvoie un `Observable`.

```ts
getQuote() {
  this.errorMessage.set('');
  this.quote = this.twainQuotes.getQuote().pipe(
    startWith('...'),
    catchError((err: any) => {
      this.errorMessage.set(err.message || err.toString());
      return of('...'); // reset message to placeholder
    }),
  );
}
```

Le composant `Twain` récupère des citations depuis un `TwainQuotes` injecté.
Le composant démarre l'`Observable` renvoyé avec une valeur de placeholder $`'...'`$, avant que le service ne puisse renvoyer sa première citation.

Le `catchError` intercepte les erreurs du service, prépare un message d'erreur et renvoie la valeur de placeholder sur le canal de succès.

Ce sont autant de fonctionnalités que vous voudrez tester.

### Tester en mockant les requêtes HTTP avec `HttpTestingController`. {#testing-by-mocking-http-requests-with-the-httptestingcontroller}

Lorsque vous testez un composant, seule l'API publique du service devrait compter.
En général, les tests eux-mêmes ne devraient pas effectuer d'appels vers des serveurs distants.
Ils devraient émuler ces appels.

Si votre service asynchrone s'appuie sur `HttpClient` pour charger des données distantes, il est recommandé de renvoyer des mocks de réponses au niveau HTTP avec `HttpTestingController`.

Pour plus de détails sur le mock de `HttpBackend`, consultez le [guide dédié](guide/http/testing).

### Tester en fournissant une implémentation stub d'un service. {#testing-by-providing-a-stubbed-implementation-of-a-service}

Quand il n'est pas possible de mocker les requêtes asynchrones au niveau HTTP, une alternative consiste à tirer parti des spies.

La configuration de ce fichier `app/twain/twain-quotes.spec.ts` montre une façon de procéder :

```ts
{header: "twain.spec.ts"}
class TwainQuotesStub implements TwainQuotes {
  private testQuote = 'Test Quote';

getQuote() {
    return of(this.testQuote);
  }

// ... Implement everything to conform to the API
}

beforeEach(async () => {
  TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

fixture = TestBed.createComponent(Twain);
  component = fixture.componentInstance;
  await fixture.whenStable();
  quoteEl = fixture.nativeElement.querySelector('.twain');
});
```

Concentrez-vous sur la façon dont l'implémentation stub remplace l'implémentation d'origine.

```ts
TestBed.configureTestingModule({
  providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
});
```

Le stub est conçu de telle sorte que tout composant ou service qui l'injecte recevra l'implémentation stub.
Cela signifie que tout appel à `getQuote` reçoit un observable contenant une citation de test.

Contrairement à la vraie méthode `getQuote()`, ce spy contourne le serveur et renvoie un observable synchrone dont la valeur est disponible immédiatement.

### Test asynchrone avec les fake timers de Vitest {#async-test-with-a-vitest-fake-timers}

Pour mocker des fonctions asynchrones comme `setTimeout` ou des `Promise`, vous pouvez tirer parti des fake timers de Vitest pour contrôler le moment où elles se déclenchent.

```ts
it('should display error when TwainQuotes service fails', async () => {
  class TwainQuotesStub implements TwainQuotes {
    getQuote() {
      return defer(() => {
        return new Promise<string>((_, reject) => {
          setTimeout(() => reject('TwainService test failure'));
        });
      });
    }

// ... Implement everything to conform to the API
  }

TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

vi.useFakeTimers(); // setting up the fake timers
  const fixture = TestBed.createComponent(TwainComponent);

// rendering isn't async, we need to flush
  await vi.runAllTimersAsync();

await expect(fixture.nativeElement.querySelector('.error')!.textContent).toMatch(/test failure/);
  expect(fixture.nativeElement.querySelector('.twain')!.textContent).toBe('...');

vi.useRealTimers(); // resets to regular async execution
});
```

### Autres tests asynchrones {#more-async-tests}

Comme le service stub renvoie des observables asynchrones, la plupart de vos tests devront également être asynchrones.

Voici un test qui illustre le flux de données auquel vous vous attendriez en conditions réelles.

```ts
class MockTwainQuotes implements TwainQuotes {
  private subject = new Subject<string>();

getQuote() {
    return this.subject.asObservable();
  }

emit(val: string) {
    this.subject.next(val);
  }
}

it('should show quote after getQuote (success)', async () => {
  vi.useFakeTimers();

TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: MockTwainQuotes}],
  });

const fixture = TestBed.createComponent(TwainComponent);
  const twainQuotes = TestBed.inject(TwainQuotes) as MockTwainQuotes;
  await vi.runAllTimersAsync(); // render before the quote is received

const quoteEl = fixture.nativeElement.querySelector('.twain');
  expect(quoteEl.textContent).toBe('...');

twainQuotes.emit('Twain Quote'); // emits the quote
  await vi.runAllTimersAsync(); // render with the quote received

expect(quoteEl.textContent).toBe('Twain Quote');
  expect(fixture.nativeElement.querySelector('.error')).toBeNull();

vi.useRealTimers();
});
```

Remarquez que l'élément de citation affiche la valeur de placeholder $`'...'`$ lors du premier rendu.
La première citation n'est pas encore arrivée.

Vous pouvez ensuite vérifier que l'élément de citation affiche le texte attendu.

### Tests asynchrones avec `zone.js` et `fakeAsync` {#async-tests-with-zonejs-and-fakeasync}

La fonction utilitaire `fakeAsync` est une autre horloge simulée qui s'appuie sur le patch des API asynchrones par `zone.js`. Elle était couramment utilisée pour les tests dans les applications basées sur `zone.js`. L'utilisation de `fakeAsync` n'est plus recommandée.

TIP: Privilégiez les stratégies natives de test asynchrone ou d'autres fake timers (aussi appelés horloges simulées, ou mock clocks), comme ceux de Vitest ou de Jasmine.

IMPORTANT: `fakeAsync` nécessite `zone.js`. Pour l'utiliser avec le test runner Vitest, ajoutez le polyfill `zone.js/plugins/vitest-patch` comme décrit dans [le guide de migration vers Vitest](guide/testing/migrating-to-vitest#zonejs-vitest-patch).

## Composant avec des inputs et des outputs {#component-with-inputs-and-outputs}

Un composant avec des inputs et des outputs apparaît généralement dans le template de la vue d'un composant hôte.
Le host utilise un property binding pour définir la propriété d'input et un event binding pour écouter les événements émis par la propriété d'output.

L'objectif du test est de vérifier que ces bindings fonctionnent comme prévu.
Les tests doivent définir les valeurs des inputs et écouter les événements des outputs.

Le composant `DashboardHero` est un petit exemple de composant dans ce rôle.
Il affiche un héros individuel fourni par le composant `Dashboard`.
Cliquer sur ce héros indique au composant `Dashboard` que l'utilisateur a sélectionné le héros.

Le composant `DashboardHero` est intégré dans le template du composant `Dashboard` comme ceci :

```html
@for (hero of heroes; track hero) {
  <dashboard-hero class="col-1-4" [hero]="hero" (selected)="gotoDetail($event)" />
}
```

Le composant `DashboardHero` apparaît dans un bloc `@for`, qui définit la propriété d'input `hero` de chaque composant avec la valeur de l'itération et écoute l'événement `selected` du composant.

Voici la définition complète du composant :

```typescript
@Component({
  selector: 'dashboard-hero',
  imports: [UpperCasePipe],
  template: `
    <button type="button" (click)="click()" class="hero">
      {{ hero().name | uppercase }}
    </button>
  `,
})
export class DashboardHero {
  readonly hero = input.required<Hero>();
  readonly selected = output<Hero>();

click() {
    this.selected.emit(this.hero());
  }
}
```

Même si tester un composant aussi simple a peu de valeur intrinsèque, il est utile de savoir comment faire.
Utilisez l'une de ces approches :

- Le tester tel qu'il est utilisé par le composant `Dashboard`
- Le tester en tant que composant standalone
- Le tester tel qu'il est utilisé par un substitut du composant `Dashboard`

L'objectif immédiat est de tester le composant `DashboardHero`, et non le composant `Dashboard` : essayez donc les deuxième et troisième options.

### Tester le composant `DashboardHero` de manière isolée {#test-the-dashboardhero-component-standalone}

Voici l'essentiel de la configuration du fichier de spec.

```ts
let fixture: ComponentFixture<DashboardHero>;
let comp: DashboardHero;
let heroDe: DebugElement;
let heroEl: HTMLElement;
let expectedHero: Hero;

beforeEach(async () => {
  fixture = TestBed.createComponent(DashboardHero);
  comp = fixture.componentInstance;

// find the hero's DebugElement and element
  heroDe = fixture.debugElement.query(By.css('.hero'));
  heroEl = heroDe.nativeElement;

// mock the hero supplied by the parent component
  expectedHero = {id: 42, name: 'Test Name'};

// simulate the parent setting the input property with that hero
  fixture.componentRef.setInput('hero', expectedHero);

// wait for initial data binding
  await fixture.whenStable();
});
```

Remarquez comment le code de configuration assigne un héros de test $`expectedHero`$ à la propriété `hero` du composant, en émulant la façon dont le `Dashboard` la définirait avec le property binding dans sa boucle de répétition.

Le test suivant vérifie que le nom du héros est propagé au template grâce à un binding.

```ts
it('should display hero name in uppercase', () => {
  const expectedPipedName = expectedHero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});
```

Comme le template fait passer le nom du héros par le `UpperCasePipe` d'Angular, le test doit comparer la valeur de l'élément avec le nom en majuscules.

### Cliquer {#clicking}

Cliquer sur le héros doit émettre un événement `selected` que le composant hôte $vraisemblablement `Dashboard`$ peut écouter :

```ts
it('should raise selected event when clicked (triggerEventHandler)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

heroDe.triggerEventHandler('click');
  expect(selectedHero).toBe(expectedHero);
});
```

La propriété `selected` du composant est un `OutputEmitterRef`, dont la méthode `subscribe` notifie les abonnés de manière synchrone.
Le test s'y abonne _explicitement_, tout comme le composant hôte le fait _implicitement_.

Si le composant se comporte comme prévu, cliquer sur l'élément du héros doit indiquer à la propriété `selected` du composant d'émettre l'objet `hero`.

Le test détecte cet événement grâce à son abonnement à `selected`.

### `triggerEventHandler` {#triggereventhandler}

Le `heroDe` du test précédent est un `DebugElement` qui représente le `<button>` du héros.

Il possède des propriétés et méthodes Angular qui abstraient l'interaction avec l'élément natif.
Ce test appelle `DebugElement.triggerEventHandler` avec le nom d'événement « click ».
L'event binding « click » réagit en appelant `DashboardHero.click()`.

`DebugElement.triggerEventHandler` d'Angular peut déclencher _n'importe quel événement lié par binding_ à partir de son _nom d'événement_.
Le second paramètre est l'objet événement transmis au handler.

Le test a déclenché un événement « click ».

```ts
heroDe.triggerEventHandler('click');
```

Dans ce cas, le test suppose à juste titre que l'event handler exécuté, la méthode `click()` du composant, ne se soucie pas de l'objet événement.

HELPFUL: D'autres handlers sont moins tolérants.
Par exemple, la directive `RouterLink` attend un objet avec une propriété `button` qui identifie quel bouton de la souris a éventuellement été pressé lors du clic.
La directive `RouterLink` lève une erreur si l'objet événement est absent.

### Cliquer sur l'élément {#click-the-element}

L'alternative de test suivante appelle la propre méthode `click()` de l'élément natif, ce qui convient parfaitement pour _ce composant_.

```ts
it('should raise selected event when clicked (element.click)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

heroEl.click();
  expect(selectedHero).toBe(expectedHero);
});
```

### Fonction utilitaire `click()` {#click-helper}

Cliquer sur un bouton, un lien ou n'importe quel élément HTML est une tâche de test courante.

Rendez-la cohérente et simple en encapsulant le processus de _déclenchement du clic_ dans une fonction utilitaire comme la fonction `click()` suivante :

```ts
/** Button events to pass to `DebugElement.triggerEventHandler` for RouterLink event handler */
export const ButtonClickEvents = {
  left: {button: 0},
  right: {button: 2},
};

/** Simulate element click. Defaults to mouse left-button click event. */
export function click(
  el: DebugElement | HTMLElement,
  eventObj: any = ButtonClickEvents.left,
): void {
  if (el instanceof HTMLElement) {
    el.click();
  } else {
    el.triggerEventHandler('click', eventObj);
  }
}
```

Le premier paramètre est l'_élément sur lequel cliquer_.
Si vous le souhaitez, passez un objet événement personnalisé comme second paramètre.
La valeur par défaut est un [objet d'événement souris du bouton gauche](https://developer.mozilla.org/docs/Web/API/MouseEvent/button) partiel, accepté par de nombreux handlers, dont la directive `RouterLink`.

IMPORTANT: La fonction utilitaire `click()` ne fait **pas** partie des utilitaires de test d'Angular.
C'est une fonction définie dans _le code d'exemple de ce guide_.
Tous les tests d'exemple l'utilisent.
Si elle vous plaît, ajoutez-la à votre propre collection de fonctions utilitaires.

Voici le test précédent, réécrit avec la fonction utilitaire click.

```ts
it('should raise selected event when clicked (click helper with DebugElement)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

click(heroDe); // click helper with DebugElement

expect(selectedHero).toBe(expectedHero);
});
```

## Composant dans un test host {#component-inside-a-test-host}

Les tests précédents jouaient eux-mêmes le rôle du composant hôte `Dashboard`.
Mais le composant `DashboardHero` fonctionne-t-il correctement lorsqu'il est correctement lié par binding à un composant hôte ?

```typescript
@Component({
  imports: [DashboardHero],
  template: ` <dashboard-hero [hero]="hero" (selected)="onSelected($event)" />`,
})
class TestHost {
  hero: Hero = {id: 42, name: 'Test Name'};
  selectedHero: Hero | undefined;

onSelected(hero: Hero) {
    this.selectedHero = hero;
  }
}
```

Le test host définit la propriété d'input `hero` du composant avec son héros de test.
Il lie l'événement `selected` du composant à son handler `onSelected`, qui enregistre le héros émis dans sa propriété `selectedHero`.

Plus tard, les tests pourront vérifier `selectedHero` pour s'assurer que l'événement `DashboardHero.selected` a émis le héros attendu.

La configuration des tests `test-host` est similaire à celle des tests isolés :

```ts
beforeEach(async () => {
  // create TestHost instead of DashboardHero
  fixture = TestBed.createComponent(TestHost);
  testHost = fixture.componentInstance;
  heroEl = fixture.nativeElement.querySelector('.hero');

await fixture.whenStable();
});
```

Cette configuration du module de test présente deux différences importantes :

- Elle _crée_ le composant `TestHost` au lieu du `DashboardHero`
- Le composant `TestHost` définit `DashboardHero.hero` avec un binding

`createComponent` renvoie une `fixture` qui contient une instance de `TestHost` au lieu d'une instance de `DashboardHero`.

Créer le `TestHost` a pour effet de bord de créer un `DashboardHero`, car ce dernier apparaît dans le template du premier.
La query de l'élément du héros $`heroEl`$ le trouve toujours dans le DOM de test, bien qu'à une profondeur plus grande qu'auparavant dans l'arbre des éléments.

Les tests eux-mêmes sont presque identiques à la version isolée :

```ts
it('should display hero name', () => {
  const expectedPipedName = testHost.hero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});

it('should raise selected event when clicked', () => {
  click(heroEl);
  // selected hero should be the same data bound hero
  expect(testHost.selectedHero).toBe(testHost.hero);
});
```

Seul le test de l'événement selected diffère.
Il confirme que le héros `DashboardHero` sélectionné remonte bien jusqu'au composant hôte via l'event binding.

## Composant de routing {#routing-component}

Un _composant de routing_ est un composant qui demande au `Router` de naviguer vers un autre composant.
Le composant `Dashboard` est un _composant de routing_, car l'utilisateur peut naviguer vers le composant `HeroDetail` en cliquant sur l'un des _boutons de héros_ du tableau de bord.

Angular fournit des utilitaires de test pour réduire le code répétitif et tester plus efficacement le code qui dépend de `HttpClient`. La fonction `provideRouter` peut aussi être utilisée directement dans le module de test.

```ts
beforeEach(async () => {
  TestBed.configureTestingModule({
    providers: [
      provideRouter([{path: '**', component: Dashboard}]),
      provideHttpClientTesting(),
      HeroService,
    ],
  });
  harness = await RouterTestingHarness.create();
  comp = await harness.navigateByUrl('/', Dashboard);
  TestBed.inject(HttpTestingController).expectOne('api/heroes').flush(getTestHeroes());
});
```

Le test suivant clique sur le héros affiché et confirme que la navigation mène à l'URL attendue.

```ts
it('should tell navigate when hero clicked', async () => {
  // get first <dashboard-hero> DebugElement
  const heroDe = harness.routeDebugElement!.query(By.css('dashboard-hero'));
  heroDe.triggerEventHandler('selected', comp.heroes[0]);

// expecting to navigate to id of the component's first hero
  const id = comp.heroes[0].id;
  expect(TestBed.inject(Router).url, 'should nav to HeroDetail for first hero').toEqual(
    `/heroes/${id}`,
  );
});
```

## Composants routés {#routed-components}

Un _composant routé_ est la destination d'une navigation du `Router`.
Il peut être plus délicat à tester, en particulier quand la route vers le composant _inclut des paramètres_.
`HeroDetail` est un _composant routé_ qui est la destination d'une telle route.

Quand un utilisateur clique sur un héros du _Dashboard_, le `Dashboard` demande au `Router` de naviguer vers `heroes/:id`.
`:id` est un paramètre de route dont la valeur est l'`id` du héros à modifier.

Le `Router` fait correspondre cette URL à une route vers `HeroDetail`.
Il crée un objet `ActivatedRoute` avec les informations de routing et l'injecte dans une nouvelle instance de `HeroDetail`.

Voici les services injectés dans `HeroDetail` :

```ts
private heroDetailService = inject(HeroDetailService);
private route = inject(ActivatedRoute);
private router = inject(Router);
```

Le composant `HeroDetail` a besoin du paramètre `id` pour récupérer le héros correspondant avec `HeroDetailService`.
Le composant doit obtenir l'`id` depuis la propriété `ActivatedRoute.paramMap`, qui est un `Observable`.

Il ne peut pas simplement référencer la propriété `id` de `ActivatedRoute.paramMap`.
Le composant doit _s'abonner_ à l'observable `ActivatedRoute.paramMap` et être prêt à ce que l'`id` change au cours de sa vie.

```ts
constructor() {
  // get hero when `id` param changes
  this.route.paramMap.subscribe((pmap) => this.getHero(pmap.get('id')));
}
```

Les tests peuvent explorer la façon dont `HeroDetail` réagit à différentes valeurs du paramètre `id` en naviguant vers différentes routes.

## Tests de composants imbriqués {#nested-component-tests}

Les templates de composants contiennent souvent des composants imbriqués, dont les templates peuvent eux-mêmes contenir d'autres composants.

L'arbre de composants peut être très profond, et parfois les composants imbriqués ne jouent aucun rôle dans le test du composant situé en haut de l'arbre.

Le composant `App`, par exemple, affiche une barre de navigation avec des liens et leurs directives `RouterLink`.

```html
<app-banner />
<app-welcome />

<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>

<router-outlet />
```

Pour valider les liens mais pas la navigation, vous n'avez pas besoin que le `Router` navigue, ni du `<router-outlet>` pour indiquer où le `Router` insère les _composants routés_.

Les composants `Banner` et `Welcome` $indiqués par `<app-banner>` et `<app-welcome>`$ ne sont pas pertinents non plus.

Pourtant, tout test qui crée le composant `App` dans le DOM crée aussi des instances de ces trois composants et, si vous laissez faire, vous devrez configurer le `TestBed` pour les créer.

Si vous omettez de les déclarer, le compilateur Angular ne reconnaîtra pas les balises `<app-banner>`, `<app-welcome>` et `<router-outlet>` du template de `App` et lèvera une erreur.

Si vous déclarez les vrais composants, vous devrez aussi déclarer _leurs_ composants imbriqués et fournir _tous_ les services injectés dans _n'importe quel_ composant de l'arbre.

Cette section décrit deux techniques pour réduire la configuration au minimum.
Utilisez-les, seules ou combinées, pour rester concentré sur le test du composant principal.

### Remplacer les composants inutiles par des stubs {#stubbing-unneeded-components}

Dans la première technique, vous créez et déclarez des versions stub des composants et de la directive qui jouent peu ou pas de rôle dans les tests.

```ts
@Component({selector: 'app-banner', template: ''})
class BannerStub {}

@Component({selector: 'router-outlet', template: ''})
class RouterOutletStub {}

@Component({selector: 'app-welcome', template: ''})
class WelcomeStub {}
```

Les selectors des stubs correspondent aux selectors des vrais composants correspondants.
Mais leurs templates et leurs classes sont vides.

Déclarez-les ensuite en surchargeant les `imports` de votre composant avec `TestBed.overrideComponent`.

```ts
let comp: App;
let fixture: ComponentFixture<App>;

beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [RouterLink, BannerStub, RouterOutletStub, WelcomeStub],
    },
  });

fixture = TestBed.createComponent(App);
  comp = fixture.componentInstance;
});
```

HELPFUL: Dans cet exemple, la clé `set` remplace tous les imports existants de votre composant : veillez à importer toutes les dépendances, et pas seulement les stubs. Vous pouvez aussi utiliser les clés `remove`/`add` pour retirer et ajouter des imports de manière sélective.

### `NO_ERRORS_SCHEMA` {#noerrorsschema}

Dans la seconde approche, ajoutez `NO_ERRORS_SCHEMA` aux surcharges de métadonnées de votre composant.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [], // resets all imports
      schemas: [NO_ERRORS_SCHEMA],
    },
  });
});
```

`NO_ERRORS_SCHEMA` indique au compilateur Angular d'ignorer les éléments et attributs non reconnus.

Le compilateur reconnaît l'élément `<app-root>` et l'attribut `routerLink`, car vous avez déclaré un composant `App` et un `RouterLink` correspondants dans la configuration du `TestBed`.

Mais le compilateur ne lèvera pas d'erreur lorsqu'il rencontrera `<app-banner>`, `<app-welcome>` ou `<router-outlet>`.
Il les rend simplement comme des balises vides, et le navigateur les ignore.

Vous n'avez plus besoin des composants stub.

### Utiliser les deux techniques ensemble {#use-both-techniques-together}

Ce sont des techniques de _test superficiel de composants_ (Shallow Component Testing), ainsi nommées parce qu'elles réduisent la surface visuelle du composant aux seuls éléments de son template qui comptent pour les tests.

L'approche `NO_ERRORS_SCHEMA` est la plus simple des deux, mais n'en abusez pas.

`NO_ERRORS_SCHEMA` empêche aussi le compilateur de vous signaler les composants et attributs manquants que vous avez omis par inadvertance ou mal orthographiés.
Vous pourriez perdre des heures à traquer des bugs fantômes que le compilateur aurait détectés en un instant.

L'approche par _composants stub_ présente un autre avantage.
Même si les stubs de _cet_ exemple étaient vides, vous pourriez leur donner des templates et des classes simplifiés si vos tests doivent interagir avec eux d'une manière ou d'une autre.

En pratique, vous combinerez les deux techniques dans la même configuration, comme dans cet exemple.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    remove: {imports: [RouterOutlet, Welcome]},
    set: {schemas: [NO_ERRORS_SCHEMA]},
  });
});
```

Le compilateur Angular crée le `BannerStub` pour l'élément `<app-banner>` et applique le `RouterLink` aux liens possédant l'attribut `routerLink`, mais il ignore les balises `<app-welcome>` et `<router-outlet>`.

### `By.directive` et directives injectées {#bydirective-and-injected-directives}

Un peu plus de configuration déclenche le data binding initial et récupère des références vers les liens de navigation :

```ts
beforeEach(async () => {
  await fixture.whenStable();

// find DebugElements with an attached RouterLinkStubDirective
  linkDes = fixture.debugElement.queryAll(By.directive(RouterLink));

// get attached link directive instances
  // using each DebugElement's injector
  routerLinks = linkDes.map((de) => de.injector.get(RouterLink));
});
```

Trois points méritent une attention particulière :

- Localisez les éléments de lien auxquels une directive est attachée avec `By.directive`
- La query renvoie des wrappers `DebugElement` autour des éléments correspondants
- Chaque `DebugElement` expose un injector de dépendances contenant l'instance spécifique de la directive attachée à cet élément

Les liens du composant `App` à valider sont les suivants :

```html
<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>
```

Voici quelques tests qui confirment que ces liens sont reliés aux directives `routerLink` comme prévu :

```ts
it('can get RouterLinks from template', () => {
  expect(routerLinks.length, 'should have 3 routerLinks').toBe(3);
  expect(routerLinks[0].href).toBe('/dashboard');
  expect(routerLinks[1].href).toBe('/heroes');
  expect(routerLinks[2].href).toBe('/about');
});

it('can click Heroes link in template', async () => {
  const heroesLinkDe = linkDes[1]; // heroes link DebugElement

TestBed.inject(Router).resetConfig([{path: '**', children: []}]);
  heroesLinkDe.triggerEventHandler('click', {button: 0});

await fixture.whenStable();

expect(TestBed.inject(Router).url).toBe('/heroes');
});
```

## Utiliser un objet `page` {#use-a-page-object}

Le composant `HeroDetail` est une vue simple avec un titre, deux champs de héros et deux boutons.

Mais même ce formulaire simple présente une bonne dose de complexité dans son template.

```html
@if (hero) {
  <div>
    <h2>
      <span>{{ hero.name | titlecase }}</span> Details
    </h2>
    <div><span>id: </span>{{ hero.id }}</div>
    <div>
      <label for="name">name: </label>
      <input id="name" [(ngModel)]="hero.name" placeholder="name" />
    </div>
    <button type="button" (click)="save()">Save</button>
    <button type="button" (click)="cancel()">Cancel</button>
  </div>
}
```

Les tests qui exercent le composant ont besoin…

- D'attendre l'arrivée d'un héros avant que les éléments n'apparaissent dans le DOM
- D'une référence vers le texte du titre
- D'une référence vers le champ de saisie du nom, pour l'inspecter et le définir
- De références vers les deux boutons, pour pouvoir cliquer dessus

Même un petit formulaire comme celui-ci peut produire un fouillis de configuration conditionnelle alambiquée et de sélections d'éléments CSS.

Maîtrisez cette complexité avec une classe `Page` qui gère l'accès aux propriétés du composant et encapsule la logique qui les définit.

Voici une telle classe `Page` pour `hero-detail.component.spec.ts`

```ts
class Page {
  // getter properties wait to query the DOM until called.
  get buttons() {
    return this.queryAll<HTMLButtonElement>('button');
  }
  get saveBtn() {
    return this.buttons[0];
  }
  get cancelBtn() {
    return this.buttons[1];
  }
  get nameDisplay() {
    return this.query<HTMLElement>('span');
  }
  get nameInput() {
    return this.query<HTMLInputElement>('input');
  }

//// query helpers ////
  private query<T>(selector: string): T {
    return harness.routeNativeElement!.querySelector(selector)! as T;
  }

private queryAll<T>(selector: string): T[] {
    return harness.routeNativeElement!.querySelectorAll(selector) as any as T[];
  }
}
```

Désormais, les points d'accroche importants pour manipuler et inspecter le composant sont bien organisés et accessibles depuis une instance de `Page`.

Une méthode `createComponent` crée un objet `page` et complète les éléments manquants une fois le `hero` arrivé.

```ts
async function createComponent(id: number) {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${id}`, HeroDetail);
  page = new Page();

const request = TestBed.inject(HttpTestingController).expectOne(`api/heroes/?id=${id}`);
  const hero = getTestHeroes().find((h) => h.id === Number(id));
  request.flush(hero ? [hero] : []);
  await harness.fixture.whenStable();
}
```

Voici quelques autres tests du composant `HeroDetail` pour appuyer ce point.

```ts
it("should display that hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(expectedHero.name);
});

it('should navigate when click cancel', () => {
  click(page.cancelBtn);
  expect(TestBed.inject(Router).url).toEqual(`/heroes/${expectedHero.id}`);
});

it('should save when click save but not navigate immediately', () => {
  click(page.saveBtn);
  expect(TestBed.inject(HttpTestingController).expectOne({method: 'PUT', url: 'api/heroes'}));
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should navigate when click save and save resolves', async () => {
  click(page.saveBtn);
  await harness.fixture.whenStable();
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should convert hero name to Title Case', async () => {
  // get the name's input and display elements from the DOM
  const hostElement: HTMLElement = harness.routeNativeElement!;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await harness.fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## Surcharger les providers d'un composant {#override-component-providers}

`HeroDetail` fournit son propre `HeroDetailService`.

```ts
@Component({
  /* ... */
  providers: [HeroDetailService],
})
export class HeroDetail {
  private heroDetailService = inject(HeroDetailService);
  private route = inject(ActivatedRoute);
  private router = inject(Router);
}
```

Il n'est pas possible de remplacer par un stub le `HeroDetailService` du composant dans les `providers` de `TestBed.configureTestingModule`.
Ce sont des providers pour le _module de test_, pas pour le composant.
Ils préparent l'injector de dépendances au _niveau de la fixture_.

Angular crée le composant avec son _propre_ injector, qui est un _enfant_ de l'injector de la fixture.
Il enregistre les providers du composant $ici, le `HeroDetailService`$ auprès de l'injector enfant.

Un test ne peut pas atteindre les services de l'injector enfant depuis l'injector de la fixture.
Et `TestBed.configureTestingModule` ne peut pas non plus les configurer.

Angular a donc créé de nouvelles instances du vrai `HeroDetailService` depuis le début !

HELPFUL: Ces tests pourraient échouer ou dépasser le délai d'attente si le `HeroDetailService` effectuait ses propres appels XHR vers un serveur distant.
Il se peut qu'il n'y ait aucun serveur distant à appeler.

Heureusement, le `HeroDetailService` délègue la responsabilité de l'accès aux données distantes à un `HeroService` injecté.

```ts
@Service()
export class HeroDetailService {
  private heroService = inject(HeroService);
}
```

La configuration de test précédente remplace le vrai `HeroService` par un `TestHeroService` qui intercepte les requêtes vers le serveur et simule leurs réponses.

Et si vous n'avez pas cette chance ?
Et s'il est difficile de simuler le `HeroService` ?
Et si `HeroDetailService` effectue ses propres requêtes vers le serveur ?

La méthode `TestBed.overrideComponent` peut remplacer les `providers` du composant par des _doublures de test_ faciles à gérer, comme le montre la variante de configuration suivante :

```ts
beforeEach(async () => {
  await TestBed.configureTestingModule({
    providers: [
      provideRouter([
        {path: 'heroes', component: HeroList},
        {path: 'heroes/:id', component: HeroDetail},
      ]),
      // HeroDetailService at this level is IRRELEVANT!
      {provide: HeroDetailService, useValue: {}},
    ],
  }).overrideComponent(HeroDetail, {
    set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
  });
});
```

Remarquez que `TestBed.configureTestingModule` ne fournit plus de faux `HeroService`, car il n'est [pas nécessaire](#provide-a-spy-stub-herodetailservicespy).

### La méthode `overrideComponent` {#the-overridecomponent-method}

Concentrez-vous sur la méthode `overrideComponent`.

```ts
.overrideComponent(HeroDetail, {
  set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
});
```

Elle prend deux arguments : le type du composant à surcharger $`HeroDetail`$ et un objet de métadonnées de surcharge.
L'[objet de métadonnées de surcharge](/guide/testing/utility-apis#testbed-class-summary) est un générique défini comme suit :

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

Un objet de surcharge de métadonnées peut soit ajouter et retirer des éléments dans les propriétés de métadonnées, soit réinitialiser complètement ces propriétés.
Cet exemple réinitialise les métadonnées `providers` du composant.

Le paramètre de type, `T`, correspond au type de métadonnées que vous passeriez au décorateur `@Component` :

```ts
selector?: string;
template?: string;
templateUrl?: string;
providers?: any[];
…
```

### Fournir un _spy stub_ (`HeroDetailServiceSpy`) {#provide-a-spy-stub-herodetailservicespy}

Cet exemple remplace complètement le tableau `providers` du composant par un nouveau tableau contenant un `HeroDetailServiceSpy`.

`HeroDetailServiceSpy` est une version stub du vrai `HeroDetailService` qui simule toutes les fonctionnalités nécessaires de ce service.
Il n'injecte pas le `HeroService` de plus bas niveau et ne lui délègue rien : il n'est donc pas nécessaire de fournir une doublure de test pour celui-ci.

Les tests associés du composant `HeroDetail` vérifieront que des méthodes du `HeroDetailService` ont été appelées en espionnant les méthodes du service.
Le stub implémente donc ses méthodes sous forme de spies :

```ts
import {vi} from 'vitest';

class HeroDetailServiceSpy {
  testHero: Hero = {...testHero};

/* emit cloned test hero */
  getHero = vi.fn(() => asyncData({...this.testHero}));

/* emit clone of test hero, with changes merged in */
  saveHero = vi.fn((hero: Hero) => asyncData(Object.assign(this.testHero, hero)));
}
```

### Les tests de surcharge {#the-override-tests}

Désormais, les tests peuvent contrôler directement le héros du composant en manipulant le `testHero` du spy stub, et confirmer que les méthodes du service ont été appelées.

```ts
let hdsSpy: HeroDetailServiceSpy;

beforeEach(async () => {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${testHero.id}`, HeroDetail);
  page = new Page();
  // get the component's injected HeroDetailServiceSpy
  hdsSpy = harness.routeDebugElement!.injector.get(HeroDetailService) as any;

harness.detectChanges();
});

it('should have called `getHero`', () => {
  expect(hdsSpy.getHero, 'getHero called once').toHaveBeenCalledTimes(1);
});

it("should display stub hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(hdsSpy.testHero.name);
});

it('should save stub hero change', async () => {
  const origName = hdsSpy.testHero.name;
  const newName = 'New Name';

page.nameInput.value = newName;

page.nameInput.dispatchEvent(new Event('input')); // tell Angular

expect(component.hero.name, 'component hero has new name').toBe(newName);
  expect(hdsSpy.testHero.name, 'service hero unchanged before save').toBe(origName);

click(page.saveBtn);
  expect(hdsSpy.saveHero, 'saveHero called once').toHaveBeenCalledTimes(1);

await harness.fixture.whenStable();
  expect(hdsSpy.testHero.name, 'service hero has new name after save').toBe(newName);
  expect(TestBed.inject(Router).url).toEqual('/heroes');
});
```

### Autres surcharges {#more-overrides}

La méthode `TestBed.overrideComponent` peut être appelée plusieurs fois pour le même composant ou pour des composants différents.
Le `TestBed` propose des méthodes similaires, `overrideDirective`, `overrideModule` et `overridePipe`, pour explorer et remplacer des parties de ces autres classes.

Explorez par vous-même les options et les combinaisons.
# Déboguer les tests

Si vos tests ne fonctionnent pas comme prévu, vous pouvez les déboguer aussi bien dans l'environnement Node.js par défaut que dans un vrai navigateur.

## Déboguer dans Node.js {#debugging-in-nodejs}

Le débogage dans l'environnement Node.js par défaut est souvent le moyen le plus rapide de diagnostiquer les problèmes qui ne sont pas liés aux API propres au navigateur ni au rendu.

1.  Exécutez la commande `ng test` avec le flag `--debug` :
    ```shell
ng test --debug
    ```
2.  Le test runner démarre en mode débogage et attend qu'un débogueur s'y attache.
3.  Vous pouvez maintenant attacher le débogueur de votre choix. Par exemple, vous pouvez utiliser le débogueur Node.js intégré à VS Code ou les Chrome DevTools pour Node.js.

## Déboguer dans un navigateur {#debugging-in-a-browser}

De la même manière que vous démarrez une session de débogage dans Node, vous pouvez utiliser `ng test` avec le flag `--debug` avec Vitest et le [mode navigateur](/guide/testing/migrating-to-vitest#5-configure-browser-mode-optional).

Le test runner démarre en mode débogage et attend que vous ouvriez les devtools du navigateur pour déboguer les tests.
# API utilitaires de test

NOTE: Pendant la mise à jour de ce guide pour Vitest, certaines descriptions et certains exemples d'API utilitaires sont présentés dans le contexte de Karma/Jasmine. Nous travaillons activement à fournir des équivalents Vitest et des recommandations à jour lorsque c'est pertinent.

Cette page décrit les fonctionnalités de test d'Angular les plus utiles.

Les utilitaires de test d'Angular comprennent le `TestBed`, la `ComponentFixture` et quelques fonctions qui contrôlent l'environnement de test.
Les classes [`TestBed`](#testbed-class-summary) et [`ComponentFixture`](#the-componentfixture) sont traitées séparément.

Voici un récapitulatif des fonctions autonomes, par ordre d'utilité probable :

| Fonction | Détails |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`inject`] | Injecte un ou plusieurs services depuis l'injector actuel du `TestBed` dans une fonction de test. Elle ne peut pas injecter un service fourni par le composant lui-même. Consultez la discussion sur [debugElement.injector](guide/testing/components-scenarios#get-injected-services). |
| `getTestBed` | Récupère l'instance actuelle du `TestBed`. Généralement inutile, car les méthodes de classe statiques de `TestBed` suffisent le plus souvent. L'instance de `TestBed` expose quelques membres rarement utilisés qui ne sont pas disponibles sous forme de méthodes statiques. |

Pour gérer des scénarios asynchrones complexes ou tester d'anciennes applications basées sur Zone.js, consultez le guide [Utilitaires de test de Zone.js](guide/testing/zone-js-testing-utilities).

## Récapitulatif de la classe `TestBed` {#testbed-class-summary}

La classe `TestBed` est l'un des principaux utilitaires de test d'Angular.
Son API est assez vaste et peut sembler écrasante tant que vous ne l'avez pas explorée, petit à petit.
Lisez d'abord le début de ce guide pour acquérir les bases avant d'essayer d'assimiler l'API complète.

La définition de module passée à `configureTestingModule` est un sous-ensemble des propriétés de métadonnées de `@NgModule`.

```ts
type TestModuleMetadata = {
  providers?: any[];
  declarations?: any[];
  imports?: any[];
  schemas?: Array<SchemaMetadata | any[]>;
};
```

Chaque méthode de surcharge prend un `MetadataOverride<T>` où `T` est le type de métadonnées adapté à la méthode, c'est-à-dire le paramètre d'un `@NgModule`, `@Component`, `@Directive` ou `@Pipe`.

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

L'API de `TestBed` se compose de méthodes de classe statiques qui mettent à jour ou référencent une instance _globale_ du `TestBed`.

En interne, toutes les méthodes statiques recouvrent des méthodes de l'instance de `TestBed` en cours d'exécution, qui est aussi renvoyée par la fonction `getTestBed()`.

Appelez les méthodes de `TestBed` _dans_ un `beforeEach()` pour garantir un nouveau départ avant chaque test.

Voici les méthodes statiques les plus importantes, par ordre d'utilité probable.

| Méthodes | Détails |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configureTestingModule` | Les shims de test établissent l'[environnement de test initial](guide/testing) et un module de test par défaut. Le module de test par défaut est configuré avec des déclarations de base et quelques substituts de services Angular dont tout testeur a besoin. <br /> Appelez `configureTestingModule` pour affiner la configuration du module de test pour un ensemble de tests donné, en ajoutant et en retirant des imports, des déclarations $de composants, de directives et de pipes$ et des providers. |
| `compileComponents` | Compile le module de test de manière asynchrone une fois que vous avez fini de le configurer. Vous **devez** appeler cette méthode si _l'un_ des composants du module de test possède des ressources chargées de manière asynchrone (comme des blocs @defer). |
| `createComponent<T>` | Crée une instance d'un composant de type `T` à partir de la configuration actuelle du `TestBed`. Après l'appel à `createComponent`, la configuration du `TestBed` est figée pour la durée de la spec en cours. |
| `overrideComponent` | Remplace les métadonnées de la classe de composant donnée, qui peut être imbriquée profondément dans un module interne. |
| `overrideDirective` | Remplace les métadonnées de la classe de directive donnée, qui peut être imbriquée profondément dans un module interne. |
| `overridePipe` | Remplace les métadonnées de la classe de pipe donnée, qui peut être imbriquée profondément dans un module interne. |
| `overrideModule` | Remplace les métadonnées du `NgModule` donné. Rappelez-vous que des modules peuvent importer d'autres modules. La méthode `overrideModule` peut atteindre en profondeur le module de test actuel pour modifier l'un de ces modules internes. |
| `inject` | Récupère un service depuis l'injector actuel du `TestBed`. La fonction `inject` suffit souvent pour cela. Mais `inject` lève une erreur si elle ne peut pas fournir le service. <br /> Et si le service est optionnel ? <br /> La méthode `TestBed.inject()` prend un second paramètre optionnel, l'objet à renvoyer si Angular ne trouve pas le provider $`null` dans cet exemple$ : `expect(TestBed.inject(NotProvided, null)).toBeNull();` Après l'appel à `TestBed.inject`, la configuration du `TestBed` est figée pour la durée de la spec en cours. |
| `initTestEnvironment` | Initialise l'environnement de test pour toute l'exécution des tests. <br /> Les shims de test l'appellent pour vous, il y a donc rarement une raison de l'appeler vous-même. <br /> Appelez cette méthode _une seule fois_. Pour changer ce comportement par défaut en cours d'exécution des tests, appelez d'abord `resetTestEnvironment`. <br /> Indiquez un module de test Angular par défaut et une `PlatformRef`. Des alternatives pour les plateformes autres que le navigateur sont disponibles sous la forme générale `@angular/platform-<platform_name>/testing`. |
| `resetTestEnvironment` | Réinitialise l'environnement de test initial, y compris le module de test par défaut. |

Quelques méthodes d'instance de `TestBed` ne sont pas couvertes par les méthodes _de classe_ statiques de `TestBed`.
Elles sont rarement nécessaires.

## La `ComponentFixture` {#the-componentfixture}

`TestBed.createComponent<T>` crée une instance du composant `T` et renvoie une `ComponentFixture` fortement typée pour ce composant.

Les propriétés et méthodes de `ComponentFixture` donnent accès au composant, à sa représentation DOM et à certains aspects de son environnement Angular.

### Propriétés de `ComponentFixture` {#componentfixture-properties}

Voici les propriétés les plus importantes pour les testeurs, par ordre d'utilité probable.

| Propriétés | Détails |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentInstance` | L'instance de la classe du composant créée par `TestBed.createComponent`. |
| `debugElement` | Le `DebugElement` associé à l'élément racine du composant. <br /> Le `debugElement` donne un aperçu du composant et de son élément DOM pendant les tests et le débogage. C'est une propriété essentielle pour les testeurs. Ses membres les plus intéressants sont présentés [ci-dessous](#debugelement). |
| `nativeElement` | L'élément DOM natif à la racine du composant. |
| `changeDetectorRef` | Le `ChangeDetectorRef` de la host view du composant, et non du composant lui-même. Consultez [Utiliser Zoneless dans `TestBed`](guide/zoneless#using-zoneless-in-testbed). |

### Méthodes de `ComponentFixture` {#componentfixture-methods}

Les méthodes de la _fixture_ amènent Angular à effectuer certaines tâches sur l'arbre de composants.
Appelez ces méthodes pour déclencher le comportement d'Angular en réponse à une action utilisateur simulée.

Voici les méthodes les plus utiles pour les testeurs.

| Méthodes | Détails |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detectChanges` | Déclenche un cycle de détection de changements pour le composant. <br /> Appelez-la pour initialiser le composant $elle appelle `ngOnInit`$ et, après que votre code de test a modifié les valeurs des propriétés liées par binding du composant. Angular ne voit pas que vous avez modifié `personComponent.name` et ne met pas à jour le binding `name` tant que vous n'appelez pas `detectChanges`. <br /> Exécute ensuite `checkNoChanges` pour confirmer qu'il n'y a pas de mises à jour circulaires, sauf si elle est appelée sous la forme `detectChanges(false)` ; |
| `autoDetectChanges` | Définissez-la à `true` quand vous voulez que la fixture détecte automatiquement les changements. <br /> Quand l'autodétection vaut `true`, la fixture de test appelle `detectChanges` immédiatement après la création du composant. Elle écoute ensuite les événements de zone pertinents et appelle `detectChanges` en conséquence. Quand votre code de test modifie directement les valeurs des propriétés du composant, vous devrez probablement encore appeler `fixture.detectChanges` pour déclencher les mises à jour du data binding. <br /> La valeur par défaut est `true` avec la détection de changements zoneless (la valeur par défaut du `TestBed`) et `false` avec la détection de changements basée sur Zone. |
| `checkNoChanges` | Effectue une passe de détection de changements pour s'assurer qu'il n'y a aucun changement en attente. Lève une exception s'il y en a. |
| `isStable` | Si la fixture est actuellement _stable_, renvoie `true`. S'il reste des tâches asynchrones non terminées, renvoie `false`. |
| `whenStable` | Renvoie une promise qui se résout quand la fixture est stable. <br /> Pour reprendre le test après la fin d'une activité asynchrone ou d'une détection de changements asynchrone, accrochez-vous à cette promise. Consultez [whenStable](guide/testing/components-scenarios#whenstable). |
| `destroy` | Déclenche la destruction du composant. |

#### `DebugElement` {#debugelement}

Le `DebugElement` donne des informations essentielles sur la représentation DOM du composant.

À partir du `DebugElement` du composant racine de test, renvoyé par `fixture.debugElement`, vous pouvez parcourir $et interroger$ l'ensemble des sous-arbres d'éléments et de composants de la fixture.

Voici les membres de `DebugElement` les plus utiles pour les testeurs, par ordre approximatif d'utilité :

| Membres | Détails |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeElement` | L'élément DOM correspondant dans le navigateur |
| `query` | Appeler `query(predicate: Predicate<DebugElement>)` renvoie le premier `DebugElement` qui correspond au prédicat, à n'importe quelle profondeur du sous-arbre. |
| `queryAll` | Appeler `queryAll(predicate: Predicate<DebugElement>)` renvoie tous les `DebugElements` qui correspondent au prédicat, à n'importe quelle profondeur du sous-arbre. |
| `injector` | L'injector de dépendances du host. Par exemple, l'injector de l'instance du composant de l'élément racine. |
| `componentInstance` | L'instance de composant propre à l'élément, s'il en a une. |
| `context` | Un objet qui fournit le contexte parent de cet élément. Souvent une instance de composant ancêtre qui gouverne cet élément. <br /> Quand un élément est répété dans un bloc `@for`, le contexte est un `RepeaterContext` dont la propriété `$implicit` est la valeur de l'instance de la ligne. Par exemple, le `hero` dans `@for(hero of heroes; ...)`. |
| `children` | Les enfants `DebugElement` directs. Parcourez l'arbre en descendant dans `children`. `DebugElement` possède aussi `childNodes`, une liste d'objets `DebugNode`. `DebugElement` dérive des objets `DebugNode`, et il y a souvent plus de nœuds que d'éléments. Les testeurs peuvent généralement ignorer les nœuds simples. |
| `parent` | Le `DebugElement` parent. Null s'il s'agit de l'élément racine. |
| `name` | Le nom de balise de l'élément, s'il s'agit d'un élément. |
| `triggerEventHandler` | Déclenche l'événement par son nom s'il existe un listener correspondant dans la collection `listeners` de l'élément. Le second paramètre est l'_objet événement_ attendu par le handler. <br /> Si l'événement n'a pas de listener ou s'il y a un autre problème, envisagez d'appeler `nativeElement.dispatchEvent(eventObject)`. |
| `listeners` | Les callbacks attachés aux propriétés `@Output` du composant et/ou aux propriétés d'événement de l'élément. |
| `providerTokens` | Les jetons de recherche de l'injector de ce composant. Comprend le composant lui-même ainsi que les jetons que le composant liste dans ses métadonnées `providers`. |
| `references` | Dictionnaire des objets associés aux variables locales du template $par exemple, `#foo`$, indexés par le nom de la variable locale. |

Les méthodes `DebugElement.query(predicate)` et `DebugElement.queryAll(predicate)` prennent un prédicat qui filtre le sous-arbre de l'élément source pour trouver les `DebugElement` correspondants.

Le prédicat est n'importe quelle méthode qui prend un `DebugElement` et renvoie une valeur _truthy_.
L'exemple suivant trouve tous les `DebugElements` ayant une référence à une variable locale de template nommée « content » :

```ts
// Filter for DebugElements with a #content reference
const contentRefs = el.queryAll((de) => de.references['content']);
```

La classe `By` d'Angular possède trois méthodes statiques pour les prédicats courants :

```ts
// Can find DebugElement either by css selector or by directive
const h2 = fixture.debugElement.query(By.css('h2'));
const directive = fixture.debugElement.query(By.directive(Highlight));
```
# Vue d'ensemble des harnais de composant

Un <strong>harnais de composant</strong> est une classe qui permet aux tests d'interagir avec les composants comme le ferait un utilisateur final, via une API prise en charge. Vous pouvez créer des harnais de test pour n'importe quel composant, du petit widget réutilisable à la page complète.

Les harnais offrent plusieurs avantages :

- Ils rendent les tests moins fragiles en les isolant des détails d'implémentation d'un composant, comme sa structure DOM
- Ils rendent les tests plus lisibles et plus faciles à maintenir
- Ils peuvent être utilisés dans plusieurs environnements de test

```ts
// Example of test with a harness for a component called MyButtonComponent
it('should load button with exact text', async () => {
  const button = await loader.getHarness(MyButtonComponentHarness);
  expect(await button.getText()).toBe('Confirm');
});
```

Les harnais de composant sont particulièrement utiles pour les widgets d'interface partagés. Les développeurs écrivent souvent des tests qui dépendent de détails d'implémentation privés des widgets, comme la structure DOM et les classes CSS. Ces dépendances rendent les tests fragiles et difficiles à maintenir. Les harnais offrent une alternative : une API prise en charge qui interagit avec le widget de la même manière qu'un utilisateur final. Les changements d'implémentation d'un widget risquent désormais moins de casser les tests des utilisateurs. Par exemple, [Angular Material](https://material.angular.dev/components/categories) fournit un harnais de test pour chaque composant de la library.

Les harnais de composant prennent en charge plusieurs environnements de test. Vous pouvez utiliser la même implémentation de harnais dans les tests unitaires comme dans les tests de bout en bout. Les auteurs de tests n'ont qu'une seule API à apprendre et les auteurs de composants n'ont pas à maintenir des implémentations distinctes pour les tests unitaires et de bout en bout.

De nombreux développeurs se rangent dans l'une des catégories suivantes : auteurs de tests, auteurs de harnais de composant et auteurs d'environnements de harnais. Utilisez le tableau ci-dessous pour trouver la section la plus pertinente de ce guide selon ces catégories :

| Type de développeur | Description | Section pertinente |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| Auteurs de tests | Développeurs qui utilisent des harnais de composant écrits par quelqu'un d'autre pour tester leur application. Par exemple, un développeur d'application qui utilise un composant de menu tiers et doit interagir avec ce menu dans un test unitaire. | [Utiliser des harnais de composant dans les tests](guide/testing/using-component-harnesses) |
| Auteurs de harnais de composant | Développeurs qui maintiennent des composants Angular réutilisables et veulent créer un harnais de test que leurs utilisateurs pourront utiliser dans leurs tests. Par exemple, l'auteur d'une library tierce de composants Angular ou un développeur qui maintient un ensemble de composants communs pour une grande application Angular. | [Créer des harnais de composant pour vos composants](guide/testing/creating-component-harnesses) |
| Auteurs d'environnements de harnais | Développeurs qui veulent permettre l'utilisation des harnais de composant dans d'autres environnements de test. Pour en savoir plus sur les environnements de test pris en charge nativement, consultez [environnements et loaders de harnais de test](guide/testing/using-component-harnesses#test-harness-environments-and-loaders). | [Ajouter la prise en charge d'autres environnements de test](guide/testing/component-harnesses-testing-environments) |

Pour la référence complète de l'API, consultez la [page de référence de l'API des harnais de composant du CDK Angular](/api#angular_cdk_testing).
# Utiliser des harnais de composant dans les tests

## Avant de commencer {#before-you-start}

TIP: Ce guide suppose que vous avez déjà lu la [vue d'ensemble des harnais de composant](guide/testing/component-harnesses-overview). Lisez-la d'abord si vous découvrez les harnais de composant.

### Installation du CDK {#cdk-installation}

Le [Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) est un ensemble de primitives de comportement pour construire des composants. Pour utiliser les harnais de composant, installez d'abord `@angular/cdk` depuis npm. Vous pouvez le faire depuis votre terminal avec l'Angular CLI :

```shell
ng add @angular/cdk
```

## Environnements et loaders de harnais de test {#test-harness-environments-and-loaders}

Vous pouvez utiliser les harnais de test de composant dans différents environnements de test. Le CDK Angular prend en charge deux environnements intégrés :

- Les tests unitaires avec le `TestBed` d'Angular
- Les tests de bout en bout avec [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver)

Chaque environnement fournit un <strong>loader de harnais</strong>. Le loader crée les instances de harnais que vous utilisez dans vos tests. Vous trouverez ci-dessous des indications plus précises sur les environnements de test pris en charge.

Les autres environnements de test nécessitent des bindings personnalisés. Consultez le guide [Prendre en charge les harnais dans d'autres environnements de test](guide/testing/component-harnesses-testing-environments) pour plus d'informations.

### Utiliser le loader de `TestbedHarnessEnvironment` pour les tests unitaires {#using-the-loader-from-testbedharnessenvironment-for-unit-tests}

Pour les tests unitaires, vous pouvez créer un loader de harnais à partir de [TestbedHarnessEnvironment](/api/cdk/testing/testbed/TestbedHarnessEnvironment). Cet environnement utilise une [fixture de composant](api/core/testing/ComponentFixture) créée par le `TestBed` d'Angular.

Pour créer un loader de harnais dont la racine est l'élément racine de la fixture, utilisez la méthode `loader()` :

```ts
const fixture = TestBed.createComponent(MyComponent);

// Create a harness loader from the fixture
const loader = TestbedHarnessEnvironment.loader(fixture);
...

// Use the loader to get harness instances
const myComponentHarness = await loader.getHarness(MyComponent);
```

Pour créer un loader de harnais destiné aux harnais d'éléments situés en dehors de la fixture, utilisez la méthode `documentRootLoader()`. Par exemple, le code qui affiche un élément flottant ou une pop-up attache souvent des éléments DOM directement au body du document, comme le service `Overlay` du CDK Angular.

Vous pouvez aussi créer directement un harnais pour l'élément racine de cette fixture avec `harnessForFixture()`.

### Utiliser le loader de `SeleniumWebDriverHarnessEnvironment` pour les tests de bout en bout {#using-the-loader-from-seleniumwebdriverharnessenvironment-for-end-to-end-tests}

Pour les tests de bout en bout basés sur WebDriver, vous pouvez créer un loader de harnais avec `SeleniumWebDriverHarnessEnvironment`.

Utilisez la méthode `loader()` pour obtenir l'instance du loader de harnais pour le document HTML actuel, dont la racine est l'élément racine du document. Cet environnement utilise un client WebDriver.

```ts
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```

## Utiliser un loader de harnais {#using-a-harness-loader}

Les instances de loader de harnais correspondent à un élément DOM précis et servent à créer des instances de harnais de composant pour les éléments situés sous cet élément.

Pour obtenir le `ComponentHarness` de la première instance de l'élément, utilisez la méthode `getHarness()`. Pour obtenir toutes les instances de `ComponentHarness`, utilisez la méthode `getAllHarnesses()`.

```ts
// Get harness for first instance of the element
const myComponentHarness = await loader.getHarness(MyComponent);

// Get harnesses for all instances of the element
const myComponentHarnesses = await loader.getAllHarnesses(MyComponent);
```

En plus de `getHarness` et `getAllHarnesses`, `HarnessLoader` propose plusieurs autres méthodes utiles pour rechercher des harnais :

- `getHarnessAtIndex(...)` : récupère le harnais d'un composant qui correspond aux critères donnés, à un index précis.
- `countHarnesses(...)` : compte le nombre d'instances de composant qui correspondent aux critères donnés.
- `hasHarness(...)` : vérifie si au moins une instance de composant correspond aux critères donnés.

Par exemple, considérez un composant réutilisable dialog-button qui ouvre une boîte de dialogue au clic. Il contient les composants suivants, chacun avec un harnais correspondant :

- `MyDialogButton` (compose `MyButton` et `MyDialog` avec une API pratique)
- `MyButton` (un composant bouton standard)
- `MyDialog` (une boîte de dialogue ajoutée à `document.body` par `MyDialogButton` lors du clic)

Le test suivant charge les harnais de chacun de ces composants :

```ts
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 () => {
  // Load a harness for the bootstrapped component with `harnessForFixture`
  dialogButtonHarness = await TestbedHarnessEnvironment.harnessForFixture(
    fixture,
    MyDialogButtonHarness,
  );

// The button element is inside the fixture's root element, so we use `loader`.
  const buttonHarness = await loader.getHarness(MyButtonHarness);

// Click the button to open the dialog
  await buttonHarness.click();

// The dialog is appended to `document.body`, outside of the fixture's root element,
  // so we use `rootLoader` in this case.
  const dialogHarness = await rootLoader.getHarness(MyDialogHarness);

// ... make some assertions
});
```

### Comportement des harnais selon les environnements {#harness-behavior-in-different-environments}

Les harnais peuvent ne pas se comporter exactement de la même manière dans tous les environnements. Certaines différences sont inévitables entre une véritable interaction utilisateur et les événements simulés générés dans les tests unitaires. Le CDK Angular fait de son mieux pour harmoniser le comportement autant que possible.

### Interagir avec les éléments enfants {#interacting-with-child-elements}

Pour interagir avec les éléments situés sous l'élément racine de ce loader de harnais, utilisez l'instance de `HarnessLoader` d'un élément enfant. Pour la première instance de l'élément enfant, utilisez la méthode `getChildLoader()`. Pour toutes les instances de l'élément enfant, utilisez la méthode `getAllChildLoaders()`.

```ts
const myComponentHarness = await loader.getHarness(MyComponent);

// Get loader for first instance of child element with '.child' selector
const childLoader = await loader.getChildLoader('.child');

// Get loaders for all instances of child elements with '.child' selector
const allChildLoaders = await loader.getAllChildLoaders('.child');
```

### Filtrer les harnais {#filtering-harnesses}

Quand une page contient plusieurs instances d'un composant donné, vous pouvez vouloir filtrer selon une propriété du composant pour obtenir une instance précise. Pour cela, vous pouvez utiliser un <strong>prédicat de harnais</strong>, une classe qui associe une classe `ComponentHarness` à des fonctions prédicats permettant de filtrer les instances de composant.

Quand vous demandez un harnais à un `HarnessLoader`, vous fournissez en réalité une HarnessQuery. Une query peut être l'une de ces deux choses :

- Un constructeur de harnais, qui récupère simplement ce harnais
- Un `HarnessPredicate`, qui récupère les harnais filtrés selon une ou plusieurs conditions

`HarnessPredicate` prend en charge quelques filtres de base (selector, ancêtre) qui fonctionnent sur tout ce qui étend `ComponentHarness`.

```ts
// Example of loading a MyButtonComponentHarness with a harness predicate
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {
  selector: '[disabled]',
});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```

Il est toutefois courant que les harnais implémentent une méthode statique `with()` qui accepte des options de filtrage propres au composant et renvoie un `HarnessPredicate`.

```ts
// Example of loading a MyButtonComponentHarness with a specific selector
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}));
```

Pour plus de détails, reportez-vous à la documentation du harnais concerné, car les options de filtrage supplémentaires sont propres à chaque implémentation de harnais.

## Utiliser les API des harnais de test {#using-test-harness-apis}

Bien que chaque harnais définisse une API propre au composant correspondant, ils partagent tous une classe de base commune, [ComponentHarness](/api/cdk/testing/ComponentHarness). Cette classe de base définit une propriété statique, `hostSelector`, qui associe la classe de harnais aux instances du composant dans le DOM.

Au-delà de cela, l'API d'un harnais donné est propre au composant correspondant ; reportez-vous à la documentation du composant pour savoir comment utiliser un harnais précis.

Par exemple, voici un test pour un composant qui utilise le [harnais du composant slider d'Angular Material](https://material.angular.dev/components/slider/api#MatSliderHarness) :

```ts
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);
});
```

## Interopérabilité avec la détection de changements d'Angular {#interop-with-angular-change-detection}

Par défaut, les harnais de test exécutent la [détection de changements](/best-practices/runtime-performance) d'Angular avant de lire l'état d'un élément DOM et après avoir interagi avec un élément DOM.

Vous pouvez parfois avoir besoin d'un contrôle plus fin de la détection de changements dans vos tests, par exemple pour vérifier l'état d'un composant pendant qu'une opération asynchrone est en cours. Dans ces cas, utilisez la fonction `manualChangeDetection` pour désactiver la gestion automatique de la détection de changements pour un bloc de code.

```ts
it('checks state while async action is in progress', async () => {
  const buttonHarness = await loader.getHarness(MyButtonHarness);
  await manualChangeDetection(async () => {
    await buttonHarness.click();
    fixture.detectChanges();
    // Check expectations while async click operation is in progress.
    expect(isProgressSpinnerVisible()).toBe(true);
    await fixture.whenStable();
    // Check expectations after async click operation complete.
    expect(isProgressSpinnerVisible()).toBe(false);
  });
});
```

Presque toutes les méthodes des harnais sont asynchrones et renvoient une `Promise` pour permettre :

- La prise en charge des tests unitaires
- La prise en charge des tests de bout en bout
- L'isolation des tests vis-à-vis des changements de comportement asynchrone

L'équipe Angular recommande d'utiliser [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) pour améliorer la lisibilité des tests. Appeler `await` bloque l'exécution de votre test jusqu'à ce que la `Promise` associée se résolve.

Il arrive que vous vouliez effectuer plusieurs actions simultanément et attendre qu'elles soient toutes terminées plutôt que d'effectuer chaque action l'une après l'autre. Par exemple, lire plusieurs propriétés d'un même composant. Dans ces situations, utilisez la fonction `parallel` pour paralléliser les opérations. La fonction parallel fonctionne de manière similaire à `Promise.all`, tout en optimisant les vérifications de détection de changements.

```ts
it('reads properties in parallel', async () => {
  const checkboxHarness = await loader.getHarness(MyCheckboxHarness);
  // Read the checked and intermediate properties simultaneously.
  const [checked, indeterminate] = await parallel(() => [
    checkboxHarness.isChecked(),
    checkboxHarness.isIndeterminate(),
  ]);
  expect(checked).toBe(false);
  expect(indeterminate).toBe(true);
});
```
# Créer des harnais pour vos composants

## Avant de commencer {#before-you-start}

TIP: Ce guide suppose que vous avez déjà lu la [vue d'ensemble des harnais de composant](guide/testing/component-harnesses-overview). Lisez-la d'abord si vous découvrez les harnais de composant.

### Quand est-il pertinent de créer un harnais de test ? {#when-does-creating-a-test-harness-make-sense}

L'équipe Angular recommande de créer des harnais de test de composant pour les composants partagés utilisés à de nombreux endroits et qui offrent une certaine interactivité. Cela concerne le plus souvent les libraries de widgets et les composants réutilisables similaires. Les harnais sont précieux dans ces cas, car ils fournissent aux consommateurs de ces composants partagés une API bien prise en charge pour interagir avec un composant. Les tests qui utilisent des harnais peuvent éviter de dépendre de détails d'implémentation peu fiables de ces composants partagés, comme la structure DOM et des event listeners spécifiques.

Pour les composants qui n'apparaissent qu'à un seul endroit, comme une page d'une application, les harnais apportent moins d'avantages. Dans ces situations, les tests d'un composant peuvent raisonnablement dépendre des détails d'implémentation de ce composant, puisque les tests et les composants sont mis à jour en même temps. Les harnais restent toutefois utiles si vous comptez utiliser le harnais à la fois dans des tests unitaires et de bout en bout.

### Installation du CDK {#cdk-installation}

```shell
ng add @angular/cdk
```

## Étendre `ComponentHarness` {#extending-componentharness}

La classe abstraite `ComponentHarness` est la classe de base de tous les harnais de composant. Pour créer un harnais de composant personnalisé, étendez `ComponentHarness` et implémentez la propriété statique `hostSelector`.

La propriété `hostSelector` identifie les éléments du DOM qui correspondent à cette sous-classe de harnais. Dans la plupart des cas, le `hostSelector` doit être identique au selector du `Component` ou de la `Directive` correspondant. Par exemple, considérez un simple composant popup :

```ts
@Component({
  selector: 'my-popup',
  template: `
    <button (click)="toggle()">{{ triggerText() }}</button>
    @if (isOpen()) {
      <div class="my-popup-content"><ng-content /></div>
    }
  `,
})
class MyPopup {
  triggerText = input('');

isOpen = signal(false);

toggle() {
    this.isOpen.update((value) => !value);
  }
}
```

Dans ce cas, un harnais minimal pour le composant ressemblerait à ceci :

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```

Bien que les sous-classes de `ComponentHarness` n'exigent que la propriété `hostSelector`, la plupart des harnais doivent aussi implémenter une méthode statique `with` pour générer des instances de `HarnessPredicate`. La [section sur le filtrage des harnais](guide/testing/using-component-harnesses#filtering-harnesses) aborde ce point plus en détail.

## Trouver des éléments dans le DOM du composant {#finding-elements-in-the-components-dom}

Chaque instance d'une sous-classe de `ComponentHarness` représente une instance particulière du composant correspondant. Vous pouvez accéder au host element du composant via la méthode `host() ` de la classe de base `ComponentHarness`.

`ComponentHarness` propose aussi plusieurs méthodes pour localiser des éléments dans le DOM du composant : `locatorFor()`, `locatorForOptional()` et `locatorForAll()`. Ces méthodes créent des fonctions qui trouvent des éléments, elles ne trouvent pas directement les éléments. Cette approche évite de mettre en cache des références à des éléments obsolètes. Par exemple, quand un bloc `@if` masque puis affiche un élément, le résultat est un nouvel élément DOM ; utiliser des fonctions garantit que les tests référencent toujours l'état actuel du DOM.

Consultez la [page de référence de l'API ComponentHarness](/api/cdk/testing/ComponentHarness) pour la liste détaillée complète des différentes méthodes `locatorFor`.

Par exemple, le `MyPopupHarness` présenté plus haut pourrait fournir des méthodes pour récupérer les éléments déclencheur et contenu comme suit :

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

// Gets the trigger element
  getTriggerElement = this.locatorFor('button');

// Gets the content element.
  getContentElement = this.locatorForOptional('.my-popup-content');
}
```

## Travailler avec des instances de `TestElement` {#working-with-testelement-instances}

`TestElement` est une abstraction conçue pour fonctionner dans différents environnements de test (tests unitaires, WebDriver, etc.). Quand vous utilisez des harnais, effectuez toutes les interactions avec le DOM via cette interface. Les autres moyens d'accéder aux éléments DOM, comme `document.querySelector()`, ne fonctionnent pas dans tous les environnements de test.

`TestElement` propose plusieurs méthodes pour interagir avec le DOM sous-jacent, comme `blur()`, `click()`, `getAttribute()`, et d'autres. Consultez la [page de référence de l'API TestElement](/api/cdk/testing/TestElement) pour la liste complète des méthodes.

N'exposez pas d'instances de `TestElement` aux utilisateurs du harnais, sauf s'il s'agit d'un élément que le consommateur du composant définit directement, comme le host element du composant. Exposer des instances de `TestElement` pour des éléments internes conduit les utilisateurs à dépendre de la structure DOM interne d'un composant.

Fournissez plutôt des méthodes plus ciblées pour les actions précises que l'utilisateur final peut effectuer ou les états particuliers qu'il peut observer. Par exemple, le `MyPopupHarness` des sections précédentes pourrait fournir des méthodes comme `toggle` et `isOpen` :

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

protected getTriggerElement = this.locatorFor('button');
  protected getContentElement = this.locatorForOptional('.my-popup-content');

/** Toggles the open state of the popup. */
  async toggle() {
    const trigger = await this.getTriggerElement();
    return trigger.click();
  }

/** Checks if the popup us open. */
  async isOpen() {
    const content = await this.getContentElement();
    return !!content;
  }
}
```

## Charger des harnais pour les sous-composants {#loading-harnesses-for-subcomponents}

Les composants plus grands composent souvent des sous-composants. Vous pouvez aussi refléter cette structure dans le harnais d'un composant. Chacune des méthodes `locatorFor` de `ComponentHarness` possède une signature alternative qui permet de localiser des sous-harnais plutôt que des éléments.

Consultez la [page de référence de l'API ComponentHarness](/api/cdk/testing/ComponentHarness) pour la liste complète des différentes méthodes locatorFor.

Par exemple, considérez un menu construit à partir de la popup ci-dessus :

```ts
@Directive({
  selector: 'my-menu-item',
})
class MyMenuItem {}

@Component({
  selector: 'my-menu',
  template: `
    <my-popup>
      <ng-content />
    </my-popup>
  `,
})
class MyMenu {
  triggerText = input('');

items = contentChildren(MyMenuItem);
}
```

Le harnais de `MyMenu` peut alors tirer parti d'autres harnais pour `MyPopup` et `MyMenuItem` :

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/** Gets the currently shown menu items (empty list if menu is closed). */
  getItems = this.locatorForAll(MyMenuItemHarness);

/** Toggles open state of the menu. */
  async toggle() {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.toggle();
  }
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';
}
```

## Filtrer les instances de harnais avec `HarnessPredicate` {#filtering-harness-instances-with-harnesspredicate}

Quand une page contient plusieurs instances d'un composant donné, vous pouvez vouloir filtrer selon une propriété du composant pour obtenir une instance précise. Par exemple, vous pouvez vouloir un bouton avec un texte précis, ou un menu avec un ID précis. La classe `HarnessPredicate` peut capturer ce type de critères pour une sous-classe de `ComponentHarness`. Même si l'auteur du test peut construire des instances de `HarnessPredicate` manuellement, c'est plus simple quand la sous-classe de `ComponentHarness` fournit une méthode utilitaire pour construire des prédicats pour les filtres courants.

Créez une méthode statique `with()` sur chaque sous-classe de `ComponentHarness`, qui renvoie un `HarnessPredicate` pour cette classe. Cela permet aux auteurs de tests d'écrire du code facile à comprendre, par exemple `loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`. En plus des options standard selector et ancestor, la méthode `with` doit ajouter toutes les autres options pertinentes pour la sous-classe concernée.

Les harnais qui ont besoin d'options supplémentaires doivent étendre l'interface `BaseHarnessFilters` et ajouter les propriétés optionnelles nécessaires. `HarnessPredicate` fournit plusieurs méthodes pratiques pour ajouter des options : `stringMatches()`, `addOption()` et `add()`. Consultez la [page de l'API HarnessPredicate](/api/cdk/testing/HarnessPredicate) pour la description complète.

Par exemple, avec un menu, il est utile de filtrer selon le texte du déclencheur et de filtrer les éléments de menu selon leur texte :

```ts
interface MyMenuHarnessFilters extends BaseHarnessFilters {
  /** Filters based on the trigger text for the menu. */
  triggerText?: string | RegExp;
}

interface MyMenuItemHarnessFilters extends BaseHarnessFilters {
  /** Filters based on the text of the menu item. */
  text?: string | RegExp;
}

class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** Creates a `HarnessPredicate` used to locate a particular `MyMenuHarness`. */
  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);

/** Gets the text of the menu trigger. */
  async getTriggerText(): Promise<string> {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.getTriggerText();
  }
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';

/** Creates a `HarnessPredicate` used to locate a particular `MyMenuItemHarness`. */
  static with(options: MyMenuItemHarnessFilters): HarnessPredicate<MyMenuItemHarness> {
    return new HarnessPredicate(MyMenuItemHarness, options).addOption(
      'text',
      options.text,
      (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text),
    );
  }

/** Gets the text of the menu item. */
  async getText(): Promise<string> {
    const host = await this.host();
    return host.text();
  }
}
```

Vous pouvez passer un `HarnessPredicate` au lieu d'une classe `ComponentHarness` à n'importe quelle API de `HarnessLoader`, `LocatorFactory` ou `ComponentHarness`. Cela permet aux auteurs de tests de cibler facilement une instance de composant précise lors de la création d'une instance de harnais. Cela permet aussi à l'auteur du harnais de réutiliser le même `HarnessPredicate` pour proposer des API plus puissantes sur sa classe de harnais. Par exemple, considérez la méthode `getItems` du `MyMenuHarness` présenté ci-dessus. Ajouter une API de filtrage permet aux utilisateurs du harnais de rechercher des éléments de menu précis :

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** Gets a list of items in the menu, optionally filtered based on the given criteria. */
  async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> {
    const getFilteredItems = this.locatorForAll(MyMenuItemHarness.with(filters));
    return getFilteredItems();
  }
  ...
}
```

## Créer un `HarnessLoader` pour les éléments qui utilisent la projection de contenu {#creating-harnessloader-for-elements-that-use-content-projection}

Certains composants projettent du contenu supplémentaire dans le template du composant. Consultez le [guide de la projection de contenu](guide/components/content-projection) pour plus d'informations.

Ajoutez une instance de `HarnessLoader` limitée à l'élément contenant le `<ng-content>` quand vous créez un harnais pour un composant qui utilise la projection de contenu. Cela permet à l'utilisateur du harnais de charger des harnais supplémentaires pour les composants passés en contenu. `ComponentHarness` propose plusieurs méthodes pour créer des instances de HarnessLoader dans ce genre de cas : `harnessLoaderFor()`, `harnessLoaderForOptional()`, `harnessLoaderForAll()`. Consultez la [page de référence de l'API de l'interface HarnessLoader](/api/cdk/testing/HarnessLoader) pour plus de détails.

Par exemple, le `MyPopupHarness` présenté plus haut peut étendre `ContentContainerComponentHarness` pour permettre de charger des harnais dans le `<ng-content>` du composant.

```ts
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```

## Accéder aux éléments en dehors du host element du composant {#accessing-elements-outside-of-the-components-host-element}

Il arrive qu'un harnais de composant doive accéder à des éléments situés en dehors du host element du composant correspondant. Par exemple, le code qui affiche un élément flottant ou une pop-up attache souvent des éléments DOM directement au body du document, comme le service `Overlay` du CDK Angular.

Dans ce cas, `ComponentHarness` fournit une méthode permettant d'obtenir une `LocatorFactory` pour l'élément racine du document. La `LocatorFactory` prend en charge la plupart des API de la classe de base `ComponentHarness` et peut ensuite servir à effectuer des recherches relatives à l'élément racine du document.

Supposons que le composant `MyPopup` ci-dessus utilise l'overlay du CDK pour le contenu de la popup, plutôt qu'un élément de son propre template. Dans ce cas, `MyPopupHarness` devrait accéder à l'élément de contenu via la méthode `documentRootLocatorFactory()`, qui récupère une locator factory dont la racine est la racine du document.

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

/** Gets a `HarnessLoader` whose root element is the popup's content element. */
  async getHarnessLoaderForContent(): Promise<HarnessLoader> {
    const rootLocator = this.documentRootLocatorFactory();
    return rootLocator.harnessLoaderFor('my-popup-content');
  }
}
```

## Attendre les tâches asynchrones {#waiting-for-asynchronous-tasks}

Les méthodes de `TestElement` déclenchent automatiquement la détection de changements d'Angular et attendent les tâches dans la `NgZone`. Dans la plupart des cas, les auteurs de harnais n'ont rien de particulier à faire pour attendre les tâches asynchrones. Il existe toutefois quelques cas limites où cela peut ne pas suffire.

Dans certaines circonstances, les animations Angular peuvent nécessiter un second cycle de détection de changements, suivi d'une stabilisation de la `NgZone`, avant que les événements d'animation soient entièrement traités. Quand c'est nécessaire, `ComponentHarness` propose une méthode `forceStabilize()` que vous pouvez appeler pour effectuer ce second passage.

Vous pouvez utiliser `NgZone.runOutsideAngular()` pour planifier des tâches en dehors de NgZone. Appelez la méthode `waitForTasksOutsideAngular()` du harnais correspondant si vous devez attendre explicitement les tâches en dehors de `NgZone`, car cela ne se fait pas automatiquement.
# Animer vos applications avec `animate.enter` et `animate.leave`

Des animations bien conçues peuvent rendre votre application plus intuitive et plus attrayante, mais elles ne sont pas que cosmétiques.
Les animations peuvent améliorer votre application et l'expérience utilisateur de plusieurs façons :

- Sans animations, les transitions entre pages web peuvent paraître abruptes et brutales
- Le mouvement améliore grandement l'expérience utilisateur : les animations permettent aux utilisateurs de percevoir la réponse de l'application à leurs actions
- De bonnes animations peuvent guider en douceur l'attention de l'utilisateur tout au long d'un parcours

Angular fournit `animate.enter` et `animate.leave` pour animer les éléments de votre application. Ces deux fonctionnalités appliquent des classes CSS d'entrée et de sortie au bon moment, ou appellent des fonctions pour appliquer des animations issues de libraries tierces. `animate.enter` et `animate.leave` ne sont pas des directives. Ce sont des API spéciales prises en charge directement par le compilateur Angular. Elles peuvent être utilisées directement sur des éléments, et aussi en tant que host binding.

## `animate.enter` {#animateenter}

Vous pouvez utiliser `animate.enter` pour animer des éléments lorsqu'ils _entrent_ dans le DOM. Vous pouvez définir des animations d'entrée avec des classes CSS utilisant des transitions ou des animations 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>

Quand l'animation se termine, Angular retire du DOM la ou les classes que vous avez indiquées dans `animate.enter`. Les classes d'animation ne sont présentes que pendant que l'animation est active.

NOTE: Quand vous utilisez plusieurs animations keyframes ou propriétés de transition sur un élément, Angular ne retire toutes les classes qu'_après_ la fin de l'animation la plus longue.

Vous pouvez utiliser `animate.enter` avec toutes les autres fonctionnalités d'Angular, comme le control flow ou les expressions dynamiques. `animate.enter` accepte soit une chaîne de classes unique (plusieurs classes séparées par des espaces), soit un tableau de chaînes de classes.

Une remarque rapide sur l'utilisation des transitions CSS : si vous choisissez d'utiliser des transitions plutôt que des animations keyframes, les classes ajoutées à l'élément avec `animate.enter` représentent l'état _vers_ lequel la transition anime. Le CSS de base de votre élément correspond à son apparence quand aucune animation n'est en cours, ce qui est probablement proche de l'état final de la transition CSS. Vous devez donc tout de même l'associer à `@starting-style` pour disposer d'un état _de départ_ approprié afin que votre transition fonctionne.

<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` {#animateleave}

Vous pouvez utiliser `animate.leave` pour animer des éléments lorsqu'ils _quittent_ le DOM. Vous pouvez définir des animations de sortie avec des classes CSS utilisant des transformations ou des animations 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>

Quand l'animation se termine, Angular retire automatiquement l'élément animé du DOM.

NOTE: Quand vous utilisez plusieurs animations keyframes ou propriétés de transition sur un élément, Angular attend la fin de la plus longue de ces animations avant de retirer l'élément.

`animate.leave` peut aussi être utilisé avec des signals et d'autres bindings. Vous pouvez utiliser `animate.leave` avec une seule classe ou plusieurs classes. Indiquez-les soit sous forme de chaîne simple séparée par des espaces, soit sous forme de tableau de chaînes.

<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>

### Ordre de retrait des éléments {#element-removal-order}

L'exécution des animations `animate.leave` et le moment où une animation se produit comportent quelques subtilités. `animate.leave` fonctionne s'il est placé sur l'élément en cours de retrait ; et si `animate.leave` est placé sur un élément _descendant_ de l'élément en cours de retrait _au sein du template d'un même composant_, ces animations `animate.leave` enfants se produisent _avant_ que le nœud parent ne soit retiré du DOM. Vous pouvez ainsi animer la disparition des éléments enfants en toute confiance, sans que le nœud parent ne disparaisse prématurément.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts">
    <docs-code header="leave-parent.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts" />
    <docs-code header="leave-parent.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.html" />
    <docs-code header="leave-parent.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.css"/>
</docs-code-multifile>

IMPORTANT: Les animations enfants ne se déclenchent que pour les éléments situés dans le template d'un même composant. Si un élément en cours de retrait contient des composants enfants, les animations `animate.leave` définies dans les templates de ces composants enfants ne s'exécuteront **pas** avant le retrait du parent. Pour animer un composant enfant lors de son retrait, appliquez plutôt `animate.leave` directement sur le host element du composant enfant dans le template parent, ou gérez par programmation le déclenchement de l'animation dans le composant enfant et retardez le retrait du parent jusqu'à la fin de cette animation.

## Event bindings, fonctions et libraries tierces {#event-bindings-functions-and-third-party-libraries}

`animate.enter` et `animate.leave` prennent tous deux en charge la syntaxe d'event binding, qui permet des appels de fonction. Vous pouvez utiliser cette syntaxe pour appeler une fonction dans le code de votre composant ou utiliser des libraries d'animation tierces, comme [GSAP](https://gsap.com/), [anime.js](https://animejs.com/) ou toute autre library d'animation 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>

L'objet `$event` est de type `AnimationCallbackEvent`. Il contient l'élément en tant que `target` et fournit une fonction `animationComplete()` pour notifier le framework quand l'animation se termine.

IMPORTANT: Vous **devez** appeler la fonction `animationComplete()` quand vous utilisez `animate.leave` pour qu'Angular retire l'élément.

Si vous n'appelez pas `animationComplete()` quand vous utilisez `animate.leave`, Angular appelle automatiquement la fonction après un délai de quatre secondes. Vous pouvez configurer la durée de ce délai en fournissant le jeton `MAX_ANIMATION_TIMEOUT` en millisecondes.

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```

## Compatibilité avec les anciennes animations Angular {#compatibility-with-legacy-angular-animations}

Vous ne pouvez pas utiliser les anciennes animations en même temps que `animate.enter` et `animate.leave` dans un même composant. Cela entraînerait des classes d'entrée qui restent sur l'élément ou des nœuds sortants qui ne sont pas retirés. En dehors de ce cas, vous pouvez tout à fait utiliser à la fois les anciennes animations et les nouvelles animations `animate.enter` et `animate.leave` dans une même _application_. La seule réserve concerne la projection de contenu. Si vous projetez du contenu d'un composant utilisant les anciennes animations dans un autre composant utilisant `animate.enter` ou `animate.leave`, ou inversement, le comportement sera le même que s'ils étaient utilisés ensemble dans le même composant. Ce cas n'est pas pris en charge.

## Tests {#testing}

TestBed fournit une prise en charge intégrée pour activer ou désactiver les animations dans votre environnement de test. Les animations CSS nécessitent un navigateur pour s'exécuter, et beaucoup de leurs API ne sont pas disponibles dans un environnement de test. Par défaut, TestBed désactive les animations pour vous dans vos environnements de test.

Si vous voulez vérifier que les animations s'exécutent bien dans un test en navigateur, par exemple un test de bout en bout, vous pouvez configurer TestBed pour activer les animations en indiquant `animationsEnabled: true` dans votre configuration de test.

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

Les animations de votre environnement de test se comporteront alors normalement.

NOTE: Certains environnements de test n'émettent pas les événements d'animation comme `animationstart`, `animationend` et leurs équivalents pour les transitions.

## En savoir plus sur les animations Angular {#more-on-angular-animations}

Ceci pourrait aussi vous intéresser :
# Animer votre application avec CSS

CSS offre un ensemble d'outils robustes pour créer des animations élégantes et attrayantes dans votre application.

## Comment écrire des animations en CSS natif {#how-to-write-animations-in-native-css}

Si vous n'avez jamais écrit d'animations CSS natives, il existe de nombreux excellents guides pour bien démarrer. En voici quelques-uns :
[Guide des animations CSS de MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)
[Guide des animations CSS3 de W3Schools](https://www.w3schools.com/css/css3_animations.asp)
[Le tutoriel complet sur les animations CSS](https://www.lambdatest.com/blog/css-animations-tutorial/)
[Les animations CSS pour les débutants](https://thoughtbot.com/blog/css-animation-for-beginners)

ainsi que quelques vidéos :
[Apprendre les animations CSS en 9 minutes](https://www.youtube.com/watch?v=z2LQYsZhsFw)
[Playlist de tutoriels sur les animations CSS de Net Ninja](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

Consultez certains de ces guides et tutoriels, puis revenez à ce guide.

## Créer des animations réutilisables {#creating-reusable-animations}

Vous pouvez créer des animations réutilisables, partagées dans toute votre application, avec `@keyframes`. Définissez des animations keyframes dans un fichier CSS partagé, et vous pourrez réutiliser ces animations keyframes où vous le souhaitez dans votre application.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

Ajouter la classe `animated-class` à un élément déclenche l'animation sur cet élément.

## Animer une transition {#animating-a-transition}

### Animer des états et des styles {#animating-state-and-styles}

Vous pouvez vouloir animer le passage entre deux états différents, par exemple quand un élément est ouvert ou fermé. Vous pouvez y parvenir avec des classes CSS, soit avec une animation keyframes, soit avec un style de transition.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

Pour déclencher l'état `open` ou `closed`, il suffit de basculer des classes sur l'élément dans votre composant. Vous trouverez des exemples dans notre [guide des templates](guide/templates/binding#css-class-and-style-property-bindings).

Vous trouverez des exemples similaires dans le guide des templates pour [animer directement des styles](guide/templates/binding#css-style-properties).

### Transitions, timing et easing {#transitions-timing-and-easing}

Animer nécessite souvent d'ajuster le timing, les délais et le comportement d'easing. Vous pouvez le faire avec plusieurs propriétés CSS ou propriétés raccourcies.

Spécifiez `animation-duration`, `animation-delay` et `animation-timing-function` pour une animation keyframes en CSS, ou utilisez plutôt la propriété raccourcie `animation`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

De même, vous pouvez utiliser `transition-duration`, `transition-delay` et `transition-timing-function`, ainsi que le raccourci `transition`, pour les animations qui n'utilisent pas `@keyframes`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### Déclencher une animation {#triggering-an-animation}

Les animations peuvent être déclenchées en basculant des styles ou des classes CSS. Dès qu'une classe est présente sur un élément, l'animation se produit. Retirer la classe ramène l'élément au CSS défini pour lui. Voici un exemple :

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.ts">
    <docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.ts" />
    <docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.html" />
    <docs-code header="open-close.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.css"/>
</docs-code-multifile>

## Transition et déclencheurs {#transition-and-triggers}

### Animer une hauteur auto {#animating-auto-height}

Vous pouvez utiliser CSS Grid pour animer vers une hauteur auto.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts">
    <docs-code header="auto-height.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts" />
    <docs-code header="auto-height.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.html" />
    <docs-code header="auto-height.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.css"  />
</docs-code-multifile>

Si vous n'avez pas à vous soucier de la prise en charge de tous les navigateurs, vous pouvez aussi regarder `calc-size()`, qui est la véritable solution pour animer une hauteur auto. Consultez [la documentation de MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) et [ce tutoriel](https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/) pour plus d'informations.

### Animer l'entrée et la sortie d'une vue {#animate-entering-and-leaving-a-view}

Vous pouvez créer des animations pour le moment où un élément entre dans une vue ou en sort. Commençons par voir comment animer un élément qui entre dans une vue. Nous allons utiliser `animate.enter`, qui applique des classes d'animation quand un élément entre dans la vue.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.ts">
    <docs-code header="insert.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.ts" />
    <docs-code header="insert.html" path="adev/src/content/examples/animations/src/app/native-css/insert.html" />
    <docs-code header="insert.css" path="adev/src/content/examples/animations/src/app/native-css/insert.css"  />
</docs-code-multifile>

Animer un élément quand il quitte la vue ressemble à l'animation de son entrée dans la vue. Utilisez `animate.leave` pour indiquer quelles classes CSS appliquer quand l'élément quitte la vue.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.ts">
    <docs-code header="remove.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.ts" />
    <docs-code header="remove.html" path="adev/src/content/examples/animations/src/app/native-css/remove.html" />
    <docs-code header="remove.css" path="adev/src/content/examples/animations/src/app/native-css/remove.css"  />
</docs-code-multifile>

NOTE: Les animations `animate.leave` des enfants ne se déclenchent qu'au sein du template d'un même composant. Les animations `animate.leave` des composants imbriqués ne se déclenchent pas quand un élément parent est retiré.

Pour plus d'informations sur `animate.enter` et `animate.leave`, consultez le [guide des animations d'entrée et de sortie](guide/animations).

### Animer une incrémentation et une décrémentation {#animating-increment-and-decrement}

Animer lors d'une incrémentation ou d'une décrémentation est un pattern courant dans les applications. Voici un exemple de la façon d'obtenir ce comportement.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts">
    <docs-code header="increment-decrement.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts" />
    <docs-code header="increment-decrement.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.html" />
    <docs-code header="increment-decrement.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.css" />
</docs-code-multifile>

### Désactiver une animation ou toutes les animations {#disabling-an-animation-or-all-animations}

Si vous souhaitez désactiver les animations que vous avez définies, plusieurs options s'offrent à vous.

1. Créez une classe personnalisée qui force animation et transition à `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

Appliquer cette classe à un élément empêche toute animation de se déclencher sur cet élément. Vous pouvez aussi l'appliquer à tout votre DOM ou à une section de votre DOM pour imposer ce comportement. Cependant, cela empêche les événements d'animation de se déclencher. Si vous attendez des événements d'animation pour retirer un élément, cette solution ne fonctionnera pas. Une solution de contournement consiste à définir plutôt des durées de 1 milliseconde.

2. Utilisez la media query [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) pour qu'aucune animation ne soit jouée pour les utilisateurs qui préfèrent moins d'animations.

3. Évitez d'ajouter des classes d'animation par programmation

### Callbacks d'animation {#animation-callbacks}

Si vous souhaitez exécuter des actions à certains moments d'une animation, vous pouvez écouter un certain nombre d'événements. En voici quelques-uns.

[`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/animationiteration_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 Web Animations API offre de nombreuses fonctionnalités supplémentaires. [Consultez la documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) pour voir toutes les API d'animation disponibles.

NOTE: Faites attention aux problèmes de propagation (bubbling) avec ces callbacks. Si vous animez des enfants et des parents, les événements remontent des enfants vers les parents. Envisagez d'arrêter la propagation ou d'examiner plus en détail l'événement pour déterminer si vous répondez bien à la cible d'événement voulue plutôt qu'à un événement remonté depuis un nœud enfant. Vous pouvez examiner la propriété `animationname` ou les propriétés en cours de transition pour vérifier que vous ciblez les bons nœuds.

## Séquences complexes {#complex-sequences}

Les animations sont souvent plus compliquées qu'un simple fondu en entrée ou en sortie. Vous pouvez avoir de nombreuses séquences d'animations complexes à exécuter. Examinons quelques-uns de ces scénarios possibles.

### Échelonner les animations dans une liste {#staggering-animations-in-a-list}

Un effet courant consiste à échelonner les animations de chaque élément d'une liste pour créer un effet de cascade. Vous pouvez y parvenir avec `animation-delay` ou `transition-delay`. Voici un exemple de ce à quoi ce CSS pourrait ressembler.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.ts">
    <docs-code header="stagger.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.ts" />
    <docs-code header="stagger.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.html" />
    <docs-code header="stagger.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.css" />
</docs-code-multifile>

### Animations parallèles {#parallel-animations}

Vous pouvez appliquer plusieurs animations à un élément en même temps avec la propriété raccourcie `animation`. Chacune peut avoir ses propres durées et délais. Cela vous permet de composer des animations et de créer des effets complexes.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

Dans cet exemple, les animations `rotate` et `fade-in` se déclenchent en même temps, mais ont des durées différentes.

### Animer les éléments d'une liste réordonnée {#animating-the-items-of-a-reordering-list}

Les éléments d'une boucle `@for` sont retirés puis rajoutés, ce qui déclenche les animations utilisant `@starting-styles` pour les animations d'entrée. Vous pouvez aussi utiliser `animate.enter` pour obtenir le même comportement. Utilisez `animate.leave` pour animer les éléments lorsqu'ils sont retirés, comme dans l'exemple ci-dessous.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.ts">
    <docs-code header="reorder.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.ts" />
    <docs-code header="reorder.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.html" />
    <docs-code header="reorder.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.css" />
</docs-code-multifile>

## Contrôle des animations par programmation {#programmatic-control-of-animations}

Vous pouvez récupérer directement les animations d'un élément avec [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations). Cette méthode renvoie un tableau de toutes les [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) de cet élément. Vous pouvez utiliser l'API `Animation` pour faire bien plus que ce que permettait l'`AnimationPlayer` du package animations. Vous pouvez ensuite appeler `cancel()`, `play()`, `pause()`, `reverse()` et bien d'autres. Cette API native devrait vous fournir tout ce dont vous avez besoin pour contrôler vos animations.

## En savoir plus sur les animations Angular {#more-on-angular-animations}

Ceci pourrait aussi vous intéresser :
# Animations de transition de route

Les animations de transition de route améliorent l'expérience utilisateur en offrant des transitions visuelles fluides lors de la navigation entre les différentes vues de votre application Angular. Le [router Angular](/guide/routing) prend en charge nativement l'API View Transitions du navigateur, ce qui permet des animations fluides entre les changements de route dans les navigateurs compatibles.

HELPFUL: L'intégration native des View Transitions dans le router est actuellement en [developer preview](/reference/releases#developer-preview). Les View Transitions natives sont une fonctionnalité de navigateur relativement récente, dont la prise en charge reste limitée selon les navigateurs.

## Fonctionnement des view transitions {#how-view-transitions-work}

Les view transitions utilisent l'[API native `document.startViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) du navigateur pour créer des animations fluides entre les différents états de votre application. L'API fonctionne ainsi :

1. **Capture de l'état courant** - Le navigateur prend une capture d'écran de la page courante
2. **Exécution de la mise à jour du DOM** - Votre fonction de callback s'exécute pour mettre à jour le DOM
3. **Capture du nouvel état** - Le navigateur capture l'état mis à jour de la page
4. **Lecture de la transition** - Le navigateur anime le passage de l'ancien état au nouveau

Voici la structure de base de l'API `startViewTransition` :

```ts
document.startViewTransition(async () => {
  await updateTheDOMSomehow();
});
```

Pour plus de détails sur l'API du navigateur, consultez l'[explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions).

## Comment le router utilise les view transitions {#how-the-router-uses-view-transitions}

Le router Angular intègre les view transitions au cycle de vie de la navigation pour créer des changements de route fluides. Pendant la navigation, le router :

1. **Termine la préparation de la navigation** - La correspondance des routes, le [lazy loading](guide/routing/loading-strategies#lazily-loaded-components-and-routes), les [guards](/guide/routing/route-guards), les [resources](/guide/routing/data-fetching-with-resources) et les [resolvers](/guide/routing/data-resolvers) s'exécutent
2. **Lance la view transition** - Le router appelle `startViewTransition` quand les routes sont prêtes à être activées
3. **Met à jour le DOM** - Le router active les nouvelles routes et désactive les anciennes dans le callback de la transition
4. **Finalise la transition** - La promise de la transition se résout quand Angular a terminé le rendu

L'intégration des view transitions dans le router agit comme une [amélioration progressive](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). Quand les navigateurs ne prennent pas en charge l'API View Transitions, le router effectue des mises à jour normales du DOM sans animation, ce qui garantit que votre application fonctionne dans tous les navigateurs.

## Activer les view transitions dans le router {#enabling-view-transitions-in-the-router}

Activez les view transitions en ajoutant la fonctionnalité `withViewTransitions` à la [configuration de votre router](/guide/routing/define-routes#adding-the-router-to-your-application). Angular prend en charge les deux approches de bootstrap, standalone et NgModule :

### Bootstrap standalone {#standalone-bootstrap}

```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 avec NgModule {#ngmodule-bootstrap}

```ts
import {NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})],
})
export class AppRouting {}
```

[Essayez l'exemple « count » sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

Cet exemple montre comment la navigation du router peut remplacer les appels directs à `startViewTransition` pour les mises à jour du compteur.

## Personnaliser les transitions avec CSS {#customizing-transitions-with-css}

Vous pouvez personnaliser les view transitions avec CSS pour créer des effets d'animation uniques. Le navigateur crée des éléments de transition distincts que vous pouvez cibler avec des sélecteurs CSS.

Pour créer des transitions personnalisées :

1. **Ajoutez view-transition-name** - Attribuez des noms uniques aux éléments que vous voulez animer
2. **Définissez des animations globales** - Créez des animations CSS dans vos styles globaux
3. **Ciblez les pseudo-éléments de transition** - Utilisez les sélecteurs `::view-transition-old()` et `::view-transition-new()`

Voici un exemple qui ajoute un effet de rotation à un élément compteur :

```css
/* Define keyframe animations */
@keyframes rotate-out {
  to {
    transform: rotate(90deg);
  }
}

@keyframes rotate-in {
  from {
    transform: rotate(-90deg);
  }
}

/* Target view transition pseudo-elements */
::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;
}
```

IMPORTANT: Définissez les animations de view transition dans votre fichier de styles globaux, pas dans les styles des composants. L'[encapsulation des vues](/guide/components/styling#style-scoping) d'Angular limite la portée des styles de composant, ce qui les empêche de cibler correctement les pseudo-éléments de transition.

[Essayez l'exemple « count » mis à jour sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)

## Contrôle avancé des transitions avec onViewTransitionCreated {#advanced-transition-control-with-onviewtransitioncreated}

La fonctionnalité `withViewTransitions` accepte un objet d'options avec un callback `onViewTransitionCreated` pour un contrôle avancé des view transitions. Ce callback :

- S'exécute dans un [contexte d'injection](/guide/di/dependency-injection-context#run-within-an-injection-context)
- Reçoit un objet [`ViewTransitionInfo`](/api/router/ViewTransitionInfo) contenant :
  - L'instance de `ViewTransition` issue de `startViewTransition`
  - L'[`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) de la route que l'on quitte
  - L'[`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) de la route vers laquelle on navigue

Utilisez ce callback pour personnaliser le comportement de la transition selon le contexte de navigation. Par exemple, vous pouvez ignorer les transitions pour certains types de navigation :

```ts
import {inject} from '@angular/core';
import {Router, withViewTransitions, isActive, IsActiveMatchOptions} from '@angular/router';

withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    const router = inject(Router);
    const targetUrl = router.currentNavigation()!.finalUrl!;

// Skip transition if only fragment or query params change
    const config: Partial<IsActiveMatchOptions> = {
      paths: 'exact',
      matrixParams: 'exact',
      fragment: 'ignored',
      queryParams: 'ignored',
    };

const isTargetRouteCurrent = isActive(targetUrl, router, config);

if (isTargetRouteCurrent()) {
      transition.skipTransition();
    }
  },
});
```

Cet exemple ignore la view transition quand la navigation ne modifie que le [fragment de l'URL ou les query parameters](/guide/routing/read-route-state#query-parameters) (comme les liens d'ancre au sein d'une même page). La méthode `skipTransition()` empêche l'animation tout en laissant la navigation se terminer.

## Respecter les préférences de mouvement de l'utilisateur {#respecting-the-users-motion-preferences}

Le router exécute les view transitions quel que soit le réglage [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) de l'utilisateur. Une préférence pour un mouvement réduit ne signifie pas forcément que l'utilisateur ne veut aucun mouvement, le framework laisse donc le choix à l'application : vous pouvez [fournir des animations plus discrètes](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#react_to_the_reduced_motion_preference) à ces utilisateurs, ou ignorer entièrement la transition avec le callback `onViewTransitionCreated` :

```ts
withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
      transition.skipTransition();
    }
  },
});
```

## Exemples de l'explainer de Chrome adaptés à Angular {#examples-from-the-chrome-explainer-adapted-to-angular}

Les exemples suivants illustrent différentes techniques de view transition, adaptées de la documentation de l'équipe Chrome pour être utilisées avec le router Angular :

### Les éléments en transition n'ont pas besoin d'être le même élément du DOM {#transitioning-elements-dont-need-to-be-the-same-dom-element}

Les éléments peuvent passer en douceur d'un élément du DOM à un autre tant qu'ils partagent le même `view-transition-name`.

- [Explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning_elements_dont_need_to_be_the_same_dom_element)
- [Exemple Angular sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-dh8npr?file=src%2Fmain.ts)

### Animations d'entrée et de sortie personnalisées {#custom-entry-and-exit-animations}

Créez des animations uniques pour les éléments qui entrent dans le viewport ou en sortent pendant les transitions de route.

- [Explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#custom_entry_and_exit_transitions)
- [Exemple Angular sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-8kly3o)

### Mises à jour asynchrones du DOM et attente du contenu {#async-dom-updates-and-waiting-for-content}

Le router Angular privilégie les transitions immédiates plutôt que l'attente du chargement de contenu supplémentaire.

- [Explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

NOTE: Le router Angular ne fournit aucun moyen de retarder les view transitions. Ce choix de conception évite que les pages deviennent non interactives pendant l'attente de contenu supplémentaire. Comme le souligne la documentation de Chrome : « Pendant ce temps, la page est figée, les délais doivent donc être réduits au minimum… dans certains cas, il vaut mieux éviter complètement le délai et utiliser le contenu dont vous disposez déjà. »

### Gérer plusieurs styles de view transition avec les types de view transition {#handle-multiple-view-transition-styles-with-view-transition-types}

Utilisez les types de view transition pour appliquer différents styles d'animation selon le contexte de navigation.

- [Explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types)
- [Exemple Angular sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-vxzcam)

### Gérer plusieurs styles de view transition avec un nom de classe sur la racine de la view transition (obsolète) {#handle-multiple-view-transition-styles-with-a-class-name-on-the-view-transition-root-deprecated}

Cette approche utilise des classes CSS sur l'élément racine de la transition pour contrôler les styles d'animation.

- [Explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [Exemple Angular sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)

### Effectuer une transition sans figer les autres animations {#transitioning-without-freezing-other-animations}

Conservez les autres animations de la page pendant les view transitions pour créer des expériences utilisateur plus dynamiques.

- [Explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning-without-freezing)
- [Exemple Angular sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-76kgww)

### Animer avec JavaScript {#animating-with-javascript}

Contrôlez les view transitions par programmation avec les API JavaScript pour des scénarios d'animation complexes.

- [Explainer de Chrome](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#animating-with-javascript)
- [Exemple Angular sur StackBlitz](https://stackblitz.com/edit/stackblitz-starters-cklnkm)
# Migrer depuis le package Animations d'Angular

Le package `@angular/animations` est déprécié depuis la v20.2, qui a aussi introduit la nouvelle fonctionnalité `animate.enter` et `animate.leave` pour ajouter des animations à votre application. Grâce à ces nouvelles fonctionnalités, vous pouvez remplacer toutes les animations basées sur `@angular/animations` par du CSS pur ou par des libraries d'animation JS. Retirer `@angular/animations` de votre application peut réduire considérablement la taille de votre bundle JavaScript. Les animations CSS natives offrent généralement de meilleures performances, car elles peuvent bénéficier de l'accélération matérielle. Ce guide présente la démarche pour refactoriser votre code de `@angular/animations` vers des animations CSS natives.

## Comment écrire des animations en CSS natif {#how-to-write-animations-in-native-css}

Si vous n'avez jamais écrit d'animations CSS natives, il existe de nombreux excellents guides pour bien démarrer. En voici quelques-uns :  
[Guide des animations CSS de MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)  
[Guide des animations CSS3 de W3Schools](https://www.w3schools.com/css/css3_animations.asp)  
[Le tutoriel complet sur les animations CSS](https://www.lambdatest.com/blog/css-animations-tutorial/)  
[Les animations CSS pour les débutants](https://thoughtbot.com/blog/css-animation-for-beginners)

ainsi que quelques vidéos :  
[Apprendre les animations CSS en 9 minutes](https://www.youtube.com/watch?v=z2LQYsZhsFw)  
[Playlist de tutoriels sur les animations CSS de Net Ninja](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

Consultez certains de ces guides et tutoriels, puis revenez à ce guide.

## Créer des animations réutilisables {#creating-reusable-animations}

Comme avec le package animations, vous pouvez créer des animations réutilisables, partagées dans toute votre application. Avec le package animations, vous utilisiez pour cela la fonction `animation()` dans un fichier TypeScript partagé. La version en CSS natif est similaire, mais se trouve dans un fichier CSS partagé.

#### Avec le package Animations {#with-animations-package}

<docs-code header="animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" region="animation-example"/>

#### Avec du CSS natif {#with-native-css}

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

Ajouter la classe `animated-class` à un élément déclenche l'animation sur cet élément.

## Animer une transition {#animating-a-transition}

### Animer des états et des styles {#animating-state-and-styles}

Le package animations vous permettait de définir différents états avec la fonction [`state()`](api/animations/state) dans un composant. Par exemple, un état `open` ou `closed` contenant dans sa définition les styles propres à chacun de ces états. Par exemple :

#### Avec le package Animations {#animating-state-and-styles-with-animations-package}

<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="state1"/>

Vous pouvez obtenir ce même comportement de manière native avec des classes CSS, soit avec une animation keyframes, soit avec un style de transition.

#### Avec du CSS natif {#animating-state-and-styles-with-native-css}

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

Vous trouverez des exemples similaires dans le guide des templates pour [animer directement des styles](guide/templates/binding#css-style-properties).

### Transitions, timing et easing {#transitions-timing-and-easing}

La fonction `animate()` du package animations permet d'indiquer un timing, comme la durée, les délais et l'easing. Vous pouvez faire de même nativement en CSS avec plusieurs propriétés CSS ou propriétés raccourcies.

Spécifiez `animation-duration`, `animation-delay` et `animation-timing-function` pour une animation keyframes en CSS, ou utilisez plutôt la propriété raccourcie `animation`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

De même, vous pouvez utiliser `transition-duration`, `transition-delay` et `transition-timing-function`, ainsi que le raccourci `transition`, pour les animations qui n'utilisent pas `@keyframes`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### Déclencher une animation {#triggering-an-animation}

Le package animations exigeait de spécifier des déclencheurs avec la fonction `trigger()` et d'y imbriquer tous vos états. Avec du CSS natif, c'est inutile. Les animations peuvent être déclenchées en basculant des styles ou des classes CSS. Dès qu'une classe est présente sur un élément, l'animation se produit. Retirer la classe ramène l'élément au CSS défini pour lui. Il faut ainsi beaucoup moins de code pour réaliser la même animation. Voici un exemple :

#### Avec le package Animations {#triggering-an-animation-with-animations-package}
#### Avec du CSS natif {#triggering-an-animation-with-native-css}

## Transition et déclencheurs {#transition-and-triggers}

### États prédéfinis et correspondance par wildcard {#predefined-state-and-wildcard-matching}

Le package animations permet de faire correspondre vos états définis à une transition au moyen de chaînes. Par exemple, une animation de l'état ouvert vers l'état fermé s'écrit `open => closed`. Vous pouvez utiliser des wildcards pour faire correspondre n'importe quel état à un état cible, comme `* => closed`, et le mot-clé `void` peut être utilisé pour les états d'entrée et de sortie. Par exemple : `* => void` quand un élément quitte une vue, ou `void => *` quand l'élément entre dans une vue.

Ces patterns de correspondance d'états sont totalement inutiles quand vous animez directement avec CSS. Vous pouvez gérer quelles transitions et quelles animations `@keyframes` s'appliquent selon les classes et / ou les styles que vous définissez sur les éléments. Vous pouvez aussi ajouter `@starting-style` pour contrôler l'apparence de l'élément dès son entrée dans le DOM.

### Calcul automatique des propriétés avec des wildcards {#automatic-property-calculation-with-wildcards}

Le package animations permet d'animer des choses historiquement difficiles à animer, comme le passage d'une hauteur fixe à `height: auto`. Vous pouvez désormais le faire aussi en CSS pur.

#### Avec le package Animations {#automatic-property-calculation-with-animations-package}
Vous pouvez utiliser CSS Grid pour animer vers une hauteur auto.

#### Avec du CSS natif {#automatic-property-calculation-with-native-css}

Si vous n'avez pas à vous soucier de la prise en charge de tous les navigateurs, vous pouvez aussi regarder `calc-size()`, qui est la véritable solution pour animer une hauteur auto. Consultez [la documentation de MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) et (ce tutoriel)[https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/] pour plus d'informations.

### Animer l'entrée et la sortie d'une vue {#animate-entering-and-leaving-a-view}

Le package animations proposait la correspondance de patterns évoquée plus haut pour l'entrée et la sortie, mais incluait aussi les alias raccourcis `:enter` et `:leave`.

#### Avec le package Animations {#enter-and-leave-with-animations-package}
#### Avec du CSS natif {#enter-with-native-css}

#### Avec du CSS natif {#leave-with-native-css}

Pour plus d'informations sur `animate.enter` et `animate.leave`, consultez le [guide des animations d'entrée et de sortie](guide/animations).

### Animer une incrémentation et une décrémentation {#animating-increment-and-decrement}

En plus des `:enter` et `:leave` évoqués plus haut, il existe aussi `:increment` et `:decrement`. Vous pouvez également les animer en ajoutant et en retirant des classes. Contrairement aux alias intégrés du package animations, les classes ne sont pas appliquées automatiquement quand les valeurs augmentent ou diminuent. Vous pouvez appliquer les classes appropriées par programmation. Voici un exemple :

#### Avec le package Animations {#increment-and-decrement-with-animations-package}
#### Avec du CSS natif {#increment-and-decrement-with-native-css}

### Animations parent / enfant {#parent---child-animations}

Contrairement au package animations, quand plusieurs animations sont définies dans un même composant, aucune animation n'a la priorité sur une autre et rien n'empêche une animation de se déclencher. Tout enchaînement d'animations doit être géré dans la définition de votre animation CSS, avec des délais d'animation / de transition, et / ou avec `animationend` ou `transitionend` pour ajouter le CSS suivant à animer.

Les animations enfants ne se déclenchent qu'au sein du template d'un même composant. Dans le package `@angular/animations`, les animations parentes pouvaient cibler et déclencher des animations dans des composants enfants imbriqués avec `query()` et `animateChild()`. Avec `animate.leave` et les animations CSS natives, les animations définies dans les templates des composants enfants imbriqués ne se déclenchent pas quand un composant parent retire un élément ou une vue. Seules les animations imbriquées au sein du template d'un même composant Angular s'exécutent. Consultez le [guide des animations d'entrée et de sortie](guide/animations#element-removal-order) pour plus d'informations à ce sujet.

### Désactiver une animation ou toutes les animations {#disabling-an-animation-or-all-animations}

Avec les animations CSS natives, si vous souhaitez désactiver les animations que vous avez définies, plusieurs options s'offrent à vous.

1. Créez une classe personnalisée qui force animation et transition à `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

3. Évitez d'ajouter des classes d'animation par programmation

### Callbacks d'animation {#animation-callbacks}

Le package animations exposait des callbacks à utiliser si vous vouliez faire quelque chose à la fin de l'animation. Les animations CSS natives disposent aussi de ces callbacks.

## Séquences complexes {#complex-sequences}

Le package animations intègre des fonctionnalités pour créer des séquences complexes. Toutes ces séquences sont parfaitement réalisables sans le package animations.

### Cibler des éléments précis {#targeting-specific-elements}

Dans le package animations, vous pouviez cibler des éléments précis avec la fonction `query()` pour trouver des éléments par nom de classe CSS, de façon similaire à [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector). C'est inutile avec les animations CSS natives. Vous pouvez plutôt utiliser vos selectors CSS pour cibler des sous-classes et appliquer la `transform` ou l'`animation` souhaitée.

Pour basculer des classes sur des nœuds enfants dans un template, vous pouvez utiliser des bindings de classe et de style afin d'ajouter les animations aux bons moments.

### Stagger() {#stagger}

La fonction `stagger()` vous permettait de retarder l'animation de chaque élément d'une liste d'une durée donnée pour créer un effet de cascade. Vous pouvez reproduire ce comportement en CSS natif avec `animation-delay` ou `transition-delay`. Voici un exemple de ce à quoi ce CSS pourrait ressembler.

#### Avec le package Animations {#stagger-with-animations-package}
#### Avec du CSS natif {#stagger-with-native-css}

### Animations parallèles {#parallel-animations}

Le package animations propose une fonction `group()` pour jouer plusieurs animations en même temps. En CSS, vous avez un contrôle total sur le timing des animations. Si vous avez défini plusieurs animations, vous pouvez toutes les appliquer en même temps.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

Dans cet exemple, les animations `rotate` et `fade-in` se déclenchent en même temps.

### Animer les éléments d'une liste réordonnée {#animating-the-items-of-a-reordering-list}

Le réordonnancement des éléments d'une liste fonctionne d'emblée avec les techniques décrites précédemment. Aucun travail spécifique supplémentaire n'est nécessaire. Les éléments d'une boucle `@for` sont correctement retirés puis rajoutés, ce qui déclenche les animations utilisant `@starting-styles` pour les animations d'entrée. Vous pouvez aussi utiliser `animate.enter` pour obtenir le même comportement. Utilisez `animate.leave` pour animer les éléments lorsqu'ils sont retirés, comme dans l'exemple ci-dessus.

#### Avec le package Animations {#reordering-list-with-animations-package}
#### Avec du CSS natif {#reordering-list-with-native-css}

## Migrer les usages d'AnimationPlayer {#migrating-usages-of-animationplayer}

La classe `AnimationPlayer` donne accès à une animation pour réaliser des opérations plus avancées, comme mettre en pause, lancer, redémarrer et terminer une animation depuis le code. Tout cela peut aussi être géré nativement.

## Transitions de route {#route-transitions}

Vous pouvez utiliser les view transitions pour animer le passage d'une route à l'autre. Consultez le [guide des animations de transition de route](guide/routing/route-transition-animations) pour commencer.
# Angular sans ZoneJS (zoneless)

## Pourquoi utiliser le mode zoneless ? {#why-use-zoneless}

Les principaux avantages à retirer ZoneJS des dépendances sont :

- **Performances améliorées** : ZoneJS utilise les événements DOM et les tâches asynchrones comme indicateurs du moment où l'état de l'application _pourrait_ avoir changé, puis déclenche une synchronisation de l'application pour exécuter la détection de changements sur ses vues. ZoneJS ne sait pas si l'état de l'application a réellement changé, et cette synchronisation est donc déclenchée plus souvent que nécessaire.
- **Core Web Vitals améliorés** : ZoneJS ajoute une surcharge non négligeable, à la fois en taille de payload et en temps de démarrage.
- **Débogage facilité** : ZoneJS rend le débogage du code plus difficile. Les stack traces sont plus difficiles à comprendre avec ZoneJS. Il est aussi difficile de comprendre quand du code casse parce qu'il s'exécute en dehors de la zone Angular.
- **Meilleure compatibilité avec l'écosystème** : ZoneJS fonctionne en patchant les API du navigateur, mais ne dispose pas automatiquement de patches pour chaque nouvelle API du navigateur. Certaines API, comme `async`/`await`, ne peuvent pas être patchées efficacement et doivent être transpilées vers une version antérieure (downleveling) pour fonctionner avec ZoneJS. Il arrive aussi que des libraries de l'écosystème soient incompatibles avec la façon dont ZoneJS patche les API natives. Retirer ZoneJS des dépendances garantit une meilleure compatibilité à long terme en supprimant une source de complexité, de monkey patching et de maintenance continue.

## Activer le mode zoneless dans une application {#enabling-zoneless-in-an-application}

Le mode zoneless est le comportement par défaut depuis Angular v21 : vous n'avez rien à faire pour l'activer. Vérifiez que `provideZoneChangeDetection` n'est utilisé nulle part pour remplacer la configuration par défaut.

Si vous utilisez Angular v20, activez la détection de changements zoneless en ajoutant `provideZonelessChangeDetection()` au bootstrap :

```ts
{header: 'standalone bootstrap'}
bootstrapApplication(MyApp, {providers: [provideZonelessChangeDetection()]});
```

```ts
{header: 'NgModule bootstrap'}
platformBrowser().bootstrapModule(AppModule);

@NgModule({
  providers: [provideZonelessChangeDetection()],
})
export class AppModule {}
```

## Retirer ZoneJS {#removing-zonejs}

Les applications zoneless devraient retirer complètement ZoneJS du build pour réduire la taille du bundle. ZoneJS est généralement
chargé via l'option `polyfills` dans `angular.json`, à la fois dans les cibles `build` et `test`. Retirez `zone.js`
et `zone.js/testing` des deux pour l'exclure du build. Les projets qui utilisent un fichier `polyfills.ts` explicite
doivent retirer `import 'zone.js';` et `import 'zone.js/testing';` de ce fichier.

Une fois ZoneJS retiré du build, la dépendance `zone.js` n'est plus nécessaire non plus et le
package peut être entièrement supprimé :

```shell
npm uninstall zone.js
```

## Prérequis pour la compatibilité zoneless {#requirements-for-zoneless-compatibility}

Angular s'appuie sur des notifications provenant des API du cœur pour déterminer quand exécuter la détection de changements et sur quelles vues.
Ces notifications comprennent :

- `ChangeDetectorRef.markForCheck` (appelé automatiquement par `AsyncPipe`)
- `ComponentRef.setInput`
- La mise à jour d'un signal lu dans un template
- Les callbacks des listeners liés au host ou au template
- L'attachement d'une vue marquée comme modifiée (dirty) par l'un des cas ci-dessus

### Composants compatibles `OnPush` {#onpush-compatible-components}

Une façon de garantir qu'un composant utilise les bons mécanismes de notification ci-dessus consiste à
utiliser [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush).

La stratégie de détection de changements `OnPush` n'est pas obligatoire, mais c'est une étape recommandée vers la compatibilité zoneless pour les composants d'application. Il n'est pas toujours possible pour les composants de library d'utiliser `ChangeDetectionStrategy.OnPush`.
Lorsqu'un composant de library est le host de composants utilisateur susceptibles d'utiliser `ChangeDetectionStrategy.Eager`/`Default`, il ne peut pas utiliser `OnPush`, car cela empêcherait le composant enfant d'être rafraîchi s'il n'est pas compatible `OnPush` et s'appuie sur ZoneJS pour déclencher la détection de changements. Les composants peuvent utiliser la stratégie `Default` tant qu'ils notifient Angular lorsque la détection de changements doit s'exécuter (en appelant `markForCheck`, en utilisant des signals, `AsyncPipe`, etc.).
Être le host d'un composant utilisateur signifie utiliser une API comme `ViewContainerRef.createComponent`, et pas seulement héberger une portion du template d'un composant utilisateur (c'est-à-dire la projection de contenu ou un input recevant une référence de template).

### Retirer `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable` ou `NgZone.onStable` {#remove-ngzoneonmicrotaskempty-ngzoneonunstable-ngzoneisstable-or-ngzoneonstable}

Les applications et les libraries doivent supprimer les utilisations de `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` et `NgZone.onStable`.
Ces observables n'émettront jamais lorsqu'une application active la détection de changements zoneless.
De même, `NgZone.isStable` vaudra toujours `true` et ne doit pas servir de condition à l'exécution de code.

Les observables `NgZone.onMicrotaskEmpty` et `NgZone.onStable` servent le plus souvent à attendre qu'Angular
termine la détection de changements avant d'effectuer une tâche. Ils peuvent être remplacés par `afterNextRender`
s'il faut attendre une seule détection de changements, ou par `afterEveryRender` si une condition peut s'étendre
sur plusieurs cycles de détection de changements. Dans d'autres cas, ces observables étaient utilisés parce qu'ils se trouvaient être
familiers et avaient un timing proche de celui nécessaire. Des API DOM plus simples ou plus directes peuvent être utilisées à la place,
comme `MutationObserver` lorsque le code doit attendre un certain état du DOM (plutôt que de l'attendre indirectement
via les hooks de rendu d'Angular).
`NgZone.run` et `NgZone.runOutsideAngular` n'ont pas besoin d'être retirés pour que le code soit compatible avec
les applications zoneless. En réalité, retirer ces appels peut entraîner des régressions de performances pour les libraries
utilisées dans des applications qui s'appuient encore sur ZoneJS.
### `PendingTasks` pour le rendu côté serveur (SSR) {#pendingtasks-for-server-side-rendering-ssr}

Si vous utilisez le SSR avec Angular, vous savez peut-être qu'il s'appuie sur ZoneJS pour déterminer quand l'application
est « stable » et peut être sérialisée. S'il existe des tâches asynchrones qui doivent empêcher la sérialisation, une application
qui n'utilise pas ZoneJS doit les signaler à Angular avec le service [PendingTasks](/api/core/PendingTasks). La sérialisation
attendra le premier moment où toutes les tâches en attente auront été retirées.

Les deux utilisations les plus simples des tâches en attente passent par la méthode `run` :

```typescript
const taskService = inject(PendingTasks);
taskService.run(async () => {
  const someResult = await doSomeWorkThatNeedsToBeRendered();
  this.someState.set(someResult);
});
```

Pour des cas d'usage plus complexes, vous pouvez ajouter et retirer manuellement une tâche en attente :

```typescript
const taskService = inject(PendingTasks);
const taskCleanup = taskService.add();
try {
  await doSomeWorkThatNeedsToBeRendered();
} catch {
  // handle error
} finally {
  taskCleanup();
}
```

De plus, le helper [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent) de `rxjs-interop` garantit
que l'application reste instable jusqu'à ce que l'observable émette, se termine, lève une erreur ou soit désabonné.

```typescript
readonly myObservableState = someObservable.pipe(pendingUntilEvent());
```

Le framework utilise aussi ce service en interne pour empêcher la sérialisation tant que des tâches asynchrones ne sont pas terminées. Cela inclut notamment une navigation du router en cours et une requête `HttpClient` non terminée.

### Reactive forms dans les applications zoneless {#reactive-forms-in-zoneless-applications}

Les mises à jour du model des reactive forms (`setValue`, `patchValue`, `FormArray.push` et API similaires) mettent à jour l'état du formulaire et émettent les observables du formulaire, mais elles ne planifient pas automatiquement la détection de changements du composant.

Si un template dépend de l'état des reactive forms, connectez les observables du formulaire à une notification de détection de changements (par exemple `ChangeDetectorRef.markForCheck()`), ou reflétez les données via des signals consommés par le template.

## Tests et débogage {#testing-and-debugging}

### Utiliser le mode zoneless dans `TestBed` {#using-zoneless-in-testbed}

`TestBed` utilise par défaut la détection de changements zoneless, même lorsque `zone.js` est chargé via les `polyfills`.

Pour utiliser la détection de changements basée sur Zone dans un test, ajoutez `provideZoneChangeDetection()` aux providers du `TestBed`. Ajouter `provideZonelessChangeDetection()` est facultatif :

```typescript
TestBed.configureTestingModule({
  // Optional: include the provider to force the testing environment
  // uses the same zoneless behavior as a zoneless application.
  providers: [provideZonelessChangeDetection()],
});

const fixture = TestBed.createComponent(MyComponent);
await fixture.whenStable();
```

Pour que les tests aient un comportement le plus proche possible du code de production,
évitez autant que possible d'utiliser `fixture.detectChanges()`. Cela force
la détection de changements à s'exécuter alors qu'Angular ne l'aurait peut-être pas
planifiée. Les tests doivent s'assurer que ces notifications
ont bien lieu et laisser Angular décider quand synchroniser
l'état, plutôt que de le forcer manuellement dans le test.

Pour les suites de tests existantes, utiliser `fixture.detectChanges()` est un pattern courant
et il ne vaut probablement pas la peine de les convertir en
`await fixture.whenStable()`. `TestBed` vérifiera toujours que le
composant de la fixture est compatible `OnPush` et lève `ExpressionChangedAfterItHasBeenCheckedError`
s'il constate que des valeurs du template ont été mises à jour sans
notification de changement (par exemple `fixture.componentInstance.someValue = 'newValue';`).
Si le composant est utilisé en production, ce problème doit être corrigé en modifiant
le composant pour qu'il utilise des signals pour son état ou appelle `ChangeDetectorRef.markForCheck()`.
Si le composant ne sert que de wrapper de test et n'est jamais utilisé dans une application,
il est acceptable de lui appliquer `ChangeDetectionStrategy.Eager` et d'appeler `fixture.changeDetectorRef.markForCheck()`.

IMPORTANT: `fixture.changeDetectorRef` appartient à la host view de la fixture, donc son `markForCheck()`
ne rafraîchit pas le template d'un composant `OnPush`. Les composants de votre application ne devraient pas en avoir besoin
dans les tests. Si un test en a besoin, c'est généralement que le composant n'est pas entièrement réactif ou
[compatible zoneless](#requirements-for-zoneless-compatibility).

### Vérification en mode debug pour garantir la détection des mises à jour {#debug-mode-check-to-ensure-updates-are-detected}

IMPORTANT: `provideCheckNoChangesConfig` est en [developer preview](reference/releases#developer-preview).

Angular fournit aussi un outil supplémentaire pour vérifier qu'une application effectue
ses mises à jour d'état d'une manière compatible zoneless. `provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})`
peut être utilisé pour vérifier périodiquement qu'aucun binding n'a été mis à jour
sans notification. Angular lève `ExpressionChangedAfterItHasBeenCheckedError`
s'il existe un binding mis à jour qui n'aurait pas été rafraîchi par la détection de changements
zoneless.
En tant que projet open source, les commits quotidiens, les PR et la dynamique d'Angular sont entièrement traçables sur GitHub. Pour plus de transparence sur la façon dont ce travail quotidien s'inscrit dans l'avenir du framework, notre feuille de route rassemble la vision actuelle et future de l'équipe.

Les projets suivants ne sont pas associés à une version particulière d'Angular. Nous les publierons une fois terminés, et ils feront partie d'une version précise selon notre calendrier de sorties, conformément au versionnage sémantique. Par exemple, nous publions les fonctionnalités dans la version mineure suivant leur achèvement, ou dans la version majeure suivante si elles comportent des changements incompatibles.

Actuellement, Angular poursuit trois objectifs pour le framework :

1. Améliorer l'[expérience de l'IA pour les développeurs](/ai)
1. Améliorer l'[expérience de développement Angular](#improving-the-angular-developer-experience)
1. Améliorer les performances du framework

Poursuivez votre lecture pour découvrir comment nous prévoyons d'atteindre ces objectifs grâce à des projets concrets.

## Explorer Angular moderne {#explore-modern-angular}

Commencez à développer avec les dernières fonctionnalités d'Angular issues de notre feuille de route. Cette liste présente le statut actuel des nouvelles fonctionnalités de notre feuille de route :

### Disponible pour expérimentation {#available-to-experiment-with}

- [Web MCP](/ai/webmcp)

### Prêt pour la production {#production-ready}

- [Signal Forms](/guide/forms/signals/overview)
- [API Resource](/guide/signals/resource)
- [httpResource](/api/common/http/httpResource)
- [Détection de changements zoneless](/guide/zoneless)
- [API Linked Signal](/guide/signals/linked-signal)
- [Hydratation incrémentale](/guide/incremental-hydration)
- [API Effect](/api/core/effect)
- [Event replay avec le SSR](/api/platform-browser/withEventReplay)
- [Mode de rendu au niveau des routes](/guide/ssr)

## Améliorer l'expérience de l'IA pour les développeurs Angular {#improving-the-ai-experience-for-angular-developers}

### Apporter le meilleur de l'IA à Angular {#bringing-the-best-of-ai-to-angular}
## Améliorer l'expérience de développement Angular {#improving-the-angular-developer-experience}

### Vélocité des développeurs {#developer-velocity}
### Améliorer l'outillage {#improve-tooling}
## Projets terminés {#completed-projects}
# Garder vos projets Angular à jour

Tout comme le Web et l'ensemble de l'écosystème web, Angular s'améliore en continu.
Angular concilie amélioration continue et forte attention portée à la stabilité et à la simplicité des mises à jour.
Garder votre application Angular à jour vous permet de profiter des nouvelles fonctionnalités de pointe, ainsi que des optimisations et des corrections de bugs.

Ce document contient des informations et des ressources pour vous aider à garder vos applications et libraries Angular à jour.

Pour en savoir plus sur notre politique et nos pratiques de versionnage — notamment en matière de support et de dépréciation, ainsi que sur le calendrier des versions — consultez [Versionnage et versions d'Angular](reference/releases 'Angular versioning and releases').

HELPFUL: Si vous utilisez actuellement AngularJS, consultez [Migrer depuis AngularJS](https://angular.io/guide/upgrade 'Upgrading from AngularJS').
_AngularJS_ est le nom de toutes les versions v1.x d'Angular.

## Être averti des nouvelles versions {#getting-notified-of-new-releases}

Pour être averti de la disponibilité de nouvelles versions, suivez [@angular](https://x.com/angular '@angular on X') sur X (anciennement Twitter) ou abonnez-vous au [blog Angular](https://blog.angular.dev 'Angular blog').

## Découvrir les nouvelles fonctionnalités {#learning-about-new-features}

Quoi de neuf ? Qu'est-ce qui a changé ? Nous partageons l'essentiel de ce que vous devez savoir sur le blog Angular, dans les [annonces de versions](https://blog.angular.dev/ 'Angular blog - release announcements').

Pour consulter la liste complète des changements, organisée par version, consultez le [change log d'Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log').

## Vérifier votre version d'Angular {#checking-your-version-of-angular}

Pour vérifier la version d'Angular de votre application, utilisez la commande `ng version` depuis le répertoire de votre projet.

## Trouver la version actuelle d'Angular {#finding-the-current-version-of-angular}

La version stable la plus récente d'Angular apparaît [sur npm](https://www.npmjs.com/package/@angular/core 'Angular on npm') sous « Version ». Par exemple, `16.2.4`.

Vous pouvez aussi trouver la version la plus récente d'Angular avec la commande CLI [`ng update`](cli/update).
Par défaut, [`ng update`](cli/update) (sans argument supplémentaire) liste les mises à jour qui vous sont disponibles.

## Mettre à jour votre environnement et vos applications {#updating-your-environment-and-apps}

Pour simplifier les mises à jour, nous fournissons des instructions complètes dans le [guide de mise à jour Angular](update-guide) interactif.

Le guide de mise à jour Angular fournit des instructions de mise à jour personnalisées, selon les versions actuelle et cible que vous indiquez.
Il propose des parcours de mise à jour basiques et avancés, adaptés à la complexité de vos applications.
Il inclut aussi des informations de dépannage et les éventuelles modifications manuelles recommandées pour tirer le meilleur parti de la nouvelle version.

Pour les mises à jour simples, la commande CLI [`ng update`](cli/update) suffit.
Sans argument supplémentaire, [`ng update`](cli/update) liste les mises à jour qui vous sont disponibles et fournit les étapes recommandées pour mettre à jour votre application vers la version la plus récente.

[Versionnage et versions d'Angular](reference/releases#angular-versioning 'Angular Release Practices, Versioning') décrit le niveau de changement auquel vous pouvez vous attendre selon le numéro de version d'une release.
Il décrit aussi les parcours de mise à jour pris en charge.

## Récapitulatif des ressources {#resource-summary}

- Annonces de versions :
  [Blog Angular - annonces de versions](https://blog.angular.dev/ 'Angular blog announcements about recent releases')

- Détails des versions :
  [Change log d'Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log')

- Instructions de mise à jour :
  [Guide de mise à jour Angular](update-guide)

- Référence de la commande de mise à jour :
  [Référence de la commande Angular CLI `ng update`](cli/update)

- Pratiques de versionnage, de publication, de support et de dépréciation :
  [Versionnage et versions d'Angular](reference/releases 'Angular versioning and releases')
L'_internationalisation_, parfois désignée par i18n, est le processus de conception et de préparation de votre projet pour qu'il puisse être utilisé dans différentes locales à travers le monde.
La _localisation_ est le processus de construction de versions de votre projet pour différentes locales.
Le processus de localisation comprend les actions suivantes.

- Extraire le texte à traduire dans différentes langues
- Formater les données pour une locale spécifique

Une _locale_ identifie une région dans laquelle les gens parlent une langue ou une variante de langue particulière.
Les régions possibles incluent les pays et les régions géographiques.
Une locale détermine le formatage et l'analyse des éléments suivants.

- Les unités de mesure, notamment la date et l'heure, les nombres et les devises
- Les noms traduits, notamment les fuseaux horaires, les langues et les pays

Pour une introduction rapide à la localisation et à l'internationalisation, regardez cette vidéo :

<docs-video src="https://www.youtube.com/embed/KNTN-nsbV7M"/>

## En savoir plus sur l'internationalisation Angular {#learn-about-angular-internationalization}
# Sécurité

Cette page décrit les protections intégrées d'Angular contre les vulnérabilités et attaques courantes des applications web, comme les attaques de cross-site scripting.
Elle ne traite pas de la sécurité au niveau applicatif, comme l'authentification et l'autorisation.

Pour plus d'informations sur les attaques et les mesures de protection décrites ci-dessous, consultez le [guide de l'Open Web Application Security Project (OWASP)](https://www.owasp.org/index.php/Category:OWASP_Guide_Project).

<a id="report-issues"></a>
Angular fait partie du [programme de récompenses pour les vulnérabilités des logiciels open source](https://bughunters.google.com/about/rules/6521337925468160/google-open-source-software-vulnerability-reward-program-rules) de Google. Pour les vulnérabilités d'Angular, soumettez votre rapport sur [https://bughunters.google.com](https://bughunters.google.com/report).

Pour plus d'informations sur la manière dont Google traite les problèmes de sécurité, consultez [la philosophie de sécurité de Google](https://www.google.com/about/appsecurity).
## Bonnes pratiques {#best-practices}

Voici quelques bonnes pratiques pour garantir la sécurité de votre application Angular.

1. **Restez à jour avec les dernières versions des libraries Angular** - Les libraries Angular reçoivent des mises à jour régulières, et ces mises à jour peuvent corriger des failles de sécurité découvertes dans des versions précédentes. Consultez le [change log](https://github.com/angular/angular/blob/main/CHANGELOG.md) d'Angular pour les mises à jour liées à la sécurité.
2. **Ne modifiez pas votre copie d'Angular** - Les versions privées et personnalisées d'Angular ont tendance à prendre du retard sur la version actuelle et peuvent ne pas inclure d'importants correctifs et améliorations de sécurité. Partagez plutôt vos améliorations d'Angular avec la communauté en ouvrant une pull request.
3. **Évitez les API Angular signalées dans la documentation comme « _Security Risk_ »** - Pour plus d'informations, consultez la section [Faire confiance aux valeurs sûres](#trusting-safe-values) de cette page.

## Prévenir le cross-site scripting (XSS) {#preventing-cross-site-scripting-xss}

Le [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) permet à des attaquants d'injecter du code malveillant dans des pages web.
Ce code peut alors, par exemple, voler des données utilisateur et des identifiants de connexion, ou effectuer des actions en se faisant passer pour l'utilisateur.
C'est l'une des attaques les plus courantes sur le web.

Pour bloquer les attaques XSS, vous devez empêcher le code malveillant d'entrer dans le Document Object Model (DOM).
Par exemple, si des attaquants parviennent à vous faire insérer une balise `<script>` dans le DOM, ils peuvent exécuter du code arbitraire sur votre site web.
L'attaque ne se limite pas aux balises `<script>` : de nombreux éléments et propriétés du DOM permettent l'exécution de code, par exemple `<img alt="" onerror="...">` et `<a href="javascript:...">`.
Si des données contrôlées par un attaquant entrent dans le DOM, attendez-vous à des vulnérabilités de sécurité.

### Le modèle de sécurité d'Angular contre le cross-site scripting {#angulars-cross-site-scripting-security-model}

Pour bloquer systématiquement les failles XSS, Angular considère par défaut toutes les valeurs comme non fiables.
Lorsqu'une valeur est insérée dans le DOM depuis un binding de template ou une interpolation, Angular assainit et échappe les valeurs non fiables.
Si une valeur a déjà été assainie en dehors d'Angular et est considérée comme sûre, indiquez-le à Angular en marquant la [valeur comme étant de confiance](#trusting-safe-values).

Contrairement aux valeurs destinées au rendu, les templates Angular sont considérés par défaut comme dignes de confiance et doivent être traités comme du code exécutable.
Ne créez jamais de templates en concaténant des saisies utilisateur et de la syntaxe de template.
Cela permettrait à des attaquants d'[injecter du code arbitraire](https://en.wikipedia.org/wiki/Code_injection) dans votre application.
Pour éviter ces vulnérabilités, utilisez toujours le [compilateur de templates Ahead-Of-Time (AOT)](#use-the-aot-template-compiler) par défaut dans vos déploiements de production.

Une couche de protection supplémentaire peut être apportée par l'utilisation de la Content Security Policy et des Trusted Types.
Ces fonctionnalités de la plateforme web opèrent au niveau du DOM, qui est l'endroit le plus efficace pour prévenir les problèmes XSS. À ce niveau, elles ne peuvent pas être contournées par d'autres API de plus bas niveau.
C'est pourquoi il est fortement recommandé de tirer parti de ces fonctionnalités. Pour cela, configurez la [Content Security Policy](#content-security-policy) de l'application et activez l'[application obligatoire des Trusted Types](#enforcing-trusted-types).

### Assainissement et contextes de sécurité {#sanitization-and-security-contexts}

L'_assainissement_ consiste à inspecter une valeur non fiable pour la transformer en une valeur qu'il est sûr d'insérer dans le DOM.
Dans de nombreux cas, l'assainissement ne modifie pas du tout la valeur.
L'assainissement dépend d'un contexte.
Par exemple, une valeur inoffensive en CSS est potentiellement dangereuse dans une URL.

Angular définit les contextes de sécurité suivants :

Angular assainit les valeurs non fiables pour le HTML et les URL. Il est impossible d'assainir les URL de ressource, car elles contiennent du code arbitraire.
En mode développement, Angular affiche un avertissement dans la console lorsqu'il doit modifier une valeur pendant l'assainissement.

### Exemple d'assainissement {#sanitization-example}

Le template suivant lie la valeur de `htmlSnippet`. Une fois en l'interpolant dans le contenu d'un élément, et une fois en la liant à la propriété `innerHTML` d'un élément :

<docs-code header="inner-html-binding.component.html" path="adev/src/content/examples/security/src/app/inner-html-binding.component.html"/>

Le contenu interpolé est toujours échappé : le HTML n'est pas interprété et le navigateur affiche les chevrons dans le contenu textuel de l'élément.

Pour que le HTML soit interprété, liez-le à une propriété HTML comme `innerHTML`.
Sachez que lier à `innerHTML` une valeur qu'un attaquant pourrait contrôler provoque normalement une vulnérabilité XSS.
Par exemple, on pourrait exécuter du JavaScript de la manière suivante :

<docs-code header="inner-html-binding.component.ts (class)" path="adev/src/content/examples/security/src/app/inner-html-binding.component.ts" region="class"/>

Angular reconnaît la valeur comme non sûre et l'assainit automatiquement, ce qui supprime l'élément `script` tout en conservant le contenu sûr, comme l'élément `<b>`.

### Utilisation directe des API du DOM et appels explicites d'assainissement {#direct-use-of-the-dom-apis-and-explicit-sanitization-calls}

À moins d'imposer les Trusted Types, les API du DOM intégrées au navigateur ne vous protègent pas automatiquement des vulnérabilités de sécurité.
Par exemple, `document`, le nœud accessible via `ElementRef` et de nombreuses API tierces contiennent des méthodes non sûres.
De même, si vous interagissez avec d'autres libraries qui manipulent le DOM, vous ne bénéficierez probablement pas du même assainissement automatique qu'avec les interpolations Angular.
Évitez d'interagir directement avec le DOM et utilisez plutôt les templates Angular lorsque c'est possible.

Dans les cas où c'est inévitable, utilisez les fonctions d'assainissement intégrées d'Angular.
Assainissez les valeurs non fiables avec la méthode [DomSanitizer.sanitize](api/platform-browser/DomSanitizer#sanitize) et le `SecurityContext` approprié.
Cette fonction accepte aussi les valeurs marquées comme étant de confiance à l'aide des fonctions `bypassSecurityTrust`, et ne les assainit pas, comme [décrit ci-dessous](#trusting-safe-values).

### Faire confiance aux valeurs sûres {#trusting-safe-values}

Il arrive que des applications aient réellement besoin d'inclure du code exécutable, d'afficher une `<iframe>` depuis une URL donnée ou de construire des URL potentiellement dangereuses.
Pour empêcher l'assainissement automatique dans ces situations, indiquez à Angular que vous avez inspecté une valeur, vérifié comment elle a été créée et vous êtes assuré qu'elle est sûre.
Soyez _prudent_.
Si vous faites confiance à une valeur potentiellement malveillante, vous introduisez une vulnérabilité de sécurité dans votre application.
En cas de doute, faites appel à un expert en revue de sécurité.

Pour marquer une valeur comme étant de confiance, injectez `DomSanitizer` et appelez l'une des méthodes suivantes :

- `bypassSecurityTrustHtml`
- `bypassSecurityTrustScript`
- `bypassSecurityTrustStyle`
- `bypassSecurityTrustUrl`
- `bypassSecurityTrustResourceUrl`

N'oubliez pas que la sûreté d'une valeur dépend du contexte : choisissez donc le bon contexte pour l'usage prévu de la valeur.
Imaginez que le template suivant doive lier une URL à un appel `javascript:alert(...)` :

<docs-code header="bypass-security.component.html (URL)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="URL"/>

Normalement, Angular assainit automatiquement l'URL, désactive le code dangereux et, en mode développement, consigne cette action dans la console.
Pour l'éviter, marquez la valeur de l'URL comme une URL de confiance avec l'appel `bypassSecurityTrustUrl` :

<docs-code header="bypass-security.component.ts (trust-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-url"/>

Si vous devez convertir une saisie utilisateur en valeur de confiance, utilisez une méthode du composant.
Le template suivant permet aux utilisateurs de saisir un identifiant de vidéo YouTube et de charger la vidéo correspondante dans une `<iframe>`.
L'attribut `<iframe src>` relève du contexte de sécurité Resource URL, car une source non fiable peut, par exemple, introduire en douce des téléchargements de fichiers que des utilisateurs non avertis pourraient exécuter.
Pour l'éviter, appelez une méthode du composant afin de construire une URL de vidéo de confiance, ce qui amène Angular à autoriser le binding sur `<iframe src>` :

<docs-code header="bypass-security.component.html (iframe)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="iframe"/>

<docs-code header="bypass-security.component.ts (trust-video-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-video-url"/>

### Politique de sécurité du contenu (Content Security Policy) {#content-security-policy}

La Content Security Policy $CSP$ est une technique de défense en profondeur pour prévenir le XSS.
Pour activer la CSP, configurez votre serveur web pour qu'il renvoie un en-tête HTTP `Content-Security-Policy` approprié.
Pour en savoir plus sur la Content Security Policy, consultez le [guide Web Fundamentals](https://developers.google.com/web/fundamentals/security/csp) sur le site Google Developers.

La politique minimale requise pour une toute nouvelle application Angular est la suivante :

```txt
default-src 'self'; style-src 'self' 'nonce-randomNonceGoesHere'; script-src 'self' 'nonce-randomNonceGoesHere';
```

Lorsqu'il sert votre application Angular, le serveur doit inclure un nonce généré aléatoirement dans l'en-tête HTTP de chaque requête.
Vous devez fournir ce nonce à Angular pour que le framework puisse effectuer le rendu des éléments `<style>`.
Vous pouvez définir le nonce pour Angular de l'une des manières suivantes :

1. Définissez l'attribut `ngCspNonce` sur l'élément racine de l'application, sous la forme `<app ngCspNonce="randomNonceGoesHere"></app>`. Utilisez cette approche si vous disposez d'un templating côté serveur capable d'ajouter le nonce à la fois à l'en-tête et à `index.html` lors de la construction de la réponse.
1. Fournissez le nonce avec le jeton d'injection `CSP_NONCE`. Utilisez cette approche si vous avez accès au nonce à l'exécution et souhaitez pouvoir mettre en cache `index.html`.

```ts
import {CSP_NONCE} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import {AppComponent} from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: CSP_NONCE,
      useValue: globalThis.myRandomNonceValue,
    },
  ],
});
```
Assurez-vous toujours que les nonces que vous fournissez sont <strong>uniques pour chaque requête</strong> et qu'ils ne sont ni prévisibles ni devinables.
Si un attaquant peut prédire les futurs nonces, il peut contourner les protections offertes par la CSP.

Il est généralement déconseillé de générer un nonce sur le serveur d'origine lorsque vous utilisez un CDN, car les réponses sont fréquemment mises en cache. Si le serveur génère un nonce et que le CDN met en cache cette réponse HTML, chaque visiteur suivant reçoit la même valeur « unique », ce qui permet à un attaquant de découvrir cette valeur statique et de contourner les protections de la CSP.

Pour préserver l'intégrité « à usage unique » d'un nonce, celui-ci devrait idéalement être généré au niveau de la couche Edge (par exemple, le CDN) juste avant que le contenu ne soit livré à l'utilisateur.
NOTE: Si vous souhaitez [intégrer en ligne le CSS critique](/tools/cli/build#critical-css-inlining) de votre application, vous ne pouvez pas utiliser le jeton `CSP_NONCE` ; privilégiez alors l'option `security.autoCsp` dans la [configuration du workspace](reference/configs/workspace-config#extra-build-and-test-options) ou définissez l'attribut `ngCspNonce` sur l'élément racine de l'application.

Si vous ne pouvez pas générer de nonces dans votre projet, vous pouvez autoriser les styles inline en ajoutant `'unsafe-inline'` à la section `style-src` de l'en-tête CSP.

| Sections                                         | Détails                                                                                                                                                                                                                                                                                                                                                  |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default-src 'self';`                            | Permet à la page de charger toutes les ressources dont elle a besoin depuis la même origine.                                                                                                                                                                                                                                                                                 |
| `style-src 'self' 'nonce-randomNonceGoesHere';`  | Permet à la page de charger les styles globaux depuis la même origine $`'self'`$ et les styles insérés par Angular avec le `nonce-randomNonceGoesHere`.                                                                                                                                                                                                             |
| `script-src 'self' 'nonce-randomNonceGoesHere';` | Permet à la page de charger du JavaScript depuis la même origine $`'self'`$ et les scripts insérés par Angular CLI avec le `nonce-randomNonceGoesHere`. Requis uniquement lorsque vous activez l'intégration en ligne du CSS critique ou l'intégrité des sous-ressources (qui injecte une import map pour valider les chunks importés dynamiquement), qui ajoutent toutes deux des scripts inline à `index.html`. |

Angular lui-même n'a besoin que de ces paramètres pour fonctionner correctement.
À mesure que votre projet grandit, vous devrez peut-être étendre vos paramètres CSP pour prendre en charge des fonctionnalités supplémentaires propres à votre application.

#### Hébergement statique sans nonce par réponse {#static-hosting-without-per-response-nonces}

Si votre environnement d'hébergement ou votre CDN peut remplacer un jeton de substitution dans le HTML mis en cache au niveau de l'edge (par exemple avec SSI, ESI ou une edge function), vous pouvez générer `index.html` avec un placeholder dans `ngCspNonce` (comme `<app ngCspNonce="__CSP_NONCE__"></app>`) et le remplacer par un nonce unique à chaque réponse.

Si vous déployez votre application sur un hébergeur statique qui sert `index.html` tel quel, sans transformation à l'edge, ne codez pas en dur un nonce statique. Utilisez plutôt l'une des approches suivantes :

##### Hacher les scripts inline avec `autoCsp` {#hash-inline-scripts-with-autocsp}

Définissez l'option `security.autoCsp` à `true` dans la [configuration du workspace](reference/configs/workspace-config#extra-build-and-test-options).
Au moment du build, Angular CLI calcule un hash de chaque script inline de `index.html`, y compris les scripts ajoutés par l'intégration en ligne du CSS critique et par l'intégrité des sous-ressources.
La CLI remplace les éléments `<script src>` par un script loader haché et ajoute une balise `<meta>` au début de `<head>` :

```txt
script-src 'strict-dynamic' 'sha256-...' https: 'unsafe-inline'; object-src 'none'; base-uri 'self';
```

Comme les hashes ne dépendent que du contenu des scripts, `index.html` reste valide pour chaque visiteur et peut être mis en cache.
Les navigateurs qui prennent en charge les hashes et `'strict-dynamic'` ignorent les sources de repli `https:` et `'unsafe-inline'`.

La politique générée par `autoCsp` présente les limites suivantes :

- Elle ne couvre que les scripts. Vous devez configurer `style-src` séparément.
- Les navigateurs ignorent certaines directives, comme `frame-ancestors`, `report-uri` et `sandbox`, lorsqu'elles apparaissent dans une balise `<meta>`. Envoyez ces directives dans un en-tête HTTP `Content-Security-Policy`.
- Lorsqu'une page a plusieurs politiques, le navigateur les applique toutes. Si vous envoyez aussi un en-tête CSP, omettez à la fois `script-src` et `default-src` de cet en-tête afin qu'ils ne bloquent pas les scripts inline hachés.
- Vous ne pouvez pas utiliser `autoCsp` avec le rendu côté serveur (SSR).

##### Éviter les scripts inline {#avoid-inline-scripts}

Angular CLI n'ajoute des scripts inline à `index.html` que pour l'intégration en ligne du CSS critique et pour l'intégrité des sous-ressources (qui émet une import map transportant les métadonnées d'intégrité des imports dynamiques de modules).
Si vous définissez `optimization.styles.inlineCritical` à `false` et laissez `subresourceIntegrity` désactivé, `index.html` ne contient aucun script inline. Vous pouvez alors configurer un en-tête `Content-Security-Policy` avec `script-src 'self'`.

NOTE: Désactiver l'intégration en ligne du CSS critique peut ralentir le rendu initial de votre application, et désactiver l'intégrité des sous-ressources supprime les vérifications d'intégrité des scripts.

##### Configurer les styles pour l'hébergement statique {#configure-styles-for-static-hosting}

Angular insère des éléments `<style>` pour les styles des composants à l'exécution, et l'intégration en ligne du CSS critique ajoute un élément `<style>` à `index.html`.
Ni `autoCsp` ni la désactivation des scripts inline ne couvrent ces styles. Sans nonce par réponse, autorisez-les en ajoutant `'unsafe-inline'` à `style-src`.
Par exemple, si votre build évite les scripts inline, configurez votre hébergeur pour qu'il envoie l'en-tête suivant :

```txt
default-src 'self'; style-src 'self' 'unsafe-inline';
```

Si vous utilisez `autoCsp`, envoyez `style-src 'self' 'unsafe-inline'` dans l'en-tête HTTP, sans `default-src` ni `script-src`.

Le code de votre application et les libraries tierces peuvent nécessiter des directives supplémentaires dans les deux cas.

### Rendre obligatoire l'usage des Trusted Types {#enforcing-trusted-types}

Il est recommandé d'utiliser les [Trusted Types](https://w3c.github.io/trusted-types/dist/spec/) pour aider à protéger vos applications contre les attaques de cross-site scripting.
Les Trusted Types sont une fonctionnalité de la [plateforme web](https://en.wikipedia.org/wiki/Web_platform) qui peut vous aider à prévenir les attaques de cross-site scripting en imposant des pratiques de codage plus sûres.
Les Trusted Types peuvent aussi faciliter l'audit du code de l'application.
Les Trusted Types ne sont peut-être pas encore disponibles dans tous les navigateurs ciblés par votre application.
Si votre application compatible Trusted Types s'exécute dans un navigateur qui ne les prend pas en charge, les fonctionnalités de l'application sont préservées. Votre application reste protégée contre le XSS grâce au DomSanitizer d'Angular.
Consultez [caniuse.com/trusted-types](https://caniuse.com/trusted-types) pour connaître la prise en charge actuelle par les navigateurs.
Pour imposer les Trusted Types dans votre application, vous devez configurer le serveur web de votre application pour qu'il émette des en-têtes HTTP avec l'une des politiques Angular suivantes :

| Politiques                 | Détail                                                                                                                                                                                                                                                                                     |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `angular`                | Cette politique est utilisée dans du code interne à Angular ayant fait l'objet d'une revue de sécurité, et elle est requise pour qu'Angular fonctionne lorsque les Trusted Types sont imposés. Toutes les valeurs de template inline et tout contenu assaini par Angular sont considérés comme sûrs par cette politique.                                          |
| `angular#bundler`        | Cette politique est utilisée par le bundler d'Angular CLI lors de la création des fichiers de chunks chargés en lazy loading.                                                                                                                                                                                                             |
| `angular#unsafe-bypass`  | Cette politique est utilisée par les applications qui utilisent l'une des méthodes du [DomSanitizer](api/platform-browser/DomSanitizer) d'Angular contournant la sécurité, comme `bypassSecurityTrustHtml`. Toute application qui utilise ces méthodes doit activer cette politique.                                  |
| `angular#unsafe-jit`     | Cette politique est utilisée par le [compilateur Just-In-Time (JIT)](api/core/Compiler). Vous devez activer cette politique si votre application interagit directement avec le compilateur JIT ou s'exécute en mode JIT à l'aide de [platform browser dynamic](api/platform-browser-dynamic/platformBrowserDynamic). |
| `angular#unsafe-upgrade` | Cette politique est utilisée par le package [@angular/upgrade](api/upgrade/static/UpgradeModule). Vous devez activer cette politique si votre application est une application hybride AngularJS.                                                                                                                           |

Vous devez configurer les en-têtes HTTP pour les Trusted Types aux emplacements suivants :

- L'infrastructure de production qui sert l'application
- Angular CLI $`ng serve`$, à l'aide de la propriété `headers` du fichier `angular.json`, pour le développement local et les tests de bout en bout
- Karma $`ng test`$, à l'aide de la propriété `customHeaders` du fichier `karma.config.js`, pour les tests unitaires

Voici un exemple d'en-tête configuré spécifiquement pour les Trusted Types et Angular :

```html
Content-Security-Policy: trusted-types angular; require-trusted-types-for 'script';
```

Un exemple d'en-tête configuré spécifiquement pour les Trusted Types et les applications Angular qui utilisent l'une des méthodes du [DomSanitizer](api/platform-browser/DomSanitizer) d'Angular contournant la sécurité :

```html
Content-Security-Policy: trusted-types angular angular#unsafe-bypass; require-trusted-types-for
'script';
```

Voici un exemple d'en-tête configuré spécifiquement pour les Trusted Types et les applications Angular utilisant le JIT :

```html
Content-Security-Policy: trusted-types angular angular#unsafe-jit; require-trusted-types-for
'script';
```

Voici un exemple d'en-tête configuré spécifiquement pour les Trusted Types et les applications Angular qui chargent des modules en lazy loading :

```html
Content-Security-Policy: trusted-types angular angular#bundler; require-trusted-types-for 'script';
```
Pour en savoir plus sur le dépannage des configurations Trusted Types, la ressource suivante peut être utile :

[Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types](https://web.dev/trusted-types/#how-to-use-trusted-types)
### Utiliser le compilateur de templates AOT {#use-the-aot-template-compiler}

Le compilateur de templates AOT empêche toute une catégorie de vulnérabilités appelées injections de template, et améliore grandement les performances de l'application.
Le compilateur de templates AOT est le compilateur utilisé par défaut par les applications Angular CLI, et vous devez l'utiliser dans tous vos déploiements de production.

Une alternative au compilateur AOT est le compilateur JIT, qui compile les templates en code de template exécutable dans le navigateur, à l'exécution.
Angular fait confiance au code des templates : générer dynamiquement des templates et les compiler, en particulier des templates contenant des données utilisateur, contourne donc les protections intégrées d'Angular. C'est un anti-pattern de sécurité.
Pour savoir comment construire dynamiquement des formulaires de manière sûre, consultez le guide [Formulaires dynamiques](guide/forms/dynamic-forms).

### Protection XSS côté serveur {#server-side-xss-protection}

Le HTML construit sur le serveur est vulnérable aux attaques par injection.
Injecter du code de template dans une application Angular revient à injecter du code exécutable dans l'application :
cela donne à l'attaquant le contrôle total de l'application.
Pour l'éviter, utilisez sur le serveur un langage de templating qui échappe automatiquement les valeurs afin de prévenir les vulnérabilités XSS.
Ne créez pas de templates Angular côté serveur à l'aide d'un langage de templating. Cela comporte un risque élevé d'introduire des vulnérabilités d'injection de template.

## Vulnérabilités au niveau HTTP {#http-level-vulnerabilities}

Angular intègre une prise en charge permettant d'aider à prévenir deux vulnérabilités HTTP courantes : la falsification de requête intersites $CSRF ou XSRF$ et l'inclusion de script intersites $XSSI$.
Ces deux vulnérabilités doivent être traitées principalement côté serveur, mais Angular fournit des utilitaires qui facilitent l'intégration côté client.

### Falsification de requête intersites {#cross-site-request-forgery}

Dans une falsification de requête intersites $CSRF ou XSRF$, un attaquant incite l'utilisateur à visiter une autre page web $comme `evil.com`$ contenant du code malveillant. Cette page web envoie secrètement une requête malveillante au serveur web de l'application $comme `example-bank.com`$.

Supposons que l'utilisateur soit connecté à l'application sur `example-bank.com`.
L'utilisateur ouvre un e-mail et clique sur un lien vers `evil.com`, qui s'ouvre dans un nouvel onglet.

La page `evil.com` envoie immédiatement une requête malveillante à `example-bank.com`.
Il s'agit peut-être d'une requête de virement depuis le compte de l'utilisateur vers celui de l'attaquant.
Le navigateur envoie automatiquement avec cette requête les cookies de `example-bank.com`, y compris le cookie d'authentification.

Si le serveur de `example-bank.com` ne dispose pas de protection XSRF, il ne peut pas distinguer une requête légitime provenant de l'application de la requête falsifiée provenant de `evil.com`.

Pour l'éviter, l'application doit s'assurer qu'une requête utilisateur provient bien de la véritable application, et non d'un autre site.
Le serveur et le client doivent coopérer pour déjouer cette attaque.

Dans une technique anti-XSRF courante, le serveur de l'application envoie un jeton d'authentification créé aléatoirement dans un cookie.
Le code client lit le cookie et ajoute un en-tête de requête personnalisé contenant le jeton à toutes les requêtes suivantes.
Le serveur compare la valeur du cookie reçu à celle de l'en-tête de requête et rejette la requête si les valeurs sont absentes ou ne correspondent pas.

Cette technique est efficace parce que tous les navigateurs implémentent la _same-origin policy_ (politique de même origine).
Seul le code du site web sur lequel les cookies sont définis peut lire les cookies de ce site et définir des en-têtes personnalisés sur les requêtes envoyées à ce site.
Cela signifie que seule votre application peut lire ce jeton de cookie et définir l'en-tête personnalisé.
Le code malveillant de `evil.com` ne le peut pas.

### Sécurité XSRF/CSRF de `HttpClient` {#httpclient-xsrf-csrf-security}

`HttpClient` prend en charge un [mécanisme courant](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token) utilisé pour prévenir les attaques XSRF. Lors de l'exécution de requêtes HTTP, un intercepteur lit un jeton depuis un cookie, par défaut `XSRF-TOKEN`, et le définit comme en-tête HTTP, `X-XSRF-TOKEN`. Comme seul le code qui s'exécute sur votre domaine peut lire le cookie, le backend peut être certain que la requête HTTP provient de votre application cliente et non d'un attaquant.

Par défaut, un intercepteur envoie cet en-tête sur toutes les requêtes modifiantes (comme `POST`) vers des URL relatives et de même origine, mais pas sur les requêtes `GET` ou `HEAD`.
La protection CSRF n'est nécessaire que pour les requêtes susceptibles de modifier l'état du backend. Par nature, les attaques CSRF franchissent les frontières de domaine, et la [same-origin policy](https://developer.mozilla.org/docs/Web/Security/Same-origin_policy) du web empêche une page malveillante de récupérer les résultats de requêtes `GET` authentifiées.
Pour en tirer parti, votre serveur doit définir un jeton dans un cookie de session lisible par JavaScript, appelé `XSRF-TOKEN`, soit au chargement de la page, soit lors de la première requête GET. Lors des requêtes suivantes, le serveur peut vérifier que le cookie correspond à l'en-tête HTTP `X-XSRF-TOKEN`, et donc être sûr que seul du code s'exécutant sur votre domaine a pu envoyer la requête. Le jeton doit être unique pour chaque utilisateur et vérifiable par le serveur ; cela empêche le client de fabriquer ses propres jetons. Pour plus de sécurité, définissez le jeton comme un condensé du cookie d'authentification de votre site, avec un sel.

Pour éviter les collisions dans les environnements où plusieurs applications Angular partagent le même domaine ou sous-domaine, donnez à chaque application un nom de cookie unique.
  Votre service backend doit être configuré pour définir le cookie de votre page et pour vérifier que l'en-tête est présent sur toutes les requêtes concernées. Sans cela, la protection par défaut d'Angular est inefficace.
### Configurer des noms de cookie et d'en-tête personnalisés {#configure-custom-cookie-header-names}

Si votre service backend utilise des noms différents pour le cookie ou l'en-tête du jeton XSRF, utilisez `withXsrfConfiguration` pour remplacer les valeurs par défaut.

Ajoutez-le à l'appel `provideHttpClient` comme suit :

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'CUSTOM_XSRF_TOKEN',
        headerName: 'X-Custom-Xsrf-Header',
      }),
    ),
  ],
};
```

### Désactiver la protection XSRF {#disabling-xsrf-protection}

Si le mécanisme de protection XSRF intégré ne fonctionne pas pour votre application, vous pouvez le désactiver avec la fonctionnalité `withNoXsrfProtection` :

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withNoXsrfProtection())],
};
```

Pour plus d'informations sur la CSRF selon l'Open Web Application Security Project $OWASP$, consultez [Cross-Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) et [Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html).
L'article de l'université Stanford [Robust Defenses for Cross-Site Request Forgery](https://seclab.stanford.edu/websec/csrf/csrf.pdf) est une source riche en détails.

Voir aussi la [conférence de Dave Smith sur le XSRF à AngularConnect 2016](https://www.youtube.com/watch?v=9inczw6qtpY 'Cross Site Request Funkery Securing Your Angular Apps From Evil Doers').

### Inclusion de script intersites (XSSI) {#cross-site-script-inclusion-xssi}

L'inclusion de script intersites, également appelée vulnérabilité JSON, peut permettre au site web d'un attaquant de lire les données d'une API JSON.
L'attaque fonctionne sur les anciens navigateurs en remplaçant les constructeurs d'objets JavaScript intégrés, puis en incluant une URL d'API à l'aide d'une balise `<script>`.

Cette attaque ne réussit que si le JSON renvoyé est exécutable en tant que JavaScript.
Les serveurs peuvent prévenir une attaque en préfixant toutes les réponses JSON pour les rendre non exécutables, par convention avec la chaîne bien connue `")]}',\n"`.

La library `HttpClient` d'Angular reconnaît cette convention et supprime automatiquement la chaîne `")]}',\n"` de toutes les réponses avant de poursuivre l'analyse.

Pour plus d'informations, consultez la section XSSI de cet [article du blog Google sur la sécurité web](https://security.googleblog.com/2011/05/website-security-for-webmasters.html).

## Prévenir la falsification de requête côté serveur (SSRF) {#preventing-server-side-request-forgery-ssrf}

Angular inclut une validation stricte des en-têtes `Host`, `Forwarded`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Forwarded-Prefix` et `X-Forwarded-Port` dans le pipeline de traitement des requêtes, afin de prévenir la [falsification de requête côté serveur (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF) basée sur les en-têtes.

Les règles de validation sont les suivantes :

- `Host`, `X-Forwarded-Host` et le paramètre `host` de l'en-tête `Forwarded` sont validés par rapport à une liste d'autorisation stricte et ne peuvent pas contenir de séparateurs de chemin.
- L'en-tête `X-Forwarded-Port` doit être numérique.
- L'en-tête `X-Forwarded-Proto` et le paramètre `proto` de l'en-tête `Forwarded` doivent valoir `http` ou `https`.
- L'en-tête `X-Forwarded-Prefix` doit commencer par `/` et ne contenir que des caractères alphanumériques, des tirets et des underscores, séparés par des barres obliques simples.
- Par défaut, l'en-tête `Forwarded` et tous les en-têtes `X-Forwarded-*` sont considérés comme non fiables et sont supprimés de la requête. Pour les conserver, ils doivent être explicitement autorisés via la configuration de `trustProxyHeaders`.

Les en-têtes invalides déclenchent un log d'erreur, et les en-têtes de proxy non autorisés sont supprimés de la requête. Les requêtes avec des noms d'hôte non reconnus aboutissent à une réponse `400 Bad Request`.

NOTE: La plupart des fournisseurs cloud et des fournisseurs de CDN effectuent automatiquement la validation de ces en-têtes avant même qu'une requête n'atteigne l'origine de l'application. Ce filtrage inhérent réduit considérablement la surface d'attaque en pratique.

### Configurer les hôtes autorisés {#configuring-allowed-hosts}

Pour autoriser des noms d'hôte spécifiques, vous devez les ajouter à la liste d'autorisation. C'est essentiel pour garantir que votre application fonctionne correctement et de manière sûre une fois déployée. Les motifs prennent en charge les wildcards pour une correspondance flexible des noms d'hôte.

Vous pouvez configurer l'option `allowedHosts` dans votre `angular.json` :

```json
{hideCopy}
{
  // ...
  "projects": {
    "your-project-name": {
      // ...
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "security": {
              "allowedHosts": [
                "example.com",
                "*.example.com" // allows all subdomains of example.com
              ]
            }
            // ... other options
          }
        }
      }
    }
  }
}
```

Vous pouvez aussi configurer `allowedHosts` lors de l'initialisation du moteur de l'application :

```typescript
const appEngine = new AngularAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});

const nodeAppEngine = new AngularNodeAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});
```

Pour la variante Node.js `AngularNodeAppEngine`, vous pouvez aussi fournir la variable d'environnement `NG_ALLOWED_HOSTS` (liste séparée par des virgules) pour autoriser des hôtes.

```bash
{hideDollar}
export NG_ALLOWED_HOSTS="example.com,*.trusted-example.com"
```

IMPORTANT: Vous pouvez utiliser `*` comme valeur dans `allowedHosts` pour autoriser tous les noms d'hôte, mais c'est généralement déconseillé et cela présente un risque de sécurité. Accepter n'importe quel en-tête host peut exposer votre application à des attaques par injection d'en-tête host et à des attaques de [falsification de requête côté serveur (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF). Cette configuration ne doit être utilisée que lorsque la validation des en-têtes `Host` et `X-Forwarded-Host` est effectuée dans une autre couche, comme un load balancer ou un reverse proxy. Pour une meilleure sécurité, nous recommandons d'utiliser une liste explicite d'hôtes autorisés chaque fois que possible. Consultez [GHSA-x288-3778-4hhx](https://github.com/angular/angular-cli/security/advisories/GHSA-x288-3778-4hhx) pour plus de détails.

### Configurer les en-têtes de proxy de confiance {#configuring-trusted-proxy-headers}

Par défaut, Angular ignore l'en-tête standard `Forwarded` et tous les en-têtes `X-Forwarded-*`. Si votre application se trouve derrière un reverse proxy de confiance (comme un load balancer) qui définit ces en-têtes, vous pouvez configurer Angular pour qu'il leur fasse confiance.

Si l'en-tête `Forwarded` est de confiance, ses paramètres `host` et `proto` sont extraits et prennent le pas sur les en-têtes `x-forwarded-host` et `x-forwarded-proto` correspondants.

Vous pouvez configurer `trustProxyHeaders` lors de l'initialisation du moteur de l'application :

```typescript
const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['forwarded'], // Trust the standard Forwarded header
});

const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['x-forwarded-host', 'x-forwarded-proto'], // Trust non-standard headers
});

const nodeAppEngine = new AngularNodeAppEngine({
  trustProxyHeaders: true, // Trust standard Forwarded and all X-Forwarded-* headers
});
```

Pour la variante Node.js `AngularNodeAppEngine`, vous pouvez aussi fournir la variable d'environnement `NG_TRUST_PROXY_HEADERS` (avec comme valeur une liste d'en-têtes séparés par des virgules) pour autoriser l'utilisation de ces en-têtes.

```bash
{hideDollar}
export NG_TRUST_PROXY_HEADERS="X-FORWARDED-HOST,X-FORWARDED-PREFIX"
```

IMPORTANT: N'activez `trustProxyHeaders` que si votre application se trouve derrière un proxy de confiance qui valide strictement ou remplace ces en-têtes. Sinon, des attaquants peuvent usurper ces en-têtes pour provoquer des attaques de [falsification de requête côté serveur (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF).

## Auditer les applications Angular {#auditing-angular-applications}

Les applications Angular doivent suivre les mêmes principes de sécurité que les applications web classiques, et doivent être auditées comme telles.
Les API propres à Angular qui doivent être auditées lors d'une revue de sécurité, comme les méthodes [_bypassSecurityTrust_](#trusting-safe-values), sont signalées dans la documentation comme sensibles du point de vue de la sécurité.