Dynamics 365中的Client API form context (formContext)

适用于Dynamics 365 for Customer Engagement apps 9.x版本。

本文是一篇翻译，原文来源是微软官方文档。

本文链接：https://www.cnblogs.com/hhelibeb/p/11042391.html

概述

Client API form context (formContext)提供了对当前代码运行的上下文中的form或对form上的item的引用，比如，一个quick view控件或者一个可编辑grid中的行。

在早期版本，全局的Xrm.Page对象用于代表form或form中的item。在9.0版本中，Xrm.Page对象过时了，你应该使用被传入的运行上下文对象的getFormContext方法获取相应的from的引用。

注意：formContext对象允许你创建通用的事件处理器，根据调用位置来对form或可编辑grid进行操作。详见getFormContext (Client API reference)。从ribbon action的Javascript函数中获取formContext和从scripting中获取它的方式是不同的。更多信息：Form and grid context in ribbon actions.

使用formContext对象

以下是一段使用formContext对象的JS代码，通过传入的运行上下文（executionContext）获取formContext对象，

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

    var firstName = formContext.getAttribute("firstname").getValue(); 
    var lastName = formContext.getAttribute("lastname").getValue();
    console.log(firstName + " " + lastName);
}

（译注：省略了原文中有关过时的Xrm.Page对象的部分）

formContext 对象模型

formContext对象下包含data和ui对象，它们允许你通过编程方式操作数据和用户界面元素。

data对象

data对象可用于访问entity数据，也提供了管理form、business process flow控件中数据的方法。它包含以下对象：

Object	Description
entity	提供方法来根据页面的显示的记录检索信息，也提供了save方法、以及包含form中全部属性的集合。
process	提供方法检索business process flow的属性。

它也提供了一个用于访问非entity绑定的控件的属性集。详见文章的稍后部分的 formContext对象模型中的集合。

更多信息：formContext.data

UI对象

提供检索UI信息的方法，包含from或grid的某些子组件的集合。它包含以下对象：

Object	Description
formSelector	提供item集合，该集合可以用于查询对当前用户有效的form。可以使用navigate方法关闭当前form，并打开一个新的form。
navigation	不包含任何方法，提供通过item集合访问item的能力。参考下一节。
process	提供在form上与business process flow控件交互的方法。

更多信息：formContext.ui

formContext对象模型中的集合

下面的表格描述了Xrm对象模型中的集合。关于集合的一般可用方法的信息，参看Collections (Client API reference).。

Collection	Description
attributes	有2个对象包含attributes集合 - formContext.data.attributes: 用于访问非entity绑定属性。 - formContext.data.entity.attributescollection: 用于访问在form中可用的entity。只对与添加到form上的字段对应的属性可用。
controls	有3个对象包含controls集合 - formContext.ui.controls: 用于访问form中出现的控件。 - formContext.data.entity.attribute.controls: 因为一个属性也许会在表单上面有多个控件，该集合用于访问它们。如果没有为属性添加多个控件，那么这个集合只会包含1个item. - formContext.ui.tabs.sections.controls: 这个集合只包含在section中的控件。
formContext.data.process.stages formContext.data.process.steps	用于访问business process flow中的stage和step集合。可以从集合中添加和删除item。
formContext.ui.formselector.items	当一个entity有多个form的时候，可以通过安全角色关联这些form。当用户的安全角色允许他访问不止一个form时，该集合可以用于访问对于当前用户可用的各个form。
formContext.ui.navigation.items	The formContext.ui.navigation.itemscollection 用于访问通过form编辑器定义的导航项。用户通过command bar来访问那些导航项。
formContext.ui.quickForms	用于访问所有quick view控件和它在Customer Enagagement forms中的上级控件。
formContext.ui.tabs	可以通过一或多个tab来组织form。这个集合用于访问tab.
formContext.ui.tabs.sections	tab中可以包含一或多个section。该集合用于访问section。