Compartir a través de

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

  • Artículo

 

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

Nota

Esta información de formato representa normalmente las opciones de formato del campo de la aplicación. Las opciones de formato de los campos booleanos no se proporcionan.

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.

Importante

Al reducir el nivel requerido de un atributo puede producirse un error al guardar la página. Si el atributo es requerido por el servidor se produce un error si no hay ningún valor para el atributo.

Este método solo es compatible para los campos de un formulario. No puede usar este método con los atributos que se muestran en el control de proceso de negocio para establecer el nivel de requisito de un paso de flujo de proceso de negocio. Para obtener más información acerca de los métodos de cliente disponibles para el paso del flujo de proceso de negocio, consulte Métodos de paso

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.

Nota

  • Actualizar un atributo mediante setValue no hace que los controladores de eventos de OnChange se ejecuten. Si desea que los controladores de eventos de OnChange se ejecuten debe usar fireOnChange además de setValue.

  • Cuando Microsoft Dynamics 365 para tabletas no está conectado al servidor setValue no funcionará.

  • No puede establecer el valor atributos compuestos.Más información:Escribir scripts para atributos compuestos.

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