为 Microsoft Dynamics 365 窗体编写代码

  • 项目

 

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

通过窗体编程，可以使用对窗体中发生的事件执行的 JavaScript 以多种方式与实体窗体进行交互。

本主题内容

何时使用窗体编程

使用窗体编程时要考虑的因素

管理库依赖项

编写执行良好的窗体脚本

不同的窗体表示

开发工具

何时使用窗体编程

Microsoft Dynamics 365 提供了众多控制业务流程的选择。 窗体编程便是一种选择。 但是注意您要有其他选项：业务规则。 业务规则为不了解 JavaScript 且不是开发人员的用户提供了在窗体中应用业务流程逻辑的方法。 有关详细信息，请参阅自定义指南主题：TechNet：创建和编辑业务规则。

窗体编程和业务规则的主要优势在于它们的即时性。 它们不需要将数据提交到服务器，因此在很多情况下可提供最佳性能。 因为允许人工交互，所以仍是最灵活的选择。

虽然业务规则具有好处（因为它们可以由非开发人员的用户创建并维护），但是它们具有一些限制，且不能用来替换窗体脚本。 窗体编程允许您实现使用业务规则无法完成的操作。

通常使用窗体编程执行的任务包括以下几项：

  • 数据验证：编辑数据时应尽可能执行数据验证。 窗体字段的定义将为您执行最常见的数据验证。 例如，针对电子邮件地址设置了格式的Single Line of Text字段不允许在其中输入无效值。

    可以使用窗体编程执行组织特有的其他数据验证。 例如，关于应该如何设置电话号码的格式或服务活动中Subject字段的最小长度，您的组织可能具有相应的具体规则。

  • 自动化：使用窗体脚本自动执行常见任务时可以显著提高生产效率。 可以设置依赖于在窗体中输入的数据的字段值，这样有助于用户在输入数据时节省大量时间。 使用窗体编程实现自动化非常有用，因为它允许用户验证标准流程在特定情况下是否有效。 用户在保存记录之前可以进行必要的调整。

  • 流程增强和实施：可以自定义要显示于窗体的数据或者窗体布局，以便针对组织所执行流程中的特定任务优化窗体。 可以使用窗体编程显示或隐藏特定窗体元素，或者打开为实体定义的不同窗体。 可以基于窗体或相关记录中存在的数据控制哪些字段是必需的。

    通过 Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新，您可以编写代码来控制显示在窗体顶部的业务流程。详细信息：编写业务流程脚本。

使用窗体编程时要考虑的因素

在窗体编程中应用的逻辑只能在与 Microsoft Dynamics 365 应用程序实体窗体交互的用户的浏览器中执行。 因此，不应该仅依赖通过窗体编程来启动或实施与数据有关的流程。 可以通过 Web 服务 API 或者窗体上下文外部的工作流来直接创建或更新记录。 窗体编程应该补充使用插件和流程应用的业务逻辑，以便通过任何方式创建或更新的所有记录将符合相同的流程。

可以将业务规则定义为在实体范围运行，以便在服务器上应用相同的逻辑，无论操作来自何处。详细信息：TechNet：创建和编辑业务规则

尽管窗体编程可以隐藏窗体字段以使用户无法查看或更新某些实体数据，但这并不是实施安全性要求的完整解决方案。 用户可以使用各种方法（例如“高级查找”）查看窗体中不可见的实体数据。详细信息：Microsoft Dynamics 365 的安全模型

管理库依赖项

作为性能优化，Microsoft Dynamics 365 窗体异步并行加载 JavaScript Web 资源。 这意味着针对窗体配置了库的订单不能保证库将完全下载并初始化，除非其他库可以尝试使用在其中定义的一个对象。

如果您有依赖其他库的代码需要完全下载并初始化，最直接的方法是使用库代码下的您的代码将两个库合并为一个 JavaScript Web 资源。 较复杂的方法是使用库（如 head.js 或 require.js）来控制如何加载单独的库。

编写执行良好的窗体脚本

当编写窗体脚本时，请使用以下做法帮助达到最佳性能：

  • 避免包含不必要的 JavaScript Web 资源库
    向窗体中添加的脚本越多，用于下载脚本的时间也会越多。 通常，脚本首次下载后会缓存在浏览器中，但首次查看窗体时的性能通常会形成重要的印象。

    对于特定示例，因为您要使用 XMLHttpRequest，因此不要在窗体脚本中包括 jQuery。 当 jQuery 提供很多人很熟悉的 $.ajax 函数来执行这些请求时，它是开发人员的首选项，不是必选项。 可以使用 Microsoft Dynamics 365 支持的所有浏览器中的本机 XMLHttpRequest 对象来执行这些请求。详细信息：jQuery 的使用

  • 避免在 Onload 事件中加载所有脚本
    如果您有仅支持字段的 OnSave 事件或 OnChange 事件的代码，请确保使用事件处理程序为这些事件（而不是 OnLoad 事件）设置脚本库。 这样可以推迟加载这些库，从而提高窗体加载时的性能。

    为方便起见，不建议使用 OnLoad 事件处理程序中的 addOnChange 方法。 虽然此方法可减少添加事件处理程序所需的步骤数，但它将导致窗体加载速度更慢。

  • 使用折叠选项卡来推迟加载 Web 资源
    当折叠的选项卡中的分区中包括了 Web 资源或 IFRAME 时，在选项卡折叠的情况下不会加载它们。 它们会在选项卡展开时加载。 当选项卡状态发生变化时，会发生 TabStateChange 事件。 支持折叠的选项卡中的 Web 资源或 IFRAME 所需的任何代码都可以使用 TabStateChange 事件的事件处理程序，从而减少本来必须在 OnLoad 事件中发生的代码。

  • 设置默认可见性选项
    避免在隐藏窗体元素的 OnLoad 事件中使用窗体脚本。 请为可能隐藏的窗体元素设置默认可见性选项，以便在加载窗体时使其默认不可见。 然后，在 OnLoad 事件中使用脚本来显示您希望显示的窗体元素。

不同的窗体表示

表现窗体有几种不同的方法。 它们影响可用于每种方法的代码类型或可用事件。

旧窗体呈现

在 Microsoft Dynamics CRM Online 2015 更新 1 和 Dynamics 365（内部部署）中，新系统设置：引入“使用旧窗体呈现”。 在这些版本中，窗体呈现已经改进，页面内部结构也进行了更改。 因此，使用了不支持方法的窗体脚本将无法访问之前版本可用的 DOM 的元素。 如果在升级到这些版本后您遇到新错误，请尝试应用此设置，查看错误是否消失。 如果是这样，导致这些错误的脚本有一个好机会使用不支持的方法。

您可以设置“使用旧窗体呈现”以留出时间解决这些问题，但是，您将体验不到新窗体呈现基础结构提供的性能改进。

备注

“使用旧窗体呈现”设置将在下一主要发行版中移除。 届时，所有窗体脚本均必须使用新窗体呈现。

更新的实体

所有自定义实体和某些系统实体具有更新的用户界面，包括使用命令栏和新窗体 API。 下表中列出更新的系统实体：

客户​​

约会

市场活动

市场活动项目

市场活动​​响应

案例

竞争对手

联系人

合同

合同子项 (ContractDetail)

电子邮件

权利

权利模板

传真

发票

发票产品 (InvoiceDetail) *

潜在​​顾客

信件

市场营销列表

商机

商机产品

订单

订单产品 (SalesOrderDetail) *

电话​​联络

位置

价目表项

产品

产品关联

产品关系 (ProductSubstitute)

队列

快速市场活动（批量操作）

报价单

报价单产品 (QuoteDetail) *

定期约会 (RecurringAppointmentMaster)

销售宣传资料

SLA

SLA KPI 实例

社交活动

社区个人资料

任务

团队

用户

* 这些实体已在 CRM Online 2016 更新 1 和 Dynamics 365 Service Pack 1（内部部署）中更新。

备注

某些更新的实体包括复合属性。 它们需要引起特别注意。详细信息：为复合属性编写脚本。

更新的实体窗体也可能包含为注释、活动和公告（如果实体中启用了这些选项）提供访问路径的协作控件。 Xrm.Page 对象不可以访问协作控件。 如果想要查看或隐藏包含协作控件的节元素，可以使用脚本对其进行访问。

更新实体的窗体编程方法和 PreSearch 事件

下表列出了仅供更新实体使用的新窗体编程方法。

方法

说明

Xrm.Page.context.客户。getClient

返回一个值以指明执行脚本的客户端。

Xrm.Page.context.客户。getClientState

返回一个值以指明客户端的状态。

Xrm.Page.context.getUserName

返回当前用户的名称。

Xrm.Page.data.entity.getPrimaryAttributeValue

获取实体的主要属性值的字符串。

Xrm.Page.data.刷新​​

异步刷新窗体的数据，而不重新加载页面。

Xrm.Page.data.保存

使用用于设置要在保存操作完成后执行的回调函数的选项，异步保存记录。

Xrm.Page.data.entity attribute.getIsPartyList

确定查找属性是否表示 PartyList 查找。

Xrm.Page.ui control.clearNotification

删除已为控件显示的消息。

Xrm.Page.ui control.setNotification

在控件旁显示消息，以指示数据无效。

Xrm.Page.ui.clearFormNotification

使用此方法删除窗体级别通知。

Xrm.Page.ui.setFormNotification

使用此方法显示窗体级别通知。

Xrm.Page.ui control.addCustomFilter

使用 fetchXml 将附加筛选器添加到查找中显示的结果。 每个筛选器将作为“AND”条件与任何以前添加的筛选器合并。

Xrm.Page.ui control.setShowTime

指定日期控件是否应显示日期的时间部分。

Xrm.Utility.alertDialog

显示包含回调函数的无阻塞警报对话框。

Xrm.Utility.confirmDialog

根据用户单击的按钮，显示包含不同回调的无阻塞确认对话框。

PreSearch 事件

仅在设置查找值时搜索对话框打开之前显示新 PreSearch 事件。 此事件没有用于在应用程序中设置事件处理程序的用户界面，它只能使用 Xrm.Page.ui control.addPreSearch 方法设置。 在 addCustomFilter、addCustomView 和 setDefaultView 方法中使用此事件，以便在用户寻找作为查找字段的值的视图时控制开启的视图。

使用经典窗体的实体

不更新的系统实体使用经典窗体表示。 在 CRM 2011 中，这些实体的窗体继续使用功能区，且无权访问此版本中添加的窗体 API。 下表中列出了这些实体：

地址

文章

文章注释

批量删除操作

业务部门

连接

折扣

折扣表

文档位置

电子邮件附件

追随

目标

目标度量

导入的源文件

发票产品

订单产品

价目表

队列项

报价单产品

汇总字段

汇总查询

已保存的视图

服务

服务活动

SharePoint 网站

场所

区域

单位

计价单位组

为适用于平板电脑的 Dynamics 365 启用的实体

只有选择的系统实体和自定义实体可供使用 适用于平板电脑的 Microsoft Dynamics 365 显示。 以下系统实体具有可在 适用于平板电脑的 Dynamics 365 中编辑的窗体。

客户​​

活动

约会

案例​​

竞争对手

连接

联系人​​

潜在顾客

注释

商机​​

商机产品

电话联络

队列项

社交活动

社区个人资料

任务

由于 适用于平板电脑的 Dynamics 365 没有与 Web 应用程序中的窗体相同的行为，因此某些 API 不可用。 例如，在无法展开或折叠的 适用于平板电脑的 Dynamics 365 选项卡中，选项卡 TabStateChange 事件 不会发生，Xrm.Page.ui tab.setDisplayState 无法用于展开或折叠选项卡。详细信息：编写和调试适用于手机和平板电脑的 Dynamics 365 的脚本。

开发工具

使用新工具后，编写 Dynamics 365 窗体的 JavaScript 的体验将更好。

使用优秀的创作工具

因为 JavaScript 是一种解释语言，所以不需要特殊开发工具。JavaScript 只是文本，因此可以在应用程序或记事本之类的文本编辑器中进行编辑。 但是，使用创作工具时可以显著提高生产效率，该环境提供专门支持编辑 JavaScript 文件的功能，例如 Microsoft Visual Studio 和 Microsoft Visual Studio Express。 可以免费获取 Visual Studio 社区 2013。

使用浏览器开发人员工具

所有现代浏览器均提供可进行脚本调试的内置工具。 这些工具在为 Dynamics 365 窗体编写脚本时也可能提供巨大帮助。 这些开发人员工具经常被称为 F12 工具，因为它是用来打开这些工具的钥匙。 有关使用这些工具的信息，请参阅 W3Schools JavaScript 调试。

使用开发人员工具可以验证您将作为脚本 Web 资源上载的脚本语法。 通过这些工具还可以进一步了解您根据其编程的对象模型。 例如，在您编写访问窗体特定对象的代码时，您通常需要按名称访问它们。 使用开发人员工具的控制台可以询问 Xrm.Page 对象模型，然后获取您要访问的属性或控件的名称，而不是在窗体编辑器中查找对象的名称。 例如，如果要按名称访问特定子网格控件，您可以使用浏览器开发人员工具控制台编写以下代码。

Xrm.Page.ui.controls.get(
function(ctrl,i){
 if(ctrl.getControlType() == "subgrid")
  console.log(ctrl.getName()
  );
});

所有子网格控件的名称将被编写到控制台的输出窗格中。 此脚本利用该功能将一个匿名代理函数传递到集合中的 获取 方法以及在对象中找到的其他方法，然后按类型进行筛选并返回对象名称，例如此示例中使用的 Xrm.Page.ui control.getControlType 和 Xrm.Page.ui control.getName。

重要

Dynamics 365 窗体由多个框架组成。 对于要在控制台中使用的代码，您必须选择正确的框架。 对于 Dynamics 365 Web 客户端窗体，请选择名为 ClientApiWrapper.aspx 的框架。 对于新的交互式服务中心客户端窗体，请选择名为 engagementhub.aspx 的框架。

下面给出了更多示例。

  • 显示窗体中所有属性的名称以及类型

    Xrm.Page.getAttribute(
function (att, i) {
 console.log(att.getName() + " : " + att.getAttributeType())
});

  • 显示选项集属性的有效选项值

    Xrm.Page.getAttribute(
function (att, i) {
 if (att.getAttributeType() == "optionset") {
  console.log(att.getName())
  var options = att.getOptions();
  var optionsLength = options.length;
  for (var i = 0; i < optionsLength; i++) {
   var option = options[i];
   console.log("   value: " + option.value + " Label: " + option.text)
  }
 }
});

另请参阅

在客户端上扩展 Microsoft Dynamics 365
使用 URL 打开窗体、视图、对话框和报表
脚本即时引用的表单
通过 Microsoft Dynamics 365 使用 JavaScript
Microsoft Dynamics 365 的 JavaScript 库
自定义 Microsoft Dynamics 365 应用程序
使用窗体和字段事件
使用 Xrm.Page 对象模型
编写和调试适用于手机和平板电脑的 Dynamics 365 的脚本
为复合属性编写脚本
编写业务流程脚本
编写子网格的脚本
使用执行上下文和窗体事件管道
在窗体上使用 IFRAME 和 Web 资源控件
Microsoft Dynamics 365 Web API（客户端 JavaScript）入门

Microsoft Dynamics 365

© 2017 Microsoft。 保留所有权利。 版权