Partilhar via


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.

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:

    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:

    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