Atributo Xrm.Page.data.entity (referencia de cliente)

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Los atributos contienen los datos del formulario. Use la colección de Xrm.Page.data.entity.fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_entityattributes o el método de acceso directo Xrm.Page.getAttribute para acceder a una colección de atributos. Para obtener más información, vea Colecciones (referencia del lado del cliente).

Propiedades y métodos de atributos

• Métodos de atributos booleanos y de OptionSet
  Los métodos getInitialValue, getOption, getOptions, getSelectedOption y getText proporcionan formas de obtener información acerca de atributos booleanos o de OptionSet.

• controles
  Controles de acceso asociados a atributos.

• getAttributeType
  Obtenga el tipo de atributo.

• getFormat
  Obtenga el formato del atributo.

• getIsDirty
  Determine si el valor de un atributo ha cambiado desde que se guardó por última vez.

• getIsPartyList
  Determine si un atributo de búsqueda representa una búsqueda Partylist.

• getMaxLength
  Obtenga la longitud máxima de cadena que puede tener un atributo que almacena datos de cadena.

• getName
  Obtenga el nombre del atributo.

• getParent
  Obtenga una referencia al objeto de Xrm.Page.data.entity que es el elemento primario de todos los atributos.

• getUserPrivilege
  Determine qué privilegios tiene un usuario para los campos que utilizan seguridad de nivel de campo.

• Número de métodos del atributo
  Use los métodos getMax, getMin y getPrecision para obtener acceso a información sobre las propiedades de atributos de número.

• Evento OnChange
  Use los métodos addOnChange, removeOnChange y fireOnChange para administrar controladores de eventos para el evento OnChange.

• RequiredLevel
  Use los métodos setRequiredLevel y getRequiredLevel para controlar si un atributo debe tener un valor para guardar un registro.

• SubmitMode
  Use los métodos setSubmitMode y getSubmitMode para controlar si el valor de un atributo se envía al guardar un registro.

• Valor
  Use los métodos getValue y setValue para determinar los valores establecidos para un atributo y cambiar el valor.

Métodos de atributos booleanos y de OptionSet

Los métodos getInitialValue, getOption, getOptions, getSelectedOption y getText proporcionan formas de obtener información acerca de atributos Boolean o de OptionSet.

getInitialValue

Devuelve un valor que representa el valor establecido para un atributo OptionSet o Boolean cuando se abrió el formulario.

Tipos de atributos: OptionSet y booleanos

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

• Valor devuelto
  Tipo: Número. El valor inicial del atributo.

getOption

Devuelve un objeto de opción con el valor que coincide con el argumento pasado al método.

Tipos de atributo: optionset

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

• Argumentos
  Valor de cadena o numérico

• Valor devuelto
  Tipo: Objeto de opción con propiedades text y value.

getOptions

Devuelve una matriz de objetos de opción que representan las opciones válidas para un atributo optionset.

Tipos de atributo: optionset

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

• Valor devuelto
  Tipo: Matriz de objetos de opción.

getSelectedOption

Devuelve el objeto de opción que está seleccionado en un atributo optionset.

Tipos de atributo: optionset

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

• Valor devuelto
  Tipo: Objeto de opción con propiedades text y value.

getText

Devuelve un valor de cadena del texto para la opción actualmente seleccionada para un atributo optionset.

Tipos de atributo: optionset

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

• Valor devuelto
  Tipo: Cadena. El valor de text de la opción seleccionada.

  Nota

  Cuando no se selecciona ninguna opción, getText devolverá un valor de cadena vacío.

controles

Vea Colecciones (referencia del lado del cliente) para obtener información sobre los métodos expuestos por colecciones.

Dado que cada atributo se puede representar más de una vez en la página, la colección de controles proporciona acceso a todos los controles que representan ese atributo. Si el atributo es representado sólo por un campo en la página, la longitud de esta colección será 1. Al usar el método 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getName del control, el nombre del primer control coincidirá con el nombre del atributo. La segunda instancia de un control para ese atributo será ‘<attributeName>1’. El patrón <attributeName>+N continuará para cada control adicional agregado al formulario para un atributo específico.

Cuando un formulario muestra un control de flujo de proceso de negocio en el encabezado, se agregarán controles adicionales para cada atributo que se muestra en el flujo de proceso de negocio. Estos controles tienen un nombre único como el siguiente: header_process_<attribute name>.

Cuando realice acciones en los controles que están ligados a un atributo siempre debe considerar que el control puede estar incluido en la página más de una vez y normalmente debe realizar las mismas acciones para cada control para el atributo. Puede hacerlo recorriendo la colección de controles de atributo y realizar las acciones en cada control.

El siguiente ejemplo representa una biblioteca de JavaScript con dos funciones reutilizables que usan la colección de controles de atributo para ocultar y mostrar controles:

• SDK.Sample.hideAllAttributeControls: Oculta todos los controles del atributo.

• SDK.Sample.showAllAttributeControls: Muestra todos los controles del 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 estas funciones, pase el nombre lógico del atributo como se indica aquí:

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

getAttributeType

Devuelve un valor de cadena que representa el tipo de atributo.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Cadena

  Este método devolverá uno de los siguientes valores de cadena:

  • boolean

  • datetime

  • decimal

  • double

  • integer

  • lookup

  • memo

  • money

  • optionset

  • string

getFormat

Devuelve un valor de cadena que representa las opciones de formato del atributo.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Cadena

  Este método devolverá uno de los siguientes valores de cadena o null:

  • date

  • datetime

  • duration

  • email

  • language

  • none

  • phone

  • text

  • textarea

  • tickersymbol

  • timezone

  • url

La siguiente tabla enumera los valores de cadena de formato que se pueden esperar para cada tipo de opción de formato y tipo de esquema de atributo.

Tipo de campo de aplicación	Opción de formato	Tipo de atributo	Valor de formato
Fecha y hora	Sólo fecha	datetime	fecha
Fecha y hora	Fecha y hora	datetime	datetime
Número entero	Duración	integer	duración
Línea única de texto	Correo electrónico	string	Correo electrónico
Número entero	Idioma	optionset	language
Número entero	Ninguna	integer	ninguna
Línea única de texto	Área de texto	string	textarea
Línea única de texto	Texto	string	texto
Línea única de texto	Símbolo del valor	string	tickersymbol
Línea única de texto	Teléfono	string	Teléfono
Número entero	Zona horaria	optionset	timezone
Línea única de texto	Dirección URL	string	url

getIsDirty

Devuelve un valor booleano que indica si hay cambios no guardados en el valor del atributo.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Booleano. True si hay cambios no guardados; en caso contrario, false.

getIsPartyList

Devuelve un valor booleano que indica si la búsqueda representa una búsqueda de tipo partylist. Las búsquedas de tipo partylist permiten establecer varios registros, como el campo Para: para un registro de entidad de correo electrónico.

Tipos de atributo: búsqueda

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

• Valor devuelto
  Tipo: Booleano. True si el atributo de búsqueda es partylist; si no, false.

• Comentarios
  Este método solo está disponible para 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties.

getMaxLength

Devuelve un número que indica la longitud máxima de un atributo de cadena o de memo.

Tipos de atributo: cadena, memo

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

• Valor devuelto
  Tipo: Número. La longitud máxima permitida de una cadena para este atributo.

  Nota

  El atributo description del formulario de correo electrónico es un atributo memo, pero no tiene un método getMaxLength.

getName

Devuelve una cadena que representa el nombre lógico del atributo.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Cadena. El nombre lógico del atributo.

getParent

Devuelve el objeto Xrm.Page.data.entity que es el elemento primario de todos los atributos.

Esta función sirve para proporcionar una interfaz consistente con otros objetos. En este caso, dado que cada atributo devuelve el mismo objeto, no hay muchas situaciones donde resulte útil.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Objeto Xrm.Page.data.entity.

getUserPrivilege

Devuelve un objeto con tres propiedades booleanas correspondientes a privilegios que indican si el usuario puede crear, leer o actualizar los valores de los datos de un atributo. Esta funcionalidad se usa cuando la seguridad de nivel de campo modificar los privilegios de un usuario para un atributo determinado. Para obtener más información, vea Cómo se puede usar la seguridad de campos para controlar el acceso a los valores de campo en Microsoft Dynamics 365.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo:Objeto

  El objeto tiene tres propiedades booleanas:

  • canRead

  • canUpdate

  • canCreate

Número de métodos del atributo

Use los métodos getMax, getMin y getPrecision para obtener acceso a información sobre las propiedades de atributos de número.

getMax

Devuelve un número que indica el valor máximo permitido para un atributo.

Tipos de atributo: dinero, decimal, entero, doble

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

• Valor devuelto
  Tipo: Número. El valor máximo permitido para el atributo.

getMin

Devuelve un número que indica el valor mínimo permitido para un atributo.

Tipos de atributo: dinero, decimal, entero, doble

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

• Valor devuelto
  Tipo: Número. El valor mínimo permitido para el atributo.

getPrecision

Devuelve el número de dígitos permitidos a la derecha de la coma decimal.

Tipos de atributo: dinero, decimal, entero, doble y entero

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

• Valor devuelto
  Tipo: Número. El número de dígitos permitidos a la derecha de la coma decimal.

Evento OnChange

Hay tres métodos que puede usar para trabajar con el evento OnChange para un atributo:

• addOnChange

• removeOnChange

• fireOnChange

addOnChange

Establece una función a la que se llamará cuando cambie el valor del atributo.

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

• Parámetro
  Tipo: puntero de función

  Comentarios: La función se agregará al final de la canalización del controlador de eventos. El contexto de ejecución se configura automáticamente para ser el primer parámetro que se pasa al controlador de eventos. Para obtener más información, vea Contexto de ejecución (referencia del lado del cliente).

  Ejemplo:En este ejemplo, la biblioteca JScript contiene dos funciones. Agregando la función addMessageToOnChange al evento OnLoad del formulario se agregará la función displayMessage como controlador del evento OnChange para el primer atributo del formulario.

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

removeOnChange

Quita una función del controlador del evento OnChange para un atributo.

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

• Parámetro
  Tipo: referencia de función

  Ejemplo: En este ejemplo, la biblioteca JScript contiene dos funciones. Agregando la función removeMessageFromOnChange a otro evento del formulario se quitará la función displayOrgName como controlador del evento OnChange para el primer atributo del formulario.

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

fireOnChange

Hace que el evento OnChange se produzca en el atributo de modo que se pueda ejecutar cualquier script asociado con ese evento.

Tipos de atributo: Todos

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

RequiredLevel

Puede controlar si la aplicación requerirá que un campo contenga datos para poder guardar un registro. Use los métodos getRequiredLevel y setRequiredLevel para ajustar este requisito.

getRequiredLevel

Devuelve un valor de cadena que indica si un valor del atributo es necesario o recomendado.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Cadena

  Devuelve uno de los tres valores posibles:

  • none

  • required

  • recommended

setRequiredLevel

Establece si los datos son requeridos o recomendados para el atributo antes de que el registro pueda ser guardado.

Tipos de atributo: Todos

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

• Argumentos
  Tipo: Cadena

  Uno de los siguientes valores:

  • none

  • required

  • recommended

SubmitMode

Puede controlar cuándo se envían datos para un atributo al crear o guardar un registro. Por ejemplo, puede tener un campo en el formulario que está pensado solo para controlar la lógica en el formulario. No está interesado en capturar los datos que contiene. Es posible configurarlo para no guardar los datos. O puede tener un complemento registrado que dependa del valor que siempre se incluye. Es posible que desee establecer el atributo de modo que siempre se incluya. Los atributos que no se actualizan tras guardar inicialmente el registro, como createdby, se configuran de forma que no se envíen al guardar. Para forzar un valor de atributo para que se envíe si ha cambiado o no, use la función setSubmitMode con el parámetro de modo establecido como "siempre".

Cuando usa setSubmitMode tiene tres opciones:

• always: El valor se envía siempre.

• never: El valor no se envía nunca. Cuando se establece esta opción, los datos no se pueden modificar para los campos del formulario para este atributo.

• dirty (predeterminado): El valor se enviará al crear si no es nulo, y al guardar solo cuando cambia.

Use getSubmitMode para determinar la configuración actual.

getSubmitMode

Devuelve una cadena que indica cuándo se enviarán los datos del atributo al guardar el registro.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Cadena

  Devuelve uno de los tres valores posibles:

  • always

  • never

  • dirty

  El valor predeterminado de los campos editables es "no válido", lo que significa que el valor se envía al servidor solo cuando cambie el valor de los datos.

setSubmitMode

Establece si los datos del atributo se enviarán al guardar el registro.

Tipos de atributo: Todos

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

• Argumentos
  Tipo: Cadena

  Uno de los siguientes valores:

  • always: Los datos se envían siempre al guardar.

  • never: Los datos no se envían nunca al guardar. Cuando se utiliza esto, no se pueden modificar los campos del formulario para este atributo.

  • dirty: Comportamiento predeterminado. Los datos se envían al guardar cuando han cambiado.

Valor

Acceder o establecer el valor de atributos son las acciones realizadas con mayor frecuencia en scripts de formularios.

getValue

Recupera el valor de los datos de un atributo.

Tipos de atributo: Todos

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

• Valor devuelto
  Tipo: Depende del tipo de atributo.

  Tipo de atributo	Tipo devuelto
  booleano	Booleano
  datetime	Fecha Para obtener la versión de la cadena de una fecha utilizando las preferencias de configuración regional del usuario de Microsoft Dynamics 365, use los métodos format y localeFormat. Otros métodos formatearán las fechas con la configuración regional del sistema operativo en lugar de las preferencias de configuración regional de Microsoft Dynamics 365 del usuario.
  decimal	Número
  Double	Número
  entero	Número
  búsqueda	Matriz Una matriz de objetos de búsqueda. Nota Algunas búsquedas permiten asociar varios registros en una búsqueda, como el campo Para: para un registro de entidad de correo electrónico. Por consiguiente, todos los valores de los datos de búsqueda usan una matriz de objetos de búsqueda, incluso cuando el atributo de búsqueda no admite que se agregue más de una referencia de registro. Cada búsqueda tiene las siguientes propiedades: entityType Cadena: el nombre de la entidad mostrada en la búsqueda id. Cadena: La representación de cadena del valor de GUID para el registro mostrado en la búsqueda. nombre Cadena: El texto que representa el registro que se mostrará en la búsqueda.
  memo	Cadena
  money	Número
  optionset	Número
  cadena	Cadena

setValue

Establece el valor de los datos de un atributo.

Tipos de atributo: Todos

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

• Argumentos
  Depende del tipo de atributo.

  Tipo de atributo	Tipo de argumento
  booleano	Booleano
  datetime	Fecha
  decimal	Número
  doble	Número
  Entero	Número
  búsqueda	Matriz Una matriz de objetos de búsqueda. Nota Algunas búsquedas, llamadas búsquedas "partylist", permiten asociar varios registros en una búsqueda, como el campo Para: para un registro de entidad de correo electrónico. Por consiguiente, todos los valores de los datos de búsqueda usan una matriz de objetos de búsqueda, incluso cuando el atributo de búsqueda no admite que se agregue más de una referencia de registro. Cada valor de búsqueda tiene las siguientes propiedades: entityType Cadena: el nombre lógico de la entidad representada por la búsqueda. id. Cadena: La representación de cadena del valor de GUID para el registro mostrado en la búsqueda. El valor debe coincidir con el siguiente formato: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. nombre Cadena: El texto que representa el registro que se mostrará en la búsqueda. Normalmente el atributo principal para la entidad. Vea Establezca el valor de atributo de búsqueda para un ejemplo de una función de ayuda que puede crear para establecer los valores de atributo de búsqueda simples.
  memo	Cadena
  money	Número
  optionset	Número Nota El método getOptions devuelve valores de opción como cadenas. Debe usar parseInt para convertirlas a números para poder usar esos valores para establecer el valor de un atributo optionset. Las opciones válidas statuscode (razón para el estado) dependen del statecode actual del registro. El campo statecode (Estado) no se puede establecer en scripts de formularios. Para saber qué valores de statecode son válidos, consulte los metadatos para los atributos. Vea TechNet: Valores predeterminados de estado y razón para el estado para una lista de valores predeterminados de las entidades del sistema. Para las entidades personalizadas use el explorador de los metadatos de la entidad descrito en Examinar los metadatos de la organización. Finalmente, considere también cualquier transición de estado personalizada que se haya aplicado al campo.Más información:TechNet: Defina transiciones de razón para el estado.
  Cadena	Cadena Nota Un campo de cadena con el formato de correo electrónico requiere que la cadena represente una dirección de correo electrónico válida.

Establezca el valor de atributo de búsqueda

El siguiente ejemplo muestra la definición de una función de ayuda de setSimpleLookupValue que establece el valor para atributos de búsqueda 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);
  }

Lo siguiente es un ejemplo que utiliza la función setSimpleLookupValue para establecer el valor del atributo primarycontactid en un formulario de cuenta:

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

Ver también

Referencia de programación del lado del cliente
Referencia de scripting de formularios
Escriba código para formularios de Microsoft Dynamics 365
Use el modelo de objeto Xrm.Page

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright