Crear componentes web Lightning

Objetivos de aprendizaje

Después de completar esta unidad, podrá:

Describir el contenido de cada archivo de componente.
Crear métodos JavaScript para un componente web Lightning.
Usar hooks de ciclo de vida en el código JavaScript de un componente.

Hora de jugar

Supongamos que quiere crear un elemento de visualización de datos que sea independiente de un objeto específico de Salesforce. Un buen ejemplo es el componente productCard del repositorio de ejemplo de ebikes. Vamos a examinar ese componente de tarjeta y crear nuestra propia versión desde cero para que vea cómo se convierte en un componente web Lightning con todas sus características. Cuando componga las partes de un componente y explore más ejemplos, adquirirá rápidamente los conocimientos básicos de este tema.

Acceder a una organización

En esta unidad, vamos a desarrollar un componente web Lightning mediante Visual Studio Code con la extensión de Salesforce.

Lo que se necesita

Como dijimos en la primera unidad, necesita algunos conocimientos de Salesforce DX para continuar. Para completar esta unidad necesita:

Visual Studio Code (VS Code) con el paquete Salesforce Extension Pack
Salesforce CLI

Para reunir estos requisitos, complete el proyecto Inicio rápido: Lightning Web Components.

Un vistazo al archivo HTML

Los archivos HTML de un componente web Lightning incluyen la etiqueta template (plantilla). La etiqueta template (plantilla) contiene el código HTML que define la estructura del componente. Veamos el código HTML de una versión simplificada del componente productCard del repositorio de ebikes.

Pegue estos ejemplos en VS Code para continuar.

Cree un proyecto seleccionando SFDX: Create Project (Crear proyecto) en Command Palette (Paleta de comandos) en VS Code. Acepte la plantilla estándar y asigne el nombre bikeCard al proyecto.
En force-app/main/default, haga clic con el botón derecho en la carpeta lwc y seleccione SFDX: Create Lightning Web Component (Crear componente web Lightning).
Escriba app como nombre del nuevo componente.
Pulse Enter (Intro) y luego vuelva a pulsar Enter (Intro) para aceptar la carpeta predeterminada force-app/main/default/lwc.

Pegue lo siguiente en app.html (sustituya el código HTML existente en el archivo).

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

Los identificadores entre llaves {} están vinculados a los campos que tienen el mismo nombre de la clase JavaScript correspondiente.

Pegue lo siguiente en 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';
}

Guarde los archivos.

Ahora vamos a jugar con un ejemplo real. Supongamos que quiere mostrar datos, pero sabe que pueden tardar un poco en cargarse. No quiere que el usuario se quede pensando en si ocurre algo. Puede usar las directivas condicionales lwc:if y lwc:else de la plantilla para determinar los elementos visuales que se van a representar.

Pegue lo siguiente en app.html. El contenido en la etiqueta div de “visualización” no aparece hasta que el valor de ready (preparado) es true (verdadero) en el archivo 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>

Pegue lo siguiente en app.js. Esto retiene los valores de nuestros datos y define un temporizador de 3 segundos. Después de 3 segundos, debería aparecer el contenido (por supuesto, esto es solo con fines de prueba).

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);
  }
}

Guarde los archivos.

Componentes web Lightning básicos

No quiere desarrollar todos los componentes desde cero. Así que vamos a explorar el uso de un componente web Lightning básico. Por supuesto, hay muchos componentes, como tipos de campo, controladores de visualización, elementos de navegación, etc. Todos ellos aparecen en la lista de referencia de componentes.

Vamos a hacer que se vean bien los detalles de la bicicleta. En el archivo app.html, sustituya las etiquetas "div" para el material y la categoría del último ejemplo por un componente Lightning de distintivo. Este es el 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>

Guarde el archivo.

Las palabras Steel (Acero) y Mountain (Montaña) aparecen en forma de distintivos. Así de sencillo.

Estructura de un componente

Lo único que necesita un componente es una carpeta y sus archivos con el mismo nombre. Estos se vinculan automáticamente por nombre y ubicación.

Archivos de un componente en una carpeta

Todos los componentes web Lightning tienen un espacio de nombres separado del nombre de la carpeta por un guion. Por ejemplo, el marcado del componente web Lightning con el nombre de carpeta "app" en el espacio de nombres predeterminado "c" es <c-app>.

Sin embargo, Salesforce Platform no admite guiones en los nombres de carpetas o archivos de componentes. ¿Qué ocurre si el nombre de un componente tiene más de una palabra, como "micomponente"? No puede asignarle el nombre "mi-componente" a los archivos y la carpeta, pero tenemos una solución muy práctica.

Puede usar una combinación de mayúsculas y minúsculas para asignar el nombre al componente, como myComponent. En el marcado, esta convención de nomenclatura para los nombres de carpetas se asigna a la convención "kebab". En el marcado, para hacer referencia a un componente con el nombre de carpeta miComponente, debemos usar <c-my-component>.

Por ejemplo, el repositorio de ejemplos de LWC incluye la carpeta viewSource, que contiene los archivos del componente viewSource. Cuando el componente “hello” hace referencia al componente viewSource en HTML, utiliza c-view-source.

¡Bien! Pasemos al JavaScript.

Trabajar con JavaScript

Así es cómo se ejecutan las ideas. Como hemos visto hasta ahora, los métodos JavaScript definen lo que hay que hacer con los datos, eventos, entradas, cambios de estado y mucho más para que el componente funcione.

El archivo JavaScript de un componente web Lightning debe incluir como mínimo este código, donde MyComponent es el nombre que ha asignado a su clase de componente.

import { LightningElement } from 'lwc';

export default class MyComponent extends LightningElement {

}

La instrucción export (exportar) define una clase que amplía la clase LightningElement. Como práctica recomendada, el nombre de la clase suele coincidir con el nombre de archivo de la clase de JavaScript, pero no es obligatorio.

Módulo LWC

Lightning Web Components utiliza módulos (los módulos integrados se introdujeron en ECMAScript 6) para agrupar funcionalidades básicas y ponerlas a disposición del código JavaScript del archivo de componente. El módulo principal para los componentes web Lightning es lwc.

Comience el módulo con la instrucción import (importar) y especifique la funcionalidad del mismo que utiliza su componente.

La instrucción import (importar) indica que el código JavaScript utiliza la funcionalidad LightningElement del módulo 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 es la clase base de los componentes web Lightning, que nos permite usar connectedCallback().
El método connectedCallback() es uno de nuestros hooks de ciclo de vida. Aprenderá más sobre los hooks de ciclo de vida en la siguiente sección. Por ahora, debe saber que el método se activa cuando se inserta un componente en Document Object Model (DOM). En este caso, inicia el temporizador.

Hooks de ciclo de vida

Lightning Web Components proporciona métodos que permiten "vincular" el código con eventos críticos del ciclo de vida de un componente. Entre estos eventos se incluye cuando un componente:

Se crea.
Se agrega a DOM.
Se representa en el navegador.
Detecta errores.
Se elimina de DOM.

Puede responder a cualquiera de estos eventos del ciclo de vida mediante métodos de devolución de llamada. Por ejemplo, connectedCallback() se invoca cuando se inserta un componente en DOM. disconnectedCallback() se invoca cuando se elimina un componente de DOM.

En el archivo de JavaScript que usamos para probar la representación condicional, usamos el método connectedCallback() para ejecutar código automáticamente cuando se insertaba el componente en DOM. El código espera 3 segundos y luego establece ready (preparado) en true (verdadero).

import { LightningElement } from 'lwc';

export default class App extends LightningElement {

  ready = false;

  connectedCallback() {

    setTimeout(() => {

      this.ready = true;

    }, 3000);

  }

}

Cuando usa este ejemplo en un editor como VS Code, es posible que vea una advertencia de análisis como "Operación asíncrona restringida..." para la función setTimeout(). Esta advertencia indica que está usando una operación asíncrona que suele utilizarse erróneamente. Retrasa el comportamiento en función del tiempo en lugar de esperar un evento. En este caso, setTimeout() sirve para demostrar un retraso arbitrario en el tiempo, y la advertencia no debería impedirle usarla.

Además, observe que hemos usado la palabra clave this (este/a). El uso de palabras clave debería resultarle familiar si ya ha trabajado con JavaScript, y funciona igual que en el resto de entornos. La palabra clave this (este/a) en JavaScript se refiere al nivel superior del contexto actual. En este caso, el contexto es esta clase. El método connectedCallback() asigna el valor para la variable "ready" de nivel superior. Este es un buen ejemplo de cómo Lightning Web Components le permite integrar funciones de JavaScript en sus tareas de desarrollo. Encontrará un vínculo con información útil sobre el elemento this (este/a) en la sección Recursos.

Decoradores

Los decoradores se suelen usar en JavaScript para modificar el comportamiento de una propiedad o función.

Para usar un decorador, impórtelo desde el módulo lwc y colóquelo delante de la propiedad o función.

import { LightningElement, api } from 'lwc';

export default class MyComponent extends LightningElement{

  @api message;

}

Puede importar varios decoradores, pero una propiedad o función solo puede tener un decorador. Por ejemplo, una propiedad no puede tener los decoradores @api y @wire.

Algunos ejemplos de decoradores de Lightning Web Components son:

@api: marca un campo como público. Las propiedades públicas definen la API de un componente. El propietario de un componente que usa el componente en este marcado HTML puede acceder a sus propiedades públicas. Todas las propiedades públicas son reactivas, lo que significa que el marco observa si hay cambios en ellas. Cuando el valor de una propiedad cambia, el marco reacciona y vuelve a representar el componente.

Campo y propiedad son términos prácticamente intercambiables. El autor de un componente declara campos en una clase de JavaScript. Una instancia de esa clase contiene propiedades. Para los consumidores de componentes, los campos son propiedades. En un componente web Lightning, solo los campos que el autor del componente decora con @api son públicos para los consumidores en forma de propiedades de objeto.

@track: indica al marco que observe los cambios en las propiedades de un objeto o en los elementos de una matriz. Si se produce un cambio, el marco vuelve a representar el componente. Todos los campos son reactivos. Si el valor de un campo cambia y el campo se utiliza en una plantilla, o el elemento getter de una propiedad de la plantilla, el marco vuelve a representar el componente. No necesita decorar el campo con @track. Utilice @track únicamente si un campo contiene un objeto o una matriz y quiere que el marco observe los cambios realizados en las propiedades del objeto o en los elementos de la matriz. Si quiere cambiar el valor de toda la propiedad, no necesita usar @track.

Antes de la versión Spring '20, tenía que usar @track para marcar los campos (también conocidos como propiedades privadas) como reactivos. Ya no es necesario. Utilice @track únicamente para indicar al marco que observe los cambios en las propiedades de un objeto o en los elementos de una matriz. Es posible que en algunos ejemplos anteriores se utilice @track sin necesidad, pero no está mal, porque el uso del decorador no cambia la funcionalidad ni rompe el código.

@wire: proporciona una manera sencilla de obtener y vincular datos de una organización de Salesforce.

Aquí tiene un ejemplo de uso del decorador @api para representar un valor de un componente (bike) en otro componente (app). La estructura del archivo tiene el siguiente aspecto:

Estructura de ejemplo del archivo app.

El componente app utiliza el siguiente código HTML.

<!-- app.html -->

<template>

  <div>

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

  </div>

</template>

El componente app utiliza el siguiente código 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'

  };

}

El componente bike utiliza el siguiente código HTML.

<!-- bike.html -->

<template>

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

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

</template>

El componente bike utiliza el siguiente código JavaScript.

// bike.js 

import { LightningElement, api } from 'lwc';

export default class Bike extends LightningElement {

  @api bike;

}

Nos movemos rápido y ya ha conseguido trabajar con algo de código en VS Code. En la siguiente unidad, implementaremos código y hablaremos un poco más del entorno en el que residen los componentes.

Recursos

Guía del desarrollador de componentes web Lightning: Reactivity
Guía del desarrollador de componentes web Lightning: Referencia (incluye directivas de plantillas HTML, decoradores y mucho más)
Documentos web de MDN: este documento