Contexto de formulario de la API de cliente

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. 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).

Nota:

Algunos puntos importantes que hay que recordar al trabajar con el contexto de formulario:

Modelo de objeto 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.

Captura de pantalla del modelo de objetos formContext que muestra los datos y los objetos ui y sus colecciones.

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:

Objeto 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 de flujo del 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:

Objeto 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 los 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 recorrer todas las pestañas para encontrar la sección relevante.

Usar el objeto formContext en lugar del objeto Xrm.Page

En el pasado, las personas usaron el objeto Xrm.Page global para representar un formulario o un elemento en el formulario. El objeto Xrm.Page estaba obsoleto en 2017. 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 significa que Microsoft tiene la intención de quitar una característica o capacidad de una futura versión principal de aplicaciones basadas en 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, el uso del objeto Xrm.Page como acceso estático al contexto principal de formulario todavía se admite 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. 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.

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);
}

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

  • Se actualizó por última vez el