上下文对象

已完成

当创建事件处理程序和使用客户端脚本 API 时,您应该了解可用的上下文对象以及如何使用它们。 上下文对象旨在为您提供有关代码的执行上下文的信息。 此上下文可确保您无需在逻辑中对信息进行硬编码。 上下文允许您创建更通用的函数,并使您的函数对正在使用的 UI 组件的特定布局不那么敏感。

执行上下文

当您注册事件处理程序时,可以将执行上下文作为第一个参数传递。 当您使用窗体属性注册事件处理程序时,这是您可以启用的选项。 下图显示了注册 OnLoad 处理程序和启用执行上下文。

通常,当您使用窗体属性注册事件处理程序时,始终选择本选项是一个好主意。 当您使用代码注册事件处理程序时,将自动选择本选项。

将执行上下文作为第一个参数的函数定义将如下所示:

执行上下文的最常见用途是检索窗体和网格上下文。 此上下文的另一个有用方法是 getEventSource。 事件源返回对触发事件的对象的引用。 此对象允许您编写通用处理程序,用于在运行时查询事件源以找出触发事件的控件。 当您要编写一种方法来为多个控件注册事件,而不是为每个控件创建单独的事件处理程序时,此对象可能很有用。 例如,如果多个字段都有一个 OnChange 事件,则可以使用 getEventSource 来确定哪个字段触发了该事件并相应地使用它。

窗体上下文

客户端 API 窗体上下文 (formContext) 引用运行当前代码的窗体或窗体上的项目的,例如快速视图控件或可编辑网格中的行。 您可以使用 getFormContext 函数从执行上下文中检索 formContext 对象。

之前,使用全局 Xrm.Page 对象访问项目或窗体。 但是,在最新版本中,Xrm.Page 对象已弃用。 而应使用执行上下文对象中的 getFormContext 方法,以获取对相应窗体或窗体上的项目的引用。 因此,不是编写如下所示的代码。

var firstName = Xrm.Page.getAttribute("firstname").getValue();

您应使用 formContext 编写以下代码。

var formContext = executionContext.getFormContext();

var firstName = formContext.getAttribute("firstname").getValue();

您可以了解有关 Xrm.Page 弃用的详细信息。

下图是窗体上下文中可用的属性和方法的高级别概述:

数据对象

数据对象 (formContext.data) 旨在用于窗体中的任何表以操作数据。

下表总结了每个数据对象的对象和集合:

名称 描述
属性 窗体上的非实体数据的集合。 本集合中的项目与实体上的属性集合具有相同的数据类型,但请务必注意,它们不是窗体表的属性。
实体 用于检索特定于页面上显示的行、保存方法的信息以及窗体上包含的所有属性集合的方法。 属性数据仅限于由窗体上的字段与实体配置中可用的所有字段表示的属性。 有关详细信息,请参阅 formContext.data.entity。
流程 要与窗体上的业务流程流交互的对象和方法。 有关详细信息,请参阅 formContext.data.process。

UI 对象

UI 对象 (formContext.ui) 提供这两种方法,用于检索有关用户界面的信息以及窗体或网格的多个子组件的集合。

下表总结了每个 UI 对象的对象和集合:

名称 描述
控件 页面上所有控件的集合。 有关集合、控件和集合中的控件对象的信息,请参阅集合。
FormSelector 获取有关窗体的信息的方法。 使用 formSelector.getCurrentItem 方法检索有关当前正在使用的窗体的信息。 使用 formSelector.items 集合返回有关用户可用的所有窗体的信息。
导航 页面上所有导航项目的集合。 有关集合中的项目的信息,请参阅 formContext.ui.navigation 项目。 导航在适用于平板电脑的 Microsoft Dynamics 365 中不可用。 为了自动执行整个应用程序导航,我们倾向于使用 Xrm.Navigation 命名空间。
流程 要与窗体上的业务流程流控件(例如设置其可见性)交互的对象和方法。 有关详细信息,请参阅 formContext.ui.process。
QuickForms 窗体上所有快速视图控件的集合。 有关详细信息,请参阅 formContext.ui.quickForms。
选项卡 页面上所有选项卡的集合。 有关集合中的项目的信息,请参阅 formContex.ui.tabs。

通常使用数据对象(而不是 UI 对象)来获取或设置表列值。 数据对象只有一个用于表示表列值的属性。 通过比较,UI 对象在窗体上的同一表列中有多个控件,每个控件都具有对属性的引用。 因此,数据对象更易于操作属性值,而 UI 对象更易于使用在窗体上表示该属性的控件。

在脚本中使用上下文对象可以使它们更灵活地在窗体上和在客户端 API 中进行更改。