Partilhar via

Xrm.Utility (referência do cliente)

  • Artigo

 

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.

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.

Observação

Nos clientes móveis (telefones e tablets) Dynamics 365 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 nos clientes móveis Dynamics 365 é 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.

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:

Observação

Esses métodos foram introduzidos no Atualização de dezembro de 2016 para Dynamics 365 (online e local).

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:

    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:

    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

Não há suporte a esses métodos para os clientes móveis Dynamics 365 (telefones e tablets) e o hub de serviço interativo.

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