Xrm.Utility（客户端引用）

 

发布日期： 2017年1月

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

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

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

Functions

• 对话框
  使用 alertDialog 和 confirmDialog 向用户显示消息，并根据响应设置要执行的代码。 这些函数必须与 Dynamics 365 移动客户端（电话和平板）连用，以取代 window.alert 和 window.confirm 方法。

• 本机设备功能（Dynamics 365 移动客户端）
  使用 getBarcodeValue 和 getCurrentPosition，以便使用移动设备的本机设备功能检索条形码值或设备的当前位置。

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

• openEntityForm
  打开实体窗体。

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

• openWebResource
  打开 HTML Web 资源。

对话框

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

备注

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

alertDialog

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

Xrm.Utility.alertDialog(message,onCloseCallback)

• 参数

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

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

confirmDialog

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

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

• 参数

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

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

本机设备功能（Dynamics 365 移动客户端）

可将这些方法用于 适用于手机的 Dynamics 365 和 适用于平板电脑的 Dynamics 365 客户端，以丰富销售、现场服务和其他领域移动业务用户的用户体验。

备注

适用于 Dynamics 365 的 2016 年 12 月更新（联机和本地） 中引入了这些方法。

getBarcodeValue

返回使用设备摄像头扫描的条形代码信息，如产品编号。

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

• 参数

  名称	类型	必填	说明
  successCallback	作用	是	返回了条形码值时要调用的函数。
  errorCallback	作用	是	当操作失败时调用的函数。 将传递具有 message 属性的错误对象，用于介绍错误的详细信息。

• 备注
  若要让 getBarcodeValue 方法工作，Dynamics 365 移动客户端必须可以访问您的设备摄像头（默认已启用）。

• 示例
  以下示例代码演示如何使用此方法。

  Xrm.Utility.getBarcodeValue().then(
      function (result) {
          Xrm.Utility.alertDialog("Barcode value: " + result);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

getCurrentPosition

使用设备地理位置功能返回当前位置。

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

• 参数

  名称	类型	必填	说明
  successCallback	作用	是	返回当前地理位置信息时要调用的函数。 将把带有以下属性的地理位置对象传递给此函数。 coords：包含一组地理坐标和关联的精确度，以及一组其他可选属性，如海拔和速度。 timestamp：表示对象的采集时间，并显示为 DOMTimeStamp。
  errorCallback	作用	是	当操作失败时调用的函数。 将传递具有以下属性的对象： code：数字。 错误代码。 message：字符串。 已本地化的消息，用于介绍错误详细信息。 如果您的移动设备上未启用用户位置设置，错误消息的指示将相同。 如果您在使用 Dynamics 365 移动客户端早期版本或您的设备无地理位置功能，将把 null 传递给错误回调。

• 备注
  若要使 getCurrentPosition 方法工作，必须在您的设备上启用地理位置功能，并且 Dynamics 365 移动客户端必须有权访问设备位置（默认未启用）。

• 示例
  以下示例代码演示如何使用此方法。

  Xrm.Utility.getCurrentPosition().then
      (function (location) {
          Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
             ", Longitude: " + location.coords.longitude);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

isActivityType

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

Xrm.Utility.isActivityType(entityName)

• 参数

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

• 返回值

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

openEntityForm

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

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

• 参数

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

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

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

  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);

• 参数

  客户	类型	必填	说明
  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 资源。

备注

此函数不支持 Dynamics 365 移动客户端（电话和平板）和交互式服务中心。

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

• 参数

  客户	类型​​	必选	说明
  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 365 窗体编写代码
使用 Xrm.Page 对象模型

Microsoft Dynamics 365

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