){kind=small}
Créer un composant Web avec Open-WC
Temps de lecture : 7 minutes
Dans les chapitres précédents de cette série, nous avons abordé les sujets suivants ce que sont les composants Web et quelques outils utilisés pour les créer. Nous allons maintenant créer un composant Web, le publier et l'utiliser sur une page Web.
Qu'allons-nous fabriquer ? Un composant de clavier utilisant Composants Web Material Design. Construire un composant Web composé de composants Web, plutôt méta, je sais.
L'idée est de pouvoir insérer un clavier dans un projet avec le moins de difficultés possible. Avec seulement quelques lignes de code, un utilisateur peut disposer d'un moyen de saisir des nombres dans une application pour passer un appel téléphonique, régler la température, sélectionner une réponse à un quiz, voter, et bien d'autres applications encore.
Dressons la liste des caractéristiques de l'élément de clavier qui sera construit :
Le composant Web prêt à l'emploi affiche un écran et, en dessous, des boutons avec les chiffres 0-9, * et #.
L'utilisateur pourra masquer l'affichage et les boutons *,# en définissant des attributs et des propriétés.
Lorsqu'un utilisateur clique sur un bouton, un caractère est ajouté à l'écran. En même temps, un événement personnalisé sera envoyé pour que l'application extérieure au composant sache qu'un bouton a été pressé.
Il y aura un bouton "Action" qui enverra tous les chiffres pressés en tant qu'événement personnalisé pour que la plus grande application puisse les traiter comme elle l'entend. Le texte du bouton peut être défini par l'utilisateur au moyen d'une propriété.
Un autre bouton sera mis à la disposition de l'utilisateur pour mettre fin à l'action. Son texte sera également personnalisable. Lorsque l'utilisateur appuie sur ce bouton, l'écran s'efface et un autre événement personnalisé est envoyé à l'application pour qu'elle en prenne connaissance.
Le composant Web disposera d'une méthode publique permettant à l'application de passer à l'état "actif" et d'afficher le bouton "Fin".
Pour ajouter un peu de style au composant Web, les composants de bouton et de champ de texte Material Design seront utilisés.
Voici un exemple fonctionnel sur CodePen
Voir le stylo le clavier de votre choix par conshus de OUR show (@conshus) sur CodePen.
Saisissez quelques chiffres et appuyez sur la touche Entrée. Cliquez sur ok sur l'alerte, puis cliquez sur annuler.
Comment allons-nous construire ce composant clavier ? Nous utiliserons lit-html par le biais d'Open Web Components (Open-WC). Comme indiqué sur leur site web:
L'objectif d'Open Web Components est de permettre à chacun de disposer d'une configuration puissante et éprouvée pour le partage de composants web open source. Nous essayons d'atteindre cet objectif en donnant un ensemble de recommandations et de valeurs par défaut sur la façon de faciliter votre projet de composants web. Nos recommandations comprennent : le développement, le linting, le test, l'outillage, la démonstration, la publication et l'automatisation.
En commençant par l'Open-WC, tous les membres d'une équipe peuvent avoir le même point de départ pour construire des composants web. Comme pour beaucoup de choses, la cohérence est un facteur de réussite.
Comme Open-WC est très attaché à la façon dont les composants Web et les projets sont construits, ils ont un outil CLI très complet pour les générer. Mettons tout en place.
Dans votre terminal, naviguez jusqu'à l'endroit où se trouvera le projet de composant Web.
Tapez ensuite npm init @open-wc. Cela lancera le processus d'installation d'Open-WC.
Voici les options que j'ai utilisées pour le projet de cet article de blog :
Que voulez-vous faire aujourd'hui ? Echafauder un nouveau projet
Qu'est-ce que vous aimeriez échafauder ? Composant Web
Qu'aimeriez-vous ajouter ? Linting (eslint & prettier)
Souhaitez-vous utiliser un texte dactylographié ? Non
Quel est le nom de balise de votre application/composant Web ? whatever-you-like-keypad (Vous pouvez nommer le composant Web comme vous le souhaitez tant qu'il s'agit d'au moins 2 mots séparés par un "-").
Voulez-vous écrire cette structure de fichier sur le disque ? Oui
Voulez-vous installer des dépendances ? Oui, avec npm (si vous préférez yarn, vous pouvez le choisir)
Open-WC cli tool setup process
Pour installer le bouton et le champ de texte Material Design. Allez dans le nouveau dossier créé par le processus d'installation de l'Open-WC et tapez ce qui suit :
npm i @material/mwc-button
npm i @material/mwc-textfield
Installing Material Design button and text field
Le code du composant Web se trouve dans ce dépôt dépôt GitHub. Passons en revue le code dans le seul fichier du dossier src .
Il y a tout d'abord les importations. L'Open-WC recommande d'utiliser lit-html et l'élément lit-element pour construire et rendre le composant Web. Nous importons également le bouton et le champ de texte Material Design à utiliser dans le composant Web.
import { html, css, LitElement } from 'lit-element';
import '@material/mwc-button/mwc-button';
import '@material/mwc-textfield/mwc-textfield';Nous basons notre nouveau composant Web sur LitElement.
export class WhateverYouLikeKeypad extends LitElement {Styliser le composant Web
static get styles() {
return css`
:host {
display: block;
padding: 25px;
color: var(--vwc-dialer-text-color, #000);
}
#container {
width: 75vw;
max-width: 300px;
}
.button-row {
display: flex;
justify-content: space-evenly;
}
.full-width {
width: 100%;
}
mwc-button {
margin: 10px;
}
mwc-textfield {
--mdc-notched-outline-leading-width: 28px;
--mdc-notched-outline-leading-border-radius: 28px 0 0 28px;
--mdc-notched-outline-trailing-border-radius: 0 28px 28px 0;
width: 100%;
}
`;
}Ici, les attributs et les propriétés que le composant Web accepte sont définis avec leurs types. De cette manière, lit-html sait comment traiter les valeurs transmises.
static get properties() {
return {
noAsterisk: { attribute: 'no-asterisk', type: Boolean },
noHash: { attribute: 'no-hash', type: Boolean },
noDisplay: { attribute: 'no-display', type: Boolean },
actionText: { type: String },
cancelText: { type: String },
actionStarted: { type: Boolean },
digits: { type: String }
};
}Le composant Web hérite de tous les "super" pouvoirs de l'élément LitElement et définit les valeurs par défaut.
constructor() {
super();
this.noAsterisk = false;
this.noHash = false;
this.noDisplay = false;
this.digits = "";
this.actionText = "Enter";
this.cancelText = "Cancel"
this.actionStarted = false;
}Viennent ensuite les différentes méthodes du composant Web. Il s'agit par exemple d'envoyer des événements personnalisés lors de l'ajout ou de l'envoi de chiffres, ou de mettre fin à une action. Il y a aussi la méthode qui peut être appelée sur le composant Web pour lui faire savoir qu'une action a commencé.
__addDigit(digit){
this.digits += digit;
const digitAdded = new CustomEvent('digit-added', {
detail: { digit },
bubbles: true,
composed: true });
this.dispatchEvent(digitAdded);
}
__sendDigits(){
const digitsSent = new CustomEvent('digits-sent', {
detail: { digits: this.digits },
bubbles: true,
composed: true });
this.dispatchEvent(digitsSent);
}
createAction(){
this.actionStarted = true;
}
__endAction(){
const actionEnded = new CustomEvent('action-ended', {
detail: { },
bubbles: true,
composed: true });
this.dispatchEvent(actionEnded);
this.digits = "";
this.actionStarted = false;
}Vous avez peut-être remarqué que la fonction __addDigit ne fait qu'ajouter le chiffre à la fin. Si un utilisateur déplace le curseur au milieu des chiffres, les nouveaux chiffres ne seront ajoutés qu'à la fin.
addDigit function only adding digits to the end
Maintenant, à titre d'exercice, permettons d'ajouter de nouveaux chiffres à l'endroit où se trouve le curseur. Voici un indice pour savoir où start.
Le balisage pour le rendu de la composante Web. En fonction de l'état et des attributs/propétences définis, le composant Web rendra ou cachera différents éléments.
render() {
return html`
<div id="container">
${this.noDisplay ? "" : html`<mwc-textfield outlined label="" .value=${this.digits}></mwc-textfield>`}
<div class="button-row">
<mwc-button unelevated @click=${()=>this.__addDigit('1')}>1</mwc-button>
<mwc-button unelevated @click=${()=>this.__addDigit('2')}>2</mwc-button>
<mwc-button unelevated @click=${()=>this.__addDigit('3')}>3</mwc-button>
</div>
<div class="button-row">
<mwc-button unelevated @click=${()=>this.__addDigit('4')}>4</mwc-button>
<mwc-button unelevated @click=${()=>this.__addDigit('5')}>5</mwc-button>
<mwc-button unelevated @click=${()=>this.__addDigit('6')}>6</mwc-button>
</div>
<div class="button-row">
<mwc-button unelevated @click=${()=>this.__addDigit('7')}>7</mwc-button>
<mwc-button unelevated @click=${()=>this.__addDigit('8')}>8</mwc-button>
<mwc-button unelevated @click=${()=>this.__addDigit('9')}>9</mwc-button>
</div>
<div class="button-row">
${this.noAsterisk ?
""
: html`<mwc-button unelevated @click=${()=>this.__addDigit('*')}>*</mwc-button>`
}
<mwc-button unelevated @click=${()=>this.__addDigit('0')}>0</mwc-button>
${this.noHash ?
""
:html`<mwc-button unelevated @click=${()=>this.__addDigit('#')}>#</mwc-button>`
}
</div>
<div class="button-row">
${this.actionStarted ?
html`<mwc-button unelevated fullwidth @click=${this.__endAction}>${this.cancelText}</mwc-button>`
:html`<mwc-button unelevated fullwidth @click=${this.__sendDigits}>${this.actionText}</mwc-button>`
}
</div>
</div>
`;
}
Maintenant que le composant Web est construit, publions-le pour que nous puissions l'utiliser dans un projet.
Pour ce faire, nous utiliserons un registre comme npm. Si vous n'en avez pas encore, ouvrez un compte. Voici quelques informations. Cela vous montrera non seulement comment créer un compte, mais aussi comment vous connecter à votre compte à l'aide de votre terminal afin de pouvoir publier le composant Web.
Une fois cette étape franchie, le composant Web sera publié en tant que paquetage public. Cela permet d'éviter les conflits au cas où il existerait un composant Web ou un paquetage portant le même nom que celui que vous avez choisi. Pour plus d'informations sur les champs d'application, voir ici.
Dans votre terminal, dans le répertoire du projet, tapez (en remplaçant votre nom d'utilisateur npm par votre nom d'utilisateur npm) :
npm init --scope=@your-npm-username
Acceptez tous les choix par défaut ou modifiez-les comme bon vous semble pour chaque étape.
Using the command line to set the scope of the project
Puisque votre composant Web est maintenant derrière un scope, modifions le fichier Readme qui a été généré par Open-WC pour refléter cela. Remplaçons à nouveau les espaces réservés (your-npm-username et whatever-you-like-keypad) par les vôtres.
La commande d'installation sera la suivante :
npm i @your-npm-username/whatever-you-like-keypad
Pour l'utiliser dans un projet, vous utiliserez la syntaxe import comme indiqué ci-dessous :
import '@your-npm-username/whatever-you-like-keypad/whatever-you-like-keypad.js';
Enregistrez vos modifications.
Publions maintenant le composant Web. Tapez dans le terminal :
npm publish --access public
Publishing the project to npm
En cas de succès, vous devriez pouvoir trouver le composant Web sur le site Web de npm à l'adresse suivante https://www.npmjs.com/package/@your-npm-username/whatever-you-like-keypad.
Bien entendu, le remplacement des your-npm-username et whatever-you-like-keypad par vos valeurs.
Félicitations, vous êtes publié ! Vous disposez maintenant d'un composant Web accessible au public que vous et d'autres personnes pouvez utiliser dans le cadre d'un projet.
Pour installer une copie localement, tapez le répertoire d'un projet dans le terminal, en le remplaçant à nouveau par vos valeurs :
npm i @your-npm-username/whatever-you-like-keypad
Mais que se passe-t-il si vous ne voulez pas installer le paquet ? Vous voulez peut-être vous assurer que vous chargez toujours la dernière version ou vous voulez voir le composant Web dans un environnement qui ne permet pas l'installation, tel que CodePen.
C'est là qu'intervient un réseau de diffusion de contenu (CDN). Il héberge votre paquet et vous permet d'accéder directement à vos fichiers. Pour cet article, nous utiliserons unpkg.com. Ils copient automatiquement vos fichiers, vous n'avez donc rien à faire.
Voici un exemple de CodePen que vous pouvez utiliser pour tester votre composant Web :
Encore une fois, remplacez le nom d'utilisateur et le nom du composant par les vôtres dans les champs HTML et JS et dans l'onglet
Voir le stylo le clavier de votre choix par conshus de OUR show (@conshus) sur CodePen.
Essayez d'ajouter certains des attributs et propriétés du composant Web que nous avons créé (no-asterisk no-hash no-display) et définissez les valeurs du texte du bouton (actionText="Quelque chose" cancelText="Autre chose").
Note : En cas de non-affichage, pour voir les chiffres, un élément HTML de type "input" ou "textarea" est nécessaire. Comme dans cet exemple :
Voir le stylo Clavier à touches (toutes options) par conshus de OUR show (@conshus) sur CodePen.
Maintenant que vous avez un nouveau composant Web brillant, que pouvez-vous lui ajouter ? Peut-être ajouter un bouton de retour en arrière qui effacera un caractère ou permettre à l'utilisateur de définir ses propres boutons. Ou encore, créez quelque chose de tout à fait nouveau.
Laissez des liens vers votre composant Web, des questions et/ou des commentaires dans notre canal Slack de la communauté. J'ai hâte de voir ce que vous allez construire.