Angular Elements résout le problème de la réutilisation du code sur plusieurs frameworks et fournit un moyen d'utiliser les composants angulaires dans des environnements non-angulaires. Apprenez comment vous pouvez commencer à les utiliser dans vos applications aujourd'hui.

Angular est génial. C'est un cadre robuste et complet avec beaucoup de puissance sous le capot. Ne serait-ce pas agréable, cependant, de pouvoir utiliser Angular dans différents contextes sans tous les frais généraux? Peut-être que vous avez besoin de partager un datpick angulaire personnalisé avec d'autres équipes utilisant d'autres cadres. Peut-être que vous avez besoin d'intégrer une petite application angulaire dans un CMS. Ou, peut-être souhaitez-vous utiliser des composants Angular à l'intérieur de votre ancienne application AngularJS comme alternative à la bibliothèque ngUpgrade.

Voici les problèmes résolus par la bibliothèque Angular Elements. Angular Elements est un projet sous Angular Labs, le parapluie de l'équipe Angular pour de nouvelles idées expérimentales. Angular Labs permet à l'équipe d'innover sans casser votre application. La première version expérimentale d'Elements est devenue une partie de Angular 6. C'est un produit minimum viable qui n'est pas encore prêt pour la production à part entière, mais nous devrions voir une version plus raffinée des éléments dans Angular 7.

Alors, quel est exactement le

Composants Web et éléments personnalisés

Avant d'explorer Angular Elements, nous devons en apprendre un peu plus sur les composants Web.

Angular Elements vous permet d'empaqueter votre Angular des composants en tant qu'éléments Web personnalisés qui font partie de l'ensemble d'API de plate-forme Web . Les composants Web sont des technologies permettant de créer des éléments réutilisables et encapsulés. À l'heure actuelle, cela comprend les shadow DOM modèles HTML HTML importations et éléments personnalisés . La technologie des éléments personnalisés alimente les éléments angulaires.

Les éléments personnalisés sont des balises HTML réutilisables et encapsulées à utiliser dans les pages Web et les applications Web. Ils peuvent être utilisés dans n'importe quel cadre ou bibliothèque qui utilise le HTML. En bref, vous pouvez créer des éléments DOM personnalisés qui ont leurs propres fonctionnalités dont le reste de la page n'a pas besoin de savoir quoi que ce soit. (Vous pouvez également modifier les éléments DOM existants, mais nous ne le ferons pas avec Angular Elements.)

Pour créer un élément personnalisé, vous devez simplement créer une classe ES6 qui s'étend à partir d'un élément HTML et enregistrer cette classe avec le navigateur via une API appelée CustomElementRegistry . Les éléments personnalisés ont des hooks de cycle de vie, tels que connectedCallback et disconnectedCallback . Ils vous permettent également d'enregistrer votre intérêt pour les attributs, qui peuvent également avoir des rappels et des propriétés associées. Et enfin, comme d'autres éléments DOM, les éléments personnalisés peuvent avoir des événements associés à eux en utilisant addEventListener .

Qu'est-ce que Angular Elements?

La bibliothèque Angular Elements est essentiellement un pont entre les composants angulaires et la custom API des éléments web. Avec les éléments angulaires, les composants angulaires agissent comme hôtes pour les éléments personnalisés. Les entrées angulaires sont mappées aux propriétés, les liaisons d'hôtes sont mappées aux attributs, les sorties sont mappées aux événements et les mappages de cycle de vie correspondent aux hooks de cycle de vie des éléments personnalisés. Comme vous pouvez le voir, Angular a été conçu pour s'interfacer facilement avec l'API DOM, et les éléments personnalisés ne font pas exception.

Angular Elements permet également de tirer parti de l'injection de dépendance d'Angular. Lorsque nous créons un élément personnalisé à l'aide d'Angular Elements, nous transmettons une référence à l'injecteur du module en cours. Cet injecteur nous permet de partager le contexte entre plusieurs éléments ou d'utiliser des services partagés.

Nous obtenons également la projection de contenu (transclusion) avec les éléments angulaires, avec quelques mises en garde. Le projet de contenu fonctionne correctement lors du premier rendu de la page, mais pas encore avec la projection de contenu dynamique. À ce jour, nous ne disposons pas encore de support pour les requêtes ContentChild ou ContentChildren . Cependant, la projection de contenu devrait être plus robuste avec le temps, et nous aurons aussi la possibilité d'utiliser les slots et le DOM shadow quand le support du navigateur augmentera.

Use Cases

Si vous avez utilisé AngularJS (1.x) , vous avez peut-être apprécié à quel point c'était flexible. Vous pouvez utiliser AngularJS dans de nombreux endroits: à l'intérieur d'un CMS, à l'intérieur d'une application Microsoft MVC ou en tant que SPA à part entière (application monopage). Angular (2+) est un framework beaucoup plus robuste et a été conçu comme un outil pour construire des applications complètes et complètes. Les éléments angulaires vont redonner de la souplesse à Angular, mais avec beaucoup plus de fonctionnalités que AngularJS pourrait fournir.

Alors, où utiliserions-nous les éléments angulaires? Rob Wormald a couvert trois zones principales avec des exemples dans sa ng-conf 2018 parle sur Angular Elements :

Elements dans Apps

• CMS embarque
• Composants dynamiques
• Rendu serveur / hybride

Élément Conteneurs

• Mini-applications
• Micro-frontend
• ngUpgrade (un favori personnel)
• SharePoint

Widgets réutilisables

• Compatibilité cross-framework
• Matériel / Composants CDK dans n'importe quel environnement
• Systèmes de conception – construire une fois, utiliser n'importe où

Essentiellement, partout où vous pensez que vous pourriez avoir besoin d'Angular, vous pourrez l'utiliser avec des éléments angulaires. La version actuelle d'Elements a été optimisée pour les applications et les conteneurs, mais il reste encore du travail à faire pour les widgets réutilisables. Cela nous amène à notre sujet: les défis auxquels font face les éléments angulaires aujourd'hui.

Les obstacles à l'utilisation de la production

Alors que les éléments angulaires semblent très prometteurs à partir de l'Angulaire 6, il reste encore quelques défis à surmonter. Prêt pour l'utilisation en production:

1. Taille du paquet: Actuellement, que vous envoyiez un petit widget ou une application complète en tant qu'élément personnalisé, beaucoup d'Angular l'accompagnent. Cela rend la taille de l'ensemble résultant de votre élément personnalisé assez grande. Heureusement, Ivy, la prochaine génération du compilateur d'Angular, résoudra ce problème. Ivy est optimisé pour enlever les morceaux d'Angular inutilisés et créer des faisceaux plus petits, donc c'est une correspondance faite au paradis pour les éléments angulaires. Vous pouvez en apprendre plus sur Ivy dans mon article First Look: Angular Ivy .
2. Étapes à suivre: Comme vous le verrez dans un moment où nous construisons notre premier élément, certains de l'installation et de l'emballage d'Angular Elements est un peu maladroit en ce moment. C'est à prévoir d'une première version, et je ne voudrais pas le transpirer. Compte tenu de la façon dont l'ICA Angular s'est développée au cours de la dernière année, je suis certain que ce processus sera peaufiné. Ivy va également aider avec cela, car le support et l'optimisation des éléments angulaires seront cuits dès le début.
3. Support du navigateur: Le support du navigateur pour les éléments personnalisés s'améliore, mais ce n'est toujours pas le cas Là. La plupart des navigateurs ont au moins un support expérimental d'éléments personnalisés, mais, à ce jour, les éléments personnalisés ne sont pas encore pris en charge dans Internet Explorer ou Edge. Malheureusement, ceci est une zone en dehors du contrôle de l'équipe Angular. En attendant, nous pouvons utiliser les polyfills pour ajouter un support de navigateur, bien que cela ajoute au clunkiness d'installation et à la taille globale de l'ensemble. J'espère que nous n'aurons pas besoin d'utiliser ces polyfills trop longtemps, mais vous pouvez voir cette table pratique de support de navigateur d'éléments personnalisés pour rester à jour avec le statut.

Premiers pas avec les éléments angulaires

Maintenant que nous connaissons tous les éléments angulaires, créons notre propre élément personnalisé réutilisable! Nous allons créer un clone simplifié de l'extension Chrome Momentum dashboard en tant que composant réutilisable. C'est simple, mais nous utiliserons une directive @Input la directive * ngIf et une variable template juste pour voir la magie angulaire utilisée hors contexte.

Juste un rappel, Les éléments angulaires en sont encore aux premiers jours, donc de nouvelles mises à jour peuvent casser des choses, et votre environnement de développement peut affecter certaines de ces étapes.

Créer et configurer le projet [19659006PouryarrivernousallonscréerunnouveauprojetAngularCLIetyajouterdeséléments

Tout d'abord, assurez-vous que l'interface CLI Angular est installée globalement (et assurez-vous qu'il s'agit de la dernière version, au moins 6.0. 8 au moment de la rédaction de cet article):

 npm install -g @ angular / cli 

Créons notre application avec la CLI. Une fois l'installation terminée, naviguez dans le dossier avec cd et ouvrez-le avec votre éditeur favori (j'utilise Visual Studio Code).

 ng new momentum-element
cd momentum-element 

Nous pouvons ajouter des éléments angulaires à notre projet en utilisant la commande ng add et passer au nom de notre projet.

 ng add @ angular / elements --project = momentum- element 

Non seulement cette commande ajoute des éléments angulaires, mais elle ajoute aussi un polyfill appelé document-register-element et l'ajoute à la section scripts de notre fichier de configuration CLI Angular ( angular.json ). Ce polyfill ajoute la prise en charge de l'API des éléments personnalisés.

Créer le composant

Maintenant que nous sommes configurés, créons notre composant. Nous allons simplement réutiliser notre AppComponent généré par l'interface de ligne de commande (il se trouve dans / src / app ). Remplacez le code dans app.component.ts par ce qui suit:

 import {Component, ViewEncapsulation, Input} à partir de '@ angular / core';

@Composant({
  selector: 'app-momentum-element',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
  encapsulation: ViewEncapsulation.Native
})

classe d'exportation AppComponent {
  @Input () nom = 'ami';
  focus: chaîne de caractères;
  focusSet = false;
  setFocus (valeur) {
    this.focus = valeur;
    this.focusSet = true;
  }
} 

Quelques notes à ce sujet. Tout d'abord, le sélecteur n'aura pas d'importance ici, car nous enregistrerons ce composant en tant qu'élément personnalisé avec son propre tag. Deuxièmement, notez que nous utilisons ViewEncapulation.Native . La spécification d'une stratégie d'encapsulation affecte la façon dont nos styles sont appliqués aux composants. La valeur par défaut est appelée Emulated qui simule le DOM d'ombre afin d'avoir un style défini, même dans les navigateurs qui ne supportent pas le DOM d'ombre. Nous retournons ici le DOM réel en utilisant la stratégie Native .

A part ça, nous ne faisons que quelques choses simples ici. Nous créons un attribut @Input pour le nom que nous utiliserons par défaut "ami". Nous créons également une propriété de chaîne focus et une propriété boolean focusSet ainsi qu'une fonction qui définit cette propriété et bascule le booléen pour afficher et masquer la boîte de saisie. [19659003] Faisons le modèle suivant. Remplacez le contenu de app.component.html avec ceci:

  

    
 Bonjour, {{name}}. 
    
    

      
 Votre objectif principal aujourd'hui est: 
      
 {{focus}} 
    
  
 

Nous avons ici une entrée simple avec une variable template pour que l'utilisateur puisse taper un focus pour la journée, appuyez sur Entrée et il s'affichera. Rien de trop fou, mais nous profitons d'Angular pour rendre cela facile.

Enfin, ajoutons du style. Remplacez le contenu de app.component.css avec ceci:

 .widget-container {
  Couleur blanche;
  font-famille: arial;
  largeur: 400px;
  hauteur: 300px;
  position: relative;
  background-image: url ('https://source.unsplash.com/400x300?mountains,snow,high%20contrast');
}

.contenu {
  text-align: centre;
  position: absolue;
  en haut: 50%;
  gauche: 50%;
  transformer: traduire (-50%, -50%);
}

contribution {
  taille de police: 24px;
  bordure: 2px noir solide;
}

.concentrer {
  largeur: 300px;
  taille de police: 20px;
} 

C'est tout ce dont nous avons besoin pour faire fonctionner notre composant.

Créer un élément personnalisé

Jusqu'à présent, nous n'avons rien fait pour les éléments angulaires ici. En fait, vous pouvez mettre à jour index.html pour utiliser app-momentum-element au lieu de app-root exécutez ng serve et voir le composant de travail dans le navigateur, comme d'habitude.

Pour utiliser notre composant comme un widget réutilisable, nous avons juste besoin de modifier la manière dont notre AppModule s'amorce. Nous avons seulement besoin de faire deux choses pour le faire. Tout d'abord, au lieu d'avoir AppComponent dans un tableau bootstrap renommez ce tableau en entryComponents pour empêcher le composant d'amorcer avec le module:

 @NgModule ({
  déclarations: [AppComponent],
  importations: [BrowserModule],
  fournisseurs: [],
  entryComponents: [AppComponent]
}) 

Ensuite, nous devons créer l'élément personnalisé. Cela peut être fait dans quelques endroits différents, mais nous le ferons dans une fonction constructeur. Vous devrez ajouter Importer à la liste des importations @ angular / core et vous devrez importer createCustomElement à partir de @ angular / éléments . Une fois cela fait, ajoutez le constructeur comme ceci:

 constructeur (injecteur privé: Injecteur) {
  const el = createCustomElement (AppComponent, {injecteur});
  customElements.define ('momentum-element', el);
} 

Ici, nous appelons la fonction createCustomElement en passant dans notre composant et une instance de l'injecteur de notre module (nous utilisons la déstructuration ES6 ici, mais c'est équivalent à {injector: injecteur} ). Cette fonction renvoie une classe spéciale que nous pouvons utiliser avec l'API Custom Elements, où nous définissons notre élément en passant un sélecteur et la classe.

Enfin, nous devons ajouter ngDoBootstrap pour remplacer le bootstrap fonction. Notre AppModule terminé ressemblera à ceci:

 import {BrowserModule} de '@ angular / platform-browser';
importer {NgModule, Injector} à partir de '@ angular / core';
importer {createCustomElement} à partir de '@ angular / elements';
importez {AppComponent} à partir de './app.component';

@NgModule ({
  déclarations: [AppComponent],
  importations: [BrowserModule],
  fournisseurs: [],
  entryComponents: [AppComponent]
})

classe d'exportation AppModule {
  constructeur (injecteur privé: Injecteur) {
  const el = createCustomElement (AppComponent, {injecteur});
  customElements.define ('momentum-element', el);
}

ngDoBootstrap () {}
} 

C'est tout!

Conditionnement des éléments angulaires

Jusqu'à présent, nous avons créé un composant et l'avons transformé en élément personnalisé. Maintenant, nous devons l'empaqueter pour qu'il puisse être utilisé ailleurs avec une étiquette de script. Cela signifie que nous devons non seulement construire l'application comme nous le ferions normalement, mais concaténer tous les fichiers de script que l'interface de ligne de commande produit en un seul fichier.

Je vais vous dire que c'est la partie la plus difficile de ce processus en ce moment. Il y a plusieurs façons d'accomplir ceci:

Je vais vous montrer l'approche Node aujourd'hui, car elle semble fonctionner sur plusieurs plates-formes sans problème. À l'avenir, cependant, je suis sûr qu'il y aura un schéma CLI pour Angular Elements qui génère une structure de fichiers plate et regroupe en un seul fichier. N'oubliez pas, nous commençons seulement avec le potentiel pour Elements!

Pour créer un script de génération de Node, vous devrez installer deux autres dépendances:

 npm install --save-dev concat fs- extra 

Ensuite, à la racine de notre projet, créez un fichier appelé elements-build.js et collez-le dans:

 const fs = require ('fs-extra');
const concat = require ('concat');

(async function build () {
  fichiers const = [
    './dist/momentum-element/runtime.js',
    './dist/momentum-element/polyfills.js',
    './dist/momentum-element/scripts.js',
    './dist/momentum-element/main.js'
  ];

  attendez fs.ensureDir ('elements');
  wait concat (fichiers, 'elements / momentum-element.js');
  attendez fs.copyFile (
    './dist/momentum-element/styles.css',
    'elements / styles.css'
  )
}) (); 

Ce script prendra tous les scripts générés par l'interface de ligne de commande et les combinera en un seul fichier. Il va également déplacer le fichier CSS, mais puisque nous utilisons l'encapsulation native, ce fichier sera vide.

Ensuite, créez un dossier à la racine du projet appelé elements . C'est ici que nous conserverons les fichiers concaténés, ainsi que le fichier HTML que nous utiliserons pour tester notre élément personnalisé.

Maintenant, ouvrez package.json et ajoutez un nouveau script: [19659043] "build: elements": "ng build –prod –output-hachage none && node elements-build.js"

Nous lançons la commande de construction CLI avec le drapeau prod et exécutons ensuite notre script de construction avec

Enfin, dans ce nouveau dossier elements créez un fichier appelé index.html et collez le dans:

N'hésitez pas à remplacer mon nom par le vôtre dans l'attribut !

C'est tout ce que nous devons faire pour obtenir une construction fonctionnelle d'un élément personnalisé.

en action

Voyons si tout cela fonctionne réellement. Tout d'abord, lancez notre nouveau script de compilation:

 npm run build: elements 

Vous devriez voir momentum-element.js et momentum-element.css dans le le fichier elements à côté de notre fichier HTML. Vous verrez que le fichier script fait environ 200 Ko en ce moment, ce qui est un peu gros pour quelque chose d'aussi simple. Ne vous inquiétez pas, cependant, Ivy vous aidera à réduire cela un peu dans le futur.

Maintenant, servons ce dossier. Vous voudrez installer un simple serveur HTTP. J'aime utiliser static-server :

 npm installer -g static-server 

Vous pouvez ensuite cd dans ce dossier et démarrer le serveur:

 cd éléments
static-server 

Lorsque vous naviguez vers localhost: 9080 (dans un navigateur qui supporte les éléments personnalisés, comme Chrome), vous devriez voir votre élément personnalisé!

]

Nous avons nous-mêmes un élément personnalisé entièrement fonctionnel! N'hésitez pas à expérimenter et à construire sur cet exemple. Vous pouvez ajouter plusieurs instances de cet élément pour effectuer le DOM avec des entrées de nom différentes. Vous pouvez également ajouter des écouteurs d'événements personnalisés pour interagir avec d'autres éléments. Essayez de déposer cet élément personnalisé dans une application React ou Vue! Vous pouvez consulter mon code terminé à ce dépôt GitHub .

Note: si vous obtenez une erreur comme Impossible de construire 'HTMLElement' vous pouvez avoir un problème de version de paquet. Je recevais cette erreur lorsque j'ai créé un projet avec une ancienne version de l'interface de ligne de commande, même lorsque j'ai essayé de mettre à jour manuellement. Une fois que j'ai mis à jour ma version globale de la CLI et généré le projet, cela a fonctionné. Bien sûr, vous ne pourrez pas exécuter cet élément personnalisé dans IE ou Edge.

Conclusion

J'espère que vous avez commencé à comprendre la puissance des éléments angulaires. La flexibilité des éléments personnalisés signifie qu'il existe un éventail vertigineux de possibilités pour utiliser votre code angulaire dans les équipes, les frameworks et même les technologies. Il y a encore quelques choses à marteler avec l'utilisation et l'outillage autour des éléments angulaires, mais cette première version ressemble à une base solide pour la prochaine version!

Pour creuser plus profondément dans les éléments angulaires et les éléments personnalisés en général, consultez ces ressources :

Articles

Vidéos