Xrm.Utility (用戶端參考)

 

發佈日期： 2016年11月

適用對象： Dynamics CRM 2015

Xrm.Utility 物件為不會直接與目前頁面關聯的有用函數提供容器。

這些函數在支援指令碼的每個應用程式頁面中可用。 您可以在表單指令碼或在功能區命令中使用它們。 若為 HTML Web 資源，包括 ClientGlobalContext.js.aspx 頁面時，可以使用它們。 如需詳細資訊，請參閱GetGlobalContext 函數和 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)

• 參數

  名稱	類型	需要	描述
  訊息	字串	是	要在對話方塊中顯示的訊息文字。
  onCloseCallback	函數	否	當按一下 [確定] 按鈕時執行的函數。

• 備註
  此方法僅適用於更新的實體。

confirmDialog

顯示確認對話方塊，包含選擇性訊息以及 [確定] 和 [取消] 按鈕。

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

• 參數

  名稱	類型	需要	描述
  訊息	字串	是	要在對話方塊中顯示的訊息文字
  yesCloseCallback	函數	否	當按一下 [確定] 按鈕時執行的函數。
  noCloseCallback	函數	否	當按一下 [取消] 按鈕時執行的函數。

• 備註
  此方法僅適用於更新的實體。

isActivityType

決定實體是否活動實體。

Xrm.Utility.isActivityType(entityName)

• 參數

  名稱	類型	需要	描述
  entityName	字串	是	實體的 logicalName。

• 傳回值

  類型	描述
  布林值	若實體是活動實體則為 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。 此參數在 平板電腦適用的 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);

• 參數

  名稱	類型	需要	描述
  entityLogicalName	字串	是	要建立之實體的邏輯名稱。
  createFromEntity	查詢	否	指定將根據對應的屬性值提供預設值的記錄。 查詢物件具有下列 String 屬性： entityType：實體的邏輯名稱。 id：記錄的 GUID 值的字串表示。 name：記錄的主要屬性值。
  參數	物件	否	字典物件，傳遞額外的查詢字串參數至表單。 無效的查詢字串參數會產生錯誤。 有效額外的查詢字串參數如下： 預設欄位 ID：設定新記錄表單的預設值。 如需詳細資訊，請參閱使用傳遞至表單的參數設定欄位值。 自訂查詢字串參數：可設定表單接受自訂查詢字串參數。 如需詳細資訊，請參閱設定表單以接受自訂查詢字串參數。
  successCallback	函數	否	建立記錄時將呼叫的函數。 此函數會收到傳遞的物件做為參數。 此物件有 savedEntityReference 屬性，其下列屬性可以識別建立的記錄： entityType：實體的邏輯名稱。 id：記錄的 GUID 值的字串表示。 name：所建立記錄的主要屬性值。
  errorCallback	函數	否	作業失敗時呼叫的函數。 具有下列屬性的物件將會傳遞： errorCode: Number. 錯誤碼。 message: 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)

• 參數

  名稱	類型	需要	描述
  webResourceName	字串	是	要開啟的 HTML Web 資源的名稱。
  webResourceData	字串	否	要傳入資料參數的資料。
  width	編號	否	開啟視窗的寬度 (像素)。
  height	編號	否	開啟視窗的高度 (像素)。

• 傳回值
  視窗物件。

• 備註
  HTML Web 資源可以接受在 將參數傳遞至 HTML 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 資源的資料參數值擷取。 如需詳細資訊，請參閱範例：透過資料參數傳遞多個值到一個 Web 資源中

  開啟 HTML Web 資源，具有 HTML Web 資源預期的參數

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

  如需詳細資訊，請參閱將參數傳遞至 HTML Web 資源。

  開啟 HTML Web 資源，設定高度與寬度

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

另請參閱

用戶端程式設計參考
使用 URL 開啟表單、檢視表、對話方塊和報表
使用傳遞至表單的參數設定欄位值
設定表單以接受自訂查詢字串參數
表單指令碼快速參考
撰寫 Microsoft Dynamics CRM 2015 表單的程式碼
使用 Xrm.Page 物件模型

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權