Xrm.Utility (referência do cliente)

 

Publicado: novembro de 2016

Aplicável a: Dynamics CRM 2015

O objeto Xrm.Utility fornece um contêiner das funções úteis não diretamente relacionadas para a página atual.

Essas funções estão disponíveis em cada página de aplicativo que ofereça suporte ao script. Você pode usá-los em scripts de formulário ou de comandos da faixa de opções. Para recursos da Web HTML, eles estão disponíveis quando você inclui a página ClientGlobalContext.js.aspx. Para obter mais informações, consulte Função GetGlobalContext e ClientGlobalContext.js.aspx (referência do cliente).

Funções

• Caixas de Diálogo
  Use mensagens de exibição alertDialog e confirmDialog para os usuários e defina o código para executar com base na resposta. Essas funções devem ser usadas com o Microsoft Dynamics CRM para Tablets no lugar dos métodos window.alert e window.confirm.

• isActivityType
  Determina se a entidade for uma entidade de atividade.

• openEntityForm
  Abre um formulário de entidade.

• openQuickCreate
  Para o Atualização 1 do Microsoft Dynamics CRM Online 2015 ou posterior, use essa função para abrir um novo formulário de criação rápida. Você pode usar essa função para definir valores padrão usando mapeamentos de atributos ou para atributos específicos. Se o usuário salvar o registro, será possível capturar uma referência ao registro criado.

• openWebResource
  Abre um recurso da Web HTML.

Caixas de Diálogo

Há dois tipos de diálogos: alertDialog e confirmDialog. Estes são incluídos para uso com scripts com Microsoft Dynamics CRM para Tabletsque funcionarão.CRM para tablets não permitirá o uso de funções JavaScript que bloqueiam o fluxo de código como window.alert e window.confirm. Use estes métodos no lugar desses métodos caso seja necessário exibir uma mensagem ao usuário. A principal diferença é que esses métodos não bloqueiam o código até um usuário o feche. Eles contêm um parâmetro da função de retorno de chamada para indicar qual código deve ser executado dependendo da resposta do usuário.

Observação

No Microsoft Dynamics CRM para Tablets qualquer uso do método window.alert substituirá o uso do Xrm.Utility.alertDialog sem o retorno de chamada. Isso exibirá a mensagem, mas não bloqueará a execução de código como o window.alert faz. Esse mapeamento do window.alert para Xrm.Utility.alertDialog no CRM para tablets é desativado e será removido na próxima principal versão. É preciso migrar todos os códigos que você precisa para usar Xrm.Utility.alertDialog em vez de window.alert.

alertDialog

Exibe uma caixa de diálogo que contém uma mensagem definida por aplicativo.

Xrm.Utility.alertDialog(message,onCloseCallback)

• Parâmetros

  Nome	Tipo	Necessário	Descrição
  mensagem	Cadeia de caracteres	Sim	O texto da mensagem a ser exibido no diálogo.
  onCloseCallback	Função	Não	Uma função para executar quando o botão OK é clicado.

• Comentários
  Este método está disponível somente para o Entidades atualizadas.

confirmDialog

Exibe uma caixa de diálogo de confirmação que contém uma mensagem opcional, assim como os botões OK e Cancelar.

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

• Parâmetros

  Nome	Tipo	Necessário	Descrição
  mensagem	Cadeia de caracteres	Sim	O texto da mensagem a ser exibido no diálogo
  yesCloseCallback	Função	Não	Uma função para executar quando o botão OK é clicado.
  noCloseCallback	Função	Não	Uma função para executar quando o botão Cancelar é clicado.

• Comentários
  Este método está disponível somente para o Entidades atualizadas.

isActivityType

Determina se a entidade for uma entidade de atividade.

Xrm.Utility.isActivityType(entityName)

• Parâmetro

  Nome	Tipo	Necessário	Descrição
  entityName	Cadeia de caracteres	Sim	O logicalName de uma entidade.

• Valor de Retorno

  Tipo	Descrição
  Booliano	True se a entidade for uma entidade de atividade, caso contrário, false.

openEntityForm

Abre um formulário de entidade para um registro de entidade novo ou existente usando as opções definidas como parâmetros.

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

• Parâmetros

  Nome	Tipo	Necessário	Descrição
  nome	Cadeia de caracteres	Sim	O nome lógico da entidade.
  id	Cadeia de caracteres	Não	A representação de cadeia de caracteres de um identificador exclusivo ou o registro para abrir no formulário. Se não definido, um formulário para criar um novo registro é aberto.
  parâmetros	Objeto	Não	Um objeto de dicionário que passa parâmetros extras para o formulário. Os parâmetros inválidos causarão um erro. Os parâmetros da cadeia de caracteres de consulta extra válidos são: Identificação de formulário: Para definir o valor de ID do formulário principal para usar quando mais de um formulário estiver disponível. O parâmetro é formid. Ids padrão de campo: Para definir valores padrão para um novo formulário de registro. Para obter mais informações, consulte Definir valores de campo usando parâmetros transmitidos a um formulário. Os parâmetros navbar e cmdbar descritos no Parâmetros de cadeia de caracteres de consulta para a página Main.aspx. Parâmetros da cadeia de caracteres de consulta personalizados: Um formulário pode ser configurado para aceitar parâmetros da cadeia de caracteres de consulta personalizados. Para obter mais informações, consulte Configurar um formulário para aceitar parâmetros de cadeia de caracteres de consulta personalizados.
  windowOptions	Objeto	Não	Para o Atualização 1 do Microsoft Dynamics CRM Online 2015 ou posterior, use esse parâmetro opcional no aplicativo Web para controlar a abertura do formulário. Você pode optar por abrir um formulário em uma nova janela passando um objeto de dicionário com uma propriedade booliana openInNewWindow definida como true. Esse parâmetro é ignorado no CRM para tablets e no CRM para telefones.

• Comentários
  Usar essa função ajuda a garantir que os usuários não sejam solicitados a entrar novamente em certas ocasiões.

• Exemplos
  Abra um novo registro da conta usando o formulário padrão

  Xrm.Utility.openEntityForm("account");
  

  Abra um registro da conta existente usando o formulário padrão

  Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");
  

  Abra um novo registro de conta com um formulário específico e valores de configuração padrão

  var parameters = {};
  parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
  parameters["name"] = "Test";
  parameters["telephone1"] = "(425) 555-1234";
  Xrm.Utility.openEntityForm("account", null, parameters);
  

  Abra um novo registro da conta usando o formulário padrão em uma nova janela

  var windowOptions = {
   openInNewWindow: true
  };
  Xrm.Utility.openEntityForm("account",null,null,windowOptions);
  

openQuickCreate

Para o Atualização 1 do Microsoft Dynamics CRM Online 2015 ou posterior, use essa função para abrir um novo formulário de criação rápida. Você pode usar essa função para definir valores padrão usando mapeamentos de atributos ou para atributos específicos. Se o usuário salvar o registro, será possível capturar uma referência ao registro criado.

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

• Parâmetros

  Nome	Tipo	Necessário	Descrição
  entityLogicalName	Cadeia de caracteres	Sim	O nome lógico da entidade a ser criada.
  createFromEntity	Consulta	Não	Indica um registro que fornecerá valores padrão baseados em valores de atributo mapeados. Um objeto de pesquisa tem as seguintes propriedades de String: entityType: o nome lógico da entidade. id: uma representação de cadeia de caracteres de um valor de GUID para o registro. name: o valor do atributo principal do registro.
  parâmetros	Objeto	Não	Um objeto de dicionário que passa seus parâmetros da cadeia de caracteres de consulta para o formulário. Os parâmetros de cadeia de caracteres de consulta inválidos causarão um erro. Os parâmetros da cadeia de caracteres de consulta extra válidos são: Ids padrão de campo: Para definir valores padrão para um novo formulário de registro. Para obter mais informações, consulte Definir valores de campo usando parâmetros transmitidos a um formulário. Parâmetros da cadeia de caracteres de consulta personalizados: Um formulário pode ser configurado para aceitar parâmetros da cadeia de caracteres de consulta personalizados. Para obter mais informações, consulte Configurar um formulário para aceitar parâmetros de cadeia de caracteres de consulta personalizados.
  successCallback	Função	Não	A função que será chamada quando um registro for criado. Esta função transmite um objeto como um parâmetro. Esse objeto tem uma propriedade savedEntityReference com as seguintes propriedades para identificar o registro criado: entityType: o nome lógico da entidade. id: uma representação de cadeia de caracteres de um valor de GUID para o registro. name: o valor do atributo principal do registro criado.
  errorCallback	Função	Não	Uma função para chamar quando a operação falha. Será passado um objeto com as seguintes propriedades: errorCode: Number. O código de erro. message: String. Uma mensagem de erro localizada.

• Comentários
  Essa função está disponível somente para o Atualização 1 do Microsoft Dynamics CRM Online 2015 ou posterior.

  Há um limite de 10 formulários de criação rápida aninhados no aplicativo Web. Se esse limite for excedido, essa função abrirá o formulário de entidade inteiro em vez do formulário de criação rápida.

• Exemplo
  Quando esse código for executado em um formulário de entidade de conta, um formulário de criação rápida para criar uma nova conta filho com um nome padrão é definido para incluir o nome da conta primária.

  var thisAccount = {
      entityType: "account",
      id: Xrm.Page.data.entity.getId()
  };
  var callback = function (obj) {
      console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
  }
  var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
  Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
      console.log(error.message);
  });
  

  Quando esse código for executado com ferramentas de desenvolvedor de navegador (ferramentas F12), o seguinte representará a saída para o console quando executado no contexto de uma conta chamada 'A. Datum Corporation (sample)' e se o usuário não alterar o nome padrão definido para a nova conta filha.

  Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}
  

openWebResource

Abre um recurso da Web HTML.

Observação

Essa função não funcionará com o Microsoft Dynamics CRM para Tablets.

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

• Parâmetros

  Nome	Tipo	Necessário	Descrição
  webResourceName	Cadeia de caracteres	Sim	O nome do recurso da Web HTML a ser aberto.
  webResourceData	Cadeia de caracteres	Não	Os dados a serem passados no parâmetro de dados.
  width	Número	Não	A largura da janela para abrir em pixels.
  height	Número	Não	A altura da janela para abrir em pixels.

• Valor de Retorno
  Objeto da janela.

• Comentários
  Um recurso da Web HTML pode aceitar os valores de parâmetro descritos em Transmitir parâmetros para os recursos da Web em HTML. Essa função prevê somente a transmissão nos parâmetros opcionais de dados. Para passar valores para outros parâmetros válidos, você deve acrescentá-los ao parâmetro webResourceName.

• Exemplos
  Abra um recurso da Web HTML chamado "new_webResource.htm"

  Xrm.Utility.openWebResource("new_webResource.htm");
  

  Abra um recurso da Web HTML incluindo um único item de dados para o parâmetro de dados

  Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
  

  Abra um recurso da Web HTML transmitindo vários valores pelo parâmetro de dados

  var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
  Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
  

  Observação

  Esses valores precisam ser extraídos do valor do parâmetro de dados no recurso da Web HTML. Para obter mais informações, consulte Amostra: Transmitir vários valores para um recurso Web através do parâmetro de dados

  Abra um recurso da Web HTML com os parâmetros esperados pelos recursos da Web HTML

  Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");
  

  Para obter mais informações, consulte Transmitir parâmetros para os recursos da Web em HTML.

  Abra um recurso da Web HTML, configuração de altura e largura

  Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);
  

Confira Também

Referência de programação do cliente
Abrir formulários, exibições, caixas de diálogo e relatórios com uma URL
Definir valores de campo usando parâmetros transmitidos a um formulário
Configurar um formulário para aceitar parâmetros de cadeia de caracteres de consulta personalizados
Referência rápida do script de formulário
Criar códigos para os formulários do Microsoft Dynamics CRM 2015
Use o modelo de objeto Xrm.Page

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais