Skip to main content

Créer des composants Web Lightning.

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

  • Décrire le contenu de chaque fichier de composant
  • Créer des méthodes JavaScript pour un composant Web Lightning
  • Utiliser des points d’ancrage de cycle de vie dans un composant JavaScript

Passons aux choses sérieuses

Supposons que vous souhaitiez créer un élément d’affichage de données indépendant de tout objet spécifique dans Salesforce. Le composant productCard, dans le référentiel d’exemple de la démo sur les vélos électriques, en est un bon exemple. Examinons ce composant Carte et créons notre propre version de A à Z afin que vous puissiez voir comment il se transforme en un composant Web Lightning à part entière. En concevant les parties d’un composant et en explorant d’autres exemples, vous acquerrez rapidement les bases du concept.

Passons à l’échelon supérieur

Dans cette unité, nous allons développer un composant Web Lightning à l’aide de Visual Studio Code doté de l’extension Salesforce.

Liste des prérequis

Comme indiqué dans la première unité, vous devez vous familiariser avec Salesforce DX avant de continuer. Pour terminer cette unité, il vous faudra :

  • Visual Studio Code (VS Code) avec le pack d’extension Salesforce
  • Salesforce CLI

Pour répondre à ces exigences, effectuez le projet Prise en main rapide : composants Web Lightning.

Présentation du fichier HTML

Les fichiers HTML du composant Web Lightning incluent tous la balise template. La balise template contient le code HTML qui définit la structure de votre composant. Regardons le HTML pour voir une version simplifiée du composant productCard du référentiel des vélos électriques.

Suivez les différentes étapes en collant ces exemples dans VS Code.

  1. Créez un projet en sélectionnant SFDX : créer un projet à partir de la palette de commandes dans VS Code. Acceptez le modèle standard et donnez-lui le nom du projet bikeCard.
  2. Sous force-app/main/default, faites un clic droit sur le dossier lwc et sélectionnez SFDX : création d’un composant Web Lightning.
  3. Saisissez app (application) pour nommer le nouveau composant.
  4. Appuyez sur Enter (Entrée), puis à nouveau sur Enter (Entrée) pour accepter l’emplacement par défaut force-app/main/default/lwc.
  5. Collez les lignes suivantes dans app.html (remplacer tout code HTML existant dans le fichier).
    <template>
  <div>
    <div>Name: {name}</div>
    <div>Description: {description}</div>
    <div>Category: {category}</div>
    <div>Material: {material}</div>
    <div>Price: {price}</div>
    <div><img src={pictureUrl} alt={name}/></div>
  </div>
</template>
    Les identifiants entre accolades {} sont liés aux champs du même nom dans la classe JavaScript correspondante.
  6. Collez les lignes suivantes dans app.js.
    import { LightningElement } from 'lwc';
export default class App extends LightningElement {
  name = 'Electra X4';
  description = 'A sweet bike built for comfort.';
  category = 'Mountain';
  material = 'Steel';
  price = '$2,700';
  pictureUrl = 'https://s3-us-west-1.amazonaws.com/sfdc-demo/ebikes/electrax4.jpg';
}
  7. Enregistrez les fichiers.

Prenons maintenant un exemple réel. Supposons que vous souhaitiez afficher des données. Vous savez cependant que le chargement peut prendre un certain temps. Vous ne voulez pas que l’utilisateur s’impatiente. Vous pouvez utiliser les directives conditionnelles lwc:if et lwc:else dans votre modèle pour déterminer quels éléments visuels afficher.

  1. Collez ce qui suit dans app.html. Le contenu de la balise div « display » n’apparaît pas tant que la valeur de ready n’est pas true dans le fichier HTML.
    <template>
  <template lwc:if={ready}>
    <div id="display">
      <div>Name: {name}</div>
      <div>Description: {description}</div>
      <div>Category: {category}</div>
      <div>Material: {material}</div>
      <div>Price: {price}</div>
      <div><img src={pictureUrl} alt={name}/></div>
    </div>
  </template>
  <template lwc:else>
    <div id="waiting">Loading…</div>
  </template>
</template>
  2. Collez les lignes suivantes dans app.js. Ces lignes contiennent nos valeurs de données et définissent un minuteur de 3 secondes. Après 3 secondes, le contenu devrait apparaître (bien évidemment, nous utilisons uniquement cette valeur à des fins de test).
    import { LightningElement } from 'lwc';
export default class App extends LightningElement {
  name = 'Electra X4';
  description = 'A sweet bike built for comfort.';
  category = 'Mountain';
  material = 'Steel';
  price = '$2,700';
  pictureUrl = 'https://s3-us-west-1.amazonaws.com/sfdc-demo/ebikes/electrax4.jpg';
  ready = false;
  connectedCallback() {
    setTimeout(() => {
      this.ready = true;
    }, 3000);
  }
}
  3. Enregistrez les fichiers.

Composants Web Lightning de base

Vous n’allez bien sûr pas construire tous vos composants de A à Z. Voyons donc comment utiliser un composant Web Lightning de base. Il existe évidemment de nombreux composants, notamment des types de champs, des contrôleurs d’affichage, des éléments de navigation, et bien plus. Tous sont répertoriés dans notre bibliothèque de composants.

Faisons ressortir les détails du vélo. Dans le fichier app.html, remplacez les balises div de contenu et de catégorie par un composant lightning-badge. Voici le HTML.

<template>
  <template lwc:if={ready}>
    <div id="display">
      <div>Name: {name}</div>
      <div>Description: {description}</div>
      <lightning-badge label={material}></lightning-badge>
      <lightning-badge label={category}></lightning-badge>
      <div>Price: {price}</div>
      <div><img src={pictureUrl} alt={name}/></div>
    </div>
  </template>
  <template lwc:else>
    <div id="waiting">Loading…</div>
  </template>
</template>

Enregistrez le fichier.

Les mots Steel (Acier) et Mountain (Montagne) apparaissent sous forme de cartouches. Simple n’est-ce pas ?

Structure de création des composants

Un composant requiert simplement que le dossier et ses fichiers portent le même nom. Ils sont automatiquement liés par leur nom et leur emplacement.

Fichiers de composant dans un dossier

Dans tous les composants Web Lightning, l’espace de noms est séparé du nom du dossier par un trait d’union. Par exemple, le balisage du composant Web Lightning portant le nom de dossier app dans l’espace de noms par défaut c est <c-app>.

La plate-forme Salesforce n’autorise cependant pas les traits d’union dans le dossier du composant ou les noms de fichier. Que se passe-t-il alors si le nom d’un composant comporte plusieurs mots, comme « mycomponent » ? Vous ne pouvez pas nommer le dossier et les fichiers my-component, mais nous avons une astuce pour vous.

Utilisez la casse mixte pour nommer votre composant myComponent. Les noms de dossier des composants en casse mixte sont mappés avec des noms au format de casse kebab dans le balisage. Dans le balisage, utilisez <c-my-component> pour faire référence à un composant avec le nom de dossier myComponent.

Par exemple, le référentiel d’exemples de composants Web Lightning comprend le dossier viewSource, qui contient les fichiers du composant viewSource. Lorsque le composant hello fait référence au composant viewSource en HTML, il utilise c-view-source.

OK. Examinons le fichier javaScript

Utilisation de JavaScript

C’est ici que vous entrez en jeu. Comme vous l’avez vu jusqu’à présent, les méthodes JavaScript définissent ce qu’il faut faire des entrées, données, événements, changements d’état, etc. pour faire fonctionner votre composant.

Le fichier JavaScript d’un composant Web Lightning doit inclure au moins le code suivant, où MyComponent est le nom que vous associez à votre classe de composant.

import { LightningElement } from 'lwc';
export default class MyComponent extends LightningElement {
}

L’instruction export définit une classe qui étend la classe LightningElement. La règle veut que le nom de la classe corresponde dans la plupart des cas au nom de fichier de la classe JavaScript, mais ce n’est pas obligatoire.

Le module lwc

Le modèle Composants Web Lightning utilise des modules (des modules intégrés ont été ajoutés dans ECMAScript 6) pour regrouper les fonctionnalités principales et les rendre accessibles au code JavaScript dans le fichier du composant. Le module principal des composants Web Lightning est lwc.

Commencez le module par l’instruction import et précisez la fonctionnalité du module utilisé par votre composant.

L’instruction import indique que JavaScript utilise la fonctionnalité LightningElement du module lwc.

// import module elements
import { LightningElement} from 'lwc';
// declare class to expose the component
export default class App extends LightningElement {
  ready = false;
  // use lifecycle hook
  connectedCallback() {
    setTimeout(() => {
      this.ready = true;
    }, 3000);
  }
}
  • LightningElement est la classe de base des composants Web Lightning, ce qui nous permet d’utiliser connectedCallback().
  • La méthode connectedCallback() est l’un de nos points d’ancrage de cycle de vie. Nous reviendrons plus en détail sur les ancrages de cycle de vie dans la section suivante. Notez pour l’instant que la méthode est déclenchée lorsqu’un composant est inséré dans le modèle d’objet de document (DOM). Dans cette situation, le minuteur est déclenché.

Points d’ancrage de cycle de vie

Le modèle Composants Web Lightning fournit des méthodes qui vous permettent d’« ancrer » votre code aux événements critiques du cycle de vie d’un composant. Il peut s’agir des situations où un composant est :

  • Créé
  • Ajouté au DOM
  • Affiché dans le navigateur
  • Confronté à des erreurs
  • Supprimé du DOM

Vous pouvez répondre à chacun de ces événements de cycle de vie à l’aide des méthodes de rappel. Par exemple, l’élément connectedCallback() est invoqué lorsqu’un composant est inséré dans le DOM. L’élément disconnectedCallback() est invoqué lorsqu’un composant est supprimé du DOM.

Dans le fichier JavaScript que nous avons utilisé pour tester notre rendu conditionnel, nous avons utilisé la méthode connectedCallback() pour exécuter automatiquement le code lorsque le composant est inséré dans le DOM. Après 3 secondes, le code passe de ready à true.

import { LightningElement } from 'lwc';
export default class App extends LightningElement {
  ready = false;
  connectedCallback() {
    setTimeout(() => {
      this.ready = true;
    }, 3000);
  }
}
Remarque

Lorsque vous utilisez cet exemple dans un éditeur tel que VS Code, vous pouvez voir un avertissement « Restricted async operation… » (Opération asynchrone restreinte…) pour la fonction setTimeout(). Cet avertissement indique que vous utilisez une opération asynchrone souvent mal utilisée ; cette opération retarde le comportement en suivant une valeur de temps au lieu d’attendre un événement. Dans cette situation, setTimeout() permet de montrer un délai arbitraire, et l’avertissement ne devrait pas vous empêcher de l’utiliser.

Veuillez également noter que nous avons utilisé le mot-clé this. Vous devriez être à l’aise avec l’utilisation de mots-clés si vous avez déjà écrit du code JavaScript, car elle fonctionne exactement comme dans d’autres environnements. Le mot-clé this fait référence au niveau supérieur du contexte actuel. Le contexte est ici cette classe. La méthode connectedCallback() associe une valeur à la variable ready de niveau supérieur. C’est un excellent exemple de la façon dont le modèle Composants Web Lightning vous permet d’intégrer des fonctionnalités JavaScript dans votre développement. Vous trouverez des informations utiles sur le mot-clé this dans la section Ressources.

Décorateurs

Les décorateurs sont souvent utilisés dans JavaScript pour modifier le comportement d’une propriété ou d’une fonction.

Pour utiliser un décorateur, importez-le depuis le module lwc et placez-le avant la propriété ou la fonction.

import { LightningElement, api } from 'lwc';
export default class MyComponent extends LightningElement{
  @api message;
}

Vous pouvez importer plusieurs décorateurs, mais une propriété ou fonction unique ne peut avoir qu’un seul décorateur. Par exemple, une propriété ne peut pas avoir de décorateurs @api et @wire.

Voici des exemples de décorateurs Composants Web Lightning :

  • @api : définit un champ comme public. Les propriétés publiques définissent l’API d’un composant. Un composant propriétaire qui utilise le composant dans son balisage HTML peut accéder aux propriétés publiques du composant. Toutes les propriétés publiques sont réactives, ce qui signifie que l’infrastructure respecte la propriété pour les modifications. Lorsque la valeur de la propriété change, l’infrastructure réagit et met à jour l’affichage du composant.
Remarque

Les termes champ et propriété sont presque interchangeables. Un auteur de composant déclare des champs dans une classe JavaScript. L’instance de la classe a des propriétés. Pour les consommateurs de composants, les champs sont des propriétés. Dans un composant Web Lightning, seuls les champs décorés par un auteur de composant avec @api sont publiquement accessibles aux consommateurs comme propriétés d’objet.

  • @track : indique à l’infrastructure de respecter les modifications apportées aux propriétés d’un objet ou aux éléments d’un tableau. Si des modifications sont apportées, l’infrastructure met à jour l’affichage du composant. Tous les champs sont réactifs. Si la valeur d’un champ change et que le champ est utilisé dans un modèle (ou dans la méthode d’obtention d’une propriété utilisée dans un modèle), l’infrastructure met à jour l’affichage du composant. Vous n’avez pas besoin de décorer le champ avec @track. Utilisez @track uniquement si un champ contient un objet ou un tableau et que vous souhaitez que l’infrastructure respecte les modifications apportées aux propriétés de l’objet ou aux éléments du tableau. Si vous souhaitez modifier la valeur de l’ensemble de la propriété, vous n’avez pas besoin d’utiliser @track.
Remarque

Avant Spring ’20, vous deviez utiliser @track pour définir les champs (également appelés propriétés privées) comme réactifs. Ce n’est maintenant plus obligatoire. Utilisez @track uniquement pour indiquer à l’infrastructure de respecter les modifications apportées aux propriétés d’un objet ou aux éléments d’un tableau. Certains anciens exemples peuvent encore utiliser @track là où ce n’est pas nécessaire, mais cela ne pose pas de problème, car l’utilisation du décorateur ne modifie pas la fonctionnalité et ne casse pas le code.

  • @wire : vous permet d’obtenir et de lier des données simplement à partir d’une organisation Salesforce.

Voici un exemple utilisant le décorateur @api pour restituer la valeur d’un composant (vélo) dans un autre composant (application). La structure de votre fichier se présente comme suit :

Structure d’un fichier d’exemple d’application

Le composant d’application utilise le code HTML suivant.

<!-- app.html -->
<template>
  <div>
    <c-bike bike={bike}></c-bike>
  </div>
</template>

Le composant d’application utilise le code JavaScript suivant.

// app.js
import { LightningElement } from 'lwc';
export default class App extends LightningElement {
  bike = {
    name: 'Electra X4',
    picture: 'https://s3-us-west-1.amazonaws.com/sfdc-demo/ebikes/electrax4.jpg'
  };
}

Le composant vélo utilise le code HTML suivant.

<!-- bike.html -->
<template>
  <img src={bike.picture} alt="bike picture" />
  <p>{bike.name}</p>
</template>

Le composant vélo utilise le code JavaScript suivant.

// bike.js
import { LightningElement, api } from 'lwc';
export default class Bike extends LightningElement {
  @api bike;
}

Nous progressons rapidement et vous avez pu manipuler du code dans VS Code. Dans l’unité suivante, nous allons déployer du code et parler davantage de l’environnement dans lequel se trouvent les composants.

Ressources

Partagez vos commentaires sur Trailhead dans l'aide Salesforce.

Nous aimerions connaître votre expérience avec Trailhead. Vous pouvez désormais accéder au nouveau formulaire de commentaires à tout moment depuis le site d'aide Salesforce.

En savoir plus Continuer à partager vos commentaires