Tarefas comuns de script de cliente

  • 8 minutos

O modelo de objeto da API do cliente é amplo e avançado. Ao se familiarizar com os scripts do cliente, você perceberá que pode usar muitos objetos e métodos de API para implementar sua lógica. Nesta unidade, veremos algumas das tarefas comuns que podem ser executadas e as técnicas usadas para realizá-las.

Acessar dados de coluna do Dataverse

Uma coluna do Dataverse é representada como um objeto de atributo no modelo de objeto. Você pode usar o método getAttribute() do objeto formContext para localizar rapidamente um atributo específico ou todos os atributos presentes no formulário. Cada objeto de atributo inclui alguns métodos comuns que estão disponíveis independentemente do tipo de dados. Existem também outros métodos disponíveis para tipos de dados de atributo específicos (texto, número, data etc.).

Observação

O código de exemplo pressupõe que os atributos e controles usados estejam presentes. A maioria dos métodos retornará nulo se os objetos não estiverem disponíveis, e as verificações defensivas comuns deverão ser usadas na prática.

Dica

As coleções retornadas pelos métodos da API do cliente têm alguns métodos úteis que podem ser usados para fazer a iteração pelos elementos. Para obter mais informações, consulte Cobranças (referência de API de cliente) em aplicativos baseados em modelos - Power Apps.

Tarefa Exemplo
Acessar por nome javascript var nameAttribute = formContext.getAttribute("name"); Atribui o atributo da coluna Nome da Conta à variável nameAttribute. Se o atributo não estiver presente no formulário, o método getAttribute retornará um valor nulo.
Acessar todos os atributos javascript var allAttributes = formContext.getAttribute(); Atribui uma matriz de todos os atributos na coleção formContext.data.entity.attributes à variável allAttributes.

Usar atributos

Tarefa Exemplo
Obter o valor de um atributo javascript var nameValue = formContext.getAttribute("name").getValue(); Atribui o valor da coluna Nome da Conta à variável nameValue.
Definir o valor de um atributo javascript formContext.getAttribute("name").setValue("new name"); Define o valor da coluna Nome da Conta como "new name".
Obter o objeto de opção selecionado no momento em um atributo OptionSet (a coluna Opção do Dataverse) javascript var addressTypeOption = formContext.getAttribute("address1_addresstypecode").getSelectedOption(); Atribui a opção selecionada na coluna Tipo de Endereço à variável addressTypeOption.
Determinar se um valor de atributo foi alterado na interface do usuário desde que o formulário foi aberto javascript var isNameChanged = formContext.getAttribute("name").getIsDirty(); Atribui um valor booliano que indica se o valor da coluna Nome da Conta foi alterado e atribui o valor à variável isNameChanged.
Alterar a obrigatoriedade de dados na coluna para salvar um registro javascript formContext.getAttribute("creditlimit").setRequiredLevel("required"); Torna necessária a coluna Limite de Crédito. javascript formContext.getAttribute("creditlimit").setRequiredLevel("none"); Torna opcional a coluna Limite de Crédito.
Determinar se os dados em um atributo serão enviados quando o registro for salvo javascript var nameSubmitMode = formContext.getAttribute("name").getSubmitMode(); O valor da variável nameSubmitMode será o texto always, never ou dirty para representar o submitMode da coluna Nome da Conta.
Controlar se os dados em um atributo serão salvos quando o registro for salvo javascript formContext.getAttribute("name").setSubmitMode("always"); O exemplo força o valor da coluna Nome da Conta a sempre ser salvo, mesmo quando não tiver sido alterado.
Quando a segurança no nível da coluna tiver sido aplicada a um atributo, determine se um usuário tem privilégios para executar operações criar, ler ou atualizar no atributo. javascript var canUpdateNameAttribute = formContext.getAttribute("name").getUserPrivilege().canUpdate; Atribui um valor booliano que representa o privilégio do usuário para atualizar a coluna Nome da Conta para a variável canUpdateNameAttribute.

Acessar controles de formulário

Tarefa Exemplo
Acessar todos os controles para um atributo específico javascript var nameControls = formContext.getAttribute("name").controls.get(); Atribui uma matriz de todos os controles do atributo name à variável nameControls. A maioria dos atributos é representada por um controle, mas poderá haver mais de um se uma coluna tiver sido adicionada ao formulário mais de uma vez.
Acessar um controle por nome javascript var nameControl = formContext.getControl("name"); O primeiro controle adicionado a um formulário para uma coluna terá o mesmo nome que a coluna. Cada um dos outros nomes de controle tem um número de índice acrescentado ao nome. Por exemplo, três controles para a coluna nome terão os nomes: name, name1 e name2, respectivamente.
Acessar todos os controles javascript var allControls = formContext.getControl(); Atribui uma matriz de todos os controles na coleção formContext.ui.controls à variável allControls.

Usar controles de formulário

Assim como os objetos de atributo, os objetos de controle têm um conjunto de métodos comum, independentemente do tipo. Eles também têm métodos especializados com base no tipo de controle.

Tarefa Exemplo
Determinar se um controle está visível javascript var isNameVisible = formContext.getControl("name").getVisible(); Atribui um valor booliano à variável isNameVisible que representa se a coluna Nome da Conta está visível.
Ocultar ou mostrar um controle javascript formContext.getControl("name").setVisible(false); Oculta a coluna Nome da Conta.
Obter uma referência ao atributo do controle javascript var nameAttribute = formContext.getControl("name").getAttribute(); Atribui o atributo do controle da coluna Nome da Conta à variável nameAttribute.
Desabilitar ou habilitar todos os controles para um atributo javascript formContext.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); }); Lembre-se de que qualquer atributo pode ter vários controles.
Alterar o rótulo de um controle javascript formContext.getControl("name").setLabel("Company Name"); Define o rótulo da coluna Nome da Conta como o texto Company Name.
Obter o pai de um controle javascript var parentSection = formContext.getControl("name").getParent(); Atribui o controle pai da coluna Nome da Conta à variável parentSection.
Definir o foco em um controle javascript formContext.getControl("name").setFocus(); Define o foco de entrada atual para a coluna Nome da Conta.

Usar guias e seções

Cada formulário tem uma coleção de guias. Cada guia tem uma coleção de seções. Cada seção tem uma coleção de controles. Você pode acessar esses elementos programaticamente e usar seus métodos.

Tarefa Exemplo
Mostrar ou ocultar uma guia javascript formContext.ui.tabs.get("general").setVisible(false); Oculta a guia general.
Inserir um rótulo para a guia javascript formContext.ui.tabs.get("general").setLabel("Major"); Define o rótulo da guia general para o texto Major.
Ocultar ou mostrar uma seção javascript formContext.getControl("industrycode").getParent().setVisible(false); Oculta a seção que contém a coluna Código do Setor.

Usar dados da entidade

A tabela a seguir contém métodos que podem ser usados para obter informações sobre o registro atual.

Tarefa Exemplo
Obter a ID do registro atual javascript var recordId = formContext.data.entity.getId(); Atribui um identificador exclusivo do registro atual à variável recordId. Se o formulário for aberto para criar um novo registro, será retornado um valor nulo.
Salvar o registro atual javascript formContext.data.entity.save(); Use saveandclose ou saveandnew para executar as ações equivalentes usando Salvar e Fechar ou Salvar e Novo.
Determine se qualquer dado no registro atual é alterado. javascript var isDirty = formContext.data.entity.getIsDirty(); Atribui um valor booliano que indica se o valor de qualquer coluna do formulário foi alterado para a variável isDirty.