Controle Xrm.Page.ui (referência do cliente)

  • Artigo

 

Publicado: novembro de 2016

Aplicável a: Dynamics CRM 2015

O objeto de control fornece métodos para alterar a apresentação ou o comportamento de um controle e identificar o atributo correspondente.

Você acessa controles usando os seguintes conjuntos: Xrm.Page.ui.controls, Xrm.Page.ui Section.controls ou Xrm.Page.data.entity Attribute.controls. O método Xrm.Page.getControl é um método de atalho para acessar Xrm.Page.ui.controls.get.

Os exemplos de sintaxe neste tópico mostram o uso do método Xrm.Page.getControl para acessar um controle. Qual controle depende dos argumentos passados para o método. O parâmetro args para acessar um único controle deve ser o nome do controle ou do índice.

Quando um formulário exibe um controle de fluxo de processo comercial no cabeçalho, os controles adicionais serão adicionados para cada atributo exibido no fluxo de processos de negócios. Esses controles tem um nome semelhante ao seguinte exemplo: header_process_<attribute name>.

Observação

Somente os controles do estágio ativo do fluxo de processos corporativos podem ser acessados por nome dessa maneira.

Os controles exibidos no cabeçalho do formulário são acessíveis e têm um nome exclusivo como o seguinte: header_<attribute name>.

Para controles associados aos atributos é comum acessar controles através do conjunto Xrm.Page.data.entity Attribute.controls.

Propriedades e métodos de controle

  • Desabilitada
    Detectar o estado e habilitar ou desabilitar controles usando os métodos getDisabled e setDisabled.

  • getAttribute
    Obter o atributo que o controle está associado.

  • getControlType
    Obter informações sobre o tipo de controle.

  • getName
    Obter o nome do controle

  • getParent
    Obter o objeto da seção que o controle está.

  • Métodos de controle da base de dados de conhecimento
    Esses métodos estão disponíveis apenas para o controle de pesquisa da base de dados de conhecimento disponível quando a organização do Microsoft Dynamics CRM Online estiver integrada ao Parature. Esses métodos foram introduzidos no Atualização 1 do Microsoft Dynamics CRM Online 2015.

    Para obter mais informações sobre esses controles, consulte Controle de pesquisa da base de dados de conhecimento do Parature (referência do cliente).

  • Etiqueta
    Obter ou alterar a etiqueta de um controle usando os métodos getLabel e setLabel.

  • Métodos de controle de pesquisa e eventos
    Controlar os resultados exibidos para um usuário selecionar quando definir o valor de um controle de pesquisa usando os métodos addCustomFilter, addCustomView, getDefaultView, setDefaultView.

    É possível adicionar ou remover manipuladores de eventos para o Evento PreSearch usando os métodos addPreSearch e removePreSearch.

  • Notificação
    Exibir e remover notificações para usuários sobre um controle usando os métodos setNotification e clearNotification.

  • Métodos de controle OptionSet
    Modifique as opções exibidas em controles OptionSet usando os métodos addOption, clearOptions, e removeOption.

  • ShowTime
    Use setShowTime para especificar se o controle de data deve mostrar a parte de hora da data e getShowTime para determinar se a parte da hora da data está sendo exibida atualmente.

  • Métodos de controle de subgrade
    Para organizações que estejam usando o CRM Online 2015 Atualização 1, há novos recursos para trabalhar com controles de subgrade.Para obter mais informações:Objetos e métodos de grade (referência do cliente)

    Para outras organizações, o método refresh é o único método exclusivo disponível para controles de subgrade. Esse método atualizará os dados exibidos na subgrade.

  • Visível
    Determinar quais controles estão visíveis e mostrar ou ocultar usando os métodos getVisible e setVisible.

  • Métodos de controle IFRAME e recursos da Web
    Interagir com o recurso da Web e controles do IFRAME usando os métodos getData, setData, getInitialUrl, getObject, setSrc e getSrc.

Desabilitada

Use getDisabled e setDisabled para detectar se um controle está desabilitado ou para habilitar ou desabilitar.

Tipos de controle: padrão, pesquisa, optionset.

getDisabled

Retorna se o controle está desabilitado.

Xrm.Page.getControl(arg).getDisabled()
  • Valor de Retorno
    Tipo: Booleano. True se o controle estiver desabilitado, caso contrário, false.

setDisabled

Define se o controle está desabilitado.

Xrm.Page.getControl(arg).setDisabled(bool)
  • Argumentos
    Tipo: Booleano. True se o controle deve ser desabilitado, caso contrário, False.

getAttribute

Retorna o atributo que o controle está associado.

Tipos de controle: padrão, pesquisa, optionset.

Xrm.Page.getControl(arg).getAttribute()

Observação

Controles que não estejam associados a um atributo (subgrade, recurso da Web e IFRAME) não têm esse método. Um erro será jogado se você tentar usar esse método em um desses controles.

  • Valor de Retorno
    Tipo: Objeto: Um atributo.

Comentários

Os controles constitutivos em um controle de exibição rápida são incluídos na coleção de controles e esses controles têm método getAttribute. Entretanto, o atributo não faz parte do conjunto de atributos da entidade. Embora você possa recuperar o valor do atributo usando getValue e até mesmo alterar o valor usando setValue, as alterações realizadas não serão salvas com a entidade.

Os seguintes códigos mostram o uso do valor do atributo mobilephone de contato quando exibidos em um formulário de entidade de conta usando um controle de exibição rápida chamado contactQuickForm. Este código ocultará o controle quando o valor do atributo for null.

var quickViewMobilePhoneControl = Xrm.Page.getControl("contactQuickForm_contactQuickForm_contact_mobilephone");
 if (quickViewMobilePhoneControl.getAttribute().getValue() == null)
 {
  quickViewMobilePhoneControl.setVisible(false);
 }

getControlType

Retorna um valor que categoriza controles.

Tipos de controle: todos.

Xrm.Page.getControl(arg).getControlType()

  • Valor de Retorno
    Tipo: Cadeia de caracteres

    Possíveis valores de retorno do getControlType:

    Valor de Retorno

    Descrição

    standard

    Um controle padrão.

    iframe

    Um controle do IFRAME.

    lookup

    Um controle de pesquisa.

    optionset

    Um controle conjunto de opções.

    subgrid

    Um controle de subgrade.

    webresource

    Um controle de recurso da Web.

    notes

    Um controle de anotações.

    timercontrol

    Um controle de timer.

    kbsearch

    Um controle de pesquisa da base de dados de conhecimento.

getName

Retorna o nome atribuído ao controle.

Observação

O nome atribuído a um controle não é determinado até o formulário carregar. As alterações para o formulário podem alterar o nome atribuído a um determinado controle.

Tipos de controle: todos.

Xrm.Page.getControl(arg).getName()
  • Valor de Retorno
    Tipo: Cadeia de caracteres. O nome do controle.

getParent

Retorna uma referência ao objeto da seção que contém o controle.

Tipos de controle: todos.

Xrm.Page.getControl(arg).getParent()

Métodos de controle da base de dados de conhecimento

Esses métodos estão disponíveis apenas para o controle de pesquisa da base de dados de conhecimento disponível quando a organização do Microsoft Dynamics CRM Online estiver integrada ao Parature. Esses métodos foram introduzidos no Atualização 1 do Microsoft Dynamics CRM Online 2015.

Para obter mais informações sobre esses controles, consulte Controle de pesquisa da base de dados de conhecimento do Parature (referência do cliente).

Etiqueta

Obter ou alterar a etiqueta de um controle usando os métodos getLabel e setLabel.

Tipos de controle: todos.

getLabel

Retorna a etiqueta do controle.

Xrm.Page.getControl(arg).getLabel()
  • Valor de Retorno
    Tipo: Cadeia de caracteres. A etiqueta do controle.

setLabel

Define a etiqueta do controle.

Xrm.Page.getControl(arg).setLabel(label)
  • Argumentos
    Tipo: Cadeia de caracteres. A nova etiqueta do controle.

Métodos de controle de pesquisa e eventos

Controlar os resultados exibidos para um usuário selecionar quando definir o valor de um controle de pesquisa usando os métodos addCustomFilter, addCustomView, getDefaultView e setDefaultView. O controle Lookup também expõe o Evento PreSearch para poder adicionar de forma programática manipuladores de eventos que usam os métodos addPreSearch e removePreSearch.

Tipos de controle: pesquisa.

addCustomFilter

Use para adicionar mais filtros aos resultados exibidos na pesquisa. Cada filtro será combinados com os filtros adicionados anteriormente como uma condição “AND”.

Xrm.Page.getControl(arg).addCustomFilter(filter, entityLogicaName)

  • Argumentos

    • filterXml
      Tipo: Cadeia de caracteres : O elemento de filtro fetchXml a aplicar. Por exemplo:

      <filter type="and">
 <condition attribute="address1_city" operator="eq" value="Redmond" />
</filter>

    • entityLogicalName
      Tipo: Cadeia de caracteres: (Opcional) Se estiver definido, o filtro será aplicado apenas para esse tipo de entidade. Caso contrário, será aplicado a todos os tipos de entidade retornadas.

  • Comentários
    Para obter mais informações:FetchXML schema.

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

    Esse método pode ser usado apenas em uma função em um manipulador de eventos para o Evento PreSearch de controle de pesquisa.

    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);
}

addCustomView

Adiciona uma nova exibição para a caixa de diálogo de pesquisa.

Xrm.Page.getControl(arg).addCustomView(viewId, entityName, viewDisplayName, fetchXml, layoutXml, isDefault)

  • Argumentos

    • viewId
      Tipo: Cadeia de caracteres: A representação da cadeia de caracteres de um GUID para uma exibição.

      Observação

      Esse valor nunca é salvo e só precisa ser exclusivo entre as outras exibições disponíveis para a pesquisa. Uma cadeia de caracteres para um GUID não válido funcionará, por exemplo, “{00000000-0000-0000-0000-000000000001}”. É recomendável usar uma ferramenta como guidgen.exe para gerar um GUID válido. A ferramenta guidgen.exe é incluída no SDK do Windows.

    • entityName
      Tipo: Cadeia de caracteres: O nome da entidade.

    • viewDisplayName
      Tipo: Cadeia de caracteres: O nome da exibição.

    • fetchXml
      Cadeia de caracteres: A consulta fetchXml para a exibição.

    • layoutXml
      Tipo: Cadeia de caracteres: O XML que define o layout da exibição.

    • isdefault
      Tipo: Booleano: Se a exibição deve ser a exibição padrão.

  • Comentários
    Este método não funciona com pesquisas de Proprietário. As pesquisas do proprietário são usadas para atribuir registros de propriedade do usuário.

DefaultView

Você pode detectar que a exibição é a exibição padrão a ser exibida para permitir que os usuários selecionem os registros em uma pesquisa e alterem a exibição padrão com o getDefaultView e setDefaultView.

getDefaultView

Retorna o valor de ID da exibição de diálogo de pesquisa padrão.

Xrm.Page.getControl(arg).getDefaultView()
  • Valor de Retorno
    Tipo: Cadeia de caracteres. O valor da ID da exibição padrão.

setDefaultView

Define a exibição padrão da caixa de diálogo de controle de pesquisa.

Xrm.Page.getControl(arg).setDefaultView(viewGuid)
  • Argumentos
    Tipo: Cadeia de caracteres. A ID da exibição a ser definida como exibição padrão.

Exemplo: essa função do setDefaultViewSample definirá a exibição padrão da pesquisa do contato principal do formulário de entidade account para a exibição de Meus Contatos Ativos.

function setDefaultViewSample() {
    Xrm.Page.getControl("primarycontactid").setDefaultView("{00000000-0000-0000-00AA-000010001003}");
}​

Evento PreSearch

É possível adicionar ou remover manipuladores de eventos para o Evento PreSearch de controle de pesquisa usando os métodos addPreSearch e removePreSearch.

Usar o evento PreSearch para controlar os resultados exibidos para o controle usando os dados do formulário atual conforme o usuário estiver começando a pesquisar registros.

Esses métodos têm Contexto de execução (referência do cliente) passado como o primeiro parâmetro.

addPreSearch

Use este método para aplicar alterações nas pesquisas com base nos valores atuais assim como o usuário está prestes a exibir os resultados da pesquisa.

Xrm.Page.getControl(arg).addPreSearch(handler)

  • Argumentos
    Tipo: Função para adicionar.

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

O argumento é uma função executada imediatamente antes da pesquisa para fornecer resultados quando uma pesquisa ocorre. Você pode usar o manipulador para chamar uma das outras funções de controle de pesquisa e melhorar os resultados para que sejam exibidos na pesquisa.

removePreSearch

Usar este método para remover as funções do manipulador de eventos que foram definidas anteriormente para o evento PreSearch.

Xrm.Page.getControl(arg).removePreSearch(handler)

  • Argumentos
    Tipo: Função para remover.

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

Notificação

Usar setNotification para exibir uma notificação sobre o controle e clearNotification para remover.

setNotification

Exibe uma mensagem próxima ao controle para indicar que os dados não são válidos. Quando este método é usado no Microsoft Dynamics CRM para Tablets, um ícone “X” vermelho é exibido ao lado do controle. Tocar no ícone será exibida a mensagem.

Xrm.Page.getControl(arg).setNotification(message,uniqueId)

Comentários

Definir uma notificação em um controle bloqueará o formulário da economia.

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

Argumentos

  • mensagem
    Tipo: Cadeia de caracteres: A mensagem será exibida.

  • uniqueId
    Tipo: Cadeia de caracteres: A ID para ser usada para desmarcar apenas essa mensagem ao usar clearNotification.

Valor de Retorno

Tipo: Booleano: Indica se o método teve sucesso.

clearNotification

Remove uma mensagem já exibida para um controle.

Xrm.Page.getControl(arg).clearNotification(uniqueId)

Argumentos

  • uniqueId
    Tipo: Cadeia de caracteres: A ID para ser usada para desmarcar uma mensagem específica definida usando setNotification.

    Se o parâmetro uniqueId não for usado, a notificação atual mostrada será removida.

Comentários

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

Valor de Retorno

Tipo: Booleano: Indica se o método teve sucesso.

Métodos de controle OptionSet

Use os métodos addOption, clearOptions e removeOption para manipular opções disponíveis para controles OptionSet. Para um exemplo destas funções sendo colocadas em uso, consulte Exemplo: Criar OptionSets dependentes (listas de seleção).

addOption

Adiciona uma opção para um controle de definição de opção.

Xrm.Page.getControl(arg).addOption(option, [index])

Importante

Este método não verifica se os valores das opções adicionadas são válidos. Se você adicionar opções inválidas, elas não funcionarão corretamente. É preciso apenas adicionar as opções que foram definidas para o atributo de conjunto de opções específico ao qual o controle está vinculado. Usar o atributo getOptions ou os métodos getOption para obter objetos de opção válidos para adicionar usando este método.

  • Argumentos

    • opção
      Tipo: Objeto: Um objeto de opções a ser adicionado ao OptionSet.

    • index
      Tipo: Número: (Opcional) A posição do índice para colocar a nova opção. Se não for fornecido, a opção será adicionada ao final.

clearOptions

Limpa todas as opções de um controle Conjunto de Opções.

Xrm.Page.getControl(arg).clearOptions()

removeOption

Remove uma opção de um controle conjunto de opções.

Xrm.Page.getControl(arg).removeOption(number)
  • Argumentos
    Tipo: Número: O valor da opção que você deseja remover.

setFocus

Define o foco para o controle.

Xrm.Page.getControl(arg).setFocus()

ShowTime

Use setShowTime para especificar se um controle de data deve mostrar a parte da hora da data e, com o Atualização 1 do Microsoft Dynamics CRM Online 2015 ou posterior, use getShowTime para determinar se a parte da hora da data está sendo exibida atualmente.

getShowTime

Veja se um controle de data mostra a parte da hora da data.

Tipos de Controle: controle padrão para os atributos datetime.

var showsTime = Xrm.Page.getControl(arg).getShowTime();

Comentários

Esse método foi introduzido no Atualização 1 do Microsoft Dynamics CRM Online 2015.

setShowTime

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

Tipos de Controle: controle padrão para os atributos datetime.

Xrm.Page.getControl(arg).setShowTime(bool)

Comentários

Este método está disponível somente para o Entidades atualizadas. Esse método mostrará ou ocultará o componente de hora de um controle de data onde o atributo usar o formato DateAndTime. Esse método não terá efeito quando o formato DateOnly for usado.

Métodos de controle de subgrade

Para versões anteriores ao Atualização 1 do Microsoft Dynamics CRM Online 2015, o único método disponível para um controle de subgrade é refresh. Com o CRM Online 2015 Atualização 1, há recursos novos que você pode usar.Para obter mais informações:Objetos e métodos de grade (referência do cliente)

refresh

Atualiza os dados exibidos em uma subgrade.

Xrm.Page.getControl(arg).refresh()

Observação

O método de atualização não está disponível no formulário Evento OnLoad porque as subgrades não são carregadas de forma assíncrona. Com a subgrade Evento OnLoad introduzida no CRM Online 2015 Atualização 1, agora você pode detectar quando a subgrade está carregada e usar esse método com manipuladores de evento para esse evento.

Visível

Determinar quais controles estão visíveis e mostrar ou ocultar usando os métodos getVisible e setVisible.

getVisible

Retorna um valor que indica se o controle está visível no momento.

Observação

Se a seção ou guia contida para este controle não estiverem visíveis, este método ainda pode retornar true. Para garantir que o controle esteja realmente visível; você também precisará verificar a visibilidade de elementos possíveis.

Xrm.Page.getControl(arg).getVisible()
  • Valor de Retorno
    Tipo: Booleano.True se o controle estiver visível. Caso contrário, false.

setVisible

Define um valor que indica se o controle está visível.

Xrm.Page.getControl(arg).setVisible(bool)
  • Argumentos
    Tipo: Booleano.True se o controle deve ser visível. Caso contrário, false.

Observação

Quando você seletivamente mostra campos para os usuários no código que executa no evento Onload, é recomendável configurar campos para não ficarem visíveis por padrão e usar setVisible(true) para mostrar os campos quando as condições são apropriadas. Usar setVisible(false) para ocultar campos no evento Onload pode resultar no campo aparecendo rapidamente para o usuário antes de ser ocultado.

Se estiver ocultando um grande número de campos usando setVisible(false), verifique se você pode agrupar as guias ou seções e ocultar a guia ou seção em vez dos campos separadamente. Isso pode aprimorar o desempenho.

Métodos de controle IFRAME e recursos da Web

Use esses métodos para interagir com o recurso da Web e controles do IFRAME.

Observação

Esses métodos não funcionam com o Microsoft Dynamics CRM para Tablets.

Dados

Recursos da Web têm um parâmetro de cadeia de caracteres de consulta especial chamado data para passar dados personalizados. Os métodos getData e setData funcionam somente para recursos da Web Silverlight adicionados a um formulário.Para obter mais informações:Transmitindo dados de um formulário para um recurso da Web do Silverlight integrado

Para recursos da Web (HTML) da página da Web, o parâmetro de dados pode ser extraído do método ou conjunto getSrc usando o método setSrc.

getData

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

Xrm.Page.getControl(arg).getData()
  • Valor de Retorno
    Tipo: Cadeia de caracteres. O valor de dados passado para o recurso da Web Silverlight.

setData

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

Xrm.Page.getControl(arg).setData(string)
  • Argumentos
    Tipo: Cadeia de caracteres. O valor de dados para passar ao recurso da Web Silverlight.

getInitialUrl

Retorna a URL padrão que um controle URL está configurado para exibição. Este método não está disponível para recursos da Web.

Xrm.Page.getControl(arg).getInitialUrl()
  • Valor de Retorno
    Tipo: Cadeia de caracteres. A URL inicial.

getObject

Retorna o objeto no formulário que representa o recurso da Web ou um I-frame.

Xrm.Page.getControl(arg).getObject()

  • Valor de Retorno
    Tipo: Objeto. Qual objeto depende do tipo de controle.

    Um IFRAME retorna o elemento IFrame do Modelo de Objeto de Documento (DOM).

    Um recurso da Web Silverlight retornará o elemento Object do DOM que representa o plug-in Silverlight integrado.

Src

IFRAMEs e recursos da Web têm uma propriedade src para definir o que exibir na janela integrada. Você pode obter ou alterar a propriedade src usando os métodos getSrc e setSrc.

getSrc

Retorna a URL atual que está sendo exibida em um IFRAME ou um recurso da Web.

Xrm.Page.getControl(arg).getSrc()
  • Valor de Retorno
    Tipo: Cadeia de caracteres. Uma URL representando a propriedade src do IFRAME ou recurso Web.

setSrc

Define a URL a ser exibida em um IFRAME ou um recurso da Web.

Xrm.Page.getControl(arg).setSrc(string)
  • Argumentos
    Tipo: Cadeia de caracteres: A URL.

Confira Também

Referência de programação do cliente
Referência rápida do script de formulário
Xrm.Page.ui (referência do cliente)
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