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 函數和 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 行動用戶端不允許使用封鎖程式碼流程的 JavaScript 函數，例如window.alert 和 window.confirm。 如果您必須對使用者顯示訊息，請使用這些方法。 主要差異是在使用者關閉它們之前，這些方法不會封鎖程式碼。 它們包含回呼函數參數，根據使用者回覆指示應該執行的程式碼。

備註

在 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 (Online 和內部部署) 的 2016 年 12 月更新 中推出。

getBarcodeValue

傳回條碼資訊，例如產品數目，使用裝置相機掃描。

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

  • 參數

    名稱

    Type

    出席者

    描述

    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)

  • 參數

    名稱

    Type

    出席者

    描述

    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。

  • 傳回值

    類型

    描述

    布林值

    若實體是活動實體則為 true，否則為 false。

openEntityForm

使用您設為參數的選項，開啟新的或現有實體記錄的實體表單。

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

  • 參數

    名稱

    類型

    需要

    描述

    名稱

    字串

    是

    實體的邏輯名稱。

    id

    字串

    否

    表單中開啟之記錄的唯一識別碼字串表示。 如果未設定，則會開啟建立新記錄的表單。

    參數

    物件

    否

    字典物件，傳遞額外的參數至表單。 無效的參數會產生錯誤。

    有效額外的查詢字串參數如下：

    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：記錄的主要屬性值。

    參數

    物件

    否

    字典物件，傳遞額外的查詢字串參數至表單。 無效的查詢字串參數會產生錯誤。

    有效額外的查詢字串參數如下：

    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 資源。

備註

此函數在 Dynamics 365 行動用戶端 (手機和平板電腦) 和互動式服務中心不支援。

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

  • 參數

    名稱

    Type

    出席者

    描述

    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 365 表單的程式碼
使用 Xrm.Page 物件模型

Microsoft Dynamics 365

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