Formations — 1 037 leçons en français

Accueil › Angular › Angular Elements et Web Components

Angular Elements et Web Components

Patterns avancés et interopérabilitéavance

Angular Elements (@angular/elements) transforme un composant Angular en Web Component : un élément HTML personnalisé, utilisable dans n'importe quelle page — Angular ou non — via customElements.define(). Cas d'usage réel : un widget (avis produit, chat, calculateur de livraison) à intégrer dans un site tiers non-Angular, ou dans une grande application existante qu'on migre progressivement composant par composant.

import { createCustomElement } from '@angular/elements';

const injector = createApplication(...).then(appRef => appRef.injector); // ou l'injecteur d'une app Angular existante
const ElementAvisProduit = createCustomElement(AvisProduit, { injector });
customElements.define('avis-produit', ElementAvisProduit);
<!-- dans une page qui n'a jamais entendu parler d'Angular -->
<avis-produit produit-id="42"></avis-produit>

Les entrées (input()) se transmettent en attributs HTML (chaînes) pour les valeurs simples, ou en propriétés JavaScript pour les objets. Les sorties (output()) deviennent des CustomEvent DOM standards, avec la valeur émise dans event.detail.

Dans l'autre sens — consommer un Web Component tiers dans un template Angular — le compilateur refuse par défaut les balises et propriétés qu'il ne connaît pas. Il faut ajouter schemas: [CUSTOM_ELEMENTS_SCHEMA] au composant qui l'utilise, puis lier propriétés et événements comme sur n'importe quel élément DOM.

Limites à connaître : chaque élément personnalisé embarque le runtime Angular nécessaire à son fonctionnement (un widget isolé pèse plus lourd qu'un composant JS natif équivalent), et une entrée complexe doit être passée en propriété JavaScript, pas en attribut.

Les termes à connaître

Web Component

Standard du navigateur (Custom Elements + Shadow DOM) permettant de définir un élément HTML personnalisé (<mon-widget>) utilisable dans n'importe quelle page, quelle que soit la technologie qui l'a produit.

createCustomElement()

Fonction de @angular/elements qui transforme un composant Angular en classe conforme à l'API Custom Elements du navigateur. Signature : createCustomElement(MonComposant, { injector }).

customElements.define()

API native du navigateur qui enregistre une classe d'élément personnalisé sous un nom de balise (obligatoirement avec un tiret, ex. avis-produit). Une fois enregistrée, la balise peut être utilisée dans n'importe quel HTML, y compris hors d'Angular.

CUSTOM_ELEMENTS_SCHEMA

Schéma à ajouter aux métadonnées d'un composant Angular pour autoriser dans son template des balises et propriétés inconnues du compilateur (typiquement des Web Components tiers), sans lever d'erreur de compilation.

CustomEvent / detail

Les sorties (output()) d'un composant transformé en élément personnalisé sont émises comme des CustomEvent DOM standards ; la valeur émise se trouve dans la propriété detail de l'événement.

Attribut vs propriété

Un attribut HTML est toujours une chaîne de caractères ; une propriété JavaScript peut contenir n'importe quelle valeur (objet, tableau). Les entrées simples d'un élément Angular Elements peuvent être passées en attribut, mais une entrée complexe (objet, tableau) doit être affectée en propriété JavaScript (element.produit = {...}).

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.