Skip to main content

Usar o Lightning Data Service para trabalhar com dados

Objetivos de aprendizagem

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

  • Criar soluções que incluam componentes básicos lightning-record-*-form.
  • Usar os adaptadores de conexão do Lightning Data Service (LDS) para ler dados.
  • Usar as funções do LDS para modificar dados.
Nota

Nota

Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e use as traduções fornecidas entre parênteses para navegar. Copie e cole somente os valores em inglês porque as validações dos desafios dependem de dados em inglês. Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

Se essa for sua primeira incursão nos componentes Web do Lightning, espere. Dê um passo para trás. Antes de trabalhar neste módulo, conclua o módulo Noções básicas dos componentes Web do Lightning e a trilha Aprender a trabalhar com o JavaScript aqui no Trailhead. O trabalho aqui realizado se baseia nos conceitos e no trabalho realizado em ambos.

Trabalhar com dados em componentes Web do Lightning

Nos componentes Web do Lightning, existem várias maneiras de trabalhar com os dados do Salesforce. Saber qual solução usar para cada caso de uso permite que você escreva um código menor, mais simples e mais sustentável. Usar a melhor solução para cada situação também melhora o desempenho de seus componentes e aplicativos.

Neste módulo, você aprenderá quando e como usar soluções diferentes. Analisaremos primeiro as opções mais fáceis, mas menos personalizáveis. Mais tarde, consideraremos opções mais complexas e mais personalizáveis.

Trabalhar com dados usando o Lightning Data Service

O Lightning Data Service é a maneira preferencial (e mais fácil) de trabalhar com os dados do Salesforce. Com o Lightning Data Service, os desenvolvedores usam o JavaScript para conectar componentes a dados do Salesforce.

O Lightning Data Service também oferece segurança ao fazer chamadas ao servidor para proteger os pontos de extremidade da API de interface de usuário. Usando um cache compartilhado do lado do cliente em todos os componentes, o Lightning Data Service maximiza o desempenho. Quando um registro é armazenado em cache, ele é recuperado do cache, eliminando chamadas desnecessárias para o servidor.

Não espere receber dados de um adaptador de conexão em um ponto específico do ciclo de vida do componente. Os dados de um adaptador de conexão nem sempre estão acessíveis em ganchos de ciclo de vida como connectedCallback() ou renderedCallback(). Para saber mais sobre o ciclo de vida dos dados do serviço de conexão, confira Entender o serviço de conexão.

O Lightning Data Service mantém dados uniformes e atualizados sobre vários componentes e clientes durante o ciclo de vida do aplicativo. Se vários componentes usam o Lightning Data Service para trabalhar com um registro e um deles atualiza o registro, os outros refletem automaticamente essa atualização.

Nas seções a seguir, destacamos diferentes maneiras de trabalhar com os dados do Salesforce usando o Lightning Data Service.

Ler ou modificar dados com componentes básicos do formulário de registro

A maneira mais fácil de trabalhar com registros únicos nos componentes Web do Lightning é usar os componentes do lightning-record-*-form. Esses componentes básicos usam o Lightning Data Service nos bastidores e herdam seus recursos de cache e sincronização. Cada componente básico oferece diferentes recursos e níveis de personalização.

  • O componente básico lightning-record-form é o mais simples deles. Com o lightning-record-form, você pode especificar um layout e permitir que os administradores configurem campos de formulário de forma declarativa. Você também pode especificar uma lista ordenada de campos para definir programaticamente o que é exibido. lightning-record-form permite que você visualize e edite registros.
  • O componente básico lightning-record-view-form permite a visualização de registros.
  • O componente básico lightning-record-edit-form permite a edição de registros.

Escolha lightning-record-view-form ou lightning-record-edit-form quando precisar personalizar o layout do formulário, preencher valores de campo ou alterar como os dados do registro são renderizados.

Veja um exemplo que usa lightning-record-form para criar contas.

accountCreator.html

<template>
    <lightning-card>
        <lightning-record-form
            object-api-name={objectApiName}
            fields={fields}
            onsuccess={handleSuccess}>
        </lightning-record-form>
    </lightning-card>
</template>

accountCreator.js

import { LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import NAME_FIELD from '@salesforce/schema/Account.Name';
import REVENUE_FIELD from '@salesforce/schema/Account.AnnualRevenue';
import INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';
export default class AccountCreator extends LightningElement {
    objectApiName = ACCOUNT_OBJECT;
    fields = [NAME_FIELD, REVENUE_FIELD, INDUSTRY_FIELD];
    handleSuccess(event) {
        const toastEvent = new ShowToastEvent({
            title: "Account created",
            message: "Record ID: " + event.detail.id,
            variant: "success"
        });
        this.dispatchEvent(toastEvent);
    }
}

Destaques do código:

accountCreator.html 

  • Linha 3: usando lightning-record-form na marcação, recebemos todos os benefícios de segurança e desempenho que o Lightning Data Service oferece. Quando lightning-record-form não especifica recordId, ele opera no modo edit (editar) e cria um registro ao enviar.
  • Linha 4: a vinculação da propriedade object-api-name indica o tipo de objeto a ser carregado.
  • Linha 5: a vinculação da propriedade fields (campos) indica os campos a serem exibidos no formulário.
  • Linha 6: definimos handleSuccess como o manipulador para o evento success (sucesso).

accountCreator.js 

  • Linhas 3 a 6: no início do arquivo, importamos referências ao objeto Conta e aos seus campos. Fazer referência a objetos e campos dessa forma assegura a integridade referencial. O Salesforce verifica se o objeto e os campos existem, impede que eles sejam excluídos e garante que sejam incluídos em pacotes e conjuntos de alterações que fazem referência ao componente. Importar referências de objeto e campo garante que o código de seu componente ainda funcione se o objeto ou os campos forem renomeados.
  • Linha 10: definimos o manipulador de eventos handleSuccess para o evento success (sucesso). handleSuccess é executado quando a operação de salvar é bem-sucedida.
  • Linhas 11 a 17: mostramos uma mensagem de notificação acionando ShowToastEvent, no qual o event.detail.id é uma referência à propriedade id do registro recém-criado.

Se precisar de mais personalização do que os componentes do lightning-record-*-form oferecem, você pode invocar diretamente o Lightning Data Service usando um adaptador de conexão ou uma função JavaScript. 

Ler dados com adaptadores de conexão do LDS

Os adaptadores de conexão do LDS são outra forma de trabalhar com os dados do Salesforce. Use um adaptador de conexão para ler dados do Salesforce (registros) e metadados (detalhes do layout, campos em um objeto e assim por diante). Para usá-los, decore uma propriedade ou função com @wire e especifique o adaptador de conexão.

Os adaptadores de conexão do LDS conferem o cache do LDS primeiro e solicitam dados do servidor apenas quando necessário. Os adaptadores reagem para alterar e atualizar os dados de acordo. Por exemplo, quando o valor do parâmetro é alterado ou outros componentes modificam dados no cache do Lightning Data Service, um adaptador provisiona os novos dados à propriedade ou função conectada.

Vamos analisar um exemplo que usa o adaptador de conexão getRecord.

wireGetRecordProperty.js

import { LightningElement, api, wire } from 'lwc';
import { getRecord, getFieldValue } from 'lightning/uiRecordApi';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
export default class WireGetRecordProperty extends LightningElement {
    @api recordId;
    @wire(getRecord, { recordId: '$recordId', fields: [ACCOUNT_NAME_FIELD] })
    account;
    get name() {
        return getFieldValue(this.account.data, ACCOUNT_NAME_FIELD);
    }
}

Destaques do código:

  • Linha 2: importamos o adaptador de conexão getRecord e a função getFieldValue.
  • Linha 3: assim como fizemos no exemplo accountCreator, importamos uma referência para o campo Account.Name. (Na linha 6, usamos isso para informar ao adaptador de conexão getRecord quais campos recuperar.)
  • Linha 5: quando o componente wireGetRecordProperty é colocado em uma página de registro, @api recordId permite que o componente pai (o FlexiPage) passe a ID do registro atual para o componente.
  • Linha 6: para conectar a propriedade da conta, aplicamos o decorador @wire e especificamos o adaptador de conexão para chamar (getRecord), bem como os parâmetros de que o adaptador precisa (recordId e fields).
  • Linha 7: o adaptador de conexão provisiona um fluxo de valores à propriedade account, que será definido várias vezes. Se um registro for recuperado, ele será armazenado em account.data. Se a recuperação de registro falhar, o erro será armazenado em account.error.
  • Linhas 6 a 7: na primeira vez que um valor é atribuído à propriedade recordId, o adaptador de conexão obtém os dados do servidor e os armazena no cache do LDS para acesso futuro. Ao passar o parâmetro recordId como uma string com prefixo $, tornamos recordId reativo. Toda vez que o valor de recordId é alterado, o adaptador de conexão obtém novos dados, seja no cache ou no servidor. Se outro componente modificar o registro em cache, o adaptador de conexão provisiona o novo valor do registro à propriedade account.
  • Linhas 8 a 10: Definimos um getter para a propriedade name. A função getFieldValue dá acesso aos valores do campo por meio dos dados retornados.

Neste exemplo, a propriedade name pode ser recuperada no arquivo HTML do seguinte modo:

wireGetRecordProperty.html

<template>
  Account Name: {name}
</template>

wireGetRecordProperty é um exemplo de decoração de propriedade. Podemos decorar uma função da mesma forma. Isso é útil quando você deseja executar alguma lógica sobre os registros retornados. Aqui está o exemplo anterior (wireGetRecordProperty), retrabalhado para conectar uma função (wiredAccount) em vez de uma propriedade.

wireGetRecordFunction.js

import { LightningElement, api, wire } from 'lwc';
import { getRecord, getFieldValue } from 'lightning/uiRecordApi';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
export default class WireGetRecord extends LightningElement {
    @api recordId;
    data;
    error;
    @wire(getRecord, { recordId: '$recordId', fields: [ACCOUNT_NAME_FIELD] })
    wiredAccount({data, error}) {
        console.log('Execute logic each time a new value is provisioned');
        if (data) {
            this.data = data;
            this.error = undefined;
        } else if (error) {
            this.error = error;
            this.data = undefined;
        }
    }
    get name() {
        return getFieldValue(this.data, ACCOUNT_NAME_FIELD);
    }
}

Destaques do código:

  • Linhas 8 a 9: Em vez de decorar uma propriedade, vamos decorar a função wiredAccount. A função recupera, como um parâmetro, um objeto que tem dois atributos: data (dados) e error (erro). Usamos a desestruturação ES6 de objeto para descompactar os atributos do objeto.
  • Linhas 11 a 17: Como os adaptadores de conexão do LDS não provisionam um único valor, mas sim um fluxo de valores, a função wiredAccount pode ser invocada várias vezes. Como resultado, a função conectada deve redefinir os estados que ela influencia. Então, aqui, nas linhas 11 a 17, se o adaptador de conexão provisiona novos dados, armazenamos esses dados na propriedade data (dados) e definimos a propriedade error (erro) como indefinida. Como alternativa, se houver um erro, armazenamos o erro na propriedade error (erro) e definimos a propriedade data (dados) como indefinida.

Neste exemplo, podemos acessar a propriedade name da mesma forma que a acessamos no exemplo anterior.

Modificar dados com funções do LDS

Os adaptadores de conexão do LDS são ótimos para ler dados, mas para criar, atualizar ou excluir registros, você precisa de uma função do LDS. Observe que, embora os adaptadores de conexão sejam invocados pelo mecanismo dos componentes Web do Lightning, as funções são invocadas imperativamente. As funções do LDS notificam o cache do LDS quando registros são criados, atualizados ou excluídos. Considere este exemplo, que usa a função do LDS createRecord para criar um registro de conta.

ldsCreateRecord.js

import { LightningElement} from 'lwc';
import { createRecord } from 'lightning/uiRecordApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
export default class LdsCreateRecord extends LightningElement {
    handleButtonClick() {
        const recordInput = {
            apiName: ACCOUNT_OBJECT.objectApiName,
            fields: {
                [ACCOUNT_NAME_FIELD.fieldApiName] : 'ACME'
            }
        };
        createRecord(recordInput)
            .then(account => {
                // code to execute if create operation is successful
            })
            .catch(error => {
                // code to execute if create operation is not successful
            });
    }
}

Destaques do código:

  • Linha 2: importamos a função do LDS createRecord.
  • Linhas 3 a 4: importamos o objeto Account e o campo Account.Name (como fizemos nos exemplos anteriores) para garantir a integridade referencial.
  • Linha 6: definimos o método handleButtonClick como um manipulador de eventos. Ele responde ao evento que ocorre quando um usuário clica em um lightning-button no arquivo .html (não mostrado). Quando handleButtonClick é invocado, ele invoca a função CreateRecord imperativamente.
  • Linha 10: nosso manipulador de eventos transmite uma string para o campo Account.Name, necessário para o adaptador criar uma nova conta.
  • Linha 13: quando invocamos uma função do LDS imperativamente, ela retorna uma promessa (um objeto do JavaScript que simplifica a execução de chamadas assíncronas).
  • Linhas 14 a 16: no método then, definimos o que acontece se a conta for criada com sucesso.
  • Linhas 17 a 19: no método catch, definimos o que acontece se a criação da conta falhar.

Nota:  as funções do LDS permitem que você trabalhe somente com registros individuais. Embora você possa usar várias funções no mesmo componente (para criar dois tipos diferentes de registros na mesma operação, por exemplo), cada função é executada em sua própria transação independente. Portanto, não há lógica de reversão comum. Se você precisar que uma operação DML combinada seja transacional, cogite usar o Apex.

Para saber mais sobre os adaptadores e funções de conexão do LDS e como usá-los, visite o Guia do desenvolvedor de componentes Web do Lightning e o blog de desenvolvedores do Salesforce.

Implantar um componente Web do Lightning que cria contas

Agora que analisamos diferentes maneiras de trabalhar com o Lightning Data Service, vamos trabalhar em um exemplo.

Antes de começar

Presumimos que você tem seu ambiente de desenvolvimento Salesforce DX configurado, e se sente confortável em usá-lo para criar componentes Web do Lightning e implantá-los em uma organização. Se você ainda não está familiarizado com esse processo, conclua o projeto Início rápido: Componentes Web do Lightning.

Criar um novo Trailhead Playground

Para este projeto, é preciso criar um novo Trailhead Playground. Role até a parte inferior desta página, clique na seta para baixo ao lado de Iniciar e selecione Criar um Trailhead Playground. Normalmente, leva de 3 a 4 minutos para criar um novo Trailhead Playground.

Nota:  sim, estamos falando de um Trailhead Playground totalmente novo! Se você estiver usando uma organização ou um playground existente, poderá ter problemas na hora de concluir os desafios.

Obtenha seu nome de usuário e senha para o Trailhead Playground

Vá ao seu Trailhead Playground. (Caso não esteja aberto, role até o fim desta página e clique em Iniciar.) Se você vir uma guia na sua organização com o rótulo Obter suas credenciais de login, ótimo! Avance para a etapa 1. 

Caso contrário, no App Launcher (Iniciador de aplicativos) (Iniciador de aplicativos), encontre e abra o Playground Starter e siga as etapas. Se você não vir o aplicativo Playground Starter, consulte Encontrar o nome de usuário e a senha para seu Trailhead Playground na Ajuda do Salesforce.

  1. Clique na guia Obter suas credenciais de login e anote seu nome de usuário.
  2. Clique em Redefinir minha senha. Isso envia um email para o endereço associado ao seu nome de usuário.
  3. Clique no link exibido no email.
  4. Insira uma nova senha, confirme-a e clique em Alterar senha.

Pronto para pôr a mão na massa? Vamos lá.

Neste exercício, você adiciona um componente Web do Lightning ao seu projeto e o implanta em seu Trailhead Playground. 

  1. Crie um novo projeto:
    1. Abra o Visual Studio Code.
    2. Abra a paleta de comandos: clique em Visualizar | Paleta de comandos.
    3. Na paleta de comandos, selecione SFDX: Create Project.
      Se não vir na lista, digite SFDX:Create Project (SFDX:Criar projeto) e pressione Enter.
    4. Aceite o modelo padrão.
    5. Como nome do projeto, insira workingWithDataInLWC e pressione Enter.
    6. Selecione um local para o novo projeto e clique em Criar projeto.
  1. Autorize seu Trailhead Playground:
    1. Na paleta de comandos, selecione (ou insira) SFDX: Autorizar uma organização.
    2. Selecione Produção: login.salesforce.com e pressione Enter.
    3. Em alias, insira lwc_and_salesforce_data e, em seguida, pressione Enter.
    4. Use o nome de usuário e a senha do Trailhead Playground para entrar.
    5. Quando você tiver feito login em seu Trailhead Playground, deixe-o aberto e volte para o Visual Studio Code.
  1. Crie um componente Web do Lightning:
    1. No painel do Explorer, clique com o botão direito na pasta lwc e selecione SFDX: Criar componente Web do Lightning.
    2. Como nome do componente, insira accountCreator e pressione Enter.
    3. Pressione Enter novamente para aceitar o diretório padrão.
  1. Substitua o conteúdo de seus arquivos accountCreator.html e accountCreator.js pelo código fornecido na seção Ler ou modificar dados com componentes básicos do formulário de registro, mostrada anteriormente nesta unidade.
  2. Para disponibilizar esse componente nas páginas do aplicativo em uma organização, substitua o conteúdo do seu arquivo accountCreator.js-meta.xml por este código:
    <?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>48.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
    </targets>
</LightningComponentBundle>
  3. Salve os três arquivos: accountCreator.html, accountCreator.js e accountCreator.js-meta.xml.
  4. Implante os arquivos de projeto em seu Trailhead Playground. (Clique com o botão direito do mouse no diretório accountCreator e selecione SFDX: Implantar fonte para organização.)
  5. Se o Trailhead Playground não estiver aberto, abra-o. (Na paleta de comandos, selecione (ou insira) SFDX: Abrir organização padrão).
  6. Em seu Trailhead Playground, clique em Configuração e, em seguida, selecione Setup (Configuração).
  7. Na caixa Busca rápida, insira Lightning App Builder (Criador de aplicativo Lightning) e selecione Lightning App Builder (Criador de aplicativo Lightning).
  8. Crie uma página do Lightning:
    1. Clique em Novo.
    2. Selecione Página de aplicativo e clique em Avançar.
    3. Em Label (Rótulo), insira Working with Data (Como trabalhar com dados) e, então, clique em Next (Avançar).
    4. Como layout, escolha Cabeçalho e barra lateral esquerda.
    5. Clique em Done (Concluído).
  1. Arraste o componente accountCreator para a barra lateral da página.
  2. Salve a página.
  3. Ative a página: Mantenha o nome do aplicativo padrão (“Working with Data”) e clique em Salvar.
  4. Quando for solicitado que você adicione a página ao menu de navegação, clique em Concluir.
  5. Abra a nova página: Na pesquisa do Iniciador de aplicativos, insira work (trabalhar) e selecione Working with Data (Como trabalhar com dados).

Pronto. Você tem um componente Web do Lightning que usa lightning-record-form para criar registros de conta na página Working with Data. Usar o Lightning Data Service é uma maneira de trabalhar com os dados do Salesforce nos componentes Web do Lightning. Na próxima unidade, você aprenderá como usar o Apex para trabalhar com dados.

Recursos

Compartilhe seu feedback do Trailhead usando a Ajuda do Salesforce.

Queremos saber sobre sua experiência com o Trailhead. Agora você pode acessar o novo formulário de feedback, a qualquer momento, no site Ajuda do Salesforce.

Saiba mais Continue compartilhando feedback