Contexto de formulario de la API del clienteClient API form context

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.The Client API form context (formContext) provides a reference to the form or to an item on the form, such as, a quick view control or a row in an editable grid, against which the current code is executed.

Anteriormente, el objeto Xrm.Page global se usaba para representan un formulario o un elemento en el formulario.Earlier, the global Xrm.Page object was used to represent a form or an item on the form. 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.With the latest version, the Xrm.Page object is deprecated, and you should use the getFormContext method of the passed in execution context object to return reference to the appropriate form or an item on the form.

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.Deprecated means that we intend to remove a feature or capability from a future major release of model-driven apps; the feature or capability will continue to work and is fully supported until it is officially removed. 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.A public announcement here in the documentation, on the official blog, and in many other places will be made at least six months before removal.

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 .Use of the Xrm.Page object as a static access to the primary form context is still supported to maintain backward compatibility with the existing scripts, and won’t be removed as soon as some other client API methods listed in the Client API deprecation section. 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.We recommend that you use the new formContext object instead of the Xrm.Page object in your code targeting version 9.0 or later where possible. 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.Also, using the formContext object enables you to create common event handlers that can operate either on a form or in an editable grid depending on where its called. Más información: getFormContext (referencia de la API de cliente).More information: getFormContext (Client API reference).

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.Getting the formContext object for JavaScript functions for ribbon actions is different from how you get it in form scripting. Más información: Formulario y cuadrícula en las acciones de la cinta.More information: Form and grid context in ribbon actions.

Uso del objeto formContext en lugar del objeto Xrm.PageUsing the formContext object instead of the Xrm.Page object

Es muy fácil convertir un código existente con Xrm.Page para usar el nuevo objeto formContext.It's easy to convert existing code with Xrm.Page to use the new formContext object. Por ejemplo, considere el siguiente script que utiliza el objeto Xrm.Page:For example, consider the following script that uses the Xrm.Page object:

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

Presentamos el script actualizado que utiliza lo pasado en el contexto de ejecución para recuperar el objeto formContext en lugar de utilizar el objeto Xrm.Page estático:Here is the updated script that uses the passed in execution context to retrieve the formContext object instead of using the static Xrm.Page object:

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.You must remember to select the Pass execution context as first parameter option in the Handler Properties dialog while defining your event handlers to use the formContext object. Más información: Contexto de ejecución de la API del clienteMore information: Client API execution context

Modelo de objetos formContextformContext object model

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.Use the data and ui objects under the formContext object to programmatically manipulate data and user interface elements in model-driven apps.

Modelo de objetos formContext

objeto de datosdata object

Proporciona acceso a los datos de entidad y los métodos para administrar los datos en el formulario así como en el control de flujo de proceso de negocio.Provides access to the entity data and methods to manage the data in the form as well as in the business process flow control. Contiene los siguientes objetos:Contains the following objects:

ObjetoObject DescripciónDescription
entidadentity Proporciona métodos para recuperar información específica del registro que se muestra en la página, el método y una recopilación de todos los atributos incluidos en el formulario.Provides methods to retrieve information specific to the record displayed on the page, the save method, and a collection of all the attributes included on the form
procesoprocess Proporciona métodos para recuperar propiedades de un flujo de proceso de negocio.Provides methods to retrieve properties of a business process flow.

También proporciona una recopilación de atributos para obtener acceso a un control no vinculado a la entidad.It also provides an attributes collection for accessing non-entity bound control. Consulte la sección Recopilaciones en el modelo de objetos formContext más adelante en este tema.See the Collections in the formContext object model section later in this topic.

Más información: formContext.dataMore information: formContext.data

objeto uiui object

Proporciona métodos para recuperar información acerca de la interfaz de usuario, además de recopilaciones para varios subcomponentes del formulario o la cuadrícula.Provides methods to retrieve information about the user interface, in addition to collections for several sub components of the form or grid. Contiene los siguientes objetos:Contains the following objects:

ObjetoObject DescripciónDescription
formSelectorformSelector Proporciona una recopilación de elementos que proporciona funciones para consultar los formularios disponibles para el usuario actual.Provides an items collection that provides capabilities to query the forms available for the current user. Use el método navigate para cerrar el formulario actual y abrir otro diferente.Use the navigate method to close the current form and open a different one.
navegaciónnavigation No contiene ningún método.Does not contain any methods. Proporciona acceso a elementos de navegación a través de la recopilación de elementos.Provides access to navigation items through the items collection. Para obtener más información, vea la siguiente sección sobre recopilaciones.See the next section on collections for more information.
procesoprocess Proporciona métodos para interactuar con el control del flujo de proceso de negocio en un formulario.Provides methods to interact with the business process flow control on a form.

Más información: formContext.uiMore information: formContext.ui

Recopilaciones en el modelo de objeto formContextCollections in the formContext object model

La siguiente tabla describe las recopilaciones en el modelo de objetos Xrm.The following table describes the collections in Xrm object model. Para obtener información sobre los métodos disponibles para recopilaciones en general, vea Recopilaciones (referencia de la API de cliente).For information about the methods available for collections in general, see Collections (Client API reference).

RecopilaciónCollection DescripciónDescription
atributosattributes Dos objetos contienen una recopilación de atributos:Two objects contain an attributes collection:

- La recopilación formContext.data.attributes proporciona acceso a atributos no vinculados a entidad.- formContext.data.attributes collection provides access to non-entity bound attributes.

- La recopilación formContext.data.entity.attributes proporciona acceso a cada atributo de entidad que esté disponible en el formulario.- formContext.data.entity.attributes collection provides access to each entity attribute that is available on the form. Solo los atributos que correspondan a los campos que se agregan al formulario están disponibles.Only those attributes that correspond to fields added to the form are available.
controlescontrols Tres objetos contienen una recopilación de controles:Three objects contain a controls collection:

- formContext.ui.controls: proporciona acceso a cada control presente en el formulario.- formContext.ui.controls: Provides access to each control present on the form.

- formContext.data.entity.attribute.controls: dado que un atributo puede tener más de un control en el formulario, esta recopilación proporciona acceso a cada uno de ellos.- formContext.data.entity.attribute.controls: Because an attribute may have more than one control on the form, this collection provides access to each of them. Esta recopilación contendrá solo un elemento a menos que se agreguen varios controles para el atributo al formulario.This collection will contain only one item unless multiple controls for the attribute are added to the form.

- formContext.ui.tabs.sections.controls: esta recopilación solo contiene los controles que se encuentran en la sección.- formContext.ui.tabs.sections.controls: This collection only contains the controls found in the section.
formContext.data.process.stages y formContext.data.process.stepsformContext.data.process.stages and formContext.data.process.steps Proporciona acceso a una recopilación de etapas y pasos en un flujo de proceso de negocio.Provides access to stages and steps collection in a business process flow. También permiten agregar o quitar elementos de la recopilación.These also allow for adding and removing of items from the collection.
formContext.ui.formselector.itemsformContext.ui.formselector.items Cuando se proporcionan varios formularios para una entidad, puede asociarlos con roles de seguridad.When multiple forms are provided for an entity, you can associate each form with security roles. Cuando los roles de seguridad asociados a un usuario les permiten ver más de un formulario, la recopilación formContext.ui.formSelector.items proporciona acceso a cada definición del formulario disponible para ese usuario.When the security roles associated with a user enable them to see more than one form, the formContext.ui.formSelector.items collection provides access to each form definition available to that user.
formContext.ui.navigation.itemsformContext.ui.navigation.items La recopilació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.The formContext.ui.navigation.items collection provides access to navigation items that are defined using the navigation area of the form editor. Los usuarios pueden desplazarse a ellos mediante la barra de comandos.People navigate to these using the command bar.
formContext.ui.quickFormsformContext.ui.quickForms Proporciona métodos para obtener acceso a todos los controles de vista rápida y los controles que los componen en los formularios de Customer Engagement.Provides methods to access all the quick view controls and its constituent controls on the Customer Enagagement forms. La recopilación Xrm.Page.ui.tabs proporciona acceso a cada una de estas pestañas.Xrm.Page.ui.tabs collection provides access to each of these tabs.
formContext.ui.tabsformContext.ui.tabs Puede organizar cada formulario mediante una o varias pestañas.You can organize each form by using one or more tabs. Esta recopilación proporciona acceso a cada una de estas pestañas.This collection provides access to each of these tabs.
formContext.ui.tabs.sectionsformContext.ui.tabs.sections Puede organizar cada pestaña de formulario usando una o varias secciones.You can organize each form tab by using one or more sections. La recopilación sections de la pestaña proporciona acceso a cada una de estas secciones.The tab sections collection provides access to each of these sections.

Método getFormContextgetFormContext method
Método getGlobalContextgetGlobalContext method
método getAttributegetAttribute method
Método getControlgetControl method
Métodos del contexto de ejecuciónExecution context methods