Criar componentes Web do Lightning

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

Descrever o conteúdo de cada arquivo do componente.
Criar métodos JavaScript para um componente Web do Lightning.
Usar ganchos do ciclo de vida no JavaScript do componente.

Hora do recreio

Digamos que você queira criar um elemento de exibição de dados, independente de um objeto específico no Salesforce. Um bom exemplo é o componente productCard no repositório de exemplo ebikes. Vamos examinar esse componente de cartão e criar nossa própria versão do zero para observar sua evolução para um componente Web do Lightning completo. Você aprenderá as noções básicas quando criar as partes de um componente e explorar mais exemplos.

Implantar em uma organização

Nesta unidade, desenvolvemos um componente Web do Lightning usando o Visual Studio Code com a extensão do Salesforce.

O que você precisa

Conforme indicado na primeira unidade, é necessário ter alguma familiaridade com o Salesforce DX para continuar. Para concluir esta unidade, você precisará:

Visual Studio Code (VS Code) com o Pacote de extensões do Salesforce
Salesforce CLI

Para cumprir esses requisitos, conclua o projeto Início rápido: Componentes Web do Lightning.

Uma visão do arquivo HTML

Todos os arquivos HTML de componentes Web do Lightning incluem a marca template. A marca template contém o HTML que define a estrutura de seu componente. Vamos observar o HTML de uma versão simplificada do componente productCard do repositório ebikes.

Acompanhe colando os exemplos no VS Code.

Crie um projeto selecionando SFDX: Create Project (Criar projeto) na Paleta de comandos no VS Code. Aceite o modelo padrão e dê a ele o nome de projeto bikeCard.
Em force-app/main/default, clique com o botão direito do mouse na pasta lwc e selecione SFDX: Criar componente web do Lightning.
Insira app como o nome do novo componente.
Pressione Enter e pressione Enter novamente para aceitar o padrão force-app/main/default/lwc.

Cole o seguinte em app.html (substituindo todo o código HTML existente no arquivo).

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

Os identificadores nas chaves {} estão vinculados aos campos com o mesmo nome na classe JavaScript correspondente.

Cole o que está abaixo em 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';
}

Salve os arquivos.

Agora vamos brincar com um exemplo da vida real. Digamos que você queira exibir dados, mas sabe que pode levar algum tempo para carregar. Você não quer que o usuário fique sem saber o que está acontecendo. Você pode usar as diretivas condicionais lwc:if e lwc:else no seu modelo para determinar quais elementos visuais são renderizados.

Cole o que está abaixo em app.html. O conteúdo na marca div "display" não aparece até que o valor ready seja true no arquivo 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>

Cole o que está abaixo em app.js. Isso mantém nossos valores de dados e define um temporizador de três segundos. Após três segundos, o conteúdo deve aparecer. (Claro, isso é apenas para fins de teste.)

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

Salve os arquivos.

Componentes Web do Lightning básicos

Você não quer criar todos os componentes do zero. Portanto, vamos explorar usando um componente Web do Lightning básico. E, claro, existem vários componentes, incluindo tipos de campo, controladores de exibição, itens de navegação e muito mais. Todos estão listados na Referência de componentes.

Vamos destacar os detalhes da bicicleta. No arquivo app.html, substitua as marcas div por material e category no último exemplo com um componente lightning-badge. Veja o 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>

Salve o arquivo.

As palavras Aço e Montanha aparecem como emblemas. É realmente muito simples.

Estrutura de criação de componentes

Um componente só precisa de uma pasta e arquivos com o mesmo nome. Eles são automaticamente vinculados por nome e local.

Arquivos do componente em uma pasta

Todos os componentes Web do Lightning têm um namespace separado do nome da pasta por um hífen. Por exemplo, a marcação do componente Web do Lightning com o nome de pasta app no namespace c padrão é <c-app>.

No entanto, a Salesforce Platform não permite hifens na pasta do componente nem nos nomes de arquivos. E se o nome de um componente tiver mais de uma palavra, como "mycomponent"? Não é possível nomear a pasta e os arquivos como my-component, mas temos uma solução útil.

Use letras concatenadas para nomear seu componente como myComponent. Os nomes de pastas de componentes com palavras concatenadas mapeiam para palavras separadas por hifens na marcação. Na marcação, para fazer referência a um componente com nome de pasta myComponent, use <c-My-Component>.

Por exemplo, o repositório de Exemplos de LWC tem a pasta viewSource que contém os arquivos do componente viewSource. Quando o componente hello faz referência ao componente viewSource em HTML, ele usa c-view-source.

OK. Vamos observar o JavaScript.

Como trabalhar com JavaScript

É aqui que você faz as coisas acontecerem. Como você viu até agora, os métodos JavaScript definem o que fazer com entradas, dados, eventos, alterações de estado e muito mais para fazer seu componente funcionar.

O arquivo JavaScript de um componente Web do Lightning deve incluir pelo menos esse código, onde MyComponent é o nome que você atribui à classe do componente.

import { LightningElement } from 'lwc';

export default class MyComponent extends LightningElement {

}

A instrução export define uma classe que estende a classe LightningElement. Como prática recomendada, o nome da classe geralmente corresponde ao nome do arquivo da classe JavaScript, mas isso não é um requisito.

O módulo LWC

Os componentes Web do Lightning usam módulos (os módulos internos foram introduzidos no ECMAScript 6) para agrupar a funcionalidade principal e torná-la acessível ao JavaScript no arquivo do componente. O lwc é o módulo principal dos componentes Web do Lightning.

Inicie o módulo com a instrução import e especifique a funcionalidade do módulo que seu componente usa.

A instrução import indica que o JavaScript usa a funcionalidade LightningElement no 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);

  }

}

O LightningElement é a classe básica dos componentes Web do Lightning que nos permite usar connectedCallback().
O método connectedCallback() é um de nossos ganchos do ciclo de vida. Aprenderemos mais sobre ganchos do ciclo de vida na próxima seção. Por enquanto, saiba que o método é acionado quando um componente é inserido no DOM (Modelo de objeto de documento). Nesse caso, ele inicia o temporizador.

Ganchos do ciclo de vida

Os Componentes Web do Lightning oferecem métodos que permitem conectar seu código a eventos críticos no ciclo de vida de um componente. Esses eventos incluem o momento que um componente:

É criado
É adicionado ao DOM
É renderizado no navegador
Encontra erros
É removido do DOM

Responda a qualquer um desses eventos de ciclo de vida usando métodos de retorno de chamada. Por exemplo, o método connectedCallback() é invocado quando um componente é inserido no DOM. O método disconnectedCallback() é invocado quando um componente é removido do DOM.

No arquivo JavaScript que usamos para testar nossa renderização condicional, usamos o método connectedCallback() para executar automaticamente o código quando o componente é inserido no DOM. O código aguarda três segundos e, em seguida, define ready como true.

import { LightningElement } from 'lwc';

export default class App extends LightningElement {

  ready = false;

  connectedCallback() {

    setTimeout(() => {

      this.ready = true;

    }, 3000);

  }

}

Quando você usa este exemplo em um editor como o VS Code, poderá ver um aviso de lint "Operação assíncrona restrita..." para a função setTimeout(). Este aviso indica que você está usando uma operação assíncrona que geralmente é usada de forma incorreta. Ela atrasa comportamentos com base no tempo em vez de esperar por um evento. Nesse caso, setTimeout() é adequada para demonstrar um atraso de tempo arbitrário e o aviso não deve impedi-lo de usar a função.

Além disso, observe que usamos a palavra-chave this. Você deve conhecer o uso da palavra-chave se tiver codificado em JavaScript e ela se comporta do mesmo jeito que se comporta em outros ambientes. Em JavaScript, a palavra-chave this refere-se ao nível superior do contexto atual. Aqui, o contexto é esta classe. O método connectedCallback() atribui o valor da variável ready de nível superior. Esse é um ótimo exemplo de como os Componentes Web do Lightning permitem trazer recursos de JavaScript para o desenvolvimento. Na seção Recursos, há um link com boas informações sobre this.

Decoradores

Os decoradores costumam ser usados em JavaScript para modificar o comportamento de uma propriedade ou função.

Para usar um decorador, importe-o do módulo lwc e coloque-o antes da propriedade ou função.

import { LightningElement, api } from 'lwc';

export default class MyComponent extends LightningElement{

  @api message;

}

Você pode importar vários decoradores. No entanto, uma única propriedade ou função pode ter apenas um decorador. Por exemplo, uma propriedade não pode ter decoradores @api e @wire.

Exemplos de decoradores de Componentes Web do Lightning incluem:

@api: marca um campo como público. Propriedades públicas definem a API de um componente. Um componente de proprietário que usa o componente em sua marcação HTML pode acessar as propriedades públicas do componente. Todas as propriedades públicas são reativas, ou seja, a estrutura considera a propriedade para alterações. Quando o valor da propriedade é alterado, a estrutura reage e renderiza novamente o componente.

Campo e Propriedade são termos quase intercambiáveis. Um autor de componente declara campos em uma classe JavaScript. Uma instância da classe tem propriedades. Para os consumidores de componentes, os campos são propriedades. Em um componente Web do Lightning, apenas os campos que um autor de componente decora com @api estão publicamente disponíveis para os consumidores como propriedades do objeto.

@track: diz à estrutura para considerar alterações nas propriedades de um objeto ou nos elementos de uma matriz. Se ocorrer uma alteração, a estrutura renderizará o componente novamente. Todos os campos são reativos. Se o valor de um campo for alterado e o campo for usado em um modelo, ou no getter de uma propriedade usada em um modelo, a estrutura renderizará o componente novamente. Você não precisa decorar o campo com @track. Use @track somente se um campo contiver um objeto ou uma matriz e se quiser que a estrutura considere as alterações nas propriedades do objeto ou nos elementos da matriz. Se quiser alterar o valor de toda a propriedade, não será necessário usar @track.

Antes da versão Spring ’20, você tinha que usar @track para marcar campos (também conhecidos como propriedades privadas) como reativos. Você já não precisa fazer isso. Use @track apenas para dizer à estrutura para considerar alterações nas propriedades de um objeto ou nos elementos de uma matriz. Alguns exemplos herdados ainda podem usar @track desnecessários, mas tudo bem, pois o uso do decorador não altera a funcionalidade nem quebra o código.

@wire: Oferece uma maneira fácil de obter e vincular dados de uma organização do Salesforce.

Veja um exemplo usando o decorador @api para renderizar um valor de um componente (bike) em outro componente (app). A estrutura do arquivo fica assim:

Estrutura de arquivo do aplicativo de exemplo.

O componente do aplicativo usa o seguinte HTML.

<!-- app.html -->

<template>

  <div>

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

  </div>

</template>

O componente do aplicativo usa o seguinte 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'

  };

}

O componente bike usa o seguinte HTML.

<!-- bike.html -->

<template>

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

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

</template>

O componente bike usa o seguinte JavaScript.

// bike.js 

import { LightningElement, api } from 'lwc';

export default class Bike extends LightningElement {

  @api bike;

}

Estamos indo rápido e você teve a chance de trabalhar com algum código no VS Code. Na próxima unidade, vamos implantar algum código e falar mais sobre o ambiente onde os componentes residem.

Recursos

Guia do desenvolvedor de Componentes Web do Lightning: Reatividade
Guia do desenvolvedor de Componentes Web do Lightning: Referência (inclui diretivas do modelo HTML, decoradores e muito mais)
Documentos da Web do MDN: this