Partilhar via

Referência rápida do script de formulário

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Este artigo apresenta uma referência rápida de métodos de scripts de formulários frequentemente usados baseados em tarefas que você executa com eles. Para obter a referência completa, consulte Referência de programação do cliente. Todos os exemplos desta página usam o formulário principal da entidade de conta padrão, salvo especificação em contrário.

Neste tópico

Atributos

  • Acessar atributos

  • Obter ou definir dados de atributos da entidade

  • Obter metadados do atributo

Salvar argumentos de evento

Exibir notificações

Controles

  • Acessar controles de formulário

  • Acessar controles de cabeçalho

  • Acesso aos controles de fluxo do processo empresarial

  • Métodos de controle do formulário

  • Métodos de controle OptionSet

  • Métodos de controle IFRAME e recursos da Web

  • Métodos de controle de pesquisa

  • Métodos de controle de Subgrade

  • Métodos de controle de dados

Navegação de formulário

Guias e seções

Adicionar ou remover manipuladores de eventos no tempo de execução

Métodos de informações contextuais

Obter, atualizar ou salvar dados da entidade

Atributos

Os atributos armazenam os dados disponíveis no registro.

Acessar atributos

Os atributos estão disponíveis no conjunto Xrm.Page.data.entity.attributes. Para acessar um atributo, você pode usar o método Xrm.Page.data.entity.attributes.9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get ou a versão de atalho Xrm.Page.getAttribute. O método get aceita quatro tipos de argumentos:

  • Cadeia de caracteres: Retorna um objeto de atributo onde o nome do atributo corresponde a cadeia de caracteres.

  • Número: Retorna o objeto do atributo onde o índice do conjunto Xrm.Page.data.entity.attributes corresponde ao número.

  • Nenhum: Retorna uma matriz de todos os atributos.

  • Delegate function(attribute,index): retorna uma matriz de todos os atributos do conjunto Xrm.Page.data.entity.attributes que fizerem com que a função delegar retorne true.

Tarefa

Exemplo

Acessar um atributo por nome

var nameAttribute = Xrm.Page.getAttribute("name");

Atribui o atributo para o campo Nome da Conta à variável nameAttribute

Acessar um atributo por índice

var firstAttribute = Xrm.Page.getAttribute(0);

Atribui o primeiro atributo no conjunto Xrm.Page.data.entity.attributes à variável firstAttribute.

Acessar todos os atributos

var allAttributes = Xrm.Page.getAttribute();

Atribui uma matriz de todos os atributos no conjunto Xrm.Page.data.entity.attributes à variável allAttributes.

Acessa todos os atributos que atendam a critérios específicos

var optionsetAttributes = Xrm.Page.getAttribute(function (attribute, index) {
return attribute.getAttributeType() == "optionset";
});

Atribui uma matriz de todos os atributos no conjunto Xrm.Page.data.entity.attributes que atende aos critérios definidos na função anônima, que retorna true quando o tipo de atributo é "optionset" à variável optionsetAttributes.

O conjunto Xrm.Page.data.entity.attributes também tem um método 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach que pode ser usado para acessar atributos dentro de uma função. As seguintes funções writeRequiredAttributesToConsole gravarão os nomes de todos os atributos que exigem dados para o console de depuração:

function writeRequiredAttributesToConsole() {
 var requiredAttributeNames = [];

 Xrm.Page.data.entity.attributes.forEach(
 function (attribute, index) {
  if (attribute.getRequiredLevel() == "required")
  { requiredAttributeNames.push(attribute.getName()); }
 });

 if (requiredAttributeNames.length > 0) {
  if (typeof console != "undefined") {
   console.log(requiredAttributeNames.join());
  }
 }
 else {
  if (typeof console != "undefined") {
   console.log("No required attributes detected");
  }
 }
}

Neste tópico

Obter ou definir dados de atributos da entidade

Os exemplos na tabela a seguir mostram como você pode recuperar ou alterar os dados armazenados nos atributos.

Tarefa

Método

Exemplo

Obter o valor de um atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getValue

var nameValue = Xrm.Page.getAttribute("name").getValue();

Atribui o valor do campo Nome da Conta à variável nameValue.

Definir o valor de um atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setValue

Xrm.Page.getAttribute("name").setValue("new name");

Define o valor do campo Nome da Conta para "novo nome".

Obter o valor de texto da opção selecionada atualmente de um atributo optionset

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getText

var addressType = Xrm.Page.getAttribute("address1_addresstypecode").getText();

Atribui o texto da opção selecionada no campo Tipo de Endereço à variável addressType.

Obter o objeto da opção selecionado atualmente em um atributo optionset

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSelectedOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getSelectedOption();

Atribui a opção selecionada no campo Tipo de Endereço à variável addressTypeOption.

Neste tópico

Obter metadados do atributo

Os exemplos na tabela a seguir mostram como você pode consultar propriedades do atributo para compreender qual é o tipo de atributo ou alterar o comportamento do atributo.

Tarefa

Método

Exemplo

Obter o tipo de um atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getAttributeType

var attributeType = Xrm.Page.getAttribute(0).getAttributeType();

Atribui o valor de cadeia de caracteres que representa o tipo de atributo para o primeiro atributo da variável attributeType.

Verificar como o atributo foi formatado

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getFormat

var attributeFormat = Xrm.Page.getAttribute(0).getFormat();

Atribui o valor de cadeia de caracteres que representa o formato do primeiro atributo da variável attributeFormat.

Obter o valor inicial de um atributo Boolean ou optionset

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getInitialValue

var attributeInitialValue = Xrm.Page.getAttribute("address1_addresstypecode").getInitialValue();

Atribui o valor do número inicial do campo Tipo de Endereço à variável attributeInitialValue.

Determina se um valor de atributo foi alterado

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsDirty

var isNameChanged = Xrm.Page.getAttribute("name").getIsDirty();

Atribui um valor Boolean que indica se o valor do campo Nome da conta foi alterado para a variável isNameChanged.

Determina se um atributo de pesquisa representa uma pesquisa de partylist.

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsPartyList

var isPartyList = Xrm.Page.getAttribute("to").getIsPartyList();

Atribui um valor Boolean indicando se a entidade Email para o campo para representa uma pesquisa da lista parcial.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Obter o valor máximo permitido para um atributo que contém um número

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMax

var newValue = 100000000000001;
var newValueBelowMax = (newValue < Xrm.Page.getAttribute("creditlimit").getMax())

Atribui um valor Boolean que indica se o valor da variável newValue excede o valor máximo permitido para o campo Limite de Crédito à variável newValueBelowMax.

Obter o comprimento máximo permitido para um atributo que contém uma cadeia de caracteres

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMaxLength

var newAccountName = "A Store";
var nameTooLong = (newAccountName.length > Xrm.Page.getAttribute("name").getMaxLength())

Atribui um valor Boolean que indica se o valor da variável newAccountName excede o comprimento máximo permitido para o campo Nome da Conta à variável nameTooLong.

Obter o valor mínimo permitido para um atributo que contém um número

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMin

var newValue = -1;
var newValueBelowMin = (newValue < Xrm.Page.getAttribute("creditlimit").getMin())

Atribui um valor Boolean que indica se o valor da variável newValue está abaixo do valor mínimo permitido para o campo Limite de Crédito à variável newValueBelowMin.

Obtém o nome lógico de um atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getName

var attributeName = Xrm.Page.getAttribute(0).getName();

Atribui o valor do nome lógico do primeiro atributo na página para a variável attributeName

Obter o objeto opção representando um valor

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getOption(1);
alert(addressTypeOption.text); //displays 'Bill To'

Mostra um alerta que exibe o texto da opção do campo Tipo de Endereço com um valor de 1.

Obter um valor numérico que representa o nível de precisão para o número de atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getPrecision

var creditLimitPrecision = Xrm.Page.getAttribute("creditlimit").getPrecision();

Atribui o valor de precisão do campo Limite de Crédito à variável creditLimitPrecision.

Obter um valor de cadeia de caracteres representando se um atributo deve ter um valor

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getRequiredLevel

var creditLimitRequired = Xrm.Page.getAttribute("creditlimit").getRequiredLevel();

O valor da variável creditLimitRequired pode ser none, required ou recommended.

Alterar se os dados são obrigatórios em um campo para salvar um registro

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setRequiredLevel

Xrm.Page.getAttribute("creditlimit").setRequiredLevel("required");

Torna o campo Limite de Crédito necessário.

Determina se os dados em um atributo serão enviados quando o registro for salvo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSubmitMode

var nameSubmitMode = Xrm.Page.getAttribute("name").getSubmitMode();

O valor da variável nameSubmitMode será always, never ou dirty para representar o submitMode para o campo Nome da Conta.

Controla se os dados em um atributo serão salvos quando o registro for salvo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setSubmitMode

Xrm.Page.getAttribute("name").setSubmitMode("always");

O exemplo forçará o valor do campo Nome da Conta para sempre ser salvo, mesmo quando não for alterado.

Quando a segurança de nível de campo for aplicada a um atributo,
determine se um usuário tem privilégios para realizar as operações de criação,
leitura ou atualização no atributo. Para obter mais informações, consulte
Como a segurança de campo pode ser usada para controlar o acesso aos valores de campo no Microsoft Dynamics 365

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getUserPrivilege

var canUpdateNameAttribute = Xrm.Page.getAttribute("name").getUserPrivilege().canUpdate;

Atribui um valor Boolean que representa o privilégio do usuário para atualizar o campo Nome da Conta à variável canUpdateNameAttribute.

Neste tópico

Salvar argumentos de evento

Para garantir a lógica comercial é frequentemente necessário impedir que um registro seja salvo de modo que ele possa incluir as informações necessárias. Para fazer isso, é preciso configurar o manipulador de eventos para passar no contexto de execução. O contexto de execução do método getEventArgs para recuperar argumentos para o evento. Esses argumentos incluem métodos que podem ser usados para controlar se um registro será salvo ou as propriedades serão consultadas informando sobre o evento save.

Tarefa

Exemplo

Evita que um registro seja salvo.

function My_PreventSaveFunction(eContext) {
 eContext.getEventArgs().preventDefault();
}

Use o parâmetro eContext para capturar o contexto de execução e use o método preventDefault incluído com argumentos de evento.

Determine qual ação iniciou o salvamento.

function My_GetSaveModeTextFunction(eContext) {
 var saveModeCode = eContext.getEventArgs().getSaveMode();
 var saveModeText = "Unknown";
 switch (saveModeCode) {
  case 1:
   saveModeText = "Save";
   break;
  case 2:
   saveModeText = "SaveAndClose";
   break;
  case 5:
   saveModeText = "Deactivate";
   break;
  case 6:
   saveModeText = "Reactivate";
   break;
  case 7:
   saveModeText = "Send";
   break;
  case 15:
   saveModeText = "Disqualify";
   break;
  case 16:
   saveModeText = "Qualify";
   break;
  case 47:
   saveModeText = "Assign";
   break;
  case 58:
   saveModeText = "SaveAsCompleted";
   break;
  case 59:
   saveModeText = "SaveAndNew";
   break;
  case 70:
   saveModeText = "AutoSave";
   break;
 }
 return saveModeText;
}

Use o parâmetro eContext para capturar o contexto de execução e use o método getSaveMode incluído com argumentos de evento para converter o valor do código inteiro no texto.

Neste tópico

Exibir notificações

As notificações oferecem uma forma de exibir uma mensagem ao usuário.

Tarefa

Método

Exemplo

Exibe uma mensagem próxima ao controle para indicar que os dados não são válidos.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.setNotification("'Test' is not a valid name.");
})

Define uma mensagem de erro de validação em cada controle no formulário para o atributo Nome da Conta.

Enquanto essa mensagem for exibida, o registro não pode ser salvo.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Remove uma mensagem já exibida para um controle.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.clearNotification();
})

Limpa todas as mensagens de erro de validação em cada controle no formulário para o atributo Nome da Conta.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Exibir notificações do nível do formulário.

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_setFormNotification

Xrm.Page.ui.setFormNotification(
"Hello",
"INFO",
"helloMsg"
);

Exibe a mensagem “Olá” na parte superior do formulário com um ícone de informações do sistema.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Remove notificações do nível do formulário

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_clearFormNotification

Xrm.Page.ui.clearFormNotification("helloMsg");

Desmarcar a mensagem anteriormente definida usando ”helloMsg" como o parâmetro uniqueid.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Exibe um diálogo de alerta de não bloqueio com uma função de retorno de chamada.

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_alertDialog

var alertDisplayed = false;
Xrm.Utility.alertDialog(
"Showing Alert",
function () { alertDisplayed = true; }
)

Exibe um alerta e define o valor da variável alertDisplayed quando foi fechada.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Exibe um diálogo de confirmação de não bloqueio com retornos de chamada diferentes dependendo do botão que o usuário clicar.

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_confirmDialog

var agree = false;
Xrm.Utility.confirmDialog(
"Do you agree?",
function () { agree = true;},
function () { agree = false; }
);

Exibe uma mensagem de confirmação e define o valor da variável agree dependendo da resposta.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Neste tópico

Controles

Os controles representam elementos da interface do usuário no formulário. Cada atributo no formulário terá pelo menos um controle associado a ele. Nem todos os controles estão associados a um atributo.IFRAME, o recurso da Web e as subgrades são controles que não possuem atributos.

Acessar controles de formulário

Os controles estão disponíveis no conjunto Xrm.Page.ui.controls. Para acessar um controle, você pode usar o método **Xrm.Page.ui.controls.**9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get ou a versão de atalho Xrm.Page.getControl.

O método get aceita quatro tipos de argumentos:

  • Cadeia de caracteres: Retorna um controle onde o nome lógico corresponde à cadeia de caracteres.

  • Número: Retorna o controle onde o índice do conjunto Xrm.Page.ui.controls corresponde ao número.

  • Nenhum: Retorna uma matriz de todos os controles.

  • Delegate function(control,index): Retorna uma matriz de todos os controles do conjunto Xrm.Page.ui.controls que fizerem com que a função delegar retorne true.

Tarefa

Exemplo

Acessa todos os controles para um atributo específico

var nameControls = Xrm.Page.getAttribute("name").controls.get();

Atribui uma matriz de todos os controles para o atributo name à variável nameControls.

Acessar um controle pelo nome

var nameControl = Xrm.Page.getControl("name");

Atribui o primeiro controle representando o campo Nome da Conta à variável nameControl.

O primeiro controle adicionado a um formulário para um atributo terá o mesmo nome do atributo. Cada nome de controle adicional terá um número de índice acrescentado ao nome. Por exemplo, três controles para o atributo name terão os nomes: name, name1e name2 , respectivamente.

Acessar um controle pelo índice

var firstControl = Xrm.Page.getControl(0);

Atribui o primeiro controle no conjunto Xrm.Page.ui.controls à variável firstControl.

Acessar todos os controles

var allControls = Xrm.Page.getControl();

Atribui uma matriz de todos os controles no conjunto Xrm.Page.ui.controls à variável allControls.

Acessa todos os controles que atendam a critérios específicos

var optionsetControls = Xrm.Page.getControl(function (control, index) {
return control.getControlType() == "optionset";
});

Atribui uma matriz de todos os atributos no conjunto Xrm.Page.ui.controls que atende aos critérios definidos na função anônima, que retorna true quando o tipo de controle é "optionsetControls" à variável.

Cada seção também contém uma coleção de controles que contém apenas os controles dessa seção. A seguinte amostra de código atribui a variável generalTabAccountInfoSectionControls a uma matriz de controles encontrada na seção Endereço da guia Geral.
var generalTabAccountInfoSectionControls = Xrm.Page.ui.tabs.get("general").sections.get("address").controls.get();

Observação

Cada atributo existe uma só vez no formulário, mas um campo pode ser adicionado ao formulário desse atributo várias vezes. Cada campo adicionado cria outro controle. Os formulários podem ser ainda mais personalizados depois que você escrever seus scripts. Os scripts que você escreve para controles de atributos devem assumir que foram incluídos no formulário várias vezes. Todas as ações realizadas em um controle para um atributo geralmente devem ser aplicadas a todos os controles desse atributo. Por exemplo, para desabilitar um controle, mas somente um deles, o usuário ainda pode inserir dados usando um controle diferente. Por esse motivo, recomendamos usar o seguinte padrão utilizando o método 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach do conjunto para aplicar a mesma lógica a todos os controles de um atributo, mesmo se houver somente um controle no momento da criação do seu script.

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

Neste tópico

Acessar controles de cabeçalho

Os controles no cabeçalho seguem a convenção de nomenclatura onde "header_” é anexado ao nome do controle. Por exemplo, se o atributo name estiver no cabeçalho é possível acessá-lo usando:
var nameControlInHeader = Xrm.Page.getControl("header_name");

Acesso aos controles de fluxo do processo empresarial

Os controles no controle do fluxo de processo empresarial seguem a convenção de nomenclatura "header_process_” é anexado ao nome do controle. Por exemplo, se o atributo name estiver no cabeçalho é possível acessá-lo usando:
var nameControlInBPF = Xrm.Page.getControl("header_process_name");

Observação

Somente os controles do estágio ativas estão no conjunto Xrm.Page.ui.controls quando o formulário for carregado. Os controles de outros fluxos de processos do setor são adicionados a um estágio para a entidade atual selecionada.

Métodos de controle do formulário

Depois de obter acesso a um controle, você pode chamar os seguintes métodos.

Tarefa

Método

Exemplo

Determine se um controle está visível

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getVisible

var isNameVisible = Xrm.Page.getControl("name").getVisible();

Atribui um valor Boolean para a variável isNameVisible que representa se o campo Nome da Conta está visível.

Ocultar ou mostrar um controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setVisible

Xrm.Page.getControl("name").setVisible(false);

Oculta o campo Nome da Conta.

Obter uma referência ao atributo para o controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getAttribute

var nameAttribute = Xrm.Page.getControl("name").getAttribute();

Atribui o atributo para o controle do campo Nome da Conta à variável nameAttribute.

Observação

Nem todos os controles têm atributos.

Determina o tipo do controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getControlType

var optionSetControls = Xrm.Page.getControl(function (control, index) { return control.getControlType() == "optionset"; });

Atribui uma matriz de controles optionset à variável optionSetControls.

Determine se um controle está habilitado

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDisabled

var disabledControls = Xrm.Page.getControl(function(control, index) { return control.getDisabled(); });

Atribui uma matriz de controles desabilitados à variável disabledControls.

Observação

Os controles de recurso da Web e subgrade não suportam este método.

Desabilitar ou habilitar um controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDisabled

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

Desabilitar todos os controles para o atributo name.

Dica

Lembrar que qualquer atributo pode ter vários controles.

Obter a etiqueta para um controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getLabel

var nameControlLabel = Xrm.Page.getControl("name").getLabel();

Atribui o valor do controle do campo Nome da Conta à variável nameControlLabel.

Alterar uma etiqueta para um controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setLabel

Xrm.Page.getControl("name").setLabel("Company Name");

Alterar a etiqueta do campo Nome da Conta para Nome da Empresa.

Obter o nome de um controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getName

var firstControlName = Xrm.Page.getControl(0).getName();

Atribui o nome do primeiro controle no conjunto Xrm.Page.ui.controls à variável firstControlName.

Obter o principal de um controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getParent

var parentSection = Xrm.Page.getControl("name").getParent();

Atribui a seção principal do controle do campo Nome da Conta à variável parentSection.

Definir foco em um controle

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setFocus

Xrm.Page.getControl("name").setFocus();

Define o foco no campo Nome da Conta.

Neste tópico

Métodos de controle OptionSet

Optionsets tem alguns métodos especiais. É importante lembrar que o atributo define as opções válidas para um optionset. Quando você trabalha com um controle optionset, é possível manipular as opções disponíveis, mas não criar novas opções.

Tarefa

Método

Exemplo

Adicionar uma opção para um controle optionset

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addOption

var addressTypeCodeControl = Xrm.Page.getControl("address1_addresstypecode");
var billToAddressOption = addressTypeCodeControl.getAttribute().getOption(1);
addressTypeCodeControl.clearOptions();
addressTypeCodeControl.addOption(billToAddressOption);

Usando uma referência para o controle do campo Tipo de Endereço, acesse o atributo para o controle e use o método 6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption para definir a variável billToAddressOption para a opção que representa a opção Cobrar Para.

Use 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions para remover as opções existentes e use addOption para definir billToAddressOption como a única opção disponível para este controle.

Remover todas as opções de um controle optionset

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions

Xrm.Page.getControl("address1_addresstypecode").clearOptions();

Remover todas as opções do controle para o campo Tipo de Endereço.

Remover uma única opção de um controle optionset.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_removeOption

Xrm.Page.getControl("address1_addresstypecode").removeOption(1);

Remover a opção Cobrar Para do controle para o campo Tipo de Endereço.

Neste tópico

Métodos de controle IFRAME e recursos da Web

Um controle IFRAME permite incluir uma página em um formulário fornecendo um URL. Um recurso da Web HTML é adicionado ao formulário presente usando um IFRAME. O Silverlight e recursos da Web de imagem são inseridos diretamente na página.

Tarefa

Método

Exemplo

Obter o valor do parâmetro de cadeia de caracteres de consulta de dados passado para um recurso da Web Silverlight.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getData

var dataValue = Xrm.Page.getControl("WebResource_SilverLightControl").getData();

Atribui o valor passado pelo parâmetro da cadeia de caracteres de consulta de dados para a variável dataValue.

Obter o URL para o conteúdo atualmente exibido em um IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getSrc

var iframeSource = Xrm.Page.getControl("IFRAME_targetPage").getSrc();

Atribui a cadeia de caracteres que representa o valor do atributo IFRAME.src atual à variável iframeSource.

Define o URL para o conteúdo a ser exibido em um IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setSrc

Xrm.Page.getControl("IFRAME_targetPage").setSrc("http://www.bing.com");

Define um URL para ser o IFRAME.src do controle.

Obter o URL que representa a URL configurada padrão para um IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getUrl

var initialUrl = Xrm.Page.getControl("IFRAME_bing").getInitialUrl();

Atribui a URL inicial configurada para ser exibida no IFRAME à variável initialUrl.

Obtém o objeto no formulário que representa o recurso da Web ou o IFRAME.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getObject

var obj = Xrm.Page.getControl("IFRAME_bing").getObject();

Atribui uma referência de objeto à variável obj. Para um IFRAME este será o elemento do Modelo de Objeto do Documento (DOM) do IFRAME. Para um recurso da Web Silverlight será o elemento Object do Objeto que representa o plug-in Silverlight integrado.

Neste tópico

Métodos de controle de pesquisa

Um requisito comum para controles de pesquisa é especificar a exibição padrão mostrada quando um usuário atualiza o campo.

Tarefa

Método

Exemplo

Adiciona uma exibição personalizada para uma pesquisa.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
var viewDisplayName = "SDK Sample View";
var fetchXml = "<fetch version='1.0' " +
"output-format='xml-platform' " +
"mapping='logical'>" +
"<entity name='account'>" +
"<attribute name='name' />" +
"<attribute name='address1_city' />" +
"<order attribute='name' " +
"descending='false' />" +
"<filter type='and'>" +
"<condition attribute='ownerid' " +
"operator='eq-userid' />" +
"<condition attribute='statecode' " +
"operator='eq' " +
"value='0' />" +
"</filter>" +
"<attribute name='primarycontactid' />" +
"<attribute name='telephone1' />" +
"<attribute name='accountid' />" +
"<link-entity "+
"alias='accountprimarycontactidcontactcontactid' " +
"name='contact' " +
"from='contactid' " +
"to='primarycontactid' " +
"link-type='outer' " +
"visible='false'>" +
"<attribute name='emailaddress1' />" +
"</link-entity>" +
"</entity>" +
"</fetch>";
var layoutXml = "<grid name='resultset' " +
"object='1' " +
"jump='name' " +
"select='1' " +
"icon='1' " +
"preview='1'>" +
"<row name='result' " +
"id='accountid'>" +
"<cell name='name' " +
"width='300' />" +
"<cell name='telephone1' " +
"width='100' />" +
"<cell name='address1_city' " +
"width='100' />" +
"<cell name='primarycontactid' " +
"width='150' />" +
"<cell name='accountprimarycontactidcontactcontactid.emailaddress1' " +
"width='150' " +
"disableSorting='1' />" +
"</row>" +
"</grid>";
Xrm.Page.getControl("parentaccountid").addCustomView(viewId, "account", viewDisplayName, fetchXml, layoutXml, true);

Define as variáveis viewId, viewDisplayName, fetchXml e layoutXml para passar como argumentos para que uma exibição personalizada seja adicionada como a exibição padrão para o controle no campo de pesquisa Conta Primária.

Obter a exibição padrão para uma pesquisa.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDefaultView

var defaultViewId = Xrm.Page.getControl("parentaccountid").getDefaultView();

Atribuir o valor id da exibição padrão à variável defaultViewId.

Definir a exibição padrão para uma pesquisa.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDefaultView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
Xrm.Page.getControl("parentaccountid").setDefaultView(viewId);

Definir a exibição padrão do controle para o campo Conta Primária para o valor id na variável viewId.

Filtrar os registros retornados para um controle de pesquisa

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomFilter

A seguinte amostra de código é para a pesquisa do formulário de oportunidade Conta (parentaccountid). Quando a função Sdk.setParentAccountIdFilter é definida no manipulador de eventos do formulário Onload, a função Sdk.filterCustomAccounts é adicionada ao evento PreSearch para essa pesquisa. O resultado é que apenas contas com o valor de Categoria (accountcategorycode) de Cliente Preferencial (1) serão retornadas.

var Sdk = window.Sdk || {};

Sdk.filterCustomerAccounts = function () {
    //Only show accounts with the type 'Preferred Customer'
    var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
    Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
}
//set 'Sdk.setParentAccountIdFilter' in the Opportunity form Onload event handler
Sdk.setParentAccountIdFilter = function () {
    Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
}

Neste tópico

Métodos de controle de Subgrade

O controle SubGrid é uma grade em um formulário. Tem um método exclusivo.

Tarefa

Método

Exemplo

Atualizar os dados exibidos na subgrade

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_refresh

Xrm.Page.getControl("accountcontactsgrid").refresh();

Atualize os Contatossubgrid.

Neste tópico

Métodos de controle de dados

O controle Date tem um método exclusivo.

Tarefa

Método

Exemplo

Especificar se um controle de data deve mostrar a parte de hora da data.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setShowTime

Xrm.Page.getControl("createdon").setShowTime(false);

Definir o campo Data de Criação para que a hora não seja exibida.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Neste tópico

É possível usar e manipular os itens de navegação no lado esquerdo do formulário. Esses itens de navegação geralmente mostram registros relacionados ao registro exibido no formulário.

Você pode acessar itens de navegação usando o conjunto Xrm.Page.ui.navigation.items como todos os conjuntos no formulário, onde há um método 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get e 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach.

Tarefa

Método

Exemplo

Obter o nome de um item de navegação

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getId

var navItemIds = [];
Xrm.Page.ui.navigation.items.forEach(
function (item, index)
{ navItemIds.push(item.getId()) }
);

Criar uma matriz navItemIds que contém os valores id de cada item de navegação no conjunto Xrm.Page.ui.navigation.items.

Obter a etiqueta de um item de navegação.

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getLabel

var navAddressesLabel = Xrm.Page.ui.navigation.items.get("navAddresses").getLabel();

Atribuir a etiqueta do item de navegação Mais Endereços à variável navAddressesLabel.

Definir a etiqueta de um item de navegação

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setLabel

Xrm.Page.ui.navigation.items.get("navAddresses").setLabel("Other Addresses");

Alterar a etiqueta do item de navegação Mais Endereços para Outro Endereços.

Mostrar ou ocultar um item de navegação

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setVisible

Xrm.Page.ui.navigation.items.get("navAddresses").setVisible(false);

Ocultar o item de navegação More Addresses.

Determine se um item de navegação está visível

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getVisible

var moreAddressesVisible = Xrm.Page.ui.navigation.items.get("navAddresses").getVisible()

Atribuir um valor Boolean à variável moreAddressesVisible para representar se o item de navegação Mais Endereços está visível.

Definir o foco em um item de navegação.

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setFocus

Xrm.Page.ui.navigation.items.get("navAddresses").setFocus();

Definir o foco no item de navegação Mais Endereços.

Neste tópico

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 de forma programática esses elementos e usar seus métodos.

Tarefa

Método

Exemplo

Determinar se uma guia está expandida ou recolhida

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_getDisplayState

var isGeneralTabExpanded = (Xrm.Page.ui.tabs.get("general").getDisplayState() == "expanded")

Atribuir um valor Boolean à variável isGeneralTabExpanded que indica quando a guia Geral é expandida.

Expandir ou recolher uma guia

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetDisplayState

Xrm.Page.ui.tabs.get("general").setDisplayState("collapsed");

Recolher a guia Geral.

Determinar se uma guia está visível

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetVisible

var isGeneralTabVisible = Xrm.Page.ui.tabs.get("general").getVisible();

Atribuir um valor Boolean à variável isGeneralTabVisible indicando quando a guia Geral está visível.

Mostrar ou ocultar uma guia

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetVisible

Xrm.Page.ui.tabs.get("general").setVisible(false);

Ocultar a guia Geral.

Obter a etiqueta para uma guia

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetLabel

var generalTabLabel = Xrm.Page.ui.tabs.get("general").getLabel();

Atribuir a etiqueta da guia Geral à variável generalTabLabel.

Alterar uma etiqueta para uma guia

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetLabel

Xrm.Page.ui.tabs.get("general").setLabel("Major");

Alterar a etiqueta da guia Geral para Principal.

Definir foco em uma guia

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetFocus

Xrm.Page.ui.tabs.get("general").setFocus();

Definir foco na guia Geral.

Obter o nome da guia

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetName

var firstTabName = Xrm.Page.ui.tabs.get(0).getName();

Atribuir o nome da primeiro guia à variável firstTabName.

Obter a guia principal de uma seção

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetParent

Xrm.Page.getControl("industrycode").getParent().getParent().setFocus();

Definir o foco na guia que contém o campo Setor.

Determinar se uma seção está visível

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetVisible

var industrySectionVisible = Xrm.Page.getControl("industrycode").getParent().getVisible();

Atribuir um valor Boolean à variável industrySectionVisible indicando se a seção que contém o campo Setor está visível.

Ocultar ou mostrar uma seção

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetVisible

Xrm.Page.getControl("industrycode").getParent().setVisible(false);

Ocultar a seção que contém o campo Setor.

Obter a etiqueta para uma seção

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_getLabel

var industryFieldSectionLabel = Xrm.Page.getControl("industrycode").getParent().getLabel();

Atribuir a etiqueta da seção que contém o campo Setor à variável industryFieldSectionLabel.

Alterar uma etiqueta para uma seção

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetLabel

Xrm.Page.getControl("industrycode").getParent().setLabel("Detailed Information");

Alterar a etiqueta da seção que contém o campo Setor para Informações Detalhadas.

Neste tópico

Adicionar ou remover manipuladores de eventos no tempo de execução

Manipuladores de eventos são geralmente configurados usando o editor de formulários no aplicativo, mas você também pode adicionar ao evento OnSave de formulário e eventos OnChange do atributo no tempo de execução que usam esse APIs. Os exemplos desta seção serão referidos a seguinte definição de funções:
function myFunction() {
//perform action here
}

Quando você pode adicionar uma função anônima, a função deve ter um nome para fazer referência para poder removê-lo.

Tarefa

Método

Exemplo

Adicionar uma função ao evento OnSave

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_addOnSave

Xrm.Page.data.entity.addOnSave(myFunction);

Adicionar a função myFunction ao evento OnSave.

Remover uma função do evento OnSave

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_removeOnSave

Xrm.Page.data.entity.removeOnSave(myFunction);

Remover a função myFunction para o evento OnSave.

Adicionar uma função a um evento OnChange de um atributo.

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_addOnChange

Xrm.Page.getAttribute("name").addOnChange(myFunction);

Adiciona a função myFunction para o evento OnChange do campo Nome da Conta.

Remover uma função do evento OnChange de um atributo

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_removeOnChange

Xrm.Page.getAttribute("name").removeOnChange(myFunction);

Remover a função myFunction para o evento OnChange do campo Nome da Conta.

Adicionar uma função a um evento PreSearch de um controle de pesquisa.

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addPreSearch

A seguinte amostra de código é para a pesquisa do formulário de oportunidade Conta (parentaccountid). Quando a função Sdk.setParentAccountIdFilter é definida no manipulador de eventos do formulário Onload, a função Sdk.filterCustomAccounts é adicionada ao evento PreSearch para essa pesquisa. O resultado é que apenas contas com o valor de Categoria (accountcategorycode) de Cliente Preferencial (1) serão retornadas.

  var Sdk = window.Sdk || {};

  Sdk.filterCustomerAccounts = function () {
      //Only show accounts with the type 'Preferred Customer'
      var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
      Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
  }
  //set 'Sdk.setParentAccountIdFilter' in the Opportunity form Onload event handler
  Sdk.setParentAccountIdFilter = function () {
      Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
  }

Use d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange e d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected em eventos que ocorrem no controle de fluxo do processo empresarial. Esses eventos têm apenas os métodos para adicionar ou remover manipuladores de eventos de forma programática.Para obter mais informações:Métodos para gerenciar manipuladores de eventos.

Neste tópico

Métodos de informações contextuais

Use estes métodos para obter informações sobre o usuário, a organização e o cliente. A tabela a seguir apresenta alguns dos métodos de contexto mais úteis. Para todos os métodos de contexto, consulte Contexto do cliente (referência do cliente)

Tarefa

Método

Exemplo

Obter a URL para se conectar à organização.

getClientUrl

var serverUrl = Xrm.Page.context.getClientUrl();

Atribuir uma cadeia de caracteres que representa o URL à variável serverUrl.

Obter o identificador exclusivo para o usuário atual.

getUserId

var userId = Xrm.Page.context.getUserId();

Atribuir uma cadeia de caracteres que representa a ID do usuário à variável userId.

Obter o nome do usuário atual.

getUserName

var userName = Xrm.Page.context.getUserName();

Atribuir uma cadeia de caracteres que representa o nome do usuário à variável userName.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Obter o código de idioma que representa o idioma da interface do usuário preferido do usuário.

getUserLcid

var userLCID = Xrm.Page.context.getUserLcid();

Atribuir um número que indica o idioma preferido do usuário à variável userLCID.

Obter uma matriz das cadeias de caracteres que representa os valores GUID para cada direito de acesso atribuído ao usuário atual e em todos as equipes que o usuário está associado.

getUserRoles

var userRoles = Xrm.Page.context.getUserRoles();

Atribuir uma matriz das cadeias de caracteres que representa os direitos de acesso do usuário à variável userRoles.

Determinar se o script está executando o cliente Microsoft Dynamics 365 para Outlook.

cliente.getClient

var isOutlookClient = (Xrm.Page.context.client.getClient() == "Outlook");

Atribuir um valor Boolean que representa se o código está executando no cliente Dynamics 365 para Outlook à variável isOutlookClient.

Determinar se o usuário está trabalhando offine com o cliente Microsoft Dynamics 365 para Microsoft Office Outlook com Acesso Offline.

cliente.getClientState

var IsOffline = (Xrm.Page.context.client.getClientState() == "Offline");

Atribuir um valor Boolean que representa se o usuário está trabalhando offline atualmente na variável IsOffline.

Neste tópico

Obter, atualizar ou salvar dados da entidade

A tabela a seguir apresenta os métodos que podem ser usados para obter informações sobre o registro atual ou para salvar alterações. Para obter mais informações, consulte Xrm.Page.data.entity (referência do cliente) e Xrm.Page.data (referência do cliente).

Tarefa

Método

Exemplo

Obter o nome lógico da entidade atual

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getEntityName

var entityName = Xrm.Page.data.entity.getEntityName();

Atribuir o nome da entidade lógica à variável entityName.

Obter o valor do atributo principal da entidade atual.
O atributo primário é o valor usado para identificar o registro. Por exemplo contact.fullname.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getPrimaryAttributeValue

var primaryAttributeValue = Xrm.Page.data.entity.getPrimaryAttributeValue();

Atribuir o valor do atributo principal à variável primaryAttributeValue.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Obter o Id do registro atual

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getId

var recordId = Xrm.Page.data.entity.getId();

Atribuir o valor id do registro à variável recordId.

Atualiza de maneira assíncrona os dados do formulário sem recarregar a página.

ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_refresh

Xrm.Page.data.refresh();

Atualiza os dados no formulário.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Salve o registro atual.

Xrm.Page.data.entity.fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_save

Xrm.Page.data.entity.save();

Salva o registro. Há argumentos opcionais. Use saveandclose ou saveandnew para executar as ações equivalentes.

Salva o registro atual de maneira assíncrona com a opção para definir
funções de retorno de chamadas a serem realizadas depois da operação de salvar ser concluída.

Xrm.Page.data.ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_dataSave

Xrm.Page.data.save().then(
function(){
Xrm.Utility.alertDialog("Record saved");
},
function(error){
Xrm.Utility.alertDialog(error.message);
});

Salva o registro e exibe uma mensagem mostrando o status do salvamento.

Este método está disponível somente para o 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

Determina se algum dado no registro atual está alterado.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getIsDirty

var isDirty = Xrm.Page.data.entity.getIsDirty();

Atribuir um valor Boolean que representa se os dados no registro foram alterados para a variável isDirty.

Obter uma cadeia de caracteres que representa os dados que serão enviados ao servidor quando o registro for salvo.

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getDataXml

var dataXml = Xrm.Page.data.entity.getDataXml();

Atribuir uma cadeia de caracteres que representa os dados a serem salvos na variável dataXml.

Neste tópico

Confira Também

Use o modelo de objeto Xrm.Page
Crie códigos para os formulários do Microsoft Dynamics 365
Referência de programação do cliente

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais