Creare componenti Web Lightning

Obiettivi di apprendimento

Al completamento di questa unità, sarai in grado di:

Descrivere il contenuto di ogni file del componente.
Creare metodi JavaScript per un componente Web Lightning.
Usare gli hook del ciclo di vita nel codice JavaScript del componente.

È ora di giocare

Supponiamo di voler creare un elemento per la visualizzazione di dati, indipendente da un oggetto specifico di Salesforce. Un buon esempio è il componente productCard nel repository di esempio ebikes. Esaminiamo questo componente scheda e creiamo la nostra versione da zero, per vedere come si evolve in un componente Web Lightning completo. Acquisirai rapidamente le nozioni di base quando crei le parti di un componente ed esplori altri esempi.

Passare a un'organizzazione

In questa unità, svilupperemo un componente Web Lightning utilizzando Visual Studio Code con l'estensione Salesforce.

Che cosa ti serve

Come indicato nella prima unità, per continuare è necessario avere una certa familiarità con Salesforce DX. Per completare questa unità, hai bisogno di:

Visual Studio Code (VS Code) installato con l'estensione Salesforce Extension Pack
Salesforce CLI

Per soddisfare questi requisiti, completa il progetto Avvio rapido: Componenti Web Lightning.

Un'occhiata al file HTML

I file HTML dei componenti Web Lightning includono tutti il tag template. Il tag template contiene il codice HTML che definisce la struttura del componente. Diamo un'occhiata al codice HTML di una versione semplificata del componente productCard dal repository ebikes.

Segui la procedura incollando questi esempi in VS Code.

Crea un progetto selezionando SFDX: Create Project (SDFX: Crea progetto) dal riquadro dei comandi in VS Code. Accetta il modello standard e assegnagli il nome di progetto bikeCard.
In force-app/main/default, fai clic con il tasto destro del mouse sulla cartella lwc e seleziona SFDX: Create Lightning Web Component (SFDX: Crea componente Web Lightning).
Inserisci app come nome del nuovo componente.
Premi Invio e quindi ancora Invio per accettare il percorso predefinito: force-app/main/default/lwc.

Incolla il codice seguente in app.html (sostituendo tutto l'HTML esistente nel file).

<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}/></div>
  </div>
</template>

Gli identificatori tra parentesi graffe {} sono associati ai campi con lo stesso nome nella classe JavaScript corrispondente.

Incolla il codice seguente in 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';
}

Salva i file.

Ora divertiamoci con un esempio della vita reale. Supponiamo che tu voglia visualizzare i dati, ma che sappia che il caricamento può richiedere del tempo e che tu non voglia che l'utente si chieda cosa sta succedendo. Puoi utilizzare le direttive condizionali lwc:if e lwc:else nel modello per determinare di quali elementi visivi deve essere eseguito il rendering.

Incolla il codice seguente in app.html. Il contenuto del tag div con id "display" non viene visualizzato fino a quando il valore di ready non è true nel file 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}/></div>
    </div>
  </template>
  <template lwc:else>
    <div id="waiting">Loading…</div>
  </template>
</template>

Incolla il codice seguente in app.js. Il codice contiene i valori dei dati e imposta un timer di 3 secondi. Dopo 3 secondi, il contenuto dovrebbe essere visualizzato (ovviamente questo è solo a scopo di 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);
  }
}

Salva i file.

Componenti Web Lightning di base

Non è il caso di creare tutti i componenti partendo da zero. Quindi vediamo come si usa un componente Web Lightning di base. Naturalmente, ci sono molti componenti, tra cui tipi di campo, controller di visualizzazione, elementi di navigazione e altro ancora. Sono tutti elencati nella guida di riferimento ai componenti.

Mettiamo in evidenza i dettagli della bicicletta. Nel file app.html, sostituisci i tag div per materiale e categoria nell'ultimo esempio con un componente lightning-badge. Ecco il codice 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}/></div>

    </div>

  </template>

  <template lwc:else> 

    <div id="waiting">Loading…</div>

  </template>

</template>

Salva il file.

Ora le parole Steel (Acciaio) e Mountain compariranno come badge. È molto semplice.

Struttura per la creazione del componente

Un componente ha semplicemente bisogno di una cartella e dei suoi file con lo stesso nome. Questi vengono collegati automaticamente in base al nome e alla posizione.

File del componente in una cartella

Tutti i componenti Web Lightning hanno uno spazio dei nomi separato dal nome della cartella da un trattino. Ad esempio, il markup del componente Web Lightning la cui cartella è denominata app nello spazio dei nomi predefinito c è <c-app>.

Tuttavia, la piattaforma Salesforce non consente l'uso di trattini nei nomi dei file o delle cartelle dei componenti. Cosa succede se il nome di un componente contiene più di una parola, ad esempio "mycomponent"? Non puoi denominare la cartella e i file my-component. Tuttavia esiste una comoda soluzione.

Usa il camelCase (ovvero caratteri minuscoli e maiuscoli alternati), per assegnare al componente il nome myComponent. I nomi delle cartelle del componente in camelCase corrispondono a quelli in kebab-case (ovvero parole separate da trattini) nel markup. Nel markup, per fare riferimento a un componente la cui cartella è denominata myComponent, usa <c-my-component>.

Ad esempio, nel repository di esempi di LWC è presente una cartella denominata viewSource che contiene i file del componente viewSource. Quando il componente hello fa riferimento al componente viewSource in HTML utilizza l'elemento c-view-source.

OK. Vediamo il codice JavaScript.

Usare JavaScript

È qui che succedono le cose. Come abbiamo visto finora, i metodi JavaScript definiscono le operazioni con input, dati, eventi, modifiche dello stato e altro ancora, da eseguire per far funzionare il componente.

Il file JavaScript di un componente Web Lightning deve includere almeno questo codice, dove MyComponent è il nome che assegni alla classe del componente.

import { LightningElement } from 'lwc';

export default class MyComponent extends LightningElement {

}

L'istruzione export definisce una classe che estende la classe LightningElement. Come best practice, il nome della classe di solito corrisponde al nome del file della classe JavaScript, ma non è un requisito.

Il modulo LWC

Componenti Web Lightning utilizza i moduli (i moduli integrati sono stati introdotti in ECMAScript 6) per raggruppare le funzionalità di base e renderle accessibili al codice JavaScript nel file del componente. Il modulo principale per i componenti Web Lightning è lwc.

Inizia il modulo con l'istruzione import (importa) e specifica la funzionalità del modulo utilizzato dal componente.

L'istruzione import indica che JavaScript utilizza la funzionalità LightningElement del modulo 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 è la classe base per i componenti Web Lightning che ci permette di utilizzare il metodo connectedCallback().
Il metodo connectedCallback() è uno dei nostri hook del ciclo di vita. Parleremo più in dettaglio di questi hook nella prossima sezione. Per ora, ricorda che il metodo viene attivato quando un componente viene inserito nel modello a oggetti del documento (DOM). In questo caso il metodo, avvia il timer.

Hook del ciclo di vita

Componenti Web Lightning fornisce metodi che consentono di "agganciare" il codice a eventi critici nel ciclo di vita di un componente. Ad esempio, si verifica un evento quando un componente:

viene creato
viene aggiunto al DOM
è oggetto di rendering nel browser
riscontra degli errori
viene rimosso dal DOM

Puoi rispondere a uno di questi eventi del ciclo di vita usando metodi di callback. Ad esempio, il metodo connectedCallback() viene chiamato quando un componente viene inserito nel DOM. Il metodo disconnectedCallback() viene chiamato quando un componente viene rimosso dal DOM.

Nel file JavaScript che abbiamo usato per testare il rendering condizionale, abbiamo usato il metodo connectedCallback() per eseguire automaticamente il codice quando il componente viene inserito nel DOM. Il codice attende 3 secondi, poi imposta ready su true.

import { LightningElement } from 'lwc';

export default class App extends LightningElement {

  ready = false;

  connectedCallback() {

    setTimeout(() => {

      this.ready = true;

    }, 3000);

  }

}

Quando usi questo esempio in un editor come VS Code, potresti vedere un avviso di lint "Restricted async operation..." (Operazione asincrona limitata...) per la funzione setTimeout(). Questo avviso indica che si sta utilizzando un'operazione asincrona, spesso utilizzata in modo improprio, che ritarda il comportamento in base al tempo anziché attendere un evento. In questo caso, setTimeout() è adatto a dimostrare un ritardo arbitrario e l'avviso non dovrebbe impedirne l'uso.

Ricorda inoltre che abbiamo usato la parola chiave this. L'uso delle parole chiave dovrebbe essere familiare se hai scritto in JavaScript e si comporta come in altri ambienti. La parola chiave this in JavaScript si riferisce al livello più alto del contesto corrente. Qui il contesto è questa (this) classe. Il metodo connectedCallback() assegna un valore alla variabile ready del primo livello. È un ottimo esempio di come Componenti Web Lightning permetta di integrare le funzionalità JavaScript nello sviluppo. Puoi trovare un link a informazioni utili su this nella sezione Risorse.

Decorator

I decorator sono spesso utilizzati in JavaScript per modificare il comportamento di una proprietà o una funzione.

Per utilizzare un decorator, importalo dal modulo lwc e inseriscilo prima della proprietà o della funzione.

import { LightningElement, api } from 'lwc';

export default class MyComponent extends LightningElement{

  @api message;

}

Puoi importare più decorator, ma una singola proprietà o funzione può avere un solo decorator. Ad esempio, una proprietà non può avere entrambi i decorator @api e @wire.

Ecco alcuni esempi di decorator di Componenti Web Lightning:

@api: contrassegna un campo come pubblico. Le proprietà pubbliche definiscono l'API per un componente. Un componente proprietario che utilizza un componente nel proprio markup HTML può accedere alle proprietà pubbliche di quel componente. Tutte le proprietà pubbliche sono reattive, ovvero il framework osserva la proprietà per rilevarne le modifiche. Quando il valore della proprietà cambia, il framework reagisce ed esegue nuovamente il rendering del componente.

Campo e proprietà sono termini quasi intercambiabili. Un autore di componente dichiara i campi in una classe JavaScript. Un'istanza della classe ha proprietà. Per i consumer del componente, i campi sono proprietà. In un componente Web Lightning, solo i campi per i quali l'autore utilizza il decorator @api sono disponibili pubblicamente come proprietà dell'oggetto.

@track: indica al framework di osservare le modifiche delle proprietà di un oggetto o degli elementi di un array. In caso di modifica, il framework esegue nuovamente il rendering del componente. Tutti i campi sono reattivi. Se il valore di un campo cambia e il campo è usato in un modello, o nel metodo getter di una proprietà usata in un modello, il framework esegue nuovamente il rendering del componente. Non è necessario utilizzare il decorator @track per i campi. Utilizza @track solo se un campo contiene un oggetto o un array e vuoi che il framework osservi le modifiche delle proprietà dell'oggetto o degli elementi dell'array. Per modificare il valore dell'intera proprietà, non è necessario usare @track.

Prima della release Spring '20, bisognava utilizzare @track per contrassegnare i campi (noti anche come proprietà private) come reattivi. Ora non è più necessario farlo. Utilizza @track solo per indicare al framework di osservare le modifiche delle proprietà di un oggetto o degli elementi di un array. Alcuni esempi legacy possono utilizzare ancora @track dove non è necessario, ma non è un problema perché l'uso di un decorator non modifica la funzionalità né provoca errori nel codice.

@wire: fornisce un modo semplice per recuperare ed eseguire il binding dei dati da un'organizzazione Salesforce.

Ecco un esempio dell'uso del decorator @api per eseguire in un componente (app) il rendering di un valore proveniente da un altro componente (bike). La struttura del file ha questo aspetto:

Struttura dei file di esempio.

Il componente app usa il seguente codice HTML.

<!-- app.html -->

<template>

  <div>

    <c-bike bike={bike}></c-bike>

  </div>

</template>

Il componente app usa il seguente codice JavaScript.

// 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'

  };

}

Il componente bike usa il seguente codice HTML.

<!-- bike.html -->

<template>

  <img src={bike.picture} alt="bike picture" />

  <p>{bike.name}</p>

</template>

Il componente bike usa il seguente codice JavaScript.

// bike.js 

import { LightningElement, api } from 'lwc';

export default class Bike extends LightningElement {

  @api bike;

}

Stiamo procedendo velocemente e hai potuto lavorare con il codice in VS Code. Nella prossima unità, distribuiremo del codice e parleremo ancora dell'ambiente in cui risiedono i componenti.

Risorse

Lightning Web Components Developer Guide: Reactivity (Guida per sviluppatori di componenti Web Lightning: Reattività)
Lightning Web Components Developer Guide: Reference (Guida per sviluppatori di componenti Web Lightning: Guida di riferimento) (include direttive per i modelli HTML, decorator e altro ancora)
MDN web docs: this (Documenti Web MDN: this)