Atributo Xrm.Page.data.entity (referência do cliente)

 

Publicado: novembro de 2016

Aplicável a: Dynamics CRM 2015

Atributos contendo dados no formulário. Use o conjunto Xrm.Page.data.entity.atributos ou o método de atalho Xrm.Page.getAttribute para acessar um conjunto de atributos. Para obter mais informações, consulte Coleções (referência do cliente).

Propriedades e métodos de atributo

• Métodos de atributo OptionSet e Booleano
  Os métodos getInitialValue, getOption, getOptions, getSelectedOption e getText fornecem formas de obter informações sobre os atributos Boolean ou OptionSet.

• controls
  Controles de acesso associados aos atributos.

• getAttributeType
  Obter o tipo de um atributo.

• getFormat
  Obter o formato do atributo.

• getIsDirty
  Determina se o valor de um atributo foi alterado desde que foi salvo pela última vez.

• getIsPartyList
  Determina se um atributo de pesquisa representa uma pesquisa de partylist.

• getMaxLength
  Obter o comprimento máximo da cadeia de caracteres que um atributo que armazena dados da cadeia de caracteres pode ter.

• getName
  Obter o nome do atributo.

• getParent
  Obter uma referência ao objeto Xrm.Page.data.entity que é o pai de todos os atributos.

• getUserPrivilege
  Determinar quais privilégios um usuário tem para campos usando a Segurança em Nível de Campo.

• Métodos de atributo de número
  Usar os métodos getMax, getMin e getPrecision para acessar informações sobre as propriedades de atributos de número.

• Evento OnChange
  Usar os métodos addOnChange, removeOnChange e fireOnChange e gerenciar manipuladores de eventos para o evento OnChange.

• RequiredLevel
  Usar os métodos setRequiredLevel e getRequiredLevel para controlar se um atributo deve ter um valor para salvar um registro.

• SubmitMode
  Usar os métodos setSubmitMode e getSubmitMode para controlar se o valor de um atributo será enviado quando um registro for salvo.

• Valor
  Usar os métodos getValue e setValue para determinar valores definidos para um atributo e alterar o valor.

Métodos de atributo OptionSet e Booleano

Os métodos getInitialValue, getOption, getOptions, getSelectedOption, e getText oferecem maneiras de obter informações sobre os atributos Boolean ou OptionSet.

getInitialValue

Retorna um valor que representa o conjunto de valores de um atributo OptionSet ou Boolean quando o formulário foi aberto.

Tipos de atributo: Optionset e Boolean

Xrm.Page.getAttribute(arg).getInitialValue()

• Valor de Retorno
  Tipo: Número. O valor inicial do atributo.

getOption

Retorna um objeto de opção com o valor correspondente ao argumento passado para o método.

Tipos de atributos: optionset

Xrm.Page.getAttribute(arg).getOption(value)

• Argumentos
  Valor de cadeia de caracteres ou número

• Valor de Retorno
  Tipo: Objeto de opção com as propriedades text e value.

getOptions

Retorna uma matriz de objetos de opção que representam as opções válidas para um atributo optionset.

Tipos de atributos: optionset

Xrm.Page.getAttribute(arg).getOptions()

• Valor de Retorno
  Tipo: Matriz de objetos de opção.

getSelectedOption

Retorna o objeto de opção selecionado em um atributo optionset.

Tipos de atributos: optionset

Xrm.Page.getAttribute(arg).getSelectedOption()

• Valor de Retorno
  Tipo: Objeto de opção com as propriedades text e value.

getText

Retorna um valor da cadeia de caracteres do texto para a opção selecionada atualmente de um atributo optionset.

Tipos de atributos: optionset

Xrm.Page.getAttribute(arg).getText()

• Valor de Retorno
  Tipo: Cadeia de caracteres. O valor text da opção selecionada.

  Observação

  Quando nenhuma opção estiver marcada, getText retornará o valor de cadeia de caracteres vazia.

controls

Consulte Coleções (referência do cliente) para obter mais informações sobre os métodos expostos por coleções.

Como cada atributo pode ser representado mais de uma vez na página, a coleção de controles proporciona acesso a todos os controles que representam esse atributo. Se o atributo é representado por apenas um campo na página, o tamanho da coleção será 1. Quando você usa o método de controle getName o nome do primeiro controle será igual ao nome do atributo. A segunda instância de um controle para esse atributo será ‘<attributeName>1’. O padrão <attributeName>+N continuará para cada controle adicionado no formulário para um atributo específico.

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 exclusivo como o seguinte: header_process_<attribute name>.

Ao executar ações nos controles vinculados a um atributo, você deverá sempre considerar se o controle pode ser incluído na página mais de uma vez e deve executar geralmente as mesmas ações para cada controle do atributo. É possível fazer isso por loop através da coleção de controles de atributos e executar as ações em cada controle.

O exemplo a seguir representa uma biblioteca JavaScript com as duas funções reutilizáveis que usam a coleção de controles de atributos para ocultar ou mostrar controles:

• SDK.Sample.hideAllAttributeControls: Oculta todos os controles do atributo.

• SDK.Sample.showAllAttributeControls: Mostra todos os controles do atributo.

if (typeof (SDK) == "undefined")
{SDK = { __namespace: true }; }
SDK.Sample = { __namespace: true };
SDK.Sample.hideAllAttributeControls = function (attributeLogicalName) {
    /// <summary>
    /// Hides all controls for the attribute.
    /// </summary>
    /// <param name="attributeLogicalName" type="String" mayBeNull="false" optional="false" >
    /// The logical name of an attribute.
    /// </param>
    if ((typeof attributeLogicalName != "string") ||
        (attributeLogicalName.length <= 3))
    { throw new Error("SDK.Sample.hideAllAttributeControls attributeLogicalName parameter must be a string at least 4 characters long."); }
    Xrm.Page.getAttribute(attributeLogicalName).controls.forEach(
        function (control, i) {
            control.setVisible(false);
            }
        );
}
SDK.Sample.showAllAttributeControls = function (attributeLogicalName) {
    /// <summary>
    /// Shows all controls for the attribute.
    /// </summary>
    /// <param name="attributeLogicalName" type="String" mayBeNull="false" optional="false" >
    /// The logical name of an attribute.
    /// </param>
    if ((typeof attributeLogicalName != "string") ||
        (attributeLogicalName.length <= 3))
    { throw new Error("SDK.Sample.showAllAttributeControls attributeLogicalName parameter must be a string at least 4 characters long."); }
    Xrm.Page.getAttribute(attributeLogicalName).controls.forEach(
        function (control, i) {
            control.setVisible(true);
            }
        );
}

Para usar as funções, passe o nome lógico do atributo conforme ilustrado a seguir:

//Hide the controls for the subject attribute.
SDK.Sample.hideAllAttributeControls("subject");
//Show the controls for the subject attribute.
SDK.Sample.showAllAttributeControls("subject");

getAttributeType

Retorna um valor de cadeia de caracteres que representa o tipo de atributo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getAttributeType()

• Valor de Retorno
  Tipo: Cadeia de caracteres

  Este método retornará um dos seguintes valores da cadeia de caracteres:

  • boolean

  • datetime

  • decimal

  • double

  • integer

  • lookup

  • memo

  • money

  • optionset

  • string

getFormat

Retorna um valor de cadeia de caracteres que representa as opções de formatação do atributo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getFormat()

• Valor de Retorno
  Tipo: Cadeia de caracteres

  Este método retornará um dos seguintes valores da cadeia de caracteres ou null:

  • date

  • datetime

  • duration

  • email

  • language

  • none

  • phone

  • text

  • textarea

  • tickersymbol

  • timezone

  • url

Observação

Essas informações de formato geralmente representam as opções de formato do campo aplicativo. As opções de formato para campos Booleanos não são fornecidas.

A tabela a seguir lista os valores da cadeia de caracteres de formato que devem ser esperados para cada tipo de esquema de atributo e opção de formato.

Tipo de campo do aplicativo	Opção de formatação	Tipo de Atributo	Formatar Valor
Data e Hora	Somente Data	datetime	data
Data e Hora	Data e Hora	datetime	datetime
Número Inteiro	Duração	integer	duration
Linha Única de Texto	Email	string	Email
Número Inteiro	Idioma	optionset	language
Número Inteiro	Nenhum(a)	integer	nenhum
Linha Única de Texto	Área de Texto	string	textarea
Linha Única de Texto	Texto	string	texto
Linha Única de Texto	Símbolo de Ação	string	tickersymbol
Linha Única de Texto	Telefone	string	Telefone
Número Inteiro	Fuso Horário	optionset	timezone
Linha Única de Texto	URL	string	url

getIsDirty

Retorna um valor booleano que indica se não há alterações não salvas do valor do atributo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getIsDirty()

• Valor de Retorno
  Tipo: Booleano. True caso haja alterações não salvas, caso contrário, false.

getIsPartyList

Retorna um valor booleano que indica se a consulta representa uma pesquisa de partylist. As pesquisas de partylist permitem que vários registros sejam definidos, como o campo Para: para um registro da entidade de email.

Tipos de Atributo: pesquisa

Xrm.Page.getAttribute(arg).getIsPartyList()

• Valor de Retorno
  Tipo: Booleano. True se o atributo de pesquisa é um partylist. Caso contrário, false.

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

getMaxLength

Retorna um número indicando o comprimento máximo de um atributo de cadeia de caracteres ou memorando.

Tipos de Atributos: cadeia de caracteres, memorando

Xrm.Page.getAttribute(arg).getMaxLength()

• Valor de Retorno
  Tipo: Número. O comprimento máximo permitido de uma cadeia de caracteres para este atributo.

  Observação

  O atributo do formulário de e-mail do description é um atributo memo, mas não possui um método getMaxLength.

getName

Retorna uma cadeia de caracteres que representa o nome lógico do atributo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getName()

• Valor de Retorno
  Tipo: Cadeia de caracteres. O nome lógico do atributo.

getParent

Retorna o objeto Xrm.Page.data.entity que é o pai de todos os atributos.

Esta função existe para fornecer uma interface consistente com os objetos. Nesse caso, como cada atributo retorna o mesmo objeto, existem várias situações em que não é útil.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getParent()

• Valor de Retorno
  Tipo:Xrm.Page.data.entity objeto.

getUserPrivilege

Retorna um objeto com três propriedades booleanas que correspondem aos privilégios indicando se o usuário pode criar, ler e atualizar valores de dados para um atributo. Esta função é destinada para uso quando a Segurança de Nível de Campo modifica um privilégio do usuário para um atributo específico. Para obter mais informações, consulte Como a segurança de campo pode ser usada para controlar o acesso aos valores de campo no Microsoft Dynamics CRM 2015.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getUserPrivilege()

• Valor de Retorno
  Tipo: Objeto

  O objeto tem três propriedades booleanas:

  • canRead

  • canUpdate

  • canCreate

Métodos de atributo de número

Usar os métodos getMax, getMin e getPrecision para acessar informações sobre as propriedades de atributos de número.

getMax

Retorna um número indicando o valor máximo permitido para um atributo.

Tipos de Atributos: dinheiro, decimal, inteiro, duplo

Xrm.Page.getAttribute(arg).getMax()

• Valor de Retorno
  Tipo: Número. O valor máximo permitido do atributo.

getMin

Retorna um número indicando o valor mínimo permitido para um atributo.

Tipos de Atributos: dinheiro, decimal, inteiro, duplo

Xrm.Page.getAttribute(arg).getMin()

• Valor de Retorno
  Tipo: Número. O valor mínimo permitido do atributo.

getPrecision

Retorna o número de dígitos permitidos à direita do ponto decimal.

Tipos de Atributos: dinheiro, decimal, duplo e inteiro

Xrm.Page.getAttribute(arg).getPrecision()

• Valor de Retorno
  Tipo: Número. O número de dígitos permitidos à direita do ponto decimal.

Evento OnChange

Há três métodos que podem ser usadas para trabalhar com o evento OnChange de um atributo:

• addOnChange

• removeOnChange

• fireOnChange

addOnChange

Define uma função a ser chamada quando o valor do atributo for alterado.

Xrm.Page.getAttribute(arg).addOnChange([function reference])

• Parâmetro
  Tipo: ponteiro de função

  Comentários: A função será adicionada à parte inferior do pipeline do manipulador de eventos. O contexto de execução é definido automaticamente como o primeiro parâmetro passado para o manipulador de eventos. Consulte Contexto de execução (referência do cliente) para obter mais informações.

  Exemplo: Neste exemplo, a biblioteca JScript contém duas funções. Adicionar a função addMessageToOnChange ao evento OnLoad do formulário adicionará a função displayMessage como um manipulador do evento OnChange para o primeiro atributo no formulário.

  function addMessageToOnChange() 
  { 
     Xrm.Page.data.entity.attributes.get(0).addOnChange(displayOrgName);
  }
  function displayOrgName(execContext) 
  { 
     Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
  }
  

removeOnChange

Remove uma função do manipulador de eventos OnChange para um atributo.

Xrm.Page.getAttribute(arg).removeOnChange([function reference])

• Parâmetro
  Tipo: referência de função

  Exemplo: Neste exemplo, a biblioteca JScript contém duas funções. Adicionar a função removeMessageFromOnChange ao outro evento do formulário removerá a função displayOrgName como um manipulador do evento OnChange para o primeiro atributo no formulário.

  function removeMessageFromOnChange() 
  {
     Xrm.Page.data.entity.attributes.get(0).removeOnChange(displayOrgName);
  }
  function displayOrgName(execContext) 
  { 
     Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
  }
  

fireOnChange

Faz com que o evento OnChange ocorra no atributo para que qualquer script associado ao evento possa ser executado.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).fireOnChange()

RequiredLevel

É possível controlar se o aplicativo exigirá que um campo contenha dados antes de um registro ser salvo. Use os métodos getRequiredLevel e de setRequiredLevel para ajustar esse requisito.

getRequiredLevel

Retorna um valor de cadeia de caracteres indicando se o valor do atributo é obrigatório ou recomendado.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getRequiredLevel()

• Valor de Retorno
  Tipo: Cadeia de caracteres

  Retorna um dos três valores possíveis:

  • none

  • required

  • recommended

setRequiredLevel

Define se os dados são necessários ou recomendados para o atributo antes que o registro possa ser salvo.

Importante

Reduzir o nível necessário de um atributo pode causar um erro quando a página for salva. Se o atributo for exigido pelo servidor, ocorrerá um erro se não houver nenhum valor para o atributo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).setRequiredLevel(requirementLevel)

• Argumentos
  Tipo: Cadeia de caracteres

  Um dos seguintes valores:

  • none

  • required

  • recommended

SubmitMode

Você pode controlar quando os dados de um atributo são enviados quando um registro é criado ou salvo. Por exemplo, você pode ter um campo no formulário que é destinado apenas à lógica de controle no formulário. Você não está interessado em capturar os dados nele. Talvez possa ser necessário definir para que os dados não sejam salvos. Ou você pode ter um plug-in registrado que depende do valor sempre sendo incluído. Convém definir o atributo de modo que seja incluído sempre. Atributos que não são atualizados depois do salvamento inicial do registro, como createdby, são definidos de forma que não sejam enviados ao salvar. Para forçar um valor de atributo a ser enviado se for alterado ou não, use a função setSubmitMode com o parâmetro do modo como “sempre”.

Ao usar setSubmitMode. você tem três opções:

• always: O valor é sempre enviado.

• never: O valor nunca é enviado. Quando essa opção está definida, os dados não podem ser editados para esses campos no formulário para esse atributo.

• dirty (padrão): O valor é enviado na criação se não for nulo e ao salvar apenas quando for alterado.

Use getSubmitMode para determinar a configuração atual.

getSubmitMode

Retorna uma cadeia de caracteres que indica quando os dados do atributo serão enviados ao salvar o registro.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getSubmitMode()

• Valor de Retorno
  Tipo: Cadeia de caracteres

  Retorna um dos três valores possíveis:

  • always

  • never

  • dirty

  O valor padrão para campos editáveis é “sujo”, o que significa que o valor será enviado ao servidor somente quando o valor de dados for alterado.

setSubmitMode

Define se os dados do atributo serão enviados quando o registro for salvo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).setSubmitMode()

• Argumentos
  Tipo: Cadeia de caracteres

  Um dos seguintes valores:

  • always: Os dados são sempre enviados com um salvamento.

  • never: Os dados nunca são enviados com um salvamento. Quando essa opção for usada, os campos no formulário deste atributo não podem ser editados.

  • dirty: Comportamento padrão. Os dados são enviados ao salvar quando tiverem sido alterados.

Valor

Acessar ou definir o valor de atributos são mais comuns às ações executadas em scripts de formulário.

getValue

Recupera o valor de dados para um atributo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).getValue()

• Valor de Retorno
  Tipo: Depende do tipo de atributo.

  Tipo de Atributo	Tipo de retorno
  boolean	Booliano
  datetime	Data Para obter a versão de cadeia de caracteres de uma data com as preferências de localidade do usuário Microsoft Dynamics 365, use os métodos format e localeFormat. Outros métodos formatarão datas usando a localidade do sistema operacional em vez das preferências de localidade do Microsoft Dynamics 365 do usuário.
  decimal	Número
  Duplo	Número
  integer	Número
  pesquisa	Matriz Uma matriz de objetos de pesquisa. Observação Determinadas pesquisas permitem que vários registros sejam associados a uma pesquisa, como o campo Para: para um registro da entidade de email. Portanto, todos os valores de dados de pesquisa usam uma matriz de objetos de pesquisa – mesmo quando o atributo de pesquisa não oferece suporte a mais de uma referência de registro a ser adicionada. Cada pesquisa deve ter as seguintes propriedades: entityType Cadeia de caracteres: o nome da entidade exibida na pesquisa ID Cadeia de caracteres: A representação da cadeia de caracteres do valor GUID para o registro exibido na pesquisa. nome Cadeia de caracteres: O texto que representa o registro a ser exibido na pesquisa.
  memo	Cadeia de caracteres
  money	Número
  optionset	Número
  string	Cadeia de caracteres

setValue

Define o valor de dados para um atributo.

Tipos de Atributo: Todos

Xrm.Page.getAttribute(arg).setValue()

• Argumentos
  Depende do tipo de atributo.

  Tipo de Atributo	Argument Type
  boolean	Booliano
  datetime	Data
  decimal	Número
  double	Número
  Inteiro	Número
  pesquisa	Matriz Uma matriz de objetos de pesquisa. Observação Determinadas pesquisas, conhecidas como pesquisas "partylist", permitem que vários registros sejam associados a uma pesquisa, como o campo Para: para um registro da entidade de email. Portanto, todos os valores de dados de pesquisa usam uma matriz de objetos de pesquisa – mesmo quando o atributo de pesquisa não oferece suporte a mais de uma referência de registro a ser adicionada. Cada valor de pesquisa deve ter as seguintes propriedades: entityType Cadeia de caracteres: o nome lógico da entidade representada pela pesquisa. ID Cadeia de caracteres: A representação da cadeia de caracteres do valor GUID para o registro exibido na pesquisa. Esse valor deverá corresponder ao seguinte formato: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. nome Cadeia de caracteres: O texto que representa o registro a ser exibido na pesquisa. Geralmente o atributo principal da entidade. Consulte Definir valor do atributo de pesquisa para ver um exemplo de uma função auxiliar que você pode criar para definir valores de atributo de pesquisa simples.
  memo	Cadeia de caracteres
  money	Número
  optionset	Número Observação O método getOptions retorna valores de opção como cadeias de caracteres. Você deve usar parseInt para converter para números antes de poder usar esses valores para definir o valor de um atributo optionset. As opções statuscode (Razão do Status) válidas dependem do statecode atual do registro. O campo statecode (Status) não pode ser definido em scripts de formulário. Para entender quais valores statecode são válidos, consulte os metadados dos atributos. Consulte TechNet: Valores de motivo de status e status padrão para obter uma lista de valores padrão de entidades do sistema. Para entidades personalizadas, use o navegador de metadados da entidade descrito em Procurar os metadados da sua organização. Por fim, considere também todas as transações de estado personalizadas que foram aplicadas ao campo.Para obter mais informações:TechNet: Definir transições de motivo do status.
  Cadeia de caracteres	Cadeia de caracteres Observação Um campo de cadeia de caracteres com o formato de email precisará que a cadeia de caracteres represente um endereço de email válido.

Observação

• Atualizar um atributo usando o setValue não causará a execução dos manipuladores de eventos OnChange. Se desejar que os manipuladores de eventos OnChange executem, você deve usar o fireOnChange além de setValue.

• Quando o Microsoft Dynamics CRM para Tablets não estiver conectado ao servidor, o setValue não funcionará.

• Não é possível definir o valor de atributos compostos.Para obter mais informações:Scripts de gravação para atributos compostos.

Definir valor do atributo de pesquisa

O exemplo a seguir mostra a definição de uma função auxiliar setSimpleLookupValue que define o valor para atributos de pesquisa simples.

function setSimpleLookupValue(LookupId, Type, Id, Name) {
   /// <summary>
   /// Sets the value for lookup attributes that accept only a single entity reference.
   /// Use of this function to set lookups that allow for multiple references, 
   /// a.k.a 'partylist' lookups, will remove any other existing references and 
   /// replace it with just the single reference specified.
   /// </summary>
   /// <param name="LookupId" type="String" mayBeNull="false" optional="false" >
   /// The lookup attribute logical name
   /// </param>
   /// <param name="Type" type="String" mayBeNull="false" optional="false" >
   /// The logical name of the entity being set.
   /// </param>
   /// <param name="Id" type="String" mayBeNull="false" optional="false" >
   /// A string representation of the GUID value for the record being set.
   /// The expected format is "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".
   /// </param>
   /// <param name="Name" type="String" mayBeNull="false" optional="false" >
   /// The text to be displayed in the lookup.
   /// </param>
   var lookupReference = [];
   lookupReference[0] = {};
   lookupReference[0].id = Id;
   lookupReference[0].entityType = Type;
   lookupReference[0].name = Name;
   Xrm.Page.getAttribute(LookupId).setValue(lookupReference);
  }

O exemplo a seguir é um exemplo usando a função setSimpleLookupValue para definir o valor de atributo primarycontactid em um formulário de conta:

setSimpleLookupValue("primarycontactid", "contact", "{6D9D4FCF-F4D3-E011-9D26-00155DBA3819}", "Brian Lamee");

Confira Também

Referência de programação do cliente
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