Contexto de formulario de la API de cliente

El contexto del formulario de cliente API (formContext) proporciona una referencia al formulario o a un elemento en el formulario, como por ejemplo, un control de vista rápida o una fila de una cuadrícula editable, en el que se ejecuta el código actual.

Anteriormente, el objeto Xrm.Page global se usaba para representan un formulario o un elemento en el formulario. Con la versión más reciente, el objeto Xrm.Page está obsoleto, y ahora debe utilizar el método getFormContext del objeto de contexto de ejecución pasado para devolver referencia al formulario adecuado o a un elemento en el formulario.

Importante

Obsoleta significa que se va a quitar una característica o una funcionalidad en una versión futura de aplicaciones basadas en modelos, la característica o funcionalidad continuará funcionando y estará completamente admite hasta que se quite oficialmente. Se realizará un anuncio público aquí en la documentación, en el blog oficial, y en muchos otros lugares al menos seis meses antes de la eliminación.

El uso del objeto Xrm.Page como acceso estático al contexto principal de formulario todavía se admite para mantener compatibilidad con versiones anteriores de scripts existentes y no se eliminará tan pronto como algunos otros métodos API de cliente que aparecen en la sección Obsolescencia de API de cliente . Se recomienda usar el nuevo objeto formContext en lugar del objeto Xrm.Page en el código dirigido a la versión 9.0 o posterior donde sea posible. Además, usar el objeto formContext permite crear controladores de eventos comunes que pueden funcionar en un formulario o en una cuadrícula editable en función de dónde sea llamado. Más información: getFormContext (referencia de la API de cliente).

Obtener el objeto formContext para las funciones de JavaScript para acciones de la cinta es diferente de cómo obtenerlo en secuencias de comandos de formulario. Más información: Formulario y cuadrícula en las acciones de la cinta.

Nota

Los contextos de formulario solo son válidos durante el evento en el que se pasan. Se aplican las mismas restricciones que con los contextos de ejecución.

Uso del objeto formContext en lugar del objeto Xrm.Page

Es muy fácil convertir un código existente con Xrm.Page para usar el nuevo objeto formContext. Por ejemplo, considere el siguiente script que utiliza el objeto Xrm.Page:

function displayName()
{
   var firstName = Xrm.Page.getAttribute("firstname").getValue();
   var lastName = Xrm.Page.getAttribute("lastname").getValue();
   console.log(firstName + " " + lastName);
}

Aquí está el script actualizado que usa el contexto de ejecución pasado para recuperar el objeto formContext en lugar de usar el objeto estático Xrm.Page :

function displayName(executionContext)
{
   var formContext = executionContext.getFormContext(); // get formContext

   // use formContext instead of Xrm.Page   
   var firstName = formContext.getAttribute("firstname").getValue(); 
   var lastName = formContext.getAttribute("lastname").getValue();
   console.log(firstName + " " + lastName);
}

Importante

Recuerde seleccionar la opción pasar el contexto de ejecución como primer parámetro en el diálogo propiedades de controlador al definir los controladores de eventos para usar el objeto formContext. Más información: Contexto de ejecución de la API del cliente

Modelo de objetos formContext

Utilice los objetos data y ui del objeto formContext para manipular mediante programación los elementos de la interfaz de usuario y los datos de aplicaciones basadas en modelos.

Objeto de datos

Proporciona propiedades y métodos para trabajar con los datos de un formulario, incluidos los datos de tabla y los datos de control del flujo de proceso de negocio. Contiene los siguientes objetos:

Objecto	Description
attributes	Recopilación de datos que no son de tabla en el formulario. Los elementos de esta colección son del mismo tipo que la colección de columnas, pero no son columnas de la tabla de formulario. Más información: Colecciones.
entity	Proporciona métodos para recuperar información específica del registro que se muestra en la página, el método de guardar y una colección de todas las columnas que se incluyen en el formulario. Los datos de las columnas se limitan a las columnas representadas en el formulario. Más información: formContext.data.entity
process	Proporciona objetos y métodos para interactuar con los datos del flujo de proceso de negocio en un formulario. Más información: formContext.data.process

También proporciona una colección de atributos para acceder a controles no enlazados a tablas. Consulte la sección Colecciones en el modelo de objetos formContext más adelante en este artículo.

Más información: formContext.data

objeto ui

Proporciona métodos para recuperar información acerca de la interfaz de usuario, además de colecciones para varios subcomponentes del formulario o la cuadrícula. Contiene los siguientes objetos:

Objecto	Description
formSelector	Proporciona una colección de elementos que proporciona funciones para consultar los formularios disponibles para el usuario actual. Use el método navigate para cerrar el formulario actual y abrir otro diferente.
navigation	No contiene ningún método. Proporciona acceso a elementos de navegación a través de la colección de elementos. Para obtener más información, vea la siguiente sección sobre colecciones.
process	Proporciona métodos para interactuar con el control del flujo de proceso de negocio en un formulario.

Más información: formContext.ui

Colecciones en el modelo de objeto formContext

La siguiente tabla describe las colecciones en el modelo de objetos Xrm. Para obtener información sobre los métodos disponibles para colecciones en general, vea Colecciones (referencia de la API de cliente).

Colección	Descripción
atributos	Dos objetos contienen una colección de columnas: - La colección formContext.data.attributes proporciona acceso a columnas no enlazadas a tablas. - La colección formContext.data.entity.attributes proporciona acceso a cada columna de tabla que está disponible en el formulario. Solo las columnas agregadas al formulario están disponibles.
controles	Tres objetos contienen una colección de controles: - formContext.ui.controls: proporciona acceso a cada control presente en el formulario. - formContext.data.entity.attribute.controls: debido a que una columna puede tener más de un control en el formulario, esta colección proporciona acceso a cada uno de ellos. Esta colección contiene solo un elemento a menos que se agreguen varios controles para la columna al formulario. - formContext.ui.tabs.sections.controls: esta colección solo contiene los controles que se encuentran en la sección.
formContext.data.process.stages y formContext.data.process.steps	Proporciona acceso a una colección de etapas y pasos en un flujo de proceso de negocio. También permiten agregar o quitar elementos de la colección.
formContext.ui.formSelector.items	Cuando se proporcionan varios formularios para una tabla, puede asociar cada formulario a roles de seguridad. Cuando los roles de seguridad asociados a un usuario les permiten ver más de un formulario, la colección formContext.ui.formSelector.items proporciona acceso a cada definición del formulario disponible para ese usuario.
formContext.ui.navigation.items	La colección formContext.ui.navigation.items proporciona acceso a elementos de navegación que se definen mediante el área de navegación del editor de formularios. Los usuarios pueden desplazarse a ellos mediante la barra de comandos.
formContext.ui.quickForms	Proporciona métodos para acceder a todos los controles de vista rápida y sus controles constituyentes en los formularios.
formContext.ui.tabs	Puede organizar cada formulario mediante una o varias pestañas. Esta colección proporciona acceso a cada una de estas pestañas.
formContext.ui Tab.secciones	Puede organizar cada pestaña de formulario usando una o varias secciones. La colección sections de la pestaña proporciona acceso a cada una de estas secciones. Debe definir la pestaña que contiene la sección deseada o iterar a través de cada pestaña para encontrar la sección relevante.

Artículos relacionados

getFormContext method
getGlobalContext method
getAttribute method
getControl method
Métodos del contexto de ejecución

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).