Contexto de formulario del cliente en la API

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

Anteriormente, utilizó el objeto global Xrm.Page para representar un formulario o un elemento del formulario. En la versión más reciente, el objeto Xrm.Page está en desuso. En su lugar, use el método getFormContext del objeto de contexto de ejecución pasado para devolver una referencia al formulario adecuado o a un elemento del formulario.

Importante

En desuso, Microsoft pretende quitar una característica o funcionalidad de una futura versión principal de aplicaciones controladas por modelos. La característica o la capacidad seguirá funcionando y será totalmente compatible hasta que se quite oficialmente. Microsoft hace un anuncio público al menos seis meses antes de la eliminación, en la documentación, en el blog oficial y en muchos otros lugares.

Para mantener la compatibilidad con versiones anteriores con scripts existentes, se sigue admitiendo el uso del objeto Xrm.Page como acceso estático al contexto del formulario principal y no se quitará tan pronto como otros métodos de API de cliente enumerados en la sección Desaprobación de la API cliente. Use el nuevo objeto formContext en lugar del objeto Xrm.Page en el código destinado a la versión 9.0 o posterior siempre que sea posible. Además, mediante el uso del objeto formContext , puede crear controladores de eventos comunes que pueden funcionar en un formulario o en una cuadrícula editable en función de dónde se llame. Para obtener más información, consulte getFormContext (referencia de 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. Para obtener más información, vea Contexto de formulario y cuadrícula en acciones de la cinta de opciones.

Nota

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

Usar el objeto formContext en lugar del objeto Xrm.Page

Es fácil convertir código existente que usa 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);
}

Este es el script actualizado que utiliza el contexto de ejecución proporcionado para recuperar el objeto formContext en lugar de utilizar 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

Seleccione la opción Pasar contexto de ejecución como primer parámetro en el cuadro de diálogo Propiedades del controlador al definir los controladores de eventos para usar el objeto formContext . Para más información, consulte Contexto de ejecución de la API de 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	Descripción
attributes	Recopilación de datos no tabulares 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 sobre la interfaz de usuario, además de colecciones para varios subcomponentes del formulario o cuadrícula. Contiene los siguientes objetos:

Objecto	Descripción
formSelector	Proporciona una colección de elementos que puede usar para consultar los formularios disponibles para el usuario actual. Use el navigate método para cerrar el formulario actual y abrir uno 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

En la tabla siguiente se describen las colecciones del 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 podría 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 al formulario varios controles para la columna. - 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 navegan a estos elementos mediante la barra de herramientas.
formContext.ui.quickForms	Proporciona métodos para obtener acceso a todos los controles de vista rápida y sus controles componentes 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 recorrer todas las pestañas para encontrar la sección relevante.

Artículos relacionados

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