Xrm.Utility（客户端引用）

 

发布日期： 2016年11月

适用于： Dynamics CRM 2015

Xrm.Utility 对象为与当前页不直接相关的有用函数提供容器。

这些函数可用于支持脚本的每个应用程序页面。 您可以将他们用于窗体脚本或功能区命令。 对于 HTML Web 资源，当包括 ClientGlobalContext.js.aspx 页面时，这些资源可用。 有关详细信息，请参阅GetGlobalContext function and ClientGlobalContext.js.aspx（客户端引用）。

Functions

• 对话框
  使用 alertDialog 和 confirmDialog 向用户显示消息，并根据响应设置要执行的代码。 这些函数必须与 适用于平板电脑的 Microsoft Dynamics CRM 联用，以取代 window.alert 和 window.confirm 方法。

• isActivityType
  确定实体是否为活动实体。

• openEntityForm
  打开实体窗体。

• openQuickCreate
  对于 Microsoft Dynamics CRM Online 2015 更新 1 或更高版本，使用此函数可以打开新快速创建窗体。 您可以使用此函数设置使用属性映射或特定属性的默认值。 如果用户保存记录，可捕获到创建的记录的引用。

• openWebResource
  打开 HTML Web 资源。

对话框

有两类对话：alertDialog 和 confirmDialog。 包含它们是为了与脚本配合使用来处理 适用于平板电脑的 Microsoft Dynamics CRM。适用于平板电脑的 CRM 将不允许使用 JavaScript 函数，因为该函数阻止 window.alert 和 window.confirm 之类代码流。 如果您需要向用户显示消息，请使用这些方法取代其他方法。 主要差别是这些方法不会阻止代码，直到用户关闭这些方法。 这些方法包含回调函数参数，以根据用户响应指示应执行的代码。

备注

在 适用于平板电脑的 Microsoft Dynamics CRM 中，任何使用 window.alert 的方法均将被替代为使用 Xrm.Utility.alertDialog，且无需回调。 这将显示消息，但不会阻止代码的执行，如 window.alert 一样。适用于平板电脑的 CRM 中从 window.alert 到 Xrm.Utility.alertDialog 的映射已弃用，将在下一主要发行版中删除。 您应将迁移拥有的任何代码，以使用 Xrm.Utility.alertDialog 而不是 window.alert。

alertDialog

显示包含一个已定义应用程序消息的对话框。

Xrm.Utility.alertDialog(message,onCloseCallback)

• 参数

  客户	Type	必填	说明
  消息	字符串	是	此消息文本将显示于对话中。
  onCloseCallback	函数	否	当单击“确定”按钮时，将执行此函数。

• 备注
  本方法仅用于 更新的实体。

confirmDialog

显示包含可选消息以及“确定”和“取消”按钮的确认对话框。

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

• 参数

  客户	Type	必填	说明
  消息	字符串	是	此消息文本将显示于对话中
  yesCloseCallback	函数	否	当单击“确定”按钮时，将执行此函数。
  noCloseCallback	函数	否	当单击“取消”按钮时，将执行此函数。

• 备注
  本方法仅用于 更新的实体。

isActivityType

确定实体是否为活动实体。

Xrm.Utility.isActivityType(entityName)

• 参数

  客户	Type	必填	说明
  entityName	字符串	是	实体的 logicalName。

• 返回值

  Type	说明
  Boolean	如果是活动实体，则为 True；反之，则为 false。

openEntityForm

使用您作为参数设置的选项打开新的或现有的实体记录的实体窗体。

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

• 参数

  客户	Type	必填	说明
  名称	字符串	是	实体的逻辑名称。
  id	字符串	否	窗体中要打开的唯一标识符或记录的字符串表示形式。 如果未设置，则打开窗体以创建新记录。
  参数	对象	否	将额外的参数传递到窗体的词典对象。 无效的参数将导致出现错误。 有效的额外查询字符串参数是： 窗体 id：当多个窗体可用时，设置要使用的主窗体的 id 值。 参数为 formid。 默认字段 id：设置新记录窗体的默认值。 有关详细信息，请参阅使用传递给窗体的参数设置字段值。 Main.aspx 页面的查询字符串参数 中介绍的 navbar 和 cmdbar 参数。 自定义查询字符串参数：窗体可以配置为接受自定义查询字符串参数。 有关详细信息，请参阅配置窗体以接受自定义查询字符串参数。
  windowOptions	对象	否	对于 Microsoft Dynamics CRM Online 2015 更新 1 或更高版本，在 Web 应用程序中使用此可选参数可以控制窗体如何打开。 您可以通过传递布尔 openInNewWindow 属性设置为 true 的词典对象在新窗口中打开一个窗体。 此参数在 适用于平板电脑的 CRM 和 适用于手机的 CRM 中被忽略。

• 备注
  使用此函数帮助确保某些情况下不提示用户登录。

• 示例
  使用默认窗体，打开新的客户记录

  Xrm.Utility.openEntityForm("account");
  

  使用默认窗体，打开现有客户记录

  Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");
  

  打开具有特定窗体和设置默认值的新客户类型

  var parameters = {};
  parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
  parameters["name"] = "Test";
  parameters["telephone1"] = "(425) 555-1234";
  Xrm.Utility.openEntityForm("account", null, parameters);
  

  在新窗口中使用默认窗体，打开新的客户记录

  var windowOptions = {
   openInNewWindow: true
  };
  Xrm.Utility.openEntityForm("account",null,null,windowOptions);
  

openQuickCreate

对于 Microsoft Dynamics CRM Online 2015 更新 1 或更高版本，使用此函数可以打开新快速创建窗体。 您可以使用此函数设置使用属性映射或特定属性的默认值。 如果用户保存记录，可捕获到创建的记录的引用。

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

• 参数

  客户	Type	必填	说明
  entityLogicalName	字符串	是	待创建实体的逻辑名称。
  createFromEntity	查找	否	指定将根据映射的属性值提供默认值的记录。 查找对象具有以下 String 属性： entityType：实体的逻辑名称。 id：记录的 GUID 值的字符串表示形式。 name：记录的主属性值。
  参数	对象	否	将额外的查询字符串参数传递到窗体的词典对象。 无效的查询字符串参数将导致出现错误。 有效的额外查询字符串参数是： 默认字段 id：设置新记录窗体的默认值。 有关详细信息，请参阅使用传递给窗体的参数设置字段值。 自定义查询字符串参数：窗体可以配置为接受自定义查询字符串参数。 有关详细信息，请参阅配置窗体以接受自定义查询字符串参数。
  successCallback	函数	否	当创建记录时要调用的函数。 此函数作为参数传递对象。 此对象包含一个 savedEntityReference 属性并带有以下属性以识别创建的记录： entityType：实体的逻辑名称。 id：记录的 GUID 值的字符串表示形式。 name：创建的记录的主属性值。
  errorCallback	函数	否	当操作失败时调用的函数。 将传递具有以下属性的对象： errorCode：Number。 错误代码。 消息: String。 本地化的错误消息。

• 备注
  此函数只能用于 Microsoft Dynamics CRM Online 2015 更新 1 或更高版本。

  Web 应用程序中最多允许有 10 个嵌套快速创建窗体。 如果超出此限制，该函数将打开完整的实体窗体，而不是快速创建窗体。

• 示例
  当此代码在客户实体窗体中运行时，快速创建窗体将创建将默认名称设置为包括上级单位名称的新下级单位。

  var thisAccount = {
      entityType: "account",
      id: Xrm.Page.data.entity.getId()
  };
  var callback = function (obj) {
      console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
  }
  var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
  Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
      console.log(error.message);
  });
  

  当此代码使用浏览器开发人员工具（F12 工具）运行时，以下表示在名为“A. Datum Corporation (sample)”的客户上下文中运行时向控制台的输出，用户不会更改为新的下级单位设置的默认名称。

  Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}
  

openWebResource

打开 HTML Web 资源。

备注

此函数无法与 适用于平板电脑的 Microsoft Dynamics CRM 联用。

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

• 参数

  客户	Type	必填	说明
  webResourceName	字符串	是	要打开的 HTML Web 资源的名称。
  webResourceData	字符串	否	传递到数据参数的数据。
  宽度	编号	否	打开窗口的宽度（单位：像素）。
  高度	编号	否	打开窗口的高度（单位：像素）。

• 返回值
  窗口对象。

• 备注
  HTML Web 资源可以接受 将参数传递到 Web 资源 中介绍的参数值。 该函数仅供传入可选数据参数。 若要传递其他有效参数的值，则必须将他们追加到 webResourceName 参数。

• 示例
  打开名为“new_webResource.htm”的 HTML Web 资源

  Xrm.Utility.openWebResource("new_webResource.htm");
  

  打开包含数据参数的单个数据项的 HTML Web 资源

  Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
  

  打开通过数据参数传递多个传的 HTML Web 资源

  var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
  Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
  

  备注

  这些值必须通过 HTML Web 资源中的数据参数值进行提取。 有关详细信息，请参阅示例：通过 Data 参数向 Web 资源传递多个值。
  打开具有 HTML Web 资源预期参数的 HTML Web 资源

  Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");
  

  有关详细信息，请参阅将参数传递到 Web 资源。

  打开 HTML Web 资源，设置高度和宽度

  Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);
  

另请参阅

客户端编程引用
使用 URL 打开窗体、视图和对话
使用传递给窗体的参数设置字段值
配置窗体以接受自定义查询字符串参数
脚本即时引用的表单
为 Microsoft Dynamics CRM 2015 窗体编写代码
使用 Xrm.Page 对象模型

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