共用方式為

表單指令碼快速參考

  • 發行項

 

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

此主題將說明您常用來執行工作的表單指令碼方法的快速參考。 如需完整參考，請參閱用戶端程式設計參考。 除非另有指定，否則此頁面上的所有範例都使用預設客戶實體主要表單。

本主題內容

屬性

  • 存取屬性

  • 取得或設定實體屬性資料

  • 取得屬性中繼資料

儲存事件引數

顯示通知

控制項

  • 存取表單控制項

  • 存取頁首控制項

  • 存取商務程序流程控制項

  • 格式控制項方法

  • OptionSet 控制項方法

  • IFRAME 和 Web 資源控制項方法

  • 查詢控制項方法

  • SubGrid 控制項方法

  • 日期控制項方法

表單導覽

索引標籤和區段

在執行階段新增或移除事件處理常式

關聯式資訊方法

取得、重新整理或儲存實體資料

屬性

屬性會將可用的資料儲存在記錄中。

存取屬性

屬性可從 Xrm.Page.data.entity.attributes 集合中取用。 若要存取屬性，您可以使用 Xrm.Page.data.entity.attributes. 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get 方法或捷徑版本 Xrm.Page.getAttribute。get 方法可接受四種類型的引數：

  • 字串： 傳回屬性名稱符合字串的屬性物件。

  • 數字： 傳回 Xrm.Page.data.entity.attributes 集合索引符合數字的屬性物件。

  • 無： 傳回所有屬性的陣列。

  • Delegate function(attribute,index): 從造成委派函式傳回 true 的 Xrm.Page.data.entity.attributes 集合傳回任何屬性的陣列。

工作​​

範例

依名稱存取屬性

var nameAttribute = Xrm.Page.getAttribute("name");

將 [客戶名稱] 欄位的屬性指派至 nameAttribute 變數

依索引存取屬性

var firstAttribute = Xrm.Page.getAttribute(0);

將 Xrm.Page.data.entity.attributes 集合中的第一個屬性指派至 firstAttribute 變數。

存取所有屬性

var allAttributes = Xrm.Page.getAttribute();

將 Xrm.Page.data.entity.attributes 集合中所有屬性的陣列指派至 allAttributes 變數。

存取符合特定準則的所有屬性

var optionsetAttributes = Xrm.Page.getAttribute(function (attribute, index) {
return attribute.getAttributeType() == "optionset";
});

將符合匿名函式 (它會在屬性類型為 "optionset" 時傳回 true) 中所設定準則的 Xrm.Page.data.entity.attributes 集合中所有屬性的陣列指派至 optionsetAttributes 變數。

Xrm.Page.data.entity.attributes 集合中也包含可用來存取函式內屬性的 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach 方法。 下列 writeRequiredAttributesToConsole 函式會將需要資料的任何屬性名稱寫入偵錯主控台：

function writeRequiredAttributesToConsole() {
 var requiredAttributeNames = [];

 Xrm.Page.data.entity.attributes.forEach(
 function (attribute, index) {
  if (attribute.getRequiredLevel() == "required")
  { requiredAttributeNames.push(attribute.getName()); }
 });

 if (requiredAttributeNames.length > 0) {
  if (typeof console != "undefined") {
   console.log(requiredAttributeNames.join());
  }
 }
 else {
  if (typeof console != "undefined") {
   console.log("No required attributes detected");
  }
 }
}

本主題內容

取得或設定實體屬性資料

下表中的範例顯示如何擷取或變更屬性中儲存的資料。

工作​​

方法

範例

取得屬性的值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getValue

var nameValue = Xrm.Page.getAttribute("name").getValue();

將 [客戶名稱] 欄位的值指派至 nameValue 變數。

設定屬性的值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setValue

Xrm.Page.getAttribute("name").setValue("new name");

將 [客戶名稱] 欄位的值設定為「新名稱」。

取得 optionset 屬性目前所選取選項的文字值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getText

var addressType = Xrm.Page.getAttribute("address1_addresstypecode").getText();

將 [地址類型] 欄位中所選取選項的文字指派至 addressType 變數。

取得 optionset 屬性中目前選取的選項物件

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSelectedOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getSelectedOption();

將 [地址類型] 欄位中選取的選項指派至 addressTypeOption 變數。

本主題內容

取得屬性中繼資料

下表中的範例顯示如何查詢屬性 (Attribute) 的屬性 (Property)，以了解屬性的類型或是變更屬性的行為。

工作​​

方法

範例

取得屬性的類型

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getAttributeType

var attributeType = Xrm.Page.getAttribute(0).getAttributeType();

將代表第一個屬性的屬性類型的字串值指派至 attributeType 變數。

取得屬性格式化的方式。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getFormat

var attributeFormat = Xrm.Page.getAttribute(0).getFormat();

將代表第一個屬性的格式的字串值指派至 attributeFormat 變數。

取得 Boolean 或 optionset 屬性的初始值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getInitialValue

var attributeInitialValue = Xrm.Page.getAttribute("address1_addresstypecode").getInitialValue();

將 [地址類型] 欄位的初始數值指派至 attributeInitialValue 變數。

判斷屬性值是否已變更

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsDirty

var isNameChanged = Xrm.Page.getAttribute("name").getIsDirty();

將指出 [客戶名稱] 欄位值是否已變更的 Boolean 值指派至 isNameChanged 變數。

決定查詢屬性是否代表 partylist 查詢。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsPartyList

var isPartyList = Xrm.Page.getAttribute("to").getIsPartyList();

指派 Boolean 值，指出 [電子郵件] 實體的 [收件者] 欄位是否代表當事人清單查詢。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

取得包含數字的屬性允許的最大值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMax

var newValue = 100000000000001;
var newValueBelowMax = (newValue < Xrm.Page.getAttribute("creditlimit").getMax())

指派 Boolean 值至 newValueBelowMax 變數，該值指出 newValue 變數的值是否超過 [信用額度] 欄位允許的最大值。

取得包含字串的屬性允許的最大長度

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMaxLength

var newAccountName = "A Store";
var nameTooLong = (newAccountName.length > Xrm.Page.getAttribute("name").getMaxLength())

將指出 newAccountName 變數的值是否超過 [客戶名稱] 欄位允許的最大長度的 Boolean 值指派至 nameTooLong 變數。

取得包含數字的屬性允許的最小值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMin

var newValue = -1;
var newValueBelowMin = (newValue < Xrm.Page.getAttribute("creditlimit").getMin())

將指出 newValue 變數值是否低於 [信用額度] 欄位允許的最小值的 Boolean 值指派至 newValueBelowMin 變數。

取得屬性的邏輯名稱

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getName

var attributeName = Xrm.Page.getAttribute(0).getName();

將頁面上第一個屬性的邏輯名稱值指派至 attributeName 變數

取得代表值的選項物件

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getOption(1);
alert(addressTypeOption.text); //displays 'Bill To'

顯示警示，其中將 [地址類型] 欄位選項的文字顯示為數值 1。

取得代表數字屬性的有效位數的數值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getPrecision

var creditLimitPrecision = Xrm.Page.getAttribute("creditlimit").getPrecision();

將 [信用額度] 欄位的有效位數值指派至 creditLimitPrecision 變數。

取得字串值，代表屬性是否需要擁有值。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getRequiredLevel

var creditLimitRequired = Xrm.Page.getAttribute("creditlimit").getRequiredLevel();

creditLimitRequired 變數值可以是 none、required 或 recommended。

變更欄位中是否需要資料才能儲存記錄。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setRequiredLevel

Xrm.Page.getAttribute("creditlimit").setRequiredLevel("required");

將 [信用額度] 欄位設為必要項。

判斷屬性中的資料是否將在記錄儲存時送出。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSubmitMode

var nameSubmitMode = Xrm.Page.getAttribute("name").getSubmitMode();

nameSubmitMode 變數值將會是 always、never 或 dirty，代表 [客戶名稱] 欄位的 submitMode。

控制屬性中的資料是否將在記錄儲存時儲存。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setSubmitMode

Xrm.Page.getAttribute("name").setSubmitMode("always");

此範例將強制一律儲存 [客戶名稱] 欄位值，即使該值未變更。

當欄位層級安全性已套用至屬性時，
請判斷使用者是否擁有對屬性執行建立、
讀取或更新作業的權限。 如需詳細資訊，請參閱
欄位安全性如何用於控制 Microsoft Dynamics 365 欄位值的存取

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getUserPrivilege

var canUpdateNameAttribute = Xrm.Page.getAttribute("name").getUserPrivilege().canUpdate;

將代表使用者更新 [客戶名稱] 欄位之權限的 Boolean 值指派至 canUpdateNameAttribute 變數。

本主題內容

儲存事件引數

強制執行商務邏輯時，通常需要防止記錄儲存，讓使用者能夠納入必要的資訊。 做法是，您必須將事件處理常式設定為在執行內容中傳遞。 執行內容包含 getEventArgs 方法，用於擷取事件的引數。 這些引數包含可用來控制是否要儲存記錄的方法，或是將通知您有關 save 事件的查詢屬性。

工作​​

範例

防止記錄儲存。

function My_PreventSaveFunction(eContext) {
 eContext.getEventArgs().preventDefault();
}

使用 eContext 參數可擷取執行內容並使用事件引數隨附的 preventDefault 方法。

判斷哪個動作啟始了儲存。

function My_GetSaveModeTextFunction(eContext) {
 var saveModeCode = eContext.getEventArgs().getSaveMode();
 var saveModeText = "Unknown";
 switch (saveModeCode) {
  case 1:
   saveModeText = "Save";
   break;
  case 2:
   saveModeText = "SaveAndClose";
   break;
  case 5:
   saveModeText = "Deactivate";
   break;
  case 6:
   saveModeText = "Reactivate";
   break;
  case 7:
   saveModeText = "Send";
   break;
  case 15:
   saveModeText = "Disqualify";
   break;
  case 16:
   saveModeText = "Qualify";
   break;
  case 47:
   saveModeText = "Assign";
   break;
  case 58:
   saveModeText = "SaveAsCompleted";
   break;
  case 59:
   saveModeText = "SaveAndNew";
   break;
  case 70:
   saveModeText = "AutoSave";
   break;
 }
 return saveModeText;
}

使用 eContext 參數可擷取執行內容，並使用事件引數隨附的 getSaveMode 方法將整數程式碼值轉換成文字。

本主題內容

顯示通知

通知提供了對使用者顯示訊息的方式。

工作​​

方法

範例

顯示鄰近控制項的訊息，指出該資料為無效。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.setNotification("'Test' is not a valid name.");
})

在表單中的每個控制項上為 [客戶名稱] 屬性設定驗證錯誤訊息。

只要顯示這個訊息，記錄就無法儲存。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

針對控制項移除已顯示的訊息。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.clearNotification();
})

清除表單中每個控制項上針對 [客戶名稱] 屬性的所有驗證錯誤訊息。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

顯示表單層級通知。

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_setFormNotification

Xrm.Page.ui.setFormNotification(
"Hello",
"INFO",
"helloMsg"
);

在表單頂端顯示帶有系統資訊圖示的訊息 "Hello"。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

移除表單層級通知

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_clearFormNotification

Xrm.Page.ui.clearFormNotification("helloMsg");

清除先前使用 "helloMsg" 設定為 uniqueid 參數的訊息。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

使用回撥函數顯示非阻塞的警示對話方塊。

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_alertDialog

var alertDisplayed = false;
Xrm.Utility.alertDialog(
"Showing Alert",
function () { alertDisplayed = true; }
)

顯示警示，並於關閉時設定 alertDisplayed 變數的值。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

搭配不同的回撥顯示非阻塞確認對話方塊，依照使用者按下的按鈕。

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_confirmDialog

var agree = false;
Xrm.Utility.confirmDialog(
"Do you agree?",
function () { agree = true;},
function () { agree = false; }
);

顯示確認訊息並依據回覆設定 agree 變數的值。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

本主題內容

控制項

控制項代表表單中的使用者介面項目。 表單中的每個屬性將至少有一個相關聯的控制項。 不是每個控制項都與屬性相關聯。IFRAME、Web 資源和子格是沒有屬性的控制項。

存取表單控制項

控制項可從 Xrm.Page.ui.controls 集合取用。 若要存取控制項，您可以使用 **Xrm.Page.ui.controls.**9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get 方法或捷徑版本 Xrm.Page.getControl。

get 方法可接受四種類型的引數：

  • 字串： 傳回邏輯名稱與字串相符的控制項。

  • 數字： 傳回 Xrm.Page.ui.controls 集合索引符合數字的控制項。

  • 無： 傳回所有控制項的陣列。

  • Delegate function(control,index): 從造成委派函式傳回 true 的 Xrm.Page.ui.controls 集合傳回任何控制項的陣列。

工作​​

範例

存取特定屬性的所有控制項

var nameControls = Xrm.Page.getAttribute("name").controls.get();

將 name 屬性中所有控制項的陣列指派至 nameControls 變數。

依名稱存取控制項

var nameControl = Xrm.Page.getControl("name");

將代表 [客戶名稱] 欄位的第一個控制項指派至 nameControl 變數。

針對屬性新增至表單中的第一個控制項將會擁有與屬性相同的名稱。 後續每個控制項名稱都會有一個索引號碼附加至名稱。 例如，name 屬性的三個控制項名稱分別為：name、name1 和 name2。

依索引存取控制項

var firstControl = Xrm.Page.getControl(0);

將 Xrm.Page.ui.controls 集合中的第一個控制項指派至 firstControl 變數。

存取所有控制項

var allControls = Xrm.Page.getControl();

將 Xrm.Page.ui.controls 集合中所有控制項的陣列指派至 allControls 變數。

存取符合特定準則的所有控制項

var optionsetControls = Xrm.Page.getControl(function (control, index) {
return control.getControlType() == "optionset";
});

將符合匿名函式 (它會在控制項類型為 "optionset" 時傳回 true) 中所設定準則的 Xrm.Page.ui.controls 集合中所有屬性的陣列指派至 optionsetControls 變數。

每個區段也會有控制項集合，其中僅包含該區段的控制項。 下列程式碼範例會將 generalTabAccountInfoSectionControls 變數指派至 [一般] 索引標籤的 [地址] 區段中找到的控制項陣列。
var generalTabAccountInfoSectionControls = Xrm.Page.ui.tabs.get("general").sections.get("address").controls.get();

注意

每個屬性只會在表單中出現一次，但是可以針對該屬性多次新增該欄位至表單中。 新增的每個欄位都會建立另一個控制項。 在您撰寫指令碼之後，可以進一步自訂表單。 您針對屬性控制項撰寫的指令碼應該假設它已多次加入表單中。 您要對屬性的控制項採取的任何動作，通常會套用至該屬性的所有控制項。 例如，如果您要停用控制項，但是只要停用其中一個，使用者仍然可以使用另一個輸入資料。 基於這個理由，建議您使用採用下列模式，使用集合 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach 方法將相同的邏輯套用至屬性的所有控制項，即使您撰寫指令碼時只有一個控制項。

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

本主題內容

存取頁首控制項

頁首中的控制項遵循在控制項名稱前面加上「header_」的命名慣例。 例如，如果 name 屬性在頁首中，可以使用以下進行存取：
var nameControlInHeader = Xrm.Page.getControl("header_name");

存取商務程序流程控制項

商務程序流程控制項中的控制項遵循在控制項名稱前面加上「header_process_」的命名慣例。 例如，如果 name 屬性在頁首中，可以使用以下進行存取：
var nameControlInBPF = Xrm.Page.getControl("header_process_name");

注意

使用中階段中的控制項，表單載入時才位於 Xrm.Page.ui.controls 集合。 其他商務程序流程控制項是在目前實體的階段選取時新增。

格式控制項方法

在您存取控制項之後，可以呼叫下列方法。

工作​​

方法

範例

判斷控制項是否顯示

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getVisible

var isNameVisible = Xrm.Page.getControl("name").getVisible();

將 Boolean 值指派至 isNameVisible 變數，指出 [客戶名稱] 欄位是否顯示。

隱藏或顯示控制項

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setVisible

Xrm.Page.getControl("name").setVisible(false);

隱藏 [客戶名稱] 欄位。

取得控制項屬性的參考

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getAttribute

var nameAttribute = Xrm.Page.getControl("name").getAttribute();

將 [客戶名稱] 欄位的控制項屬性指派至 nameAttribute 變數。

注意

並非所有控制項都有屬性。

判斷控制項的類型

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getControlType

var optionSetControls = Xrm.Page.getControl(function (control, index) { return control.getControlType() == "optionset"; });

將 optionset 控制項的陣列指派至 optionSetControls 變數。

判斷控制項是否已啟用

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDisabled

var disabledControls = Xrm.Page.getControl(function(control, index) { return control.getDisabled(); });

將停用的控制項陣列指派至 disabledControls 變數。

注意

Web 資源與子格控制項不支援此方法。

停用或啟用控制項

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDisabled

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

停用 name 屬性的每個控制項。

提示

請記住，任何屬性都可能有多個控制項。

取得控制項的標籤

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getLabel

var nameControlLabel = Xrm.Page.getControl("name").getLabel();

將 [客戶名稱] 欄位的控制項值指派至 nameControlLabel 變數。

變更控制項的標籤

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setLabel

Xrm.Page.getControl("name").setLabel("Company Name");

將 [客戶名稱] 欄位的標籤變更為 [公司名稱]。

取得控制項的名稱

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getName

var firstControlName = Xrm.Page.getControl(0).getName();

將 Xrm.Page.ui.controls 集合中第一個控制項的名稱指派至 firstControlName 變數。

取得控制項的上層

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getParent

var parentSection = Xrm.Page.getControl("name").getParent();

將 [客戶名稱] 欄位之控制項的上層區段指派至 parentSection 變數。

將焦點設定在控制項上

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setFocus

Xrm.Page.getControl("name").setFocus();

將焦點設定在 [客戶名稱] 欄位上。

本主題內容

OptionSet 控制項方法

Optionset 有一些特殊方法。 請務必記住，屬性會定義 optionset 的有效選項。 當您使用 optionset 控制項時，您可以操作可用選項，但是無法建立新選項。

工作​​

方法

範例

新增選項至 optionset 控制項。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addOption

var addressTypeCodeControl = Xrm.Page.getControl("address1_addresstypecode");
var billToAddressOption = addressTypeCodeControl.getAttribute().getOption(1);
addressTypeCodeControl.clearOptions();
addressTypeCodeControl.addOption(billToAddressOption);

使用 [地址類型] 欄位的控制項參考存取控制項的屬性，並使用 6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption 方法將 billToAddressOption 變數設為代表 [帳單地址] 選項的選項。

使用 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions 移除所有現有的選項，並使用 addOption 將 billToAddressOption 設定為此控制項唯一可用的選項。

從 optionset 控制項移除所有選項

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions

Xrm.Page.getControl("address1_addresstypecode").clearOptions();

從 [地址類型] 欄位的控制項移除所有選項。

從 optionset 控制項移除單一選項。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_removeOption

Xrm.Page.getControl("address1_addresstypecode").removeOption(1);

從 [地址類型] 欄位的控制項移除 [帳單地址] 選項。

本主題內容

IFRAME 和 Web 資源控制項方法

IFRAME 控制項可藉由提供 URL 的方式讓您在表單內包含頁面。 新增至表單的 HTML Web 資源是使用 IFRAME 元素呈現。Silverlight 和影像 Web 資源直接內嵌於頁面中。

工作​​

方法

範例

取得傳遞至 Silverlight Web 資源的資料查詢字串參數的值。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getData

var dataValue = Xrm.Page.getControl("WebResource_SilverLightControl").getData();

將透過資料查詢字串參數傳遞的值指派至 dataValue 變數。

針對目前在 IFRAME 中顯示的內容取得 URL。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getSrc

var iframeSource = Xrm.Page.getControl("IFRAME_targetPage").getSrc();

將代表目前 IFRAME.src 屬性值的字串指派至 iframeSource 變數。

設定要在 IFRAME 中顯示的內容的 URL。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setSrc

Xrm.Page.getControl("IFRAME_targetPage").setSrc("http://www.bing.com");

將 URL 設定為控制項的 IFRAME.src。

取得 URL，其代表針對 IFRAME 預設設定的 URL。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getUrl

var initialUrl = Xrm.Page.getControl("IFRAME_bing").getInitialUrl();

將設定要在 IFRAME 中顯示的初始 URL 指派至 initialUrl 變數。

取得表單中代表 Web 資源或 IFRAME 的物件。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getObject

var obj = Xrm.Page.getControl("IFRAME_bing").getObject();

將物件參考指派至 obj 變數。 對於 IFRAME，這會是 IFRAME 文件物件模型 (DOM) 元素。 對於 Silverlight Web 資源，它會是物件 Object 元素，代表內嵌的 Silverlight 外掛程式。

本主題內容

查詢控制項方法

對於查詢控制項的一般需求，是指定使用者更新欄位時顯示的預設檢視表。

工作​​

方法

範例

新增查詢的自訂檢視表。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
var viewDisplayName = "SDK Sample View";
var fetchXml = "<fetch version='1.0' " +
"output-format='xml-platform' " +
"mapping='logical'>" +
"<entity name='account'>" +
"<attribute name='name' />" +
"<attribute name='address1_city' />" +
"<order attribute='name' " +
"descending='false' />" +
"<filter type='and'>" +
"<condition attribute='ownerid' " +
"operator='eq-userid' />" +
"<condition attribute='statecode' " +
"operator='eq' " +
"value='0' />" +
"</filter>" +
"<attribute name='primarycontactid' />" +
"<attribute name='telephone1' />" +
"<attribute name='accountid' />" +
"<link-entity "+
"alias='accountprimarycontactidcontactcontactid' " +
"name='contact' " +
"from='contactid' " +
"to='primarycontactid' " +
"link-type='outer' " +
"visible='false'>" +
"<attribute name='emailaddress1' />" +
"</link-entity>" +
"</entity>" +
"</fetch>";
var layoutXml = "<grid name='resultset' " +
"object='1' " +
"jump='name' " +
"select='1' " +
"icon='1' " +
"preview='1'>" +
"<row name='result' " +
"id='accountid'>" +
"<cell name='name' " +
"width='300' />" +
"<cell name='telephone1' " +
"width='100' />" +
"<cell name='address1_city' " +
"width='100' />" +
"<cell name='primarycontactid' " +
"width='150' />" +
"<cell name='accountprimarycontactidcontactcontactid.emailaddress1' " +
"width='150' " +
"disableSorting='1' />" +
"</row>" +
"</grid>";
Xrm.Page.getControl("parentaccountid").addCustomView(viewId, "account", viewDisplayName, fetchXml, layoutXml, true);

設定 viewId、viewDisplayName、fetchXml 和 layoutXml 變數做為引數傳遞，以便將自訂檢視表做為預設檢視表新增至 [上層客戶] 查詢欄位的控制項。

取得查詢的預設檢視表。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDefaultView

var defaultViewId = Xrm.Page.getControl("parentaccountid").getDefaultView();

將預設檢視表的 id 值指派至 defaultViewId 變數。

設定查詢的預設檢視表。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDefaultView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
Xrm.Page.getControl("parentaccountid").setDefaultView(viewId);

將 [客戶名稱] 欄位之控制項的預設檢視表設定為 viewId 中的 id 值。

篩選為查詢控制項傳回的記錄

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomFilter

以下是商機表單客戶 (parentaccountid) 查詢的程式碼範例。 在 Onload 事件處理常式中設定 Sdk.setParentAccountIdFilter 函數時，Sdk.filterCustomAccounts 函數會新增至該查詢的 PreSearch 事件。 結果是，只會傳回含有 [偏好的客戶] (1) 之 [類別] (accountcategorycode) 值的客戶。

var Sdk = window.Sdk || {};

Sdk.filterCustomerAccounts = function () {
    //Only show accounts with the type 'Preferred Customer'
    var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
    Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
}
//set 'Sdk.setParentAccountIdFilter' in the Opportunity form Onload event handler
Sdk.setParentAccountIdFilter = function () {
    Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
}

本主題內容

SubGrid 控制項方法

SubGrid 控制項是表單內的資料格。 它具有一個唯一的方法。

工作​​

方法

範例

重新整理子格中顯示的資料

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_refresh

Xrm.Page.getControl("accountcontactsgrid").refresh();

重新整理 [連絡人subgrid]。

本主題內容

日期控制項方法

Date 控制項具有一個唯一的方法。

工作​​

方法

範例

指定日期控制項是否要顯示日期的時間部分。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setShowTime

Xrm.Page.getControl("createdon").setShowTime(false);

設定 [建立時間] 欄位，不要顯示時間。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

本主題內容

表單導覽

您可以使用並操作表單左側的導覽項目。 這些導覽項目通常會顯示與表單中所顯示的記錄相關的記錄。

您可以使用 Xrm.Page.ui.navigation.items 集合存取導覽項目。就像表單中的所有集合一樣，會有 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get 和 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach 方法。

工作​​

方法

範例

取得導覽項目的名稱

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getId

var navItemIds = [];
Xrm.Page.ui.navigation.items.forEach(
function (item, index)
{ navItemIds.push(item.getId()) }
);

建立 navItemIds 陣列，其中包含 Xrm.Page.ui.navigation.items 集合中每個導覽項目的 id 值。

取得導覽項目的標籤。

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getLabel

var navAddressesLabel = Xrm.Page.ui.navigation.items.get("navAddresses").getLabel();

將 [其他地址] 導覽項目的標籤指派至 navAddressesLabel 變數。

設定導覽項目的標籤

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setLabel

Xrm.Page.ui.navigation.items.get("navAddresses").setLabel("Other Addresses");

將 [其他地址] 導覽項目標籤變更為 [其他地址]。

顯示或隱藏導覽項目

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setVisible

Xrm.Page.ui.navigation.items.get("navAddresses").setVisible(false);

隱藏 More Addresses 導覽項目。

判斷導覽項目是否顯示

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getVisible

var moreAddressesVisible = Xrm.Page.ui.navigation.items.get("navAddresses").getVisible()

將 Boolean 值指派至 moreAddressesVisible 變數，表示 [其他地址] 導覽項目是否顯示。

將焦點設定在導覽項目上。

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setFocus

Xrm.Page.ui.navigation.items.get("navAddresses").setFocus();

將焦點設定在 [其他地址] 導覽項目上。

本主題內容

索引標籤和區段

每個表單都有索引標籤集合。 每個索引標籤都有區段集合。 每個區段都有控制項集合。 您可以用程式設計的方式存取這些元素並使用其方法。

工作​​

方法

範例

判斷索引標籤為展開或摺疊狀態

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_getDisplayState

var isGeneralTabExpanded = (Xrm.Page.ui.tabs.get("general").getDisplayState() == "expanded")

將 Boolean 值指派至 isGeneralTabExpanded 變數，指出 [一般] 索引標籤是否為展開狀態。

展開或摺疊索引標籤

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetDisplayState

Xrm.Page.ui.tabs.get("general").setDisplayState("collapsed");

摺疊 [一般] 索引標籤。

判斷索引標籤是否顯示

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetVisible

var isGeneralTabVisible = Xrm.Page.ui.tabs.get("general").getVisible();

將 Boolean 值指派至 isGeneralTabVisible 變數，指出 [一般] 索引標籤是否顯示。

顯示或隱藏索引標籤

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetVisible

Xrm.Page.ui.tabs.get("general").setVisible(false);

隱藏 [一般] 索引標籤。

取得索引標籤的標籤

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetLabel

var generalTabLabel = Xrm.Page.ui.tabs.get("general").getLabel();

將 [一般] 索引標籤的標籤指派至 generalTabLabel 變數。

變更索引標籤的標籤

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetLabel

Xrm.Page.ui.tabs.get("general").setLabel("Major");

將 [一般] 索引標籤的標籤變更為 [主要]。

將焦點設定在索引標籤上

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetFocus

Xrm.Page.ui.tabs.get("general").setFocus();

將焦點設定在 [一般] 索引標籤上。

取得索引標籤的名稱

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetName

var firstTabName = Xrm.Page.ui.tabs.get(0).getName();

指派第一個索引標籤的名稱至 firstTabName 變數。

取得區段的上層索引標籤

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetParent

Xrm.Page.getControl("industrycode").getParent().getParent().setFocus();

將焦點設定在包含 [產業] 欄位的索引標籤上。

判斷區段是否顯示

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetVisible

var industrySectionVisible = Xrm.Page.getControl("industrycode").getParent().getVisible();

將 Boolean 值指派至 industrySectionVisible 變數，指出包含 [產業] 欄位的區段是否顯示。

顯示或隱藏區段

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetVisible

Xrm.Page.getControl("industrycode").getParent().setVisible(false);

隱藏包含 [產業] 欄位的區段。

取得區段的標籤

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_getLabel

var industryFieldSectionLabel = Xrm.Page.getControl("industrycode").getParent().getLabel();

將包含 [產業] 欄位之區段的標籤指派至 industryFieldSectionLabel 變數。

變更區段的標籤

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetLabel

Xrm.Page.getControl("industrycode").getParent().setLabel("Detailed Information");

將包含 [產業] 欄位之區段的標籤變更為 [詳細資訊]。

本主題內容

在執行階段新增或移除事件處理常式

事件處理常式通常是使用應用程式中的表單編輯器設定，但是您也可以在執行階段使用這些 APIs 將它們新增至表單 OnSave 事件和屬性 OnChange 事件。 本節中的範例將參考下列函式定義：
function myFunction() {
//perform action here
}

雖然您可以新增匿名函式，但是函式必須具有可參考的名稱才能將它移除。

工作​​

方法

範例

新增函式至 OnSave 事件

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_addOnSave

Xrm.Page.data.entity.addOnSave(myFunction);

新增 myFunction 函式至 OnSave 事件。

從 OnSave 事件移除函式

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_removeOnSave

Xrm.Page.data.entity.removeOnSave(myFunction);

從 OnSave 事件移除 myFunction 函式。

新增函式至屬性的 OnChange 事件。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_addOnChange

Xrm.Page.getAttribute("name").addOnChange(myFunction);

新增 myFunction 函式至 [客戶名稱] 欄位的 OnChange 事件。

從屬性的 OnChange 事件移除函式

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_removeOnChange

Xrm.Page.getAttribute("name").removeOnChange(myFunction);

從 [客戶名稱] 欄位的 OnChange 事件移除 myFunction 函式。

新增函數至查詢控制項的 PreSearch 事件

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addPreSearch

以下是商機表單客戶 (parentaccountid) 查詢的程式碼範例。 在 Onload 事件處理常式中設定 Sdk.setParentAccountIdFilter 函數時，Sdk.filterCustomAccounts 函數會新增至該查詢的 PreSearch 事件。 結果是，只會傳回含有 [偏好的客戶] (1) 之 [類別] (accountcategorycode) 值的客戶。

var Sdk = window.Sdk || {};

Sdk.filterCustomerAccounts = function () {
    //Only show accounts with the type 'Preferred Customer'
    var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
    Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
}
//set 'Sdk.setParentAccountIdFilter' in the Opportunity form Onload event handler
Sdk.setParentAccountIdFilter = function () {
    Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
}

針對在商務程序流程控制項發生的事件，使用 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange 和 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected。 這些事件只有以程式設計方式新增或移除事件處理常式的方法。其他資訊：管理事件處理常式的方法。

本主題內容

關聯式資訊方法

使用這些方法可取得關於使用者、組織和用戶端的資訊。 下表提供一些最實用的內容方法。 如需所有內容方法，請參閱用戶端內容 (用戶端參考)

工作​​

方法

範例

取得要連線至組織的 URL。

getClientUrl

var serverUrl = Xrm.Page.context.getClientUrl();

將代表 URL 的字串指派至 serverUrl 變數。

取得目前使用者的唯一識別碼。

getUserId

var userId = Xrm.Page.context.getUserId();

將代表使用者識別碼的字串指派至 userId 變數。

取得目前使用者的名稱。

getUserName

var userName = Xrm.Page.context.getUserName();

將代表使用者名稱的字串指派至 userName 變數。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

取得代表使用者慣用的使用者介面語言的語言碼。

getUserLcid

var userLCID = Xrm.Page.context.getUserLcid();

將表示使用者慣用語言的數字指派至 userLCID 變數。

取得字串陣列，其代表指派給目前使用者的每個資訊安全角色的 GUID 值，以及與使用者相關聯的任何團隊。

getUserRoles

var userRoles = Xrm.Page.context.getUserRoles();

將代表使用者的資訊安全角色的字串陣列指派至 userRoles 變數。

判斷指令碼是否在 Microsoft Dynamics 365 for Outlook 用戶端中執行。

client.getClient

var isOutlookClient = (Xrm.Page.context.client.getClient() == "Outlook");

將代表程式碼是否在 Dynamics 365 for Outlook 用戶端中執行的 Boolean 值指派至 isOutlookClient 變數。

判斷使用者是否使用 Microsoft Dynamics 365 for Microsoft Office Outlook with Offline Access 用戶端離線工作。

client.getClientState

var IsOffline = (Xrm.Page.context.client.getClientState() == "Offline");

將代表使用者目前是否離線工作的 Boolean 值指派至 IsOffline 變數。

本主題內容

取得、重新整理或儲存實體資料

下表包含您可以用來取得目前記錄相關資訊或儲存變更的方法。 如需詳細資訊，請參閱 Xrm.Page.data.entity (用戶端參考)和 Xrm.Page.data (用戶端參考)。

工作​​

方法

範例

取得目前實體的邏輯名稱

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getEntityName

var entityName = Xrm.Page.data.entity.getEntityName();

將邏輯實體名稱指派至 entityName 變數。

取得目前實體的主要屬性值。
主要屬性是用來識別記錄的值。 例如 contact.fullname。

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getPrimaryAttributeValue

var primaryAttributeValue = Xrm.Page.data.entity.getPrimaryAttributeValue();

將主要屬性的值指派至 primaryAttributeValue 變數。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

取得目前記錄的 Id

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getId

var recordId = Xrm.Page.data.entity.getId();

將記錄的 id 指派至 recordId 變數。

非同步重新整理表單的資料，而不必重新載入頁面。

ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_refresh

Xrm.Page.data.refresh();

重新整理表單中的資料。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

儲存目前的記錄

Xrm.Page.data.entity.fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_save

Xrm.Page.data.entity.save();

儲存記錄。 有一些選擇性的引數。 使用 saveandclose 或 saveandnew 執行同等的動作。

在儲存作業完成後，以非同步形式儲存目前的記錄，搭配設定要執行的
回撥函數的選項。

Xrm.Page.data.ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_dataSave

Xrm.Page.data.save().then(
function(){
Xrm.Utility.alertDialog("Record saved");
},
function(error){
Xrm.Utility.alertDialog(error.message);
});

儲存記錄並顯示訊息，指出儲存的狀態。

此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

判斷目前記錄中是否有任何資料變更。

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getIsDirty

var isDirty = Xrm.Page.data.entity.getIsDirty();

將代表記錄中的資料是否已變更的 Boolean 值指派至 isDirty 變數。

取得字串，其代表儲存記錄時要傳送至伺服器的資料。

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getDataXml

var dataXml = Xrm.Page.data.entity.getDataXml();

將代表要儲存的資料的字串指派至 dataXml 變數。

本主題內容

另請參閱

使用 Xrm.Page 物件模型
撰寫 Microsoft Dynamics 365 表單的程式碼
用戶端程式設計參考

Microsoft Dynamics 365

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