Xrm.Utility (referência do cliente)

Publicado: janeiro de 2017

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

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 clientes de dispositivos móveis (telefones e tablets) Dynamics 365 no lugar dos métodos window.alert e window.confirm.

• Recursos de dispositivo nativos (clientes móveis do Dynamics 365)
  Use getBarcodeValuegetCurrentPosition e para utilizar os recursos de dispositivo nativo de dispositivos móveis para recuperar o valor do código de barras ou para recuperar a posição atual do dispositivo.

• 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 com o uso de scripts dos clientes móveis Dynamics 365 (telefones e tablets). Clientes móveis do Dynamics 365 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.

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.

Recursos de dispositivo nativos (clientes móveis do Dynamics 365)

Use esses métodos para os clientes Dynamics 365 para telefones e Dynamics 365 para tablets para ajudar a enriquecer a experiência de usuários empresariais móveis em vendas, serviços de campo e outras áreas:

getBarcodeValue

Retorna informações do código de barras, como o número de produto, usando a digitalizado de câmera de um dispositivo.

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

• Parâmetros

  Nome	Digite	Obrigatório	Descrição
  successCallback	Função	Sim	Um a função a ser chamada quando o valor do código de barras for retornado.
  errorCallback	Função	Sim	Uma função para chamar quando a operação falha. Um objeto de erro com a propriedade message será passado e descreverá os detalhes do erro.

• Comentários
  Para que o método getBarcodeValue funcione, os clientes móveis do Dynamics 365 deverão ter acesso à câmera do seu dispositivo, o que está habilitado por padrão.

• Exemplo
  O código de exemplo a seguir demonstra o uso deste método.

  Xrm.Utility.getBarcodeValue().then(
      function (result) {
          Xrm.Utility.alertDialog("Barcode value: " + result);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

getCurrentPosition

Retorna o local atual usando o recurso de geolocalização de um dispositivo.

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

• Parâmetros

  Nome	Digite	Obrigatório	Descrição
  successCallback	Função	Sim	Um a função a ser chamada quando as informações de geolocalização atuais forem retornadas. Um objeto de geolocalização com os atributos a seguir é passado para a função. coords: contém um conjunto de coordenadas geográficas junto com a exatidão associada, bem como um conjunto de outros atributos opcionais, como altitude e velocidade. timestamp: representa a hora em que o objeto foi adquirido e é representado como DOMTimeStamp.
  errorCallback	Função	Sim	Uma função para chamar quando a operação falha. Será passado um objeto com as seguintes propriedades: code: Número. O código de erro. message: Cadeia de caracteres. Mensagem localizada que descreve os detalhes do erro. Se a configuração da localização do usuário não estiver habilitada em seu dispositivo móvel, a mensagem de erro indicará isso. Se você estiver usando uma versão anterior do cliente móvel do Dynamics 365 ou se o recurso de geolocalização não estiver disponível no dispositivo móvel, null será passado para o retorno de chamada de erro.

• Comentários
  Para que o método getCurrentPosition funcione, o recurso de geolocalização deverá estar habilitado em seu dispositivo, e os clientes móveis do Dynamics 365 deverão ter permissões para acessar a localização do dispositivo, o que não está habilitado por padrão.

• Exemplo
  O código de exemplo a seguir demonstra o uso deste método.

  Xrm.Utility.getCurrentPosition().then
      (function (location) {
          Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
             ", Longitude: " + location.coords.longitude);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

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 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 são ignorados em clientes móveis Dynamics 365 (telefones e tablets).

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

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

• Parâmetros

  Nome	Tipo	Obrigató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
Crie códigos para os formulários do Microsoft Dynamics 365
Use o modelo de objeto Xrm.Page

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais